How it works

The pieces

Matching versus generating

When a walkthrough starts by project key, the backend just returns that flow. When it starts from a free-form goal, the backend runs a small pipeline of agents:

• Plannerturns "set up billing and invite my team" into smaller intents. Simple goals skip this and pass straight through.
• Matcher searches your published flows by exact key, fuzzy text, and meaning. A confident hit is returned as-is.
• Generator runs only when nothing matched. It assembles steps from your vocabulary and never invents selectors, so with no vocabulary it returns nothing.

Rendering a step

The SDK takes the returned steps and, for each one:

• resolves the selector against the live DOM, retrying briefly because single-page apps render late, and falling back to the step's fallback selectors if the primary misses
• draws the cursor and a highlight ring on the element, and a card with the instruction
• waits for the user to do the action, then advances
• if a selector cannot be found at all, it emits a drift signal so you learn the flow needs attention, and shows the step as text

The learning loop

Walkthroughs degrade when your app changes underneath them. The backend closes that loop on its own:

Quality scoring runs alongside this. Session outcomes (completions, wrong clicks, abandons) roll up per flow, and a sharp drop raises an explained alert so you know which walkthrough regressed and likely why.

Published SDK versus the runtime build

The docs note in a few places that some features belong to a v1 runtime build rather than the package on npm today. The short version:

• Published nudge-sdk is the self-contained bundle. It renders walkthroughs, themes, records via the authoring button, and emits events. This is what you install.
• The v1 runtime splits into a tiny npm loader plus a CDN-hosted runtime, and adds presets, render slots, headless mode, and passive capture. It is not published yet because it depends on a deployed CDN runtime.