@helpai/elements 1.10.0 → 1.12.0

package/llms-full.txt

@@ -1,6 +1,6 @@
-# Help AI Elements: the full SDK docs (@helpai/elements@1.10.0)
+# Help AI Elements: the full SDK docs (@helpai/elements@1.12.0)
 
-<!-- https://cdn.help.ai/sdk/js/elements/1.10.0/docs/quickstart.md -->
+<!-- https://cdn.help.ai/sdk/js/elements/1.12.0/docs/quickstart.md -->
 
 # Quickstart
 
@@ -67,7 +67,7 @@ kebab-case `data-*` attribute. Common ones:
 ></script>
 ```
 
-Full list: [Installation § script data attributes](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/installation.md#path-a--script-data--auto-boot).
+Full list: [Installation § script data attributes](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/installation.md#path-a--script-data--auto-boot).
 
 ---
 
@@ -149,7 +149,7 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 ### Vue / Svelte / Angular / any bundler
 
 Call `init(...)` once on mount and `destroy()` on unmount, or use the `<web-ai-chat>` element (path D).
-Full framework-by-framework walkthrough: [Framework integrations](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/frameworks.md).
+Full framework-by-framework walkthrough: [Framework integrations](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/frameworks.md).
 
 ---
 
@@ -186,20 +186,20 @@ round chat bubble with an accent color.
 - **Close the panel** → the bubble returns.
 - **Reload the page** → your chat history stays intact.
 
-Something not showing up? → [Troubleshooting](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/troubleshooting.md).
+Something not showing up? → [Troubleshooting](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/troubleshooting.md).
 
 ---
 
 ## 4. Common next steps
 
-- **Match your brand** — [Theming](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/theming.md) has every color,
+- **Match your brand** — [Theming](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/theming.md) has every color,
   radius, and font knob.
-- **Change the launcher label / icon** — [`launcher` options](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/configuration.md#launcher).
+- **Change the launcher label / icon** — [`launcher` options](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/configuration.md#launcher).
 - **Know who the visitor is** — pass `userContext: { id, email, name }`
   (and `pageContext: { area }`) for personalization.
-- **Forward chat events to analytics** — [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/events-and-hooks.md).
+- **Forward chat events to analytics** — [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/events-and-hooks.md).
 - **Add a second widget** (one for sales, one for support) — [Recipes
-  § Multiple widgets](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/recipes.md#multiple-widgets-on-one-page).
+  § Multiple widgets](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/recipes.md#multiple-widgets-on-one-page).
 
 ---
 
@@ -230,15 +230,15 @@ the same deployment:
 | Remix                   | read from `window.ENV` |
 | Create React App        | `REACT_APP_*`          |
 
-Full security notes: [Security & privacy](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/security-privacy.md).
+Full security notes: [Security & privacy](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/security-privacy.md).
 
 ---
 
-<!-- https://cdn.help.ai/sdk/js/elements/1.10.0/docs/installation.md -->
+<!-- https://cdn.help.ai/sdk/js/elements/1.12.0/docs/installation.md -->
 
 # Installation
 
-Deep-dive for every install path. See [Quickstart](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/quickstart.md)
+Deep-dive for every install path. See [Quickstart](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/quickstart.md)
 for the 5-minute version.
 
 ---
@@ -250,7 +250,7 @@ for the 5-minute version.
 | [A. `<script data-*>` auto-boot](#path-a--script-data--auto-boot) | Static HTML, WordPress, no build step               | CDN        |
 | [B. Async loader snippet](#path-b--async-loader-snippet)          | Tag managers, analytics pipelines                   | CDN        |
 | [C. NPM package](#path-c--npm-package)                            | React, Next.js, Vue, Svelte, SolidJS, any bundler   | NPM        |
-| [React kit](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/frameworks.md#react)                                | React, Next.js, Remix: `<HelpAI />` + `useHelpAI()` | NPM        |
+| [React kit](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/frameworks.md#react)                                | React, Next.js, Remix: `<HelpAI />` + `useHelpAI()` | NPM        |
 | [D. Web Component](#path-d--web-component)                        | Declarative tags in any framework                   | CDN or NPM |
 
 > ### CDN URL
@@ -271,9 +271,9 @@ for the 5-minute version.
 All four paths:
 
 - Load the same JS bundle.
-- Accept the same [configuration options](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/configuration.md).
-- Emit the same [events](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/events-and-hooks.md).
-- Respect the same [isolation guarantees](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/security-privacy.md#shadow-dom--iframe).
+- Accept the same [configuration options](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/configuration.md).
+- Emit the same [events](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/events-and-hooks.md).
+- Respect the same [isolation guarantees](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/security-privacy.md#shadow-dom--iframe).
 
 You can combine them — e.g., a Next.js page can use path C, and a
 marketing landing can use path A, both pointing at the same deployment.
@@ -327,24 +327,24 @@ The zero-JavaScript path intentionally exposes a small, flat subset of
 | `data-page-context`                            | `pageContext` extras (JSON)       | `'{"experiment":"b"}'`          |
 
 Unknown attributes are ignored. Full option semantics:
-[Configuration](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/configuration.md).
+[Configuration](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/configuration.md).
 
 > Explicit scalar attributes (`data-user-id`, `data-page-area`, …) win
 > over keys in the `data-user-context` / `data-page-context` JSON. For
 > SPAs where the visitor logs in after load or navigates between pages,
 > set context dynamically with
-> [`instance.setUserContext(...)` / `setPageContext(...)`](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/configuration.md#setting-context-after-login--on-navigation).
+> [`instance.setUserContext(...)` / `setPageContext(...)`](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/configuration.md#setting-context-after-login--on-navigation).
 > The `data-user-*` / `data-page-*` attributes are reactive — updating
 > one re-handshakes with the same anonymous visitor/conversation. This
 > context is informational for the AI, never an auth credential.
 
-### `data-no-autoboot`
+### Load without mounting
 
-Add this flag to load the bundle **without** automatically mounting.
-Useful when you want to `init()` later from JavaScript:
+The script tag mounts the widget only when it carries `data-ai-agent-deployment-id`. Leave that attribute out to
+load the bundle **without** mounting, then call `init()` from JavaScript when you're ready:
 
 ```html
