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

specs/fleet-operator-incentives.md

@@ -1,93 +1,67 @@
-# Fleet Operator Incentives Program
+# Fleet Operator Incentives & Partner Program
 
 ## Overview
 
-This specification defines the incentive structure and certification program for Timmy Home fleet operators. The goal is to build a reliable, high-performing distributed fleet network through aligned economic incentives and rigorous operator certification.
+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.
 
-## Program Objectives
+## Objectives
 
-- Recruit and retain 3-5 active certified operators within 6 months
+- Attract and retain high-quality fleet operators
+- Ensure fleet uptime >99.5%
 - Maintain operator churn <10% annually
-- Achieve fleet uptime >99.5%
-- Ensure partner channel delivers >30% of leads
+- Build sustainable partner channel driving >30% of leads
 
-## Operator Tiers & Requirements
+## Operator Tiers & Compensation
 
 ### Tier 1: Certified Operator
-- Complete operator application and training
-- Maintain minimum hardware specifications
-- Agree to SLAs and monitoring
-- Pass technical assessment
+- 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
 
 ### Tier 2: Senior Operator
-- 6+ months active participation
-- Uptime >99.7%
-- Mentor at least 1 new operator
-- Advanced troubleshooting capabilities
+- 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
 
-### Tier 3: Fleet Lead
-- 12+ months active participation
-- Uptime >99.9%
-- Team lead responsibilities
-- Strategic input on fleet improvements
+### 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
 
-## Incentive Structure
+## Performance Bonuses
 
-### Base Compensation
-- Tier 1: $X/month per active node
-- Tier 2: $Y/month per active node (+15% bonus)
-- Tier 3: $Z/month per active node (+30% bonus)
+- 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
 
-### Performance Bonuses
-- Uptime bonus: Additional 5% for >99.5% monthly uptime
-- Lead generation bonus: $100 per qualified lead from operator network
-- Mentorship bonus: $200/month per successfully onboarded mentee
+## Partner Program
 
-### Penalties & Adjustments
-- Downtime deductions: Prorated based on SLA breach
-- Early termination fees: 50% of commitment period value
-- Performance improvement plan for chronic underperformance
+### Partner Tiers
 
-## Certification Process
+#### Bronze Partner
+- Referral target: 1-3 operators/quarter
+- Benefits: 5% rev-share on referred operator revenue
 
-1. Application submission (operator-application.md template)
-2. Technical screening and hardware validation
-3. Training completion (modules & hands-on)
-4. Assessment exam (minimum 80% score)
-5. Probation period (30 days)
-6. Full certification
+#### Silver Partner
+- Referral target: 4-10 operators/quarter
+- Benefits: 8% rev-share + co-marketing support
 
-## Monitoring & Metrics
+#### Gold Partner
+- Referral target: 11+ operators/quarter
+- Benefits: 12% rev-share + strategic partnership agreement
 
-- Real-time uptime monitoring via Prometheus/Grafana
-- Monthly performance reports
-- Quarterly business reviews for senior operators
-- Automated alerting for SLA breaches
+## Certification Pathway
 
-## Partner Program Integration
+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
 
-- Certified operators become partner channel participants
-- Operators receive referral commissions
-- Partner leads tracked through dedicated attribution system
-- Monthly partner reports generated (partner-report.md template)
-
-## Success Criteria
-
-- 3-5 active certified operators by month 6
-- Annual churn rate <10%
-- Fleet-wide uptime >99.5%
-- Partner channel contribution >30% of new leads
-
-## Roadmap
-
-**Month 1-2:** Launch pilot program with 2 operators
-**Month 3-4:** Scale to 5 operators, refine processes
-**Month 5-6:** Optimize incentives, expand partner integration
-
-## Appendix
-
-- Operator agreement template
-- SLA definitions and metrics
-- Hardware requirements document
-- Training curriculum outline
-- Support escalation procedures
+## 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,161 +1,101 @@
 # Fleet Operations Runbook
 
-## Emergency Procedures
+## Purpose
 
