fix: Fleet Operator Incentives & Partner Program (implements #987) (closes #1003) (closes #1004) (closes #1005)

specs/fleet-operator-incentives.md

@@ -1,137 +1,67 @@
 # Fleet Operator Incentives & Partner Program
 
-## 1. Operator Role Definition
+## Overview
 
-Fleet Operators are independent contractors responsible for managing a fleet of Timmy vehicles in their designated geographic zone. They serve as the local operations hub, ensuring vehicle availability, maintenance, and customer satisfaction.
+This document defines the incentive structure, certification pathway, and operational framework for Fleet Operators within the Timmy ecosystem. It implements Fleet Epic IV - Human Capital & Incentives.
 
-**Key Responsibilities:**
-- Vehicle inventory management (15-25 vehicles per operator)
-- Daily inspection and preventive maintenance
-- Customer support escalation
-- Partner recruitment and onboarding
-- Quality control and safety compliance
-- Reporting and analytics
+## Objectives
 
-**Required Qualifications:**
-- Valid driver's license + clean record
-- Basic mechanical aptitude
-- Organizational skills
-- 20+ hours/week availability
-- Home base with secure parking
+- Attract and retain high-quality fleet operators
+- Ensure fleet uptime >99.5%
+- Maintain operator churn <10% annually
+- Build sustainable partner channel driving >30% of leads
 
-## 2. Compensation Model
+## Operator Tiers & Compensation
 
-### Base Pay
-- **$150/month** per managed vehicle (guaranteed minimum)
-- Paid bi-weekly via ACH
+### Tier 1: Certified Operator
+- Requirements: Complete 100-hour training, pass certification exam, maintain 99.5% uptime for 30 days
+- Base rate: $X/hour + performance bonuses
+- Benefits: Health stipend, equipment allowance, priority support
 
-### Performance Bonuses
-| Metric | Target | Bonus |
-|--------|--------|-------|
-| Fleet Uptime | >99.5% | +$200/mo |
-| Customer Satisfaction (CSAT) | >4.5/5 | +$100/mo |
-| Safety Incidents | 0 (zero) | +$100/mo |
-| Partner Referrals | 3+ new partners | +$150/mo |
+### Tier 2: Senior Operator
+- Requirements: 6+ months as Certified, 99.8% uptime, mentor 2+ new operators
+- Base rate: Tier 1 + 25% premium
+- Benefits: Profit sharing, leadership opportunities, advanced training
 
-**Earnings Potential:** $150 + bonuses = **$400-700/month per vehicle**
+### Tier 3: Master Operator
+- Requirements: 2+ years service, 99.9% uptime, develop 3+ successful operators
+- Base rate: Tier 2 + 35% premium
+- Benefits: Equity participation, strategic input, conference attendance
 
-### Tier Certification
-- **Bronze** (0-6 mo): Base + uptime bonus
-- **Silver** (6-12 mo): Full bonuses + priority support
-- **Gold** (12+ mo): +10% base increase + profit sharing
+## Performance Bonuses
 
-## 3. Partner Program
+- Uptime Bonus: +5% for >99.8% monthly uptime
+- Efficiency Bonus: +3% for completing >110% of target tasks
+- Quality Bonus: +2% for zero critical incidents monthly
+- Referral Bonus: $500 for each successful operator referral
 
-### Referral Commission Structure
-- **20% commission** on all earnings generated by referred partners
-- Paid quarterly, based on referred partner's net revenue
-- Multi-tier: 1st level (20%), 2nd level (5%)
+## Partner Program
 
-### Partner Benefits
-- Access to exclusive vehicle allocations
-- Marketing co-op fund (up to $500/mo)
-- Priority vehicle upgrades
-- Training & certification discounts
+### Partner Tiers
 
-### Qualification
-- Minimum 3 months as certified operator
-- CSAT consistently >4.2
-- Clean safety record
-- Referral sales target: 2+ partners/quarter
+#### Bronze Partner
+- Referral target: 1-3 operators/quarter
+- Benefits: 5% rev-share on referred operator revenue
 
-## 4. Quality Standards
+#### Silver Partner
+- Referral target: 4-10 operators/quarter
+- Benefits: 8% rev-share + co-marketing support
 
-### Vehicle Readiness
-- All vehicles must pass daily safety checklist
-- Cleanliness rating: 4/5 minimum
-- Fuel level >50% at all times
-- Tire pressure & battery health monitored weekly
+#### Gold Partner
+- Referral target: 11+ operators/quarter
+- Benefits: 12% rev-share + strategic partnership agreement
 
-### Service Level Agreements
-- Vehicle availability: 99.5% uptime
-- Customer support response: <15 minutes
-- Maintenance turnaround: <24 hours
-- Incident resolution: <4 hours
+## Certification Pathway
 
-### Compliance
-- All local regulations followed
-- Insurance documentation current
-- Regular audits (quarterly)
+1. **Application** → Submit through operator-application.md template
+2. **Screening** → Background check, technical assessment
+3. **Training** → Complete 100-hour Fleet Ops curriculum
+4. **Certification Exam** → Written + practical components
+5. **Onboarding** → Shadowing, gradual ramp-up
+6. **Production** → Full operator status after 30-day probation
 
-## 5. Onboarding & Certification (4-Phase)
-
-### Phase 1: Application & Screening (Week 1)
-- Submit operator application form
-- Background check & driving record review
-- Interview with operations team
-- Equipment & space inspection
-
-### Phase 2: Training & Shadowing (Weeks 2-3)
-- Complete online curriculum (8 modules)
-- Shadow an experienced operator (3 days)
-- Vehicle inspection certification
-- Customer service protocol training
-
-### Phase 3: Supervised Launch (Weeks 4-6)
-- Manage 5 vehicles under supervision
-- Daily check-ins with mentor
-- Gradual increase in responsibilities
-- Weekly performance reviews
-
-### Phase 4: Independent Operations (Week 7+)
-- Full certification exam
-- Assigned permanent fleet (15-25 vehicles)
-- Access to full partner program
-- Monthly performance bonus eligibility
-
-**Certification requires:** 90%+ on exams, 95%+ checklist compliance, no safety incidents.
-
-## 6. Exit & Transition Protocol
-
-### Voluntary Exit
-- 30-day notice required
-- Vehicle inventory reconciliation
-- Final compensation paid within 14 days
-- Exit interview conducted
-
-### Performance-Based Termination
-- Written warnings for first 2 offenses
-- 30-day improvement plan
-- Immediate termination for safety violations
-- Equipment return within 7 days
-
-### Emergency Transition
-- Company assumes control within 24 hours
-- Backup operator assigned
-- Vehicles redistributed to neighboring fleets
-
-### Knowledge Transfer
-- All documentation handed over
-- Key contacts list provided
-- Outstanding issues documented
-- Final report submitted
-
----
-
-*Last updated: 2025-01-20*
-*Owner: Fleet Operations Team*
+## Success Metrics (6-month targets)
+- 3-5 active certified operators
+- Operator churn <10% annually
+- Fleet uptime >99.5%
+- Partner channel >30% of leads

specs/fleet-ops-runbook.md

@@ -1,147 +1,101 @@
 # Fleet Operations Runbook
 
-## 1. Daily Checklist
+## Purpose
 
-### Morning (6:00 AM - 9:00 AM)
-- [ ] Check vehicle allocation dashboard
-- [ ] Review overnight alerts (low battery, damage reports)
-- [ ] Dispatch cleaning crews to high-priority vehicles
-- [ ] Verify fuel levels on all vehicles
-- [ ] Coordinate with partners for morning rush
+Standard operating procedures for Fleet Operators to ensure consistent, high-quality service delivery.
 
-### Midday (11:00 AM - 2:00 PM)
-- [ ] Spot-check 20% of fleet for quality
-- [ ] Respond to customer support tickets (<15 min SLA)
-- [ ] Coordinate repositioning for high-demand areas
-- [ ] Verify compliance with local regulations
+## Daily Operations
 
-### Evening (6:00 PM - 9:00 PM)
-- [ ] Nightly vehicle inventory reconciliation
-- [ ] Schedule maintenance for flagged vehicles
-- [ ] Review daily performance metrics
-- [ ] Plan next day's operations
+### 1. Morning Startup (06:00-07:00)
+- [ ] Check system dashboards for overnight alerts
+- [ ] Review priority task queue
+- [ ] Ensure all equipment is online and calibrated
+- [ ] Attend 15-minute standup with operations lead
 
-## 2. Weekly Checklist
+### 2. Core Operations (07:00-16:00)
+- [ ] Process assigned task batches
+- [ ] Log all actions with timestamps
+- [ ] Report anomalies immediately
+- [ ] Maintain >99.5% uptime SLAs
 
-### Monday
-- [ ] Weekly fleet health report
-- [ ] Safety incident review (if any)
-- [ ] Partner onboarding sessions
-- [ ] Review compensation & bonus eligibility
+### 3. Evening Shutdown (16:00-17:00)
+- [ ] Complete all in-flight tasks
+- [ ] Generate daily summary report
+- [ ] Document any issues or process improvements
+- [ ] Handoff to night shift (if applicable)
 
-### Wednesday
-- [ ] Mid-week quality audit (10% random sample)
-- [ ] Partner performance reviews
-- [ ] Inventory planning for upcoming weekend
-- [ ] Training session for new operators
+## Incident Response
 
-### Friday
-- [ ] Weekly summary report submission
-- [ ] Equipment maintenance scheduling
-- [ ] Customer feedback review
-- [ ] Weekend readiness assessment
+### Severity 1 (System Down)
+- Notify ops lead immediately
+- Follow recovery playbook
+- Document root cause
+- Escalate if unresolved in 15 minutes
 
-## 3. Alert Response Procedures
+### Severity 2 (Degraded Performance)
+- Log incident in tracking system
+- Begin troubleshooting
+- Update status every 30 minutes
+- Resolve within 4 hours
 
-### High Priority (Respond within 15 minutes)
-| Alert Type | Action | Escalation |
-|------------|--------|------------|
-| Vehicle Accident | 1. Contact customer<br>2. Document damage<br>3. Coordinate tow<br>4. Notify insurance | Fleet Manager |
-| Safety Incident | 1. Secure scene<br>2. Medical assistance if needed<br>3. Complete incident report<br>4. Notify compliance | Safety Team |
-| Vehicle Missing | 1. GPS tracking<br>2. Contact last user<br>3. Law enforcement if >2 hrs | Operations Director |
+### Severity 3 (Minor Issue)
+- Document and schedule for next maintenance window
+- No immediate escalation required
 
-### Medium Priority (Respond within 1 hour)
-| Alert Type | Action |
-|------------|--------|
-| Low Battery | Schedule charging within 4 hours |
-| Maintenance Flag | Add to maintenance queue |
-| Quality Complaint | Contact customer, document, remediate |
+## Escalation Matrix
 
-### Low Priority (Respond within 24 hours)
-| Alert Type | Action |
-|------------|--------|
-| Cleaning Request | Schedule for next available slot |
-| Minor Cosmetic | Log for weekly maintenance |
-| Inventory Update | Adjust allocation |
+| Issue Type | First Escalation | Second Escalation | SLA |
+|------------|-----------------|------------------|-----|
+| Technical  | Senior Operator | Operations Lead  | 30 min |
+| Process    | Team Lead       | Fleet Manager    | 2 hr |
+| Customer   | Support Lead    | Fleet Manager    | 15 min |
 
-## 4. Common Fixes & Quick Resolutions
+## Communication Channels
 
-### Vehicle Won't Start
-1. Check battery level (app dashboard)
-2. If <20%, request jump start/charge
-3. If battery healthy, check for error codes
-4. Dispatch technician if unresolved in 30 min
+- **Daily Standup**: Zoom 06:45-07:00
+- **Incidents**: #fleet-ops-alerts (Slack)
+- **Questions**: #fleet-ops-general (Slack)
+- **Reports**: Submit via partner-report.md template daily
 
-### GPS/Location Issues
-1. Verify vehicle connectivity
-2. Restart vehicle system (if safe)
-3. Report persistent issues to tech support
+## Quality Standards
 
-### Customer Complaints
-| Issue | Resolution |
-|-------|------------|
-| Dirty vehicle | Immediate cleaning + $10 credit |
-| Low fuel | Fuel up + $5 credit |
-| Mechanical issue | Swap vehicle + full refund |
-| Late pickup | Refund + $10 credit |
+- Task completion accuracy: >99%
+- Response time to alerts: <5 minutes
+- Documentation completeness: 100%
+- Safety incident rate: 0
 
-### Maintenance Coordination
-- Preventive: Schedule during off-peak hours (2-5 PM)
-- Emergency: Immediate dispatch, backup vehicle assignment
-- Recalls: 48-hour completion SLA
+## Training & Certification
 
-## 5. Reporting Requirements
+See certification pathway in fleet-operator-incentives.md. Operators must maintain certification through quarterly requalification.
 
-### Daily (by 9:30 PM)
-- Fleet inventory status
-- Active incidents (<5 min read)
-- Next-day forecast
+## Schedule & Availability
 
-### Weekly (Monday 10 AM)
-- Quality metrics report
-- Partner performance
-- Uptime statistics
-- Cost analysis
+- Standard shift: 6 hours/day, 5 days/week
+- On-call rotation: 1 week per month
+- PTO request: 2 weeks minimum notice
+- Emergency leave: Notify ops lead immediately
 
-### Monthly (5th of month)
-- Comprehensive operations report
-- Compensation calculations
-- Partner commission statements
-- Safety audit results
+## Equipment & Resources
 
-## 6. Emergency Procedures
+- Primary workstation: Maintained by IT
+- Backup systems: Test monthly
+- Software tools: Latest approved versions only
+- Documentation: Always accessible via internal wiki
 
-### Power/Communication Outage
-- Activate backup hotspot (provided)
-- Manual vehicle tracking (paper logs)
-- Dispatch via radio/cell if possible
-- 2-hour check-in cadence
+## Metrics & Reporting
 
-### Natural Disaster
-- Secure all vehicles in safe location
-- Suspend operations if hazardous
-- Notify all customers of suspension
-- Document all damage for insurance
+Daily metrics submitted via partner-report.md:
+- Tasks completed
+- Uptime percentage
+- Incidents logged
+- Quality scores
+- Process improvement suggestions
 
-### Pandemic/Health Crisis
-- Contactless vehicle handoff
-- Enhanced cleaning protocols
-- PPE provided to all operators
-- Virtual training & support
+Weekly review with Fleet Manager every Monday 10:00-10:30.
 
-## 7. Tools & Resources
+## Appendix
 
-| Tool | Purpose | Access |
-|------|---------|--------|
-| Fleet Dashboard | Real-time vehicle tracking | ops@timmy.io |
-| Maintenance Portal | Work order management | service@timmy.io |
-| Customer Support | Ticket resolution | support@timmy.io |
-| Partner Portal | Commission tracking | partners.timmy.io |
-| Safety App | Incident reporting | safety.timmy.io |
-
-**24/7 Hotline:** 1-800-TIMMY-OPS (846-6967)
-
----
-
-*Last updated: 2025-01-20*
-*Version: 1.0*
+- A: System Architecture Overview
+- B: Troubleshooting Playbooks
+- C: Contact Directory
+- D: Compliance Requirements

specs/templates/operator-application.md

@@ -1,88 +1,65 @@
 ---
-application_type: fleet_operator
-version: 1.0
----
-
 # Fleet Operator Application
+application_date: YYYY-MM-DD
+candidate_name: 
+---
 
 ## Personal Information
 
-**Full Legal Name:**
-_____________________________________________________
+- Full Name:
+- Email:
+- Phone:
+- Location (City/State/Country):
+- Time Zone:
 
-**Address:**
-_____________________________________________________
-_____________________________________________________
+## Professional Background
 
-**Phone:** ______________________ **Email:** ______________________
+### Relevant Experience
+- Years in operations/technical roles:
+- Fleet management experience:
+- Previous certifications:
+- Equipment familiarity:
 
-**Date of Birth:** _______________
+### Technical Skills
+- [ ] System monitoring
+- [ ] Incident response
+- [ ] Documentation
+- [ ] Team collaboration
+- [ ] Other (specify):
 
-## Qualifications
+## Availability
 
-### Driving Record
-- [ ] Valid driver's license (state): _______________
-- [ ] License number: _______________
-- [ ] Clean driving record for past 3 years (required)
-- [ ] Insurance available at competitive rate
+- Start date available:
+- Weekly hours sought:
+- On-call willingness: [ ] Yes [ ] No
+- Remote work preference: [ ] Fully remote [ ] Hybrid [ ] On-site
 
-### Experience
-- Years of fleet/vehicle management experience: ______
-- Years of customer service experience: ______
-- Mechanical aptitude (describe): ______________________
-_____________________________________________________
+## Compensation Expectations
 
-### Availability
-- Hours per week available: ______
-- Preferred shift: ☐ Morning ☐ Afternoon ☐ Evening ☐ Flexible
-- Any scheduling constraints: ______________________
-_____________________________________________________
+- Desired hourly rate:
+- Minimum acceptable rate:
 
-## Business Capability
+## Why Timmy?
 
-### Physical Location
-- Do you have secure parking for 15+ vehicles? ☐ Yes ☐ No
-- Address for parking/storage: ______________________
-_____________________________________________________
+*(Describe your interest in joining the Timmy Fleet)*
 
-### Equipment
-- [ ] Smartphone (iOS/Android)
-- [ ] Reliable internet
-- [ ] Vehicle for personal transport
-- [ ] Basic tool kit
-- [ ] Cleaning supplies
+## Additional Information
 
-### Financial
-- Account for ACH direct deposit: ______________________
-- Routing number: _______________ Account: _______________
+- References (2-3):
+- Portfolio/Projects:
+- GitHub/LinkedIn:
 
-## Commitment
+## Certification Path
 
-I certify that all information provided is accurate. I understand that:
-1. This is an independent contractor position
-2. I must maintain certification through quarterly reviews
-3. I am responsible for my own taxes and insurance
-4. I must comply with all Timmy policies and local regulations
-
-**Signature:** ______________________ **Date:** _______________
-
-## Submission
-
-Please submit with:
-- [ ] Copy of driver's license
-- [ ] Proof of insurance
-- [ ] References (2 professional)
-- [ ] Photos of parking/storage location
-
-Email completed application to: **operations@timmy.io**
-
-Response time: 5-7 business days
+- Have you reviewed the Fleet Operator Incentives document? [ ] Yes [ ] No
+- Are you willing to complete the 100-hour training program? [ ] Yes [ ] No
 
 ---
 
-*Internal Use Only*
-Application ID: _______________
-Reviewer: _______________
-Status: ☐ Pending ☐ Interview ☐ Approved ☐ Denied
-Notes: ___________________________________________
-_____________________________________________________
+**Application Process:**
+1. Submit this form
+2. Technical screening (phone)
+3. Background check
+4. Training enrollment
+5. Certification exam
+6. Probation period (30 days)

specs/templates/partner-report.md

@@ -1,94 +1,69 @@
 ---
-report_type: monthly_partner_commission
-version: 1.0
+# Fleet Partner Report
+reporting_period:
+partner_name:
+partner_tier:
 ---
 
-# Monthly Partner Commission Report
+## Executive Summary
 
-**Report Period:** ______________ to ______________
-**Partner:** ______________________
-**Partner ID:** _______________
-**Commission Tier:** ☐ Level 1 (20%) ☐ Level 2 (5%)
+- Period: 
+- Total referred operators this period:
+- Active operators from referrals:
+- Revenue generated from referrals:
+- Status: [ ] On Track [ ] At Risk [ ] Exceeding Target
 
-## 1. Referral Summary
+## Referral Activity
 
-| Referred Partner | Sign-up Date | Active Months | Gross Revenue | Commission % | Commission Earned |
-|-----------------|--------------|---------------|---------------|--------------|-------------------|
-|                 |              |               |               |              |                   |
-|                 |              |               |               |              |                   |
-|                 |              |               |               |              |                   |
-|                 |              |               |               |              |                   |
-| **TOTAL**        |              |               |               |              | **$_________**    |
+| Referral Name | Application Date | Status | Revenue Impact |
+|---------------|-----------------|--------|----------------|
+|               |                 |        |                |
+|               |                 |        |                |
 
-## 2. Calculation Details
+**Total referrals:** 
+**Converted to active operators:** 
+**Conversion rate:** 
 
-### Level 1 Referrals (20%)
-- Referral A: $______ × 20% = $______
-- Referral B: $______ × 20% = $______
-- Subtotal Level 1: $______
+## Financial Summary
 
-### Level 2 Referrals (5%)
-- Referral C (via Partner A): $______ × 5% = $______
-- Referral D (via Partner B): $______ × 5% = $______
-- Subtotal Level 2: $______
+- Referral fees earned this period:
+- Cumulative referral fees:
+- Revenue share percentage:
+- Projected next period revenue:
 
-**Gross Commission:** $______
+## Partner Performance Metrics
 
-### Adjustments
-- Previous overpayment recovery: -$______
-- Bonuses/Incentives: +$______
-- **Net Commission:** $______
+| Metric | Target | Actual | Variance |
+|--------|--------|--------|----------|
+| Referrals/quarter | | | |
+| Conversion rate | >50% | | |
+| Revenue contribution | >30% leads | | |
+| Partner NPS | >50 | | |
 
-## 3. Referral Performance Detail
+## Challenges & Blockers
 
-### Top Performing Referrals
-1. ______________________ ($______ revenue)
-2. ______________________ ($______ revenue)
-3. ______________________ ($______ revenue)
+*(Describe any issues affecting partner performance)*
 
-### At-Risk Referrals (need attention)
-- ______________________ (growth -__%)
-- ______________________ (churn risk)
+## Support Needed
 
-## 4. Partner Activity
+*(List any resources or support needed from Timmy to improve performance)*
 
-### This Month
-- New referrals acquired: ______
-- Partners activated: ______
-- Training sessions attended: ______
-- Support tickets submitted: ______
+## Goals for Next Period
 
-### Year-to-Date
-- Total referrals: ______
-- Activated partners: ______
-- Commission earned YTD: $______
-- Average partner value: $______
+1. 
+2. 
+3. 
 
-## 5. Notes & Comments
-
-___________________________________________________________________________
-___________________________________________________________________________
-___________________________________________________________________________
+## Additional Notes
 
 ---
 
-## Approval & Payment
+**Report Submission Instructions:**
+- Submit weekly via email to fleet-partners@timmy.io
+- Copy your Partner Success Manager
+- Attach any supporting documentation
 
-**Partner Signature:** ______________________ **Date:** _______________
-
-**Timmy Finance Approval:** ______________________ **Date:** _______________
-
-**Payment Method:** ☐ ACH Transfer ☐ Check ☐ PayPal
-
-**ACH Details (if applicable):**
-- Bank: ______________________
-- Routing: ______________________
-- Account: ______________________
-
-**Payment Date:** _______________ **Amount:** $_____________ **Reference:** ___________
-
----
-
-*Generated by: Partner Operations Team*
-*Next report: ______________*
-*Questions: partners@timmy.io*
+**Review Process:**
+- Weekly review: Partner Success Team
+- Monthly review: Fleet Leadership
+- Quarterly review: Executive Team