-<script src="https://cdn.help.ai/sdk/js/elements/latest/elements.js" data-no-autoboot></script>
+<script src="https://cdn.help.ai/sdk/js/elements/latest/elements.js"></script>
 <script>
   // Mount later, conditionally
   document.addEventListener('DOMContentLoaded', () => {
@@ -436,7 +436,7 @@ arrays or objects to it before the bundle arrives:
 </script>
 ```
 
-Full details: [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/events-and-hooks.md#global-lifecycle-hooks).
+Full details: [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/events-and-hooks.md#global-lifecycle-hooks).
 
 ### After boot
 
@@ -458,7 +458,7 @@ window.HelpAI.brand                      // { id, displayName, cdnUrl, ... }
 ## Path C — NPM package
 
 For sites with a bundler. Full framework-specific walkthroughs:
-[Framework integrations](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/frameworks.md).
+[Framework integrations](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/frameworks.md).
 
 ### Install
 
@@ -650,7 +650,7 @@ declare module 'react' {
 
 **Angular** — add `CUSTOM_ELEMENTS_SCHEMA` to your module.
 
-Framework-by-framework details: [Framework integrations](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/frameworks.md).
+Framework-by-framework details: [Framework integrations](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/frameworks.md).
 
 ---
 
@@ -858,14 +858,14 @@ weigh chunking (see [Caching, versioning & self-hosting](#caching-versioning--se
 
 ## Next
 
-- [Configuration](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/configuration.md) — every option explained with examples.
-- [Theming & customization](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/theming.md) — matching your brand.
-- [Framework integrations](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/frameworks.md) — framework-specific recipes.
-- [Troubleshooting](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/troubleshooting.md) — "my widget isn't showing up".
+- [Configuration](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/configuration.md) — every option explained with examples.
+- [Theming & customization](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/theming.md) — matching your brand.
+- [Framework integrations](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/frameworks.md) — framework-specific recipes.
+- [Troubleshooting](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/troubleshooting.md) — "my widget isn't showing up".
 
 ---
 
-<!-- https://cdn.help.ai/sdk/js/elements/1.10.0/docs/frameworks.md -->
+<!-- https://cdn.help.ai/sdk/js/elements/1.12.0/docs/frameworks.md -->
 
 # Framework integrations
 
@@ -954,20 +954,23 @@ function PricingHelp() {
 }
 ```
 
-- **`<HelpAI {...options} />`** takes every [widget option](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/configuration.md) as a prop; `aiAgentDeploymentId` is
+- **`<HelpAI {...options} />`** takes every [widget option](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/configuration.md) as a prop; `aiAgentDeploymentId` is
   required. It renders nothing itself: the widget mounts once the page is in the browser, a prop change re-configures
   the live widget without a remount, and unmounting removes it. Callback props (`onOpen`, `onMessage`, …) can be new
   functions on every render; the widget always calls the latest one.
-- **`useHelpAI(widgetId?)`** returns `{ state, ask, open, close, reset }`. `state` is
-  [`{ open, ready, unread, conversationId? }`](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/api-reference.md#state-and-ready) and re-renders the component when it changes;
+- **`useHelpAI(widgetId?)`** returns `{ state, ask, open, close, reset, track }`. `state` is
+  [`{ open, ready, unread, conversationId? }`](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/api-reference.md#state-and-ready) and re-renders the component when it changes;
   the server render sees the initial state. The commands are stable across renders and do nothing until the widget
   has mounted (`state.ready`). `ask(text)` fills the composer; `ask(text, { send: true })` sends it. Call `reset()`
   when your user logs out.
 - **One import path.** The kit carries the whole widget API (`getInstance`, `hook`, the types), so import everything
   from `@helpai/elements/react`; the package's other entries are separate copies with their own widgets.
 - **Two widgets** on one page: give each `<HelpAI widgetId='support' … />` and read it with `useHelpAI('support')`.
+- **Page tools:** `useHelpAITool(tool)` gives the agent a tool while the component is mounted, or pass
+  `<HelpAI tools={[...]} />` ([Page tools](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/page-tools.md)). `execute` can be a new function on every render; the
+  agent's call runs the latest one, and only a changed definition registers or configures anything again.
 - **Signed-in users:** pass `userToken`, a function that fetches the token your server signs
-  ([Verified users](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/security-privacy.md#verified-users-usertoken)). Keep it stable for one user (a module function, or
+  ([Verified users](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/security-privacy.md#verified-users-usertoken)). Keep it stable for one user (a module function, or
   `useCallback` keyed on your user id): a different function signs in afresh, and dropping it signs out.
 
 The kit bundles the widget and imports only React from your app, so you don't need Preact installed.
@@ -990,7 +993,7 @@ function Chat() {
 `import type {} from '@helpai/elements/jsx/react';` once (in your entry file or a `.d.ts`) registers `<web-ai-chat>`
 in React 19's JSX: every attribute the element reads autocompletes, `ai-agent-deployment-id` is required, and a `ref`
 is the typed element with `ask`, `open`, `state`, `ready` and `reset`. Vue and Svelte have `@helpai/elements/jsx/vue`
-and `@helpai/elements/jsx/svelte` ([JSX typings](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/api-reference.md#jsx-typings)).
+and `@helpai/elements/jsx/svelte` ([JSX typings](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/api-reference.md#jsx-typings)).
 
 ```tsx
 import { useRef } from 'react';
@@ -1499,21 +1502,21 @@ sometimes mounts duplicate instances. Always pair your `useEffect` /
 
 **CSP blocks the widget** — the widget inlines styles inside a shadow
 root (requires `style-src 'unsafe-inline'` or a nonce pattern). See
-[Security & privacy § CSP](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/security-privacy.md#content-security-policy).
+[Security & privacy § CSP](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/security-privacy.md#content-security-policy).
 
-More: [Troubleshooting](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/troubleshooting.md).
+More: [Troubleshooting](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/troubleshooting.md).
 
 ---
 
 ## Next
 
-- [Recipes](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/recipes.md) — programmatic control patterns.
-- [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/events-and-hooks.md) — analytics integration.
-- [Configuration](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/configuration.md) — every option in detail.
+- [Recipes](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/recipes.md) — programmatic control patterns.
+- [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/events-and-hooks.md) — analytics integration.
+- [Configuration](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/configuration.md) — every option in detail.
 
 ---
 
-<!-- https://cdn.help.ai/sdk/js/elements/1.10.0/docs/configuration.md -->
+<!-- https://cdn.help.ai/sdk/js/elements/1.12.0/docs/configuration.md -->
 
 # Configuration reference
 
@@ -1521,7 +1524,7 @@ Every option you can pass to `init(...)` / `mount(...)` / set via
 `data-*` attributes / set via web-component attributes.
 
 Group-by-group walkthrough with realistic examples. For an at-a-glance
-lookup, see [API reference](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/api-reference.md).
+lookup, see [API reference](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/api-reference.md).
 
 ---
 
@@ -1606,7 +1609,7 @@ init({ widgetId: 'support', publicKey: SUPPORT_KEY, aiAgentDeploymentId: SUPPORT
 init({ widgetId: 'sales', publicKey: SALES_KEY, aiAgentDeploymentId: SALES_DEPLOYMENT_ID });
 ```
 
-See [Recipes § Multiple widgets](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/recipes.md#multiple-widgets-on-one-page).
+See [Recipes § Multiple widgets](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/recipes.md#multiple-widgets-on-one-page).
 
 ### `baseUrl`
 
@@ -1626,12 +1629,30 @@ Override if you use:
 Signs the visitor in as your logged-in user: a JWT your server signs with the deployment's secret key, or a function
 returning a fresh one. Their conversations then follow them to any device, and the AI gets their name and email as
 verified facts. Runtime-only: not an attribute or `data-*` option, so the token stays out of the page's markup. See
-[Security → Verified users](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/security-privacy.md#verified-users-usertoken) for signing it.
+[Security → Verified users](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/security-privacy.md#verified-users-usertoken) for signing it.
 
 ```ts
 init({ publicKey: 'agent_pk_...', aiAgentDeploymentId: '01900000-0000-7000-8000-000000000000', userToken: () => fetch('/api/help-ai-token').then((res) => res.text()) });
 ```
 
+### `tools`
+
+`ModelContextTool[]` · default: none
+
+Tools the AI agent can use on your page, in the WebMCP tool shape: a name, a description, a JSON Schema of its input
+and an `execute` function the widget runs in the visitor's browser when the agent calls it
+(`annotations: { consequentialHint: true }` asks the visitor first). Runtime-only, like `userToken`;
+`chat.update({ tools })` replaces them. `chat.registerTool(tool)` adds one for every widget on the page instead. Full
+guide: [Page tools](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/page-tools.md).
+
+```ts
+init({
+  publicKey: 'agent_pk_...',
+  aiAgentDeploymentId: '01900000-0000-7000-8000-000000000000',
+  tools: [{ name: 'open_booking', description: 'Open the booking form. Use it whenever the visitor wants to book a call.', execute: () => (bookingForm.open(), { opened: true }) }],
+});
+```
+
 ### `userContext`
 
 `object | undefined`
@@ -1751,8 +1772,8 @@ widget.clearUserContext();
 ```
 
 You can also seed context at load time via `data-user-*` /
-`data-page-*` tag attributes — see [Installation](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/installation.md) and
-the framework recipes in [`frameworks.md`](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/frameworks.md).
+`data-page-*` tag attributes — see [Installation](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/installation.md) and
+the framework recipes in [`frameworks.md`](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/frameworks.md).
 
 ---
 
@@ -1807,7 +1828,7 @@ init({ presentation: { mode: 'floating', iframe: true }, publicKey: 'agent_pk_..
 ```
 
 Composes with any `mode`. Default is `false` — shadow DOM alone is
-enough for 95% of deployments. [Security § Iframe isolation](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/security-privacy.md#iframe-isolation).
+enough for 95% of deployments. [Security § Iframe isolation](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/security-privacy.md#iframe-isolation).
 
 ### `presentation.position`
 
@@ -1872,7 +1893,7 @@ mode via the header picker regardless of palette overrides.
 End users can flip the theme via the header picker. Their choice is
 persisted per device + synced cross-device.
 
-Full customization guide: [Theming](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/theming.md).
+Full customization guide: [Theming](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/theming.md).
 
 ---
 
@@ -1972,7 +1993,7 @@ init({
 ```
 
 Variants + callout fully explained in
-[Theming § Launcher](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/theming.md#launcher).
+[Theming § Launcher](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/theming.md#launcher).
 
 ### `launcher.hidden`
 
@@ -2211,7 +2232,7 @@ Full behavior + wire contract:
 `boolean` · default: `false`
 
 Turn OFF the 👍/👎 feedback controls under each rateable reply (AI or operator) — unset/`false` shows them (default). While
-shown, a choice fires the [`messageFeedback`](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/events-and-hooks.md) event and is sent to the backend.
+shown, a choice fires the [`messageFeedback`](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/events-and-hooks.md) event and is sent to the backend.
 
 ```ts
 init({ behavior: { disableMessageFeedback: true } }); // hide the controls
@@ -2300,7 +2321,7 @@ init({
 });
 ```
 
-Full key list: [i18n](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/theming.md#internationalization) or
+Full key list: [i18n](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/theming.md#internationalization) or
 `src/i18n/strings.ts` in the source.
 
 ---
@@ -2383,7 +2404,7 @@ init({
 });
 ```
 
-For richer event handling, see [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/events-and-hooks.md).
+For richer event handling, see [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/events-and-hooks.md).
 
 ---
 
@@ -2419,7 +2440,7 @@ The widget itself does not include drafts in Help AI network requests before
 Send. Use an encrypted adapter when same-origin plaintext storage is not
 acceptable; an in-memory adapter disables reload restoration.
 
-Full adapter contract: [Security & privacy § custom storage](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/security-privacy.md#custom-storage).
+Full adapter contract: [Security & privacy § custom storage](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/security-privacy.md#custom-storage).
 
 ---
 
@@ -2525,14 +2546,14 @@ const chat = init({
 
 ## Not covered here
 
-- **Events** → [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/events-and-hooks.md)
-- **Theming deep-dive** → [Theming](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/theming.md)
-- **Framework-specific wiring** → [Frameworks](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/frameworks.md)
+- **Events** → [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/events-and-hooks.md)
+- **Theming deep-dive** → [Theming](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/theming.md)
+- **Framework-specific wiring** → [Frameworks](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/frameworks.md)
 - **Backend API** → Backend contract (internal)
 
 ---
 
-<!-- https://cdn.help.ai/sdk/js/elements/1.10.0/docs/options.md -->
+<!-- https://cdn.help.ai/sdk/js/elements/1.12.0/docs/options.md -->
 
 # Configuration — `ChatWidgetOptions`
 
@@ -2860,13 +2881,13 @@ Pass `footer: { poweredBy: { text: "" } }` to opt out of the brand attribution.
 
 ---
 
-<!-- https://cdn.help.ai/sdk/js/elements/1.10.0/docs/api-reference.md -->
+<!-- https://cdn.help.ai/sdk/js/elements/1.12.0/docs/api-reference.md -->
 
 # API reference
 
 Compact lookup for the SDK's exported functions, types, and events.
-For explanations + examples, see the [Configuration](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/configuration.md)
-and [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/events-and-hooks.md) guides.
+For explanations + examples, see the [Configuration](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/configuration.md)
+and [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/events-and-hooks.md) guides.
 
 ---
 
@@ -2910,13 +2931,14 @@ React kit (React 18+; everything above plus the component and the hook, so impor
 ```ts
 import {
   HelpAI, // <HelpAI {...options} /> mounts the widget, re-configures it on prop changes, removes it on unmount
-  useHelpAI, // useHelpAI(widgetId?) → { state, ask, open, close, reset }, re-rendering on state changes
+  useHelpAI, // useHelpAI(widgetId?) → { state, ask, open, close, reset, track }, re-rendering on state changes
+  useHelpAITool, // useHelpAITool(tool) gives the agent a page tool while the component is mounted
   type HelpAIProps,
   type HelpAIControls,
 } from '@helpai/elements/react';
 ```
 
-See [Frameworks → React](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/frameworks.md#react).
+See [Frameworks → React](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/frameworks.md#react).
 
 ---
 
@@ -3004,13 +3026,15 @@ interface ChatWidgetInstance {
   // Lifecycle
   reset(): void; // start over as a new anonymous visitor (on logout)
   login(userToken: UserTokenSource): void; // sign the visitor in as your logged-in user (a signed token, or a function returning one)
+  track(name: string, data?: Record<string, string | number | boolean>): void; // report your page's own event: analytics + the agent's next message
+  registerTool(tool: ModelContextTool, options?: { signal?: AbortSignal }): void; // a tool the agent can use on this page, for every widget on it
   destroy(): void;
 
   // Events
   on<E extends EventName>(name: E, fn: (payload: EventMap[E]) => void): () => void; // returns unsubscribe fn
 
   // Re-config
-  update(patch: Partial<ChatWidgetOptions>): void;
+  update(patch: Partial<ChatWidgetOptions>): void; // e.g. update({ tools }) on a route change
 
   // Host-asserted context (informational, not auth; re-handshakes, same visitor/conversation)
   setUserContext(ctx: Partial<NonNullable<ChatWidgetOptions['userContext']>>): void; // merges into the current user context
@@ -3030,7 +3054,7 @@ interface ChatWidgetInstance {
 ## `ChatWidgetOptions`
 
 The generated, schema-backed field reference is
-[`docs/api/configuration.md`](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/options.md); it is authoritative.
+[`docs/api/configuration.md`](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/options.md); it is authoritative.
 The public input keeps embed identity, context, endpoint overrides, storage,
 and callbacks at the top level. Serializable widget settings use focused
 nested sections. `mount()` and `init()` require `aiAgentDeploymentId`; the
@@ -3070,7 +3094,30 @@ init({
 ```
 
 The complete type also exposes `features`, `forms`, `modules`, and `tracking`.
-See [Configuration](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/configuration.md) for behavior and examples.
+See [Configuration](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/configuration.md) for behavior and examples.
+
+### `ModelContextTool`
+
+A tool the agent can use on your page, in the WebMCP tool shape ([Page tools](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/page-tools.md)). On `<web-ai-chat>`
+it's the `tools` property or `registerTool()`, since functions can't be attributes.
+
+```ts
+interface ModelContextTool<TInput = unknown> {
+  name: string; // letters, digits, `_` and `-` (58 at most; others become `_`); the agent sees `site__<name>`
+  title?: string;
+  description: string; // when to use it (1024 characters at most)
+  inputSchema?: Record<string, unknown>; // JSON Schema of an object; none = no input
+  annotations?: ToolAnnotations; // `consequentialHint: true` = the visitor approves each call first
+  execute(input: TInput, options: { signal: AbortSignal }): unknown; // a JSON result, or throw; `signal` aborts when the visitor moves on
+}
+
+interface ToolAnnotations {
+  readOnlyHint?: boolean;
+  untrustedContentHint?: boolean;
+  consequentialHint?: boolean;
+  debugging?: boolean;
+}
+```
 
 ### `ActionName`
 
@@ -3205,7 +3252,7 @@ reconnects as that user: their conversations on this browser move to them, and t
 device where they're signed in. Call `reset()` when they sign out; switching to another user's token starts over the
 same way. Also `HelpAI('login', userToken)`, `element.login(userToken)` on `<web-ai-chat>` (not an attribute, so the
 token stays out of the DOM), the `userToken` option at `init()`, and `<HelpAI userToken={…} />`. Signing and the
-guarantees: [Security → Verified users](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/security-privacy.md#verified-users-usertoken).
+guarantees: [Security → Verified users](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/security-privacy.md#verified-users-usertoken).
 
 ```ts
 chat.login(() => fetch('/api/help-ai-token').then((res) => res.text()));
@@ -3213,6 +3260,32 @@ chat.login(() => fetch('/api/help-ai-token').then((res) => res.text()));
 
 ---
 
+### `registerTool(tool, options?)`
+
+Gives the agent a tool on this page, for every widget on it: the latest registration of a name wins, and aborting
+`options.signal` removes it. Also `HelpAI('registerTool', tool)` (queued before the script loads),
+`element.registerTool(tool)` and the React kit's `useHelpAITool(tool)`. Details: [Page tools](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/page-tools.md).
+
+```ts
+chat.registerTool({ name: 'open_booking', description: 'Open the booking form. Use it whenever the visitor wants to book a call.', execute: () => bookingForm.open() });
+```
+
+---
+
+### `track(name, data?)`
+
+Reports something the visitor did on your site, outside the chat. It sends a `hostEvent` hit to Elements analytics
+(not when tracking is off), and the widget keeps the last 10 for the agent, which reads them with the visitor's next
+message. The name is 1–64 characters; the data is flat (strings, numbers, booleans; 256 characters of JSON at most).
+Also `HelpAI('track', name, data)`, `element.track(name, data)` and `useHelpAI().track`. Details:
+[Analytics → Your own events](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/analytics.md#your-own-events-chattrack).
+
+```ts
+chat.track('plan_viewed', { plan: 'pro' });
+```
+
+---
+
 ## Events
 
 ### `EventMap`
@@ -3288,10 +3361,10 @@ The auto-boot parser exposes the documented flat `data-*` subset.
 ></script>
 ```
 
-Full attribute list: [Installation § script data attributes](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/installation.md#attributes).
+Full attribute list: [Installation § script data attributes](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/installation.md#attributes).
 
-`data-no-autoboot` — loads the bundle but doesn't auto-mount. For
-deferred init via JS.
+Leave out `data-ai-agent-deployment-id` to load the bundle without mounting, then call
+`HelpAI.init({ … })` from JavaScript ([Installation § Load without mounting](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/installation.md#load-without-mounting)).
 
 ---
 
@@ -3495,14 +3568,14 @@ Or use `/v1/` for the latest 1.x.x (auto-patches, no major breaks).
 
 ## See also
 
-- [Configuration](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/configuration.md) — options with examples + context.
-- [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/events-and-hooks.md) — event handling deep-dive.
-- [Recipes](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/recipes.md) — copy-paste scenarios.
-- [Troubleshooting](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/troubleshooting.md) — when things go wrong.
+- [Configuration](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/configuration.md) — options with examples + context.
+- [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/events-and-hooks.md) — event handling deep-dive.
+- [Recipes](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/recipes.md) — copy-paste scenarios.
+- [Troubleshooting](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/troubleshooting.md) — when things go wrong.
 
 ---
 
-<!-- https://cdn.help.ai/sdk/js/elements/1.10.0/docs/events-and-hooks.md -->
+<!-- https://cdn.help.ai/sdk/js/elements/1.12.0/docs/events-and-hooks.md -->
 
 # Events & lifecycle hooks
 
@@ -3524,17 +3597,19 @@ Both deliver the same event stream. Both are safe to mix.
 
 ## Available events
 
-| Event             | Fires on                                          | Payload                                                |
-| ----------------- | ------------------------------------------------- | ------------------------------------------------------ |
-| `open`            | Panel opens (floating mode)                       | `void`                                                 |
-| `close`           | Panel closes                                      | `void`                                                 |
-| `message`         | User sends a message + assistant finishes a reply | `{ role: "user" \| "assistant"; text: string }`        |
-| `error`           | Transport error or mid-stream error               | `unknown` (error object or message)                    |
-| `expand`          | Expanded tier toggled (⤢)                         | `boolean` (new state)                                  |
-| `fullscreen`      | Fullscreen tier toggled (⛶)                       | `boolean` (new state)                                  |
-| `handshake`       | Widget finishes booting (once per mount)          | `HandshakeResponse` (dashboard config)                 |
-| `localeChange`    | User picks a different language                   | `string` (new BCP-47 tag)                              |
-| `messageFeedback` | User rates a reply 👍/👎 (or clears it)           | `{ messageId: string; value: "up" \| "down" \| null }` |
+| Event             | Fires on                                                                            | Payload                                                                                                                                    |
+| ----------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `open`            | Panel opens (floating mode)                                                         | `void`                                                                                                                                     |
+| `close`           | Panel closes                                                                        | `void`                                                                                                                                     |
+| `message`         | User sends a message, or a reply from the AI agent or a team member finishes        | `{ role: "user" \| "assistant" \| "operator"; text: string }`                                                                              |
+| `error`           | Transport error or mid-stream error                                                 | `unknown` (error object or message)                                                                                                        |
+| `expand`          | Expanded tier toggled (⤢)                                                           | `boolean` (new state)                                                                                                                      |
+| `fullscreen`      | Fullscreen tier toggled (⛶)                                                         | `boolean` (new state)                                                                                                                      |
+| `handshake`       | Widget finishes booting (once per mount)                                            | `HandshakeResponse` (dashboard config)                                                                                                     |
+| `localeChange`    | User picks a different language                                                     | `string` (new BCP-47 tag)                                                                                                                  |
+| `messageFeedback` | User rates a reply 👍/👎 (or clears it)                                             | `{ messageId: string; value: "up" \| "down" \| null }`                                                                                     |
+| `hostEvent`       | Your page calls `chat.track(name, data)`                                            | `{ name: string; data?: Record<string, scalar> }`                                                                                          |
+| `toolResult`      | A [page tool](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/page-tools.md) call settles, or the visitor answers a question card | `{ toolCallId: string; name?: string; status?: "completed" \| "failed" \| "declined" \| "stopped" \| "interrupted"; durationMs?: number }` |
 
 ---
 
@@ -3976,21 +4051,220 @@ explicit `off()` is belt-and-suspenders. Either way works.
 | No events at all                    | `.on()` called before the instance was fully constructed. Use `init()`'s return value or a pre-boot hook |
 | Pre-boot hook never fires           | Widget never mounted — check the public-key/deployment-id pair                                           |
 
-[Troubleshooting](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/troubleshooting.md) has the full diagnostic
+[Troubleshooting](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/troubleshooting.md) has the full diagnostic
 checklist.
 
 ---
 
 ## Next
 
-- [Analytics integration](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/analytics.md) — GA4, Mixpanel, Segment, Amplitude, PostHog, Sentry, multi-provider
-- [Recipes](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/recipes.md) — copy-paste scenarios
-- [API reference § events](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/api-reference.md#events) — compact lookup
-- [Configuration § callbacks](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/configuration.md#callbacks-shortcut-for-events)
+- [Analytics integration](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/analytics.md) — GA4, Mixpanel, Segment, Amplitude, PostHog, Sentry, multi-provider
+- [Recipes](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/recipes.md) — copy-paste scenarios
+- [API reference § events](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/api-reference.md#events) — compact lookup
+- [Configuration § callbacks](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/configuration.md#callbacks-shortcut-for-events)
+
+---
+
+<!-- https://cdn.help.ai/sdk/js/elements/1.12.0/docs/page-tools.md -->
+
+# Page tools
+
+Give the AI agent tools that act on your own page: open your booking form, read the visitor's cart, jump to a
+section, fill in a form. You describe each tool and write its function; the agent decides when to call it, the
+widget runs the function in the visitor's browser, and the agent continues the conversation with what it returned.
+Every page can offer different tools, so the agent can do on each page what that page is for.
+
+A tool has the [WebMCP](https://webmachinelearning.github.io/webmcp/) shape (the W3C draft for tools a web page
+offers to AI agents), so a tool you write for the widget also works with a browser's own WebMCP support, and the
+other way round.
+
+```ts
+chat.registerTool({
+  name: 'open_booking',
+  description: 'Open the booking form on this page for a meeting type. Use it whenever the visitor wants to book a call.',
+  inputSchema: {
+    type: 'object',
+    properties: { meetingType: { type: 'string', enum: ['sales', 'support'] } },
+    required: ['meetingType'],
+  },
+  execute({ meetingType }) {
+    bookingForm.open(meetingType);
+    return { opened: true };
+  },
+});
+```
+
+A visitor writes "I'd like to talk to sales"; the agent calls `open_booking` with `{ meetingType: 'sales' }`, your
+booking form opens, and the agent answers "The booking form is open, pick a time that suits you."
+
+## Adding tools
+
+| Where you are    | How                                                                                                                          |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| Script tag       | `HelpAI('registerTool', tool)`. Works before the widget has loaded: the loader queues it.                                    |
+| npm              | `chat.registerTool(tool, { signal })`, or `init({ tools: [...] })`.                                                          |
+| React            | `useHelpAITool(tool)` in the component that owns the feature, or `<HelpAI tools={[...]} />`.                                 |
+| `<web-ai-chat>`  | `element.registerTool(tool)`, or the `tools` property (functions can't be attributes).                                       |
+| Plain HTML       | A form with `toolname` and `tooldescription` attributes ([Forms as tools](#forms-as-tools)); no script needed.               |
+| A WebMCP browser | Tools registered with the browser's own `document.modelContext.registerTool()` are offered too ([WebMCP](#webmcp-browsers)). |
+
+`registerTool` adds the tool for every widget on the page. Pass an `AbortSignal` to remove it again, for example when
+a single-page app leaves the route that owns it:
+
+```ts
+const route = new AbortController();
+chat.registerTool(addToCart, { signal: route.signal });
+// …when the visitor leaves the product page:
+route.abort();
+```
+
+`useHelpAITool` does this for you: the tool is registered while the component is mounted, `execute` always runs the
+latest render's function, and React's StrictMode double mount still leaves one registration.
+
+## A tool
+
+| Field                           | What it is                                                                                                                                                                                 |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `name`                          | Letters, digits, `_` and `-`, 58 characters at most; other characters become `_`. The agent sees `site__<name>`. A name registered again replaces the earlier tool.                        |
+| `description`                   | When the agent should use it and what it does, 1024 characters at most. The agent picks tools by their descriptions: say when, not only what. Without one, `title` (then `name`) is used.  |
+| `title`                         | Optional. A short human name.                                                                                                                                                              |
+| `inputSchema`                   | Optional. [JSON Schema](https://json-schema.org/) of the input, an object. The agent fills it in; use `enum` and `required` to keep the input exact. Without one, the tool takes no input. |
+| `annotations.consequentialHint` | Optional. `true` for a tool with real consequences (an order, a booking, a message to someone): the visitor approves each call in the chat first, and the function runs only on Approve.   |
+| `execute`                       | `(input, { signal }) => result`. Return a value or a promise of one; throw to report a failure. `signal` aborts when the visitor moves on before the call finishes.                        |
+
+The `ModelContextTool` and `ToolAnnotations` types are exported for TypeScript; `ModelContextTool<{ sku: string }>`
+types `execute`'s input. WebMCP's other annotations (`readOnlyHint`, `untrustedContentHint`) are accepted and not used
+yet.
+
+Nothing about a tool can break the chat: a tool without a `name` or an `execute` function is left out with a warning
+in the browser console, and every message still goes through.
+
+## Forms as tools
+
+A form becomes a tool with two attributes, in every browser:
+
+```html
+<form toolname="request_demo" tooldescription="Request a product demo for the visitor." toolautosubmit>
+  <label for="email">Work email</label>
+  <input id="email" name="email" type="email" required />
+  <input name="company" toolparamdescription="The visitor's company name" />
+  <select name="plan">
+    <option value="starter">Starter</option>
+    <option value="pro">Pro</option>
+  </select>
+  <button>Request demo</button>
+</form>
+```
+
+- Each named field is an input the agent can fill: a `select` or radio group takes one of its values, a checkbox
+  `true` or `false`, a number field a number, anything else text. Hidden, disabled and file fields are left out, and
+  so are passwords: the visitor types those, never the chat.
+- A field's description is its `toolparamdescription`, else its label, else its `aria-description`; `required`
+  fields are required.
+- The agent fills the fields the way a visitor would (your framework's change handlers run). With `toolautosubmit`
+  the form is then submitted; without it the visitor checks the form and presses its button. When a field still
+  blocks the submit (a password, or a value the browser rejects), the form isn't submitted and the agent is told which
+  field needs the visitor.
+
+## WebMCP browsers
+
+In a browser with WebMCP (`document.modelContext`: in Chrome, turn on `chrome://flags/#enable-experimental-web-platform-features`
+or join the origin trial), the tools the page registered with the browser are offered to the agent too, and the widget
+runs them through the browser. A `<form toolname>` is the exception: such a browser lists it too, but the widget fills
+it itself, as in every other browser, so your form's own submit handler keeps working and passwords stay the
+visitor's. Elsewhere, nothing changes.
+
+## Which tools a message offers
+
+The widget reads the page's tools when the visitor sends each message: the browser's WebMCP tools, then forms, then
+the `tools` option, then `registerTool`. For a name in more than one place, the later one wins. When the agent calls a
+tool, the widget reads them again and runs the current function of that name, so a single-page app's route change
+applies straight away, with nothing to keep in sync. A call to a tool the page no longer has tells the agent the page
+doesn't offer it right now. So does a call to a tool the message didn't offer at all (the agent repeating an earlier
+call after a route change): the server answers it with "This page doesn't offer that action right now.", tells the agent
+not to call it again this turn, and the agent carries on from what it knows or asks the visitor.
+
+## What the agent gets back
+
+- **A return value** becomes the tool's result, as JSON: dates become strings, `undefined` becomes `null`, functions
+  are dropped, a page element is named (`"[dialog]"`), a repeated object reads `"[circular]"`, and a result over
+  30,000 characters is sent as `{ truncated: true, preview }`. Return what the agent needs to answer well, such as
+  `{ opened: true }` or `{ items: 2, total: '$48' }`.
+- **A thrown error** (or a rejected promise) reaches the agent as the tool's error, with its message, so it can tell
+  the visitor or try another way. For an expected miss ("that product is out of stock") a normal result such as
+  `{ ok: false, reason: 'out of stock' }` gives the agent more to work with.
+
+With several calls in one step, the agent waits for all of them, and for any approvals, then continues once.
+
+## Each call runs once
+
+- **Tabs.** Only the tab where the visitor sent the message runs the calls in its reply; another tab of the same
+  conversation shows them running, then the agent's answer.
+- **Reloads and navigation.** A call that hadn't started when the page reloaded runs once after the reload. A call
+  that was running is never run again: the agent is told the page reloaded, so it may or may not have taken effect,
+  and checks with the visitor; its card reads "Not completed". A result that was ready but not yet sent is sent after the reload. The widget keeps
+  this note per tab in `sessionStorage`, so it also covers a navigation to another page of your site.
+- **Leaving the page.** Results go out with `keepalive`, so they arrive even when the page navigates straight after.
+  A tool that navigates should return first and leave after:
+
+  ```ts
+  execute({ path }) {
+    setTimeout(() => location.assign(path), 0); // navigate after the result is sent
+    return { navigating: path };
+  },
+  ```
+
+- **The script loaded twice, or two widgets.** The call still runs once.
+- **No time limit.** The agent waits for the result. While a tool runs, the chat shows Stop. If the visitor presses it,
+  or sends another message first, the call's `signal` aborts, its result is never sent, and its card reads
+  "Not completed". A stopped call never runs again, not even after a reload.
+
+When `sessionStorage` is blocked (some private modes), the note lives in memory, so a reload can't tell a call that
+ran from one that didn't; everything else works the same.
+
+## What the visitor sees
+
+A tool that runs on its own appears in the transcript only when the deployment shows tool calls
+(`behavior.showToolCalls`), with its input and result: "Running", then "Completed" or "Error" (the tool failed), or
+"Not completed" when the visitor stopped it or moved on, or a reload cut it short. A tool with `consequentialHint` always shows an approval card with the input; Reject tells
+the agent the visitor declined, and the function never runs.
+
+## Events
+
+Each call this page settles fires `toolResult` with `{ toolCallId, name, status, durationMs }`: `status` is
+`completed`, `failed`, `declined` (the visitor rejected it), `stopped` (the visitor pressed Stop) or `interrupted` (a
+reload cut it short). It never carries the input or the result.
+
+```ts
+chat.on('toolResult', ({ name, status, durationMs }) => analytics.track('help_ai_tool', { name, status, durationMs }));
+```
+
+## Security
+
+- Tools run with your page's full privileges, as code you wrote. Anyone can also call your functions from the
+  browser's developer tools, so a tool may do only what the visitor could do on the page themselves.
+- The agent chooses the input. Check it in `execute` as you would a form submission, and mark tools with real
+  consequences (payments, deletions, messages to other people) `consequentialHint: true`, or confirm in your own UI.
+- The definitions are sent with each message and the results are stored in the conversation, like any tool's result,
+  so never put secrets in a description or a result.
+
+## Testing
+
+`testing/page-tools-manual.md` walks through every case above in a real browser
+on the `dev/page-tools.html` playground, with a real model or the mock backend.
+
+## Troubleshooting
+
+- **The agent never uses the tool:** write the description as an instruction ("Use it whenever the visitor wants to
+  book a call"), and check the console for a "skipped a tool" warning.
+- **The chat waits after a tool:** the function never settled (a promise that doesn't resolve). Return, or throw.
+- **"This page doesn't offer … right now":** the call came after the tool was removed (a route change aborted its
+  signal), or the agent tried a tool this page doesn't register. Keep a tool registered while the agent may still use
+  it.
 
 ---
 
-<!-- https://cdn.help.ai/sdk/js/elements/1.10.0/docs/theming.md -->
+<!-- https://cdn.help.ai/sdk/js/elements/1.12.0/docs/theming.md -->
 
 # Theming & customization
 
@@ -4317,7 +4591,7 @@ init({
 
 ## Header actions
 
-See [Configuration § Header actions](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/configuration.md#header-actions)
+See [Configuration § Header actions](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/configuration.md#header-actions)
 for the full semantics. Quick customization examples:
 
 ### Minimal chrome
@@ -4524,7 +4798,7 @@ are for what tokens don't cover (shadows, corners, borders).
 
 For truly bespoke designs (e.g., replacing the launcher with your
 own component), use `launcher.hidden: true` + custom trigger, or a
-[no-script trigger](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/api-reference.md#no-script-triggers).
+[no-script trigger](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/api-reference.md#no-script-triggers).
 
 ---
 
@@ -4556,16 +4830,16 @@ can always override.
 
 ## Next
 
-- [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/events-and-hooks.md) — listening to chat
+- [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/events-and-hooks.md) — listening to chat
   interactions, integrating with analytics.
-- [Recipes](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/recipes.md) — copy-paste examples for common
+- [Recipes](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/recipes.md) — copy-paste examples for common
   customization scenarios.
-- [Configuration reference](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/configuration.md) — the full option
+- [Configuration reference](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/configuration.md) — the full option
   table.
 
 ---
 
-<!-- https://cdn.help.ai/sdk/js/elements/1.10.0/docs/recipes.md -->
+<!-- https://cdn.help.ai/sdk/js/elements/1.12.0/docs/recipes.md -->
 
 # Recipes
 
@@ -5289,13 +5563,13 @@ brand accent set in the dashboard.
 
 ## Next
 
-- [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/events-and-hooks.md) — full event API
-- [Configuration](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/configuration.md) — every option
-- [Troubleshooting](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/troubleshooting.md) — when things go wrong
+- [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/events-and-hooks.md) — full event API
+- [Configuration](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/configuration.md) — every option
+- [Troubleshooting](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/troubleshooting.md) — when things go wrong
 
 ---
 
-<!-- https://cdn.help.ai/sdk/js/elements/1.10.0/docs/analytics.md -->
+<!-- https://cdn.help.ai/sdk/js/elements/1.12.0/docs/analytics.md -->
 
 # Analytics integration
 
@@ -5327,8 +5601,13 @@ internal event bus, and you subscribe as many listeners as you want.
 <!-- 2. Load the widget -->
 <script src="https://cdn.help.ai/sdk/js/elements/latest/elements.js" data-public-key="agent_pk_..." data-ai-agent-deployment-id="01900000-0000-7000-8000-000000000000" defer></script>
 
-<!-- 3. Subscribe to every widget event with one wildcard hook -->
+<!-- 3. Subscribe to every widget event with one wildcard hook. The stub queues the call until the deferred script runs. -->
 <script>
+  window.HelpAI =
+    window.HelpAI ||
+    function () {
+      (HelpAI.q = HelpAI.q || []).push(arguments);
+    };
   HelpAI('hook', 'default', '*', (chat, event, payload) => {
     gtag('event', `chat_${event}`, flatten(payload));
   });
@@ -5351,7 +5630,7 @@ event.
 
 Every interactive action emits one event with a typed payload. Subscribe
 via `chat.on(name, fn)` (instance) or `HelpAI.hook(widgetId, name, fn)`
-(global, pre-boot-safe). Full schema in [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/events-and-hooks.md).
+(global, pre-boot-safe). Full schema in [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/events-and-hooks.md).
 
 | Category         | Event                 | Payload                                            |
 | ---------------- | --------------------- | -------------------------------------------------- |
@@ -5377,6 +5656,7 @@ via `chat.on(name, fn)` (instance) or `HelpAI.hook(widgetId, name, fn)`
 |                  | `soundToggle`         | `{ muted }`                                        |
 |                  | `sidebarToggle`       | `{ collapsed }` (page mode)                        |
 |                  | `calloutDismiss`      | `void`                                             |
+| **Your page**    | `hostEvent`           | `{ name, data? }` (from `chat.track()`)            |
 | **Lifecycle**    | `error`               | `unknown` (any unhandled error)                    |
 |                  | `handshake`           | `HandshakeResponse` (full handshake payload)       |
 |                  | `conversationRebound` | `{ previous, current }`                            |
@@ -5691,6 +5971,32 @@ chat.on('close', () => {
 
 ## Common patterns
 
+### Your own events (`chat.track`)
+
+Report what the visitor does on your site, outside the chat, with `chat.track(name, data)`:
+
+```ts
+chat.track('plan_viewed', { plan: 'pro' });
+chat.track('cart_updated', { items: 2, total: 48.5 });
+```
+
+Each call does two things:
+
+- **Analytics.** It sends one hit to help.ai's Elements analytics as a `hostEvent`, with your event name and data,
+  like the widget's own events. A deployment with tracking off (or a browser sending Global Privacy Control or Do
+  Not Track) sends nothing.
+- **The agent.** The widget keeps your last 10 events and sends them with the visitor's next message, as
+  `recentEvents` in the page context (`{ name, data?, secondsAgo }`, oldest first), so an answer can take into
+  account what the visitor just did: "I see you were looking at the Pro plan." Like the rest of the page context, the
+  agent treats them as information from your site, never as instructions. They live only in this page view.
+
+The name is 1–64 characters. The data is flat: strings, numbers and booleans (other values are left out), up to 256
+characters as JSON (longer data is not sent; the name still is). Nothing personal should go in either: use ids and
+plan names, not emails. `track()` also fires the `hostEvent` event, so your own listeners see it.
+
+Also `HelpAI('track', name, data)` with the script tag, `element.track(name, data)` on `<web-ai-chat>`, and
+`useHelpAI().track` in React.
+
 ### Identify the visitor
 
 The widget mints a stable anonymous `visitorId` on first load and
@@ -5844,14 +6150,14 @@ yourself — see the snippets above.
 
 ## See also
 
-- [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/events-and-hooks.md) — full event reference, payload shapes, pre-boot queue semantics
-- [API reference](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/api-reference.md) — `ChatWidgetInstance` shape
-- [Recipes](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/recipes.md) — other end-to-end snippets
-- [Security & privacy](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/security-privacy.md) — what data flows where
+- [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/events-and-hooks.md) — full event reference, payload shapes, pre-boot queue semantics
+- [API reference](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/api-reference.md) — `ChatWidgetInstance` shape
+- [Recipes](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/recipes.md) — other end-to-end snippets
+- [Security & privacy](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/security-privacy.md) — what data flows where
 
 ---
 
-<!-- https://cdn.help.ai/sdk/js/elements/1.10.0/docs/security-privacy.md -->
+<!-- https://cdn.help.ai/sdk/js/elements/1.12.0/docs/security-privacy.md -->
 
 # Security & privacy
 
@@ -6043,7 +6349,7 @@ unsent text values in addition to identity and UI state, so adapter code owns
 their storage destination, retention, and privacy behavior. Use cases include
 encrypted `localStorage`, `sessionStorage`, and in-memory consent fallbacks.
 
-[Recipes § Custom storage](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/recipes.md#custom-storage-adapter).
+[Recipes § Custom storage](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/recipes.md#custom-storage-adapter).
 
 ---
 
@@ -6342,10 +6648,13 @@ and anyone can base64url-decode it. Never put a secret in context.
 
 ### Key rotation
 
-- **public keys** — rotate from the dashboard. Old keys are deactivated
-  instantly; update your embeds.
-- **secret key** — user tokens signed with a replaced secret key stop verifying, so every verified user is signed out
-  until your server signs new ones with the new key.
+The dashboard has no key rotation today.
+
+- **public key** — public by design: it only names the deployment. Limit where it works with the deployment's
+  **Allowed websites**.
+- **secret key** — keep it on your server. If it leaks, create a new deployment (it gets new keys), move your embed
+  and your token signing to it, and delete the old one. User tokens signed with the old key stop verifying, so every
+  verified user is signed out until your server signs new ones.
 
 ---
 
@@ -6492,7 +6801,7 @@ We respond within 24 hours and coordinate disclosure on your schedule.
 
 ---
 
-<!-- https://cdn.help.ai/sdk/js/elements/1.10.0/docs/browser-support.md -->
+<!-- https://cdn.help.ai/sdk/js/elements/1.12.0/docs/browser-support.md -->
 
 # Browser support
 
@@ -6799,7 +7108,7 @@ with:
 
 ---
 
-<!-- https://cdn.help.ai/sdk/js/elements/1.10.0/docs/troubleshooting.md -->
+<!-- https://cdn.help.ai/sdk/js/elements/1.12.0/docs/troubleshooting.md -->
 
 # Troubleshooting
 
@@ -6895,7 +7204,7 @@ for (const k of Object.keys(localStorage)) {
 3. **Any CSP errors in the console?** — `"Refused to connect to
    https://help.ai/api/agent because it violates the following Content
    Security Policy…"` means you need to add `help.ai` to your
-   `connect-src`. See [Security § CSP](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/security-privacy.md#content-security-policy).
+   `connect-src`. See [Security § CSP](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/security-privacy.md#content-security-policy).
 
 ---
 
@@ -6978,7 +7287,7 @@ first.
 ### Symptom: widget ignores my CSS
 
 That's by design. The widget lives inside a shadow root — your page
-CSS can't reach inside. Use the [theming options](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/theming.md)
+CSS can't reach inside. Use the [theming options](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/theming.md)
 instead.
 
 For advanced customization, override CSS custom properties on the
@@ -7243,7 +7552,7 @@ font-src 'self' https:;
 media-src 'self' blob:;                      # For voice recording
 ```
 
-Full CSP guide: [Security § CSP](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/security-privacy.md#content-security-policy).
+Full CSP guide: [Security § CSP](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/security-privacy.md#content-security-policy).
 
 ---
 
@@ -7308,7 +7617,7 @@ provide `i18n.availableLocales` and include `language` in `header.actions`.
 
 ## Getting more help
 
-1. **Read the [FAQ](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/faq.md)** — most common questions answered
+1. **Read the [FAQ](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/faq.md)** — most common questions answered
    there.
 
 2. **Check our GitHub issues**: [github.com/help-ai/elements](https://github.com/help-ai/elements/issues).
@@ -7327,7 +7636,7 @@ provide `i18n.availableLocales` and include `language` in `header.actions`.
 
 ---
 
-<!-- https://cdn.help.ai/sdk/js/elements/1.10.0/docs/faq.md -->
+<!-- https://cdn.help.ai/sdk/js/elements/1.12.0/docs/faq.md -->
 
 # FAQ
 
@@ -7367,7 +7676,7 @@ own builds. Your public key gates the backend, not the frontend.
 ### What browsers are supported?
 
 Chrome/Edge 100+, Safari 15+, Firefox 100+, iOS Safari 15+. No IE11.
-See [Browser support](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/browser-support.md).
+See [Browser support](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/browser-support.md).
 
 ---
 
@@ -7386,11 +7695,11 @@ yourself) and serve it from your CDN. Point your `<script src>` at your hosted
 URL. Self-hosting is also what unlocks **chunked delivery** (only changed code
 re-downloads across releases) behind a single stable URL the customer never has
 to change — see
-[Caching, versioning & self-hosting](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/installation.md#caching-versioning--self-hosting).
+[Caching, versioning & self-hosting](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/installation.md#caching-versioning--self-hosting).
 
 ### Can I use this with a tag manager (GTM)?
 
-Yes. Use the async loader snippet ([Path B](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/installation.md#path-b--async-loader-snippet))
+Yes. Use the async loader snippet ([Path B](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/installation.md#path-b--async-loader-snippet))
 inside a Custom HTML tag. All `HelpAI(...)` calls queue until the
 bundle lands.
 
@@ -7398,7 +7707,7 @@ bundle lands.
 
 Yes — and there's an optional `presentation.iframe: true` flag that wraps the
 widget in its OWN iframe for extra isolation. See
-[Configuration § presentation.iframe](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/configuration.md#presentationiframe).
+[Configuration § presentation.iframe](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/configuration.md#presentationiframe).
 
 ### Does it work in shadow DOM?
 
@@ -7408,15 +7717,15 @@ custom element on your page). Everything just works.
 
 ### Does it work with React / Next.js?
 
-Yes. Full walkthrough: [Framework integrations § Next.js](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/frameworks.md#nextjs).
+Yes. Full walkthrough: [Framework integrations § Next.js](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/frameworks.md#nextjs).
 
 ### Does it work with Vue / Svelte / SolidJS / Angular?
 
-Yes. See [Framework integrations](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/frameworks.md).
+Yes. See [Framework integrations](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/frameworks.md).
 
 ### Does it work with WordPress / Shopify / Webflow / Squarespace?
 
-Yes. [Framework integrations § CMS](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/frameworks.md#wordpress).
+Yes. [Framework integrations § CMS](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/frameworks.md#wordpress).
 
 ---
 
@@ -7425,12 +7734,12 @@ Yes. [Framework integrations § CMS](https://cdn.help.ai/sdk/js/elements/1.10.0/
 ### Can I change the launcher icon?
 
 Yes. Pick from presets (`chat`, `spark`, `message`, `help`, `wand`)
-or pass raw SVG. See [Theming § Icons](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/theming.md#icons).
+or pass raw SVG. See [Theming § Icons](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/theming.md#icons).
 
 ### Can I match my brand colors?
 
 Yes. Set `theme.accent`, `theme.accentText`, `theme.radius`,
-`theme.fontFamily`. See [Theming § Colors](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/theming.md#color-overrides).
+`theme.fontFamily`. See [Theming § Colors](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/theming.md#color-overrides).
 
 ### Can I change the font?
 
@@ -7440,7 +7749,7 @@ respects any CSS font stack you provide.
 ### Can I hide the launcher and open the widget from my own button?
 
 Yes. Set `launcher: { hidden: true }`, then call `chat.open()` from
-your button's click handler. [Recipes § Custom launcher](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/recipes.md#custom-launcher-button).
+your button's click handler. [Recipes § Custom launcher](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/recipes.md#custom-launcher-button).
 
 ### Can I change the welcome message?
 
@@ -7449,24 +7758,24 @@ widget just renders what the backend sends.
 
 ### Can I override UI strings?
 
-Yes, per-locale or flat. See [Theming § Strings](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/theming.md#strings-overrides).
+Yes, per-locale or flat. See [Theming § Strings](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/theming.md#strings-overrides).
 
 ### Can I have multiple widgets on one page?
 
 Yes — with distinct `widgetId` values. Each gets its own chat
-thread, storage, and events. [Recipes § Multi-widget](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/recipes.md#multiple-widgets-on-one-page).
+thread, storage, and events. [Recipes § Multi-widget](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/recipes.md#multiple-widgets-on-one-page).
 
 ### Can I show the widget only on certain pages?
 
 Yes — just skip the `init()` call on pages where you don't want it.
 Or conditionally mount/unmount based on the URL.
-[Recipes § Conditional show](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/recipes.md#conditionally-show-based-on-url).
+[Recipes § Conditional show](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/recipes.md#conditionally-show-based-on-url).
 
 ### Can I use it in a specific language?
 
 Yes. Force via `i18n.locale: 'fr-CA'`. Let users switch via
 `i18n.availableLocales: ['en', 'fr', 'es']`. Full details: [Theming §
-Internationalization](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/theming.md#internationalization).
+Internationalization](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/theming.md#internationalization).
 
 ### Can I change the widget's position on mobile?
 
@@ -7503,7 +7812,7 @@ allowlisted event metadata through 1×1 pixel requests; it never sends message
 text or form values and can be disabled with `tracking.enabled: false`. GPC and
 DNT disable it automatically. No cookies or fingerprinting.
 
-Full breakdown: [Security & privacy § data collected](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/security-privacy.md#what-data-the-widget-collects).
+Full breakdown: [Security & privacy § data collected](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/security-privacy.md#what-data-the-widget-collects).
 
 ### Does the widget use cookies?
 
@@ -7523,7 +7832,7 @@ Help AI API + your deployment's configured model provider.
 It stores data about identified users (when you pass `user.id`) or
 anonymous visitors. Your DPA (Data Processing Agreement) with Help
 AI covers the processing terms. For consent management, see
-[Recipes § Gate behind consent](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/recipes.md#gate-the-widget-behind-consent).
+[Recipes § Gate behind consent](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/recipes.md#gate-the-widget-behind-consent).
 
 ### Can visitors delete their chat history?
 
@@ -7538,7 +7847,7 @@ Yes — pass a custom in-memory storage adapter. Adapter-managed identity,
 conversation, draft, preference, and UI state then evaporates on reload. The
 optional logger debug level is separate: calling `setDebug` persists
 `helpai.debug` directly in `localStorage` until the host clears it.
-[Recipes § Custom storage adapter](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/recipes.md#custom-storage-adapter).
+[Recipes § Custom storage adapter](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/recipes.md#custom-storage-adapter).
 
 ### Does the widget track visitors across sites?
 
@@ -7563,7 +7872,7 @@ init({
 not an auth credential. Browser public access uses the matching
 `publicKey` + `aiAgentDeploymentId` pair, or the deployment ID alone for
 intentional guest mode.
-See [Recipes § Logged-in user personalization](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/recipes.md#logged-in-user-personalization).
+See [Recipes § Logged-in user personalization](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/recipes.md#logged-in-user-personalization).
 
 ### How do I integrate with my analytics (GA / Segment / Mixpanel)?
 
@@ -7582,7 +7891,7 @@ One-line pre-boot hook forwards every event:
 </script>
 ```
 
-Full examples: [Recipes § Analytics forwarding](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/recipes.md#analytics-forwarding).
+Full examples: [Recipes § Analytics forwarding](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/recipes.md#analytics-forwarding).
 
 ### How do I capture errors in Sentry / Datadog?
 
@@ -7767,7 +8076,7 @@ table.
 
 ---
 
-<!-- https://cdn.help.ai/sdk/js/elements/1.10.0/docs/README.md -->
+<!-- https://cdn.help.ai/sdk/js/elements/1.12.0/docs/README.md -->
 
 # Help AI Elements — SDK Documentation
 
@@ -7796,7 +8105,7 @@ it → the panel opens → they can chat.
 Get the public key and deployment ID from [help.ai](https://help.ai) →
 **Dashboard → Deployments**.
 
-[**Continue with the quickstart →**](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/quickstart.md)
+[**Continue with the quickstart →**](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/quickstart.md)
 
 ---
 
@@ -7804,19 +8113,20 @@ Get the public key and deployment ID from [help.ai](https://help.ai) →
 
 | You want to…                                                | Read                                          |
 | ----------------------------------------------------------- | --------------------------------------------- |
-| Install the widget end-to-end                               | [**Quickstart**](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/quickstart.md)             |
-| See every install method (NPM, Web Component, React)        | [Installation](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/installation.md)             |
-| Customize every option                                      | [Configuration reference](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/configuration.md) |
-| Match my brand colors and typography                        | [Theming & customization](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/theming.md)       |
-| Send chat events to my analytics                            | [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/events-and-hooks.md)       |
-| Wire GA4 / Mixpanel / Segment / multi-provider              | [Analytics integration](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/analytics.md)       |
-| Integrate with Next.js / Vue / Svelte / WordPress / Shopify | [Framework integrations](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/frameworks.md)     |
-| Copy a working example                                      | [Recipes](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/recipes.md)                       |
-| Diagnose "why isn't this working"                           | [Troubleshooting](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/troubleshooting.md)       |
-| Quick answer to a common question                           | [FAQ](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/faq.md)                               |
-| Compact API reference for lookup                            | [API reference](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/api-reference.md)           |
-| Understand what data the widget sees                        | [Security & privacy](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/security-privacy.md)   |
-| Check browser compatibility                                 | [Browser support](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/browser-support.md)       |
+| Install the widget end-to-end                               | [**Quickstart**](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/quickstart.md)             |
+| See every install method (NPM, Web Component, React)        | [Installation](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/installation.md)             |
+| Customize every option                                      | [Configuration reference](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/configuration.md) |
+| Match my brand colors and typography                        | [Theming & customization](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/theming.md)       |
+| Send chat events to my analytics                            | [Events & hooks](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/events-and-hooks.md)       |
+| Wire GA4 / Mixpanel / Segment / multi-provider              | [Analytics integration](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/analytics.md)       |
+| Integrate with Next.js / Vue / Svelte / WordPress / Shopify | [Framework integrations](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/frameworks.md)     |
+| Copy a working example                                      | [Recipes](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/recipes.md)                       |
+| Let the AI agent act on my page                             | [Page tools](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/page-tools.md)                 |
+| Diagnose "why isn't this working"                           | [Troubleshooting](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/troubleshooting.md)       |
+| Quick answer to a common question                           | [FAQ](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/faq.md)                               |
+| Compact API reference for lookup                            | [API reference](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/api-reference.md)           |
+| Understand what data the widget sees                        | [Security & privacy](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/security-privacy.md)   |
+| Check browser compatibility                                 | [Browser support](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/browser-support.md)       |
 
 ---
 
@@ -7878,7 +8188,7 @@ Five ways to install. Pick whichever fits your site:
 | **ESM via CDN**          | Plain HTML, sandboxes, MDX — no build, no NPM install          | `import { mount } from 'https://cdn.jsdelivr.net/npm/@helpai/elements@<version>/elements.esm.js'` |
 
 All five use the same underlying library. Same options, same events,
-same behavior. Full comparison: [Installation](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/installation.md).
+same behavior. Full comparison: [Installation](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/installation.md).
 
 ---
 
@@ -7933,14 +8243,14 @@ fuller example showing the most common options in one place:
 </script>
 ```
 
-Every option explained in [Configuration](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/configuration.md). Every
-customization path in [Theming](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/theming.md).
+Every option explained in [Configuration](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/configuration.md). Every
+customization path in [Theming](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/theming.md).
 
 ---
 
 ## Support
 
-- **Questions?** [FAQ](https://cdn.help.ai/sdk/js/elements/1.10.0/docs/faq.md) — common answers first. [support@help.ai](mailto:support@help.ai) for anything else.
+- **Questions?** [FAQ](https://cdn.help.ai/sdk/js/elements/1.12.0/docs/faq.md) — common answers first. [support@help.ai](mailto:support@help.ai) for anything else.
 - **Found a bug?** File an issue at [github.com/help-ai/elements](https://github.com/help-ai/elements/issues).
 - **Need a feature?** Same place — we read every request.
 - **Status page:** [help.ai/status](https://help.ai/status).