-### System Outage Response
-
-**Severity 1 (Total Outage)**
-- Immediate: Alert all on-call operators via PagerDuty
-- Within 15min: Incident commander declared, communication channel established
-- Within 1hr: Root cause identified or escalation to engineering
-- Resolution: Post-mortem within 24 hours
-
-**Severity 2 (Partial Degradation)**
-- Alert within 30min
-- Diagnosis within 2 hours
-- Resolution or workaround within 4 hours
-
-**Severity 3 (Minor Issues)**
-- Ticket creation in incident tracker
-- Resolution within 24 hours
-
-### Hardware Failure
-
-1. **Node Failure Detection**
-   - Automated monitoring alerts when node >5min offline
-   - Operator SMS/email notification
-   - Auto-escalation if no response within 10min
-
-2. **Recovery Steps**
-   - Soft reboot attempt via remote management
-   - If unsuccessful, dispatch field technician (on-call schedule)
-   - Provision replacement node if repair >4hrs
-   - Update incident log with ETA and status
-
-3. **Post-Recovery**
-   - Root cause analysis
-   - Hardware replacement if faulty
-   - Configuration drift detection and remediation
-
-### Network Disruption
-
-- **Provider Outage**: Switch to backup ISP (if available), notify customers of degraded service
-- **Local Network Issues**: Verify local routing, contact site operator for physical inspection
-- **DNS Issues**: Switch to secondary DNS, monitor for propagation
+Standard operating procedures for Fleet Operators to ensure consistent, high-quality service delivery.
 
 ## Daily Operations
 
-### Morning Checks (08:00 UTC)
-- Review overnight alert summary
-- Verify all nodes reported healthy in last 24hrs
-- Check capacity utilization trends
-- Review pending maintenance windows
+### 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
 
-### Ongoing Monitoring
-- Dashboard: `https://monitoring.timmyfoundation.org/fleet`
-- Slack channel: `#fleet-operations`
-- PagerDuty schedule: rotate weekly among Tier 3 operators
+### 2. Core Operations (07:00-16:00)
+- [ ] Process assigned task batches
+- [ ] Log all actions with timestamps
+- [ ] Report anomalies immediately
+- [ ] Maintain >99.5% uptime SLAs
 
-### Handoff Procedure
-- Outgoing operator: Complete handoff checklist by end of shift
-- Incoming operator: Review log, verify all systems nominal
-- Both parties: Sign off in runbook log
+### 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)
 
-## Maintenance Windows
+## Incident Response
 
-- **Weekly**: Software updates (Sunday 02:00-04:00 UTC)
-- **Monthly**: Hardware inspection and cleaning
-- **Quarterly**: Full system audit and capacity planning
+### Severity 1 (System Down)
+- Notify ops lead immediately
+- Follow recovery playbook
+- Document root cause
+- Escalate if unresolved in 15 minutes
 
-## Escalation Path
+### Severity 2 (Degraded Performance)
+- Log incident in tracking system
+- Begin troubleshooting
+- Update status every 30 minutes
+- Resolve within 4 hours
 
-```
-Operator (Tier 1) → Senior Operator (Tier 2) → Fleet Lead (Tier 3)
-    ↓
-Engineering On-Call (P0-P1 incidents)
-    ↓
-CTO / Executive Review (P0 incidents, business critical)
-```
+### Severity 3 (Minor Issue)
+- Document and schedule for next maintenance window
+- No immediate escalation required
 
-## Communication Templates
+## Escalation Matrix
 
-### Outage Notification (Customer-Facing)
+| 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 |
 
-```
-Subject: Service Disruption Notification
+## Communication Channels
 
-Dear Customer,
+- **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
 
-We are currently experiencing an issue affecting [service]. Our team is investigating and working to restore service as quickly as possible.
+## Quality Standards
 
-Estimated time to resolution: [ETA]
-Next update: [time]
+- Task completion accuracy: >99%
+- Response time to alerts: <5 minutes
+- Documentation completeness: 100%
+- Safety incident rate: 0
 
-We apologize for the inconvenience and appreciate your patience.
+## Training & Certification
 
-Timmy Operations Team
-```
+See certification pathway in fleet-operator-incentives.md. Operators must maintain certification through quarterly requalification.
 
-### Internal Alert
+## Schedule & Availability
 
