Skip to content

IDENTITY-ENTRY-PATH-01 — Design Note

Type: Design note (capture artefact — NOT a brief) Status: Parked / informs Bricks 3–5 of People Phase 1.5; feeds a new ADR (see §6) Author: Claude · Date: 2026-06-14 References: PC-SPEC-01 v0.3 (Two-Layer Identity Model; Provisioning & The Admin-Only Mint Rule; T4B section), ADR-020, ADR-024, ADR-040, ADR-042; the parked OPERATOR-CLIENT-FILE-USERS-VIEW-01

Why this note exists

Surfaced 2026-06-14 in conversation while scoping People Phase 1.5. It records a model for how a human enters RTOpacks — the universal entry path that every invited person walks, regardless of tier. The model was reasoned out from a concrete scale scenario (a 100-person RTO, not the 3-person test client) and two compliance insights that give it weight beyond UX convenience.

This note does not authorise build. It is a capture artefact, same as OPERATOR-CLIENT-FILE-USERS-VIEW-01. Its job is to settle the model now, while it is sharp, so that Bricks 3–5 are written against a fixed destination instead of re-deriving it each time. It also seeds a new ADR (§6) that the canon owner (Tim) authors.

It does not change Brick 2 (seat↔person link display). Brick 2 is the floor's first visible payoff and stands independently of everything here.

The model — the universal entry path

Every human who is invited into RTOpacks walks the same path, whatever tier they are headed for:

  Admin invites          Person logs in           First-run GATE              Admin approves         Grant / access
  (login minted,    →    (my.rtopacks.dev,    →    authors own record    →    (reviews the          →  opens
   email + name +        familiar entry            — the gate to entry;        attested record)         (T4A seat consumed,
   membership type)      for everyone)             attests true & correct                                or T4B confirmed)
                                                   via signed declaration

The shape mirrors what the founding admin (the "L4"/T3 lineage) did organically: signed up, came in, minted themselves. The entry path generalises that arc — the admin initiates the invitation, but the person authors their own facts as the condition of entry. Nobody's identity facts are typed by someone else.

The five moments

  1. Admin invites. From the Users surface (the renamed Administration→Team — see OPERATOR/Users note and PC-SPEC-01 Admin-Only Mint Rule). The admin authors only login facts: email, display name, membership type (→ tier). The admin does not author person-facts. (This is the Admin-Only Mint Rule: identity is minted only from Administration.)
  2. Person logs in. Through my.rtopacks.dev — the same entry gate for everyone, T4A / T4B / T4 alike. One familiar door, not a tier-specific maze.
  3. First-run gate — self-authoring. Before any other surface opens, the person authors their own pc_persons record using the same edit path built in Brick 1 (PERSON-RECORD-EDIT-PATH-01), pointed at their own record rather than an admin editing on their behalf. This is the gate: no completion, no entry.
  4. Attestation. The authored record terminates in a signed declaration — the person attests the record is true and correct. This is the compliance asset (see §2). It is filed into their People record as an audit artefact.
  5. Admin approves → grant/access opens. The admin reviews the attested record. On approval, the grant lands: if the invitation offered a seat (T4A), the seat-consuming grant is minted and access opens as an operator; if the invitation was self-maintainer-only (T4B), they are confirmed as a T4B with their record authored and maintained. (Assertion ≠ verification — ADR-042. Approval is an administrative gate, distinct from credential verification.)

Why this model is right (not just neat)

Two compliance insights give the model weight beyond convenience. These are the rationale the spec should carry, because they drive later design decisions.

1. Self-attested data is a stronger compliance asset than admin-entered data

Admin-typed person data carries the defect "someone may have mistyped — that wasn't what I meant." Self-authored, self-attested data carries "the person swore this is true and correct." For an RTO at audit, that is the difference between a weak record and a defensible one. The signed declaration is not a finish-line nicety — it is the point:

  • It converts a data-entry step into an audit artefact with the person's attestation attached.
  • It shifts the integrity burden onto the person ("if it's wrong, that's a misattestation, taken on face value"), which is exactly where an RTO wants it.
  • It feeds the People record as a filed, attested document — useful downstream for the CV-for-T&A-audit use case.

