@syntrologie/runtime-sdk 2.11.0 → 2.13.0

package/CAPABILITIES.md

@@ -54,8 +54,8 @@ Change a page header when the element is visible:
   },
   "actions": [
     {
-      "kind": "set_text",
-      "anchorId": "h1.hero-title",
+      "kind": "content:setText",
+      "anchorId": { "selector": "h1.hero-title", "route": "/" },
       "text": "Welcome to Our New Experience"
     }
   ]
@@ -160,62 +160,73 @@ The widget reads auth credentials from the browser:
 
 DOM content modification capabilities for text, attributes, styles, HTML, and classes.
 
+## When to use
+
+| Goal | Action |
+|------|--------|
+| Replace an element's text | `content:setText` |
+| Change an HTML attribute (href, src, data-*) | `content:setAttr` |
+| Modify inline styles (color, size, spacing) | `content:setStyle` |
+| Inject new HTML before/after/inside an element | `content:insertHtml` |
+| Add a CSS class (show/hide, animate) | `content:addClass` |
+| Remove a CSS class | `content:removeClass` |
+
 ## Actions
 
-### set_text
+### content:setText
 
 Replaces the text content of an element.
 
-| Property   | Type         | Required | Description      |
-| ---------- | ------------ | -------- | ---------------- |
-| `kind`     | `"set_text"` | Yes      | Action type      |
-| `anchorId` | string       | Yes      | Element selector |
-| `text`     | string       | Yes      | New text content |
+| Property   | Type                | Required | Description      |
+| ---------- | ------------------- | -------- | ---------------- |
+| `kind`     | `"content:setText"` | Yes      | Action type      |
+| `anchorId` | object              | Yes      | `{ selector, route }` |
+| `text`     | string              | Yes      | New text content |
 
 ```json
 {
-  "kind": "set_text",
-  "anchorId": "h1.hero-title",
+  "kind": "content:setText",
+  "anchorId": { "selector": "h1.hero-title", "route": "/" },
   "text": "Start Your Free Trial Today"
 }
 ```
 
-### set_attr
+### content:setAttr
 
 Sets an HTML attribute on an element.
 
-| Property   | Type         | Required | Description      |
-| ---------- | ------------ | -------- | ---------------- |
-| `kind`     | `"set_attr"` | Yes      | Action type      |
-| `anchorId` | string       | Yes      | Element selector |
-| `attr`     | string       | Yes      | Attribute name   |
-| `value`    | string       | Yes      | Attribute value  |
+| Property   | Type                | Required | Description      |
+| ---------- | ------------------- | -------- | ---------------- |
+| `kind`     | `"content:setAttr"` | Yes      | Action type      |
+| `anchorId` | object              | Yes      | `{ selector, route }` |
+| `attr`     | string              | Yes      | Attribute name   |
+| `value`    | string              | Yes      | Attribute value  |
 
 **Blocked attributes:** Event handlers (`onclick`, `onerror`, etc.) are not allowed.
 
 ```json
 {
-  "kind": "set_attr",
-  "anchorId": "#signup-form",
+  "kind": "content:setAttr",
+  "anchorId": { "selector": "#signup-form", "route": "/" },
   "attr": "data-experiment",
   "value": "signup-v2"
 }
 ```
 
-### set_style
+### content:setStyle
 
 Sets inline CSS styles on an element.
 
-| Property   | Type          | Required | Description              |
-| ---------- | ------------- | -------- | ------------------------ |
-| `kind`     | `"set_style"` | Yes      | Action type              |
-| `anchorId` | string        | Yes      | Element selector         |
-| `styles`   | object        | Yes      | CSS property/value pairs |
+| Property   | Type                 | Required | Description              |
+| ---------- | -------------------- | -------- | ------------------------ |
+| `kind`     | `"content:setStyle"` | Yes      | Action type              |
+| `anchorId` | object               | Yes      | `{ selector, route }` |
+| `styles`   | object               | Yes      | CSS property/value pairs |
 
 ```json
 {
-  "kind": "set_style",
-  "anchorId": ".hero-section",
+  "kind": "content:setStyle",
+  "anchorId": { "selector": ".hero-section", "route": "/" },
   "styles": {
     "background-color": "#1e40af",
     "padding": "2rem"
@@ -223,17 +234,17 @@ Sets inline CSS styles on an element.
 }
 ```
 
-### insert_html
+### content:insertHtml
 
 Inserts HTML content relative to an element.
 
