> For the complete documentation index, see [llms.txt](https://t420.gitbook.io/t420/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://t420.gitbook.io/t420/fleetos-data-structure-for-sales-evals.md).

# FleetOS — Data Structure for B2B Sales Agent Evals

**Purpose:** Hard-output snapshot of FleetOS for designing evals across a B2B sales agent team. **Sources:** `PROJECT.md`, `database/core/schema.sql`, `database/fleetos/schema.sql`, `supabase/migrations/*`, `types/api/workOrder.ts`, `supabase/functions/api-v1/index.ts`, landing components, `docs/FEATURES.md`, `docs/miami-go-to-market-plan.md`. **As of:** 2026-04-30

***

## 1. Diagram — System Map

```mermaid
flowchart TB
  subgraph ICP["ICP & Buyers"]
    FleetBuyer["FLEET buyer<br/>Coordinator / Dispatcher / Compliance Lead<br/>US, multi-vehicle, multi-supplier"]
    SupplierBuyer["SUPPLIER buyer<br/>Mobile Tire / Tow / Roadside / Mech / Body<br/>SMB owner-operator or dispatch lead"]
  end

  subgraph Channels["Inbound / Outbound Channels"]
    SMS["SMS (Twilio)<br/>10DLC PENDING - blocks launch"]
    Email["Email (Resend)<br/>LIVE"]
    WA["WhatsApp<br/>phasing out"]
    Web["Web form / magic link"]
    API["REST API v1<br/>X-API-Key"]
  end

  subgraph Product["FleetOS Product Surface"]
    Landing["Landing - fleetos.us<br/>'FROM CHAOS TO COMPLIANCE'<br/>Free tier - no credit card"]
    Inbox["Unified Request Inbox<br/>URGENT / TODAY / SCHEDULED"]
    Dispatch["Quote -> Schedule -> Execute -> Complete"]
    Compliance["Audit Trail<br/>photo + signature + odometer + timeline"]
  end

  subgraph Data["Core Data Model (company-scoped)"]
    Companies[("companies<br/>fleet | supplier | mixed")]
    Contacts[("contacts<br/>email/phone/whatsapp")]
    WorkOrders[("service_requests<br/>aka work_orders")]
    Vehicles[("vehicles")]
    Relationships[("fleetos_relationships<br/>health_score 0-100")]
    Notifications[("notifications<br/>12-step ladder")]
    EventLog[("event_log<br/>audit trail")]
    Shadow[("shadow_tables<br/>AI training")]
  end

  subgraph Agents["Agent Ecosystem"]
    Blade["Blade / OpenClaw<br/>growth operator<br/>(separate repo)"]
    MC["Mission Control<br/>human sales cockpit"]
    SalesAgents["NEW: B2B Sales Agent Team<br/>(this eval target)"]
  end

  FleetBuyer & SupplierBuyer --> Channels
  Channels --> Landing
  Landing --> Inbox --> Dispatch --> Compliance
  Dispatch -.writes.-> WorkOrders
  WorkOrders --> EventLog
  WorkOrders --> Shadow
  Companies --> Contacts
  Companies --> WorkOrders
  Companies --> Vehicles
  WorkOrders --> Relationships
  WorkOrders --> Notifications

  Blade -. researches & drafts outreach .-> FleetBuyer
  Blade -. researches & drafts outreach .-> SupplierBuyer
  SalesAgents -. qualify / pitch / handoff .-> MC
  MC -. activates .-> Product
```

```mermaid
stateDiagram-v2
  direction LR
  [*] --> requested
  state Commercial {
    requested --> quoted
    quoted --> approved
    quoted --> declined
    approved --> invoiced
  }
  state Operational {
    unscheduled --> scheduled
    scheduled --> en_route
    en_route --> in_progress
    in_progress --> waiting_parts
    waiting_parts --> in_progress
    in_progress --> ready_for_pickup
    ready_for_pickup --> completed
    in_progress --> completed
    scheduled --> cancelled
    in_progress --> cancelled
  }
  approved --> scheduled : assign tech + bay
  completed --> invoiced : final cost + photo + signature
```

***

## 2. Structured Snapshot (YAML)

```yaml
product:
  name: FleetOS
  url: fleetos.us
  one_liner: "SMS-first US fleet service coordination — turns WhatsApp/email/call chaos into trackable work orders."
  tagline_landing: "FREE DISPATCH FOR MOBILE OPS & SMALL SHOPS"
  positioning: "Operating layer for EXTERNAL fleet service coordination (cross-company)."
  not_positioned_as: [generic fleet software, marketplace, chat wrapper, AI platform, broad maintenance suite]
  parent_org: T420 (FleetOS is the freemium supply-side acquisition engine for T420)
  market: US-only (100%)
  wedge_city: Miami, Florida
  stage: pre-seed, founder in SA, no US users yet, launch-ready except 10DLC carrier approval
  legacy_note: WhatsApp send path being phased out → SMS migration Phases 0-3 shipped, Phase 4 pending

icp:
  segment: B2B, SMB-to-mid-market, dispatch-heavy
  geography: US (Miami first), dense commercial-fleet metros
  fleet_side:
    titles: [Fleet Coordinator, Fleet Manager, Dispatcher, Compliance Lead]
    company_signals: [recurring external service spend, multiple vehicles, currently coordinates via WhatsApp/email/calls, no audit trail]
    pain: ["he-said-she-said disputes", missing invoices, no approval chain, no compliance proof]
  supplier_side:
    titles: [Owner-Operator, Service Dispatcher, Shop Manager]
    categories: [Mobile Tire Service, Mechanic Shops, Emergency Towing, Roadside Assistance, Auto Body & Repair, Fleet Recovery]
    pain: [requests scattered across WhatsApp/email/calls, no structured intake, slow quoting, lost jobs]
  audience_pills_from_landing:
    - Mobile Tire Service
    - Mechanic Shops
    - Emergency Towing
    - Roadside Assistance
    - Auto Body & Repair
    - Fleet Recovery
    - Service Dispatchers
    - Fleet Coordinators
    - Fleet Managers
    - Compliance Teams

pricing:
  fleet_coordination:
    price: $0/month
    hook: "No credit card required"
    badged: "Most Popular"
    includes:
      - Unified request inbox
      - Unlimited requests & relationships
      - Instant automated confirmations
      - Complete service history
      - Magic link authentication
  paid_tier_exists: true   # second tile in LandingPricing.tsx — details TBD
  monetization_thesis: "Freemium supply-side acquisition engine; T420 monetizes downstream"

competition_being_replaced:
  - WhatsApp threads
  - Email inboxes
  - Phone calls
  - Spreadsheets
not_competing_directly_with: "all-in-one fleet management suites"

core_data_model:
  companies:
    purpose: "Company-Owned Work — every record scoped to company_id, never user-first"
    fields: [company_id, domain, company_name, company_type{fleet|supplier|mixed}, settings_jsonb]
  contacts:
    purpose: "Emergent Contacts (BIBLE architecture) — contact tracked before user signup"
    fields: [contact_id, company_id, contact_value, contact_type{email|phone|whatsapp}, display_name, is_primary]
  users:
    auth_tiers: [GUEST, MAGIC_LINK (view-only), AUTHENTICATED]
    roles: [supplier, fleet, dispatch, manager, tech, owner]
  service_requests_aka_work_orders:
    urgency: [URGENT, TODAY, SCHEDULED]
    legacy_status: [pending, sent, delivered, assigned, acknowledged, accepted, in_progress, completed, declined]
    api_status_split:
      commercial_status: [requested, quoted, approved, declined, invoiced]
      operational_status: [unscheduled, scheduled, en_route, in_progress, waiting_parts, ready_for_pickup, completed, cancelled]
    priority: [emergency, urgent, routine]
    captured: [vehicle_identifier, location, description, service_category, scheduled_time, quoted_amount, final_cost, currency, vat_type, quote_attachment, invoice_attachment, technician_name, bay_number, part_description, eta, odometer_in, completion_photo, signature]
  vehicles:
    fields: [vehicle_id, company_id, identifier, make, model, year, vin]
  fleetos_relationships:
    purpose: "Fleet↔Supplier pairs with health score (0-100), success rate, response time"
  fleetos_invites:
    flow: "fleet invites supplier (or vice versa) via code; expires in 7 days"
    inviter_types: [supplier, fleet]
  notifications:
    channels: [whatsapp, email, sms, in-app]
    tracked: [sent_at, delivered_at, opened_at, clicked_at]
    ladder: "12-step nudge sequence in NotificationService.ts; persisted in scheduled_nudges, processed by edge function"
  event_log: "Audit trail — every state change, who/when, JSONB metadata"
  shadow_tables: "Every fleet/supplier decision logged to shadow tables for cross-product AI training"
  viral_analytics:
    moments: [acknowledgment, pride, relief, first, momentum, today]
    actions: [shown, clicked, dismissed, converted]
    conversions: [invited_supplier, invited_fleet, shared_page, created_relationship]

key_flows:
  fleet_creates_request:
    - Fleet manager opens dashboard / form
    - Adds vehicle, location, description, urgency
    - Supplier receives WhatsApp/SMS/email magic link
    - No app download required
  supplier_responds_via_magic_link:
    steps: [VIEW → QUOTE → ETA → CONFIRMED → COMPLETE]
    auth: tokenized magic link, signed by sign-token edge function, revocable
  three_step_marketing_pitch:
    - "Request comes in (WhatsApp/email/web → structured work order instantly)"
    - "You quote and schedule (price + tech + bay + slot; fleet approves via magic link)"
    - "Complete with proof (final cost + photo + signature; audit trail auto-generated)"
  daily_access:
    "View Today's Work" → enter email/phone → magic link in <30s → org-scoped TODOs
  acknowledgment_target: "<4 hour median ack time"
  first_value_target: "<5 minutes"

channels:
  primary: SMS (Twilio, sender +1 912 504 4460, 10DLC PENDING — blocks launch)
  email: Resend (branded auth emails configured)
  whatsapp: phasing out
  in_app: dashboard
  sms_market_thesis: "US market favors SMS+email > WhatsApp"

api_surface:
  base: /api/v1 (Supabase Edge Function `api-v1`)
  auth: X-API-Key header → api_keys table
  endpoints:
    work_orders: [POST /, GET /, GET /:id]
    quote: [POST /:id/quote, /:id/approve-quote, /:id/decline-quote]
    execution: [/:id/assign, /:id/en-route, /:id/start, /:id/ready-for-pickup, /:id/request-delivery, /:id/complete, /:id/cancel]
    parts: [POST /:id/parts, PATCH /:id/parts/:partId]
    attachments: [POST /:id/attachments]
  webhooks:
    events: [work_order.created, quote.submitted, quote.approved, quote.declined, assignment.updated, work.started, work.waiting_parts, work.ready_for_pickup, delivery.requested, work.completed, work.cancelled]
  source_types_recognized: [fleet_api, manual, whatsapp, email, webform, agent]
  integration_pitch: "Sell to fleets with existing TMS/ERP — they POST work orders, FleetOS coordinates the supplier side"

key_features:
  compliance_engine:
    claim: "100% Audit Ready, Instant Verification"
    evidence: [event_log, signature capture, completion photo, odometer, attachments, timeline]
  unified_inbox: "WhatsApp + email + web form → one structured queue"
  traffic_light_urgency: {URGENT: red, TODAY: yellow, SCHEDULED: green}
  no_app_required: "Suppliers/fleets respond via browser magic link — no install"
  org_scoped_access: "Magic link grants org-scoped view, not user-scoped"
  rate_limits: "Migration 033 — present"
  rls_hardening: "Multiple migrations (014, 017, 021, 032, 20260404_*); production-grade"

agent_ecosystem_adjacent:
  blade_aka_openclaw:
    role: "FleetOS growth operator — autonomous sales/marketing agent"
    repo: separate
    job: [local supplier prospect research, fleet target research, outreach drafts, content support]
    attribution: "V1 Blade attribution contract LOCKED; migration 20260418_blade_fleetos_attribution.sql"
  mission_control:
    role: "Human sales and activation cockpit"
  three_great_roles_thesis:
    - Architect (strategy, weekly decisions)
    - Builder (ships product/content/experiments)
    - Reviewer/Refiner (evals output, identifies drift)

points_of_interest_for_sales_agent_evals:
  qualification_signals_FLEET_buyer:
    - Currently using WhatsApp/email/calls for service coordination
    - Multiple external suppliers, no central queue
    - Has had a "missing invoice" or "audit dispute" incident
    - US-based (hard filter)
    - Operates in dense metro (Miami first, then expand)
  qualification_signals_SUPPLIER_buyer:
    - Mobile/dispatch operation in [tire, towing, roadside, mechanic, body, recovery]
    - Receives requests from multiple fleets via different channels
    - Currently has no structured intake / quote-to-invoice flow
    - Owner-operator or small dispatch team
  disqualification:
    - Outside US
    - Already on a competing TMS that owns dispatch
    - W2 internal-only fleet (no external suppliers) — wedge mismatch
    - Single-fleet single-supplier exclusive relationship
  hooks_per_pain:
    audit_dispute: "Every job timestamped, photo, signature, exportable"
    quote_chaos: "Magic-link quote → fleet one-tap approve"
    no_app_friction: "Suppliers don't install anything"
    free_tier: "$0/mo, no credit card — removes procurement objection"
  channels_to_use_for_outreach:
    - SMS (once 10DLC clears — currently blocked)
    - Email (Resend SMTP live)
    - LinkedIn / cold email manual until SMS clears
  cta_paths:
    fleet: "?view=FLEETOS_FLEET_ONBOARDING"
    supplier: "?view=FLEETOS_SUPPLIER_ONBOARDING"
    public_request: "/request/:slug"
    track: "/track/:token"
  metrics_to_eval_against:
    activation: ["first work order created in <5 min", "first magic link clicked"]
    coordination: ["<4hr median ack time", "quote→approval cycle time"]
    retention: ["repeat requests in 30d", "relationship health score"]
    viral: ["invite sent / accepted ratio", "shared_page conversions"]

constraints_blockers_for_sales:
  10DLC: "A2P registration not started — 1-2 week carrier approval blocks SMS launch"
  no_us_users_yet: "Pre-launch; sales agents need to seed first cohort"
  founder_geo: "Founder in SA (+27 dev phone is not a geo signal; FleetOS is US-only)"
```

***

## 3. Suggested Eval Anchors (per sales-agent role)

| Agent role                  | What to eval against this snapshot                                                                                                           |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **Researcher / Prospector** | Did it surface US-only? Right metro density? Right supplier category from `audience_pills`?                                                  |
| **Qualifier (BDR)**         | Did it hit `qualification_signals_*` and reject `disqualification` cases? Did it identify FLEET vs SUPPLIER side?                            |
| **Outreach Drafter**        | Did the message map a real pain → a `hooks_per_pain` hook? Did it pick the right `channels_to_use_for_outreach` (no SMS until 10DLC clears)? |
| **Demo / Pitch**            | Did it use the `three_step_marketing_pitch`? Did it route to the correct `cta_paths`? Did it lead with the free tier?                        |
| **Activation / Handoff**    | Did it hit `first_value_target <5 min`? Did the lead create a work order or accept a magic link?                                             |
| **Reviewer / Refiner**      | Track `metrics_to_eval_against` weekly; flag drift from `not_positioned_as` traps.                                                           |

***

## 4. Hard "Do Not" List (sales-team guardrails)

* Do not pitch outside the US.
* Do not pitch as "all-in-one fleet management" — wedge is **external coordination**.
* Do not promise SMS until 10DLC clears.
* Do not require app install in any pitch — magic link is the differentiator.
* Do not lead with paid tier; free tier is the wedge.
* Do not target single-supplier-single-fleet relationships — no coordination value.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://t420.gitbook.io/t420/fleetos-data-structure-for-sales-evals.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.