# Writing a journey

> Journeys · Steps, triggers, and how the assistant knows a step is finished.

A journey has a **name** (what the assistant calls it out loud), a **trigger sentence**, and its **steps** in order. You write it on the Journeys page; a coding agent connected over MCP can also draft one for you — a draft never runs until you publish it.

## The trigger sentence

The trigger is compared against **what the visitor typed**, so write a sentence, not a menu label: *"when the visitor wants to return or send back something they bought"*. A noun phrase like "Returns" matches almost nothing.

## How a step ends

Every step says how we know it finished. This is a closed list — there is no free-text condition, because a condition the engine cannot check is a condition that silently never fires.

| Ends when | Needs |
| --- | --- |
| `click_self` | The step's own target was clicked. |
| `visible` / `hidden` | A target element appears or disappears. |
| `filled` | A target field has a value. |
| `url_change` | The address changes to something you name. |
| `settled` | A target stops changing. |
| `attempts` | A number of tries. |
| `user_continue` | The visitor presses Continue. Required for hold steps. |

> **Rule:** **A step that opens a page must end on something the page can show.** Opening a page tears the script down and rebuilds it on the new page, so an event that was going to happen — a click — can never arrive: the step would open the page again on every load. The editor therefore offers only `url_change`, `visible` and `filled` for an "open a page" step, and the server refuses a plan that says otherwise. The engine also stops a step after two navigations, so a wrong plan can never leave your site reloading.

One more thing the engine does on your behalf: it **waits** for a step's target to appear (a few seconds, checking continuously) before deciding it is missing. A page that renders its form a moment after loading is normal, and it should not stop a journey.

## Publishing

What gets published is a **specific version**. Editing a published journey takes it back offline, so a plan that nobody approved can never be running on your site. Read the steps, then publish again.

> **Tip:** Most of the work in a journey is naming the right elements on your page. A step's target has to match **exactly one** element — `#country-select` or `select[aria-label="Passport"]` are both fine if only one thing on the page answers to them, while a bare `button` is refused: a reference that could mean forty things is not a pointer. If you have a coding agent connected (see **Coding agents**), it can read your pages and draft the steps — you review and publish.

---

Read this page on the web: [Writing a journey](/docs/journeys/writing-a-journey)
