People — Companion¶

The plain-English companion to people-02-spec.md. The spec is the clause-bound "what to build"; this is the "what it is, how it works for the user, and where the build is" — the doc to read when someone says "remind me what People is and where we got to." Derived from the spec + the build state as at 2026-06-29 (commit a6b078c7). Not canonical — it tracks the living build; where it and the spec disagree, the spec is right and this is corrected.

1. What People is (the one-paragraph answer)¶

People is the compliance workforce module of the RTOpacks workspace. It is the store of the credentialed people who operate in a training organisation — primarily its trainers and assessors — and it answers the regulator's standing question: "can the people delivering and assessing your courses prove they're qualified, current, and fit to do so?"

The name is slightly misleading. People is not a flat staff directory. It is organised by compliance role, not system access — a person appears because their qualifications matter to an audit, not because they have a login. The organising switch is TAE4 (the Cert IV in Training & Assessment): holding it makes you the full four-dimension compliance record People exists to keep; not holding it makes you a lighter, differently-shaped record (an expert, a support person, an admin).

The mental model we use internally is the librarian and the bookcase: People is a bookcase of vetted resources; the T4 admin is the librarian — the only one who shelves, vets, and removes records. Everyone else is read-only: they can take a book off the shelf and read the compliance picture, but only the librarian edits the books. The only door into People is a grant. That single rule is the whole access model.

2. How it actually works — the user journey¶

This is the part worth getting straight, because it spans three surfaces and a deliberate separation.

The triangle: enter → approve → appears (and revoke → stays-but-marked).

Entry (/entry). A person self-authors their own record — name, employment, credential, the compliance facts. They do this themselves because the most authoritative source for a trainer's currency is the trainer. This is the "author" lens. Entry is reached after an admin invites them (below); a person can't just wander in.
Admin → Team (the mint surface). An administrator (a T4 — the crown) invites a person from the Team screen, reviews what they self-authored, and approves them. Approval mints a grant (a tier_grant) — the act of "shelving the book." Identity is minted here, from the admin side — never from inside People. This is the deliberate rule: People displays people; it does not create them.
People (the register). Once a person holds a live grant, they appear in People. This is the lifecycle gate: a person shows up in the register if (and only if) their record is tied to a non-revoked grant. No grant / still-pending invite → they don't appear yet. Revoke the grant and they don't vanish — they stay, marked "Revoked {date}." That's deliberate: revocation is audit evidence. A five-yearly audit may need to see a trainer who delivered for two years and then left; deleting them would erase the compliance history. (We never hard-delete a person; we deactivate.)

Where it shows up for the user: the People tile and its register live on the workspace surface. Whether you see the admin controls (invite, approve, the Team screen) depends on the hat you're wearing — T4 admins get the Team/admin surface; seated members (T4A) get the read-only register and their own record. A person who holds both hats can slide between User and Admin from the account menu (the toggle in the top-right). So "you come into entry, you're approved via Admin → Team, and if you hold the credential/grant you appear in People" is exactly the loop — entry authors it, admin blesses it, the grant makes it visible.

3. What you can do today (the live functionality)¶

As at 2026-06-29, the People surface is read-only and grant-gated — a deliberate Round-1 shape (it proves the triangle before it re-opens authoring):

The register (/people) — a table of every grant-backed person in the org: name, role, employment type, and a row of at-a-glance status dots. The live register shows five dots: the four clause-bound compliance dimensions (credential, vocational competency, industry currency, T&A currency) plus WWCC. Note WWCC is a suitability fact (working-with-children clearance), not a fifth compliance dimension — it rides alongside the four because it's part of the at-a-glance read, but the spec's compliance core is the four. The dots read green / amber / red / grey. Filter by status or role. Revoked people stay, marked.
The person detail (/people/{id}) — the full record: identity & suitability, credential, vocational competencies (with experience + licences), CPD, supervision. All read-only on this surface today.
The Matrix view — person × qualification compliance grid.
Field-level privacy (ADR-061) — a colleague (another seated member) viewing your record sees it with five personal fields withheld (address, DOB, middle name, WWCC number, USI) — shown as "Withheld," never blank. Self and admins see the full record; a self-maintainer viewing someone else is refused.
Self-service (/my-record) — a person can author/assert their own facts (the T4B self-maintainer path), but never verify them (the integrity boundary: you can claim, only an admin can confirm).
Admin → Team — invite, approve/return onboarding, promote, deactivate; this is where grants mint and seats are consumed.

The compliance read is honest: a trainer with no credential record on file shows red (genuinely missing); a management person with no teaching obligation shows grey N/A (correctly nothing to flag). The dots are computed live, never stored.

4. Where we're at (build state)¶

