Operator manual

How to run AIOS day to day: create a customer, give them a key, get their taxis onto the platform, and know which page belongs to whom. Written for the person holding the master key.

Who is who

Two different companies use this platform, and their staff must never see each other's data. Almost every confusing decision becomes obvious once you know which one you are dealing with.

Who	What they are	Their page
You master	Founder / super-admin of realaios. Not a customer, and not an RBAC role.	/console
Taxi boss	The customer who owns the taxis and runs the fleet. Also called owner-operator or association.	/cosmos-taxi/owner
Insurance company	One underwriting business, many staff — underwriters, actuaries. They price the risk.	/cosmos-taxi/ops (Underwriting) and /cosmos-taxi/insurer
Financier	Whoever financed the vehicle. Asset control and recovery.	/cosmos-taxi/finance
Driver	The person behind the wheel — not the same thing as the vehicle. Their record follows them between taxis. Sees only themselves: their shift, their licence dates, their ratings in aggregate.	/cosmos-taxi/driver
Rider	The public. Sees only their own trips and wallet.	/cosmos-taxi/rider

The one trap. The role called ops belongs to the insurance company, not the taxi operator — despite how it sounds. It opens the underwriting console and the actuarial figures. For a taxi boss the role is always fleet. Getting this wrong hands your insurance client's product to a taxi owner.

Your first customer, end to end

The whole flow, in the order that works. Everything happens at /aios/team except the last step.

Create their fleet — a fleet is one customer's boundary. Name it after the business or the depot, e.g. "Khayelitsha Depot". Do this first: a member created before their fleet exists cannot be scoped to it.
Add the person — name, optional email, role fleet, and tick their fleet. Leave the permission grid blank unless you want to restrict them further.
Copy the key — an aiosk-… key appears once. Send it to them; they use it to sign in at /cosmos-taxi/owner.
Onboard their taxis at /cosmos-taxi/onboard — see Onboard taxis below.
Download the tokens CSV before leaving that page. It is the only copy you will get.

You cannot skip step 1. A fleet-role member with no fleet selected is refused outright — because without a fleet they would see every operator's vehicles and the simulated test taxis as if they were their own.

Create a fleet

A fleet is the tenant boundary — one customer's set of vehicles, and the unit an insurance policy is written against. One taxi boss normally has exactly one fleet.

At /aios/team, type a name under New fleet and add it. That is all it is: a named container that vehicles and people get attached to.

Fleet is not route. A boss with 40 taxis across 5 routes has one fleet and five routes. Routes live on the vehicle (see Onboard taxis), which is what lets the insurer compare the same route across different operators.

Add a user and give them a key

Name — who this is.
Email (optional) — so months later you can tell who holds this key. It is never used to sign in.
Role — see the role reference. For a taxi boss: fleet.
Fleets — tick the ones they may see. Required for fleet; leaving it blank for insurer-side roles means all fleets, which is usually what you want for them.
Console access grid (optional) — leave every box blank in the normal case. The grid only ever narrows access; ticking boxes restricts them to those tabs rather than granting anything extra.

The key is shown once. Copy it before closing the panel. If it is lost, delete the member and add them again — there is no way to read an existing key back.

Onboard taxis

At /cosmos-taxi/onboard you can add one taxi at a time, or paste a whole rank from a spreadsheet. Four columns, in this order — only Plate is required.

Column	Example	Where it shows up
Plate	CA 123 456	Identifies the taxi everywhere
Driver	Sipho Ndlovu	Under the plate on the owner dashboard
Association	CATA	A filter chip on the owner dashboard
Route	BELLVILLE - NYANGA	A filter chip — and how the insurer prices risk per route. Suggestions come from the real ingested network (Cape Town, eThekwini, Tshwane, Polokwane), so type a place name and pick the gazetted route.
Operating licence	WC-OL-123456	The PRE licence for this taxi
OL expiry	2027-03-15	Flags on the dashboard 30 days before it lapses

Pasting from a spreadsheet

Export as CSV and paste. A first line beginning with plate is treated as a header and skipped:

plate,driver,association,route,operating_licence,ol_expiry
CA 123 456,Sipho Ndlovu,CATA,BELLVILLE - NYANGA,WC-OL-123456,2027-03-15
ND 555 001,,,,,

Spelling does not have to be perfect. Association and Route are matched loosely, so Route N2, route-n2 and ROUTE N2 all become the same chip instead of three near-identical ones. The boxes also suggest values already in use.

Commas inside a field would shift the columns, so the single-taxi form strips them automatically.

Tokens and QR codes

Registering a taxi produces two things that look similar. Only one is a secret, and they behave completely differently if lost.

	Device token secret	Rider QR not secret
What it is	How the blackbox proves it is that taxi	A printable code a passenger scans to see their trip
Shown	Once, at registration	Any time
Stored	Only as a hash — it genuinely cannot be looked up	Generated from the device ID on demand
If lost	Re-issue it (Rotate). The old token stops working immediately.	You cannot lose it — reopen /api/taxi/qr?id=<device-id>

