# Customer onboarding control

**Objective:** Pace and **gate** customer entry so ops and support absorb load without compromising tenant isolation or payroll integrity.

**Do not:** Open unlimited self-serve signup with full modules on day one without staffing and gates (see [production-readiness-gates](./production-readiness-gates.md)).

---

## 1. Onboarding pacing

| Phase | Pace cap (example) | Rationale |
|-------|--------------------|-----------|
| Pilot | Invite-only; **manual** provisioning | Relationship + observability |
| Limited production | **N new tenants/week** cap (business sets N) | Queue, support, integration load |
| Broader GA | Raise N only after green weekly review | Controlled learning loops |

**Config lever:** `TENANCY_NEW_TENANT_LIFECYCLE` — use `onboarding` when wizard must complete before “fully live”; keep `active` only when intentionally skipping wizard (internal/test). See `config/tenancy.php`.

---

## 2. Onboarding approval flow (recommended)

1. **Commercial / CS** submits tenant request with plan, modules, primary contact.
2. **Ops** verifies: backup OK, worker count, webhook capacity for integrations.
3. **Admin** creates tenant via existing admin tenancy flow; subscription/plan assigned.
4. **Tenant owner** completes `/onboarding` (company profile, locale, timezone, module acknowledgment) where enabled.
5. **CS** validates completion in admin diagnostics / audit (`platform_audit_events`, `category = onboarding`) before declaring “live.”

---

## 3. High-risk tenant detection (signals)

| Signal | Mitigation |
|--------|------------|
| Request for **immediate** payroll + large headcount migration | Phased payroll go-live gate; migration checklist |
| Many API tokens requested day one | Scoped tokens; delayed high-volume ingestion |
| Custom integration with unknown partner SLA | Pilot webhook URL in staging first |
| Repeated `lifecycle_state` churn (suspend/active) | Finance/legal review before re-enable |

Document outcomes in ticketing; optionally tag tenant in CRM for heightened monitoring ([production-monitoring](./production-monitoring.md)).

---

## 4. Integration readiness checks

Before enabling outbound webhooks or high-volume API for a tenant:

- [ ] Staging webhook received **successful** signed delivery (`2xx`).
- [ ] Tenant has **production** URLs and secrets stored per security policy (not in chat logs).
- [ ] Rate limits and timeout expectations communicated to customer.
- [ ] `integrations-health` admin page reviewed for platform-side errors.

See `docs/customer-success/integration-onboarding-support.md`.

---

## References

- `docs/rollout/production-rollout-strategy.md`
- `app/Modules/Settings/Onboarding/` (wizard)
- `docs/resilience/final-resiliency-review.md`