Design implications to carry forward (not for build now): the declaration should be timestamped and versioned, and re-triggered when material facts change (a stale attestation against changed facts is worthless). How re-attestation is scoped is a later design question; the principle is recorded here.

2. The entry gate is a compliance control, not an onboarding step

The gate's deeper value: it refuses operational access until the compliance record exists and is attested. This directly counters the classic RTO audit failure — "we never actually checked their credentials before they started teaching." The product is not being polite by asking for details first; it is being a compliance spine by making un-attested operation structurally impossible.

This is a selling point and a design principle at once: RTOpacks does not let a person become operational before their compliance record is authored and attested. The gate is the control.

What this does and does not change

  • Does NOT change Brick 2. Brick 2 = make the existing user_id link visible both ways (Users confirming-slice + click-through to People; People shows linked login). It needs none of this model to be correct. Proceed as scoped.
  • Resolves the open edge from Brick 2 scoping. The "person not linked to any login" case (a pure compliance record, no seat — common at scale) is answered: such a person simply has not walked the entry path. Whether the People-side display dangles an "invite" affordance toward Brick 3 is a Brick 3 decision, now with a clear model behind it.
  • Defines Brick 3's shape. Brick 3 (invitation / admin-only mint) is no longer "admin mints a login" — it is the full entry path: invite → first-run self-author gate → attestation → approve → grant. Meatier; deserves its own design pass against this note.
  • Confirms Brick 1 was more load-bearing than framed. The self-authoring gate (moment 3) reuses the Brick 1 edit path pointed at the person's own record. The floor we built is the same surface the self-maintainer meets on day one.

Build/work sequence (the destination, ordered)

Documentation (now, cheap, high-leverage — pre-revenue is the right time to pay this cost): - This note — the entry-path model, captured. - New ADR (§6) — Tim authors; Claude drafts text for sign-off. - Users-spec lift (Team→Users rename + own spec) — hold the full write until this note exists, because the Users spec and the entry path share the invite/mint boundary; writing them together stops drift.

Build (order unchanged; content now clearer): - Brick 2 — link display both ways. Clean, ready, independent of this note. - Brick 2.5 (surfaced 2026-06-14) — tier_grants.tier CHECK migration to add T4B to the enum. Currently ('T3','T4','T4A') — T4B is absent; nothing T4B can be minted until the constraint is migrated. Small, substrate, must precede any T4B brick. - Brick 3 — invitation / admin-only mint, written against this note (invite → self-author gate → declaration → approve → grant). - Brick 4 — T4B self-maintainer view (the locked-down single-record surface the gate drops them into). - Brick 5 — T4B → T4A promotion (grant change, not re-onboard).

Parked (acknowledged, not built)

  • Webcam / profile photo capture at self-authoring time → becomes the person's icon, feeds CV-for-T&A-audit. Good idea, Phase 2+ texture. Recorded so it is not lost; deliberately not allowed to pull focus now.
  • Re-attestation triggers — the declaration re-firing when material facts change. Principle recorded (§2.1); scoping deferred.

Open questions this note does not resolve

  • The approval state. "Admin approves the attested record before access fully opens" is a workflow state not yet in the spec or substrate. What does "pending approval" look like — can the person log in but see only their own record until approved? Is approval per-record or per-grant? Brick 3 design pass settles this.
  • Naming for the access surface. Working decision: Users (the tile is currently "Members"; the page is currently titled "Team"). Rename + page-retitle + own spec to follow. The contrast "Users (logins) vs People (humans)" is crisp and stops person-fact bleed-through. Confirm at the Users-spec lift.
  • Tier nomenclature. T4A/T4B/T3 vs an "L" lineage — unsettled informally. Glossary owns the canonical answer; flagged for the canon owner.

Capture artefact. Records the entry-path model so it survives to inform Bricks 3–5 and a new ADR. Not a brief. Does not change Brick 2.