Re-issuing a lost token

Open the vehicle list, find the taxi, and use Rotate. You get a fresh token shown once; the blackbox must be updated with it, and the old one is dead from that moment.

Always download the tokens CSV at the end of an onboarding session. It is the only copy — re-issuing is the only alternative, and it means re-flashing the device.

Operating licences

In South Africa a minibus taxi needs an operating licence from the Provincial Regulatory Entity under the National Land Transport Act. Three things about it shape how AIOS stores it:

One per vehicle — an owner with ten taxis needs ten licences, so the number lives on the vehicle, not on the fleet.
Tied to a specific route or area — which is why it sits beside Route on the form. They describe the same fact.
Valid five years at most — so it expires, and an expiry is a dated change in risk.

Membership of a registered taxi association is a legal prerequisite for holding a licence, which is why Association is worth capturing too.

These are self-declared. There is no public API to check a licence against the PRE, so AIOS records what you enter and never claims it is verified. Treat the flags as a prompt to check the paperwork, not as proof of it.

Once an expiry date is on file, the owner dashboard shows OL expiring within 30 days and OL expired after it lapses.

The change log

Every change made by every user is recorded at /aios/logs — who did it, their role, what changed, whether it worked, and when. Owner key only.

Filter by user, change type, role, outcome (succeeded / failed), date, or free text — search a plate and see everything that ever happened to that vehicle. Export the filtered view as CSV.

What is recorded: vehicles registered, removed, tagged, revoked or reactivated; device tokens rotated; licence documents bound; team members and fleets added or removed; vehicles assigned between fleets; actuarial and insurer settings changed.

Tokens are never written to the log. A rotation records that it happened, on which vehicle, by whom — never the token itself.

Role reference

Pick by who the person works for, not by what the word sounds like.

Role	Who it is	Sees
fleet	The taxi boss and his staff	Their own fleet: vehicles, drivers, scores. No actuarial figures.
ops	Insurance underwriting staff — not the taxi operator	Underwriting console, scoring rules, exposure, risk concentration
insurer	Insurance boardroom	Reports, underwriting feed, actuarial settings
financier	Whoever financed the vehicles	Only the vehicles they finance
support	Helpdesk	Read access plus rider support. No risk products.
viewer	Anyone who should only look	Read only
owner	Reserved for you	Cannot be created here — it is the master key

Role and fleet together are the floor, enforced on the server. The permission grid can only narrow that floor, never widen it.

Which page is whose

Page	For	What it does
/console	You only	Whole-picture cockpit: every surface, threads, roadmap
/aios/team	You only	Fleets, members, keys, permission grid
/cosmos-taxi/owner	Taxi boss	Their fleet, scores, service due. Tap a taxi for live location and detail.
/cosmos-taxi/onboard	You / operator	Register taxis, issue tokens and QRs, provision e-SIMs
/cosmos-taxi/ops	Insurance	Underwriting: scoring rules, exposure, risk concentration
/cosmos-taxi/insurer	Insurance	Boardroom: reports, actuarial settings
/cosmos-taxi/finance	Financier	Asset register, due-process immobilise
/cosmos-taxi/live	Public	Live fleet map. Driver names hidden unless signed in.
/cosmos-taxi/driver	Drivers	Their own record: shift start/end, licence & PrDP countdown, ratings in aggregate. Self-claimed on the driver's own phone — no invite key needed.
/cosmos-taxi/rider	Riders	Their own trips, wallet and receipts

Keys and sign-in

Key	Who holds it	Opens
Master	You	Everything, including /console
Sub-master	An evaluator you trust	Everything except /console and saving global defaults
aiosk-…	Each member you create	Only their role's consoles, only their fleet(s)

A console remembers your key in that browser. Sign out forgets it on that device only — it does not change or cancel the key, which keeps working everywhere else.

Never paste a key into a page, ticket or chat that others can read. Member keys cannot be read back once created; if one leaks, delete that member and issue a new one.

Troubleshooting

"It made me sign in again"

Signing in on one taxi console now carries across the owner, underwriting, fleet, vehicle and reports pages. If you are asked again, the key was cleared on that device — sign in once more and it will stick.

A customer says they see taxis that are not theirs

Their key is not scoped to a fleet. Check the member at /aios/team: the Fleets column should name their fleet, not every fleet. Delete and re-create them with the fleet ticked.

Simulated taxis appearing in a customer's dashboard

They should never be. Simulated vehicles are hidden from every member key and visible only to your master key. If a customer sees them, their key is unscoped — same fix as above.

A taxi never appears under any route chip

It was registered without an Association or Route. Those chips are built from what you enter at onboarding.

A device never comes online

The blackbox has the wrong token, or it was rotated after the device was flashed. Re-issue the token and update the device with the new one.