Floor OS — Pilot Agency Onboarding Guide¶

Step-by-step implementation for 90-day pilot agencies Werner Harmonic Labs LLC | Internal Use Only

Overview¶

This guide walks through onboarding a new pilot agency from zero to live. Typical timeline: 2-3 weeks from signed pilot agreement to first governed collection action.

Pilot includes: - Full Professional tier features for 90 days - Dedicated implementation engineer - Data migration assistance - Weekly check-in calls for first 30 days

Phase 1: Initial Setup (Days 1-3)¶

1.1 Environment Deployment¶

Docker deployment (recommended for pilots):

# Pull the Floor OS image
docker pull registry.wernerharmoniclabs.com/floor-os:latest

# Create environment file
cp .env.template .env.pilot

# Required environment variables
FLOOROS_TENANT_ID=<agency-slug>
FLOOROS_TENANT_NAME=<agency-display-name>
DB_ENGINE=postgres
DATABASE_URL=postgresql://<user>:<pass>@<host>:5432/flooros_<agency>
FLOOROS_SECRET_KEY=<generated-256-bit-key>
FLOOROS_ENCRYPTION_KEY=<generated-256-bit-key>
WHL_SCAR_HMAC_KEY=<generated-256-bit-key>
FLOOROS_DEMO_MODE=0

# Optional — external service integrations (configure later)
FIVE9_API_KEY=
CONVOSO_API_KEY=
STRIPE_SECRET_KEY=
TWILIO_ACCOUNT_SID=
TWILIO_AUTH_TOKEN=

# Start the stack
docker compose -f docker-compose.prod.yaml up -d

Verify deployment:

# Health check
curl http://localhost:9033/api/health

# Expected response:
# {"status": "healthy", "version": "...", "uptime_seconds": ...}

1.2 Database Initialization¶

The database schema auto-creates on first startup. Verify tables:

# Check table count (should be 20+)
curl http://localhost:9033/api/monitoring/db-stats

1.3 Admin User Setup¶

Create the initial admin user for the agency:

curl -X POST http://localhost:9033/api/auth/setup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@agency.com",
    "name": "Agency Administrator",
    "role": "admin",
    "password": "<strong-password>"
  }'

1.4 Verify Core Services¶

Run the startup verification checklist:

Service	Endpoint	Expected
Collections API	`GET /api/health`	`{"status": "healthy"}`
Governance Pipeline	`GET /api/governance/status`	`{"gates": 12, "active": true}`
Compliance Memory	`GET /api/compliance/memory/status`	`{"scars": 0, "active": true}`
Dashboard	`GET /api/dashboard/html`	HTML page loads
Monitoring	`GET /api/monitoring/dashboard`	HTML page loads

Phase 2: Creditor Configuration (Days 3-5)¶

2.1 Import Creditor Rules¶

Each creditor the agency works for has specific rules. Import them via API or CSV.

API method:

curl -X POST http://localhost:9033/api/creditor-rules \
  -H "Content-Type: application/json" \
  -d '{
    "creditor_id": "chase-bank",
    "rules": [
      {
        "rule_type": "settlement_floor",
        "rule_value": "0.40",
        "description": "Minimum settlement: 40% of balance"
      },
      {
        "rule_type": "max_contact_per_week",
        "rule_value": "5",
        "description": "Max 5 contact attempts per 7-day window"
      },
      {
        "rule_type": "allowed_channels",
        "rule_value": "[\"phone\",\"email\",\"sms\",\"letter\"]",
        "description": "All channels permitted"
      },
      {
        "rule_type": "reporting_frequency",
        "rule_value": "weekly",
        "description": "Weekly performance reports required"
      }
    ]
  }'

CSV method:

creditor_id,rule_type,rule_value,description
chase-bank,settlement_floor,0.40,Minimum settlement: 40% of balance
chase-bank,max_contact_per_week,5,Max 5 contact attempts per 7-day window
discover,settlement_floor,0.45,Minimum settlement: 45% of balance
discover,max_contact_per_week,4,Max 4 contact attempts per 7-day window
discover,allowed_channels,"[""phone"",""email"",""letter""]",No SMS permitted

2.2 Verify Creditor Rules Loaded¶

curl http://localhost:9033/api/creditor-rules?creditor_id=chase-bank

# Should return all rules for the creditor

2.3 Key Creditor Rule Types¶

Rule Type	Description	Example Value
`settlement_floor`	Minimum settlement percentage	`0.40`
`max_contact_per_week`	Weekly contact attempt limit	`5`
`allowed_channels`	Permitted contact channels	`["phone","email"]`
`reporting_frequency`	Required report schedule	`weekly`
`payment_plan_max_months`	Max installment plan length	`24`
`no_credit_reporting`	Suppress credit bureau reports	`true`
`hardship_review_threshold`	Auto-refer below this balance	`500`
`income_verification_required`	Require income docs for plans	`true`

