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

specs/fleet-operator-incentives.md

@@ -0,0 +1,93 @@
+# Fleet Operator Incentives 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.
+
+## Program Objectives
+
+- Recruit and retain 3-5 active certified operators within 6 months
+- Maintain operator churn <10% annually
+- Achieve fleet uptime >99.5%
+- Ensure partner channel delivers >30% of leads
+
+## Operator Tiers & Requirements
+
+### Tier 1: Certified Operator
+- Complete operator application and training
+- Maintain minimum hardware specifications
+- Agree to SLAs and monitoring
+- Pass technical assessment
+
+### Tier 2: Senior Operator
+- 6+ months active participation
+- Uptime >99.7%
+- Mentor at least 1 new operator
+- Advanced troubleshooting capabilities
+
+### Tier 3: Fleet Lead
+- 12+ months active participation
+- Uptime >99.9%
+- Team lead responsibilities
+- Strategic input on fleet improvements
+
+## Incentive Structure
+
+### 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)
+
+### 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
+
+### Penalties & Adjustments
+- Downtime deductions: Prorated based on SLA breach
+- Early termination fees: 50% of commitment period value
+- Performance improvement plan for chronic underperformance
+
+## Certification Process
+
+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
+
+## Monitoring & Metrics
+
+- Real-time uptime monitoring via Prometheus/Grafana
+- Monthly performance reports
+- Quarterly business reviews for senior operators
+- Automated alerting for SLA breaches
+
+## Partner Program Integration
+
+- 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

specs/fleet-ops-runbook.md

@@ -0,0 +1,161 @@
+# Fleet Operations Runbook
+
+## Emergency Procedures
+
+### 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
+
+## 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
+
+### Ongoing Monitoring
+- Dashboard: `https://monitoring.timmyfoundation.org/fleet`
+- Slack channel: `#fleet-operations`
+- PagerDuty schedule: rotate weekly among Tier 3 operators
+
+### 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
+
+## Maintenance Windows
+
+- **Weekly**: Software updates (Sunday 02:00-04:00 UTC)
+- **Monthly**: Hardware inspection and cleaning
+- **Quarterly**: Full system audit and capacity planning
+
+## Escalation Path
+
+```
+Operator (Tier 1) → Senior Operator (Tier 2) → Fleet Lead (Tier 3)
+    ↓
+Engineering On-Call (P0-P1 incidents)
+    ↓
+CTO / Executive Review (P0 incidents, business critical)
+```
+
+## Communication Templates
+
+### Outage Notification (Customer-Facing)
+
+```
+Subject: Service Disruption Notification
+
+Dear Customer,
+
+We are currently experiencing an issue affecting [service]. Our team is investigating and working to restore service as quickly as possible.
+
+Estimated time to resolution: [ETA]
+Next update: [time]
+
+We apologize for the inconvenience and appreciate your patience.
+
+Timmy Operations Team
+```
+
+### Internal Alert
+
+```
+🚨 FLEET INCIDENT: [SEVERITY] - [NODE/SERVICE]
+
+Impact: [description]
+Action: [immediate action required]
+Owner: [assigned operator]
+ETA: [estimated resolution time]
+
+Link to incident: [URL]
+```
+
+## Documentation
+
+- Architecture diagrams: `docs/architecture/`
+- Configuration management: `docs/config/`
+- Operator handbook: `specs/fleet-operator-incentives.md`
+- Compliance checklist: `docs/compliance/`
+
+## 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
+
+## Appendix
+
+- Outage history log
+- Maintenance schedule
+- Vendor contact list
+- Compliance audit checklist

specs/templates/operator-application.md

@@ -0,0 +1,112 @@
+# Fleet Operator Application
+
+## Personal Information
+
+**Full Name:**
+**Email:**
+**Phone:**
+**Location (City, State/Province, Country):**
+**Time Zone:**
+
+## Business Entity
+
+**Legal Structure:** (Sole Proprietor / LLC / Corporation / Other)
+**Business Registration Number:**
+**Tax ID/EIN:**
+**Years in Operation:**
+
+## Technical Capabilities
+
+### Infrastructure
+
+- **Number of Nodes Available:** __________
+- **Hardware Specifications (per node):**
+  - CPU: __________
+  - RAM: __________
+  - Storage: __________
+  - Network: __________
+
+- **Uptime History (past 12 months):** __________%
+- **Average Monthly Downtime:** __________ hours
+
+### Connectivity
+
+- **Primary ISP:** __________
+- **Backup ISP:** __________ (Yes/No)
+- **Average Upload Speed:** __________ Mbps
+- **Average Download Speed:** __________ Mbps
+- **Latency to primary regions:** __________ ms
+
+### Security & Compliance
+
+- **Physical Security Measures:** (e.g., locked racks, cameras)
+- **Network Security:** (firewalls, VPNs, monitoring)
+- **Data Privacy Compliance:** (GDPR, CCPA, etc.)
+- **Insurance Coverage:** (liability, errors & omissions)
+
+## Operational Capacity
+
+**Support Hours:** __________ (24/7 / Business Hours / On-call)
+**Staff Count:** __________ (Full-time / Part-time)
+**Incident Response SLA:** __________
+**Monitoring Tools Used:** __________
+
+## Financial Terms
+
+**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:**
+__________
+__________

specs/templates/partner-report.md

@@ -0,0 +1,134 @@
+# Partner Monthly Report
+
+## Report Period
+
+**Month/Year:** __________
+**Partner ID:** __________
+**Partner Name:** __________
+**Report Generated:** __________
+
+## Executive Summary
+
+- Total leads generated: __________
+- Qualified leads: __________
+- converted customers: __________
+- Revenue attributed: $__________
+- Commission earned: $__________
+- YoY growth: __________%
+
+## Lead Generation Metrics
+
+### Lead Volume
+
+| Channel | Total Leads | Qualified Leads | Conversion Rate | Notes |
+|---------|-------------|-----------------|-----------------|-------|
+| Direct Referral | __ | __ | __% | |
+| Marketing Campaign | __ | __ | __% | |
+| Events/Conferences | __ | __ | __% | |
+| Other: __________ | __ | __ | __% | |
+
+### Lead Quality Assessment
+
+- **High Value (likely to convert):** __________ leads
+- **Medium Value:** __________ leads
+- **Low Value:** __________ leads
+- **Lead Source Validation:** __________% verified
+
+## Revenue & Commission
+
+### 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: __________
+
+## Challenges & Blockers
+
+- __________
+- __________
+- __________
+
+## Opportunities & Goals (Next Period)
+
+1. __________
+2. __________
+3. __________
+
+## Support Needs
+
+- __ Technical assistance
+- __ Marketing materials
+- __ Training resources
+- __ Lead qualification support
+- __ Other: __________
+
+## 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
+
+---
+
+*This report is confidential and intended solely for the use of the partner and Timmy Home leadership. Distribution without authorization is prohibited.*