> 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/routing_access_bible.md). # 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** --- # 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/routing_access_bible.md?ask=&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.