-```
-🚨 FLEET INCIDENT: [SEVERITY] - [NODE/SERVICE]
+- 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
 
-Impact: [description]
-Action: [immediate action required]
-Owner: [assigned operator]
-ETA: [estimated resolution time]
+## Equipment & Resources
 
-Link to incident: [URL]
-```
+- Primary workstation: Maintained by IT
+- Backup systems: Test monthly
+- Software tools: Latest approved versions only
+- Documentation: Always accessible via internal wiki
 
-## Documentation
+## Metrics & Reporting
 
-- Architecture diagrams: `docs/architecture/`
-- Configuration management: `docs/config/`
-- Operator handbook: `specs/fleet-operator-incentives.md`
-- Compliance checklist: `docs/compliance/`
+Daily metrics submitted via partner-report.md:
+- Tasks completed
+- Uptime percentage
+- Incidents logged
+- Quality scores
+- Process improvement suggestions
 
-## Support Contacts
-
-- **Engineering On-Call**: `pagerduty://schedule/engineering`
-- **Network Provider**: `support@provider.com / 1-800-SUPPORT`
-- **Hardware Vendor**: `support@vendor.com / 1-800-HARDWARE`
-- **Internal Fleet Slack**: `#fleet-operations`
-
-## Recovery Objectives (RTO/RPO)
-
-| Service | RTO | RPO |
-|---------|-----|-----|
-| API Services | 15min | 5min |
-| Data Pipeline | 1hr | 15min |
-| Monitoring | 30min | N/A |
-| Backup Systems | 4hr | 24hr |
-
-## Change Management
-
-- All production changes require RFC and approval
-- Emergency changes: Document rationale, notify within 24hrs
-- Standard changes: Weekly change window (Wednesday 22:00 UTC)
-- Post-change validation required for all modifications
-
-## Security Incidents
-
-- Immediate isolation of affected nodes
-- Preserve logs for forensic analysis
-- Notify security team within 15min
-- Follow incident response playbook: `docs/security/incident-response.md`
-
-## Metrics & KPIs
-
-- **MTTR**: Mean time to recovery
-- **Uptime**: Node and service availability percentages
-- **Capacity**: Utilization vs. provisioned resources
-- **Customer Impact**: Number of affected customers per incident
+Weekly review with Fleet Manager every Monday 10:00-10:30.
 
 ## Appendix
 
-- Outage history log
-- Maintenance schedule
-- Vendor contact list
-- Compliance audit checklist
+- A: System Architecture Overview
+- B: Troubleshooting Playbooks
+- C: Contact Directory
+- D: Compliance Requirements

specs/templates/operator-application.md

@@ -1,112 +1,65 @@
+---
 # Fleet Operator Application
+application_date: YYYY-MM-DD
+candidate_name: 
+---
 
 ## Personal Information
 
-**Full Name:**
-**Email:**
-**Phone:**
-**Location (City, State/Province, Country):**
-**Time Zone:**
+- Full Name:
+- Email:
+- Phone:
+- Location (City/State/Country):
+- Time Zone:
 
-## Business Entity
+## Professional Background
 
-**Legal Structure:** (Sole Proprietor / LLC / Corporation / Other)
-**Business Registration Number:**
-**Tax ID/EIN:**
-**Years in Operation:**
+### Relevant Experience
+- Years in operations/technical roles:
+- Fleet management experience:
+- Previous certifications:
+- Equipment familiarity:
 
-## Technical Capabilities
+### Technical Skills
+- [ ] System monitoring
+- [ ] Incident response
+- [ ] Documentation
+- [ ] Team collaboration
+- [ ] Other (specify):
 
-### Infrastructure
+## Availability
 
-- **Number of Nodes Available:** __________
-- **Hardware Specifications (per node):**
-  - CPU: __________
-  - RAM: __________
-  - Storage: __________
-  - Network: __________
+- Start date available:
+- Weekly hours sought:
+- On-call willingness: [ ] Yes [ ] No
+- Remote work preference: [ ] Fully remote [ ] Hybrid [ ] On-site
 
-- **Uptime History (past 12 months):** __________%
-- **Average Monthly Downtime:** __________ hours
+## Compensation Expectations
 
-### Connectivity
+- Desired hourly rate:
+- Minimum acceptable rate:
 
