Four-tier access model: self-governing admin, pre-login access, audit trail

PI decisions 2026-07-22:
- Roles: pi | maintainer | lab | external (legacy "member" reads as
external). Lab members and above: unlimited saved runs.
- PI role holds escalation rights in-app (grant/revoke staff, act on
staff accounts, audit view); ADMIN_EMAILS is bootstrap + break-glass
only. Maintainers get the operational surface. Nobody can change
their own role.
- Construct verification is maintainer-only (the RA's job); PI/admin
keep a read-only queue.
- Access before sign-in: email-bound pre-assigned roles (staff-capable,
claimed on first password/Google sign-in) and signed 7-day invite
links (lab/external only, ?invite= signup flow).
- Append-only admin_audit table records every admin action; visible to
PI/env admins.
- Docs split: /guide = navigate-and-test; new /product page = access
model + capability matrix + architecture (moved from guide).

MANUAL_TESTING.md

@@ -168,15 +168,38 @@ Checklist before giving the URL to real users:
 
 ## 12. Admin page (/admin)
 
-Requires `ADMIN_EMAILS` to include your signed-in email (see .env.example).
+Requires `ADMIN_EMAILS` to include your signed-in email (see .env.example),
+OR a pi/maintainer role. The env allowlist is bootstrap + break-glass; the
+PI role carries the same escalation rights in-app. The full access model is
+documented at /product.
 
-1. Sign in with an allowlisted account: an "Admin" link appears in the header;
-   non-admins (and signed-out visitors) see an access notice at /admin.
+1. Sign in with an allowlisted or staff account: an "Admin" link appears in
+   the header; non-admins (and signed-out visitors) see an access notice.
 2. Overview: account/run/project counters plus scales awaiting verification.
-3. Users: toggle a user to "lab" (their saved-run cap disappears - check
-   /api/auth/me shows max_saved_runs null), reset a password (temporary
-   password shown once; old one stops working), delete a user (removes all
-   their data; self-deletion refused).
+3. Users - four tiers (external user, lab member, maintainer, PI):
+   - Set a user to "lab member" or above: their saved-run cap disappears
+     (check /api/auth/me shows max_saved_runs null).
+   - Set a user to "maintainer" or "PI": they also get this admin page.
+   - Escalation needs PI or env-admin rights: a maintainer gets 403 on
+     granting pi/maintainer, and on resetting the password of, changing the
+     role of, or deleting a pi/maintainer account. A PI-by-role CAN do all
+     of that (no env entry needed). Nobody can change their own role.
+   - Reset a password (temporary password shown once; old one stops working),
+     delete a user (removes all their data; self-deletion refused).
+4. Access before sign-in:
+   - Pre-assign a role to an email (staff roles need PI/env rights): register
+     with that email afterwards - the account lands at that tier, the
+     assignment shows "claimed". Works for Google sign-ins too.
+   - Create an invite link (lab member or external only): open it in a
+     private window - the signup form announces the invite; registering
+     through it grants the role. Expired/garbage tokens refuse registration.
+5. Construct verification is maintainer-only: PI/env admins see the queue
+   read-only (no action buttons; the API returns 403), a maintainer can mark
+   scales verified. Statuses are applied back to the library YAML before
+   production.
+6. Audit trail (PI/env admins only; maintainers get 403 and don't see the
+   card): every role change, reset, deletion, invite, pre-assignment,
+   requeue, and verification appears with actor, target, and time.
 4. Failed runs: a failed job lists with its error tail; Requeue re-runs it
    (refused when the corpus file is already gone - anonymous retention).
 5. Verification: mark a scale Verified; its "unverified" flag disappears

backend/app/admin.py

@@ -10,8 +10,12 @@ Four concrete pains drive this, nothing speculative:
   * usage numbers + failed-run triage (the PI's "how is testing going?"
     answered with counts, and stuck runs requeued without SQL).
 
-Access: signed-in AND email in the ADMIN_EMAILS env allowlist. Admin is an
-env capability, not a DB role, so the DB cannot mint admins.
+Access: signed-in AND (email in the ADMIN_EMAILS env allowlist, OR role
+pi/maintainer - PI decision 2026-07-22). The app is self-governing: the
+PI role carries escalation rights (grant/revoke staff, act on staff
+accounts), maintainers get the operational surface only, and the env
+allowlist is bootstrap + break-glass (seed the first PI; recover a
+locked-out lab). Every mutating action lands in the admin_audit table.
 """
 
 from __future__ import annotations
@@ -27,16 +31,47 @@ from sqlalchemy.orm import Session
 from . import auth, retention, storage
 from . import jobs as jobs_module
 from .db import get_db
-from .models import Construct, Corpus, Job, Project, User
+from .models import AdminAudit, Construct, Corpus, Job, Project, RoleAssignment, User
 
 router = APIRouter(prefix="/api/admin", tags=["admin"])
 
 
-def require_admin(request: Request) -> dict:
+def require_admin(request: Request, db: Session = Depends(get_db)) -> dict:
     user = auth.get_current_user(request)
-    if user is None or not auth.is_admin(user.get("email")):
+    if user is None:
+        raise HTTPException(403, "Admin access required.")
+    env_admin = auth.is_admin(user.get("email"))
+    row = db.get(User, user["id"])
+    role = auth.normalize_role(row.role if row else None)
+    if not env_admin and not auth.role_is_staff(role):
         raise HTTPException(403, "Admin access required.")
-    return user
+    # can_escalate gates the power-expanding paths below (staff role grants,
+    # actions on staff accounts): PIs and env-allowlisted admins have it,
+    # maintainers get the operational surface only.
+    return {
+        **user,
+        "role": role,
+        "env_admin": env_admin,
+        "can_escalate": env_admin or role == "pi",
+    }
+
+
+def _require_escalation_rights(admin: dict, target: User, action: str) -> None:
+    """Actions on staff or env-allowlisted accounts require escalation rights
+    (PI role or env allowlist) - otherwise a maintainer could take over a PI
+    account (password reset), delete one, or mint more staff."""
+    if admin["can_escalate"]:
+        return
+    if auth.role_is_staff(target.role) or auth.is_admin(target.email):
+        raise HTTPException(
+            403, f"Only a PI (or allowlisted admin) can {action} a PI/maintainer account."
+        )
+
+
+def _audit(db: Session, admin: dict, action: str, target: str, detail: str = "") -> None:
+    """Append to the audit trail; committed together with the action itself."""
+    db.add(AdminAudit(actor_email=admin.get("email", ""), action=action,
+                      target=target, detail=detail))
 
 
 # ---------------------------------------------------------------- overview
@@ -46,9 +81,12 @@ def overview(db: Session = Depends(get_db), _admin: dict = Depends(require_admin
     runs_by_status = dict(
         db.query(Job.status, func.count(Job.id)).group_by(Job.status).all()
     )
+    users_by_role: dict[str, int] = {r: 0 for r in auth.ROLES}
+    for (role,) in db.query(User.role).all():
+        users_by_role[auth.normalize_role(role)] += 1
     return {
         "users": db.query(User).count(),
-        "lab_users": db.query(User).filter_by(role="lab").count(),
+        "users_by_role": users_by_role,
         "projects": db.query(Project).count(),
         "anonymous_projects": db.query(Project).filter_by(owner_user_id="").count(),
         "corpora": db.query(Corpus).count(),
@@ -78,11 +116,12 @@ def list_users(db: Session = Depends(get_db), _admin: dict = Depends(require_adm
             "id": u.id,
             "email": u.email,
             "name": u.name,
-            "role": u.role or "member",
+            "role": auth.normalize_role(u.role),
             "google_only": not u.password_hash,
             "saved_runs": saved.get(u.id, 0),
             "created_at": u.created_at,
-            "is_admin": auth.is_admin(u.email),
+            "is_admin": auth.is_admin(u.email) or auth.role_is_staff(u.role),
+            "env_admin": auth.is_admin(u.email),
         }
         for u in db.query(User).order_by(User.created_at.desc()).all()
     ]
@@ -93,34 +132,44 @@ def set_role(
     user_id: str,
     body: dict,
     db: Session = Depends(get_db),
-    _admin: dict = Depends(require_admin),
+    admin: dict = Depends(require_admin),
 ):
-    role = str(body.get("role", "")).strip().lower()
-    if role not in ("member", "lab"):
-        raise HTTPException(400, "Role must be 'member' or 'lab'.")
+    raw = str(body.get("role", "")).strip().lower()
+    if raw not in auth.ROLES and raw != "member":  # "member" = legacy external
+        raise HTTPException(400, f"Role must be one of: {', '.join(auth.ROLES)}.")
+    role = auth.normalize_role(raw)
     user = db.get(User, user_id)
     if user is None:
         raise HTTPException(404, "User not found")
+    if user_id == admin["id"]:
+        raise HTTPException(400, "You cannot change your own role (ask another admin).")
+    _require_escalation_rights(admin, user, "change the role of")
+    if role in auth.STAFF_ROLES and not admin["can_escalate"]:
+        raise HTTPException(403, "Only a PI (or allowlisted admin) can grant PI/maintainer roles.")
+    old = auth.normalize_role(user.role)
     user.role = role
+    _audit(db, admin, "set_role", user.email, f"{old} -> {role}")
     db.commit()
     return {"id": user.id, "role": user.role}
 
 
 @router.post("/users/{user_id}/reset-password")
 def reset_password(
-    user_id: str, db: Session = Depends(get_db), _admin: dict = Depends(require_admin)
+    user_id: str, db: Session = Depends(get_db), admin: dict = Depends(require_admin)
 ):
     """Generate a temporary password, shown ONCE in the response. The admin
     passes it to the user, who should change it (or use Google sign-in)."""
     user = db.get(User, user_id)
     if user is None:
         raise HTTPException(404, "User not found")
+    _require_escalation_rights(admin, user, "reset the password of")
     if not user.password_hash:
         raise HTTPException(
             400, "This is a Google account - it has no password to reset (they sign in via Google)."
         )
     temp = secrets.token_urlsafe(9)  # 12 chars, meets the minimum length
     user.password_hash = auth.hash_password(temp)
+    _audit(db, admin, "reset_password", user.email)
     db.commit()
     return {"id": user.id, "email": user.email, "temporary_password": temp}
 
@@ -135,13 +184,117 @@ def delete_user(
     user = db.get(User, user_id)
     if user is None:
         raise HTTPException(404, "User not found")
+    _require_escalation_rights(admin, user, "delete")
     for project in db.query(Project).filter_by(owner_user_id=user_id).all():
         retention.delete_project_cascade(db, project)
+    _audit(db, admin, "delete_user", user.email, f"role was {auth.normalize_role(user.role)}")
     db.delete(user)
     db.commit()
     return None
 
 
+# ---------------------------------------------------------------- invites
+@router.post("/invites", status_code=201)
+def create_invite(
+    body: dict,
+    db: Session = Depends(get_db),
+    admin: dict = Depends(require_admin),
+):
+    """Signed, expiring invite link: whoever registers through it lands at
+    the invited tier (external/lab only - staff is granted, never invited).
+    Stateless, so it cannot be revoked early; creation is audited."""
+    role = str(body.get("role", "")).strip().lower()
+    try:
+        token, expires = auth.create_invite_token(role, admin.get("email", ""))
+    except ValueError as exc:
+        raise HTTPException(400, str(exc)) from exc
+    _audit(db, admin, "invite_created", auth.normalize_role(role), f"expires {expires}")
+    db.commit()
+    return {"token": token, "role": auth.normalize_role(role), "expires_at": expires,
+            "ttl_days": auth.invite_ttl_days()}
+
+
+# ------------------------------------------------------ pre-assigned roles
+@router.get("/role-assignments")
+def list_role_assignments(db: Session = Depends(get_db), _admin: dict = Depends(require_admin)):
+    return [
+        {"id": a.id, "email": a.email, "role": auth.normalize_role(a.role),
+         "assigned_by": a.assigned_by, "created_at": a.created_at,
+         "claimed_at": a.claimed_at or None}
+        for a in db.query(RoleAssignment)
+        .order_by(RoleAssignment.created_at.desc()).limit(100).all()
+    ]
+
+
+@router.post("/role-assignments", status_code=201)
+def create_role_assignment(
+    body: dict,
+    db: Session = Depends(get_db),
+    admin: dict = Depends(require_admin),
+):
+    """Bind a role to an email BEFORE the account exists: whoever first signs
+    in with this email (password or Google) lands at this tier. This is how
+    an external collaborator gets full credentials without touching env vars.
+    Staff assignments require escalation rights, same as the Users table."""
+    email = str(body.get("email", "")).strip().lower()
+    role = auth.normalize_role(str(body.get("role", "")))
+    if not auth.valid_email(email):
+        raise HTTPException(400, "Please enter a valid email address.")
+    if str(body.get("role", "")).strip().lower() not in auth.ROLES:
+        raise HTTPException(400, f"Role must be one of: {', '.join(auth.ROLES)}.")
+    if role in auth.STAFF_ROLES and not admin["can_escalate"]:
+        raise HTTPException(403, "Only a PI (or allowlisted admin) can pre-assign PI/maintainer roles.")
+    if db.query(User).filter_by(email=email).first():
+        raise HTTPException(409, "This email already has an account - change their role in the Users table.")
+    existing = db.query(RoleAssignment).filter_by(email=email).first()
+    if existing is not None:
+        if auth.role_is_staff(existing.role) and not admin["can_escalate"]:
+            raise HTTPException(403, "Only a PI (or allowlisted admin) can change a staff pre-assignment.")
+        existing.role = role
+        existing.assigned_by = admin.get("email", "")
+        existing.claimed_at = ""
+        assignment = existing
+    else:
+        assignment = RoleAssignment(email=email, role=role, assigned_by=admin.get("email", ""))
+        db.add(assignment)
+    _audit(db, admin, "role_preassigned", email, role)
+    db.commit()
+    return {"id": assignment.id, "email": email, "role": role}
+
+
+@router.delete("/role-assignments/{assignment_id}", status_code=204)
+def delete_role_assignment(
+    assignment_id: str,
+    db: Session = Depends(get_db),
+    admin: dict = Depends(require_admin),
+):
+    assignment = db.get(RoleAssignment, assignment_id)
+    if assignment is None:
+        raise HTTPException(404, "Assignment not found")
+    if auth.role_is_staff(assignment.role) and not admin["can_escalate"]:
+        raise HTTPException(403, "Only a PI (or allowlisted admin) can remove a staff pre-assignment.")
+    _audit(db, admin, "preassignment_removed", assignment.email,
+           auth.normalize_role(assignment.role))
+    db.delete(assignment)
+    db.commit()
+    return None
+
+
+# -------------------------------------------------------------- audit log
+@router.get("/audit")
+def audit_log(db: Session = Depends(get_db), admin: dict = Depends(require_admin)):
+    """Top-down oversight is the PI's (and env admin's) view - maintainers
+    work the operational cards but don't review each other's actions."""
+    if not admin["can_escalate"]:
+        raise HTTPException(403, "The audit trail is visible to PIs and allowlisted admins.")
+    rows = db.query(AdminAudit).order_by(AdminAudit.at.desc(), AdminAudit.id.desc()).limit(100).all()
+    return [
+        {"at": r.at, "actor": r.actor_email, "action": r.action,
+         "target": r.target, "detail": r.detail}
+        for r in rows
+    ]
+
+
 # ----------------------------------------------------------- failed runs
 @router.get("/jobs/failed")
 def failed_jobs(db: Session = Depends(get_db), _admin: dict = Depends(require_admin)):
@@ -171,7 +324,7 @@ def failed_jobs(db: Session = Depends(get_db), _admin: dict = Depends(require_ad
 
 @router.post("/jobs/{job_id}/requeue")
 def requeue_job(
-    job_id: str, db: Session = Depends(get_db), _admin: dict = Depends(require_admin)
+    job_id: str, db: Session = Depends(get_db), admin: dict = Depends(require_admin)
 ):
     job = db.get(Job, job_id)
     if job is None:
@@ -188,6 +341,7 @@ def requeue_job(
     job.progress = 0.0
     job.started_at = ""
     job.finished_at = ""
+    _audit(db, admin, "requeue_job", job.id[:8])
     db.commit()
     jobs_module.submit_job(job.id)
     return {"id": job.id, "status": "queued"}
@@ -222,11 +376,21 @@ def set_verification(
     construct_id: str,
     body: dict,
     db: Session = Depends(get_db),
-    _admin: dict = Depends(require_admin),
+    admin: dict = Depends(require_admin),
 ):
     """Operational overlay for the RA's workflow. The YAML library remains the
     durable source of truth: statuses set here are exported and written back to