People went from "barely built" to a real working surface across three arcs this season:

Round 1 (shipped + live). The whole surface was made read-only, token-conformant, and grant-gated, and the lifecycle gate was built (the triangle above is real and walked). Write authorisation was aligned so an admin is recognised by the full set of grants they hold, not just their highest.
Schema cleanup (shipped). The last prototype-debris table was dropped; the schema now reads as a living system.
Role-vocabulary corrective (shipped). The role vocabulary was settled to four populations (below), single-sourced, guarded at the write boundary, and a latent compliance mis-flag was fixed at both code and data.

The four populations (the banding the whole module organises around):

Population	Holds TAE4?	What People keeps for them
Trainers / assessors	Yes	The full four-dimension compliance record — what People is for
Experts / industry specialists	No (legitimacy is expertise-under-direction)	A supervision-driven record, not a credential one
Support / clerical	No	Name + position only — part of the resource picture, no compliance dimensions
Admins (management)	Maybe / not relevant to the role	A wafer-thin record — name, role, contact. Accountability obligation, not teaching

(Standing role values are trainer_assessor, expert, support_staff, management. Whether a given trainer delivers, assesses, or both is NOT a role tag — it's the engine's per-assignment verdict, derived from their credentials.)

5. The architecture, in plain terms (so the "how" is honest)¶