Phase 3: Agent Setup (Days 5-7)¶

3.1 Import Agent Roster¶

CSV format for agent import:

agent_id,first_name,last_name,role,team,shift,supervisor,email,phone,skills
AGT001,Elena,Martinez,Senior Collector,Early Out,8:00-5:00,Mike Reynolds,elena.m@agency.com,(213) 555-0101,"spanish,high_balance,negotiation"
AGT002,Derek,Johnson,Collector II,Early Out,8:00-5:00,Mike Reynolds,derek.j@agency.com,(213) 555-0102,"ptp_follow_up,new_placement"
AGT003,Lisa,Chen,Senior Collector,Mid Stage,9:00-6:00,Sarah Kim,lisa.c@agency.com,(213) 555-0103,"medical_debt,hardship"

Import via API:

curl -X POST http://localhost:9033/api/agents/import \
  -F "file=@agent_roster.csv"

3.2 Assign Skills¶

Skills drive the task queue optimizer. Common skill tags:

Skill	Description
`spanish`	Spanish language fluency
`high_balance`	Trained for $10K+ accounts
`negotiation`	Advanced negotiation training
`medical_debt`	Medical debt regulations (HIPAA, No Surprises Act)
`student_loan`	Student loan regulations (HEA, Borrower Defense)
`settlement`	Settlement authority and training
`skip_trace`	Skip trace analysis and research
`compliance`	Compliance review and QA
`legal_prep`	Legal escalation preparation
`hardship`	Hardship review and documentation

3.3 Create Teams¶

curl -X POST http://localhost:9033/api/teams \
  -H "Content-Type: application/json" \
  -d '{
    "teams": [
      {"name": "Early Out", "manager": "Mike Reynolds"},
      {"name": "Mid Stage", "manager": "Sarah Kim"},
      {"name": "Late Stage", "manager": "Tom Bradley"},
      {"name": "Recovery", "manager": "Diana Cross"},
      {"name": "Settlement", "manager": "Mike Reynolds"},
      {"name": "Skip/Legal", "manager": "Tom Bradley"},
      {"name": "Compliance", "manager": "Diana Cross"}
    ]
  }'

Phase 4: Account Import (Days 7-10)¶

4.1 CSV Format Specification¶

Floor OS accepts accounts in the following CSV format. All fields except account_id, debtor_name, and balance are optional.

Required fields:

Field	Type	Description
`account_id`	string	Unique account identifier (your internal ID)
`debtor_name`	string	Consumer full name
`balance`	float	Current balance owed

Recommended fields:

Field	Type	Description
`state`	string	Consumer state (2-letter code) — required for state law compliance
`creditor_id`	string	Creditor identifier (must match creditor rules)
`debt_type`	string	`credit_card`, `medical`, `auto`, `student`, `other`
`original_amount`	float	Original debt amount at placement
`age_days`	integer	Days since placement / charge-off
`status`	string	`active`, `payment_plan`, `settled`, `disputed`, `ceased`, `legal`, `bankruptcy`
`phone`	string	Primary phone number
`email`	string	Email address

Optional fields:

Field	Type	Description
`principal_remaining`	float	Principal balance remaining
`interest_accrued`	float	Accrued interest
`late_fees`	float	Late fee balance
`other_fees`	float	Other fee balance
`cost_basis`	float	What the agency paid for the debt
`ssn_last4`	string	Last 4 of SSN (encrypted at rest)
`dob`	string	Date of birth (YYYY-MM-DD, encrypted at rest)
`address`	string	Consumer mailing address
`city`	string	City
`zip`	string	ZIP code

4.2 Field Mapping¶

If the agency's export format does not match Floor OS field names, configure field mapping:

curl -X POST http://localhost:9033/api/accounts/field-mapping \
  -H "Content-Type: application/json" \
  -d '{
    "mappings": {
      "Account Number": "account_id",
      "Consumer Name": "debtor_name",
      "Current Balance": "balance",
      "State Code": "state",
      "Client Code": "creditor_id",
      "Placement Date": "placement_date",
      "Original Balance": "original_amount"
    }
  }'

4.3 Import Accounts¶

# Import via CSV upload
curl -X POST http://localhost:9033/api/accounts/import \
  -F "file=@accounts_export.csv"

# Verify import
curl http://localhost:9033/api/queue/stats

4.4 Post-Import Validation¶

After import, Floor OS runs automatic validation:

Duplicate detection (matching on name + SSN last 4 + balance)
State code validation (all 50 states + DC + territories)
Balance sanity check (negative balances, zero balances flagged)
Deceased check against SSA Death Master File (if configured)
SCRA check against DOD DMDC (if configured)
Statute of limitations calculation per state

