> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.rydhm.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.rydhm.ai/_mcp/server.

# Onboarding coach

The Onboarding coach is an expert that lives in your product, not on your marketing site. Your users click its bubble and ask, out loud or typed, "how do I invite my team?". The coach knows which page they're on, answers from what you taught it, and **shows** them: it outlines the Invite button, scrolls to it, and clicks it or fills a field when they ask it to.

**Talk or type.** The bubble has a **Talk** / **Type** switch. A typed conversation needs no microphone and makes no sound, for people in an open office or on a phone without headphones, and the coach does everything it does by voice. The bubble remembers each person's choice; voice is the default. The expert's widget setting **Visitors can** (talk or type, talk only, type only) decides which are offered.

It can also:

* **Run guides**: short step-by-step walkthroughs ("Set up billing", "Invite your team") that it offers at the right moment and keeps track of per person.
* **Announce what's new**: a small card above the bubble ("We launched dark mode. Want me to show you?") whose button starts a guide.
* **Report what happened**: who used it, which guides people finish, where they drop off, and which buttons it couldn't find. See [Onboarding analytics](/engine/onboarding-analytics).

> **Note**
>
> Every step on this page can also be done with the API or the server SDKs, for example to keep guides and the page map in your own code: see [Set up with code](/engine/onboarding-coach-code).

## Set it up without code

#### Build the coach

Go to **Experts** → **New expert** and choose **Onboarding coach** (`kind: "onboarding"` in the API). One form makes the whole coach:

* **Where should the coach appear?**: your app's address, such as `app.example.com`. Required.
* **Your website or help center**: where it reads about your product. Optional.
* **What should new users do first?**: in your own words, such as "Create their first project, then invite a teammate". Optional.

Select **Build my coach**. Rydhm reads your website (**Reading your website**, **Writing what your coach knows**, **Drafting guides**, **Ready**), writes the coach's name, instructions and first message, imports your website and help center into its [knowledge](/knowledge/overview) and, when you gave goals, drafts up to 3 guides, switched off for you to review. It also makes the coach's **website key** (`rydhm_pk_live_…`) for your app's address, and for `http://localhost` while **Also allow localhost for testing** is ticked. Knowledge keeps filling in after **Ready**; the coach works meanwhile.

The coach opens on its **Setup** tab, a four-step checklist. Its other tabs are **Knowledge**, **Guides**, **Insights** and **Settings**.

#### Learned your app