-- **Primary ISP:** __________
-- **Backup ISP:** __________ (Yes/No)
-- **Average Upload Speed:** __________ Mbps
-- **Average Download Speed:** __________ Mbps
-- **Latency to primary regions:** __________ ms
+## Why Timmy?
 
-### Security & Compliance
+*(Describe your interest in joining the Timmy Fleet)*
 
-- **Physical Security Measures:** (e.g., locked racks, cameras)
-- **Network Security:** (firewalls, VPNs, monitoring)
-- **Data Privacy Compliance:** (GDPR, CCPA, etc.)
-- **Insurance Coverage:** (liability, errors & omissions)
+## Additional Information
 
-## Operational Capacity
+- References (2-3):
+- Portfolio/Projects:
+- GitHub/LinkedIn:
 
-**Support Hours:** __________ (24/7 / Business Hours / On-call)
-**Staff Count:** __________ (Full-time / Part-time)
-**Incident Response SLA:** __________
-**Monitoring Tools Used:** __________
+## Certification Path
 
-## Financial Terms
+- Have you reviewed the Fleet Operator Incentives document? [ ] Yes [ ] No
+- Are you willing to complete the 100-hour training program? [ ] Yes [ ] No
 
-**Desired Compensation Model:** (Tier 1 / Tier 2 / Tier 3)
-**Expected Monthly Revenue:** $__________
-**Start Date Availability:** __________
-**Commitment Period:** (6 months / 12 months / 24 months)
+---
 
-## References
-
-**Previous Fleet/Customer References:**
-1. Name: __________ | Contact: __________ | Relationship: __________
-2. Name: __________ | Contact: __________ | Relationship: __________
-
-**Technical References:**
-1. Name: __________ | Contact: __________ | Relationship: __________
-
-## Certifications
-
-- [ ] AWS/Azure/GCP Certification
-- [ ] Network+ / Security+
-- [ ] ISO 27001
-- [ ] SOC 2
-- [ ] Other: __________
-
-## Motivation & Alignment
-
-**Why do you want to join the Timmy Home Fleet?** (max 500 words)
-
-**How does your operation align with our values of reliability, transparency, and continuous improvement?** (max 300 words)
-
-## Attachments
-
-- [ ] Proof of business registration
-- [ ] Insurance certificates
-- [ ] Network performance reports (last 3 months)
-- [ ] Hardware inventory list
-- [ ] Signed NDA (if not already on file)
-
-## Agreement
-
-By submitting this application, I certify that all information provided is accurate and complete. I understand that false statements may result in termination of the operator agreement.
-
-**Signature:** _________________________
-**Date:** _________________________
-
-## Internal Use Only (Timmy Home Team)
-
-- **Application Received:** __________
-- **Initial Screening:** __________ (Pass/Fail) by __________
-- **Technical Review:** __________ (Pass/Fail) by __________
-- **Site Visit/Remote Inspection:** __________ (Completed/Dates)
-- **Certification Assigned:** __________ (Tier 1 / Tier 2 / Tier 3)
-- **Onboarding Date:** __________
-- **Mentor Assigned:** __________
-- **Operational Start Date:** __________
-
-**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,134 +1,69 @@
-# Partner Monthly Report
-
-## Report Period
-
-**Month/Year:** __________
-**Partner ID:** __________
-**Partner Name:** __________
-**Report Generated:** __________
+---
+# Fleet Partner Report
+reporting_period:
+partner_name:
+partner_tier:
+---
 
 ## Executive Summary
 
-- Total leads generated: __________
-- Qualified leads: __________
-- converted customers: __________
-- Revenue attributed: $__________
-- Commission earned: $__________
-- YoY growth: __________%
+- Period: 
+- Total referred operators this period:
+- Active operators from referrals:
+- Revenue generated from referrals:
+- Status: [ ] On Track [ ] At Risk [ ] Exceeding Target
 
-## Lead Generation Metrics
+## Referral Activity
 
-### Lead Volume
+| Referral Name | Application Date | Status | Revenue Impact |
+|---------------|-----------------|--------|----------------|
+|               |                 |        |                |
+|               |                 |        |                |
 