Review validation results:

curl http://localhost:9033/api/accounts/import/validation-report

Phase 5: Dialer Integration (Days 10-12)¶

5.1 Five9 Setup¶

curl -X POST http://localhost:9033/api/integrations/configure \
  -H "Content-Type: application/json" \
  -d '{
    "connector_id": "five9",
    "display_name": "Five9 Dialer",
    "connector_type": "dialer",
    "credentials": {
      "api_key": "<your-five9-api-key>",
      "client_id": "<your-five9-client-id>",
      "endpoint": "https://api.five9.com/wsadmin/v12"
    },
    "field_mapping": {
      "agent_id": "agent_id",
      "disposition": "disposition",
      "talk_time": "talk_time",
      "campaign": "campaign"
    },
    "enabled": true
  }'

5.2 Convoso Setup¶

curl -X POST http://localhost:9033/api/integrations/configure \
  -H "Content-Type: application/json" \
  -d '{
    "connector_id": "convoso",
    "display_name": "Convoso Dialer",
    "connector_type": "dialer",
    "credentials": {
      "api_key": "<your-convoso-api-key>",
      "client_id": "<your-convoso-client-id>",
      "endpoint": "https://api.convoso.com/v1"
    },
    "field_mapping": {
      "agent_id": "agent_id",
      "disposition": "disposition",
      "talk_time": "talk_time",
      "campaign": "campaign"
    },
    "enabled": true
  }'

5.3 Test Connection¶

curl -X POST http://localhost:9033/api/integrations/five9/test

# Expected: {"status": "connected", "latency_ms": ...}

5.4 Webhook Configuration¶

Set up dialer webhooks so Floor OS receives real-time call disposition data:

Five9 webhook URL: https://<your-floor-os-url>/api/dialer-webhooks/five9 Convoso webhook URL: https://<your-floor-os-url>/api/dialer-webhooks/convoso

Configure in your dialer's admin panel to POST call events to these URLs.

Phase 6: Compliance Policy Setup (Days 12-14)¶

6.1 Write First CPL Policies¶

These are the essential policies every agency should start with. Your compliance officer can customize them.

Policy 1 — Reg F 7-in-7:

RULE reg_f_contact_limit
  WHEN contact_attempts_7day >= 7
  THEN BLOCK contact
  REASON "Reg F 7-in-7 limit reached"
  SEVERITY high
END

Policy 2 — State time-of-day restrictions:

RULE time_of_day
  WHEN local_hour < 8 OR local_hour >= 21
  THEN BLOCK call
  REASON "FDCPA/state law: calls restricted to 8AM-9PM local"
  SEVERITY critical
END

Policy 3 — Cease and desist enforcement:

RULE cease_desist
  WHEN account.status = "ceased"
  THEN BLOCK ALL contact
  REASON "Cease and desist on file"
  SEVERITY critical
  PERMANENT true
END

Policy 4 — Mini-Miranda required:

RULE mini_miranda
  WHEN action = "call" AND is_initial_contact = true
  THEN REQUIRE disclosure "mini_miranda"
  REASON "FDCPA 1692e(11): initial communication must include Mini-Miranda"
  SEVERITY high
END

Policy 5 — Settlement floor enforcement:

RULE settlement_floor
  WHEN action = "settlement_offer"
  AND offer_percentage < creditor.settlement_floor
  THEN BLOCK settlement
  REASON "Offer below creditor minimum floor"
  ESCALATE supervisor
  SEVERITY medium
END

6.2 Deploy Policies¶

curl -X POST http://localhost:9033/api/policy-language/deploy \
  -H "Content-Type: application/json" \
  -d '{
    "policies": [
      {"name": "reg_f_contact_limit", "cpl": "..."},
      {"name": "time_of_day", "cpl": "..."},
      {"name": "cease_desist", "cpl": "..."},
      {"name": "mini_miranda", "cpl": "..."},
      {"name": "settlement_floor", "cpl": "..."}
    ]
  }'

6.3 Test Policies¶

Run a test evaluation to verify policies are active:

curl -X POST http://localhost:9033/api/demo/simulate?account_id=<test-account>

Phase 7: Go-Live Checklist (Day 14)¶

Pre-Launch Verification¶

Complete all 10 items before the first agent logs in:

