# Onboarding, end to end

Onboarding begins on the relationship that already holds the deal, not on a new record. The workspace's own steps are tracked against the person; Connect chases what is owed, answers from Knowledge and the existing history, records what happened, and stops where a decision belongs to somebody. Steady state is reached when the steps are done and only ordinary work remains.

- **Status:** Available
- **Audience:** both
- **In the app:** #/relationships, #/follow-ups, #/needs-you
- **Last verified:** 2026-09-10
- **Canonical:** https://connectbyjbrh.com/docs/workflows/onboarding-workflow/

## The stage chain

1. Trigger — a deal is closed as won, or somebody starts onboarding on a relationship directly.
2. User event — a person confirms this customer is starting, which is an action rather than something inferred from the deal moving.
3. Authentication and workspace resolution — the workspace is fixed before anything is read or written; the onboarding record can only ever attach to a person in it.
4. Ingest — the request names the customer and the steps this workspace uses. No template is supplied, because what a new customer needs differs completely between businesses.
5. Canonical record — the onboarding attaches to the same Person and Company that carried the prospect research and the deal, so the first message can refer to what was agreed.
6. Reasoning — for each step, Connect works out what is owed, by whom, and what would move it: a message, a question, or a wait.
7. Knowledge, memory and rules — answers to the customer's questions are grounded in what the workspace supplied, bounded to the same budget every other answer uses. Commercial terms Knowledge does not support are refused rather than improvised.
8. Autonomy and approval — messages obey the channel's rule. A workspace that holds this channel will see onboarding messages queue in Needs You rather than go out.
9. Action and provider — chases are follow-ups with reasons, executed on the agreed channel through the same boundary as any other outbound work; phone chases drain two per tick.
10. Result — each execution records what actually happened, with the provider's acknowledgement deciding whether a message counts as sent.
11. Relationship, timeline and memory — completed steps, messages and calls land on the person's timeline; what the customer tells you during onboarding is worth storing as memory, because it is what the next year is answered from.
12. Audit, usage and Needs You — decisions are attributed, usage is metered, and any step needing a person waits in Needs You rather than in somebody's head.

> **Note** Stage two matters more than it looks. Starting onboarding is an explicit act, in the same way opening a case is, because a board that advances itself on inference is a board people stop trusting and then stop reading.

## Who does what

| Work | Connect | A person |
|---|---|---|
| Chasing what the customer owes | Schedules and executes follow-ups with reasons | Decides when a chase has become counter-productive |
| Answering questions | Answers from Knowledge and the relationship's history | Supplies the Knowledge that made the answer possible |
| Recording what happened | Writes messages, calls and outcomes to the timeline | Marks a step complete — an action, never an inference |
| Commercial questions | Refuses what Knowledge cannot support, and escalates | Gives the term, ideally into Knowledge rather than into one reply |
| Deciding the plan | Nothing. The steps are the workspace's | Owns the plan and changes it when it is wrong |

## Where onboarding stalls

**The customer goes quiet** — Chases are follow-ups and obey follow-up rules, including a phone chase more than 24 hours past due being closed as missed rather than made. Silence needs a decision, not a longer queue.
**A step waits on somebody internal** — It sits as work for a person to do — the `task` channel, which no drain ever sends. If nobody works the follow-ups screen, that step is invisible.
**Knowledge does not cover the questions** — Every question becomes an escalation. The onboarding is working; the workspace has given it little to work with.
**Two records for one customer** — Half the history is on the other record. Merge them, and both sides' identities, follow-ups, deals, cases and onboarding come across.
**A problem appears mid-onboarding** — Open a case. The two records coexist on the person and each reads the other's history as context.

## What steady state looks like

The steps are done, the onboarding record is closed, and the relationship continues with ordinary work: conversations answered under the channel's autonomy, commitments kept with reasons attached, cases opened when something goes wrong. Nothing is archived and nothing moves — the difference between onboarding and steady state is the absence of outstanding steps, not a change of system.

The lifecycle stage is what tells the rest of the workspace which of those two a customer is in, and moving it is its own recorded action. That is deliberate: a stage that drifted automatically would be a field nobody could rely on for anything that mattered.

## Questions

### Does winning a deal start onboarding automatically?

No. Starting onboarding is an explicit action on the relationship. A deal moving to won is a commercial fact; deciding a customer is now being onboarded is a different statement, and it is made by a person.

### What chases the customer during onboarding?

Follow-ups, with reasons, on whichever channel suits. They obey every ordinary follow-up rule, including autonomy, suppression and the limit that closes a very late phone chase instead of making it.

### Can onboarding and a support case run at the same time?

Yes. Both attach to the same person, and each is part of the context the other is answered from. A problem during onboarding is a case, not a reason to stop the plan.

## Related

- [Onboarding a new customer](https://connectbyjbrh.com/docs/support/onboarding/)
- [The relationship after the sale](https://connectbyjbrh.com/docs/support/post-sale/)
- [Handing a won deal to onboarding](https://connectbyjbrh.com/docs/workflows/won-deal-handover/)
- [Follow-ups for a person to do](https://connectbyjbrh.com/docs/follow-ups/task-channel/)
- [Lifecycle stages](https://connectbyjbrh.com/docs/relationships/lifecycle-stages/)
- [Knowledge in Connect](https://connectbyjbrh.com/docs/knowledge/)

## What this page is based on

- `docs-source/sources/CHANNELS.md` §5 — `onboarding_action`, `move_stage` and `merge_people`
- `docs-source/sources/GENERAL.md` §7 — follow-up channels, the `task` channel and the phone drain
- `docs-source/sources/CHANNELS.md` §6 — refusing ungrounded commercial terms
- Connect capability registry (docs-source/facts.py) — `onboarding`, `followups`, `lifecycle_stage`