📄FleetOS Routing & Access – FINAL Claude Code Brief

Status: BIBLE - Non-Negotiable Truth Date: 2026-01-09 Purpose: Align the last ~5% of FleetOS routing, notification, and access logic so it behaves exactly as intended in real-world B2B operations (fleets + suppliers), especially under emergency conditions.

---

⚠️ Claude: Assume 95% of the system already exists.

Your task is NOT to redesign — it is to verify, adjust, and close gaps.

---

1️⃣ Core Truths (These Are Non-Negotiable)

A. Organisation-first, not user-first

• All work (RFQs / TODOs / jobs) is owned by an Organisation (Org).

• Humans are not primary entities; they are temporary actors.

B. Magic links = capabilities, not identities

Magic links are the only way to access FleetOS.

They are:

• time-bound

• scope-bound

• org-bound

They do not represent accounts or users.

C. Never block work

Routing must never fail because:

• a person is unavailable

• a contact was not predefined

• a user does not "exist"

Continuity beats formality.

---

2️⃣ Canonical Objects (Confirm These Exist)

Claude, verify these exist or are trivially derivable:

Org

• OrgID = hash(canonical email domain)

TODO / RFQ

• owned by Supplier Org

• linked to Fleet Org

• status lifecycle: new → acknowledged → in_progress → completed / declined

MagicLink

• Org-scoped or RFQ-scoped

• capability-scoped (view, act, acknowledge, update)

• expiry enforced

EventLog

• records every access + action

If any of these are missing → flag explicitly.

---

3️⃣ Routing Rules (This Is the Law)

RFQ Ingress

When an RFQ arrives (WhatsApp / email / web):

1. Resolve Fleet Org (sender domain / phone)

2. Resolve Supplier Org (target)

3. Create TODO owned by Supplier Org

4. Status = new

5. Log event

Notification Rule (Critical)

RFQs notify the organisation first, not a person.

Routing logic:

If a contact hint exists (phone suffix / alias):
    → send RFQ-scoped magic link to that contact
ELSE:
    → send org-level magic link
    → target:
        - last active org access point, OR
        - org default channel

There must always be org-level fallback. No single point of failure.

---

4️⃣ Access Model (Clarify + Verify)

Daily Access (Very Important)

Operators must be able to:

1. Go to fleetos.com

2. Click "View Today's Work"

3. Enter work email or phone

4. Receive a fresh org-level magic link

5. See all open TODOs

No login. No accounts. No remembering old links.

Verify this flow exists or propose minimal changes.

Emergency Access

• Any org member who can regenerate an org-level link can act.

• No dependency on named contacts.

• Still logged, still scoped, still time-bound.

Confirm this is true in the current build.

---

5️⃣ Contacts (Important Clarification)

FleetOS v1 does NOT have contact lists.

Contacts are emergent, not pre-created.

A "contact" exists only when:

• someone clicks a magic link

• or receives a targeted notification

If the current build assumes users / contacts → flag and propose how to loosen it without refactoring everything.

---

6️⃣ What We Want From You (Process)

Claude, do NOT start coding yet.

Step 1 — INGEST

• Read this brief fully.

• Read the existing codebase with this model in mind.

Step 2 — MAP

Produce a short document with:

• What already matches this spec

• What partially matches

• What is missing or misaligned

Step 3 — PLAN

Propose:

• minimal changes required

• files/modules affected

• any data model tweaks

• any routing logic adjustments

Step 4 — WAIT

Do not implement until founders review and sign off.

---

7️⃣ Success Criteria

We will approve your plan if:

✅ RFQs can never get "stuck" due to identity issues ✅ Any org member can recover access in <30 seconds ✅ Targeted notifications exist without creating fragility ✅ There is zero confusion between:

• "who owns the work" (the org)

• "who is acting right now" (temporary)

---

8️⃣ One Sentence Test (Use This Internally)

If the system behaves such that:

"A tired operator in an emergency can remember FleetOS, go to the site, and immediately see today's work without knowing who was invited or logged in"

then routing is correct.

If not, it needs adjustment.

---

End of Brief