-| Property   | Type            | Required | Description                                                 |
-| ---------- | --------------- | -------- | ----------------------------------------------------------- |
-| `kind`     | `"insert_html"` | Yes      | Action type                                                 |
-| `anchorId` | string          | Yes      | Element selector                                            |
-| `html`     | string          | Yes      | HTML content (sanitized)                                    |
-| `position` | string          | Yes      | `"before"`, `"after"`, `"prepend"`, `"append"`, `"replace"` |
-| `deepLink` | object          | No       | Makes the entire inserted element clickable to open the canvas panel and navigate to a specific tile |
+| Property   | Type                  | Required | Description                                                 |
+| ---------- | --------------------- | -------- | ----------------------------------------------------------- |
+| `kind`     | `"content:insertHtml"` | Yes      | Action type                                                 |
+| `anchorId` | object                | Yes      | `{ selector, route }` |
+| `html`     | string                | Yes      | HTML content (sanitized)                                    |
+| `position` | string                | Yes      | `"before"`, `"after"`, `"prepend"`, `"append"`, `"replace"` |
+| `deepLink` | object                | No       | Makes the entire inserted element clickable to open the canvas panel and navigate to a specific tile |
 
 **Positions:**
 
@@ -245,8 +256,8 @@ Inserts HTML content relative to an element.
 
 ```json
 {
-  "kind": "insert_html",
-  "anchorId": ".cta-button",
+  "kind": "content:insertHtml",
+  "anchorId": { "selector": ".cta-button", "route": "/" },
   "html": "<span class=\"badge\">NEW</span>",
   "position": "append"
 }
@@ -263,8 +274,8 @@ Use `deepLink` to make inserted content open the canvas panel and navigate to a
 
 ```json
 {
-  "kind": "insert_html",
-  "anchorId": "[data-id='pricing-heading']",
+  "kind": "content:insertHtml",
+  "anchorId": { "selector": "[data-id='pricing-heading']", "route": "/" },
   "html": "<button style='background: #4a90e2; color: white; border: none; padding: 8px 16px; border-radius: 20px; cursor: pointer;'>Help Me Choose</button>",
   "position": "after",
   "deepLink": { "tileId": "plan_selector_faq" }
@@ -273,38 +284,38 @@ Use `deepLink` to make inserted content open the canvas panel and navigate to a
 
 The SDK automatically handles opening the canvas, setting the cursor to pointer, and publishing a `notification.deep_link` event. The click handler is wired up and cleaned up by the SDK — no JavaScript in the HTML is needed.
 
-### add_class
+### content:addClass
 
 Adds a CSS class to an element.
 
-| Property    | Type          | Required | Description       |
-| ----------- | ------------- | -------- | ----------------- |
-| `kind`      | `"add_class"` | Yes      | Action type       |
-| `anchorId`  | string        | Yes      | Element selector  |
-| `className` | string        | Yes      | Class name to add |
+| Property    | Type                 | Required | Description       |
+| ----------- | -------------------- | -------- | ----------------- |
+| `kind`      | `"content:addClass"` | Yes      | Action type       |
+| `anchorId`  | object               | Yes      | `{ selector, route }` |
+| `className` | string               | Yes      | Class name to add |
 
 ```json
 {
-  "kind": "add_class",
-  "anchorId": ".pricing-card",
+  "kind": "content:addClass",
+  "anchorId": { "selector": ".pricing-card", "route": "/pricing" },
   "className": "highlighted"
 }
 ```
 
-### remove_class
+### content:removeClass
 
 Removes a CSS class from an element.
 
-| Property    | Type             | Required | Description          |
-| ----------- | ---------------- | -------- | -------------------- |
-| `kind`      | `"remove_class"` | Yes      | Action type          |
-| `anchorId`  | string           | Yes      | Element selector     |
-| `className` | string           | Yes      | Class name to remove |
+| Property    | Type                    | Required | Description          |
+| ----------- | ----------------------- | -------- | -------------------- |
+| `kind`      | `"content:removeClass"` | Yes      | Action type          |
+| `anchorId`  | object                  | Yes      | `{ selector, route }` |
+| `className` | string                  | Yes      | Class name to remove |
 
 ```json
 {
-  "kind": "remove_class",
-  "anchorId": ".pricing-card",
+  "kind": "content:removeClass",
+  "anchorId": { "selector": ".pricing-card", "route": "/pricing" },
   "className": "hidden"
 }
 ```
@@ -316,24 +327,50 @@ Removes a CSS class from an element.
 
 Collapsible Q&A accordion with actions, rich content, feedback, and personalization.
 
-## Actions
+## When to use
+
+| Goal | Action |
+|------|--------|
+| Add an FAQ accordion widget | Add a **tile** in `tiles[]` with `widget: "adaptive-faq:accordion"` |
+| Scroll to and expand a specific FAQ item | `faq:scroll_to` |
+| Open, close, or toggle a FAQ item | `faq:toggle_item` |
+| Add, remove, reorder, or replace FAQ items | `faq:update` |
 
-### mount_faq
+## Mounting an FAQ Widget
 
-Mounts an FAQ accordion widget to a surface slot.
+FAQ widgets are mounted via **tiles** (not actions). Add an entry to the `tiles[]` array in the config:
+
+```json
+{
+  "tiles": [
+    {
+      "id": "my-faq",
+      "title": "Frequently Asked Questions",
+      "content": {
+        "type": "custom",
+        "component": "adaptive-faq:accordion",
+        "props": {
+          "expandBehavior": "single",
+          "searchable": true,
+          "items": [ ... ]
+        }
+      }
+    }
+  ]
+}
+```
+
+### Tile Props
 
 | Property                | Type                              | Required | Description                                                         |
 | ----------------------- | --------------------------------- | -------- | ------------------------------------------------------------------- |
-| `kind`                  | `"mount_faq"`                     | Yes      | Action type                                                         |
-| `slot`                  | string                            | Yes      | Target slot (e.g., `"drawer_right"`, `"overlay_center"`)            |
-| `config.title`          | string                            | No       | Widget title                                                        |
-| `config.expandBehavior` | `"single"` \| `"multiple"`        | No       | Whether one or many items can be open at once (default: `"single"`) |
-| `config.searchable`     | boolean                           | No       | Show a search/filter input (default: `false`)                       |
-| `config.theme`          | `"light"` \| `"dark"` \| `"auto"` | No       | Color theme (default: `"auto"`)                                     |
-| `config.items`          | array                             | Yes      | FAQ items (see below)                                               |
-| `config.feedback`       | boolean \| FeedbackConfig         | No       | Enable per-item feedback widget                                     |
-| `config.ordering`       | OrderingStrategy                  | No       | Item ordering strategy (default: `"static"`)                        |
-| `config.injections`     | InjectionRule[]                   | No       | Dynamic item injection rules                                        |
+| `expandBehavior`        | `"single"` \| `"multiple"`        | No       | Whether one or many items can be open at once (default: `"single"`) |
+| `searchable`            | boolean                           | No       | Show a search/filter input (default: `false`)                       |
+| `theme`                 | `"light"` \| `"dark"` \| `"auto"` | No       | Color theme (default: `"auto"`)                                     |
+| `items`                 | array                             | Yes      | FAQ items (see below)                                               |
+| `feedback`              | boolean \| FeedbackConfig         | No       | Enable per-item feedback widget                                     |
+| `ordering`              | OrderingStrategy                  | No       | Item ordering strategy (default: `"static"`)                        |
+| `injections`            | InjectionRule[]                   | No       | Dynamic item injection rules                                        |
 
 ### FAQ Item Schema
 
@@ -348,65 +385,63 @@ Each item in the `items` array:
 | `config.category`       | string                   | No       | Category for grouping items                     |
 | `config.priority`       | number                   | No       | Priority weight for ordering                    |
 | `config.answerStrategy` | AnswerStrategy           | No       | AI-generated answer configuration               |
-| `showWhen`              | DecisionStrategy \| null | No       | Conditional visibility strategy                 |
+| `triggerWhen`              | DecisionStrategy \| null | No       | Conditional visibility strategy                 |
+
+**Full tile example with FAQ items:**
 
 ```json
 {
-  "kind": "mount_faq",
-  "slot": "drawer_right",
-  "config": {
-    "title": "Frequently Asked Questions",
-    "expandBehavior": "single",
-    "searchable": true,
-    "theme": "auto",
-    "feedback": {
-      "style": "thumbs",
-      "prompt": "Was this helpful?"
-    },
-    "ordering": "priority",
-    "items": [
-      {
-        "kind": "faq:question",
-        "config": {
-          "id": "getting-started",
-          "question": "How do I get started?",
-          "answer": "Sign up for a free account and follow our quickstart guide.",
-          "category": "General",
-          "priority": 10
-        }
-      },
-      {
-        "kind": "faq:question",
-        "config": {
-          "id": "payment-methods",
-          "question": "What payment methods do you accept?",
-          "answer": "We accept all major credit cards and PayPal.",
-          "category": "Billing",
-          "priority": 5
-        },
-        "showWhen": {
-          "type": "rules",
-          "rules": [
+  "tiles": [
+    {
+      "id": "help-faq",
+      "title": "Frequently Asked Questions",
+      "content": {
+        "type": "custom",
+        "component": "adaptive-faq:accordion",
+        "props": {
+          "expandBehavior": "single",
+          "searchable": true,
+          "feedback": {
+            "style": "thumbs",
+            "prompt": "Was this helpful?"
+          },
+          "ordering": "priority",
+          "items": [
             {
-              "conditions": [{ "type": "page_url", "pattern": "/pricing*" }],
-              "value": true
+              "kind": "faq:question",
+              "config": {
+                "id": "getting-started",
+                "question": "How do I get started?",
+                "answer": "Sign up for a free account and follow our quickstart guide.",
+                "category": "General",
+                "priority": 10
+              }
+            },
+            {
+              "kind": "faq:question",
+              "config": {
+                "id": "payment-methods",
+                "question": "What payment methods do you accept?",
+                "answer": "We accept all major credit cards and PayPal.",
+                "category": "Billing",
+                "priority": 5
+              }
             }
-          ],
-          "default": false
+          ]
         }
       }
-    ]
-  }
+    }
+  ]
 }
 ```
 
-### scroll_to_faq
+### faq:scroll_to
 
 Scrolls the viewport to a specific FAQ item and optionally expands it.
 
 | Property       | Type              | Required | Default    | Description                                |
 | -------------- | ----------------- | -------- | ---------- | ------------------------------------------ |
-| `kind`         | `"scroll_to_faq"` | Yes      |            | Action type                                |
+| `kind`         | `"faq:scroll_to"` | Yes      |            | Action type                                |
 | `itemId`       | string            | No\*     |            | Target item ID                             |
 | `itemQuestion` | string            | No\*     |            | Target item question text (fuzzy match)    |
 | `expand`       | boolean           | No       | `true`     | Whether to expand the item after scrolling |
@@ -416,20 +451,20 @@ Scrolls the viewport to a specific FAQ item and optionally expands it.
 
 ```json
 {
-  "kind": "scroll_to_faq",
+  "kind": "faq:scroll_to",
   "itemId": "payment-methods",
   "expand": true,
   "behavior": "smooth"
 }
 ```
 
-### toggle_faq_item
+### faq:toggle_item
 
 Opens, closes, or toggles a FAQ item's expanded state.
 
 | Property       | Type                | Required | Default    | Description                             |
 | -------------- | ------------------- | -------- | ---------- | --------------------------------------- |
-| `kind`         | `"toggle_faq_item"` | Yes      |            | Action type                             |
+| `kind`         | `"faq:toggle_item"` | Yes      |            | Action type                             |
 | `itemId`       | string              | No\*     |            | Target item ID                          |
 | `itemQuestion` | string              | No\*     |            | Target item question text (fuzzy match) |
 | `state`        | string              | No       | `"toggle"` | `"open"`, `"closed"`, `"toggle"`        |
@@ -438,19 +473,19 @@ Opens, closes, or toggles a FAQ item's expanded state.
 
 ```json
 {
-  "kind": "toggle_faq_item",
+  "kind": "faq:toggle_item",
   "itemId": "getting-started",
   "state": "open"
 }
 ```
 
-### update_faq
+### faq:update
 
 Dynamically adds, removes, reorders, or replaces FAQ items at runtime.
 
 | Property    | Type                | Required | Description                                             |
 | ----------- | ------------------- | -------- | ------------------------------------------------------- |
-| `kind`      | `"update_faq"`      | Yes      | Action type                                             |
+| `kind`      | `"faq:update"`      | Yes      | Action type                                             |
 | `operation` | string              | Yes      | `"add"`, `"remove"`, `"reorder"`, `"replace"`           |
 | `items`     | FAQQuestionAction[] | No       | Items to add or replace with (required for add/replace) |
 | `itemId`    | string              | No       | Item to remove (required for remove)                    |
@@ -462,7 +497,7 @@ Dynamically adds, removes, reorders, or replaces FAQ items at runtime.
 
 ```json
 {
-  "kind": "update_faq",
+  "kind": "faq:update",
   "operation": "add",
   "position": "append",
   "items": [
@@ -482,7 +517,7 @@ Dynamically adds, removes, reorders, or replaces FAQ items at runtime.
 
 ```json
 {
-  "kind": "update_faq",
+  "kind": "faq:update",
   "operation": "remove",
   "itemId": "outdated-question"
 }
@@ -492,7 +527,7 @@ Dynamically adds, removes, reorders, or replaces FAQ items at runtime.
 
 ```json
 {
-  "kind": "update_faq",
+  "kind": "faq:update",
   "operation": "reorder",
   "order": ["getting-started", "new-feature", "payment-methods"]
 }
@@ -502,7 +537,7 @@ Dynamically adds, removes, reorders, or replaces FAQ items at runtime.
 
 ```json
 {
-  "kind": "update_faq",
+  "kind": "faq:update",
   "operation": "replace",
   "items": [
     {
@@ -521,12 +556,12 @@ Dynamically adds, removes, reorders, or replaces FAQ items at runtime.
 
 The FAQ widget uses a **compositional action pattern** where `faq:question` actions serve as configuration data rendered by the widget, rather than being executed by the runtime. This allows:
 
-- **Per-item conditional visibility** via `showWhen` strategies -- items can appear or hide based on page URL, user segment, viewport, or any DecisionStrategy condition
+- **Per-item conditional visibility** via `triggerWhen` strategies -- items can appear or hide based on page URL, user segment, viewport, or any DecisionStrategy condition
 - **Category grouping** -- items with a `category` field are grouped under collapsible section headers
 - **Dynamic injection** -- `injections` rules can add items when trigger conditions are met, supporting contextual FAQ content
 - **Ordering control** -- the `ordering` strategy determines how items are sorted within categories
 
-Items without `showWhen` are always visible. Items without `category` appear in an ungrouped section.
+Items without `triggerWhen` are always visible. Items without `category` appear in an ungrouped section.
 
 ## Rich Answer Content
 
@@ -672,17 +707,67 @@ Injection rules add contextual FAQ items when conditions are met:
 
 Gamification capabilities including badges, points, and leaderboards.
 
+## When to use
+
+| Goal | Action |
+|------|--------|
+| Award a badge to a user | `gamification:awardBadge` |
+| Add points to a user's score | `gamification:addPoints` |
+| Mount a gamification widget (leaderboard, progress) | Add a **tile** with `component: "adaptive-gamification:leaderboard"` |
+
 ## Actions
 
-### mount_gamification
+### gamification:awardBadge
+
+Awards a badge to the current user.
+
+| Property | Type                       | Required | Description      |
+| -------- | -------------------------- | -------- | ---------------- |
+| `kind`   | `"gamification:awardBadge"` | Yes      | Action type      |
+| `badgeId` | string                    | Yes      | Badge identifier |
+
+```json
+{
+  "kind": "gamification:awardBadge",
+  "badgeId": "first-purchase"
+}
+```
+
+### gamification:addPoints
+
+Adds points to the current user's score.
 
-Mounts gamification UI elements.
+| Property | Type                       | Required | Description      |
+| -------- | -------------------------- | -------- | ---------------- |
+| `kind`   | `"gamification:addPoints"` | Yes      | Action type      |
+| `points` | number                     | Yes      | Points to add    |
 
-| Property | Type                   | Required | Description                |
-| -------- | ---------------------- | -------- | -------------------------- |
-| `kind`   | `"mount_gamification"` | Yes      | Action type                |
-| `slot`   | string                 | Yes      | Target slot                |
-| `config` | object                 | Yes      | Gamification configuration |
+```json
+{
+  "kind": "gamification:addPoints",
+  "points": 50
+}
+```
+
+### Gamification Widget (via Tile)
+
+Mount gamification UI elements (leaderboard, badge display, progress tracker) via a **tile**:
+
+```json
+{
+  "tiles": [
+    {
+      "id": "gamification",
+      "title": "Your Progress",
+      "content": {
+        "type": "custom",
+        "component": "adaptive-gamification:leaderboard",
+        "props": { ... }
+      }
+    }
+  ]
+}
+```
 
 ### Configuration Schema
 
@@ -707,9 +792,13 @@ Mounts gamification UI elements.
 
 ```json
 {
-  "kind": "mount_gamification",
-  "slot": "overlay_corner_br",
-  "config": {
+  "tiles": [{
+    "id": "gamification-widget",
+    "title": "Achievements",
+    "content": {
+      "type": "custom",
+      "component": "adaptive-gamification:leaderboard",
+      "props": {
     "badges": [
       {
         "id": "first-purchase",
@@ -719,18 +808,6 @@ Mounts gamification UI elements.
         "trigger": {
           "event": "purchase_completed"
         }
-      },
-      {
-        "id": "explorer",
-        "name": "Explorer",
-        "icon": "compass",
-        "description": "Visited 10 different pages",
-        "trigger": {
-          "event": "page_view",
-          "conditions": [
-            { "type": "session_metric", "key": "unique_pages", "operator": ">=", "threshold": 10 }
-          ]
-        }
       }
     ],
     "points": {
@@ -759,6 +836,14 @@ Mounts gamification UI elements.
 
 Navigation tips accordion widget with conditional item visibility and toast notifications.
 
+## When to use
+
+| Goal | Action |
+|------|--------|
+| Scroll to an element on the page | `navigation:scrollTo` |
+| Navigate to a different URL | `navigation:navigate` |
+| Show contextual navigation tips widget | Add a **tile** with `component: "adaptive-nav:tips"` |
+
 ## Widget: `adaptive-nav:tips`
 
 Accordion of contextual navigation tips. Each tip has a collapsible header and expanded body with optional CTA link.
@@ -879,15 +964,26 @@ Navigates to a URL.
 
 Visual overlay capabilities including highlights, tooltips, badges, pulse animations, and celebrations.
 
+## When to use
+
+| Goal | Action |
+|------|--------|
+| Draw attention to an element (spotlight) | `overlays:highlight` |
+| Show contextual help or guidance near an element | `overlays:tooltip` |
+| Add a notification indicator (count, "NEW") | `overlays:badge` |
+| Subtle attention-grab animation | `overlays:pulse` |
+| Show a blocking or non-blocking dialog | `overlays:modal` |
+| Celebrate a user achievement | `overlays:celebrate` |
+
 ## Actions
 
-### highlight
+### overlays:highlight
 
 Creates a spotlight effect around an element with a scrim overlay.
 
 | Property             | Type          | Required | Default     | Description                             |
 | -------------------- | ------------- | -------- | ----------- | --------------------------------------- |
-| `kind`               | `"highlight"` | Yes      |             | Action type                             |
+| `kind`               | `"overlays:highlight"` | Yes      |             | Action type                             |
 | `anchorId`           | string        | Yes      |             | Element selector                        |
 | `style.color`        | string        | No       | `"#5b8cff"` | Ring color                              |
 | `style.scrimOpacity` | number        | No       | `0.55`      | Backdrop opacity 0-1 (set to 0 to hide) |
@@ -896,7 +992,7 @@ Creates a spotlight effect around an element with a scrim overlay.
 
 ```json
 {
-  "kind": "highlight",
+  "kind": "overlays:highlight",
   "anchorId": "#signup-button",
   "style": {
     "color": "#22c55e",
@@ -905,13 +1001,13 @@ Creates a spotlight effect around an element with a scrim overlay.
 }
 ```
 
-### tooltip
+### overlays:tooltip
 
 Shows a tooltip near an element with optional title, body, and CTA.
 
 | Property             | Type        | Required | Default       | Description                            |
 | -------------------- | ----------- | -------- | ------------- | -------------------------------------- |
-| `kind`               | `"tooltip"` | Yes      |               | Action type                            |
+| `kind`               | `"overlays:tooltip"` | Yes      |               | Action type                            |
 | `anchorId`           | string      | Yes      |               | Element selector                       |
 | `content.title`      | string      | No       |               | Tooltip heading                        |
 | `content.body`       | string      | Yes      |               | Tooltip text                           |
@@ -927,14 +1023,14 @@ Shows a tooltip near an element with optional title, body, and CTA.
 
 ```json
 {
-  "kind": "tooltip",
+  "kind": "overlays:tooltip",
   "anchorId": "#pricing-toggle",
   "content": {
     "title": "Save 20%",
     "body": "Switch to annual billing to save on your subscription.",
     "cta": {
       "label": "Switch Now",
-      "action": { "kind": "navigate", "url": "/billing?annual=true" }
+      "action": { "kind": "navigation:navigate", "url": "/billing?annual=true" }
     }
   },
   "placement": "bottom",
@@ -973,45 +1069,45 @@ Use `ctaButtons` for tooltips with multiple actions. Each button has:
 - `"faq:open:<questionId>"` — Convention for companion FAQ tooltips (see adaptive-faq CAPABILITIES for details). Publishes `action.tooltip_cta_clicked` which the FAQ widget listens for.
 - Any other value — Publishes `action.tooltip_cta_clicked` with the `actionId` in event props for custom handling
 
-### badge
+### overlays:badge
 
 Adds a small badge indicator near an element.
 
 | Property   | Type      | Required | Default       | Description                                                    |
 | ---------- | --------- | -------- | ------------- | -------------------------------------------------------------- |
-| `kind`     | `"badge"` | Yes      |               | Action type                                                    |
+| `kind`     | `"overlays:badge"` | Yes      |               | Action type                                                    |
 | `anchorId` | string    | Yes      |               | Element selector                                               |
 | `text`     | string    | Yes      |               | Badge text (e.g., "NEW", "3")                                  |
 | `position` | string    | No       | `"top-right"` | `"top-left"`, `"top-right"`, `"bottom-left"`, `"bottom-right"` |
 
 ```json
 {
-  "kind": "badge",
+  "kind": "overlays:badge",
   "anchorId": "#inbox-icon",
   "text": "5",
   "position": "top-right"
 }
 ```
 
-### pulse
+### overlays:pulse
 
 Adds a pulsing animation to draw attention.
 
 | Property   | Type      | Required | Default | Description              |
 | ---------- | --------- | -------- | ------- | ------------------------ |
-| `kind`     | `"pulse"` | Yes      |         | Action type              |
+| `kind`     | `"overlays:pulse"` | Yes      |         | Action type              |
 | `anchorId` | string    | Yes      |         | Element selector         |
 | `duration` | number    | No       | `2000`  | Animation duration in ms |
 
 ```json
 {
-  "kind": "pulse",
+  "kind": "overlays:pulse",
   "anchorId": ".notification-bell",
   "duration": 3000
 }
 ```
 
-### modal
+### overlays:modal
 
 Shows a centered modal dialog with optional CTA buttons.
 
@@ -1051,7 +1147,7 @@ Shows a centered modal dialog with optional CTA buttons.
 }
 ```
 
-### celebrate
+### overlays:celebrate
 
 Renders a fullscreen Canvas 2D celebration effect. One action kind with a pluggable `effect` parameter supporting multiple visual presets.
 
@@ -1273,15 +1369,7 @@ Control when adaptives activate using `DecisionStrategy`:
 
 ### 1. Choose the Right Action Type
 
-| Goal | Action |
-|------|--------|
-| Change text | `set_text` |
-| Add visual indicator | `badge`, `pulse` |
-| Show help text | `tooltip` |
-| Draw attention | `highlight` |
-| Add content | `insert_html` |
-| Navigate user | `scroll_to`, `navigate` |
-| Show UI panel | `mount_widget` + Surfaces |
+Each adaptive package has a "When to use" guide at the top of its capabilities section above. Refer to those for action selection guidance.
 
 ### 2. Anchor Selection
 
@@ -1313,8 +1401,8 @@ When `content:insertHtml` needs to open the canvas panel (e.g., a "Help Me Choos
 
 ```json
 {
-  "kind": "insert_html",
-  "anchorId": "[data-id='pricing-heading']",
+  "kind": "content:insertHtml",
+  "anchorId": { "selector": "[data-id='pricing-heading']", "route": "/" },
   "html": "<button style='background: #4a90e2; color: white; border: none; padding: 8px 16px; border-radius: 20px; cursor: pointer;'>Help Me Choose</button>",
   "position": "after",
   "deepLink": { "tileId": "plan_selector_faq" }
@@ -1327,4 +1415,4 @@ The `deepLink` object:
 
 The SDK automatically opens the canvas, navigates to the tile, sets cursor to pointer, and wires up click/cleanup handlers.
 
-**NEVER use `onclick`, `window.SynOS`, or any JavaScript in `insert_html` HTML strings.** The HTML is sanitized and event handlers are stripped. Use `deepLink` instead.
+**NEVER use `onclick`, `window.SynOS`, or any JavaScript in `content:insertHtml` HTML strings.** The HTML is sanitized and event handlers are stripped. Use `deepLink` instead.