#	Item	Verification Command	Expected
1	Database healthy	`GET /api/health`	`status: healthy`
2	All accounts imported	`GET /api/queue/stats`	Account count matches source
3	All agents in roster	`GET /api/agents/sync-manifest`	Agent count matches roster
4	Creditor rules loaded	`GET /api/creditor-rules`	Rules for each creditor
5	Dialer connected	`POST /api/integrations/<dialer>/test`	`status: connected`
6	CPL policies active	`GET /api/policy-language/active`	5+ policies deployed
7	Governance pipeline passing	`POST /api/demo/simulate`	12 gates evaluated
8	Compliance memory initialized	`GET /api/compliance/memory/status`	`active: true`
9	Admin can access dashboard	Browser: `/api/dashboard/html`	Dashboard loads with data
10	Audit trail recording	`GET /api/audit/recent`	Recent entries visible

Go-Live Communication¶

Send to agency management:

Floor OS is live for [Agency Name].

Dashboard: https://[url]/api/dashboard/html

Agent count: [N] agents configured

Account count: [N] accounts loaded

Creditors: [list]

Governance: 12-gate pipeline active

Compliance policies: [N] rules enforcing

First 30 days: weekly check-in calls every [day] at [time]. Support: support@wernerharmoniclabs.com

Phase 8: 30/60/90 Day Success Metrics¶

30-Day Review¶

Metric	Target	How to Measure
System uptime	>99.5%	`GET /api/monitoring/uptime`
Governance evaluations/day	>100	`GET /api/monitoring/gate-stats`
Compliance events caught	>0	`GET /api/compliance/events`
Agent adoption rate	>80% agents logging in daily	`GET /api/monitoring/agent-activity`
Blocked actions	Review for false positives	`GET /api/governance/blocked-actions`
RPC rate baseline	Establish pre-Floor OS baseline	`GET /api/reports/rpc-trend`

30-day check-in agenda: 1. Review system health and uptime 2. Review compliance events caught (the wins) 3. Review blocked actions for false positive tuning 4. Gather agent feedback 5. Adjust CPL policies based on first month experience 6. Plan 60-day feature rollout (Dreamer, advanced CPL)

60-Day Review¶

Metric	Target	How to Measure
RPC rate improvement	>10% over baseline	`GET /api/reports/rpc-trend`
Compliance event reduction	Downward trend	`GET /api/compliance/events/trend`
Settlement acceptance rate	>5% improvement	`GET /api/reports/settlement-trend`
Agent satisfaction	Net positive feedback	Survey
CPL policies in production	10+ rules active	`GET /api/policy-language/active`
Portfolio Dreamer insights	>5 actionable insights generated	`GET /api/dreamer/insights`

60-day check-in agenda: 1. Present ROI analysis (complaints prevented, efficiency gains) 2. Review Portfolio Dreamer insights and actions taken 3. Demo advanced CPL rules based on agency-specific needs 4. Plan compliance memory demonstration for management 5. Discuss Enterprise tier upgrade if applicable 6. Prepare 90-day conversion proposal

90-Day Review (Conversion Decision)¶

Metric	Target	How to Measure
Total ROI	Positive (savings > cost)	ROI calculator
Complaints prevented	>0 attributable to Floor OS	Compliance event log
RPC improvement	>15% over baseline	Trend analysis
Agent productivity	>10% more accounts worked/day	Productivity report
Compliance audit readiness	Full audit trail available	One-click export test
Management satisfaction	Buy signal	Verbal confirmation

90-day conversion meeting agenda: 1. Full ROI presentation 2. Comparison: before Floor OS vs. after 3. Compliance events prevented (with dollar values) 4. Agent testimonials 5. Pricing proposal for ongoing subscription 6. Implementation timeline for full production deployment 7. Contract review and signature

Appendix A: Troubleshooting¶

Common Issues¶

Issue	Diagnosis	Fix
Dashboard not loading	Check API health	`docker compose logs floor-os`
Dialer not syncing	Check webhook URL	Verify URL is reachable from dialer network
Accounts not importing	CSV format mismatch	Check field mapping configuration
Governance blocking everything	CPL rules too strict	Review and loosen `SEVERITY` levels
Slow performance	Database needs indexing	`POST /api/monitoring/optimize-db`

Support Contact¶

Email: support@wernerharmoniclabs.com
Response time: <4 hours during business hours
Emergency: Dedicated Slack channel (created during onboarding)

Appendix B: Data Migration Checklist¶

When migrating from another platform (Latitude, DAKCS/iA, Finvi, Columbia Ultimate):

Export full account inventory as CSV
Export agent roster
Export creditor rules / client SLA documents
Export disposition history (last 12 months)
Export payment history (last 12 months)
Export compliance event log
Map fields to Floor OS schema (see Phase 4)
Import in order: creditors -> agents -> accounts -> history
Validate record counts match source system
Run parallel operation for 1-2 weeks before cutting over

Werner Harmonic Labs LLC — Governed Collections Intelligence Internal Use Only. Not for distribution to pilot agencies.