ONBOARDING_CHECKLIST — First Month Pilot Runbook¶

Audience: Floor OS implementation engineer + tenant's technical lead + tenant's compliance officer. Goal: A new tenant signing up has a clear, dated path from "credentials issued" to "decision on continuation" — with hard milestones at 30 / 60 / 90 days. Related: PILOT_SCOPE.md (what's in scope), CRM_WEBHOOK_INTEGRATION.md (all wiring details), DEMO_CHEAT_SHEET.md (15-min discovery demo).

Legend: - Summary — one sentence on what this step is. - Action — concrete command, click path, or artifact to produce. - Acceptance — how we know the step is done. No ambiguity.

Role Taxonomy — pick this BEFORE Day 1¶

Floor OS ships with a 3-cluster role model. Tenant picks which clusters they need active. Tour them at /demo/roles.

The 3 clusters¶

Cluster	Purpose	Who uses it
Compliance	Governance, statute mapping, audit defense	Compliance Director, Compliance Officer/Analyst
Operations	Daily collection work, queues, dialing, payments	Executive (Ops), Manager, Agent
Support	Plumbing — vendor config, user provisioning, HR sign-off	IT/Admin, Tenant Admin, HR

The 8 personas¶

Each persona maps to a default home screen, a default permission set, and a default sidebar. Pick which personas the tenant will provision during the kickoff call.

Compliance Director — owns the gate, signs the audit log. Home: ComplianceCoverage. Reads WeeklyReview every Monday.
Compliance Officer / Analyst — investigates blocks, resolves disputes. Home: AuditTrail. Same person doing line-level statute review.
Executive (Ops VP, Collections SVP) — top-line KPIs across the floor. Home: WeeklyReview + OpsCoverage.
Manager — owns a team of agents, escalation paths, queue health. Home: TeamQueue + Coaching surfaces (deferred for pilot).
Agent — runs the queue. Home: today's queue + AccountDetail with the deep-link action bar.
IT — wires vendors, rotates keys, watches webhook health. Home: Settings → Vendors and Settings → API Keys.
Tenant Admin — provisions users, assigns roles, manages billing. Home: Admin → Users.
HR — gates hiring/offboarding flows that touch system access. Home: Admin → Users (read-only) + offboarding workflow.

Pilots usually start with Compliance Officer + Manager + Agent + IT + Tenant Admin (5 of 8). Director and Executive surfaces light up once Coverage data accumulates (~7 days). HR comes online when the tenant has a real offboarding case.

First Day — Tenant Setup¶

Goal by end of day: tenant logs in, has uploaded a sample portfolio, and has chosen which personas they want.

1.1 Tenant provisioned¶

Summary: Create the tenant record and default admin user in Floor OS.
Action: Ops runs scripts/provision_tenant.py --slug <tenant_slug> --name "<Legal Name>" --pilot-mode true. Sets tenant.pilot_mode=true so deferred nav is hidden.
Acceptance: Tenant admin can log in at https://app.flooros.com/<tenant_slug> and sees the PILOT badge in the sidebar header.

1.2 API key generated¶

Summary: Issue the tenant's first API key for the gate and outcome APIs.
Action: In Admin → API Keys, click Generate Key. Label it pilot-primary. Copy the secret to the tenant's vault (1Password, AWS Secrets Manager, etc).
Acceptance: curl -X POST https://api.flooros.com/api/v1/compliance/contact-check -H "X-API-Key: <key>" -d '{"tenant_id":"<slug>","account_id":"smoke-test","channel":"voice"}' returns a JSON body with allowed, reasons, statutes, audit_id, expires_at. The audit_id starts with ccs_.

1.3 Sample portfolio uploaded (CSV upload + preview)¶

Summary: Tenant uploads a small CSV (50-200 accounts is fine for Day 1) so we can show them the preview + column mapping flow live.
Action: Portfolio → Import → drop CSV. The new flow shows a preview pane with the first 25 rows. Tenant maps columns visually (drag header → field). Required: account_id, phone_number, state. Recommended: balance, last_contact_at, bankruptcy_flag. Click Confirm + Scan.
Acceptance: Preview pane shows 25 rows with green checkmarks on mapped columns, yellow warnings on optional, red on missing required. Scan completes within 60 seconds for ≤200 rows. Tenant sees the intake report with total_rows, blocked_rows, blocks_by_statute.

1.4 Pick role personas¶

Summary: Decide which of the 8 personas this tenant will provision in week 1.
Action: Walk the tenant through /demo/roles. For each persona they want, capture the user's name + email. Default to the 5-persona starter set (Compliance Officer, Manager, Agent, IT, Tenant Admin).
Acceptance: Persona-to-user mapping is signed off in the kickoff doc. Tenant Admin invites those users from Admin → Users with the right cluster role pre-selected.

1.5 Integration inventory¶

Summary: Identify which dialer, CRM, and payment processor the tenant uses.
Action: Fill the Integration Inventory worksheet. Supported adapters in CRM_WEBHOOK_INTEGRATION.md § Endpoints.
Acceptance: Worksheet signed off. Dialer vendor, CRM vendor, payment processor named. Decision recorded: five9 | twilio | convoso | generic.

1.6 SSO setup (optional, enterprise only)¶

Summary: Wire SAML or OIDC if the tenant requires it. Most pilots defer.
Action: Tenant provides metadata URL. We configure in Admin → SSO.
Acceptance: A tenant user logs in via their IdP. If skipped, log "deferred — username/password for pilot."

First Week — Train, Wire, Scan¶

Goal by end of week: compliance officer trained, dialer integrated via deep-link config, first compliance scan reviewed.

W1.1 Compliance officer training (Day 2-3)¶

Summary: 60-minute walkthrough of the Compliance cluster surfaces with the tenant's compliance officer.
Action: Screen-share. Cover:
AuditTrail — every gate decision, statute, agent. Drill into a single audit_id.
ComplianceCoverage — channel-by-channel green/yellow/red across voice/SMS/email/payment.
WeeklyReview — what the report covers, who it's mailed to (default: Compliance Director + Executive).
How to dispute a block (annotate the audit row, route to IT for data fix).
Acceptance: Compliance officer can independently pull an audit row, cite the statute, and explain it to a hypothetical regulator. Record the rehearsed quote.

W1.2 Dialer integration via deep-link config (Day 3-4)¶

Summary: Wire the tenant's dialer to call our gate before every dial AND configure the per-vendor deep-link button so agents jump from Floor OS into the dialer in one click.
Action — Gate: In the dialer's pre-dial hook, call POST /api/v1/compliance/contact-check. On allowed=true, proceed and keep audit_id in the call record. On hangup, POST outcome to /api/v1/webhooks/{five9|twilio|convoso|generic}/{tenant_id}. Set HMAC secret in dialer_config row or env var.
Action — Deep-link config: Settings → Vendors → (vendor card) → Quick Access section → toggle Enable. Set URL template (e.g. Five9: https://app.five9.com/agent?lead={{phone_e164}}), label, category (auto-fills requires_gate for voice/sms/payment), sort order. Save.
Acceptance: Test dial on a known-blocked account returns allowed=false with the correct statute and the dialer refuses to dial. Test dial on a clean account → allowed=true, call connects, outcome arrives within 60 seconds. Agent on AccountDetail sees the "Open in " button at the top of the action bar; clicking it fires the gate first, then opens the URL only on allow.
Reference: CRM_WEBHOOK_INTEGRATION.md § Endpoints + Deep-Link Contract.

W1.3 SMS / email / payment hooks (Day 4-5, if in scope)¶

Summary: Same gate-then-act pattern as voice, for any other channel the tenant uses.
Action: Wrap each channel's send function with POST /api/v1/compliance/contact-check?channel={sms|email|payment}. Block on negative responses. POST outcomes back.
Acceptance: Per channel, one blocked test and one allowed test reach the audit log with matching outcome rows. Channels not in pilot scope: mark "N/A — deferred" in the onboarding log.

W1.4 First full compliance scan (Day 5-6)¶

Summary: Tenant uploads their full portfolio (typical pilot: 5K-50K accounts) and we walk the intake report together.
Action: Portfolio → Import → full CSV. Scan runs collections_pkg/ingestion/intake_scan.py. Review the output with the compliance officer screen-to-screen.
Acceptance: For each top-5 block reason, the officer says one of: "yes, we want enforcement" / "data quality issue, we'll fix our CRM" / "let's discuss." At least one block is confirmed as "we would have dialed this — that's a save." Capture the verbatim quote.

W1.5 Shadow mode flip (Day 6)¶

Summary: Gate runs and logs but doesn't enforce. Collect 24-72 hours of "what would have been blocked" data.
Action: Admin → Compliance → Enforcement → Shadow.
Acceptance: Shadow banner visible. Compliance event log fills with decisions. No tenant-side enforcement.

W1.6 Compliance gap report + flip to enforce (Day 7)¶

Summary: Generate the gap report from shadow data, walk it with the compliance officer, then flip enforcement ON.
Action: Reports → Compliance Gap → last 72h. Export CSV + PDF. Officer signs. Admin → Compliance → Enforcement → Enforce.
Acceptance: Report lists every block that would have happened, grouped by statute, with sample account_id + phone_number + agent_id. Officer signature on file. First production block in compliance_event_log within 2 hours of flipping.

First Month — Stabilize, Measure, Decide¶

Goal by end of month: weekly compliance review cadence is steady, usage stats inform the continuation decision.

M1.1 Weekly compliance reviews (Days 8, 15, 22, 29)¶

Summary: Recurring 30-minute meeting. Compliance Director + Officer + our implementation engineer.
Agenda: Last week's ComplianceCoverage, top 5 block reasons, any state-level regulatory changes, any rule-database updates from us, any CFPB / AG / FTC news in the tenant's markets.
Acceptance: Four reviews held. Minutes in tenant's shared folder. Action items closed within the following week.

M1.2 Usage stats — gathered weekly, summarized at Day 30¶

Summary: Track adoption + value delivered per persona.
Metrics to gather (weekly snapshot):
Number of gate calls per channel
Block rate per channel + per statute (trending — should stabilize after Week 2)
Number of distinct active users per cluster (Compliance / Operations / Support)
Agent queue throughput vs. pre-Floor-OS baseline (if tenant shares it)
Number of audit-log drilldowns per week (proxy for compliance officer engagement)
Webhook delivery success rate (target ≥99.5%)
Mean gate latency (target ≤120ms p95)
Acceptance: A one-page Day 30 readout with all metrics, trend arrows, and a recommended next step.

M1.3 Day 30 decision meeting¶

Summary: Tenant decides: continue (Day 31+), expand (more channels / more users), or pause.
Action: Walk the Day 30 readout with the tenant's economic buyer (usually the COO or VP Collections). Present the renewal terms (founding-partner discount if they signed in the first cohort).
Acceptance: Written decision in the tenant's contract folder. If continuing, the Day 31-60 plan is dated. If pausing, exit interview captured.

M1.4 Day 60 — Expansion checkpoint (forward-looking)¶

Summary: If continuing: which deferred surfaces (Coaching, QA, Training, SMS Center) light up next?
Acceptance: Roadmap dated. New SOWs signed if any added scope.

M1.5 Day 90 — Steady state¶

Summary: Engagement is no longer "onboarding." Implementation engineer hands off to support cadence (monthly check-ins, quarterly business review).
Acceptance: Handoff doc signed by both sides. Monthly check-in on calendar. QBR scheduled for end of Q.

Handoff to Steady-State¶

End-of-month deliverable to the tenant:

Signed integration inventory.
Signed compliance gap report (shadow mode).
API key + webhook secrets handed off to tenant's vault.
Runbook: fail-closed verification, rollback to shadow, who to page.
Recurring weekly compliance review on three calendars.
Day 30 usage readout with continuation decision logged.
Link to CRM_WEBHOOK_INTEGRATION.md for their dev team.
Link to DEMO_CHEAT_SHEET.md for any internal champion presenting Floor OS to other teams.

If onboarding slips, the block is usually First Week dialer wiring or First Week deep-link config. Re-read CRM_WEBHOOK_INTEGRATION.md with the tenant's dev team before escalating.