> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thread.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Motions overview
> A Motion is a versioned, stage-based program you assign accounts to — each stage runs plays and tracks milestones, and stage advances are always proposed to a human.
A **Motion** is a staged program you assign accounts to: onboarding, activation, a rollout, an expansion play. Each stage owns two things — the **plays** that do the work (mostly agents) and the **milestones** that tell you whether the work landed. Accounts move through the stages one at a time, and the Motion holds the goal, the context, and the gate for each step of the way.
You author Motions at **Motions** in the app sidebar.
Motions authoring is visible to org admins only. Members see the results — proposed advances, approvals, and wins — in the [Inbox](/inbox/overview).
## The anatomy of a Motion
**Stages** are the phases of the program, in order — for example Handoff → Activation → Adoption → Value. Each stage has a display name, a description, and an ideal timeline (a day range), so everyone can see whether an account is on pace.
**Plays** are the units of work a stage runs. Most plays are **agents** — AI workers with a goal, a set of tools, and per-action approval rules (see [Agents in Motions](/motions/agents)). A play can also be a **workflow** (a multi-step routing process — see [Workflows](/workflows/overview)) or an **inline prompt** (a single AI call). Each stage has two slots:
* **On entry** — plays that fire once, the moment an account enters the stage (send the welcome email, spin up the kickoff doc).
* **While in stage** — plays that run continuously for as long as the account is in the stage (watch for stalls, verify milestones, keep the customer moving).
**Milestones** are plain-English customer outcomes attached to each stage — "Sending domain authenticated", "First message sent". Each is confirmed either by an agent reading your connected tools or by a human marking it. Milestones flagged **Required to advance** are the stage gate. See [Milestones and verification](/motions/milestones-and-verification).
## Versioning: pinned on entry
Motions are versioned. Publishing a Motion freezes that version — edits always go into a new draft version, and publishing the draft creates the next version.
The rule that matters: **an account is pinned to the version it entered on.** When you publish v4 while accounts are mid-flight on v3, Thread tells you exactly what will happen before you confirm:
> 187 accounts on v3 will continue running against v3. New accounts will be assigned to v4.
Mid-Motion accounts are never silently migrated. You can change the program with confidence that nothing already in flight shifts under an account partway through.
## How accounts enter a Motion
* **From a workflow** — an *Assign to Motion* step at the end of a routing workflow assigns the account to the newest published version automatically (a deal closes in your CRM, the workflow routes it, the Motion begins). See [Workflows](/workflows/overview).
* **Manually** — from an account's page, assign it to any published Motion. An account with no Motion is a normal state, not an error.
## Stage advances are proposed, never automatic
As an account works through a stage, agents confirm milestones against your connected systems and humans mark the manual ones. When every **required** milestone on the current stage is confirmed, the runtime **proposes** the advance to a human — it never advances an account on its own:
1. The account's stage panel shows the gate filling in ("3 of 4 required met") with the advance button disabled until the gate is satisfied.
2. When the gate is met, an item lands in the [Inbox](/inbox/overview): the account is ready to advance and needs review.
3. A person clicks **Advance to \[next stage]** (or **Complete motion** on the final stage) and confirms. Only then does the account move, and the next stage's on-entry plays fire.
This is deliberate. Agents gather the evidence; a human makes the call that a customer has genuinely moved forward.
## When to use a Motion vs a guide
Thread has two ways to put AI to work on an account, and they compose rather than compete:
| | **Guide** | **Motion** |
| -------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| Shape | One resident agent on one account | A staged program many accounts move through |
| Best for | A single concrete outcome — finish onboarding setup, adopt one feature, complete one task | A whole lifecycle phase — onboarding end to end, a rollout, a renewal program |
| Work | The guide texts, emails, and calls the customer itself | Each stage runs its own plays: agents, emails, workflows |
| Progress | The outcome funnel: enrolled → reached → engaged → verifying → done | Stages, with required milestones gating each advance |
Rule of thumb: if you can state the goal in one sentence and one agent could own it, [build a guide](/guides/overview). If the program has phases — where what runs in week one differs from what runs in month two, and each phase has its own definition of done — build a Motion.
## Get started
Draft a complete Motion with AI from your existing process docs, then review and publish.
How outcomes get confirmed — by agents against your systems, or by a human.
The Motion email editor: documents, AI prompt slots, previews, and the audit trail.
The Agent Templates catalog, per-action autonomy, and the save → publish → promote lifecycle.