-| Channel | Total Leads | Qualified Leads | Conversion Rate | Notes |
-|---------|-------------|-----------------|-----------------|-------|
-| Direct Referral | __ | __ | __% | |
-| Marketing Campaign | __ | __ | __% | |
-| Events/Conferences | __ | __ | __% | |
-| Other: __________ | __ | __ | __% | |
+**Total referrals:** 
+**Converted to active operators:** 
+**Conversion rate:** 
 
-### Lead Quality Assessment
+## Financial Summary
 
-- **High Value (likely to convert):** __________ leads
-- **Medium Value:** __________ leads
-- **Low Value:** __________ leads
-- **Lead Source Validation:** __________% verified
+- Referral fees earned this period:
+- Cumulative referral fees:
+- Revenue share percentage:
+- Projected next period revenue:
 
-## Revenue & Commission
+## Partner Performance Metrics
 
-### Revenue Attribution
-
-| Customer | Deal Size | Start Date | Commission % | Commission Amount |
-|----------|-----------|------------|--------------|-------------------|
-| | $ | | % | $ |
-| | $ | | % | $ |
-| | $ | | % | $ |
-
-- **Total Revenue:** $__________
-- **Total Commission:** $__________
-- **Commission Rate:** __________%
-- **Payment Status:** (Paid / Pending / Escrow)
-
-### Payment Schedule
-
-- **Commission Period:** 1st - last day of month
-- **Payment Date:** __________ (net 30 days)
-- **Payment Method:** (ACH / Wire / Check / Crypto)
-- **Invoice Attached:** (Yes/No)
-
-## Fleet Performance Impact
-
-### Operator Contributions
-
-| Operator | Leads Generated | Conversions | Revenue Impact |
-|----------|----------------|-------------|----------------|
-| | | | $ |
-| | | | $ |
-| | | | $ |
-
-### Uptime & Reliability Correlation
-
-- **Average fleet uptime during reporting period:** __________%
-- **Leads from high-uptime operators (>99.5%):** __________
-- **Customer complaints related to fleet issues:** __________
-
-## Marketing & Training Activities
-
-### Promotional Efforts
-
-- Campaigns run: __________
-- Materials distributed: __________
-- Events attended: __________
-- Content created: __________
-
-### Training Completed
-
-- New operator certifications: __________
-- Continuing education hours: __________
-- Process improvements implemented: __________
+| Metric | Target | Actual | Variance |
+|--------|--------|--------|----------|
+| Referrals/quarter | | | |
+| Conversion rate | >50% | | |
+| Revenue contribution | >30% leads | | |
+| Partner NPS | >50 | | |
 
 ## Challenges & Blockers
 
-- __________
-- __________
-- __________
+*(Describe any issues affecting partner performance)*
 
-## Opportunities & Goals (Next Period)
+## Support Needed
 
-1. __________
-2. __________
-3. __________
+*(List any resources or support needed from Timmy to improve performance)*
 
-## Support Needs
+## Goals for Next Period
 
-- __ Technical assistance
-- __ Marketing materials
-- __ Training resources
-- __ Lead qualification support
-- __ Other: __________
+1. 
+2. 
+3. 
 
-## Compliance & Agreement Status
-
-- [ ] All reporting requirements met
-- [ ] Commissions calculated correctly
-- [ ] SLA adherence documented
-- [ ] Partner agreement in good standing
-- [ ] No compliance violations
-
-**Partner Signature:** _________________________
-**Date:** _________________________
-
-**Timmy Home Representative:** _________________________
-**Date:** _________________________
-
-## Attachments
-
-- [ ] Lead verification documentation
-- [ ] Revenue reports from finance system
-- [ ] Commission calculation spreadsheet
-- [ ] Marketing activity logs
-- [ ] Training completion certificates
+## Additional Notes
 
 ---
 
-*This report is confidential and intended solely for the use of the partner and Timmy Home leadership. Distribution without authorization is prohibited.*
+**Report Submission Instructions:**
+- Submit weekly via email to fleet-partners@timmy.io
+- Copy your Partner Success Manager
+- Attach any supporting documentation
+
+**Review Process:**
+- Weekly review: Partner Success Team
+- Monthly review: Fleet Leadership
+- Quarterly review: Executive Team