Step 1 shows what the coach knows: its knowledge, the screens of your app it has learned, and your goals (**What should new users do first?**, saved with **Save goals**). The coach steers new people towards those goals in the conversation, with no guide needed. See [How it learns your app](#how-it-learns-your-app).

#### Put it on your site

Step 2 shows the websites the key **Works on** and **Your tag**: the one line to paste just before `</body>` on every page of your app. The tag never changes. It looks like this:

```html
<script src="https://staging.rydhm.ai/engine.js" data-key="rydhm_pk_live_…" async></script>
```

**Where to paste it** has the steps for HTML, React / Next.js, WordPress, Webflow, Shopify, Wix, Squarespace, Framer and Google Tag Manager. To hand it off, use **Copy a prompt for your AI coding tool** or **Email it to your developer**. **Is it there?** says when a page with the tag has loaded the coach, and on which site.

The key works only on the websites it lists: a page on any other site is refused, and a key with no websites refuses every browser. Add a staging host, or edit and revoke keys, in **Settings** → **Website keys**.

#### Try it

**Talk to it here** opens the test panel in Rydhm. **Try it on your own site** is a bookmarklet: drag it to your bookmarks bar, open your app and click the bookmark, and the coach loads on that page with nothing deployed. It works on the key's websites only.

#### Turn it on

A new coach is in **test mode**: **Who sees your coach** is **Only me (testing)**. With the tag on your live app, the coach shows only in a browser you open with **Preview on my site** (the link lasts 7 days) or with a teach link; everyone else sees nothing. Choose **Everyone** when it's ready.

The step also checks whether the coach is ready to go live: **Knows your product**, **Knows your screens**, **Guides work**, and **You tried it**, plus two optional ones: **Nothing needs you** (what needs a person in **Insights**, the same count as its badge; the coach fixes what it can by itself) and **Checked on your app** (a run of the Explorer, a command-line check that tries the coach on your app; it isn't packaged for customers yet during early access). Choosing **Everyone** while a required check fails asks you to confirm and lists what is missing; it never stops you.

The switch below turns the coach on or off. While it's off, nobody sees it, even with the tag on your site, and preview and teach links don't work either.

> **Warning**
>
> **A new coach shows only to you until you choose Everyone.** If you paste the tag and see no bubble, open your app with **Preview on my site** (step 4), or set **Who sees your coach** to **Everyone**. A copy of a coach starts in test mode too.

> **Note**
>
> **Rydhm is in early access.** The script is served by the Rydhm app, so its address follows the app: `https://staging.rydhm.ai/engine.js` today, and `https://app.rydhm.ai/engine.js` at launch. The **Setup** tab always shows the right one.

### Two files, and your Content Security Policy

`engine.js` is a small loader (about 58 KB gzipped): it draws the bubble, runs guides and announcements, and costs nothing until someone talks or types. The first time a conversation starts, it loads a second file, `engine-livekit.js` (the connection, about 200 KB gzipped), from the **same directory**. If your site sends a Content Security Policy, allow both: add the script's origin (`https://staging.rydhm.ai`, later `https://app.rydhm.ai`) to `script-src`. See [Browser support, size and CSP](/developers/sdk-web#browser-support-size-and-csp) for the full list.

To host the files yourself, put both in one folder and point the tag at it; or set `data-livekit-src` to where `engine-livekit.js` lives.

### Options on the script tag

Every option has a `data-*` form, so you can change the bubble without writing JavaScript:

| Attribute                                          | What it does                                                                     |
| -------------------------------------------------- | -------------------------------------------------------------------------------- |
| `data-key`                                         | Your publishable key. Required.                                                  |
| `data-position`                                    | `bottom-right` (default) or `bottom-left`.                                       |
| `data-theme`                                       | `auto` (follows the user's system), `light` or `dark`.                           |
| `data-accent`                                      | The bubble's colour, such as `#0f766e`.                                          |
| `data-language`                                    | The language the coach speaks, such as `hi`.                                     |
| `data-ui="none"`                                   | Draw nothing: your developers build their own button and captions.               |
| `data-user-id`, `data-user-hash`, `data-user-name` | Who the user is. See [Signed users](/engine/onboarding-coach-code#signed-users). |
| `data-api-url`                                     | The API address, such as `https://api-staging.rydhm.ai` while in early access.   |

## How it learns your app

The coach learns about your product from its [knowledge](/knowledge/overview): the website and help center it read when you built it, and anything you add. It learns **where things are** (your screens, menus and buttons) from inside your app, because its script runs in each signed-in person's own browser. Nothing has to crawl your dashboard.

* **By itself.** Each page the coach shows on teaches it that page's headings, menus, tabs and buttons: names only, never what people type, never records' contents. That is the coach's **app map**, which it uses to take people to the right page and point at the right button, even from another page. See it in **Settings** → **App map** (**What your coach learned about your app**), switch **Learn from the pages it's on** off, or forget what it learned.
* **Teach mode.** **Teach it your app** (Setup, step 1) opens your app with a short-lived link (30 minutes). Click through your main screens for two minutes, then press **Done** in the teaching bar. It starts at the bottom of the page, away from your navigation and the coach's launcher; if it's in the way, drag it by its grip (or use the arrow keys) to move it, double-click the grip to put it back, or minimise it to a small "3 learned" pill while you click around. The coach learns each screen and its own words (headings, short help text, empty-state copy; never tables of records or field values) and writes them up as a knowledge document named after your app ("Inside Acme"), which you can read and remove.
* **`data-rydhm-private`** on any element keeps it, and everything inside it, out of what the coach learns and sees.

### Your own names (optional)

The coach finds most things by itself, by their visible words. To give a button or field a fixed place, or a name your guides can point at, add it under **Settings** → **App map** → **Your own names**:

| Field        | Example              | What it's for                                                                        |
| ------------ | -------------------- | ------------------------------------------------------------------------------------ |
| **Name**     | Invite button        | What guides and the coach call it. Unique per expert.                                |
| **Page**     | `/settings/team`     | Where it lives. `*` is any page; `/settings/*` is every settings page.               |
| **Selector** | `[data-test=invite]` | How a developer would find it (a CSS selector). Optional.                            |
| **Text**     | Invite               | The words on it. Used when there's no selector, or when the selector stops matching. |

You need a name and at least one of selector or text. Your own names stay when you forget what the coach learned, and they make it reliable when your design changes. In the API they are the expert's page map (`/v1/agents/{id}/page-targets`).

Each entry shows its **health**: **OK** (the SDK found it recently), **Missing** (someone's browser couldn't find it: the button moved or was renamed) or **Unseen** (no report yet). Fix missing entries by updating their selector or text.

## Guides

Guides are optional: with goals set (Setup, step 1), the coach already steers people where you want them. A guide is a short, measured walkthrough the coach takes a person through. Add guides in the coach's **Guides** tab, and drag them to change their order. **Write with AI** drafts one from a sentence ("Show them how to invite a teammate"), using what the coach knows about your screens; the draft is switched off until you review it.

| Part                      | What it is                                                                                                                                                                                                                         |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name**                  | "Invite your team".                                                                                                                                                                                                                |
| **Nudge**                 | The one line shown before it starts: "Want me to show you how to invite your team?". Voice starts only when the person says yes.                                                                                                   |
| **When it offers itself** | **Only when started** (by an announcement, your app or the coach), **First visit**, **On a page** (a path such as `/settings/*`), **After an event** your app sends, or **When stuck** (after some seconds on one page, 5 to 600). |
| **Who sees it**           | Everyone, or only people with certain traits or plans, or who have (or haven't) done something.                                                                                                                                    |
| **Steps**                 | Each with a title, what the coach should show and say, the page it happens on, an optional page-map target to point at, and what counts as done.                                                                                   |

A step is done when:

* **The user reaches a page** (a path pattern),
* **clicks a page-map target**,
* **your app sends an event** (such as `invite_sent`),
* **a tool answers successfully**, or
* **manually**: the person says they did it.

Each guide is offered at most 3 times, 12 hours apart, and never again after the person dismisses or finishes it. Progress is kept per person, so a guide picks up where they left off, on any device when users are [signed](/engine/onboarding-coach-code#signed-users).

## Announcements

An announcement is a small card above the bubble: a title, a line of text and a button ("Show me"). The button can start a guide. Add them in the coach's **Guides** tab, switched to **Announcements**, with:

* **When**: a start date and an optional end date.
* **Who**: everyone, or an audience, the same rules as guides.
* **How often**: by default each person sees it at most 3 times, 24 hours apart, and never again once they click or dismiss it.

## Daily caps and a bot check

A website key sits in your page for anyone to read, so each key has **daily caps** on what it can start, counted per UTC day. They protect your credits from a script that copies the key:

| Plan       | Conversations a key can start a day | Voice minutes a key can use a day |
| ---------- | ----------------------------------- | --------------------------------- |
| Free       | 200                                 | 300                               |
| Starter    | 1,000                               | 2,000                             |
| Growth     | 3,000                               | 6,000                             |
| Scale      | 10,000                              | 20,000                            |
| Enterprise | No cap                              | No cap                            |

When a cap is reached, new conversations are refused until the next UTC midnight (`daily_session_cap`), or voice is (`daily_voice_minutes_cap`; typing still works). The [browser SDK](/developers/sdk-web#error-codes) reports these as errors with `retryAt`. Conversations already running are never cut.

A workspace can also ask for a **bot check** ([Cloudflare Turnstile](https://www.cloudflare.com/products/turnstile/)) before each conversation starts. When it's on, the SDK uses Turnstile from your page (`window.turnstile`, never bundled by Rydhm) or your own `getBotToken` function, and a start without a valid token is refused (`bot_check_required`, `bot_check_failed`).

There's no screen for these settings yet. A workspace admin sets the bot check's Turnstile secret, or caps of the workspace's own (up to 1,000,000), from a signed-in session with `PUT /v1/workspace/engine-protection`; API keys can't change them.

## What it costs

A voice conversation with the coach is billed as a web call, \$0.10 a minute. A typed conversation is billed like chat, by the tokens the expert reads and writes, never by the minute. Loading the bubble, guides and announcements costs nothing. See [Billing](/workspace/billing).

## Related

* [Set up with code](/engine/onboarding-coach-code)
* [Client tools and safety](/engine/client-tools)
* [Onboarding analytics](/engine/onboarding-analytics)
* [Browser SDK reference](/developers/sdk-web)