@proveanything/smartlinks 1.4.0 → 1.4.2

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.4.0  |  Generated: 2026-02-20T14:52:16.722Z
+Version: 1.4.2  |  Generated: 2026-02-20T21:56:06.588Z
 
 This is a concise summary of all available API functions and types.
 
@@ -18,6 +18,7 @@ For detailed guides on specific features:
 - **[Theme Defaults](theme-defaults.md)** - Default theme values and presets
 - **[Proof Claiming Methods](proof-claiming-methods.md)** - All methods for claiming/registering product ownership (NFC tags, serial numbers, auto-generated claims)
 - **[App Data Storage](app-data-storage.md)** - User-specific and collection-scoped app data storage
+- **[AI Guide Template](ai-guide-template.md)** - A sample for an app on how to build an AI setup guide
 
 ## API Namespaces
 
@@ -820,6 +821,41 @@ interface AppConfigurationResponse {
 
 ### appManifest
 
+**AppBundle** (interface)
+```typescript
+interface AppBundle {
+  js: string | null;
+  css: string | null;
+  source?: string;
+  styles?: string;
+}
+```
+
+**AppWidgetDefinition** (interface)
+```typescript
+interface AppWidgetDefinition {
+  name: string;
+  description?: string;
+  sizes?: Array<'compact' | 'standard' | 'large' | string>;
+  props?: {
+  required?: string[];
+  optional?: string[];
+  };
+}
+```
+
+**AppContainerDefinition** (interface)
+```typescript
+interface AppContainerDefinition {
+  name: string;
+  description?: string;
+  props?: {
+  required?: string[];
+  optional?: string[];
+  };
+}
+```
+
 **AppManifest** (interface)
 ```typescript
 interface AppManifest {
@@ -831,15 +867,8 @@ interface AppManifest {
   platformRevision?: string;
   appId: string;
   };
-  widgets?: Array<{
-  name: string;
-  description?: string;
-  sizes?: string[];
-  props?: {
-  required?: string[];
-  optional?: string[];
-  };
-  }>;
+  widgets?: AppWidgetDefinition[];
+  containers?: AppContainerDefinition[];
   setup?: {
   description?: string;
   questions?: Array<{
@@ -848,12 +877,14 @@ interface AppManifest {
   type: string;
   default?: any;
   required?: boolean;
+  options?: Array<{ value: string; label: string }>;
   }>;
   configSchema?: Record<string, any>;
   saveWith?: {
   method: string;
-  scope: string;
+  scope: 'collection' | 'product' | string;
   admin?: boolean;
+  note?: string;
   };
   contentHints?: Record<string, {
   aiGenerate?: boolean;
@@ -884,44 +915,38 @@ interface AppManifest {
   name: string;
   description?: string;
   type: string;
+  options?: string[];
   }>;
   };
   metrics?: {
-  interactions?: Array<{
-  id: string;
-  description?: string;
-  }>;
-  kpis?: Array<{
-  name: string;
-  compute?: string;
-  }>;
+  interactions?: Array<{ id: string; description?: string }>;
+  kpis?: Array<{ name: string; compute?: string }>;
   };
-  [key: string]: any; // Allow additional custom fields
+  [key: string]: any;
 }
 ```
 
-**CollectionWidget** (interface)
+**CollectionAppWidget** (interface)
 ```typescript
-interface CollectionWidget {
+interface CollectionAppWidget {
   appId: string;
-  manifestUrl: string;
   manifest: AppManifest;
-  bundleSource: string;
-  bundleCss?: string; // Optional CSS file
+  widget: AppBundle;
+  container: AppBundle | null;
 }
 ```
 
 **CollectionWidgetsResponse** (interface)
 ```typescript
 interface CollectionWidgetsResponse {
-  apps: CollectionWidget[];
+  apps: CollectionAppWidget[];
 }
 ```
 
 **GetCollectionWidgetsOptions** (interface)
 ```typescript
 interface GetCollectionWidgetsOptions {
-  force?: boolean; // Bypass cache and fetch fresh data
+  force?: boolean;
 }
 ```
 

package/dist/docs/ai-guide-template.md

@@ -0,0 +1,241 @@
+# AI Guide: Example App
+
+<!-- CUSTOMIZE: Replace "Example App" and all content below with your app's specifics. -->
+<!-- This file is consumed by AI orchestrators alongside public/app.manifest.json. -->
+<!-- The manifest provides structured data; this file provides prose context and nuance. -->
+
+---
+
+## Purpose & Identity
+
+<!-- CUSTOMIZE: Describe what your app does in 2-3 sentences. -->
+
+The **Example App** is a template SmartLinks microapp that demonstrates all platform patterns including setup wizards, data imports, widget embedding, and analytics. It serves as a reference implementation for app authors building on the SmartLinks platform.
+
+---
+
+## Setup Wizard Instructions
+
+An AI orchestrator should follow these steps to configure the Example App for a collection. The structured questions and schema are in `app.manifest.json` under `setup`.
+
+### Prerequisites
+
+- The user must have **admin access** to the target collection.
+- The `collectionId` and `appId` must be known (typically from URL context).
+
+### Questions to Ask
+
+Walk the user through each question defined in `setup.questions[]` of the manifest:
+
+1. **App Title** (`appTitle`): Ask what the app should be called. Offer to auto-generate a suggestion using `SL.ai.chat.completions` if the user wants help (see `contentHints` in the manifest).
+2. **Enable Notifications** (`enableNotifications`): Ask whether the app should send notifications to users.
+
+<!-- CUSTOMIZE: Add app-specific guidance for each question. For example: -->
+<!-- "If the user is setting up a competition, suggest a title like 'Win a [Product Name]!'" -->
+<!-- "For plant passports, notifications are typically disabled." -->
+
+### How to Save the Config
+
+After collecting answers, validate against `setup.configSchema` and save:
+
+```typescript
+await SL.appConfiguration.setConfig({
+  collectionId,
+  appId,
+  config: {
+    appTitle: "User's chosen title",
+    enableNotifications: false
+  },
+  admin: true  // REQUIRED for admin operations
+});
+```
+
+### Post-Setup Verification
+
+After saving, confirm by reading the config back:
+
+```typescript
+const saved = await SL.appConfiguration.getConfig({
+  collectionId,
+  appId,
+  admin: true
+});
+// Verify saved.appTitle and saved.enableNotifications match expectations
+```
+
+Tell the user: "Your app is configured! You can adjust settings anytime by asking me to update the configuration."
+
+---
+
+## Import Instructions
+
+The app supports bulk import of product-level configuration. The field definitions are in `app.manifest.json` under `import`.
+
+### CSV Template
+
+Generate or share this template with the user:
+
+```csv
+productId,appTitle,enableNotifications
+prod_001,My First Product,true
+prod_002,My Second Product,false
+```
+
+<!-- CUSTOMIZE: Add real-world examples relevant to your app. -->
+
+### Field Validation Rules
+
+| Field                 | Type    | Required | Validation                            |
+| --------------------- | ------- | -------- | ------------------------------------- |
+| `productId`           | string  | ✅       | Must be a valid SmartLinks product ID |
+| `appTitle`            | string  | ✅       | Non-empty string                      |
+| `enableNotifications` | boolean | ❌       | Defaults to `false`                   |
+
+<!-- CUSTOMIZE: Add app-specific validation rules. For example: -->
+<!-- "For plant passports: botanicalName must be in Latin binomial format." -->
+
+### API Call Sequence
+
+For each row in the CSV:
+
+```typescript
+await SL.appConfiguration.setConfig({
+  collectionId,
+  productId: row.productId,  // From CSV
+  appId,
+  config: {
+    appTitle: row.appTitle,
+    enableNotifications: row.enableNotifications ?? false
+  },
+  admin: true
+});
+```
+
+### Error Handling
+
+- If a `productId` is invalid, log the error and continue with the next row.
+- After processing all rows, report a summary: `"Imported X of Y products successfully. Z failed."`.
+- For failed rows, list the product ID and error message so the user can fix the data.
+
+### Cross-App Import
+
+When importing data for multiple apps simultaneously:
+
+1. Fetch `app.manifest.json` from each app.
+2. Merge `import.fields` arrays (prefix field names with app name if there are conflicts).
+3. Generate a combined CSV template.
+4. For each row, split into separate payloads per app and call each app's `saveWith.method`.
+
+---
+
+## Widget Embedding Guide
+
+### Available Widgets
+
+| Widget          | Description                                | Sizes                    |
+| --------------- | ------------------------------------------ | ------------------------ |
+| `ExampleWidget` | Demo widget showing SmartLinks integration | compact, standard, large |
+
+<!-- CUSTOMIZE: List all widgets your app exports. -->
+
+### Props Reference
+
+All widgets receive `SmartLinksWidgetProps`:
+
+| Prop              | Type           | Required | Description                             |
+| ----------------- | -------------- | -------- | --------------------------------------- |
+| `collectionId`    | string         | ✅       | Collection context                      |
+| `appId`           | string         | ✅       | App identifier                          |
+| `SL`              | SmartLinks SDK | ✅       | Pre-initialized SDK instance            |
+| `productId`       | string         | ❌       | Product context                         |
+| `proofId`         | string         | ❌       | Proof context                           |
+| `user`            | object         | ❌       | Current user info                       |
+| `onNavigate`      | function       | ❌       | Navigation callback                     |
+| `publicPortalUrl` | string         | ❌       | URL to full app for deep linking        |
+| `size`            | string         | ❌       | `"compact"`, `"standard"`, or `"large"` |
+| `lang`            | string         | ❌       | Language code (e.g., `"en"`)            |
+| `translations`    | object         | ❌       | Translation overrides                   |
+
+### Example Code
+
+```tsx
+import { ExampleWidget } from '@my-app/widgets';
+
+<ExampleWidget
+  collectionId="col_123"
+  appId="example-app"
+  SL={SL}
+  size="standard"
+  onNavigate={(path) => router.push(path)}
+/>
+```
+
+<!-- CUSTOMIZE: Show real widget usage with app-specific props. -->
+
+---
+
+## Tunable Settings
+
+These settings can be adjusted after initial setup without reconfiguring everything. The AI can modify them in response to user requests like "turn off notifications" or optimization suggestions.
+
+| Setting               | Type    | Description                    |
+| --------------------- | ------- | ------------------------------ |
+| `enableNotifications` | boolean | Toggle notifications on or off |
+
+<!-- CUSTOMIZE: List all tunable fields with guidance on when to change them. -->
+
+To update a tunable setting:
+
+```typescript
+// 1. Read current config
+const current = await SL.appConfiguration.getConfig({ collectionId, appId, admin: true });
+
+// 2. Merge the change
+await SL.appConfiguration.setConfig({
+  collectionId,
+  appId,
+  config: { ...current, enableNotifications: true },
+  admin: true
+});
+```
+
+---
+
+## Metrics & Analytics
+
+### Tracked Interactions
+
+| Interaction ID | Description                                   |
+| -------------- | --------------------------------------------- |
+| `page-view`    | Tracks each time a user views the public page |
+
+<!-- CUSTOMIZE: List all interaction IDs your app tracks. -->
+
+### KPIs
+
+| KPI         | How to Compute                                                                         |
+| ----------- | -------------------------------------------------------------------------------------- |
+| Total Views | `SL.interactions.countsByOutcome(collectionId, { appId, interactionId: 'page-view' })` |
+
+<!-- CUSTOMIZE: Add app-specific KPIs and interpretation guidance. -->
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+| Issue                 | Cause                      | Fix                                                   |
+| --------------------- | -------------------------- | ----------------------------------------------------- |
+| Config save fails     | Missing `admin: true` flag | Always include `admin: true` for admin operations     |
+| Widget doesn't render | Missing required props     | Ensure `collectionId`, `appId`, and `SL` are provided |
+| Import skips rows     | Invalid `productId`        | Verify product IDs exist in the collection            |
+| Theme not applied     | Missing `?theme=` param    | Check URL parameters or postMessage setup             |
+
+<!-- CUSTOMIZE: Add app-specific troubleshooting entries. -->
+
+### Getting Help
+
+- **SDK Docs**: `node_modules/@proveanything/smartlinks/docs/`
+- **App Manifest**: `public/app.manifest.json`
+- **Platform Guide**: `src/docs/smartlinks/about.md`

package/dist/types/appManifest.d.ts

@@ -1,6 +1,54 @@
 /**
- * SmartLinks App Manifest structure
- * Defines the configuration, widgets, setup, import, and metrics for a microapp
+ * A bundle (widget or container) as returned by the collection widgets endpoint.
+ *
+ * The server currently returns URLs only. In future it may also inline the file
+ * contents when bundles are small or frequently accessed. Clients should check
+ * for inline content first and fall back to loading the URL.
+ *
+ *   if (bundle.source) {
+ *     // inline JS — create a Blob URL or inject directly
+ *   } else if (bundle.js) {
+ *     // load from URL
+ *   }
+ */
+export interface AppBundle {
+    /** URL to the JavaScript file — load if `source` is absent */
+    js: string | null;
+    /** URL to the CSS file — load if `styles` is absent */
+    css: string | null;
+    /** Inlined JavaScript source (present when server bundles it inline) */
+    source?: string;
+    /** Inlined CSS styles (present when server bundles it inline) */
+    styles?: string;
+}
+/**
+ * A single widget defined in the manifest.
+ * Presence of the `widgets` array means a widget bundle exists for this app.
+ */
+export interface AppWidgetDefinition {
+    name: string;
+    description?: string;
+    sizes?: Array<'compact' | 'standard' | 'large' | string>;
+    props?: {
+        required?: string[];
+        optional?: string[];
+    };
+}
+/**
+ * A single container defined in the manifest.
+ * Presence of the `containers` array means a container bundle exists for this app.
+ * Containers are full-page / embedded components (larger than widgets, no iframe needed).
+ */
+export interface AppContainerDefinition {
+    name: string;
+    description?: string;
+    props?: {
+        required?: string[];
+        optional?: string[];
+    };
+}
+/**
+ * SmartLinks App Manifest — the app.manifest.json structure.
  */
 export interface AppManifest {
     $schema?: string;
@@ -11,15 +59,10 @@ export interface AppManifest {
         platformRevision?: string;
         appId: string;
     };
-    widgets?: Array<{
-        name: string;
-        description?: string;
-        sizes?: string[];
-        props?: {
-            required?: string[];
-            optional?: string[];
-        };
-    }>;
+    /** Presence means a widget bundle (widgets.umd.js / widgets.css) exists */
+    widgets?: AppWidgetDefinition[];
+    /** Presence means a container bundle (containers.umd.js / containers.css) exists */
+    containers?: AppContainerDefinition[];
     setup?: {
         description?: string;
         questions?: Array<{
@@ -28,12 +71,17 @@ export interface AppManifest {
             type: string;
             default?: any;
             required?: boolean;
+            options?: Array<{
+                value: string;
+                label: string;
+            }>;
         }>;
         configSchema?: Record<string, any>;
         saveWith?: {
             method: string;
-            scope: string;
+            scope: 'collection' | 'product' | string;
             admin?: boolean;
+            note?: string;
         };
         contentHints?: Record<string, {
             aiGenerate?: boolean;
@@ -64,6 +112,7 @@ export interface AppManifest {
             name: string;
             description?: string;
             type: string;
+            options?: string[];
         }>;
     };
     metrics?: {
@@ -79,24 +128,26 @@ export interface AppManifest {
     [key: string]: any;
 }
 /**
- * Single app widget data with manifest and bundle files
+ * One app entry in the collection widgets response.
  */
-export interface CollectionWidget {
+export interface CollectionAppWidget {
     appId: string;
-    manifestUrl: string;
     manifest: AppManifest;
-    bundleSource: string;
-    bundleCss?: string;
+    /** Widget bundle — always present (apps without widgets are excluded from the response) */
+    widget: AppBundle;
+    /** Container bundle — null when the app has no containers */
+    container: AppBundle | null;
 }
 /**
- * Response from collection widgets endpoint
+ * Response from GET /api/v1/public/collection/:collectionId/widgets
  */
 export interface CollectionWidgetsResponse {
-    apps: CollectionWidget[];
+    apps: CollectionAppWidget[];
 }
 /**
  * Options for fetching collection widgets
  */
 export interface GetCollectionWidgetsOptions {
+    /** Bypass server cache and fetch fresh manifests */
     force?: boolean;
 }

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.4.0  |  Generated: 2026-02-20T14:52:16.722Z
+Version: 1.4.2  |  Generated: 2026-02-20T21:56:06.588Z
 
 This is a concise summary of all available API functions and types.
 
@@ -18,6 +18,7 @@ For detailed guides on specific features:
 - **[Theme Defaults](theme-defaults.md)** - Default theme values and presets
 - **[Proof Claiming Methods](proof-claiming-methods.md)** - All methods for claiming/registering product ownership (NFC tags, serial numbers, auto-generated claims)
 - **[App Data Storage](app-data-storage.md)** - User-specific and collection-scoped app data storage
+- **[AI Guide Template](ai-guide-template.md)** - A sample for an app on how to build an AI setup guide
 
 ## API Namespaces
 
@@ -820,6 +821,41 @@ interface AppConfigurationResponse {
 
 ### appManifest
 
+**AppBundle** (interface)
+```typescript
+interface AppBundle {
+  js: string | null;
+  css: string | null;
+  source?: string;
+  styles?: string;
+}
+```
+
+**AppWidgetDefinition** (interface)
+```typescript
+interface AppWidgetDefinition {
+  name: string;
+  description?: string;
+  sizes?: Array<'compact' | 'standard' | 'large' | string>;
+  props?: {
+  required?: string[];
+  optional?: string[];
+  };
+}
+```
+
+**AppContainerDefinition** (interface)
+```typescript
+interface AppContainerDefinition {
+  name: string;
+  description?: string;
+  props?: {
+  required?: string[];
+  optional?: string[];
+  };
+}
+```
+
 **AppManifest** (interface)
 ```typescript
 interface AppManifest {
@@ -831,15 +867,8 @@ interface AppManifest {
   platformRevision?: string;
   appId: string;
   };
-  widgets?: Array<{
-  name: string;
-  description?: string;
-  sizes?: string[];
-  props?: {
-  required?: string[];
-  optional?: string[];
-  };
-  }>;
+  widgets?: AppWidgetDefinition[];
+  containers?: AppContainerDefinition[];
   setup?: {
   description?: string;
   questions?: Array<{
@@ -848,12 +877,14 @@ interface AppManifest {
   type: string;
   default?: any;
   required?: boolean;
+  options?: Array<{ value: string; label: string }>;
   }>;
   configSchema?: Record<string, any>;
   saveWith?: {
   method: string;
-  scope: string;
+  scope: 'collection' | 'product' | string;
   admin?: boolean;
+  note?: string;
   };
   contentHints?: Record<string, {
   aiGenerate?: boolean;
@@ -884,44 +915,38 @@ interface AppManifest {
   name: string;
   description?: string;
   type: string;
+  options?: string[];
   }>;
   };
   metrics?: {
-  interactions?: Array<{
-  id: string;
-  description?: string;
-  }>;
-  kpis?: Array<{
-  name: string;
-  compute?: string;
-  }>;
+  interactions?: Array<{ id: string; description?: string }>;
+  kpis?: Array<{ name: string; compute?: string }>;
   };
-  [key: string]: any; // Allow additional custom fields
+  [key: string]: any;
 }
 ```
 
-**CollectionWidget** (interface)
+**CollectionAppWidget** (interface)
 ```typescript
-interface CollectionWidget {
+interface CollectionAppWidget {
   appId: string;
-  manifestUrl: string;
   manifest: AppManifest;
-  bundleSource: string;
-  bundleCss?: string; // Optional CSS file
+  widget: AppBundle;
+  container: AppBundle | null;
 }
 ```
 
 **CollectionWidgetsResponse** (interface)
 ```typescript
 interface CollectionWidgetsResponse {
-  apps: CollectionWidget[];
+  apps: CollectionAppWidget[];
 }
 ```
 
 **GetCollectionWidgetsOptions** (interface)
 ```typescript
 interface GetCollectionWidgetsOptions {
-  force?: boolean; // Bypass cache and fetch fresh data
+  force?: boolean;
 }
 ```
 

package/docs/ai-guide-template.md

@@ -0,0 +1,241 @@
+# AI Guide: Example App
+
+<!-- CUSTOMIZE: Replace "Example App" and all content below with your app's specifics. -->
+<!-- This file is consumed by AI orchestrators alongside public/app.manifest.json. -->
+<!-- The manifest provides structured data; this file provides prose context and nuance. -->
+
+---
+
+## Purpose & Identity
+
+<!-- CUSTOMIZE: Describe what your app does in 2-3 sentences. -->
+
+The **Example App** is a template SmartLinks microapp that demonstrates all platform patterns including setup wizards, data imports, widget embedding, and analytics. It serves as a reference implementation for app authors building on the SmartLinks platform.
+
+---
+
+## Setup Wizard Instructions
+
+An AI orchestrator should follow these steps to configure the Example App for a collection. The structured questions and schema are in `app.manifest.json` under `setup`.
+
+### Prerequisites
+
+- The user must have **admin access** to the target collection.
+- The `collectionId` and `appId` must be known (typically from URL context).
+
+### Questions to Ask
+
+Walk the user through each question defined in `setup.questions[]` of the manifest:
+
+1. **App Title** (`appTitle`): Ask what the app should be called. Offer to auto-generate a suggestion using `SL.ai.chat.completions` if the user wants help (see `contentHints` in the manifest).
+2. **Enable Notifications** (`enableNotifications`): Ask whether the app should send notifications to users.
+
+<!-- CUSTOMIZE: Add app-specific guidance for each question. For example: -->
+<!-- "If the user is setting up a competition, suggest a title like 'Win a [Product Name]!'" -->
+<!-- "For plant passports, notifications are typically disabled." -->
+
+### How to Save the Config
+
+After collecting answers, validate against `setup.configSchema` and save:
+
+```typescript
+await SL.appConfiguration.setConfig({
+  collectionId,
+  appId,
+  config: {
+    appTitle: "User's chosen title",
+    enableNotifications: false
+  },
+  admin: true  // REQUIRED for admin operations
+});
+```
+
+### Post-Setup Verification
+
+After saving, confirm by reading the config back:
+
+```typescript
+const saved = await SL.appConfiguration.getConfig({
+  collectionId,
+  appId,
+  admin: true
+});
+// Verify saved.appTitle and saved.enableNotifications match expectations
+```
+
+Tell the user: "Your app is configured! You can adjust settings anytime by asking me to update the configuration."
+
+---
+
+## Import Instructions
+
+The app supports bulk import of product-level configuration. The field definitions are in `app.manifest.json` under `import`.
+
+### CSV Template
+
+Generate or share this template with the user:
+
+```csv
+productId,appTitle,enableNotifications
+prod_001,My First Product,true
+prod_002,My Second Product,false
+```
+
+<!-- CUSTOMIZE: Add real-world examples relevant to your app. -->
+
+### Field Validation Rules
+
+| Field                 | Type    | Required | Validation                            |
+| --------------------- | ------- | -------- | ------------------------------------- |
+| `productId`           | string  | ✅       | Must be a valid SmartLinks product ID |
+| `appTitle`            | string  | ✅       | Non-empty string                      |
+| `enableNotifications` | boolean | ❌       | Defaults to `false`                   |
+
+<!-- CUSTOMIZE: Add app-specific validation rules. For example: -->
+<!-- "For plant passports: botanicalName must be in Latin binomial format." -->
+
+### API Call Sequence
+
+For each row in the CSV:
+
+```typescript
+await SL.appConfiguration.setConfig({
+  collectionId,
+  productId: row.productId,  // From CSV
+  appId,
+  config: {
+    appTitle: row.appTitle,
+    enableNotifications: row.enableNotifications ?? false
+  },
+  admin: true
+});
+```
+
+### Error Handling
+
+- If a `productId` is invalid, log the error and continue with the next row.
+- After processing all rows, report a summary: `"Imported X of Y products successfully. Z failed."`.
+- For failed rows, list the product ID and error message so the user can fix the data.
+
+### Cross-App Import
+
+When importing data for multiple apps simultaneously:
+
+1. Fetch `app.manifest.json` from each app.
+2. Merge `import.fields` arrays (prefix field names with app name if there are conflicts).
+3. Generate a combined CSV template.
+4. For each row, split into separate payloads per app and call each app's `saveWith.method`.
+
+---
+
+## Widget Embedding Guide
+
+### Available Widgets
+
+| Widget          | Description                                | Sizes                    |
+| --------------- | ------------------------------------------ | ------------------------ |
+| `ExampleWidget` | Demo widget showing SmartLinks integration | compact, standard, large |
+
+<!-- CUSTOMIZE: List all widgets your app exports. -->
+
+### Props Reference
+
+All widgets receive `SmartLinksWidgetProps`:
+
+| Prop              | Type           | Required | Description                             |
+| ----------------- | -------------- | -------- | --------------------------------------- |
+| `collectionId`    | string         | ✅       | Collection context                      |
+| `appId`           | string         | ✅       | App identifier                          |
+| `SL`              | SmartLinks SDK | ✅       | Pre-initialized SDK instance            |
+| `productId`       | string         | ❌       | Product context                         |
+| `proofId`         | string         | ❌       | Proof context                           |
+| `user`            | object         | ❌       | Current user info                       |
+| `onNavigate`      | function       | ❌       | Navigation callback                     |
+| `publicPortalUrl` | string         | ❌       | URL to full app for deep linking        |
+| `size`            | string         | ❌       | `"compact"`, `"standard"`, or `"large"` |
+| `lang`            | string         | ❌       | Language code (e.g., `"en"`)            |
+| `translations`    | object         | ❌       | Translation overrides                   |
+
+### Example Code
+
+```tsx
+import { ExampleWidget } from '@my-app/widgets';
+
+<ExampleWidget
+  collectionId="col_123"
+  appId="example-app"
+  SL={SL}
+  size="standard"
+  onNavigate={(path) => router.push(path)}
+/>
+```
+
+<!-- CUSTOMIZE: Show real widget usage with app-specific props. -->
+
+---
+
+## Tunable Settings
+
+These settings can be adjusted after initial setup without reconfiguring everything. The AI can modify them in response to user requests like "turn off notifications" or optimization suggestions.
+
+| Setting               | Type    | Description                    |
+| --------------------- | ------- | ------------------------------ |
+| `enableNotifications` | boolean | Toggle notifications on or off |
+
+<!-- CUSTOMIZE: List all tunable fields with guidance on when to change them. -->
+
+To update a tunable setting:
+
+```typescript
+// 1. Read current config
+const current = await SL.appConfiguration.getConfig({ collectionId, appId, admin: true });
+
+// 2. Merge the change
+await SL.appConfiguration.setConfig({
+  collectionId,
+  appId,
+  config: { ...current, enableNotifications: true },
+  admin: true
+});
+```
+
+---
+
+## Metrics & Analytics
+
+### Tracked Interactions
+
+| Interaction ID | Description                                   |
+| -------------- | --------------------------------------------- |
+| `page-view`    | Tracks each time a user views the public page |
+
+<!-- CUSTOMIZE: List all interaction IDs your app tracks. -->
+
+### KPIs
+
+| KPI         | How to Compute                                                                         |
+| ----------- | -------------------------------------------------------------------------------------- |
+| Total Views | `SL.interactions.countsByOutcome(collectionId, { appId, interactionId: 'page-view' })` |
+
+<!-- CUSTOMIZE: Add app-specific KPIs and interpretation guidance. -->
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+| Issue                 | Cause                      | Fix                                                   |
+| --------------------- | -------------------------- | ----------------------------------------------------- |
+| Config save fails     | Missing `admin: true` flag | Always include `admin: true` for admin operations     |
+| Widget doesn't render | Missing required props     | Ensure `collectionId`, `appId`, and `SL` are provided |
+| Import skips rows     | Invalid `productId`        | Verify product IDs exist in the collection            |
+| Theme not applied     | Missing `?theme=` param    | Check URL parameters or postMessage setup             |
+
+<!-- CUSTOMIZE: Add app-specific troubleshooting entries. -->
+
+### Getting Help
+
+- **SDK Docs**: `node_modules/@proveanything/smartlinks/docs/`
+- **App Manifest**: `public/app.manifest.json`
+- **Platform Guide**: `src/docs/smartlinks/about.md`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",