# Paths

> Multi-step guided journeys — onboarding, learning modules, activation checklists, certification tracks.

Source: https://docs.hatched.live/docs/concepts/paths

A path is an ordered journey made of **steps** and **sub-steps**. Each step
unlocks once the previous one is complete; sub-steps inside a step finish
either automatically (rule-engine event) or manually (widget CTA / API).
Operators define one path per audience as the active default; users see it
through the [path widget](/docs/reference/widgets/path).

## Why paths exist

Coins, streaks, and badges reward isolated moments. Paths reward
**progress through a defined arc** — first-value onboarding, a five-lesson
unit, a seller activation checklist, a 30-day training plan, a certification
track. Instead of asking users to infer "what's next," the widget shows the
next concrete action and rewards completion in context.

## How they work

A path has three layers:

- **Definition** — label, audience, display mode, accent color, icon.
- **Steps** — ordered milestones. Each step has a label, optional
  description, optional `unlock_condition` override, optional
  `completion_condition`, and reward (coins + badge).
- **Sub-steps** — the actual work inside a step. Each sub-step finishes
  via a `completion_condition` (auto) or `allow_manual_complete=true`
  (manual CTA / public API). Optional `content_url` deep-links to the
  customer's app.

Default unlock semantics: step `n+1` unlocks when step `n` is fully
completed. Override per step with `unlock_condition` (e.g. "unlocks when
the user earns the `novice` badge") if you need non-linear gating.

Default sub-step semantics: `allow_manual_complete=true` with no
`completion_condition`. The widget shows a "Mark complete" CTA (if the
session token has `events:track` scope), and a `content_url` opens in a
new tab. Add an automation later if you want the rule engine to mark the
sub-step done off an event.

Step-level completion is optional. Add a step `completion_condition`
when one event should finish the whole milestone, such as
`event_count(module_finished) >= 1`. When it matches, Hatched marks every
unfinished sub-step in that step as complete in the same event tick,
applies each sub-step reward once, then applies the step reward. Leave
the step condition blank when each sub-step should complete from its own
event or manual CTA.

## Display modes

- **Straight column** (`display_mode: 'straight'`) — a readable vertical
  path with a continuous accent connector. Best for long ordered
  journeys where clarity matters.
- **Zigzag quest** (`display_mode: 'zigzag'`) — alternating nodes and
  labels, Duolingo-style. Best when the path should feel more playful.
- **Compact stepper** (`display_mode: 'stepper'`) — horizontal scrolling
  chips with the active step expanded inline. Best for short checklists,
  onboarding flows, or any place vertical real estate is tight.

The runtime renders the same data either way — toggle freely; users see
the change on next mount.

## Path icons

The definition `icon` is optional decoration next to the path label.
Allowed values are `path`, `flame`, `heart`, `bolt`, `star`, and `leaf`.
Use `path` for no icon. Existing unsupported icon values are normalized
to `path` by the path icon migration.

## Single active path per audience

Activating a path atomically deactivates every other path in the same
audience. There is one live path per audience at any time. Drafts stay
inactive until you flip the toggle from the dashboard.

## Example

> **buyer_onboarding path (audience: `seller`)** — three steps:
> 1. *Set up your storefront* — sub-step "Add your first product" (manual,
>    deep-links to `/products/new`).
> 2. *Stock your shop* — sub-step "Add five products" (auto, completes
>    when `event_count(product_added) ≥ 5`).
> 3. *Go live* — step completion condition
>    `event_count(storefront_submitted) ≥ 1`, then awards
>    `verified_seller` badge.

## How to set it up

1. Dashboard → Paths → **New path**.
2. Pick the audience (multi-audience customers only).
3. Add steps in order; expand each one to add sub-steps.
4. Default sub-step is manual — leave it that way unless you want
   automation. If one event should complete the whole step, add a step
   completion rule instead.
5. Live preview shows fresh / in-progress / completed states.
6. **Set active** when you're ready. Activating swaps in this path and
   deactivates whatever was previously live for this audience.
7. Embed the [path widget](/docs/reference/widgets/path) on the customer
   surface — the runtime resolves the active path automatically.

## Gotchas

- Audience is **immutable** after a path is created. Pick carefully on
  creation; if you need a different audience, clone the path.
- Manual completion needs a session token with `events:track` scope.
  Embed-token mounts (read-only) won't show the "Mark complete" CTA.
- Step completion rules cascade unfinished sub-steps and their rewards.
  Use them for true milestone events; use per-sub-step conditions when
  each task should award independently.
- Add at least one sub-step when using a step completion rule. The rule
  persists progress by marking unfinished sub-steps complete; an empty
  step has no completion record to update.
- A sub-step must keep either a `completion_condition` *or*
  `allow_manual_complete=true`. The API rejects sub-steps that drop both.
- Path definition icons are curated keys, not arbitrary emoji or image
  URLs. Use one of `path`, `flame`, `heart`, `bolt`, `star`, or `leaf`.
- Per-buddy completion state is bound to the path definition. Deleting a
  path removes its completion records — there is no recovery.

## Related

- [Badges](/docs/concepts/badges) — step rewards are usually a badge.
- [Streaks](/docs/concepts/streaks) — habit loops that run alongside a path.
- [Send events](/docs/guides/send-events) — events drive automatic sub-step completion.
- [Path widget](/docs/reference/widgets/path) — rendering the active path.