-    the library files by the developer before production (recorded decision)."""
+    the library files by the developer before production (recorded decision).
+
+    Verification is the MAINTAINER's job (PI decision 2026-07-22): the queue is
+    visible to all staff, but only maintainers mark scales - the trail then
+    shows the responsible RA, not whichever admin clicked. PI/env admins keep
+    read access; to verify, hold the maintainer role."""
+    if admin["role"] != "maintainer":
+        raise HTTPException(
+            403, "Construct verification is done by maintainers. "
+                 "PI/admin accounts have read access to the queue."
+        )
     status = str(body.get("status", "")).strip()
     if status not in ("verified", "needs_verification"):
         raise HTTPException(400, "Status must be 'verified' or 'needs_verification'.")
@@ -234,5 +398,6 @@ def set_verification(
     if construct is None:
         raise HTTPException(404, "Construct not found")
     construct.verification_status = status
+    _audit(db, admin, "set_verification", construct.name, status)
     db.commit()
     return {"id": construct.id, "verification_status": construct.verification_status}

backend/app/auth.py

@@ -77,8 +77,9 @@ def cookies_secure() -> bool:
 
 
 def admin_emails() -> set[str]:
-    """Comma-separated allowlist; admin is an env-granted capability, not a DB
-    role, so a compromised database cannot mint admins."""
+    """Comma-separated allowlist; env-granted, so it bootstraps the first
+    admin and can never be locked out by DB state. See roles below for the
+    DB-granted staff tiers (PI decision 2026-07-22)."""
     raw = os.environ.get("ADMIN_EMAILS", "")
     return {e.strip().lower() for e in raw.split(",") if e.strip()}
 
@@ -87,6 +88,42 @@ def is_admin(email: str | None) -> bool:
     return bool(email) and email.strip().lower() in admin_emails()
 
 
+# ------------------------------------------------------------- user roles
+# Four tiers (PI decision 2026-07-22): pi | maintainer | lab | external.
+#   * external   - default on signup; saved-run cap applies.
+#   * lab        - lab members: unlimited saved runs.
+#   * maintainer - lab privileges + the /admin operational surface
+#                  (user management for lab/external, resets, requeue,
+#                  verification queue, invites).
+#   * pi         - maintainer surface + escalation rights: grant/revoke
+#                  staff roles and act on staff accounts. The app is
+#                  self-governing; ADMIN_EMAILS is bootstrap + break-glass
+#                  only (seed the first PI, recover a locked-out lab).
+# Escalation therefore requires pi-or-env-admin (admin.py guards), so a
+# maintainer - or a compromised maintainer session - cannot mint staff.
+ROLES = ("external", "lab", "maintainer", "pi")
+UNLIMITED_ROLES = frozenset({"lab", "maintainer", "pi"})
+STAFF_ROLES = frozenset({"maintainer", "pi"})
+INVITABLE_ROLES = frozenset({"external", "lab"})  # staff is granted, never invited
+
+
+def normalize_role(role: str | None) -> str:
+    """Map stored roles to the current scheme ('member' predates 'external')."""
+    role = (role or "").strip().lower()
+    if role == "member":
+        return "external"
+    return role if role in ROLES else "external"
+
+
+def role_unlimited(role: str | None) -> bool:
+    """Lab members and above: no saved-run cap."""
+    return normalize_role(role) in UNLIMITED_ROLES
+
+
+def role_is_staff(role: str | None) -> bool:
+    return normalize_role(role) in STAFF_ROLES
+
+
 # ---------------------------------------------------------- passwords
 def hash_password(password: str) -> str:
     salt = secrets.token_bytes(16)
@@ -150,10 +187,46 @@ def get_current_user(request: Request) -> dict | None:
         "id": data["uid"],
         "email": data.get("email", ""),
         "name": data.get("name", ""),
-        "tier": "member",
+        # placeholder only - real role lives in the users table (queried per
+        # request in main.py/admin.py so role changes apply without re-login)
+        "tier": "external",
     }
 
 
+# ------------------------------------------------------------ invite links
+# Signed, expiring tokens the PI copies into Slack; whoever registers through
+# one lands at the invited tier instead of external. Stateless (no DB row):
+# the cost is that an invite cannot be revoked before it expires - acceptable
+# for a 7-day lab onboarding link, and every creation/redemption is audited.
+INVITE_TTL_DAYS_DEFAULT = 7
+
+
+def invite_ttl_days() -> int:
+    return int(os.environ.get("CCR_INVITE_TTL_DAYS", INVITE_TTL_DAYS_DEFAULT))
+
+
+def create_invite_token(role: str, invited_by: str) -> tuple[str, str]:
+    """Returns (token, expires_at ISO date). Role must be invitable."""
+    from datetime import timedelta
+
+    role = normalize_role(role)
+    if role not in INVITABLE_ROLES:
+        raise ValueError(f"Only these roles can be invited: {', '.join(sorted(INVITABLE_ROLES))}.")
+    expires = (datetime.now(timezone.utc) + timedelta(days=invite_ttl_days())).date().isoformat()
+    return sign_payload({"invite": role, "by": invited_by, "exp": expires}), expires
+
+
+def verify_invite_token(token: str | None) -> str | None:
+    """Role granted by a valid, unexpired invite token; None otherwise."""
+    data = verify_payload(token)
+    if not data or "invite" not in data:
+        return None
+    if str(data.get("exp", "")) < datetime.now(timezone.utc).date().isoformat():
+        return None  # expired (dates are ISO, so string compare is correct)
+    role = normalize_role(str(data["invite"]))
+    return role if role in INVITABLE_ROLES else None
+
+
 # ------------------------------------------- anonymous daily run counter
 def _today() -> str:
     return datetime.now(timezone.utc).date().isoformat()

backend/app/guide.html

@@ -120,13 +120,15 @@ systematically stress-testing the platform, but <b>your real data is the best te
 have</b>.</p>
 
 <h2 id="limits">Limits at a glance</h2>