HARD SEPARATION of identity and compliance. Who you are and what you may access (logins, grants, seats) lives in one database (identity-db); your compliance record lives in another (workspace-db). They never join in SQL. When People needs to know who holds a live grant, it asks the internal API over a service binding and joins the answer in code. This keeps the credential substrate and the access substrate from bleeding into each other.
The lifecycle gate is an app-level join, not a database join — exactly because of that separation. (Consequence: People now has a hard runtime dependency on the internal API; if it's unreachable, the register fails closed rather than showing a wrong or empty list.)
The compliance engine (canDeliver) is specified but not yet built in code. Today the live verdict is a simpler "can make assessment judgements" read off the credential. So the surface today is structure and state, not yet the full per-assignment delivery verdict — that lights up when the engine lands.
The regulated substrate (rto-nrt-db, the national training data, ~15,000 enriched rows) is sacred — read-only, never written.

6. What's owed (Round 2 and beyond)¶

Held deliberately for their own round, on the now-clean substrate:

Population banding by depth-of-obligation + management's "wafer-thin" render (name/role/contact only).
The visual gate-vs-flag colour/grouping system (a signal language for the populations) — explicitly not yet designed.
Multi-hat is normal. In the micro/small-RTO market — the reachable early segment, and the shape UCCA itself runs as — one or two people wear every hat (director and trainer/assessor). The data model treats a person as single-role today; making role multi-valued is a backlogged change we've re-weighted upward, because multi-hat is the dominant shape there, not the edge. (This also validates the access-vs-membership split: the crown grants access; the role describes the record; one person is legitimately both.)
The canDeliver engine + the Studio↔People seam (Studio asks "can this trainer deliver this unit?"; People answers — the verdict is People's, Studio only renders it).
Re-opening authoring through a librarian-only path (Round 1 stripped write affordances to dormant; they return T4-gated).

7. Why role is single-valued now (the corrective, in plain terms)¶

This is the freshest decision and the one most likely to confuse anyone who's seen older language, so it's worth saying cleanly.

A person in People carries exactly one role from four values: trainer_assessor, expert, support_staff, management. There is no trainer and no assessor as standalone values — they were removed. There is one teaching population, trainer_assessor, and that is the only role that carries a full compliance record.

The reason trainer and assessor aren't separate is the load-bearing idea: whether a person delivers, assesses, or does both is not a fact about the person — it's a verdict about an assignment. Give the same trainer two different units and the answer can differ for each, because it's computed from the credentials they hold against what that unit's activity requires. So "delivers vs assesses" is the engine's per-assignment output (canDeliver, spec §3), never a tag you hang on the person. Tagging it on the person was presentation trying to do the engine's job — the corrective took that job back.

The mechanics, for the record: the four values are single-sourced in apps/workspace/lib/roles.ts (the const array, the type, the labels, the non-teaching subset). Every write boundary rejects a non-canonical role with a 400 and case-folds a valid-but-miscased one. The database column itself has no constraint — the guard is app-level, which is worth knowing if you're ever reasoning about what could land in that column from a raw write (answer: nothing, the writers won't pass it).

This corrective also killed a latent bug: a management person was being mis-flagged as missing trainer credentials, because one consumer compared role values without case-folding. Fixed at both the code (the comparison now folds) and the data (the stored values were normalised). It was latent on prod, never live — but it's dead now at both layers.

8. The principle behind the banding — depth-of-record follows depth-of-obligation¶

§4's table shows what each population gets. This is the principle that generates that table, and naming it matters because it's what makes the banding feel inevitable rather than arbitrary:

Every population appears in People, each rendered at the depth its obligation warrants.

trainer_assessor carries the heaviest obligation (they deliver and assess regulated training) → the full four-dimension record.
expert carries a different obligation (expertise under direction, not T&A credential) → a supervision-shaped record.
management carries an accountability obligation, not a teaching one → wafer-thin: name, role, contact.
support_staff carries the lightest → name and position only.

The sharp point — and the thing that resolves the "or absent" question — is management. It's tempting to think a non-teaching admin doesn't belong in a compliance module at all. But accountability to ASQA sits with management. When an RTO fails an audit, it's the managing agent whose name is on the line, not the trainer's. So the accountable party cannot be invisible in the compliance record. Management always appears — thin, but present. Depth-follows-obligation means thin, not absent.

(One canon note for whoever designs the Round-2 visuals: the banding is structural grouping, not colour. Foundation's rule is "colour individuates, structure groups." Populations are grouped by the shape and depth of their record, not by a hue. Colour in People is reserved for status — the gate-vs-flag distinction — not for population. Don't reach for "a colour per population" in Round 2; that cuts against canon.)

9. Single-valued now, multi-hat later — and why that isn't a contradiction¶

§6 banks "multi-hat is normal" as owed. Worth being explicit that this and §7 (role is single-valued) are not in tension — they're the present and the future of the same field.

Today: role is single-valued. One person, one role. This is the honest current state, and it's correct for what's built.

The known future: in the micro/small-RTO segment — the most reachable early market, and the shape UCCA itself runs as — the median operator is one or two people wearing every hat: director and trainer and assessor, because that's the only way a tiny RTO is viable. The spec frames multi-hat as an exception (§10.6, "the manager who also delivers"); in the core early segment it's the dominant shape. So role going single→multi-valued is a real backlogged data-model change, re-weighted up because it serves the core user, not an edge case.

Tim and Jimmy are the first two live specimens of this: stored today as single-hat trainer_assessor, but genuinely {trainer_assessor, management} — both hold TAE4 and run the business. Their management hat currently rides their tier (the crown that grants access), not their role (which describes the record). That's the clean separation worth holding onto: access is the crown, membership is the record — and a multi-hat director is legitimately both at once. When multi-hat lands, it's the record that learns to hold two hats; access already does.

10. What "the engine is spec-only" actually means for reading the surface¶

§5 says canDeliver is specified but not built. Because that's easy to under-weight, here's what it concretely means when you walk the surface today:

The compliance dimensions render state, but the state is read off simpler live inputs (a credential-section check, canMakeAssessmentJudgements), not the full per-assignment delivery verdict. The rich "can this person deliver this specific product under this activity" answer doesn't exist in code yet.
Several entities the spec describes aren't built: the delivery assignment itself (the thing the engine would evaluate), expert engagements, equivalence mappings. Some live tables are naming-drifted from the spec (pc_supervision is the spec's direction-relationship; pc_cpd is the spec's CPD record). So the spec reads as a target schema, not a built one — which is correct for a spec, but means you shouldn't read it as a description of what exists.
Practical consequence: red on a teaching person today means "no credential record on file" — a genuine, honest absence — not "the engine evaluated them and said no." There's no exit door to turn that red green yet, because the write-path that would capture credentials (/entry's dimension sections) is still stubbed. The red is honest incompleteness, not a verdict. It resolves when the capture path and the engine land — not before.

The takeaway: the surface today is structure and state honestly reported over a substrate that's mostly empty. It's not theatre, and it's not finished. It tells the truth, and the truth is "not built yet" in a lot of places.

11. The one-line version (the distillation — and how every companion closes)¶

People is the compliance record of an RTO's trainers and assessors. A person is invited by an admin, self-authors their credentials at entry, and appears in People once an admin approves them and a grant is minted — revoke the grant and they stay, marked, as audit evidence. It's organised by compliance role (TAE4 is the switch), it's read-only and grant-gated today, and the per-assignment "can they deliver this?" engine is specified but not yet built.

Template note: a companion closes on its one-line distillation. The shape is overview (what / how / where) → rationale (the why behind the decisions) → this one-liner. The TL;DR earns its place at the end, after the reader has the whole picture — not at the top fighting its own meaning.

This companion points back at people-02-spec.md for the clause-bound detail; where the two disagree, the spec wins and this is corrected. The spec itself carries a small owed redline — §10.6 still frames multi-hat as the exception, §3.2 still lists the old role values, and an open "appear-as-name vs absent" question for management is now closed (management always appears, §8) — to be applied to the governed spec as its own drip, not here.