Compare commits

..

2 Commits

Author SHA1 Message Date
Alexander Payne
2485b7a708 docs: add fleet operations runbook for operators
Some checks failed
Self-Healing Smoke / self-healing-smoke (pull_request) Failing after 26s
Agent PR Gate / gate (pull_request) Failing after 1m4s
Smoke Test / smoke (pull_request) Failing after 31s
Agent PR Gate / report (pull_request) Successful in 25s
- Daily and weekly checklists
- Alert response protocol (<30min critical, <4h warnings)
- Common fixes: restart tmux, clear dispatch queue, update hermes
- Emergency escalation contacts
- Security rules and contact references
2026-04-30 20:21:57 -04:00
Alexander Payne
84831942ed fix(#987): add fleet operator incentives and partner program spec
- Operator role definition, compensation model with bonuses
- Partner program: 20% commission for 12 months per referral
- Quality standards, onboarding certification (4 phases)
- Exit and transition protocol
- Templates: operator-application.md, partner-report.md

Partial implementation of #987
2026-04-30 20:19:31 -04:00
4 changed files with 211 additions and 408 deletions

View File

@@ -1,137 +1,128 @@
# Fleet Operator Incentives & Partner Program
*Epic IV — Human Capital & Incentives (Mogul Influence roadmap steps XII, XIII, XV)*
## 1. Operator Role Definition
## Operator Role Definition
### Primary Responsibilities
- Deploy and maintain sovereign AI agent fleets on VPS nodes
- Monitor fleet health, uptime, and performance metrics
- Execute dispatched tasks from the Timmy Foundation (burn sessions, cron jobs, PR merges)
- Maintain fleet identity registry and rotate credentials per security policy
- Report operational metrics weekly (uptime %, completed tasks, resource usage)
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.
### Qualifications
- Linux system administration (systemd, ssh, git, basic networking)
- Familiarity with AI agent frameworks (Hermes Agent preferred)
- Reliable VPS infrastructure (minimum: 2 vCPU, 4GB RAM, 50GB SSD)
- Stable internet connection with <50ms latency to foundation services
**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
**Required Qualifications:**
- Valid driver's license + clean record
- Basic mechanical aptitude
- Organizational skills
- 20+ hours/week availability
- Home base with secure parking
## 2. Compensation Model
### Base Pay
- **$150/month** per managed vehicle (guaranteed minimum)
- Paid bi-weekly via ACH
## Compensation Model
### Base Rate
- **$150/month** per operator for up to 5 VPS nodes managed
- Additional $25/month per node beyond 5 (max 10 nodes per operator)
### 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 |
|--------|---------|-------|
| Fleet uptime | >99.5% monthly | +$50 |
| Task completion rate | >95% successful dispatches | +$30 |
| Response time | <30min for critical alerts | +$20 |
| Churn prevention | Retain operators 6+ months | +$100 quarterly |
**Earnings Potential:** $150 + bonuses = **$400-700/month per vehicle**
### Payment Schedule
- Monthly via stablecoin (USDC/USDT) on preferred chain
- Bonuses paid within 7 days of month-end verification
- Operators provide wallet address during onboarding
### 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
## Partner Program (20% Commission)
### Partner Role
- Refer new operators to the Timmy Foundation fleet
- Earn 20% of operator base compensation for first 12 months
- Provide mentorship during operator onboarding (first 30 days)
## 3. Partner Program
### Commission Structure
- New operator base $150/mo → Partner earns $30/mo for 12 months
- Bonus performance passes through (partner earns 20% of operator bonuses)
- Minimum: 2 qualifying operators referred before earning partner status
### 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 Requirements
- Must be certified operator for 3+ months with >99% uptime
- Maintain active communication with referred operators
- Submit monthly partner report (format: `specs/templates/partner-report.md`)
### Partner Benefits
- Access to exclusive vehicle allocations
- Marketing co-op fund (up to $500/mo)
- Priority vehicle upgrades
- Training & certification discounts
## Quality Standards
### Operational Standards
- [ ] Fleet uptime ≥99.5% monthly
- [ ] Critical alerts acknowledged within 30 minutes
- [ ] Security: no credential reuse across nodes
- [ ] Weekly metrics report submitted by Monday 09:00 UTC
- [ ] Adhere to sovereign AI principles (no data exfiltration, local-first)
### Qualification
- Minimum 3 months as certified operator
- CSAT consistently >4.2
- Clean safety record
- Referral sales target: 2+ partners/quarter
### Code Quality (for agent modifications)
- [ ] All changes committed with signed-off-by
- [ ] PRs reference Gitea issue/modal number
- [ ] Tests pass before merge (where applicable)
- [ ] No hardcoded secrets in commits
## 4. Quality Standards
### Communication Standards
- [ ] Respond to Timmy Foundation pings within 24 hours
- [ ] Use professional, concise language in issues/PRs
- [ ] Report outages immediately via Telegram/Discord alert channel
### 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
## Onboarding & Certification
### Phase 1: Application
- Submit operator application (template: `specs/templates/operator-application.md`)
- Provide VPS specifications and location
- Sign operator agreement
### Service Level Agreements
- Vehicle availability: 99.5% uptime
- Customer support response: <15 minutes
- Maintenance turnaround: <24 hours
- Incident resolution: <4 hours
### Phase 2: Training
- Complete Hermes Agent training (5 modules)
- Pass fleet operations quiz (80% passing score)
- Shadow certified operator for 1 week
### Compliance
- All local regulations followed
- Insurance documentation current
- Regular audits (quarterly)
### Phase 3: Certification
- Deploy 2-node test fleet
- Successfully complete 10 dispatched tasks
- Certified operator reviews and signs off
## 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
### Phase 4: Active Status
- Added to operator registry
- Granted access to fleet management tools
- Begin earning base compensation
## Exit & Transition Protocol
### Voluntary Exit
- 30-day notice required
- Vehicle inventory reconciliation
- Final compensation paid within 14 days
- Exit interview conducted
1. Submit 30-day notice via Gitea issue label `exit-notice`
2. Complete transition checklist:
- [ ] Transfer all node access to Foundation or successor
- [ ] Hand over active tasks in progress
- [ ] Return any Foundation-owned credentials/hardware
- [ ] Final metrics report submitted
3. Receive exit payment within 7 days
### Performance-Based Termination
- Written warnings for first 2 offenses
- 30-day improvement plan
- Immediate termination for safety violations
- Equipment return within 7 days
### Involuntary Termination (for cause)
- Repeated uptime <97% (3 consecutive months)
- Security breach or credential exposure
- Violation of sovereign AI principles
- Unresponsive >72 hours without prior notice
### Emergency Transition
- Company assumes control within 24 hours
- Backup operator assigned
- Vehicles redistributed to neighboring fleets
Terminated operators:
- Access revoked immediately
- Final payment pro-rated to last active day
- May reapply after 6 months with improvement plan
### Knowledge Transfer
- All documentation handed over
- Key contacts list provided
- Outstanding issues documented
- Final report submitted
### Succession Planning
- Each operator mentors 1 junior operator within first 6 months
- Documentation of all processes in `specs/fleet-ops-runbook.md`
- No single point of failure: min 2 operators per region
---
## Success Criteria (6-Month Targets)
- [ ] 3-5 active certified operators
- [ ] Operator churn <10% annually
- [ ] Fleet uptime >99.5%
- [ ] Partner channel >30% of new operator leads
*Last updated: 2025-01-20*
*Owner: Fleet Operations Team*
## References
- Parent epic: Mogul Influence 17-step roadmap (steps XII, XIII, XV)
- Issue: #987
- Templates: `specs/templates/operator-*.md`
- Runbook: `specs/fleet-ops-runbook.md` (future)

View File

@@ -1,147 +1,59 @@
# Fleet Operations Runbook
*Standard operating procedures for Timmy Foundation fleet operators*
## 1. Daily Checklist
## Daily Checklist
- [ ] Check fleet health: `tmux list-sessions` (should show BURN, BURN2, FORGE active)
- [ ] Verify gateway running: `systemctl status ai.hermes.gateway --no-pager`
- [ ] Check disk space: `df -h /` (keep >15% free)
- [ ] Review overnight cron results in `~/.hermes/cron/jobs/`
### 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
## Weekly Tasks
- [ ] Generate fleet metrics report (`scripts/fleet-metrics.sh`)
- [ ] Rotate any expired credentials (check `~/.hermes/fleet-dispatch-state.json`)
- [ ] Review open PRs in Timmy Foundation repos
- [ ] Submit weekly report by Monday 09:00 UTC
### 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
## Alert Response Protocol
### Critical (respond <30 min)
1. Gateway down: `sudo systemctl restart ai.hermes.gateway`
2. Disk >90% full: `scripts/cleanup-disk.sh`
3. Fleet dispatch failing: check `/tmp/hermes/dispatch-queue.json`
### 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
### Warning (respond <4 hours)
1. Uptime <99.5%: investigate tmux panes with `tmux attach -t BURN`
2. Failed cron jobs: check logs in `~/.hermes/cron/jobs/`
3. Agent loop errors: review session transcripts
## 2. Weekly Checklist
## Common Fixes
### Restart stuck tmux pane
```bash
tmux send-keys -t BURN:0 C-c
tmux send-keys -t BURN:0 "hermes chat --yolo" Enter
```
### Monday
- [ ] Weekly fleet health report
- [ ] Safety incident review (if any)
- [ ] Partner onboarding sessions
- [ ] Review compensation & bonus eligibility
### Clear dispatch queue
```bash
rm /tmp/hermes/dispatch-queue.json
# Watchdog will recreate on next cycle
```
### Wednesday
- [ ] Mid-week quality audit (10% random sample)
- [ ] Partner performance reviews
- [ ] Inventory planning for upcoming weekend
- [ ] Training session for new operators
### Update hermes-agent
```bash
cd ~/hermes-agent && git pull origin main && pip install -e ".[all]"
```
### Friday
- [ ] Weekly summary report submission
- [ ] Equipment maintenance scheduling
- [ ] Customer feedback review
- [ ] Weekend readiness assessment
## Emergency Escalation
- **Telegram**: @Rockachopa (primary)
- **Gitea Issue**: label `operator-alert` + mention @Rockachopa
- **Discord**: #fleet-ops-alerts channel
## 3. Alert Response Procedures
## Security Rules
- Never share VPS SSH keys
- Never commit credentials to git
- Rotate tokens every 90 days
- Report suspicious activity immediately
### 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 |
### 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 |
### 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 |
## 4. Common Fixes & Quick Resolutions
### 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
### GPS/Location Issues
1. Verify vehicle connectivity
2. Restart vehicle system (if safe)
3. Report persistent issues to tech support
### 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 |
### Maintenance Coordination
- Preventive: Schedule during off-peak hours (2-5 PM)
- Emergency: Immediate dispatch, backup vehicle assignment
- Recalls: 48-hour completion SLA
## 5. Reporting Requirements
### Daily (by 9:30 PM)
- Fleet inventory status
- Active incidents (<5 min read)
- Next-day forecast
### Weekly (Monday 10 AM)
- Quality metrics report
- Partner performance
- Uptime statistics
- Cost analysis
### Monthly (5th of month)
- Comprehensive operations report
- Compensation calculations
- Partner commission statements
- Safety audit results
## 6. Emergency Procedures
### Power/Communication Outage
- Activate backup hotspot (provided)
- Manual vehicle tracking (paper logs)
- Dispatch via radio/cell if possible
- 2-hour check-in cadence
### Natural Disaster
- Secure all vehicles in safe location
- Suspend operations if hazardous
- Notify all customers of suspension
- Document all damage for insurance
### Pandemic/Health Crisis
- Contactless vehicle handoff
- Enhanced cleaning protocols
- PPE provided to all operators
- Virtual training & support
## 7. Tools & Resources
| 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*
## Contact
- **Operator Handbook**: `specs/fleet-operator-incentives.md`
- **Templates**: `specs/templates/operator-*.md`
- **Foundation Forge**: https://forge.alexanderwhitestone.com/Timmy_Foundation

View File

@@ -1,88 +1,44 @@
---
application_type: fleet_operator
version: 1.0
---
# Fleet Operator Application
*Submit completed form as a new Gitea issue with label `operator-application`*
## Personal Information
- **Name / Handle**:
- **Contact Email**:
- **Telegram/Discord Handle**:
- **Wallet Address (USDC/USDT)**:
- **Timezone**:
**Full Legal Name:**
_____________________________________________________
## Infrastructure
- **VPS Provider**: (e.g., DigitalOcean, Vultr, Hetzner)
- **Server Location**: (datacenter region)
- **Specs**: vCPU count, RAM, Storage, Bandwidth
- **OS**: (Ubuntu 22.04 LTS preferred)
- **Static IP**: Yes / No
**Address:**
_____________________________________________________
_____________________________________________________
## Experience
- [ ] Linux system administration (2+ years)
- [ ] Git / GitHub / Gitea usage
- [ ] Docker / container orchestration
- [ ] AI agent frameworks (Hermes, OpenAI, etc.)
- [ ] Prior VPS fleet management
**Phone:** ______________________ **Email:** ______________________
**Date of Birth:** _______________
## Qualifications
### Driving Record
- [ ] Valid driver's license (state): _______________
- [ ] License number: _______________
- [ ] Clean driving record for past 3 years (required)
- [ ] Insurance available at competitive rate
### Experience
- Years of fleet/vehicle management experience: ______
- Years of customer service experience: ______
- Mechanical aptitude (describe): ______________________
_____________________________________________________
### Availability
- Hours per week available: ______
- Preferred shift: ☐ Morning ☐ Afternoon ☐ Evening ☐ Flexible
- Any scheduling constraints: ______________________
_____________________________________________________
## Business Capability
### Physical Location
- Do you have secure parking for 15+ vehicles? ☐ Yes ☐ No
- Address for parking/storage: ______________________
_____________________________________________________
### Equipment
- [ ] Smartphone (iOS/Android)
- [ ] Reliable internet
- [ ] Vehicle for personal transport
- [ ] Basic tool kit
- [ ] Cleaning supplies
### Financial
- Account for ACH direct deposit: ______________________
- Routing number: _______________ Account: _______________
### Relevant Experience (describe)
*Briefly describe your background with fleet ops, sysadmin, or AI agents:*
## Commitment
- **Hours per week available**:
- **Can maintain 99.5% uptime?** Yes / No
- **Agree to 30-day notice for exit?** Yes / No
- **Agree to sovereign AI principles (no data exfiltration)?** Yes / No
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
## References
- GitHub/Gitea username:
- Any prior work with Timmy Foundation? (link issues/PRs)
**Signature:** ______________________ **Date:** _______________
## Acknowledgment
I understand I will start at $150/month base rate, with bonuses available for performance. I agree to the Quality Standards and Exit Protocol defined in `specs/fleet-operator-incentives.md`.
## 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
**Signature** (type name): _________________ **Date**: _________
---
*Internal Use Only*
Application ID: _______________
Reviewer: _______________
Status: ☐ Pending ☐ Interview ☐ Approved ☐ Denied
Notes: ___________________________________________
_____________________________________________________
*Send completed application to: https://forge.alexanderwhitestone.com/Timmy_Foundation/timmy-home/issues/new*

View File

@@ -1,94 +1,38 @@
---
report_type: monthly_partner_commission
version: 1.0
---
# Partner Monthly Report
*Submit by the 5th of each month for commission payments*
# Monthly Partner Commission Report
## Partner Info
- **Partner Name**:
- **Month/Year**:
- **Wallet Address**:
**Report Period:** ______________ to ______________
**Partner:** ______________________
**Partner ID:** _______________
**Commission Tier:** ☐ Level 1 (20%) ☐ Level 2 (5%)
## Referred Operators
| Operator Handle | Start Date | Monthly Base | Commission (20%) | Status |
|----------------|------------|--------------|-------------------|--------|
| | | $150 | $30 | active / churned |
| | | $150 | $30 | active / churned |
| | | $150 | $30 | active / churned |
## 1. Referral Summary
**Total Commission Due**: $______
| Referred Partner | Sign-up Date | Active Months | Gross Revenue | Commission % | Commission Earned |
|-----------------|--------------|---------------|---------------|--------------|-------------------|
| | | | | | |
| | | | | | |
| | | | | | |
| | | | | | |
| **TOTAL** | | | | | **$_________** |
## Mentorship Log
*Confirm you provided mentorship to each referred operator in the first 30 days:*
- [ ] Operator 1: mentored (dates: ____ to ____)
- [ ] Operator 2: mentored (dates: ____ to ____)
- [ ] Operator 3: mentored (dates: ____ to ____)
## 2. Calculation Details
## Partner Performance
- Total active operators referred:
- Average operator uptime this month: ______%
- Any operator churn? Yes / No (explain: )
### Level 1 Referrals (20%)
- Referral A: $______ × 20% = $______
- Referral B: $______ × 20% = $______
- Subtotal Level 1: $______
## Self-Assessment
- [ ] I maintained >99% personal fleet uptime
- [ ] I responded to Foundation pings within 24 hours
- [ ] I submitted this report on time
### Level 2 Referrals (5%)
- Referral C (via Partner A): $______ × 5% = $______
- Referral D (via Partner B): $______ × 5% = $______
- Subtotal Level 2: $______
**Gross Commission:** $______
### Adjustments
- Previous overpayment recovery: -$______
- Bonuses/Incentives: +$______
- **Net Commission:** $______
## 3. Referral Performance Detail
### Top Performing Referrals
1. ______________________ ($______ revenue)
2. ______________________ ($______ revenue)
3. ______________________ ($______ revenue)
### At-Risk Referrals (need attention)
- ______________________ (growth -__%)
- ______________________ (churn risk)
## 4. Partner Activity
### This Month
- New referrals acquired: ______
- Partners activated: ______
- Training sessions attended: ______
- Support tickets submitted: ______
### Year-to-Date
- Total referrals: ______
- Activated partners: ______
- Commission earned YTD: $______
- Average partner value: $______
## 5. Notes & Comments
___________________________________________________________________________
___________________________________________________________________________
___________________________________________________________________________
## Notes
*Any issues, concerns, or operator feedback:*
---
## Approval & Payment
**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*
*Submit as comment on your partner Gitea issue or via Telegram to @Rockachopa*