-<p>Signing in lifts the anonymous caps; a lab account (admin-granted) removes the
-saved-run cap. The row limit is usually what you hit first, not the file size.</p>
+<p>Accounts come in four tiers, set by the admins: <b>external user</b> (the default on
+sign-up), <b>lab member</b>, <b>maintainer</b>, and <b>PI</b>. Signing in lifts the
+anonymous caps; lab members and above have no saved-run cap. The row limit is usually
+what you hit first, not the file size.</p>
 <div class="tablewrap">
 <table>
-  <tr><th>Limit</th><th>Signed out</th><th>Signed in</th><th>Lab account</th></tr>
+  <tr><th>Limit</th><th>Signed out</th><th>External user</th><th>Lab member +</th></tr>
   <tr><td>Upload size</td><td>5&nbsp;MB</td><td>50&nbsp;MB</td><td>50&nbsp;MB</td></tr>
-  <tr><td>Rows per file</td><td>200</td><td>20,000</td><td>20,000</td></tr>
+  <tr><td>Rows per file</td><td>200</td><td>50,000</td><td>50,000</td></tr>
   <tr><td>Runs per day</td><td>3, then sign in</td><td>unlimited</td><td>unlimited</td></tr>
   <tr><td>Saved runs kept</td><td>none (file deleted after each run)</td><td>15</td><td>unlimited</td></tr>
 </table>
@@ -291,9 +293,9 @@ pages don't update.</p>
 <ol>
   <li>Sign in, upload, run: no ANONYMOUS_DATA_REMOVED warning; re-running the same corpus
       works (file kept).</li>
-  <li>Saved-run budget: the Step 3 card shows "N of M saved runs used". Lab accounts on
-      this dev instance are set effectively unlimited; public accounts get 15. At the cap,
-      new runs are refused until you delete old runs/projects (nothing is auto-deleted).</li>
+  <li>Saved-run budget: the Step 3 card shows "N of M saved runs used". Lab members and
+      above have no cap; external accounts get 15. At the cap, new runs are refused until
+      you delete old runs/projects (nothing is auto-deleted).</li>
   <li>Ownership: your projects are invisible to signed-out visitors and other accounts.
       Anonymous projects stay shared.</li>
 </ol>
@@ -308,126 +310,13 @@ pages don't update.</p>
       dupes): identical scores for identical texts, less compute.</li>
 </ol>
 
-<h2 id="architecture">11. How it works (architecture &amp; data flow)</h2>
-<p>For anyone who wants to look under the hood. The whole system is deliberately
-simple: one application, a few managed services around it, and no third-party AI
-APIs — the embedding models run on our own server, so uploaded text never leaves
-the platform.</p>
+<h2 id="architecture">10. Under the hood</h2>
+<p>Architecture, data flow, data retention, and the full access/roles model
+(tiers, invite links, pre-assigned roles, audit trail) live on their own page:
+<a href="/product"><b>Product &amp; Architecture →</b></a>. This guide stays
+focused on using and testing the platform.</p>
 
-<h3>What runs where</h3>
-<figure>
-<svg viewBox="0 0 760 300" xmlns="http://www.w3.org/2000/svg" role="img"
-     aria-label="Architecture: browser talks to one app container, which uses Postgres, R2, and Supabase/Google auth.">
-  <defs>
-    <marker id="arw" markerWidth="9" markerHeight="9" refX="7" refY="3" orient="auto">
-      <path d="M0,0 L7,3 L0,6 Z" fill="var(--muted)"/>
-    </marker>
-  </defs>
-  <!-- browser -->
-  <rect class="box" x="20" y="120" width="150" height="60" rx="8"/>
-  <text class="lbl" x="95" y="147" text-anchor="middle">Your browser</text>
-  <text class="lbl-sm" x="95" y="165" text-anchor="middle">the web interface</text>
-  <!-- app container -->
-  <rect class="box-accent" x="270" y="90" width="220" height="120" rx="10"/>
-  <text class="lbl" x="380" y="115" text-anchor="middle">One app container</text>
-  <text class="lbl-sm" x="380" y="135" text-anchor="middle">API + interface (FastAPI/React)</text>
-  <text class="lbl-sm" x="380" y="152" text-anchor="middle">embedding models run here</text>
-  <text class="lbl-sm" x="380" y="169" text-anchor="middle">(MiniLM, E5) — no external AI</text>
-  <text class="lbl-sm" x="380" y="190" text-anchor="middle">hosted on Hugging Face</text>
-  <!-- stores -->
-  <rect class="box" x="590" y="30" width="150" height="52" rx="8"/>
-  <text class="lbl" x="665" y="52" text-anchor="middle">Postgres</text>
-  <text class="lbl-sm" x="665" y="69" text-anchor="middle">records (Supabase)</text>
-  <rect class="box" x="590" y="124" width="150" height="52" rx="8"/>
-  <text class="lbl" x="665" y="146" text-anchor="middle">Object storage</text>
-  <text class="lbl-sm" x="665" y="163" text-anchor="middle">files (Cloudflare R2)</text>
-  <rect class="box" x="590" y="218" width="150" height="52" rx="8"/>
-  <text class="lbl" x="665" y="240" text-anchor="middle">Sign-in</text>
-  <text class="lbl-sm" x="665" y="257" text-anchor="middle">Google / Supabase</text>
-  <!-- arrows -->
-  <path class="flow" d="M170,150 L268,150"/>
-  <path class="flow" d="M492,140 L588,58"/>
-  <path class="flow" d="M492,150 L588,150"/>
-  <path class="flow" d="M492,162 L588,244"/>
-</svg>
-<figcaption>The interface, the API, and the embedding models all live in one
-container. Around it: a persistent database for records, object storage for
-uploaded files, and Google/Supabase for sign-in. Every piece is on a free tier.</figcaption>
-</figure>
-
-<h3>What happens during a run</h3>
-<figure>
-<svg viewBox="0 0 760 190" xmlns="http://www.w3.org/2000/svg" role="img"
-     aria-label="Data flow: upload, quality checks, embed items and texts, cosine similarity, scores, results and exports.">
-  <defs>
-    <marker id="arw2" markerWidth="9" markerHeight="9" refX="7" refY="3" orient="auto">
-      <path d="M0,0 L7,3 L0,6 Z" fill="var(--muted)"/>
-    </marker>
-  </defs>
-  <g>
-    <rect class="box" x="15" y="30" width="120" height="54" rx="8"/>
-    <text class="lbl-sm" x="75" y="52" text-anchor="middle">1. Upload</text>
-    <text class="lbl-sm" x="75" y="68" text-anchor="middle">corpus + construct</text>
-
-    <rect class="box" x="165" y="30" width="120" height="54" rx="8"/>
-    <text class="lbl-sm" x="225" y="52" text-anchor="middle">2. Quality checks</text>
-    <text class="lbl-sm" x="225" y="68" text-anchor="middle">language, warnings</text>
-
-    <rect class="box-accent" x="315" y="30" width="130" height="54" rx="8"/>
-    <text class="lbl-sm" x="380" y="52" text-anchor="middle">3. Embed both</text>
-    <text class="lbl-sm" x="380" y="68" text-anchor="middle">items &amp; texts, one model</text>
-
-    <rect class="box-accent" x="475" y="30" width="130" height="54" rx="8"/>
-    <text class="lbl-sm" x="540" y="52" text-anchor="middle">4. Cosine similarity</text>
-    <text class="lbl-sm" x="540" y="68" text-anchor="middle">text × each item</text>
-
-    <rect class="box" x="635" y="30" width="110" height="54" rx="8"/>
-    <text class="lbl-sm" x="690" y="52" text-anchor="middle">5. CCR score</text>
-    <text class="lbl-sm" x="690" y="68" text-anchor="middle">mean of items</text>
-
-    <rect class="box" x="240" y="120" width="280" height="50" rx="8"/>
-    <text class="lbl-sm" x="380" y="141" text-anchor="middle">6. Results: distributions, per-item loadings,</text>
-    <text class="lbl-sm" x="380" y="157" text-anchor="middle">top/bottom texts + CSV, metadata, repro script</text>
-  </g>
-  <path class="flow" style="marker-end:url(#arw2)" d="M135,57 L163,57"/>
-  <path class="flow" style="marker-end:url(#arw2)" d="M285,57 L313,57"/>
-  <path class="flow" style="marker-end:url(#arw2)" d="M445,57 L473,57"/>
-  <path class="flow" style="marker-end:url(#arw2)" d="M605,57 L633,57"/>
-  <path class="flow" style="marker-end:url(#arw2)" d="M690,84 L690,120 L522,145"/>
-</svg>
-<figcaption>CCR in one line: embed the validated scale items and your texts with
-the <em>same</em> model, then each text's cosine similarity to the items is its
-loading; the mean across items is the CCR score. It is deterministic embeddings
-plus arithmetic — no LLM, no prompting, no randomness.</figcaption>
-</figure>
-
-<h3>Where your data lives (and for how long)</h3>
-<ul>
-  <li><b>Records</b> (account, projects, run results and summaries) → the Postgres
-      database. Persistent, backed up.</li>
-  <li><b>Uploaded files</b> → object storage. Signed-in users' files persist;
-      anonymous uploads are deleted the moment their analysis finishes.</li>
-  <li><b>Anonymous sessions</b> are wiped entirely after 24&nbsp;hours; nothing you
-      upload anonymously is kept.</li>
-  <li><b>Reproducibility</b>: every run also records the exact model version, an
-      item-wording hash, and package versions, so the downloadable script
-      reproduces the numbers on any machine.</li>
-</ul>
-
-<h3>A few engineering choices worth knowing</h3>
-<ul>
-  <li><b>Same model for items and texts</b>, always — mixing models makes scores
-      non-comparable, so the platform records the model on every run and warns you.</li>
-  <li><b>MiniLM is the default</b> because it is the reference model in the published
-      CCR work; the stronger E5 models are available and clearly labelled.</li>
-  <li><b>Re-running a new construct on the same corpus is near-instant</b> — the
-      text embeddings are cached and reused (identical every time), so only the
-      cheap similarity step repeats.</li>
-  <li><b>Warnings never silently "fix" your data</b> — the platform surfaces issues
-      (wrong language, truncation, duplicates) and lets you decide.</li>
-</ul>
-
-<h2 id="feedback">12. Found something off?</h2>
+<h2 id="feedback">11. Found something off?</h2>
 <p>Anything that doesn't match what this guide says it should do - or anything confusing,
 slow, or missing - post it in the lab's <b>#ccr Slack channel</b>: the 🐞 thread for bugs,
 the 💡 thread for ideas and feature requests. One line is enough; note the section number

backend/app/main.py

@@ -13,6 +13,7 @@ import json
 import os
 import uuid
 from contextlib import asynccontextmanager
+from datetime import datetime, timezone
 from pathlib import Path
 
 from fastapi import Depends, FastAPI, HTTPException, Request, Response, UploadFile
@@ -31,7 +32,7 @@ from .construct_files import parse_construct_file
 from .construct_lib import sync_library
 from .db import DATA_DIR, Base, SessionLocal, auto_migrate_sqlite, engine, get_db
 from .ingest import IngestError, load_corpus, max_rows as corpus_max_rows, suggest_text_column
