# Funnel Journey — which box of the sales flowchart a lead is in

**Read-only AI invitation guard (2026-10-25):** `FunnelJourney::hasWonInFunnel()` lets shared funnel AI calls/redials respect a confirmed `STATUS_WON` for that lead and funnel. It does not treat an intermediate payment or another funnel's win as global suppression, reopen a journey, or finish human work. See [PDF acceptance](/docs/modules_handbook/shared/voice-agent/yunke-pdf-acceptance.md).

Historical Zoom webinars can now be [assigned to a Funnel / Slot as completed Sessions](../../zoom/legacy-webinar-sessions.md) from Recordings → Webinars, or in bulk from a reviewed plan with `zoom:import-legacy-webinars` (which also takes webinars without a recording). Their matched attendance enters the existing Journey counts without replaying automation.

**Nav:** no page of its own. It shows as the **Journey** column on Manage → Leads, the **Sales → Journey**
sub-tab on a lead (page and modal), a **"Sales flow"** tag on the tasks it hands out in
[My Work](/docs/modules_handbook/manage/my-work/readMe.md), and a **"Sales flow"** choice on the funnel form
(Events → Funnels → Edit).

> **2026-10-14 — the lead's Sales → Journey sub-tab is back, redesigned** (hidden 2026-10-12 as too hard to read).
> It now answers which stage / box the customer is in, who handles them, the next step with one-click
> **Pending / Done**, what happened and what we know — all from one prop, `journeyOverview`. The old per-funnel cards
> and the flow chart sit collapsed under *Automation details* at its bottom. `JOURNEY_TAB_HIDDEN` in
> `resources/js/composables/useLeadTabs.js` is `false` (still a switch: `true` hides the tab and `remapLeadTabs()`
> sends `stab=journey` links to the Sales strip's default). The lead PAGE's sales-flow bar stays hidden on its own
> flag, `SALES_FLOW_BAR_HIDDEN` — the stage cards carry the same stages; ⚠️ the lead MODAL's bar still follows the
> tab and shows again. Full description: the *Journey tab* bullet in the [Leads handbook](/docs/modules_handbook/manage/leads/readMe.md).

> **Not** the AI Copilot's *Customer Journey* (`lead_journey_updates`, `Src\Lead\Services\CustomerJourney`),
> **not** the *Revenue Journey* module (`Src\RevenueJourney`, commands `journey:*`) and **not** the member's
> learning road (`src/Journey`). Four things share the word; this one is always called the **funnel journey**
> in code (`funnel_journeys`, `Src\Lead\Journey\`, `funnel-journey:advance`).

The shared readiness integration is documented in
[Journey and readiness](/docs/modules_handbook/manage/leads/funnel-journey/readiness.md):
seven parallel evidence areas, shared financial preparation, and the Project-fee handoff to
Sales Projects. It preserves the existing attendance qualification and duration bands.

> **Owner rules of 2026-10-08 — read before changing behaviour.**
>
> - **Human contact is mandatory.** Every answered AI call is handed to a colleague, useful answers or not
>   (`HandOffAfterAiCall`); AI answers prepare the conversation, they never complete it. Attendance, payment or a
>   later registration never close an unfinished contact task. This supersedes the old "useful → no task" default.
>   **One exception of timing, not of the rule (owner, 2026-10-16):** when the slot's AI-call rule picks AI 2 Rounds'
>   round-1 profile, an answered round 1 does NOT hand off at once — the colleague's call waits for round 2's agreed
>   time, at most the usual `handoff_hours` (see *AI 2 Rounds as the AI call* below).
> - **D1 — the three image stages** (1 Registration → Preview webinar · 2 After Preview → Project webinar · 3 After
>   Project webinar → Closing) band the charts and My Work. They are a presentation of the boards; they are **not**
>   `FunnelJourney::flowStage()`, which is a journey's own position and only routes DATA points (§4c).
> - **D2 — a colleague's registration starts no automation.** The agreed-Session form, From Preview (§3e), admin
>   add and CSV import: no AI call, no M2, no Project journey opened at registration, no automatic task. Only a
>   landing-page registration runs the boxes before the webinar; everyone else waits in the R1 (`webinar`) box and
>   is not human work.
> - **D3–D5 — recording a contact** on any human box, the 30-day re-contact window, service steps a contact never
>   completes, the Stage 3 closing decision and who may record: one home,
>   [Pending / Done](/docs/modules_handbook/shared/sales-flow-chart/record-contact.md).
> - The live charts (company and the funnel's Journey tab) are the
>   [Sales flow chart](/docs/modules_handbook/shared/sales-flow-chart/readMe.md).

## What it does

The owner's flowchart (`storage/app/workflow/PropertyLab Flow.html`, git-ignored — the three images are screenshots of
it; the original spec text is in `docs/temp/7-10-temp/07-owner-flowchart-original.md`) is a per-person state machine:
registration → welcome → AI call → *answered / missed* → missed-call message → *clicked?* → a colleague calls →
reminders → webinar → *attended?* → *paid?* → closer → booked / lost.

The automation already did every one of those steps. What nothing did was **remember where each person
stood** — so nobody could be handed the people the machine dropped. The funnel journey is that memory:

- **One row per (lead, funnel)** says which box the person is in, since when, and who owns it.
- **An append-only log** says how they got there.
- **A scanner** applies the time-outs ("no click for six hours → a colleague calls").
- **A hand-off** turns a box into a real task for a real person, in My Work.

It records and hands out; it never sends anything to a customer.

## A funnel must be switched on

`event_funnels.journey_kind` — the **Sales flow** choice on the funnel form:

| Value | Meaning | What counts as "Paid?" |
|---|---|---|
| *(blank)* | **Not tracked.** No journey rows, no tasks. Every funnel starts here. | — |
| `1` Preview webinar | registration → AI call → webinar → membership | **any membership** payment |
| `2` Project webinar | webinar → project fee → 1-1 sales Zoom → Booked | a **project fee** (a course never counts) |

Only webinar funnels can have one (a Video Sales Letter has no webinar; the controller forces blank).
A journey's own stage number is derived (`FunnelJourney::flowStage()`): Preview before its webinar = 1, after = 2;
Project before = 2, after = 3. It routes DATA points (`FunnelJourneyAnswer::pointFor()`) and the chip's
`flow_stage`. The charts and My Work band their boxes by the owner's **image stage** instead (which chart a box sits
on — `MyWorkResponsibilities::QUEUES`, `jstage`): the two agree for journey work, but the bands also hold work no
journey has (invitations, paid service, Stage 3 opportunities), so never compute one from the other.

⚠️ `FUNNEL_JOURNEY_ENABLED` (default on) is the master switch, but **on is not enough** — a funnel with a blank
Sales flow records nothing. After deploying, set the Preview funnel to *Preview webinar* and the Project funnel
to *Project webinar* on their forms.

Two more per-funnel settings appear once a Sales flow is chosen:

- **How long a silent lead waits** — `event_funnels.handoff_hours` (the form's "客户没反应多久后，交给同事打电话"),
  blank = the default six hours. `FunnelJourney::handoffHours()` is the one reader. The "three hours before the
  webinar" cutoff stays global.
- **No caller queue of its own (2026-10-05).** Who is given each new lead is the **company round robin** on
  Setting → Lead Distribution → **Round Robin** — one list for every funnel and every source. The funnel page
  header shows a **Round robin** box that links there. See *Round robin at registration* below.

## How it works

### Journey overview layout

The funnel's **Journey** tab is the shared [Sales flow chart](/docs/modules_handbook/shared/sales-flow-chart/readMe.md)
workspace (`JourneyBoardTab` → `FunnelJourneyWorkspace` → `SalesJourneyWorkspace`): the owner's flowchart images with
this funnel's counts on every box (a Preview funnel shows image stages 1 and 2, a Project funnel 2 and 3; the stage
it does not feed links to the company flow), then the customer roster for a clicked count. The first paint is counts
only; a count loads its roster (`jnode`) — a `jnode` that is no node or reference of the board (a typo, a retired key)
stays counts only (2026-10-13; it used to list everyone). There is no separate "Detailed workflow" view any more — the AI / WhatsApp
branches are boxes of the chart itself.

### Stage 2 and the whole-company chart — 2026-10-08

The Project funnel's board feeds image stages 2 and 3 of the
[shared Sales flow chart](/docs/modules_handbook/shared/sales-flow-chart/readMe.md); My Work's live tab joins the
selected Project funnel (`jproject`) to its configured Preview source and the company Closing board.

`ProjectJourneyBoard` includes source-Ready customers, actual Project Session
registrants, funnel acquisition records, tracked journeys and event-attributed
Project purchasers, deduplicated
by Lead. Internal staff and deleted leads are excluded. Source readiness uses the
same actual attendance rule as Stage 1. Direct Stage 2 registrants do not need a
Preview attendance record. The source-ready, ready-and-registered and other-
registered cards are reference cohorts with their own rosters, not additive
current-position counts.

Default scope is all time. Session filters select a registration cohort; date
filters select Lead creation dates — whole days compared in the app timezone, the
timezone `leads.created_at` is stored in (before 2026-10-13 the bounds were converted
to UTC, which moved the window 8 hours earlier). Attendance and payments still read all valid
Sessions across this funnel's Slots. Owner falls back from Journey owner to the
Lead's assigned admin. All counts and rosters use `LeadVisibility`.

Positions are per **customer × Project context** (`ProjectJourneyContexts`, the latest visit per Slot and
Project). Each context resolves, first match wins: an attributed active Project fee → `paid` (Stage 2 ends; the
deal's REP, Zoom and closing are the [Closing board](/docs/modules_handbook/shared/sales-flow-chart/closing.md)'s) →
fee paid through another funnel, or a fee with no reliable mapping → `review` → a deal Booked / Converted without
such a fee → `won` (Stage 3's Won box; owner, 2026-10-13 — it was `review`) → a recorded **Not closed** contact (D4b)
or a **Lost** deal → `lost` with its reason → every deal ended with a **Swing** → `swung` (beside Not closed, never in
it; owner, 2026-10-13 — it was `lost`) → a stopped / lost journey → `lost` → the
journey is With a colleague before the webinar → `human` → attended → `attended` → no-show → `no_show` → an
after-webinar hand-off with no attendance verdict (residual) → `human` → an upcoming Session whose
reminders were muted → `review` → an upcoming Session: the automation box (`welcome` / `ai`) for a **landing**
registration, else `webinar` (D2) → `review`. The customer's summary node is the highest of `paid · won · human ·
attended · no_show · eligible · welcome · ai · webinar · lost · swung · review`; the old `rep` / `zoom` / `booked`
nodes are gone. A `won` or `swung` context's item is **done** (badged "Won" / "Moved to another project"). A
later no-show cannot erase earlier attendance; a historical `paid_at` alone does not count an active fee after a
refund. A `paid` context's roster item is **done**, badged "In Stage 3", with no Pending / Done — only the
**Continue in Stage 3** link (`JourneyWorkQueue::stateForFact()`; before 2026-10-13 it read "To do" with no button).
The `lost` reason from a contact is the context's **newest outcome that carries a closing decision** across the three
closing queues: a later explicit "Still following up" reopens it, a later No answer never hides it
(`ProjectJourneyContexts::notClosed()`).

Payments must be for `Src\Property\Project`. Explicit `event_id` must name a
Session of this funnel — a **cancelled** Session included (cancelling a Session does not
move its fee to another funnel, so such a fee is `paid`, not "paid through another
funnel"); without an event, the product must match an active offer
on a Slot this customer registered for. Another funnel's explicitly attributed
payment is excluded even if its product matches. Active payments form the fee
metric; related inactive payments can still establish an opportunity's provenance.
Memberships, unrelated products and soft-deleted payments are excluded. An
opportunity must link one of these payments, or (without a payment link) match
a registered Slot's project offer. Unknown associations stay uncounted rather
than treating all company sales as this funnel's conversions.

Consultation evidence for paid Projects (scheduled, held, not held) is read on the Closing board, not here.
No automation history is inferred from a registration. The Project candidate
picker's time window and registration actions are unchanged: Ready qualifies a
customer for an invitation, and opening a chart never enrols them.

### Stage 1 flowchart — 2026-10-08

The Preview funnel's **Journey** tab reads `PreviewJourneyBoard` through the shared workspace (the old
`PreviewJourneyBoard.vue` / `PreviewJourneyFlow.vue` components are gone). Project funnels read
`ProjectJourneyBoard`; the scheduled `SalesFlowWeeklyReport` alone still uses `JourneyBoard` (§6c).

- Intake is the **company Lead population**, including people with no funnel or
  Session registration. Each `leads.id` counts once. Deleted leads are excluded;
  internal staff accounts have their own node, included in the headline total but
  excluded from customer readiness. `LeadVisibility::apply()` scopes counts, owner
  choices and drill-down rows together; a restricted viewer sees their allowed
  subset, not a company-wide count they cannot open.
- Default is **all time**. An optional Session picks its registrants; optional
  dates pick people added to the CRM (`leads.created_at`) in that range — whole days
  of the user's display timezone, compared in the app timezone `leads.created_at` is
  stored in (2026-10-13: the bounds used to be converted to UTC, which moved the window
  8 hours earlier). The date inputs are labelled **Lead added from / to**.
  The owner filter uses the Journey owner, falling back to the lead's account manager.
- **Ready for Stage 2** requires `EventRegistration::STATUS_ATTENDED` in any
  non-cancelled, non-deleted Session of this funnel. It checks all Slots and all
  dates even when a narrower cohort is selected. No membership payment or Journey
  row is required. A later no-show or unfinished call does not remove readiness.
  Editing actual attendance affects the next refresh; a stale Journey timestamp is
  not an alternative source of attendance evidence.
- Ready customers are subdivided by **cumulative attendance minutes**: ≥240,
  120–239, 60–119 and <60. Sum `event_registrations.attended_minutes` for attended
  Sessions in this funnel, across all Slots and dates. Each registration already
  includes the webinar's join/leave segments; do not add segments again. The unique
  `(event_id, lead_id)` key prevents counting one Session twice. Other funnels,
  no-shows and upcoming registrations do not contribute minutes. Two 80-minute
  Sessions count as 160; exact 60/120/240 belong to the higher group. Recorded zero
  is valid (attendance under 30 seconds rounds to zero). If any attended Session
  has missing/invalid duration, put the customer in **Duration incomplete** and
  show the known subtotal, without treating unknown minutes as zero. Every Ready
  customer appears in exactly one duration group, and their sum equals Ready.
- Each lead occupies exactly **one current node**. Before an upcoming/live Session,
  its matching Journey supplies the welcome, M2 offer (`offer`), AI, missed-call, callback or human step —
  **only when that cycle began on the landing page** (`FunnelJourney::landingCycles()`: the journey's last
  `registered` event says `landing`, or the registration's source is Landing). A colleague's registration (admin
  add, import, From Preview, an agreed Session) waits in `webinar` even when a later message opened a journey for
  it (D2); a real hand-off task still shows as `human`. Otherwise an upcoming registration means waiting for
  attendance. Precedence (`PreviewJourneyBoard::node()`), first match wins: any attendance → `ready`; a
  stopped / lost journey → `paused` (it beats an upcoming registration); an upcoming Session → its box or
  `webinar`; a **before-webinar** hand-off (With a colleague) → `human`; the latest registration a no-show →
  `no_show`; an **after-webinar** hand-off with no attendance verdict (residual) → `human`; else `review`
  (a registration) or `registered` (none). An after-webinar hand-off of a no-show is therefore the `no_show`
  box (Stage 2), carried by its hand-off task (`preview_no_show`) — never also Stage 1's Human box
  (2026-10-13; it used to be counted under `preview:human`). A company lead without a Preview registration is
  not a no-show.
  These are current positions, not cumulative send/call counts. The intake total
  is the sum of all current nodes, including review, stopped and internal accounts.
- Imported registrations need no backfill. With no Journey history, the board
  never claims that an AI call or message happened. Automation still follows each
  Session's Slot settings; arrows describe the intended routes.
- The first paint is counts only (no roster). Clicking a node reloads the same optional `journeyBoard` prop and
  shows 25 leads per page, with owner, relevant Session and links to the lead's Sales → Journey or
  the Session's attendance/registration roster. Ready rows show cumulative minutes
  and attended Session count. Clicking a duration group narrows the Ready roster;
  `jduration` persists through paging and is cleared when another node is selected.
  `jnode`, `jpage`, `jduration` join `jsession`, `jfrom`, `jto`, `jowner` in the URL (an unknown `jnode` is
  counts only);
  navigation preserves `suite`.
- The board also computes `entered_stage2` (distinct ready leads already registered in a linked Project funnel,
  `candidate_source_funnel_id` — a subset of Ready), `destinations`, `untracked`, `in_progress`, `window` and
  `preparation`, but **no page shows them today** (`SalesJourneyWorkspace.vue` does not read them). Opening the
  board does not register anyone, create tasks or send messages/calls. Stage 2's existing candidate picker and
  its date window remain separate from this all-time readiness view.
- A roster page asks "is this customer still in Stage 1?" (D6, for a colleague's Stage 1 button) once for the
  page — `FollowUpAccess::rememberStageOne()`, as My Work does — not once per row.

No migration or production data command is needed for this read-only projection.
`tests/Feature/Lead/PreviewJourneyBoardTest.php` covers legacy records, cross-Slot
attendance, repeat registrations, date/Session cohorts, stale steps, staff separation,
deleted Session exclusion, company leads without registrations, permission scopes,
duration boundaries, incomplete minutes and count/roster agreement — and (2026-10-13) the app-timezone date window,
an after-webinar no-show hand-off counted once, the `journeyBoard`-only reload and a "Cannot be reached" contact
read as finished.

### 1. Everything is written through one door

`FunnelJourneyRepository::record($journey, $event, $ref, $data)`:

- `TRANSITIONS` maps the EVENT to the box it lands the person in (`null` = log only: a reminder, a refund).
- `ONLY_FROM` lists the boxes an event may move a journey **from**. An event the current box does not accept
  is still **logged** but moves nothing — a late "AI call missed" after a colleague took over, or a no-show
  verdict for an old session after the person attended a later one, must not pull them backwards.
  *Attended once = attended.*
- Idempotent per `(journey, event, ref)` — the hooks live in webhooks and queue jobs that retry.
- A closed journey only moves again through `reopened`: a new landing registration reopens a **lost** or **stopped**
  one (`FunnelJourneyRecorder::registered()`); a **won** journey is never reopened — its registration is logged and it
  stays *Booked*. The one other way: a journey a **deal** closed follows that same deal — it switches *Booked* ↔
  *Not closed*, and `deal_reopened` takes it back to the box it was in before that close when the deal is open
  again (§2, *A closed journey follows its own deal*).
- Facts are stamped whatever the box: `attended_at`, `paid_at`. `record(…, move: false)` logs an event and keeps
  its fact without moving the box — how a verdict for an older session is written (§2).
- `handed_to_human` is accepted only from the automation boxes or *Colleague called* (a reopened task).
- **Human contact survives milestone changes (2026-10-08).** Registration, attendance and payment
  do not fulfil or close a Call task. `handoff_context` freezes its Session, Slot, registration and
  question phase. Retries reuse the same task, including a completed task; another Session or
  before/after phase has its own obligation. Paid-path Zoom booking tasks still retire when superseded.
- Task outcomes and AI callbacks carry their original Session/phase. They log evidence without moving
  another Session's current box. My Work uses actual open task assignees independently of the customer's
  current account manager, payment or attendance milestone.
- **`lead_action_items.handoff_context`** (JSON, migration `2026_10_08_150000_add_handoff_context_to_lead_action_items`)
  is the task's frozen identity — read it, never re-derive it from the journey's current Session:

  | Written by | Keys |
  |---|---|
  | a hand-off (`FunnelJourneyHandoff::contextOf()` / `forRegistration()`) | `event_id` · `event_series_id` · `registration_id` · `phase` (`FunnelQuestionSet::MOMENT_BEFORE` / `MOMENT_AFTER` / `MOMENT_PAID`) |
  | the REP's Zoom task (`toRep()`) | the above + `engagement_id` · `project_id` |
  | an AI appointment request (`FunnelAppointmentRequest`) | + `appointment_request` `{call_id, call_uuid, requested_time, …, instruction}`; once a colleague agreed a time: `consumed_appointment_call_id` · `consumed_appointment_call_uuid` |
  | an agreed follow-up (`HandoffOutcome::followUpTask()`) | the original context (minus `appointment_request` / `submission_uuid`) + `followup_at` |
  | a recorded contact ([Pending / Done](/docs/modules_handbook/shared/sales-flow-chart/record-contact.md)) | `funnel_id` · `event_id` · `event_series_id` · `registration_id` · `project_id` · `engagement_id` · `responsibility_queue` · `phase` · `submission_uuid` |

  A task without a `project_id` covers every Project of its Session. `responsibility_queue` (a
  `LeadActionItem::FOLLOW_UP_QUEUES` key) makes any task a sales-flow task even without a `funnel_journey_id`.

### 2. The hooks — one line each, all fail-soft

Every hook is `app(FunnelJourneyHooks::class)->…`, placed right after the automation did its work. The class
resolves what the call site cannot know (which funnel an AI call belongs to, which journey a payment is for).
**A hook never throws**, and does nothing for an untracked funnel.

**A hook runs AFTER its caller's transaction commits** (`DB::afterCommit` inside `guard()`; straight away when
there is none — and in tests, where Laravel skips the wrapping transaction). Many call sites sit inside a write:
a payment, an assignment, a booking, an outcome. The tracker locks journey rows of its own, so inside the
caller's transaction a deadlock between the two would roll the caller's work back — and a swallowed one would
leave it half done. A write that rolls back also never reaches the journey, which is the truth.

| Where | Hook | Event recorded |
|---|---|---|
| `RegisterLeadAction` (landing page only) | `landingRegistered` | `registered` (source `landing`) — also queues `EnsureFunnelHumanContact` for the registration (§3) |
| `SendFunnelWhatsAppMessage` | `whatsappSent` | `welcome_sent` (the on-register rule) · `reminder_sent` — about the send's `event_id`, else (a welcome) its `context_event_id` |
| `SendFunnelAiCall` | `aiCallPlaced` | `ai_call_placed` · `ai_call_refused` (budget, blocked number…) — a call placed by an **"after the session ends"** rule carries `after_webinar` + its `event_id`: the after-webinar loop (§3c) |
| `AiCallAftermath::settled` / `analyzed` | `aiCallMissed` · `aiCallAnswered` | `ai_call_missed` · `ai_call_answered` (+ `useful`) — and, when the call's Session is known, the **hand-off at once** (`toHuman`, reason `ai_completed` / `ai_no_info` by `useful`, plus any appointment request) |
| `AiRoundsAftermath` (an AI 2 Rounds round 1 a funnel placed) | `aiCallMissed` · `aiCallAnswered` · `aiRoundTwoAnswered` | as above, but an answered round 1 records `ai_round: 1` and **waits** for round 2; round 2 answered → the hand-off now, its agreed time as the task's appointment line and due day |
| `SendAiCallFollowUp` | `aiCallFollowUpSent` | `missed_message_sent` · `offer_sent` |
| `AiCallbackController`, the WhatsApp "call me" button | `callbackClicked` | `callback_clicked` |
| `ReconcileWebinarAttendance`, `EventRegistrationRepository` (mark / walk-in / close) | `attendanceFinalized` · `registrationMarked` | `webinar_attended` · `webinar_no_show` |
| `PurchaseFulfiller::fulfill` / `revoke` | `purchasePaid` · `purchaseRefunded` | `paid` · `payment_refunded` |
| `EngagementRepository::changeStatus` | `engagementStatusChanged` | `closed_won` (Booked) · `closed_lost` (Lost) — also on a journey this deal already closed, which switches with it · `deal_reopened` when that deal moves to an open status |
| `LeadActionItemRepository` done / reopen / update | `actionItemDone` · `actionItemReopened` · `actionItemAssigned` | `human_done` (carrying the outcome's result; none for a system-closed task or a REP's Zoom task its booking closed) · back to "With a colleague" · owner change |
| `HandoffOutcome::record()` (a "no answer" attempt) | — (it records directly) | `human_attempt` |
| `LeadRepRepository::syncAccountManager()` | `accountManagerChanged` | no event — the journey's owner follows the manager |
| `ProcessInboundWhatsAppWebhook` (a tap on a funnel template's button) | `templateButtonTapped` | `note` |
| `EventRepository::update` / `cancel`, `EventsController::destroy` | `sessionChanged` | no event — the session's journeys look again on the next tick (their wake times came from the old schedule); a start moved **earlier** re-queues `EnsureFunnelHumanContact` (§3) |
| `PreviewCandidatesController::store` ("From Preview", §3e) | `candidateRegistered` | `candidate_marked` on the **Preview** journey only (it moves no box). Since 2026-10-08 (D2) no Project journey is opened and no owner assigned at registration. |
| `ZoomMeetingRepository::create` / `linkLead` / `linkEngagement` | `zoomMeetingScheduled` | `zoom_scheduled` — the REP's 1-1 Zoom (§3d), from *Paid*, *Closer assigned*, *Sales Zoom booked* or *held* |
| `ZoomMeetingRepository::markEnded` / `recordActualDuration`, `linkEngagement` (an ended meeting) | `zoomMeetingHeld` | `zoom_done` — only for a meeting a journey recorded as booked |
| `EngagementRepository::setZoomCloser` | `closerChanged` | no event — the REP's open task moves to the new closer, and the journey names them |

Things worth knowing:

- **Who gets a journey.** A landing registration opens one at once. A colleague's registration — admin add,
  import, From Preview, an agreed Session, a Zoom-side registration — does not (D2); its journey opens **on
  demand**, when the first message (a From Preview welcome, a reminder) or the attendance verdict reaches them, pointed
  at that message's Session (a welcome's `context_event_id` too, since 2026-10-13 — before, a welcome-opened journey had
  no Session and the scanner could not time it). Only that pointer is set: such a journey has no landing `registered` event, so the boards keep the customer in the `webinar` box, no "AI never
  reached" hand-off follows and `EnsureFunnelHumanContact` is never queued for it. After the webinar they are
  followed up like anyone else (no-show / attended suggestions, the after-webinar rules). **Staff never get one.**
- **Which session.** A landing registration points the journey at the Session that form registered (a slot
  landing), else at the person's **next** Session that has not ended (a cancelled one is nobody's next). A reminder
  never moves it; a new registration, or a newer session's verdict, does. Tasks do not follow it: each task keeps
  the Session frozen in its `handoff_context` (§1), so moving the journey never re-labels or closes another
  Session's task. A verdict
  for an **older** session — an admin correcting last week's roster — is logged and its fact kept, but moves
  nothing (`FunnelJourneyRecorder::isOlderSession()`). A registration the box does not accept (somebody who
  already paid) moves no session either; one with no upcoming session at all clears it
  (`FunnelJourneyRepository::clearSession()`), or the clocks would keep reading a webinar that already ended.
- **The "let the AI call you" invitation** (opted out at registration) carries its funnel
  (`SendAiCallFollowUp::$funnelId`) and is logged on that funnel's journey only. The original send ID also fixes its Session; a legacy message with no reliable context does not
  move unrelated journeys.
- **Which funnel an AI call belongs to.** New calls freeze the send, Funnel, Slot and Session IDs plus the before/after phase in metadata.
  Older calls resolve their original send ledger; ambiguous unscoped callbacks do not broadcast. A manual or payment AI call belongs to no journey.
- **A "useful" AI call** = the call's extracted fields carry every name in `funnel_journey.useful_fields`
  (`will_attend`, `buy_intent`) with a real value (`unknown` does not count) — or, for a call AFTER the webinar,
  every name in `funnel_journey.useful_fields_after` (`buy_intent` alone: "will you attend" was about a session
  that is over) — `FunnelJourney::usefulFields()`. ⚠️ These must match the **extraction field names on the AI
  call profile** — a profile without them makes every answered call "not useful". Since 2026-10-08 every answered
  call is handed to a colleague either way; "useful" only chooses the hand-off reason (`ai_completed` vs
  `ai_no_info`) and the "did we learn it" flag on a colleague's outcome. Since 2026-10-13 `aiCallAnswered` makes that
  hand-off **at once** for the call's own Session (idempotent per journey · kind · Session · phase): left to the
  scanner, a payment or a verdict landing before its next tick moved the journey off *AI call answered* and nobody
  was asked to call. `HandOffAfterAiCall` stays as the safety net.
- **AI 2 Rounds as the AI call (owner, 2026-10-16).** A slot's AI-call rule may pick AI 2 Rounds' round-1 profile
  (`ai-rounds-1-zh`): the registration then rings [AI 2 Rounds](/docs/modules_handbook/manage/my-work/ai-rounds.md)'
  round 1, whose call carries the send's Session like any funnel call, and the lead appears on their account
  manager's 2 Rounds AI Call list. Missed → the usual *AI call missed* + M3. Answered → the answers are filed
  (DATA 1; round 1 also asks `will_attend`, and already asks `buy_intent`, so "useful" still works) with `ai_round: 1`
  on the event, and **no hand-off yet**: `HandOffAfterAiCall` waits as for a missed call (step + `handoff_hours`,
  pulled to the webinar cutoff, at once if the webinar starts first), and `EnsureFunnelHumanContact` still fires at
  its own time. When the account manager approves the answer and round 2 is answered before the class starts,
  `aiRoundTwoAnswered()` hands off now (reason `ai_completed`): with an agreed time it rides in as the task's
  `appointment_request` ("AI 2 Rounds — call 2 agreed a call at …") and AI 2 Rounds moves the task to that day and
  adds the calendar entry — on the task the six-hour wait already wrote, if it did, never a second one. A round 2
  after the class has started is plain AI 2 Rounds again (its own callback task).
- **Which journey a payment belongs to.** The session that sold it (`purchase_histories.event_id`) when its
  funnel sells that kind of thing; otherwise the lead's active journey on a funnel of the right kind. A Project
  journey whose slot lists offers (`event_series_offers`) only counts a payment for one of those projects.
- **A refund is logged, not acted on** — it clears `paid_at` and leaves the box; whether the deal is dead is the
  sales team's call, as it is for the engagement.
- **A deal closes a Project journey only with evidence**: its payment was recorded on that journey, or the
  journey's slot lists the deal's project among its offers. "Cannot say" is not enough — production has no
  `event_series_offers`, and an old deal on another project marked Lost must not end the journey of next week's
  webinar. A Booked deal made by hand, with no payment behind it, therefore leaves the journey open.
- **A closed journey follows its own deal** (2026-10-13). When the deal whose status closed the journey changes again
  between Booked and Lost — a cancelled booking (`BookingRepository` sets the deal Lost), a revived sale — the journey
  switches *Booked* ↔ *Not closed* with it (`closed_at` and `lost_reason_code` follow; Booked clears the reason). The
  repository allows it only when the journey's last close was that deal's (`FunnelJourneyRepository::closedByDeal()`);
  each switch is logged without a ref.
- **A revived deal reopens its journey** (owner decision 2026-10-13). When that deal moves to an **open** status — any
  status but the wins (Booked, the retired Following Up, Converted) and the ends (Lost, Swing); e.g. Lost → With
  Closer, the customer came back — the hook records `deal_reopened` (log: *Deal back in progress — journey
  reopened*, with the project and the deal's new status). The journey goes back to the box it was in before that
  close — the `from_step` of the last moving close not made from *Booked* / *Not closed*
  (`FunnelJourneyRepository::beforeDealClose()`) — with the stage it had then (set by the last moving `registered` /
  `reopened` / webinar verdict before that close), status ACTIVE, `closed_at` and `lost_reason_code` cleared. It is
  NOT `reopened`: no new registration cycle starts. Booking or losing the deal again closes the journey again (a
  repeat close by the same deal carries no ref — the first close holds the `(event, deal)` key). A REP's "book the
  Zoom" task the close superseded is not recreated.

### AI-requested appointments require human confirmation

Ordinary Funnel calls use `FunnelAppointmentRequest` to turn structured requested times/types into
**Pending confirmation** instructions on the existing human contact task. A fresh request after
completed contact gets a separate `confirm_appointment` task. Retries deduplicate by original call;
raw times such as "Friday afternoon" remain unconfirmed. The owner confirms the customer, time and
format before creating a real meeting. No Calendar, Appointment or Zoom record is created here.

Existing webinar profiles' `wants_followup` means the customer wants the team to follow up, possibly
for information. Without a time/type it produces a clarification task, never an assumed appointment.
Profiles can provide `appointment_time` / `appointment_datetime` / `appointment`, `meeting_type`,
`wants_human`, and `callback_time` for more detail; an AI callback time alone is not a human meeting.
`appointment_booked` from the AI is only reported evidence, never a confirmed system booking.

### 3. The scanner — `funnel-journey:advance` (every 5 minutes)

The aggregate journey scanner handles its current cycle. It takes the active journeys whose `next_check_at` has come and runs the
rule classes in `config('funnel_journey.rules')`, one rule per journey per tick:

| Rule | Fires when | Does |
|---|---|---|
| `HandOffAfterAiCall` | answered → at once (the safety net: `aiCallAnswered` normally hands off first) — except an AI 2 Rounds round 1, which waits like a missed call (round 2 normally hands off first) · missed / pending / callback with no outcome → after the wait | all answered calls → human hand-off, including useful answers |
| `HandOffWhenNotClicked` | "let the AI call you" or the missed-call message was sent, and no click | hand-off |
| `HandOffWhenAiNeverReached` | a **landing** registrant still at Registered / Welcome sent (not a colleague's pick from the Preview list — nobody offered them an AI call) | hand-off |
| `ExpireCallAtWebinarStart` | *With a colleague* **before** the webinar, and it has started | records **Not called before the webinar** (`human_expired`); the human contact task remains open |
| `SettleAttendanceAfterWebinar` | 30 min after the webinar **really** ended, still no verdict (before-the-webinar journeys only) | reads the registration; none → no-show (`inferred`) |
| `UnpaidAfterWebinar` | 2 h after the webinar ended, attended or no-show, not paid — never while its Zoom webinar is still live | `unpaid` |
| `AssignRepWhenPaid` | at *Paid* (the next tick after the payment) while `paid_at` is set — a payment refunded before that tick gets no REP | the REP hand-off (§3d) |

**"Nothing to do" is not an error.** `FunnelJourneyHandoff::toHuman()` reuses the task of the same
(journey, Session, phase, kind) — open, or DONE with a human outcome — and returns the DONE one without logging
anything; `describe()` then returns `null`, which the scanner reads as "nothing to do". So that this never turns
into a re-check every 15 minutes (for ever, after the webinar), the hand-off rules stop waking a journey once
`contactFulfilled()` finds a colleague's completed contact for its current Session and phase — `HandOffAfterAiCall`
(answered and unanswered boxes), `HandOffWhenNotClicked` and `HandOffWhenAiNeverReached` (2026-10-13; before, only
the answered box did). A task closed only by the system (expired / superseded) never counts as contact.
An agreed follow-up that continues a completed contact is reused without a new hand-off and never pulls the
journey back from *Colleague called*.

`EnsureFunnelHumanContact` (`app/Jobs/Automation`) is queued by `landingRegistered` for the landing registration
(`afterCommit`, delayed to `dueAt()`: registration + `handoff_hours` (6), never later than `handoff_cutoff_hours`
(3) before the webinar, never sooner than the 20-minute automation grace). At its deadline it calls
`forRegistration()` → `toHuman()` with that registration's Session frozen, so human work survives the aggregate
journey moving to another Session or a paid milestone. It first re-checks: registration still there and not muted,
lead not staff, Session not cancelled and still in the same funnel / Slot, funnel active and tracked. If the
deadline has moved **later** (rescheduled Session, a raised wait) it dispatches a **new** delayed job instead of
`release()`: production workers run `tries=1`, so a release would end in `MaxAttemptsExceeded` and lose the
obligation. A duplicate job is harmless (the hand-off reuses the task). On the `sync` driver it does not
re-dispatch (it would loop). An **earlier** deadline the waiting job cannot notice, so a Session whose start
`EventRepository::update` moves earlier re-queues the job (`FunnelJourneyHooks::sessionChanged()` →
`requeueHumanContact()`, owner decision 2026-10-13) for each of its landing registrations still registered and not
muted, delayed to the new `dueAt()` (now when already due), in chunks of 200; the old job stays and is harmless. It never replays old registrations, calls anyone or sends a message; production queue
workers must process it.

- **The wait** = `handoff_hours` (6), but never later than `handoff_cutoff_hours` (3) before the webinar
  starts. Once the webinar has started, pre-webinar hand-offs stop. **After the webinar** (the follow-up loop,
  §3c) there is no webinar to be late for: the plain wait, with the same grace floor.
- **The automation's grace** = `automation_grace_minutes` (20): no hand-off sooner than that after the person
  entered the box they wait in. Somebody who registers INSIDE the cutoff is past it from the first second, and
  the AI call placed a minute later needs time to ring, talk and be analysed — before this floor they were
  handed to a colleague on the next tick while that call was still going.
- **A cancelled session is no session** (`WebinarClock::liveSession()`; a deleted one the relation no longer
  loads): no start for a call to be late for, no end after which anybody was a no-show. Its people wait — a
  silent one is still handed over after the usual wait — until they register again.
- **"Not paid" counts from the webinar's END** (the real one, else the scheduled one), never from the verdict:
  somebody checked in at the door is not "not paid" two hours later with the session still running. While its Zoom
  webinar is still **live** (`WebinarClock::webinarIsLive()`) the rule only looks again in 15 minutes, however long the
  webinar overruns (bounded by the 12-hour fallback below).
- **The inferred no-show is keyed on the registration**, so the real verdict for it, arriving later, is the same
  fact and is not logged twice (a real *attended* is a different event and still moves the box).
- **"Really ended"** = `SessionDueWindow::endedAt()` — a Zoom webinar that is still live has not ended,
  whatever the clock says. If its "ended" webhook never arrives, the scheduled end is used after 12 hours.
- **A paused funnel is left alone** (2026-10-13; owner rule 2026-10-02: a paused funnel stops its automation). The
  scanner takes only journeys of a funnel that is tracked AND active (`event_funnels.is_active`), as
  `EnsureFunnelHumanContact` and the screenshot nudge already did. Its journeys keep their `next_check_at` and are
  looked at on the first tick after the funnel is switched back on: pre-webinar hand-offs are already null once a
  webinar has started, so what follows is the facts (inferred no-shows, *Not paid*, *Not called before the
  webinar*) and contacts still owed (after-webinar hand-offs, a REP for a payment) — never a burst of pre-webinar calls.
- **How a journey sleeps.** Every event wakes its journey for the next tick. A journey nothing fired on sleeps
  until the earliest moment any rule names (`JourneyRule::wakeAt()`), or for good (`next_check_at = null`)
  when no rule watches its box. So the table can hold every registrant without the scanner re-reading them.
- **It decides from rows it read at the start of the tick**, so every write re-checks under the journey's lock:
  `toHuman()` creates no task when the person has since moved on (the AI call came back, they attended or paid);
  `expire()` does nothing unless the journey is still *With a colleague*; `scheduleCheck()` writes the next wake
  only while the journey stands in the box it was worked out from — an event that landed meanwhile has already
  asked for a look on the next tick, and a wake from the OLD box could put it to sleep for hours.
- **A rule that throws** is reported, the journey is re-checked in 15 minutes, and the rules after it still run
  this tick.
- A new box with a clock = **one class + one line** in `config/funnel_journey.php`.
- `php artisan funnel-journey:advance --dry-run` prints what would fire and moves nothing.

### 3c. After the webinar — the follow-up loop (Stages 2 and 3)

The flowchart, once a webinar is over: **no-show** → "why didn't you attend" WhatsApp → AI call; **attended,
not paid** → follow-up WhatsApp → AI call → M4 if missed → a colleague; **paid** → a REP (§3d).

- **The messages and calls are ordinary funnel rules** with the **"after the session ends"** trigger and the
  conditions *attended?* (`attendance_condition`) and *paid?* (`payment_condition`) on both rule tables — plus,
  on an AI call, the warm-cohort limit *attended the Preview* (`cohort_condition`, owner decision #15). How they
  are judged: [Funnel Automation handbook](/docs/modules_handbook/manage/events/funnel-automation/readMe.md).
- **The journey re-enters the automation boxes.** An AI call placed by an "after the session ends" rule, for
  the journey's OWN session, moves a journey standing in an after-webinar box (`attended` · `no_show` ·
  `unpaid` · `followed_up`) back to *AI calling* — `FunnelJourneyRepository::ONLY_FROM_AFTER_WEBINAR`, judged
  under the lock from the call's `after_webinar` + `event_id`. Any other call (a reminder for a later session)
  keeps the usual `ONLY_FROM` and cannot drag a no-show back in. The stage stays *After the webinar*.
- From there it is Stage 1's loop without a webinar cutoff. Useful fields still describe AI evidence,
  but every answered call requires human contact. A refused follow-up call also reads "AI call missed",
  so the hand-off follows after the wait.
- **The colleague's task** reads "Call X" with the webinar's verdict ("did not attend" / "attended, has not
  paid") and an after-webinar question; it never expires (`ExpireCallAtWebinarStart` is before-the-webinar only).
  The verdict is the task's OWN Session registration's (2026-10-13 — it used to read the journey's aggregate
  `attended_at`, so a no-show in Session 2 who attended Session 1 read "attended, has not paid").
- **The missed-call message** after an after-webinar call is the rule's own template (`missed_template` — the
  owner's M4). Not approved yet = nothing is sent, and the hand-off follows after the wait.
- **Cold no-shows get no call at all** when the AI-call rule is limited to the Preview's attendees: they stay at
  *No-show* with the WhatsApp only. Nothing hands them to a colleague — 600 call tasks after every Project
  webinar is exactly what decision #15 rules out.

### 3d. The paid path — a REP and the 1-1 Zoom

"Paid? Yes → Payment received → the system auto-assigns a REP; the REP calls the lead to book the Zoom → Human
Zoom." For a Preview journey "paid" is a membership (the member's 1-1 Zoom); for a Project journey the slot's
project fee (the 1-1 sales Zoom).

- **`AssignRepWhenPaid` fires on the scanner's next tick, not inside the payment.** `PurchaseFulfiller` records
  *Paid* before `fulfillProject()` opens the deal, and the REP is stamped on that deal — five minutes is nothing
  to a customer who just paid; a closer named on a deal that does not exist yet is lost.
- **Who** (`FunnelJourneyHandoff::pickRep()`): the deal's Zoom closer, when it has an active one → the lead's
  **account manager** (owner, 2026-10-05: no second rotation after payment — the account manager IS the REP) →
  a lead with no manager takes the next turn on the company round robin → nobody (the task is written
  unassigned; the journey reads "Closer assigned · nobody"). Never "any admin". The per-funnel paid-customer
  queue this used to read is gone (`assignRep()` deleted). **Since 2026-10-11 (D9) that account manager is
  fresh:** the payment itself (`PurchaseFulfiller` → `RecomputeTopRepOnPaymentAction`, every Membership /
  Project-fee payment, journey or not) refreshes the buyer's rep figures and moves the seat to their TOP REP
  when clearly ahead — so by this tick the account manager is whoever did the selling, not whoever the last
  rollup left. `pickRep()` itself is unchanged; the Zoom closer still comes first. Rule: Leads handbook,
  *The account manager follows the TOP REP*.
- **What** (`toRep()`): the REP becomes the deal's `zoom_closer_id` (tracking only — never the `closer`
  commission role: a payment-opened deal has no closer pool and `rollTeamForPayment` would move it), the
  account manager when the lead has none, and gets a HIGH-priority **"Book the 1-1 sales Zoom with X"** /
  **"Book the member's 1-1 Zoom with X"** task (`handoff_kind = zoom`, *Schedule*, with a "Paid:" line) plus a
  phone alert. Journey → *Closer assigned* (`rep_assigned`), owner = the REP.
- **Booking the Zoom closes the task.** A **sales** Zoom (purpose 2 — for both kinds) scheduled for the lead (or
  linked to it, or to its deal, later) that starts after the payment — for a Project journey also paired with that
  deal — moves the journey to *Sales Zoom booked* (`zoom_pending`) and marks the task done **by whoever booked it**
  (no outcome row, so no "Colleague recorded the outcome" log line — 2026-10-13). Booked before any REP was named:
  the host becomes the REP. The meeting ending (webhook, or the duration sweep) moves it to *Sales Zoom held*
  (`zoom_done`). A **second** sales Zoom — booked while one is pending, or after the first was held — is the next
  meeting and moves it back to *Sales Zoom booked* (2026-10-13; before, only *Paid* / *Closer assigned* were read).
  The deal's Booked / Lost then closes the journey.
- **Known gap:** a REP who records an outcome on the "book the Zoom" task without booking closes the task; the journey
  stays *Closer assigned* and nothing writes a new task.
- **The REP keeps them.** A second payment is logged but never pulls the journey back to *Paid*
  (`ONLY_FROM[paid]`); a new account manager does not re-point the owner (`accountManagerChanged` skips the
  closing boxes); changing the deal's Zoom closer by hand moves the open task — and so the journey — to them
  (`closerChanged` → `followCloser()`). The deal closing before any Zoom closes the task as "no longer needed".
- **"Payment received" WhatsApp** stays the payment link's ON_PAID rule. A purchase with no link (portal
  checkout, an admin's manual entry) now borrows the rules of the ONE active link selling exactly the same thing
  — [Payment Automation handbook](/docs/modules_handbook/manage/payments/payment-automation/readMe.md).
- **The REP's outcome form** is the call task's (`HandoffOutcome`), asking the "paid" moment's questions
  (`HandoffQuestions::for()`): the Session's Slot **Paid** set, else that Slot's AI-profile fields; with no Session
  / Slot it asks none and the note is the record. Answers file as DATA 3+4 (Preview) / DATA 5 (Project). Since
  2026-10-08 anyone D5 allows may also record a contact on the paid steps without touching the REP's task — it never
  completes them ([Pending / Done](/docs/modules_handbook/shared/sales-flow-chart/record-contact.md)).

### 3e. The Project webinar's candidates — "From Preview"

A Project-webinar funnel names where its people come from (`event_funnels.candidate_source_funnel_id` — the
funnel form's "Candidates come from", shown for the Project Sales flow only). Each of its sessions'
Registrations tab then has **From Preview** (manage-events + manage-leads, the same gates as the CSV import):
everyone registered on a source-funnel session since this funnel's previous session (date editable) and not on
this session — name, phone, Preview session, attended?, member?, latest AI-call result, account manager. Somebody
already on another upcoming session of this funnel is shown greyed with it. Attended is pre-ticked.

- **Opening the list registers nobody** (`PreviewCandidates` computes it). A registration is a Zoom
  registration, which Zoom emails at once and nothing takes back — so the click is the approval.
- **Register selected** re-checks the ticks against the list as it stands (a uuid outside it falls out),
  registers them as `SOURCE_FROM_PREVIEW` ("From Preview"), sends the session's ticket, logs the activity trail
  (`source: from_preview`), pushes them to the Zoom webinar and sends the Session's **welcome** with their Zoom link
  (unlike a CSV import; `DispatchFunnelWelcomeAction` with `fromLanding: false`: WhatsApp / email / SMS welcomes go
  out, the AI-call welcome rule — and so its M2 offer — is skipped). It is still a colleague's registration (owner
  decision **D2, 2026-10-08**): **no Project journey is opened at registration**, no owner assigned, no AI call, no
  automatic task. `candidateRegistered()` only logs `candidate_marked` on their Preview journey. The welcome's send
  may open a Project journey on demand (like any reminder), pointed at the Session the welcome is about; it has no landing `registered` event, so the customer
  stays in the `webinar` box until the webinar. A session that has started takes nobody.
- **My Work** shows the ops / marketing person the next two weeks' Project sessions nobody has registered anyone
  onto from the list yet, with the count (`MyWorkBoard::candidateReviews()`).
- The CSV import stays as the fallback for people who never came through the Preview. The list is capped at
  1,500 (newest Preview first); past that it says so.

### 3b. Round robin at registration — every lead gets a person on day one

Owner decision #13, revised 2026-10-05: **one company list** (`lead_rotations` + `lead_rotation_members`,
Setting → Lead Distribution → Round Robin; [leads readMe](/docs/modules_handbook/manage/leads/readMe.md) has the
whole rule) takes turns, and every registrant of a tracked funnel with no account manager gets the person whose
turn it is (`FunnelJourneyHandoff::ownerAtRegistration()` → `pickPerson()` →
`LeadRotationRepository::assignManager()`, reason `REASON_ROUND_ROBIN` (11, "Round robin")). Through
`LeadDistributionService::assign()` like every assignment, so they are also the lead's first rep and can open it.
A brand-new lead is usually named already: Lead's `created` hook queues the same turn for every new lead.

- **Nobody is buzzed at registration** — a funnel takes hundreds of sign-ups, and only the ones the AI could not
  finish become a task (which does alert).
- **An existing account manager is kept and costs the list no turn.**
- **Round robin off, or nobody on it → nothing happens**, and a later hand-off is written unassigned.
- A lead the round robin assigned is an assigned lead like any other: if the Lead Distribution reapers are
  switched on (they are off by default), their no-appointment / no-booking rules recycle it to the pool on their
  own clock.
- **History:** before 2026-10-05 each sales-flow funnel had its own caller queue (`funnel_caller_rotations`
  `KIND_LEAD` + `KIND_BOOKING`, reason `REASON_FUNNEL_ROTATION` (9)). Those rows are still in the table but
  nothing reads them for a sales-flow funnel; `PUT funnels/{id}/caller-rotation` is VSL-only again.
- The journey's `owner_user_id` is set at once, and **follows the account manager** afterwards
  (`FunnelJourneyHooks::accountManagerChanged()`, called from `LeadRepRepository::syncAccountManager()` — the one
  place both writers of `assigned_admin_id` pass through), except while the journey is *With a colleague* (that
  owner is whoever the open task is assigned to) or on the paid path (`rep_assigned` · `zoom_pending` · `zoom_done`
  belong to the REP). `ownerAtRegistration()` skips the same boxes (2026-10-13): a paid customer's new landing
  registration is refused but still reaches it, and used to hand the journey from the REP to the account manager.

### 4. The hand-off — `FunnelJourneyHandoff::toHuman($journey, $kind, $reason)`

The one way a box becomes somebody's task:

1. **Picks the person** — the lead's account manager, when they are still an active account with a manage
   role; else whose turn it is on the company round robin.
2. **Makes them the account manager** — the round robin's turn writes it (a lead with none, or whose manager
   has left), so they are also a [lead rep](/docs/modules_handbook/manage/leads/readMe.md) and can open the lead.
3. **Writes the task** — an ordinary `lead_action_items` row: type **Call** (a Zoom or confirm-appointment task:
   **Schedule**), due **today** — **tomorrow** when written after 21:00 user time — and **High** when the webinar
   starts within a day or the reason is `webinar_soon` (a REP's task is always High), carrying `funnel_journey_id` +
   `handoff_kind` + the frozen `handoff_context` (§1). Line 1 is the action; the lines under it say why the
   automation gave up, the Session with the verdict of THAT Session's registration, and what to ask.
4. **Moves the journey** to *With a colleague* and records `handed_to_human`.
5. **Buzzes the colleague** through the existing `leads.action_item_assigned` alert
   ([Notify](/docs/modules_handbook/shared/notify/readMe.md)), "From: Sales flow".

- **Idempotent per (journey, Session, phase, kind)** (`taskInContext()`): a second call returns the same task —
  the open one, or the DONE one when a colleague already recorded the contact for that Session and phase ("nothing
  to do", §3). Another Session, or before vs after the webinar, is a separate obligation with its own task. A
  hand-off made AGAIN with a task somebody reopened is logged without that task as its key (the old key would read
  as a repeat and move nothing).
- **Nobody to hand to is visible, never a guess.** The task is still written, unassigned, and the journey reads
  *With a colleague · nobody assigned* (a rose icon on the list chip). Assigning the task on the lead's Action
  items tab makes that person the journey's owner.
- **Recording the outcome** (a closing result on the outcome form, §4b) moves the journey to *Colleague called*;
  reopening the task moves it back. A sales-flow task is never ticked: `ActionItemsController::done()` refuses it.
- **A hand-off has no author, so anybody working the lead may edit it** (`LeadActionItem::canEditFor()` — the
  one rule behind both the panel's pencil and `ActionItemsController::guardOwner()`). Every other action item
  stays author-only. Without this an unassigned hand-off could never be given to anyone.

⚠️ A hand-off only lands on a person when the lead has an account manager or the company **Round Robin** gives one
(§3b; the per-funnel Callers queue is gone). On 2026-10-08 every customer in Shawn's development copy was given a
manager (`leads:assign-missing-managers`); production still needs the Round Robin switched on and the same backfill
(see `docs/temp/7-10-temp/03-open-items.md` §C), or most hand-offs go out unassigned.

### 4b. Closing a hand-off — Pending / Done (formerly the outcome form, the flowchart's "DATA 2")

A hand-off task is not ticked off; it is closed by saying **how the call went** — since 2026-10-14 with ONE click,
**Pending** (*No answer*: the task stays open) or **Done** (*Spoke to them*: it closes), from
[`FunnelFollowUpButton`](/resources/js/Components/Leads/FunnelFollowUpButton.vue) on My Work, the sales-flow rosters,
the lead's Journey tab and Action items. Nothing else is asked; the "How did the call go?" form
(`HandoffOutcomeModal`, with the call's questions, a note and an agreed time) was removed — the questions below are
now filled only by the AI call. The same two buttons also record a contact on a human box that has
**no task** (a suggestion, a customer without a journey, a paid service step), may be used by the task's holders
**and** the lead's account manager, the opportunity's sales owner and super admins (D5) — and, on a **Stage 1** step
(`preview_invite` / `preview_call`) of a customer still in Stage 1, by any sales admin who can see the lead (D6,
2026-10-11; a hand-off nobody calls in time shows on colleagues' My Work **Help team** list), and on Stage 3's unpaid
contact Done records *Still following up* (D4b; *Not closed* + reason is recorded in Sales Projects since 2026-10-14). That contract — endpoints, conflicts, the 30-day re-contact window — lives
in [Pending / Done](/docs/modules_handbook/shared/sales-flow-chart/record-contact.md).
`HandoffOutcome::record()` writes one `lead_action_item_outcomes` row **per attempt**:

| Result | What happens |
|---|---|
| **Spoke to them** (Done) | The task closes, the journey moves to *Colleague called*, and a "📞 电话回报" line lands in the lead's Discussion feed beside the AI call's own report. |
| **No answer** (Pending) | The attempt is logged (`human_attempt` on the journey), the task stays **open** and moves to tomorrow (today, when the webinar is within a day). |
| **Cannot be reached** | The task closes with nothing learnt. No button offers it since 2026-10-14; older records keep it. |

- **The questions are the owner's for this call, else the AI call's own** (`HandoffQuestions`, §4c). With no set
  written for the moment: the extraction fields of the AI call profile the funnel's on-register AI-call rule uses
  — wording, type and choices — limited to the names in `funnel_journey.outcome_fields` (the profile also extracts
  things only a transcript can tell). Those answers are stored under the SAME field names, so an AI answer and a
  human answer are comparable; `HandoffOutcome::isUseful()` is the same "did we learn `will_attend` and
  `buy_intent`" test. Edit the profile's fields and the form follows.
- **"They will skip this session and join next time"** sets `event_registrations.reminders_muted_at`. Both reminder
  scanners (`whatsapp:run-funnel-reminders`, `funnel:run-automation-reminders`) skip a muted registration for
  EVERY rule of that session — reminders and follow-ups. The person stays registered (a Zoom registrant cannot be
  taken back). The Registrations roster shows a **Reminders off** chip; with manage rights a click turns them back
  on (`POST registrations/{id}/reminders`).
- **"Agreed a time to talk again"** creates an ordinary Call task for the same colleague on that day — from
  today on (`after_or_equal:today`; the picker greys out the past).
- **Two saves record once.** The outcome locks the journey, then the lead, then the task — the scanner's order —
  and re-reads the task. Closed meanwhile (another colleague, the webinar starting, a double click) → nothing is
  recorded: a plain XHR gets 409 with the message, an Inertia visit a toast and the refreshed page
  (`ActionItemsController::outcomeTooLate()`; a 409 there would open the framework's raw error dialog).
  "Join next time" is re-checked on the server too: only a session still AHEAD of them can be skipped.
- **A missed pre-webinar deadline does not complete human contact.** The scanner records
  `human_expired` and moves the aggregate to *Not called before the webinar* (`not_called`; the log line reads
  "Not called before the webinar — task still open"). The Call task stays open, including
  when nobody was assigned. A human outcome, rather than elapsed time or attendance, resolves it.
- Endpoints: `GET` / `POST leads/{id}/action-items/{item}/outcome` (`ActionItemsController::outcomeForm` /
  `outcome`, `OutcomeRequest`); 404 for a task that is not a sales-flow task; a plain XHR gets 204, or 409 for a task
  already done (an Inertia visit: a flash and `back()`). A task with
  a follow-up queue gets the extended form (instructions, completion, closing decision, agreed-Session
  registration). The task-less path is `GET` / `POST leads/{id}/funnel-follow-up`
  ([Pending / Done](/docs/modules_handbook/shared/sales-flow-chart/record-contact.md)).
- **Answers without a journey.** A contact recorded where the customer has no journey files its answers against an
  unsaved journey projection of the funnel (`funnel_journey_answers.funnel_journey_id` null, `event_funnel_id` set —
  migration `2026_10_08_191000`), so readiness still reads them.

### 4c. DATA 1–5 — the call questions and the answers (Phase 6, 2026-10-05)

The owner's flowchart captures "analysis data" at five points. Each answer is filed under its point, one row per
question, in `funnel_journey_answers` ([`FunnelJourneyAnswer`](/src/Lead/Journey/FunnelJourneyAnswer.php)):

| Point | The call | Answers come from |
|---|---|---|
| DATA 1 | Stage 1 · the AI call before the Preview webinar | the AI call, when it is analysed (`aiCallAnswered`) |
| DATA 2 | Stage 1 · a colleague's call | the outcome form |
| DATA 3 / DATA 4 | Stage 2 · the AI call / a colleague after the Preview (and before the Project webinar) | the AI call / the outcome form |
| DATA 3+4 | Stage 2 · the REP's call to somebody who paid on the Preview funnel | the outcome form of the REP's "book the 1-1 Zoom" task |
| DATA 3 · Stage 3 / DATA 4 · Stage 3 | after the Project webinar · AI call / colleague | stored `data_3b` / `data_4b` (plan decision #11) |
| DATA 5 | Stage 3 · the REP's call to somebody who paid on the Project funnel | the REP's outcome form |

The point is ONE rule, `FunnelJourneyAnswer::point()`: the funnel's kind, the journey's flowchart stage
(`FunnelJourney::flowStage()`) and who asked. The editor and the form both ask it.

- **The owner writes the questions** — the slot page's **Call questions** button
  (`CallQuestionsModal.vue`, `PUT slots/{id}/questions`, `FunnelQuestionsController`,
  `QuestionsRequest`, `manage-events`). The current Journey session selects its
  slot; each slot has independent before/after/paid question sets, up to 10 questions
  per moment, with an answer type and optional readiness area. An empty set uses
  only that slot's registration AI-call profile. A missing session/slot/profile
  yields no default questions; another slot's questions are never borrowed.
  Editing questions preserves their keys and previously recorded answer wording.
  The slot-questions migration copies legacy funnel sets to existing slots while
  retaining the original rows as archives. See [Slot operations](/docs/modules_handbook/manage/events/funnels/slot-operations.md).
- **Every answer keeps the wording it was asked with** (`question`), so a set rewritten later never changes what
  an old answer meant. An AI answer prints the description's first clause ("对方提到的预算范围"). What the AI
  JUDGED rather than heard (`funnel_journey.ai_judgement_fields`: interest level, suspected agent, time-waster,
  consent hesitation) and "unknown" are not filed; "none" is (owns no property yet).
- **Readiness** — an answer to a question about an area is evidence for it: AMBER, never green (a record anyone
  can open is green; a thing said is amber). `ReadinessColumns::answered()` lays it beside the AI channel
  readings' quotes as `Said (DATA 2 · Colleague's call): “预算大概多少？: RM600k”`. Meaningful negative Needs
  answers such as "not looking now" or "undecided" still clarify the brief (2026-10-08); unknown / unasked
  answers do not. Other areas retain the positive-evidence check. AI fields map through
  `funnel_journey.answer_areas` (purchase budget, looking now, buying purpose, timing, current problem,
  help needed, must-haves and area of interest → Need; project sentiment → Property fit). Available
  funds are separate Cash evidence. Legacy default answers are interpreted through this map without
  rewriting their original wording. Relationship comes from recorded human contact only, never an
  AI answer or quote. The
  list's colours read it at once; the readiness filters and sorts after the hourly `leads:refresh-readiness`.
- **Where it shows** — the lead's Sales → Journey tab: *What we know* (the newest answer per question — want to buy,
  buying for, area, budget — with who asked and when), the AI call's answers on its *What happened* line, and every
  call's full answers under *Automation details* ("What they told us", one block per call, newest first);
  the outcome form prints the point over its questions; the Discussion note ("📞 电话回报（接通）· DATA 2 · …")
  prints each answer beside its wording. The **Summary (客户档案)** reads the answers through that Discussion
  feed — it already reads the team's notes, and the AI call posts its own "🤖 AI 电话回报" — so its prompt did not
  change and no stored Summary went stale.
- **A colleague's "useful"** is judged only when they were asked the fields it needs
  (`FunnelJourneyHooks::usefulOf()`): with the owner's own questions, or on the REP's call, the log no longer says
  "attendance or buying intent still unknown".
- Merge: `funnel_journey_answers.lead_id` is a plain repoint; `mergeFunnelJourneys()` moves `funnel_journey_id`
  when two journeys fold. Deleting a lead deletes its answers.

### 5. The boxes

`FunnelJourney::STEPS` — every name and colour the UI prints comes from there (GUIDELINES §5).

| Stage | Box (`step`) | Who holds the ball |
|---|---|---|
| Before the webinar | `registered` · `welcome_sent` | automation |
| | `offer_sent` · `missed_sent` — waiting for a click | automation (6 h clock) |
| | `ai_call_pending` · `ai_call_answered` · `ai_call_missed` · `callback_clicked` | automation |
| | `human_pending` — *With a colleague* | **a colleague** |
| | `human_done` — a colleague recorded the contact | nobody |
| | `reminders` — **unreachable today**: only `ai_handled` leads there, and nothing records it since A25 | — |
| | `not_called` — *Not called before the webinar*: handed over, the webinar started, nobody reached them yet | **a colleague** — the call task stays open |
| After the webinar | `attended` · `no_show` · `unpaid` | the after-webinar rules (2 h unpaid clock) |
| | the automation boxes again, for a follow-up AI call (§3c) | automation |
| | `followed_up` — **unreachable today** (only `ai_handled` after the webinar leads there) | — |
| | `paid` — waiting for the next tick's REP | automation |
| | `rep_assigned` · `zoom_pending` (Zoom booked) · `zoom_done` (Zoom held) | **the REP** (§3d) |
| Closed | `won` (Booked) · `lost` (Not closed) — they switch with their deal, and go back to their earlier box when it is open again (§2) · `stopped` (**unreachable today**: nothing records `stopped`) | — |

### 6. Where it shows

- **Leads list → Journey column** (`JourneyCell.vue`): the box as a chip; hover = funnel, session, since when,
  who it is with. A rose person-icon means *needs a colleague and nobody is assigned*. One query per page
  (`FunnelJourney::chipsForLeads()`); a lead with several journeys shows the one the stage pills are about
  (`lead_flow.journey_uuid` — since 2026-10-06; before, the active one that moved last, which printed an old
  Preview journey's "Not paid" beside a Booked Project deal), else the active one that moved last.
  In front of the chip, **three small pills** — which of the flow's three stages the lead has reached across
  ALL its journeys (`lead_flow` on the chip, `SalesFlowChartPath::forLead($journeys, false)`). A list page never
  loads event logs: the pills come from the journeys' boxes plus four event ids the same query adds
  (`SalesFlowChartPath::withListKeys()`), so the list puts the lead on the **same journey and stage as the lead
  page** (§6d). The hover card spells the STAGE out (*第 2 段 / 3 · Preview webinar 之后*), never a box — the step
  alone cannot tell a landing sign-up from an import, or a refused AI call from a missed one (2026-10-13; it
  printed *客户在 landing page 报名* for an import and *接了吗？* for a refused call). Only the lead page names the box.
- **Lead modal (and, until 2026-10-14, the lead page) → the sales-flow bar** (`Components/Leads/SalesFlowProgress.vue`,
  above the tabs; owner, 2026-10-06: "admin can direct know what process the lead has go through"; hidden on the
  lead page since the Journey tab's stage cards carry the same stages — `SALES_FLOW_BAR_HIDDEN`): 第 1 · 2 · 3 段 as chevrons —
  green = done, blue = 现在, grey = not reached yet, pale grey = *no record* (the system never saw the lead in that
  stage: an import, an admin add, a lead from before the flow was tracked) — and the box the lead is in now.
  第 2 段 is never *no record* under 第 3 段: the lead's place on the Project webinar is its record (2026-10-13; a
  Project-landing registrant who paid before that webinar read 没有记录).
  `show()`, `quick()` and the modal's Discussion refresh send `journeyFlow` beside `journeys`
  (`LeadsController::journeyPayload()` loads the journeys once for both). Hidden in the AE suite (like the
  Journey tab) and for a lead no tracked funnel has seen. **看流程图** opens Sales → Journey.
- **Lead → Sales → Journey** (`JourneyTab.vue`, page **and** modal — `show()` and `quick()` both send
  `journeyOverview`, `journeys` and `journeyFlow`). Since 2026-10-14: three **stage cards** (Done / Now / Not yet
  and the box — `LeadJourneyStages`), the **next step** with Pending / Done (`LeadJourneyWork`, read from the
  boards for this one lead, with their authorization), **What happened** (`LeadJourneyTimeline`: registrations,
  attendance minutes, recorded calls, payments and this log, newest first by day) and **What we know** — see the
  Leads handbook's *Journey tab* bullet. Read-only but for the two buttons. The modal's Discussion refresh
  (`quick?section=discussion`) carries the Journey props too, so a call recorded there (or from the tab inside the
  modal) updates it without reopening the lead. Collapsed at the bottom, **Automation details** keeps one card per
  funnel with the open task, the answers and the log, and **one chart for the whole lead**: the
  sales flow guide's own chart (`MyWork/Partials/SalesFlowChart.vue`, given `:flow`) — boxes passed green, the
  current one blue and tagged 现在, a box reached where nothing was done orange (没做到), the rest grey, and the
  arrows walked lit. One chart, not one per card, because the Preview and the Project funnel are one flow. It
  opens scrolled to the current box (520px tall; **显示全部** shows it whole).
- **My Work**: a hand-off is an ordinary task, tagged **Sales flow**, closed through its outcome form, and also an
  item of **My responsibilities** in its image stage (see [My Work](/docs/modules_handbook/manage/my-work/readMe.md)).
  A **Sales flow** block lists the person's leads by who holds the ball (`MyWorkBoard::flow()`, by `owner_user_id`):
  *With the automation* · *Waiting for my call* (count only — those are the Call tasks) · *AI collected the
  answers* (the human contact is still owed) · *Called* · *Not called before the webinar* · *After the webinar*.
- **Lead → Action items**: the task's origin chip reads **Sales flow** (`LeadActionItem::ORIGIN_SYSTEM`).
- **Funnel page header**: a "Sales flow · Preview webinar / Project webinar" chip.
- **Switching a funnel's Sales flow off** hides its journeys from both surfaces and stops the scanner on
  them; the rows stay, and reappear (as they were) if it is switched back on.

#### 6d. The bar and the chart — how one lead's path is worked out (`SalesFlowChartPath`)

The design and its corrections: [`docs/temp/7-10-temp/04-sales-flow-chart-path-design.md`](/docs/temp/7-10-temp/04-sales-flow-chart-path-design.md);
the review findings and their status: [`05-review-findings-2026-10-07.md`](/docs/temp/7-10-temp/05-review-findings-2026-10-07.md).
The code is the truth — the step → box tables are `PREVIEW_STEP_NODES` / `PROJECT_STEP_NODES`.

- **One walk per journey, over its log**, oldest event id first (`created_at` can be backdated). The current cycle
  starts at the last *accepted* `registered` / `reopened` event, else at the first event (a journey a reminder or a
  verdict opened: an import, an admin add, and since D2 every Project journey after a From-Preview pick). Earlier
  cycles stay in the log but are not drawn.
- **Boxes are drawn on proof.** `start` only for a landing registration; the welcome even when its event was
  refused (the AI call landed first); a refused AI call, a call task the webinar overtook, or a REP's Zoom task
  closed before any Zoom is **orange** (reached, not done); `pick` only when a colleague really picked
  (`candidate_marked`, or a Project registration with source `preview_candidate`). Paying before the verdict puts
  the lead in the paid box's stage — the band is the box's, never `flow_stage`. A refused "attended" on the paid
  path, or on a Project journey already Booked / Not closed, is still drawn as attended.
- **An inferred no-show is dropped** when the real "attended" for the same session arrives, moved or refused,
  unless a follow-up already ran from it (2026-10-13: a refused one on the paid path left 没来 lit).
- **After a From-Preview pick** the Preview path ends at `project`: later Preview verdicts and payments are drawn as
  facts before the pick, and the task the pick found open turns green once it is done — the call logged, the REP's
  Zoom booked — instead of staying orange (2026-10-13).
- **A revived deal** (`deal_reopened`, owner 2026-10-13): the close never stood, so *Closing* leaves the path and the
  box the journey reopened to is current again; the bar no longer reads Booked / Not closed.
- **Safety net:** an active journey's step overrides the walk when it names one box, or a box in another stage —
  a lead merge moves the other person's log onto this journey but keeps this journey's step (2026-10-13; before,
  a step that could be several boxes, e.g. `unpaid`, never overrode it).
- **Which journey speaks for the lead** (`forLead()`): one Preview and one Project journey are read (each: active
  first, then the latest move). The Preview journey owns the lead only when its current cycle started **after the
  Project journey's last move** (event ids); otherwise the Project journey does, with the Preview path drawn in
  front of it. A Preview re-registration after an old Project webinar starts the lead over; a Project journey that
  moves after that sign-up (webinar attended, fee paid, a follow-up handed over, deal Booked) holds the lead again;
  an old Preview task ticked after a Booked deal never takes it back.
- **The list decides the same way** without loading a log: `chipsForLeads()` adds four sub-selects to its one
  query — cycle start, first event, last move, last `candidate_marked` (`SalesFlowChartPath::withListKeys()`) —
  and a Preview journey picked in its current cycle reads `project`, as on the page. Its box is otherwise the
  step's (band-accurate, not box-perfect), so the list's pill words name the stage, never a chart box (the chip
  beside them is the journey's step label, as before). Before 2026-10-13 the
  list compared `step_since` while the page compared cycle starts, and the two could choose different journeys.
- **Bands:** `done` when the path has a box of that stage (the list: a Preview journey is 第 1 段's record),
  第 2 段 always `done` under 第 3 段, else `skipped` (没有记录); an ended flow shows its outcome (Booked / Not closed).
- **Known gaps** (the owner's to decide — 04's GAPS): M2 has no box; the Project funnel's own pre-webinar
  automation collapses onto `project`; there is no box after `task3`; a refund does not undo 付了.

### Individual customer progress and historical records (2026-10-08)

The Lead page and read-only modal now receive `journeyOverview` from the same
`LeadsController::journeyPayload()` method. `LeadJourneyOverview` uses the existing
Preview / Project board populations restricted to this lead, active Membership /
Project fee payments, shared FPA progress and readiness evidence. Business Stage 1,
Stage 2 and Stage 3 are visible even with **zero automation journey rows**. A newer
no-show does not erase earlier Preview attendance; minutes accumulate across its Slots.
A historical Project fee needs no Event attribution to establish the Stage 3 handoff.
Payment does not establish attendance or prove a previous stage was completed.

*Until 2026-10-14 (replaced by the stage cards, next step and timeline; the two files below were deleted):* the
individual Journey opened with a three-lane Stage 1 → Stage 2 → Stage 3 flowchart.
`JourneyFlowMap.vue` drew compact HTML nodes over an SVG canvas with curved arrows,
zoom / fit controls, and a horizontally scrollable readable size on mobile. Hover or
keyboard focus on a stage or node opens its evidence popover; click pins it, Escape
or Close dismisses it, and touch uses the same pinned details in a bottom panel.
The popover owns the recorded Session / Slot, attendance duration, payment date and
permission-scoped navigation links. Details remain reachable when the pointer moves
from the node into the popover. Automation history is a separate collapsed disclosure.

`journeyMap.js` presents independent registration, attendance and qualification/payment
flags without inferring earlier milestones from later ones. Being in the Preview population is not
evidence of registration; being eligible for Stage 2 is not participation there.
Missing stages remain visible as **No participation recorded**, including direct
Project fee buyers. The current follow-up stage is the furthest stage with actual
participation or payment. Arrows describe business order, not a verified chronological
transition; dates remain visible because a customer can return to an earlier stage.
Consent, financial questions and WhoPay are individual Stage 3 nodes, showing shared
customer evidence even when collected during Stage 1. The 1-1 / closing point links
to recorded Project progress; payment never marks a meeting or sale completed.
Readiness remains customer-wide beneath the chart. The page and lead modal render
the same `JourneyOverview.vue`.

`journeys` and `journeyFlow` retain their existing purpose: recorded automation
executions, handoffs and DATA answers. Their empty state now says that no automation
history has been recorded, not that the customer has no business progress. The older
execution chart's three time bands remain separate from the three business stages.
Opening this tab never backfills journey rows, replays automation or creates tasks.
Round Robin only assigns an owner; it cannot create execution history.

The overview offers the next unfinished paid preparation step, or the existing
Sessions / Sales Projects destination. Links respect the viewer's module permissions;
Lead visibility and Project group scope remain enforced. Show, quick modal and its
Discussion refresh share this payload. The regression test in `FunnelJourneyTest`
covers imported attendance, payment without Event attribution, full page/modal parity,
unchanged automation history, and an unauthorized viewer.

### 6b. During the webinar — the screenshot nudge

The flowchart's R2 has "1 hour after start — post a screenshot to the group". A person has to take the
screenshot, so the system's part is not forgetting it: `SessionNudges::remindScreenshots()` (run by the same
five-minute scanner) sends the Notify event **`events.webinar_screenshot`** an hour into every tracked funnel's
session that is really running (a Zoom webinar must be LIVE). Opt-in: a colleague ticks "Events — time to post a
webinar screenshot" on Manage → Notifications. Once per session, by the event's own day-long throttle scoped to
the session. `funnel_journey.screenshot_reminder_minutes` (60; 0 = off).

R2's other line — "15 minutes after start, AI-call the people who have not joined" — needs no code: it is an
AI-call automation rule with the after-start trigger and "no-shows only", on the funnel's Automation tab.

### 6c. The boss's view — Journey tab, Sunday report, Leads filters (Phase 5)

**Funnel page → Journey tab** (`JourneyBoardTab.vue`). Shown only on a funnel whose Sales flow is on, to a
viewer who can see leads. It is the shared [Sales flow chart](/docs/modules_handbook/shared/sales-flow-chart/readMe.md)
workspace over the **all-time** `PreviewJourneyBoard` / `ProjectJourneyBoard` (see *Journey overview layout* and the
Stage 1 / Stage 2 sections above) — not `JourneyBoard` (since 2026-10-08). The tab asks for its board itself
(`Inertia::optional`, a partial reload of `journeyBoard`), so opening the funnel page never pays for it. A reload
that asks for `journeyBoard` alone (`X-Inertia-Partial-Data: journeyBoard` — every chip, page or filter click)
returns from `FunnelsController::show()` right after the funnel lookup, the merged-funnel / VSL redirects and the
lead-visibility check, with just that prop (2026-10-13). Before, every click first built the whole page — Sessions
with ad spend and CPL, slot sales, catalogue projects, … — only for Inertia to discard it.

**The Sunday report's board — `JourneyBoard`** (behind CEO → Reports → "Sales flow board", below; no page shows it).
The bullets describe that board's two groups:

- **Who is counted — two groups, on purpose.** The **flow** (how far they got, where they are now, how long a
  box holds people, why lost) counts the people of one session when one is picked, otherwise the journeys
  that opened, or re-registered, in the date range (default: the last 30 days). The **work** (the *Need a
  colleague now*, *Nobody assigned* and *Overdue tasks* cards, the overdue list, the per-colleague table)
  counts every journey still running, whenever it opened, plus those that closed in the range
  (`JourneyBoard::workingIds()`). A call task ten days late belongs to somebody who registered before a
  7-day range, and it is the most urgent line, so a date range must never hide it. Both groups narrow to the
  picked session and owner, and always to the leads the viewer may see (`LeadVisibility`). URL keys
  `jsession`, `jfrom`, `jto`, `jowner`; anything unrecognised reads as "no filter", never as an error.
- **How far they got:** Registered → Attended → Paid → REP assigned → 1-1 Zoom held → Booked (Project funnels
  only). Each step is counted from a fact the journey already keeps (`attended_at`, `paid_at`, a REP_ASSIGNED or
  ZOOM_DONE line in the log, status WON). Nothing is defined afresh here. Under it: how many the AI call
  reached, handled alone, handed to a colleague, and how many a colleague called or never called.
- **Where they are now:** the boxes of the three stages, plus the "nobody assigned" count.
- **How long a box holds people:** the median from entering a box to leaving it, read off the log. A box
  someone is still in is counted once they leave. "With a colleague" = how long colleagues take to call.
- **Per colleague** (the work group): the running journeys they own (and how many need them now); their
  hand-off tasks open, overdue, and done in the range; calls and 1-1 Zooms with these people in the range;
  deals booked in the range. Calls and Zooms use the leaderboard's own rules (`ChannelLeaderboard::countableRows()`), so a call
  counted here is counted everywhere else too.
- **Why lost** (the deal's lost-reason codes) and **overdue tasks** (50 named; the count is always the full
  one). Overdue = an open hand-off task past its day, the same rule as My Work (`SalesWorkQueue::bucketFor()`).

**CEO → Reports → "Sales flow board"** (`SalesFlowWeeklyReport`, key `sales-flow-weekly`, Sunday 23:00 by
default). Off until the owner enables it and picks recipients. The last 7 days: one row per tracked funnel (the
flow), then one per colleague, the overdue list (25) and the deals lost THIS week (the work group), with an AI
summary (prompt `ceo_sales_flow_report`). The per-colleague rows are read once over every funnel's journeys together, so a call
to somebody on two funnels counts once. See the
[Reports handbook](/docs/modules_handbook/manage/ceo-dashboard/reports/readMe.md).

**Leads list:**

- **Filters** `journey_stage` (1 before the webinar, 2 after, 3 closed = booked or not closed), `journey_step`
  (any box), `journey_owner` (`me`, a colleague's uuid, or `none` = a box that needs a colleague with nobody
  named). Only funnels whose Sales flow is on count. A lead with journeys on two funnels matches on either.
- **Pay attention → "Sales flow task overdue"** (`AttentionFlags::JOURNEY_OVERDUE`): an open sales-flow task
  more than one day past its day (`JOURNEY_OVERDUE_DAYS`). Stricter than the board on purpose: a task due
  yesterday is already "overdue" on the board, but gets one day of grace before the list flags it.

### 7. Merging and deleting people

`IdentityChildMap` classifies `funnel_journeys.lead_id` as a special case: when two leads merge, a journey on a
funnel the winner has no journey for simply moves; when both have one, the loser's log and its hand-off tasks
move onto the winner's journey (`LeadRepository::mergeFunnelJourneys()`). Deleting a lead deletes its journeys
and their log. `owner_user_id` is staff, so a merge leaves it alone.

## Not built yet (plan `docs/temp/lead-journey-implementation-plan.md`)

- **The owner's questions themselves.** The flowchart's "1) 2) 3)" for each call are still to be written, on
  each funnel's Call questions box (§4c). Until then a colleague is asked the AI call's questions.
- **The four Stage 2/3 templates are SUBMITTED, not yet approved** (2026-10-05, from a dev box on the shared
  WABA, all `zh_CN`): M4 = `ai_caller_missed_after_v1` (body {{1}} name + the call-back URL button — the
  AI-call rule's missed-call WhatsApp), Payment received = `payment_received_v3` (the ON_PAID four: name, item,
  amount with currency, reference — plain, so it stays UTILITY; `payment_received_v2` adds a wa.link and is
  MARKETING), "Why didn't you attend" = `webinar_no_show_followup_v1` and "Follow-up (unpaid)" =
  `webinar_attended_followup_v1` (both {{1}} name, {{2}} the session title, one quick reply — map them on the
  funnel's after-the-session-ends WhatsApp rules to `{{name}}` / `{{event_title}}`). Production learns of them
  only through Messages → Templates → **Sync from Meta**. Then attach each to its rule.
- No automation-log backfill: `funnel_journeys` records only events observed after tracking was enabled. Historical business progress is displayed separately by `LeadJourneyOverview` (§6).
- **The per-lead chart** on Sales → Journey still draws the older `SalesFlowChart.vue` / `FLOW_CHART` boxes
  (`SalesFlowChartPath`), not the owner's image renderer the company and funnel charts use.

**Known limits, left as they are (2026-10-04 review):**

- **A manager who left is replaced only when the flow needs somebody.** A lead whose account manager was
  deactivated keeps that name until the sales flow next hands it over; then the round robin's next person takes
  the seat. Nothing sweeps such leads in bulk.
- **Quiet hours do not pause the clock.** With `RETELL_QUIET_HOURS=true` (off by default) an AI call that
  would ring at night is deferred to 9am, but nothing tells the journey — a 10pm registrant can be handed to a
  colleague at 4am, before their AI call is placed.
- **Attendance verdicts are processed where they land** — the reconcile job, or the "Close attendance"
  request — about ten queries per registrant, not on a queue of their own. Fine for hundreds; watch it at
  thousands.
- **A merge keeps the WINNER's box.** The loser's log, tasks and outcomes move under it and its attended / paid
  facts are folded in (the earlier moment wins), but its step is not compared.
- **A Preview journey never closes** (2026-10-05). Only a Project deal's Booked / Lost closes a journey, so the
  Journey board's WORK group (every running journey, §6c) holds every Preview registrant since the Sales flow
  was switched on, and a colleague's "Journeys" count on that funnel only grows. Waiting, nobody assigned and
  overdue are unaffected: they read the three colleague boxes and open tasks. The board also passes journey ids
  as PHP arrays — fine for thousands, worth turning into subqueries at tens of thousands.

## Deploy checklist

1. `php artisan migrate` (seven migrations dated 2026-10-04 — including the `(ref_type, ref_id)` index on
   `funnel_journey_events` and the `whatsapp_message_id` index on `funnel_whatsapp_sends`; a database that ran
   an earlier copy of those two migrations has neither — roll them back and migrate again, or add the indexes).
2. Setting → Lead Distribution → **Round Robin**: add the people, then switch it on (2026-10-05 — one company
   list replaces the per-funnel Callers queue). Until it is on, a new lead gets no account manager
   automatically and every hand-off is written unassigned.
3. Events → Funnels → Edit the funnel → **Sales flow** (and the wait in hours, if not six).
4. Make sure the AI call profile extracts `will_attend` and `buy_intent` (or change
   `funnel_journey.useful_fields`) — they are also the first two questions on the outcome form.
5. Whoever hosts the webinar: Manage → Notifications → tick "Events — time to post a webinar screenshot".
6. The scheduler already runs `funnel-journey:advance` every five minutes; try
   `php artisan funnel-journey:advance --dry-run` once.
7. **After the webinar (2026-10-05 migrations `2026_10_05_100003` … `100005`):** Edit the
   Project funnel → "Candidates come from" = the Preview funnel; on each slot add the "after the session ends"
   rules with their conditions (no-show WhatsApp + AI call limited to the Preview's attendees, unpaid
   follow-up), naming the approved M4 as the AI-call rule's missed-call WhatsApp. Set `RETELL_DAILY_BUDGET_USD`
   above the cohort's worst case; `RETELL_CALLS_PER_MINUTE` (10) paces the calls.
8. **DATA 1–5 (migrations `2026_10_05_100006` + `100007`):** migrate, then `php artisan config:cache` (two new
   `funnel_journey` keys). Optional: write each funnel's **Call questions** — nothing changes until you do.
9. **2026-10-08 (owner decisions D1–D5):** migrate `2026_10_08_150000_add_handoff_context_to_lead_action_items`,
   `2026_10_08_190000_add_closing_decision_to_lead_action_item_outcomes` and
   `2026_10_08_191000_allow_funnel_journey_answers_without_journey`, then `php artisan config:cache` (new key
   `funnel_journey.recontact_after_days`, env `FUNNEL_RECONTACT_AFTER_DAYS`, default 30).
10. **Once, after the first deploy:** `php artisan leads:rollup-reps --all` (fills `lead_reps` for every lead —
   the Leads list's Rep column is empty until it runs) and `php artisan zoom:sync-actual-durations --all --limit=1000` (`--all` alone still stops at `--limit`, default 300; production had 498 meetings on 2026-10-06) (asks
   Zoom how long each past meeting really ran). The scheduler keeps both current afterwards. A local database
   refreshed by `db:sync-from-production` needs the same two: the sync leaves local-only tables untouched, so
   `lead_reps` still describes the old data until the rollup runs again.

## Related files

- `src/Lead/Journey/LeadJourneyOverview.php` — read-only individual business progress, independent of automation logs.

**Backend**
- `src/Lead/Journey/FunnelJourney.php` — the row: stages, boxes, statuses, list / panel payloads.
- `src/Lead/Journey/FunnelJourneyEvent.php` — the log row: event names, labels, the detail line.
- `src/Lead/Journey/Repositories/FunnelJourneyRepository.php` — `TRANSITIONS`, `ONLY_FROM`, `record()`.
- `src/Lead/Journey/FunnelJourneyRecorder.php` — fail-soft writes; tracked-funnel and staff gates.
- `src/Lead/Journey/FunnelJourneyHooks.php` — every call site's one-liner.
- `src/Lead/Journey/FunnelJourneyHandoff.php` — the hand-off: person, task, alert; round robin at registration.
- `src/Lead/Journey/HandoffOutcome.php` + `Support/HandoffQuestions.php` — closing a hand-off with what was learnt;
  which questions a call asks (the owner's set, else the AI call's) and what an AI call learnt.
- `src/Lead/Journey/FunnelQuestionSet.php` + `Repositories/FunnelQuestionSetRepository.php` — the owner's call
  questions; `FunnelJourneyAnswer.php` + `Repositories/FunnelJourneyAnswerRepository.php` — DATA 1–5, the one
  `point()` rule; `app/Http/Controllers/Manage/Events/FunnelQuestionsController.php`,
  `app/Http/Requests/Manage/Events/Funnels/QuestionsRequest.php`, `FunnelsController::journeyQuestions()`.
- `src/Lead/Support/ReadinessColumns.php` — `answered()`: an answer as amber evidence.
- `src/Lead/LeadActionItemOutcome.php` + `Repositories/LeadActionItemOutcomeRepository.php` — one row per attempt.
- `src/Lead/Journey/SessionNudges.php` — the screenshot reminder (`config/notify.php` → `events.webinar_screenshot`).
- `app/Http/Requests/Manage/Leads/ActionItems/OutcomeRequest.php`, `ActionItemsController::outcomeForm()` / `outcome()`.
- `src/Event/EventRegistration.php` (`reminders_muted_at`), `EventRegistrationRepository::setRemindersMuted()`,
  `RegistrationsController::reminders()`, and the two reminder scanners that skip muted rows.
- `src/Event/FunnelCallerRotation.php` + its repository, `FunnelsController::saveCallerRotation()` — VSL funnels only
  since 2026-10-05 (a sales-flow funnel uses the company Round Robin).
- `app/Jobs/Automation/EnsureFunnelHumanContact.php` — the per-registration human-contact deadline (§3).
- The boards and the record path: `src/Lead/Journey/{PreviewJourneyBoard,ProjectJourneyBoard,ProjectJourneyContexts,ClosingJourneyBoard,JourneyWorkQueue}.php`,
  `src/Lead/Services/{FunnelFollowUpState,MyWorkResponsibilities}.php`, `src/Lead/Repositories/FunnelFollowUpRepository.php`,
  `src/Lead/Support/FollowUpAccess.php`, `app/Http/Controllers/Manage/Leads/FunnelFollowUpController.php`,
  `src/Event/Support/WorkflowSessions.php` — see the [Sales flow chart](/docs/modules_handbook/shared/sales-flow-chart/readMe.md)
  and [Pending / Done](/docs/modules_handbook/shared/sales-flow-chart/record-contact.md).
- `src/Lead/Journey/Rules/*` — `JourneyRule`, `TimedRule`, `WebinarClock` and the six rules (incl. `AssignRepWhenPaid`).
- `src/Event/Support/FunnelRuleAudience.php` — the after-webinar conditions and the AI call's cohort.
- `src/Event/Services/PreviewCandidates.php`, `app/Http/Controllers/Manage/Events/PreviewCandidatesController.php`,
  `CandidatesRequest` / `RegisterCandidatesRequest` — the "From Preview" list; `EventRegistration::SOURCE_FROM_PREVIEW`.
- `src/Zoom/Repositories/ZoomMeetingRepository.php`, `EngagementRepository::setZoomCloser()` — the Zoom / closer hooks.
- `app/Console/Commands/AdvanceFunnelJourneys.php` + `app/Console/Kernel.php` — the scanner and its schedule.
- `config/funnel_journey.php` — switch, waits, useful fields, the rule list.
- `src/Event/EventFunnel.php` (`JOURNEY_*`), `EventFunnelRepository`, `Funnels/StoreRequest`, `FunnelsController`.
- `src/Lead/LeadActionItem.php` (`funnel_journey_id`, `handoff_kind`, `ORIGIN_SYSTEM`), `LeadActionItemRepository`.
- `src/Lead/Services/ActionItemAssignees.php` — `notify()` accepts no actor; `src/LeadDistribution/LeadAssignment.php` — `REASON_FUNNEL_HANDOFF`.
- `app/Http/Controllers/Manage/Leads/LeadsController.php` — `journey` on list rows, `journeyPayload()` (the
  journeys once → `journeys` + `journeyFlow`, and into `journeyOverview`), `buildJourneyRows()`.
- `src/Lead/Journey/LeadJourneyOverview.php` — the lead's Journey tab payload (`journeyOverview`); beside it
  `LeadJourneyStages.php` (stage cards + the box), `LeadJourneyWork.php` (the boards for one lead → the next step)
  and `LeadJourneyTimeline.php` ("What happened"). Test: `tests/Feature/Lead/LeadJourneyTabTest.php`.
- `src/Lead/Journey/Support/SalesFlowChartPath.php` — a lead's journeys → the boxes of the sales flow chart
  (§6d): `NODES`, `nodeFor()`, `forLead()`, `withListKeys()` (the Leads list's four event-id sub-selects). Pure — reads only loaded relations.
- `src/Lead/Support/IdentityChildMap.php`, `src/Lead/Repositories/LeadRepository.php`, `src/Lead/Lead.php` — merge / delete.
- `src/Lead/Journey/JourneyBoard.php` — the board (Journey tab and Sunday report); `FunnelsController::journeyBoard()` — the tab's filters.
- `src/Report/Definitions/SalesFlowWeeklyReport.php`, `resources/prompts/ceo_sales_flow_report.md` — the Sunday report.
- `app/Http/Requests/Manage/Leads/LeadQueryRequest.php` (`journey_stage` / `journey_step` / `journey_owner`),
  `LeadsController::journeyCounts()`, `src/Lead/Support/AttentionFlags.php` + `AttentionReasons.php` (`journey_overdue`).

**Frontend**
- `resources/js/utils/funnelJourney.js` — chip tones.
- `resources/js/Pages/Manage/Leads/Partials/JourneyCell.vue`, `Partials/Tabs/JourneyTab.vue` (+ `JourneyTab.test.js`).
- `resources/js/Pages/Manage/Leads/Partials/Tabs/JourneyOverview.vue` (stage cards + next step) and
  `Partials/Tabs/Journey/{JourneyStageCards,JourneyNextStep,JourneyTimeline,JourneyKnown,JourneyAutomation}.vue` —
  the Journey tab since 2026-10-14. `Partials/Tabs/JourneyFlowMap.vue` + `journeyMap.js` (the business-stage canvas
  the tab drew before) were deleted the same day.
- `resources/js/Components/Leads/SalesFlowProgress.vue` — the three-stage bar (modal; hidden on the page) and its pill form
  (list); `resources/js/Pages/Manage/MyWork/Partials/SalesFlowChart.vue` — the chart, plain on My Work's guide
  tab, a lead's map when given `flow` (`tests/Unit/Lead/SalesFlowChartPathTest.php` pins `SalesFlowChartPath::NODES` and its arrows to `FLOW_CHART`).
- `resources/js/Pages/Manage/Leads/Index.vue`, `Show.vue`, `Components/LeadDetailModal.vue`,
  `Components/Leads/LeadListCell.vue`, `composables/useLeadTabs.js`.
- `resources/js/Pages/Manage/Events/Funnels/Partials/FunnelFormModal.vue`, `Funnels/Show.vue`.
- `resources/js/Pages/Manage/MyWork/Index.vue`, `Leads/Partials/Tabs/ActionItemsPanel.vue`.
- `resources/js/Components/Leads/FunnelFollowUpButton.vue` — the one-click Pending / Done buttons (the outcome form `HandoffOutcomeModal.vue` was deleted 2026-10-14).
- `resources/js/Pages/Manage/Events/Partials/PreviewCandidatesModal.vue` (+ the "From Preview" button on
  `Events/Partials/Tabs/RegistrationsTab.vue`); the "Review the Preview's people" card on `MyWork/Index.vue`.
- `resources/js/Pages/Manage/Events/Funnels/Partials/Tabs/{JourneyBoardTab,FunnelJourneyWorkspace}.vue` — the funnel's
  Journey tab (→ `MyWork/Partials/SalesJourneyWorkspace.vue`, the shared live workspace).
- `resources/js/Components/Leads/{FunnelFollowUpButton,FunnelSessionRegistrationModal,LastContactLine}.vue` — Record
  contact, the agreed-Session registration, the Last contact line.
- `resources/js/Pages/Manage/Events/Funnels/Partials/CallQuestionsModal.vue` — the Call questions editor (the box
  on `Funnels/Show.vue`); the lead's answers render in the Journey tab (`Tabs/Journey/JourneyKnown.vue`,
  `Tabs/Journey/JourneyAutomation.vue`).
- The **Reminders off** chip on `Events/Partials/Tabs/RegistrationsTab.vue`. (`CallerRotationModal.vue` lost its
  `journey` variant on 2026-10-05; the funnel header's **Round robin** box links to Setting → Lead Distribution.)

**Migrations**
- `2026_10_04_100001_create_funnel_journeys_tables.php`
- `2026_10_04_100002_add_funnel_journey_to_lead_action_items.php`
- `2026_10_04_100003_add_journey_kind_to_event_funnels.php`
- `2026_10_04_100004_add_handoff_hours_to_event_funnels.php`
- `2026_10_04_100005_create_lead_action_item_outcomes_table.php`
- `2026_10_04_100006_add_reminders_muted_to_event_registrations.php`
- `2026_10_04_100007_add_button_reply_to_funnel_whatsapp.php` (the welcome template's button reply — see the
  [Funnel WhatsApp handbook](/docs/modules_handbook/manage/events/funnel-whatsapp/readMe.md))
- `2026_10_05_100003_add_after_webinar_conditions_to_funnel_rules.php`
- `2026_10_05_100004_add_candidate_source_to_event_funnels.php`
- `2026_10_05_100005_add_missed_template_to_funnel_automation_messages.php`
- `2026_10_05_100006_create_funnel_question_sets_table.php`, `2026_10_05_100007_create_funnel_journey_answers_table.php`
- `2026_10_08_150000_add_handoff_context_to_lead_action_items.php` — the task's frozen Session / phase (§1)
- `2026_10_08_190000_add_closing_decision_to_lead_action_item_outcomes.php` — D4b
- `2026_10_08_191000_allow_funnel_journey_answers_without_journey.php` — answers without a journey

**Tests**
- `tests/Feature/Lead/FunnelJourneyTest.php` (incl. the after-webinar loop, the REP queue + Zoom, a member's REP,
  the owner's call questions and DATA 1–5)
- `tests/Feature/Manage/Events/PreviewCandidatesTest.php`
- `tests/Feature/Event/FunnelAutomationReminderTest.php` (conditions, cohort, the paid re-check, validation)
- `tests/Feature/Lead/JourneyBoardTest.php` (the board, the Sunday report, the Leads filters + flag)
- `tests/Feature/Lead/{FunnelFollowUpTest,PreviewJourneyBoardTest,ProjectJourneyBoardTest,ClosingJourneyBoardTest,JourneyWorkQueueTest}.php`,
  `tests/Feature/Event/{WorkflowSessionRegistrationTest,SlotCallQuestionsTest}.php`, `tests/Unit/Lead/SalesFlowChartPathTest.php`