-from .models import Construct, Corpus, Job, Project, User
+from .models import AdminAudit, Construct, Corpus, Job, Project, RoleAssignment, User
 from .reproducibility import (
     requirements_filename,
     requirements_text,
@@ -255,13 +256,15 @@ def auth_me(
 ):
     if user:
         row = db.get(User, user["id"])
-        role = (row.role if row else None) or "member"
+        role = auth.normalize_role(row.role if row else None)
         return {
             "signed_in": True,
             "name": user["name"],
             "email": user["email"],
             "role": role,
-            "is_admin": auth.is_admin(user["email"]),
+            # effective admin: env allowlist OR staff role (pi/maintainer) -
+            # drives the Admin link in the header
+            "is_admin": auth.is_admin(user["email"]) or auth.role_is_staff(role),
             # max_rows is NOT unlimited for signed-in users: CCR_MAX_ROWS is a
             # global ingest ceiling and is usually the limit that actually
             # binds (deployed instances set it well below the byte ceiling).
@@ -270,8 +273,8 @@ def auth_me(
             "limits": {"max_bytes": max_upload_bytes(), "max_rows": corpus_max_rows()},
             "usage": {
                 "saved_runs": _saved_runs_used(db, user["id"]),
-                # lab accounts: unlimited saved runs (admin-granted role)
-                "max_saved_runs": None if role == "lab" else auth.user_max_saved_runs(),
+                # lab members and above: unlimited saved runs (admin-granted)
+                "max_saved_runs": None if auth.role_unlimited(role) else auth.user_max_saved_runs(),
             },
         }
     return {
@@ -287,6 +290,26 @@ def auth_me(
     }
 
 
+def _initial_role(db: Session, email: str, invite_token: str | None = None) -> str:
+    """Tier a brand-new account lands at. Precedence: an email-bound
+    pre-assignment (may carry staff roles - the 'credentials before first
+    sign-in' case) beats an invite link (bearer token, external/lab only)
+    beats the external default. Claiming is recorded in the audit trail."""
+    pre = db.query(RoleAssignment).filter_by(email=email).first()
+    if pre is not None and not pre.claimed_at:
+        pre.claimed_at = datetime.now(timezone.utc).isoformat(timespec="seconds")
+        role = auth.normalize_role(pre.role)
+        db.add(AdminAudit(actor_email=email, action="role_claimed", target=email,
+                          detail=f"pre-assigned {role} by {pre.assigned_by}"))
+        return role
+    invited = auth.verify_invite_token(invite_token)
+    if invited:
+        db.add(AdminAudit(actor_email=email, action="invite_redeemed",
+                          target=email, detail=invited))
+        return invited
+    return "external"
+
+
 @app.post("/api/auth/register", status_code=201)
 def register(body: RegisterIn, response: Response, db: Session = Depends(get_db)):
     email = body.email.strip().lower()
@@ -296,7 +319,16 @@ def register(body: RegisterIn, response: Response, db: Session = Depends(get_db)
         raise HTTPException(400, f"Password must be at least {auth.MIN_PASSWORD_LEN} characters.")
     if db.query(User).filter_by(email=email).first():
         raise HTTPException(409, "An account with this email already exists. Sign in instead.")
-    user = User(email=email, name=body.name.strip(), password_hash=auth.hash_password(body.password))
+    # A dead invite link should say so, not silently demote to external -
+    # unless a pre-assignment covers the email anyway.
+    has_preassignment = db.query(RoleAssignment).filter_by(email=email).first() is not None
+    if body.invite_token and not auth.verify_invite_token(body.invite_token) and not has_preassignment:
+        raise HTTPException(400, "This invite link is invalid or has expired. Ask for a new one.")
+    user = User(
+        email=email, name=body.name.strip(),
+        password_hash=auth.hash_password(body.password),
+        role=_initial_role(db, email, body.invite_token),
+    )
     db.add(user)
     db.commit()
     _set_session_cookie(response, user)
@@ -356,8 +388,10 @@ def google_callback(request: Request, code: str = "", db: Session = Depends(get_
     user = db.query(User).filter_by(email=info["email"]).first()
     if user is None:
         # Google-verified account: no local password (password login is refused
-        # with a pointer to the Google button).
-        user = User(email=info["email"], name=info["name"], password_hash="")
+        # with a pointer to the Google button). Pre-assigned roles apply here
+        # too - the "credentials before first sign-in" path works either way.
+        user = User(email=info["email"], name=info["name"], password_hash="",
+                    role=_initial_role(db, info["email"].strip().lower()))
         db.add(user)
         db.commit()
 
@@ -677,9 +711,9 @@ def create_job(
             )
     else:
         # Signed-in tier: saved-run cap instead of deletion (their data, their
-        # call). Lab-role accounts (admin-granted) are uncapped.
+        # call). Lab members and above (admin-granted roles) are uncapped.
         row = db.get(User, user["id"])
-        if (row.role if row else "member") != "lab" and (
+        if not auth.role_unlimited(row.role if row else None) and (
             _saved_runs_used(db, user["id"]) >= auth.user_max_saved_runs()
         ):
             raise HTTPException(
@@ -840,6 +874,20 @@ def testing_guide():
     return FileResponse(GUIDE_HTML, media_type="text/html")
 
 
+# /product: the under-the-hood companion to /guide - access model (tiers,
+# invites, pre-assignments, audit), architecture, data flow, retention.
+# The guide stays a how-to-use-and-test document; this page holds the
+# product/architecture detail (split requested 2026-07-22).
+PRODUCT_HTML = Path(__file__).resolve().parent / "product.html"
+
+
+@app.get("/product", include_in_schema=False)
+def product_page():
+    if not PRODUCT_HTML.exists():
+        raise HTTPException(404, "Product page not available on this instance.")
+    return FileResponse(PRODUCT_HTML, media_type="text/html")
+
+
 @app.get("/admin", include_in_schema=False)
 def admin_page():
     """Serve the SPA at /admin; the frontend renders the admin view there

backend/app/models.py

@@ -29,12 +29,51 @@ class User(Base):
     email: Mapped[str] = mapped_column(String(255), unique=True, index=True)
     name: Mapped[str] = mapped_column(String(120), default="")
     password_hash: Mapped[str] = mapped_column(Text)  # scrypt$salt$digest (auth.py)
-    role: Mapped[str] = mapped_column(String(16), default="member")  # member | lab
-    # "lab" = unlimited saved runs (set via /admin). Admins are NOT a DB role:
-    # admin access is granted by the ADMIN_EMAILS env allowlist (auth.is_admin).
+    role: Mapped[str] = mapped_column(String(16), default="external")
+    # external | lab | maintainer | pi (auth.ROLES; legacy "member" reads as
+    # external). lab+ = unlimited saved runs; maintainer/pi also get /admin.
+    # Staff roles are grantable only by ADMIN_EMAILS env-allowlisted admins
+    # (admin.py guards), so the API cannot self-escalate; the env allowlist
+    # remains the bootstrap and break-glass admin path.
     created_at: Mapped[str] = mapped_column(String(32), default=_now)
 
 
+class RoleAssignment(Base):
+    """Pre-provisioned access: a role bound to an email BEFORE the account
+    exists (PI request 2026-07-22 - e.g. an external collaborator who must
+    land with full credentials on first sign-in, Google or password).
+
+    Unlike invite links (bearer tokens, external/lab only), assignments are
+    email-bound and may carry staff roles - so creating one for pi/maintainer
+    requires escalation rights. Claimed rows are kept as history."""
+
+    __tablename__ = "role_assignments"
+
+    id: Mapped[str] = mapped_column(String(32), primary_key=True, default=_uuid)
+    email: Mapped[str] = mapped_column(String(255), unique=True, index=True)
+    role: Mapped[str] = mapped_column(String(16))
+    assigned_by: Mapped[str] = mapped_column(String(255), default="")
+    created_at: Mapped[str] = mapped_column(String(32), default=_now)
+    claimed_at: Mapped[str] = mapped_column(String(32), default="")  # "" = pending
+
+
+class AdminAudit(Base):
+    """Append-only trail of admin actions (who did what to whom, when).
+
+    What makes multiple admins trustworthy: role grants, password resets,
+    deletions, invites, requeues, and verification changes all land here.
+    Never updated or deleted from the app."""
+
+    __tablename__ = "admin_audit"
+
+    id: Mapped[str] = mapped_column(String(32), primary_key=True, default=_uuid)
+    at: Mapped[str] = mapped_column(String(32), default=_now)
+    actor_email: Mapped[str] = mapped_column(String(255))
+    action: Mapped[str] = mapped_column(String(40))  # e.g. set_role, invite_created
+    target: Mapped[str] = mapped_column(String(300), default="")  # email/name acted on
+    detail: Mapped[str] = mapped_column(Text, default="")
+
+
 class Project(Base):
     __tablename__ = "projects"
 

backend/app/product.html

@@ -0,0 +1,355 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>CCR Platform - Product &amp; Architecture</title>
+<style>
+  :root {
+    --bg: #ffffff; --fg: #1a1a1a; --muted: #666; --border: #ddd;
+    --accent: #2456a6; --card: #f7f7f8; --amber-bg: #fff7e0; --amber-border: #e0b84d;
+    --code-bg: #f0f0f2;
+  }
+  @media (prefers-color-scheme: dark) {
+    :root {
+      --bg: #16181c; --fg: #e6e6e6; --muted: #9a9a9a; --border: #3a3d44;
+      --accent: #7aa7e8; --card: #1f2228; --amber-bg: #2e2810; --amber-border: #8a6d1f;
+      --code-bg: #24272e;
+    }
+  }
+  * { box-sizing: border-box; }
+  body {
+    margin: 0; background: var(--bg); color: var(--fg);
+    font: 16px/1.6 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+  }
+  main { max-width: 860px; margin: 0 auto; padding: 2rem 1.25rem 4rem; }
+  h1 { font-size: 1.7rem; margin: 0 0 .25rem; }
+  h2 { font-size: 1.25rem; margin: 2.2rem 0 .6rem; padding-top: .6rem; border-top: 1px solid var(--border); }
+  h3 { font-size: 1.02rem; margin: 1.2rem 0 .4rem; }
+  p, li { color: var(--fg); }
+  .sub { color: var(--muted); margin: 0 0 1.2rem; }
+  a { color: var(--accent); }
+  code { background: var(--code-bg); padding: .1em .35em; border-radius: 4px; font-size: .9em; }
+  .note {
+    background: var(--amber-bg); border: 1px solid var(--amber-border);
+    border-radius: 8px; padding: .8rem 1rem; margin: 1rem 0;
+  }
+  .note b { display: block; margin-bottom: .25rem; }
+  .tablewrap { overflow-x: auto; }
+  table { border-collapse: collapse; width: 100%; margin: .8rem 0; font-size: .93rem; }
+  th, td { border: 1px solid var(--border); padding: .45rem .6rem; text-align: left; vertical-align: top; }
+  th { background: var(--card); }
+  ol li, ul li { margin: .3rem 0; }
+  .top { position: fixed; right: 1rem; bottom: 1rem; background: var(--card);
+    border: 1px solid var(--border); border-radius: 8px; padding: .4rem .7rem;
+    text-decoration: none; font-size: .85rem; }
+  figure { margin: 1rem 0 1.4rem; }
+  figure svg { width: 100%; height: auto; border: 1px solid var(--border);
+    border-radius: 8px; background: var(--card); }
+  figcaption { color: var(--muted); font-size: .85rem; margin-top: .4rem; }
+  .box { fill: var(--bg); stroke: var(--border); stroke-width: 1.5; }
+  .box-accent { fill: none; stroke: var(--accent); stroke-width: 2; }
+  .lbl { fill: var(--fg); font: 600 13px sans-serif; }
+  .lbl-sm { fill: var(--muted); font: 11px sans-serif; }
+  .flow { stroke: var(--muted); stroke-width: 1.5; fill: none; marker-end: url(#arw); }
+  h2[id], h3[id] { scroll-margin-top: 1rem; }
+  .anchor {
+    opacity: 0; text-decoration: none; color: var(--muted); font-weight: 400;
+    margin-left: .4rem; cursor: pointer; transition: opacity .12s;
+  }
+  h2:hover .anchor, h3:hover .anchor, .anchor:focus { opacity: .7; }
+  .anchor:hover { opacity: 1; color: var(--accent); }
+  :target { animation: flash 1.4s ease-out; }
+  @keyframes flash {
+    from { background: var(--amber-bg); }
+    to   { background: transparent; }
+  }
+  .toast {
+    position: fixed; left: 50%; bottom: 1.5rem; transform: translateX(-50%);
+    background: var(--accent); color: #fff; padding: .5rem .9rem; border-radius: 8px;
+    font-size: .85rem; opacity: 0; pointer-events: none; transition: opacity .2s;
+  }
+  .toast.show { opacity: 1; }
+  .yes { color: var(--accent); font-weight: 600; }
+  .no { color: var(--muted); }
+  @media (prefers-reduced-motion: reduce) {
+    :target { animation: none; }
+    .anchor { transition: none; }
+  }
+</style>
+</head>
+<body>
+<main>
+
+<h1>CCR Platform - Product &amp; Architecture</h1>
+<p class="sub">The under-the-hood companion to the <a href="/guide">testing guide</a>:
+who can do what, how access is governed, what runs where, and the engineering
+decisions behind it. The guide tells you how to <em>use</em> the platform; this
+page tells you how it <em>works</em>.</p>
+
+<h2 id="access">1. Access model: four tiers + break-glass</h2>
+<p>Every account has one of four roles. New sign-ups land as <b>external user</b>
+unless an invite link or a pre-assigned role says otherwise (see
+<a href="#prelogin">§2</a>). Roles are managed entirely in the app, on the
+<code>/admin</code> page - no server configuration involved.</p>
+
+<figure>
+<svg viewBox="0 0 760 330" xmlns="http://www.w3.org/2000/svg" role="img"
+     aria-label="Access model: env allowlist and PI hold escalation rights over maintainer, who manages lab members and external users. Every action is audited.">
+  <defs>
+    <marker id="arw" markerWidth="9" markerHeight="9" refX="7" refY="3" orient="auto">
+      <path d="M0,0 L7,3 L0,6 Z" fill="var(--muted)"/>
+    </marker>
+  </defs>
+  <!-- top row: escalation holders -->
+  <rect class="box" x="40" y="20" width="230" height="64" rx="8" stroke-dasharray="5,4"/>
+  <text class="lbl" x="155" y="44" text-anchor="middle">ADMIN_EMAILS (env)</text>
+  <text class="lbl-sm" x="155" y="62" text-anchor="middle">bootstrap + break-glass only</text>
+  <rect class="box-accent" x="330" y="20" width="180" height="64" rx="8"/>
+  <text class="lbl" x="420" y="44" text-anchor="middle">PI</text>
+  <text class="lbl-sm" x="420" y="62" text-anchor="middle">runs the team from /admin</text>
+  <rect class="box" x="560" y="20" width="170" height="64" rx="8"/>
+  <text class="lbl" x="645" y="44" text-anchor="middle">Audit trail</text>
+  <text class="lbl-sm" x="645" y="62" text-anchor="middle">every action recorded</text>
+  <!-- escalation arrows -->
+  <path class="flow" d="M155,84 L155,120 L330,150"/>
+  <path class="flow" d="M420,84 L420,148"/>
+  <text class="lbl-sm" x="440" y="115">grant / revoke any role,</text>
+  <text class="lbl-sm" x="440" y="130">act on staff accounts</text>
+  <!-- maintainer -->
+  <rect class="box-accent" x="330" y="150" width="180" height="64" rx="8"/>
+  <text class="lbl" x="420" y="174" text-anchor="middle">Maintainer</text>
+  <text class="lbl-sm" x="420" y="192" text-anchor="middle">operations + construct verification</text>
+  <!-- maintainer arrows -->
+  <path class="flow" d="M420,214 L420,248"/>
+  <text class="lbl-sm" x="440" y="238">manage lab / external, invites,</text>
+  <text class="lbl-sm" x="440" y="253">resets, requeues</text>
+  <!-- bottom row -->
+  <rect class="box" x="180" y="250" width="180" height="60" rx="8"/>
+  <text class="lbl" x="270" y="274" text-anchor="middle">Lab member</text>
+  <text class="lbl-sm" x="270" y="292" text-anchor="middle">unlimited saved runs</text>
+  <rect class="box" x="400" y="250" width="180" height="60" rx="8"/>
+  <text class="lbl" x="490" y="274" text-anchor="middle">External user</text>
+  <text class="lbl-sm" x="490" y="292" text-anchor="middle">saved-run cap (15)</text>
+</svg>
+<figcaption>Escalation flows top-down only: PIs (and the env allowlist, as recovery)
+manage staff; maintainers manage members; nobody can raise their own role. The
+audit trail sees everything.</figcaption>
+</figure>
+
+<h3 id="matrix">Capability matrix</h3>
+<div class="tablewrap">
+<table>
+  <tr><th>Capability</th><th>Signed out</th><th>External user</th><th>Lab member</th><th>Maintainer</th><th>PI</th></tr>
+  <tr><td>Run analyses</td><td>3/day, data deleted after</td><td class="yes">✓</td><td class="yes">✓</td><td class="yes">✓</td><td class="yes">✓</td></tr>
+  <tr><td>Saved runs</td><td class="no">none kept</td><td>15</td><td class="yes">unlimited</td><td class="yes">unlimited</td><td class="yes">unlimited</td></tr>
+  <tr><td>/admin: manage lab &amp; external users, password resets, requeue failed runs, invites, pre-assignments</td><td class="no">-</td><td class="no">-</td><td class="no">-</td><td class="yes">✓</td><td class="yes">✓</td></tr>
+  <tr><td>Construct verification (mark scales verified)</td><td class="no">-</td><td class="no">-</td><td class="no">-</td><td class="yes">✓ their job</td><td class="no">queue visible, read-only</td></tr>
+  <tr><td>Grant/revoke PI &amp; maintainer; act on staff accounts</td><td class="no">-</td><td class="no">-</td><td class="no">-</td><td class="no">-</td><td class="yes">✓</td></tr>
+  <tr><td>Audit trail (who did what, when)</td><td class="no">-</td><td class="no">-</td><td class="no">-</td><td class="no">-</td><td class="yes">✓</td></tr>
+</table>
+</div>
+<p>Two deliberate asymmetries: <b>verification belongs to maintainers</b> - the
+trail then names the responsible RA, not whichever admin clicked - while
+<b>oversight belongs to the PI</b>, who sees everything (including the audit
+trail) but delegates the hands-on QA. And <b>nobody can change their own
+role</b>, so no session can quietly climb the ladder.</p>
+
+<div class="note">
+  <b>Break-glass: the ADMIN_EMAILS environment variable</b>
+  A short server-side allowlist holds the same powers as the PI role. It exists
+  for exactly two reasons: seeding the very first PI (someone has to grant the
+  first role) and recovering a locked-out lab. Day-to-day it should be one
+  entry - the developer - and everything else lives in the app.
+</div>
+
+<h2 id="prelogin">2. Access before first sign-in</h2>
+<p>Three ways someone has the right access <em>before</em> they ever log in,
+in increasing order of privilege:</p>
+<ol>
+  <li><b>Anonymous use</b> - no account at all: 3 runs/day, small files, uploads
+      deleted right after analysis. The zero-commitment trial tier.</li>
+  <li><b>Invite links</b> - a signed URL an admin copies from /admin into Slack
+      or an email. Whoever registers through it lands as a <b>lab member</b> (or
+      external user). Bearer-style: anyone with the link can use it, so it only
+      carries non-staff roles and expires after 7 days. It cannot be revoked
+      early (it is stateless by design); creation and every redemption are audited.</li>
+  <li><b>Pre-assigned roles</b> - a role bound to a <em>specific email</em>
+      before the account exists. When that person first signs in - password or
+      Google - they land at the assigned tier, staff roles included. This is how
+      an external collaborator gets full credentials on day one: pre-assign
+      <code>maintainer</code> to their email, send them the URL, done. Staff
+      pre-assignments require PI (or break-glass) rights, are listed as pending
+      until claimed, and can be removed any time before the claim.</li>
+</ol>
+
+<h2 id="architecture">3. How it works (architecture &amp; data flow)</h2>
+<p>The whole system is deliberately simple: one application, a few managed
+services around it, and no third-party AI APIs — the embedding models run on
+our own server, so uploaded text never leaves the platform.</p>
+
+<h3>What runs where</h3>
+<figure>
+<svg viewBox="0 0 760 300" xmlns="http://www.w3.org/2000/svg" role="img"
+     aria-label="Architecture: browser talks to one app container, which uses Postgres, R2, and Supabase/Google auth.">
+  <defs>
+    <marker id="arw3" markerWidth="9" markerHeight="9" refX="7" refY="3" orient="auto">
+      <path d="M0,0 L7,3 L0,6 Z" fill="var(--muted)"/>
+    </marker>
+  </defs>
+  <!-- browser -->
+  <rect class="box" x="20" y="120" width="150" height="60" rx="8"/>
+  <text class="lbl" x="95" y="147" text-anchor="middle">Your browser</text>
+  <text class="lbl-sm" x="95" y="165" text-anchor="middle">the web interface</text>
+  <!-- app container -->
+  <rect class="box-accent" x="270" y="90" width="220" height="120" rx="10"/>
+  <text class="lbl" x="380" y="115" text-anchor="middle">One app container</text>
+  <text class="lbl-sm" x="380" y="135" text-anchor="middle">API + interface (FastAPI/React)</text>
+  <text class="lbl-sm" x="380" y="152" text-anchor="middle">embedding models run here</text>
+  <text class="lbl-sm" x="380" y="169" text-anchor="middle">(MiniLM, E5) — no external AI</text>
+  <text class="lbl-sm" x="380" y="190" text-anchor="middle">hosted on Hugging Face</text>
+  <!-- stores -->
+  <rect class="box" x="590" y="30" width="150" height="52" rx="8"/>
+  <text class="lbl" x="665" y="52" text-anchor="middle">Postgres</text>
+  <text class="lbl-sm" x="665" y="69" text-anchor="middle">records (Supabase)</text>
+  <rect class="box" x="590" y="124" width="150" height="52" rx="8"/>
+  <text class="lbl" x="665" y="146" text-anchor="middle">Object storage</text>
+  <text class="lbl-sm" x="665" y="163" text-anchor="middle">files (Cloudflare R2)</text>
+  <rect class="box" x="590" y="218" width="150" height="52" rx="8"/>
+  <text class="lbl" x="665" y="240" text-anchor="middle">Sign-in</text>
+  <text class="lbl-sm" x="665" y="257" text-anchor="middle">Google / Supabase</text>
+  <!-- arrows -->
+  <path class="flow" style="marker-end:url(#arw3)" d="M170,150 L268,150"/>
+  <path class="flow" style="marker-end:url(#arw3)" d="M492,140 L588,58"/>
+  <path class="flow" style="marker-end:url(#arw3)" d="M492,150 L588,150"/>
+  <path class="flow" style="marker-end:url(#arw3)" d="M492,162 L588,244"/>
+</svg>
+<figcaption>The interface, the API, and the embedding models all live in one
+container. Around it: a persistent database for records, object storage for
+uploaded files, and Google/Supabase for sign-in. Every piece is on a free tier.</figcaption>
+</figure>
+
+<h3>What happens during a run</h3>
+<figure>
+<svg viewBox="0 0 760 190" xmlns="http://www.w3.org/2000/svg" role="img"
+     aria-label="Data flow: upload, quality checks, embed items and texts, cosine similarity, scores, results and exports.">
+  <defs>
+    <marker id="arw2" markerWidth="9" markerHeight="9" refX="7" refY="3" orient="auto">
+      <path d="M0,0 L7,3 L0,6 Z" fill="var(--muted)"/>
+    </marker>
+  </defs>
+  <g>
+    <rect class="box" x="15" y="30" width="120" height="54" rx="8"/>
+    <text class="lbl-sm" x="75" y="52" text-anchor="middle">1. Upload</text>
+    <text class="lbl-sm" x="75" y="68" text-anchor="middle">corpus + construct</text>
+
+    <rect class="box" x="165" y="30" width="120" height="54" rx="8"/>
+    <text class="lbl-sm" x="225" y="52" text-anchor="middle">2. Quality checks</text>
+    <text class="lbl-sm" x="225" y="68" text-anchor="middle">language, warnings</text>
+
+    <rect class="box-accent" x="315" y="30" width="130" height="54" rx="8"/>
+    <text class="lbl-sm" x="380" y="52" text-anchor="middle">3. Embed both</text>
+    <text class="lbl-sm" x="380" y="68" text-anchor="middle">items &amp; texts, one model</text>
+
+    <rect class="box-accent" x="475" y="30" width="130" height="54" rx="8"/>
+    <text class="lbl-sm" x="540" y="52" text-anchor="middle">4. Cosine similarity</text>
+    <text class="lbl-sm" x="540" y="68" text-anchor="middle">text × each item</text>
+
+    <rect class="box" x="635" y="30" width="110" height="54" rx="8"/>
+    <text class="lbl-sm" x="690" y="52" text-anchor="middle">5. CCR score</text>
+    <text class="lbl-sm" x="690" y="68" text-anchor="middle">mean of items</text>
+
+    <rect class="box" x="240" y="120" width="280" height="50" rx="8"/>
+    <text class="lbl-sm" x="380" y="141" text-anchor="middle">6. Results: distributions, per-item loadings,</text>
+    <text class="lbl-sm" x="380" y="157" text-anchor="middle">top/bottom texts + CSV, metadata, repro script</text>
+  </g>
+  <path class="flow" style="marker-end:url(#arw2)" d="M135,57 L163,57"/>
+  <path class="flow" style="marker-end:url(#arw2)" d="M285,57 L313,57"/>
+  <path class="flow" style="marker-end:url(#arw2)" d="M445,57 L473,57"/>
+  <path class="flow" style="marker-end:url(#arw2)" d="M605,57 L633,57"/>
+  <path class="flow" style="marker-end:url(#arw2)" d="M690,84 L690,120 L522,145"/>
+</svg>
+<figcaption>CCR in one line: embed the validated scale items and your texts with
+the <em>same</em> model, then each text's cosine similarity to the items is its
+loading; the mean across items is the CCR score. It is deterministic embeddings
+plus arithmetic — no LLM, no prompting, no randomness.</figcaption>
+</figure>
+
+<h3>Where your data lives (and for how long)</h3>
+<ul>
+  <li><b>Records</b> (account, projects, run results and summaries) → the Postgres
+      database. Persistent, backed up.</li>
+  <li><b>Uploaded files</b> → object storage. Signed-in users' files persist;
+      anonymous uploads are deleted the moment their analysis finishes.</li>
+  <li><b>Anonymous sessions</b> are wiped entirely after 24&nbsp;hours; nothing you
+      upload anonymously is kept.</li>
+  <li><b>Reproducibility</b>: every run also records the exact model version, an
+      item-wording hash, and package versions, so the downloadable script
+      reproduces the numbers on any machine.</li>
+</ul>
+
+<h3>A few engineering choices worth knowing</h3>
+<ul>
+  <li><b>Same model for items and texts</b>, always — mixing models makes scores
+      non-comparable, so the platform records the model on every run and warns you.</li>
+  <li><b>MiniLM is the default</b> because it is the reference model in the published
+      CCR work; the stronger E5 models are available and clearly labelled.</li>
+  <li><b>Re-running a new construct on the same corpus is near-instant</b> — the
+      text embeddings are cached and reused (identical every time), so only the
+      cheap similarity step repeats.</li>
+  <li><b>Warnings never silently "fix" your data</b> — the platform surfaces issues
+      (wrong language, truncation, duplicates) and lets you decide.</li>
+  <li><b>Admin power is layered, not global</b> — see <a href="#access">§1</a>:
+      operations are delegated to maintainers, escalation stays with the PI, and
+      one env variable exists purely as the fire escape.</li>
+</ul>
+
+<h2 id="feedback">4. Questions?</h2>
+<p>For how-to and testing scenarios, see the <a href="/guide">testing guide</a>.
+Anything unclear on this page - post in the lab's <b>#ccr Slack channel</b> or email
+<a href="mailto:devaanand@umass.edu">devaanand@umass.edu</a>.</p>
+
+</main>
+<a class="top" href="#">↑ Top</a>
+<div class="toast" id="toast" role="status" aria-live="polite">Link copied</div>
+<script>
+(function () {
+  var toast = document.getElementById('toast'), timer;
+  function ping(msg) {
+    toast.textContent = msg;
+    toast.classList.add('show');
+    clearTimeout(timer);
+    timer = setTimeout(function () { toast.classList.remove('show'); }, 1600);
+  }
+  function share(id) {
+    if (history.replaceState) history.replaceState(null, '', '#' + id);
+    location.hash = id;
+    var url = location.href;
+    if (navigator.clipboard && navigator.clipboard.writeText) {
+      navigator.clipboard.writeText(url).then(
+        function () { ping('Section link copied'); },
+        function () { ping('Link in address bar'); }
+      );
+    } else {
+      ping('Link in address bar');
+    }
+  }
+  var heads = document.querySelectorAll('h2[id], h3[id]');
+  Array.prototype.forEach.call(heads, function (h) {
+    var a = document.createElement('a');
+    a.className = 'anchor';
+    a.href = '#' + h.id;
+    a.textContent = '#';
+    a.setAttribute('aria-label', 'Copy link to this section');
+    a.addEventListener('click', function (e) { e.preventDefault(); share(h.id); });
+    h.appendChild(a);
+    h.style.cursor = 'pointer';
+    h.addEventListener('click', function (e) {
+      if (e.target.tagName === 'A') return;
+      share(h.id);
+    });
+  });
+})();
+</script>
+</body>
+</html>

backend/app/schemas.py

@@ -26,6 +26,7 @@ class RegisterIn(BaseModel):
     email: str = Field(min_length=3, max_length=255)
     password: str = Field(min_length=8, max_length=200)
     name: str = Field(min_length=1, max_length=120)
+    invite_token: str | None = None  # signed invite link payload (auth.py)
 
 
 class LoginIn(BaseModel):

backend/static/index.html

@@ -4,7 +4,7 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>CCR Platform - Contextualized Construct Representations</title>
-    <script type="module" crossorigin src="/assets/index-cmMEZ7Xf.js"></script>
+    <script type="module" crossorigin src="/assets/index-DRZ4Mumd.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-CN_FzJfm.css">
   </head>
   <body>

backend/tests/test_admin.py

@@ -126,6 +126,70 @@ def _as_admin(client):
     return client
 
 
+def _user_id(client, email):
+    return next(u["id"] for u in client.get("/api/admin/users").json() if u["email"] == email)
+
+
+# ------------------------------------------- four tiers (PI decision 2026-07-22)
+def test_staff_roles_get_admin_surface_and_unlimited_runs(client, monkeypatch):
+    monkeypatch.setenv("CCR_USER_MAX_SAVED_RUNS", "1")
+    register(client, "newpi@lab.test", "The PI")
+    me = client.get("/api/auth/me").json()
+    assert me["role"] == "external" and me["is_admin"] is False  # default tier
+    assert me["usage"]["max_saved_runs"] == 1
+    client.post("/api/auth/logout")
+
+    _as_admin(client)
+    for role in ("pi", "maintainer", "lab", "external"):  # all four grantable
+        resp = client.post(f"/api/admin/users/{_user_id(client, 'newpi@lab.test')}/role",
+                           json={"role": role})
+        assert resp.status_code == 200 and resp.json()["role"] == role
+    client.post(f"/api/admin/users/{_user_id(client, 'newpi@lab.test')}/role",
+                json={"role": "pi"})
+    assert client.post(f"/api/admin/users/{_user_id(client, 'newpi@lab.test')}/role",
+                       json={"role": "owner"}).status_code == 400
+    overview = client.get("/api/admin/overview").json()
+    assert overview["users_by_role"]["pi"] >= 1
+    client.post("/api/auth/logout")
+
+    client.post("/api/auth/login", json={"email": "newpi@lab.test", "password": "password123"})
+    me = client.get("/api/auth/me").json()
+    assert me["role"] == "pi"
+    assert me["is_admin"] is True  # staff role grants the admin surface...
+    assert me["usage"]["max_saved_runs"] is None  # ...and unlimited saved runs
+    assert client.get("/api/admin/overview").status_code == 200
+
+
+def test_maintainer_cannot_escalate_or_touch_staff(client):
+    _as_admin(client)
+    for email, role in (("mnt@lab.test", "maintainer"), ("boss@lab.test", "pi"),
+                        ("phd2@lab.test", "external")):
+        sign_in_as(client, email)
+        client.post("/api/auth/logout")
+        _as_admin(client)
+        client.post(f"/api/admin/users/{_user_id(client, email)}/role", json={"role": role})
+    boss_id, phd_id = _user_id(client, "boss@lab.test"), _user_id(client, "phd2@lab.test")
+    client.post("/api/auth/logout")
+
+    client.post("/api/auth/login", json={"email": "mnt@lab.test", "password": "password123"})
+    # operational surface works, and lab/external grants are allowed...
+    assert client.get("/api/admin/overview").status_code == 200
+    assert client.post(f"/api/admin/users/{phd_id}/role",
+                       json={"role": "lab"}).status_code == 200
+    # ...but staff grants and any action on a staff account are env-admin only
+    assert client.post(f"/api/admin/users/{phd_id}/role",
+                       json={"role": "maintainer"}).status_code == 403
+    assert client.post(f"/api/admin/users/{boss_id}/role",
+                       json={"role": "external"}).status_code == 403
+    assert client.post(f"/api/admin/users/{boss_id}/reset-password").status_code == 403
+    assert client.delete(f"/api/admin/users/{boss_id}").status_code == 403
+    client.post("/api/auth/logout")
+
+    _as_admin(client)  # env admin CAN demote a staff account
+    assert client.post(f"/api/admin/users/{boss_id}/role",
+                       json={"role": "lab"}).status_code == 200
+
+
 # --------------------------------------------------------- reset + delete
 def test_password_reset_issues_working_temp_password(client):
     register(client, "forgetful@lab.test")
@@ -228,12 +292,33 @@ def test_failed_job_requeue(client, monkeypatch):
 
 
 # ------------------------------------------------------------ verification
-def test_verification_queue_marks_verified(client):
+def _make_role(client, email, role):
+    """Register (if needed) and set a role, as the env admin; leaves the
+    client signed in as that user."""
+    sign_in_as(client, email)
+    client.post("/api/auth/logout")
+    _as_admin(client)
+    resp = client.post(f"/api/admin/users/{_user_id(client, email)}/role", json={"role": role})
+    assert resp.status_code == 200, resp.json()
+    client.post("/api/auth/logout")
+    client.post("/api/auth/login", json={"email": email, "password": "password123"})
+
+
+def test_verification_is_the_maintainers_job(client):
+    """PI decision 2026-07-22: maintainers verify; PI/admin see the queue
+    read-only (the trail then names the responsible RA)."""
     sign_in_as(client, ADMIN_EMAIL, "Admin")
     queue = client.get("/api/admin/constructs?status=needs_verification").json()
     assert len(queue) > 0
     target = queue[0]
 
+    # env admin: queue visible, verification action refused
+    resp = client.post(
+        f"/api/admin/constructs/{target['id']}/verification", json={"status": "verified"}
+    )
+    assert resp.status_code == 403 and "maintainer" in resp.json()["detail"]
+
+    _make_role(client, "ra@lab.test", "maintainer")
     resp = client.post(
         f"/api/admin/constructs/{target['id']}/verification", json={"status": "verified"}
     )
@@ -244,3 +329,120 @@ def test_verification_queue_marks_verified(client):
     # visible to regular users too (flag disappears in the picker/details)
     pub = next(c for c in client.get("/api/constructs").json() if c["id"] == target["id"])
     assert pub["verification_status"] == "verified"
+
+
+# ------------------------------------- pre-login access + audit (PI email 2026-07-22)
+def test_preassigned_role_lands_on_first_signin(client):
+    """The Dr. Chen scenario: full credentials bound to an email before the
+    account exists; first sign-in (password or Google) claims them."""
+    _as_admin(client)
+    resp = client.post(
+        "/api/admin/role-assignments",
+        json={"email": "collaborator@other-lab.edu", "role": "maintainer"},
+    )
+    assert resp.status_code == 201
+    pending = client.get("/api/admin/role-assignments").json()
+    entry = next(a for a in pending if a["email"] == "collaborator@other-lab.edu")
+    assert entry["role"] == "maintainer" and entry["claimed_at"] is None
+    client.post("/api/auth/logout")
+
+    register(client, "collaborator@other-lab.edu", "Dr. Chen")
+    me = client.get("/api/auth/me").json()
+    assert me["role"] == "maintainer" and me["is_admin"] is True
+    assert me["usage"]["max_saved_runs"] is None
+    client.post("/api/auth/logout")
+
+    _as_admin(client)
+    claimed = next(
+        a for a in client.get("/api/admin/role-assignments").json()
+        if a["email"] == "collaborator@other-lab.edu"
+    )
+    assert claimed["claimed_at"] is not None
+    # existing accounts are managed in the Users table, not via pre-assignment
+    resp = client.post(
+        "/api/admin/role-assignments",
+        json={"email": "collaborator@other-lab.edu", "role": "lab"},
+    )
+    assert resp.status_code == 409
+
+
+def test_maintainer_cannot_preassign_staff(client):
+    _make_role(client, "mnt3@lab.test", "maintainer")
+    assert client.post(
+        "/api/admin/role-assignments",
+        json={"email": "someone@new.edu", "role": "pi"},
+    ).status_code == 403
+    assert client.post(
+        "/api/admin/role-assignments",
+        json={"email": "someone@new.edu", "role": "lab"},
+    ).status_code == 201
+
+
+def test_invite_link_grants_role_on_register(client, monkeypatch):
+    _as_admin(client)
+    invite = client.post("/api/admin/invites", json={"role": "lab"}).json()
+    assert invite["role"] == "lab" and invite["token"]
+    # staff can never be invited by bearer link
+    assert client.post("/api/admin/invites", json={"role": "maintainer"}).status_code == 400
+    client.post("/api/auth/logout")
+
+    resp = client.post("/api/auth/register", json={
+        "email": "invited@lab.test", "password": "password123",
+        "name": "Invited", "invite_token": invite["token"],
+    })
+    assert resp.status_code == 201
+    me = client.get("/api/auth/me").json()
+    assert me["role"] == "lab" and me["usage"]["max_saved_runs"] is None
+    client.post("/api/auth/logout")
+
+    # dead/garbage tokens refuse registration instead of silently demoting
+    resp = client.post("/api/auth/register", json={
+        "email": "invited2@lab.test", "password": "password123",
+        "name": "Invited2", "invite_token": "garbage.token",
+    })
+    assert resp.status_code == 400 and "invite" in resp.json()["detail"].lower()
+
+    monkeypatch.setenv("CCR_INVITE_TTL_DAYS", "-1")  # mint an already-expired invite
+    _as_admin(client)
+    expired = client.post("/api/admin/invites", json={"role": "lab"}).json()
+    client.post("/api/auth/logout")
+    resp = client.post("/api/auth/register", json={
+        "email": "invited3@lab.test", "password": "password123",
+        "name": "Invited3", "invite_token": expired["token"],
+    })
+    assert resp.status_code == 400
+
+
+def test_audit_trail_records_and_is_pi_only(client):
+    _as_admin(client)
+    audit = client.get("/api/admin/audit")
+    assert audit.status_code == 200
+    actions = {(a["action"], a["target"]) for a in audit.json()}
+    assert ("role_preassigned", "collaborator@other-lab.edu") in actions
+    assert ("role_claimed", "collaborator@other-lab.edu") in actions
+    assert ("invite_redeemed", "invited@lab.test") in actions
+    assert any(a[0] == "set_verification" for a in actions)
+    client.post("/api/auth/logout")
+
+    # maintainers work the cards but don't get top-down oversight
+    client.post("/api/auth/login", json={"email": "mnt3@lab.test", "password": "password123"})
+    assert client.get("/api/admin/audit").status_code == 403
+
+
+def test_pi_role_holds_escalation_rights_and_no_self_change(client):
+    _make_role(client, "pi2@lab.test", "pi")
+    me = client.get("/api/auth/me").json()
+    assert me["role"] == "pi" and me["is_admin"] is True
+
+    sign_in_as(client, "newbie@lab.test")
+    client.post("/api/auth/logout")
+    client.post("/api/auth/login", json={"email": "pi2@lab.test", "password": "password123"})
+    newbie_id = _user_id(client, "newbie@lab.test")
+    # a PI-by-role can mint staff and see the audit trail - no env entry needed
+    assert client.post(f"/api/admin/users/{newbie_id}/role",
+                       json={"role": "maintainer"}).status_code == 200
+    assert client.get("/api/admin/audit").status_code == 200
+    # but nobody, PI included, can change their own role
+    my_id = _user_id(client, "pi2@lab.test")
+    resp = client.post(f"/api/admin/users/{my_id}/role", json={"role": "external"})
+    assert resp.status_code == 400 and "own role" in resp.json()["detail"]

backend/tests/test_api.py

@@ -78,6 +78,13 @@ def test_health(client):
     assert client.get("/api/health").json()["status"] == "ok"
 
 
+def test_guide_and_product_pages_served(client):
+    for path in ("/guide", "/product"):
+        resp = client.get(path)
+        assert resp.status_code == 200, path
+        assert "text/html" in resp.headers["content-type"]
+
+
 def test_seed_constructs_present(client):
     names = {c["name"] for c in client.get("/api/constructs").json()}
     assert "Satisfaction with Life" in names

frontend/src/AdminPage.jsx

@@ -2,8 +2,18 @@ import { useCallback, useEffect, useState } from "react";
 
 // Minimal admin surface (v1): overview counters, user roles + password
 // resets, failed-run requeue, and the RA's construct-verification queue.
-// Access is enforced server-side (ADMIN_EMAILS); this page just renders
-// what the admin API returns.
+// Access is enforced server-side (ADMIN_EMAILS allowlist or pi/maintainer
+// role); this page just renders what the admin API returns. Actions a
+// maintainer isn't allowed to take (granting staff roles, touching staff
+// accounts) are rejected by the server and surface in the error banner.
+
+const ROLES = ["external", "lab", "maintainer", "pi"];
+const ROLE_LABELS = {
+  external: "external user",
+  lab: "lab member",
+  maintainer: "maintainer",
+  pi: "PI",
+};
 
 async function adminFetch(path, options = {}) {
   const resp = await fetch(path, options);
@@ -29,15 +39,26 @@ export default function AdminPage({ auth }) {
   const [users, setUsers] = useState([]);
   const [failed, setFailed] = useState([]);
   const [constructs, setConstructs] = useState([]);
+  const [assignments, setAssignments] = useState([]);
+  const [audit, setAudit] = useState(null); // null = not visible (maintainers)
   const [onlyUnverified, setOnlyUnverified] = useState(true);
+  const [inviteRole, setInviteRole] = useState("lab");
+  const [assignEmail, setAssignEmail] = useState("");
+  const [assignRole, setAssignRole] = useState("lab");
   const [error, setError] = useState("");
   const [notice, setNotice] = useState("");
 
+  // Only maintainers can flip verification statuses (the RA workflow);
+  // PI/admin see the queue read-only. Enforced server-side too.
+  const canVerify = auth?.role === "maintainer";
+
   const reload = useCallback(() => {
     setError("");
     adminFetch("/api/admin/overview").then(setOverview).catch((e) => setError(e.message));
     adminFetch("/api/admin/users").then(setUsers).catch(() => {});
     adminFetch("/api/admin/jobs/failed").then(setFailed).catch(() => {});
+    adminFetch("/api/admin/role-assignments").then(setAssignments).catch(() => {});
+    adminFetch("/api/admin/audit").then(setAudit).catch(() => setAudit(null)); // 403 for maintainers
     adminFetch(
       "/api/admin/constructs" + (onlyUnverified ? "?status=needs_verification" : "")
     ).then(setConstructs).catch(() => {});
@@ -87,8 +108,11 @@ export default function AdminPage({ auth }) {
         <h3>Overview</h3>
         {overview ? (
           <p className="hint">
-            <b>{overview.users}</b> accounts ({overview.lab_users} lab tier,{" "}
-            {overview.signups_last_7_days} new this week) · <b>{overview.runs_total}</b>{" "}
+            <b>{overview.users}</b> accounts (
+            {ROLES.filter((r) => overview.users_by_role?.[r])
+              .map((r) => `${overview.users_by_role[r]} ${ROLE_LABELS[r]}`)
+              .join(", ") || "none"}
+            ; {overview.signups_last_7_days} new this week) · <b>{overview.runs_total}</b>{" "}
             runs total ({overview.runs_last_7_days} this week
             {overview.runs_by_status?.failed ? `, ${overview.runs_by_status.failed} failed` : ""}) ·{" "}
             <b>{overview.projects}</b> projects ({overview.anonymous_projects} anonymous) ·{" "}
@@ -112,20 +136,21 @@ export default function AdminPage({ auth }) {
                 <tr key={u.id}>
                   <td>{u.email}{u.is_admin ? " ★" : ""}</td>
                   <td>{u.name}</td>
-                  <td><span className={`pill ${u.role === "lab" ? "completed" : "queued"}`}>{u.role}</span></td>
-                  <td>{u.saved_runs}</td>
-                  <td className="muted small">{u.google_only ? "Google" : "password"}</td>
                   <td>
-                    <button
-                      className="linkish"
-                      onClick={() =>
-                        act(() => post(`/api/admin/users/${u.id}/role`, {
-                          role: u.role === "lab" ? "member" : "lab",
-                        }))
+                    <select
+                      value={u.role}
+                      onChange={(e) =>
+                        act(() => post(`/api/admin/users/${u.id}/role`, { role: e.target.value }))
                       }
                     >
-                      {u.role === "lab" ? "Make member" : "Make lab (unlimited)"}
-                    </button>{" "}
+                      {ROLES.map((r) => (
+                        <option key={r} value={r}>{ROLE_LABELS[r]}</option>
+                      ))}
+                    </select>
+                  </td>
+                  <td>{u.saved_runs}</td>
+                  <td className="muted small">{u.google_only ? "Google" : "password"}</td>
+                  <td>
                     {!u.google_only && (
                       <button
                         className="linkish"
@@ -139,7 +164,7 @@ export default function AdminPage({ auth }) {
                         Reset password
                       </button>
                     )}{" "}
-                    {!u.is_admin && (
+                    {!u.env_admin && (
                       <button
                         className="linkish danger"
                         onClick={() => {
@@ -162,6 +187,128 @@ export default function AdminPage({ auth }) {
         </div>
       </div>
 
+      {/* Access before sign-in: pre-assigned roles + invite links */}
+      <div className="card">
+        <h3>Access before sign-in</h3>
+        <p className="hint">
+          <b>Pre-assign a role to an email</b> (e.g. an external collaborator who
+          should land with full credentials): whoever first signs in with that
+          email - password or Google - gets the role automatically.
+        </p>
+        <form
+          onSubmit={(e) => {
+            e.preventDefault();
+            if (!assignEmail.trim()) return;
+            act(async () => {
+              await post("/api/admin/role-assignments", {
+                email: assignEmail.trim(), role: assignRole,
+              });
+              setAssignEmail("");
+            });
+          }}
+          style={{ display: "flex", gap: ".5rem", flexWrap: "wrap", alignItems: "center" }}
+        >
+          <input
+            type="email"
+            placeholder="person@university.edu"
+            value={assignEmail}
+            onChange={(e) => setAssignEmail(e.target.value)}
+            style={{ minWidth: "16rem" }}
+          />
+          <select value={assignRole} onChange={(e) => setAssignRole(e.target.value)}>
+            {ROLES.map((r) => (
+              <option key={r} value={r}>{ROLE_LABELS[r]}</option>
+            ))}
+          </select>
+          <button type="submit" disabled={!assignEmail.trim()}>Pre-assign</button>
+        </form>
+        {assignments.length > 0 && (
+          <div className="table-wrap">
+            <table className="docs">
+              <thead>
+                <tr><th>Email</th><th>Role</th><th>By</th><th>Status</th><th /></tr>
+              </thead>
+              <tbody>
+                {assignments.map((a) => (
+                  <tr key={a.id}>
+                    <td>{a.email}</td>
+                    <td>{ROLE_LABELS[a.role] || a.role}</td>
+                    <td className="muted small">{a.assigned_by}</td>
+                    <td className="muted small">
+                      {a.claimed_at ? `claimed ${a.claimed_at.slice(0, 10)}` : "pending"}
+                    </td>
+                    <td>
+                      {!a.claimed_at && (
+                        <button
+                          className="linkish danger"
+                          onClick={() =>
+                            act(() => adminFetch(`/api/admin/role-assignments/${a.id}`, { method: "DELETE" }))
+                          }
+                        >
+                          Remove
+                        </button>
+                      )}
+                    </td>
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+          </div>
+        )}
+        <p className="hint" style={{ marginTop: "1rem" }}>
+          <b>Or create an invite link</b> (anyone with the link; lab member /
+          external only - staff is granted per person above): paste it in Slack,
+          it expires after a week.
+        </p>
+        <div style={{ display: "flex", gap: ".5rem", alignItems: "center" }}>
+          <select value={inviteRole} onChange={(e) => setInviteRole(e.target.value)}>
+            <option value="lab">lab member</option>
+            <option value="external">external user</option>
+          </select>
+          <button
+            onClick={() =>
+              act(async () => {
+                const r = await post("/api/admin/invites", { role: inviteRole });
+                const url = `${window.location.origin}/?invite=${encodeURIComponent(r.token)}`;
+                try { await navigator.clipboard.writeText(url); } catch { /* show below */ }
+                setNotice(`Invite link (${ROLE_LABELS[r.role]}, expires ${r.expires_at}) - copied: ${url}`);
+              })
+            }
+          >
+            Create invite link
+          </button>
+        </div>
+      </div>
+
+      {/* Audit trail - PI/env-admin only (404s/403s hide it for maintainers) */}
+      {audit !== null && (
+        <div className="card">
+          <h3>Audit trail</h3>
+          {audit.length === 0 ? (
+            <p className="hint">No admin actions recorded yet.</p>
+          ) : (
+            <div className="table-wrap">
+              <table className="docs">
+                <thead>
+                  <tr><th>When</th><th>Who</th><th>Action</th><th>Target</th><th>Detail</th></tr>
+                </thead>
+                <tbody>
+                  {audit.map((a, i) => (
+                    <tr key={i}>
+                      <td className="muted small">{a.at.replace("T", " ").slice(0, 16)}</td>
+                      <td className="small">{a.actor}</td>
+                      <td className="small">{a.action.replaceAll("_", " ")}</td>
+                      <td className="small">{a.target}</td>
+                      <td className="muted small">{a.detail}</td>
+                    </tr>
+                  ))}
+                </tbody>
+              </table>
+            </div>
+          )}
+        </div>
+      )}
+
       {/* Failed runs */}
       <div className="card">
         <h3>Failed runs</h3>
@@ -204,10 +351,11 @@ export default function AdminPage({ auth }) {
       <div className="card">
         <h3>Construct verification</h3>
         <p className="hint">
-          For the RA workflow: mark a scale verified once its wording is checked
-          against the original publication (cross-reference the verification
-          checklist spreadsheet). Statuses set here are applied back to the
-          library files before production.
+          The maintainer's workflow: mark a scale verified once its wording is
+          checked against the original publication (cross-reference the
+          verification checklist spreadsheet). Statuses set here are applied
+          back to the library files before production.
+          {!canVerify && " Your account has read access; verification actions are for maintainers."}
           {" "}
           <button className="linkish" onClick={() => setOnlyUnverified((v) => !v)}>
             {onlyUnverified ? "Show all" : "Show unverified only"}
@@ -230,18 +378,20 @@ export default function AdminPage({ auth }) {
                     </span>
                   </td>
                   <td>
-                    <button
-                      className="linkish"
-                      onClick={() =>
-                        act(() => post(`/api/admin/constructs/${c.id}/verification`, {
-                          status: c.verification_status === "verified"
-                            ? "needs_verification"
-                            : "verified",
-                        }))
-                      }
-                    >
-                      {c.verification_status === "verified" ? "Un-verify" : "Mark verified"}
-                    </button>
+                    {canVerify && (
+                      <button
+                        className="linkish"
+                        onClick={() =>
+                          act(() => post(`/api/admin/constructs/${c.id}/verification`, {
+                            status: c.verification_status === "verified"
+                              ? "needs_verification"
+                              : "verified",
+                          }))
+                        }
+                      >
+                        {c.verification_status === "verified" ? "Un-verify" : "Mark verified"}
+                      </button>
+                    )}
                   </td>
                 </tr>
               ))}

frontend/src/App.jsx

@@ -55,6 +55,19 @@ export default function App() {
   const [authName, setAuthName] = useState("");
   const [authError, setAuthError] = useState("");
   const [authBusy, setAuthBusy] = useState(false);
+  const [inviteToken, setInviteToken] = useState("");
+
+  // Invite links carry their role in the signed payload; decode it for the
+  // banner only - the server re-verifies the signature on registration.
+  const inviteRole = (() => {
+    if (!inviteToken) return null;
+    try {
+      const data = JSON.parse(atob(inviteToken.split(".")[0].replace(/-/g, "+").replace(/_/g, "/")));
+      return { lab: "lab member", external: "external user" }[data.invite] || null;
+    } catch {
+      return null;
+    }
+  })();
 
   const loadProjects = () =>
     api.listProjects().then(setProjects).catch((e) => setError(e.message));
@@ -70,6 +83,15 @@ export default function App() {
       setError(`Sign-in problem: ${authFail.replaceAll("-", " ")}.`);
       window.history.replaceState({}, "", "/");
     }
+    // Invite link (?invite=TOKEN): open the signup form with the token
+    // attached. The URL keeps the token until signup succeeds, so a page
+    // refresh doesn't lose the invite.
+    const invite = params.get("invite");
+    if (invite) {
+      setInviteToken(invite);
+      setAuthMode("register");
+      setShowLogin(true);
+    }
   }, []);
 
   async function handleAuthSubmit(e) {
@@ -78,7 +100,14 @@ export default function App() {
     setAuthBusy(true);
     try {
       if (authMode === "register") {
-        await api.register({ email: authEmail.trim(), password: authPassword, name: authName.trim() });
+        await api.register({
+          email: authEmail.trim(), password: authPassword, name: authName.trim(),
+          ...(inviteToken ? { invite_token: inviteToken } : {}),
+        });
+        if (inviteToken) {
+          setInviteToken("");
+          window.history.replaceState({}, "", "/"); // invite consumed
+        }
       } else {
         await api.login({ email: authEmail.trim(), password: authPassword });
       }
@@ -163,6 +192,12 @@ export default function App() {
         <div className="modal-backdrop" onClick={() => setShowLogin(false)}>
           <div className="modal" onClick={(e) => e.stopPropagation()}>
             <h3>{authMode === "register" ? "Create an account" : "Sign in"}</h3>
+            {inviteToken && authMode === "register" && (
+              <p className="hint" style={{ fontWeight: 600 }}>
+                🎟 You've been invited{inviteRole ? ` as a ${inviteRole}` : ""} - create
+                your account below and the access comes with it.
+              </p>
+            )}
             <p className="hint">
               Accounts are free. Signing in lifts the anonymous limits
               {auth?.limits?.max_rows