Admin page v1: user roles (lab tier), password resets, failed-run requeue, verification queue

Synced from lab mainline. /admin gated by ADMIN_EMAILS env allowlist.
Lab-role accounts get unlimited saved runs (replaces the global env
hack). 72 tests passing.

.env.example

@@ -51,6 +51,10 @@
 # Public base URL of this app (Google redirect target).
 # CCR_APP_URL=http://127.0.0.1:8000
 
+# ---- Admin access ----
+# Comma-separated allowlist; these signed-in accounts see /admin (user roles,
+# password resets, failed-run requeue, verification queue, usage stats).
+# ADMIN_EMAILS=devaanand@umass.edu,matari@umass.edu
+
 # ---- Phase 2 (not read yet; reserved names) ----
 # DATABASE_URL=postgresql://...
-# ADMIN_EMAILS=devaanand@umass.edu,matari@umass.edu

MANUAL_TESTING.md

@@ -162,3 +162,20 @@ Checklist before giving the URL to real users:
 - [ ] `CCR_DATA_DIR` on a persistent volume (default /tmp is ephemeral)
 - [ ] `CCR_ANON_TTL_HOURS=24` (default in the image)
 - [ ] Smoke test: sections 2, 4, 6, 7 above
+
+## 12. Admin page (/admin)
+
+Requires `ADMIN_EMAILS` to include your signed-in email (see .env.example).
+
+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.
+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).
+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
+   platform-wide. Statuses are applied back to the library YAML before
+   production.

backend/app/admin.py

@@ -0,0 +1,234 @@
+"""Admin endpoints - the minimal operational surface (design: admin page v1).
+
+Four concrete pains drive this, nothing speculative:
+  * password resets ("reset = admin action" finally has an admin action),
+  * per-user lab tier (replaces the global saved-run env hack: lab accounts
+    get unlimited saved runs, public accounts keep the cap),
+  * the RA's verification queue (mark constructs verified from the UI;
+    the YAML library stays the durable source of truth - DB status is the
+    operational overlay and is written back to YAML by the developer),
+  * 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.
+"""
+
+from __future__ import annotations
+
+import json
+import secrets
+from datetime import datetime, timedelta, timezone
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from sqlalchemy import func
+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
+
+router = APIRouter(prefix="/api/admin", tags=["admin"])
+
+
+def require_admin(request: Request) -> dict:
+    user = auth.get_current_user(request)
+    if user is None or not auth.is_admin(user.get("email")):
+        raise HTTPException(403, "Admin access required.")
+    return user
+
+
+# ---------------------------------------------------------------- overview
+@router.get("/overview")
+def overview(db: Session = Depends(get_db), _admin: dict = Depends(require_admin)):
+    week_ago = (datetime.now(timezone.utc) - timedelta(days=7)).isoformat(timespec="seconds")
+    runs_by_status = dict(
+        db.query(Job.status, func.count(Job.id)).group_by(Job.status).all()
+    )
+    return {
+        "users": db.query(User).count(),
+        "lab_users": db.query(User).filter_by(role="lab").count(),
+        "projects": db.query(Project).count(),
+        "anonymous_projects": db.query(Project).filter_by(owner_user_id="").count(),
+        "corpora": db.query(Corpus).count(),
+        "runs_total": db.query(Job).count(),
+        "runs_by_status": runs_by_status,
+        "runs_last_7_days": db.query(Job).filter(Job.created_at >= week_ago).count(),
+        "signups_last_7_days": db.query(User).filter(User.created_at >= week_ago).count(),
+        "constructs_unverified": db.query(Construct)
+        .filter(Construct.verification_status != "verified")
+        .filter_by(is_seed=True)
+        .count(),
+    }
+
+
+# ------------------------------------------------------------------- users
+@router.get("/users")
+def list_users(db: Session = Depends(get_db), _admin: dict = Depends(require_admin)):
+    saved = dict(
+        db.query(Project.owner_user_id, func.count(Job.id))
+        .join(Job, Job.project_id == Project.id)
+        .filter(Project.owner_user_id != "")
+        .group_by(Project.owner_user_id)
+        .all()
+    )
+    return [
+        {
+            "id": u.id,
+            "email": u.email,
+            "name": u.name,
+            "role": u.role or "member",
+            "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),
+        }
+        for u in db.query(User).order_by(User.created_at.desc()).all()
+    ]
+
+
+@router.post("/users/{user_id}/role")
+def set_role(
+    user_id: str,
+    body: dict,
+    db: Session = Depends(get_db),
+    _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'.")
+    user = db.get(User, user_id)
+    if user is None:
+        raise HTTPException(404, "User not found")
+    user.role = 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)
+):
+    """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")
+    temp = secrets.token_urlsafe(9)  # 12 chars, meets the minimum length
+    user.password_hash = auth.hash_password(temp)
+    db.commit()
+    return {"id": user.id, "email": user.email, "temporary_password": temp}
+
+
+@router.delete("/users/{user_id}", status_code=204)
+def delete_user(
+    user_id: str, db: Session = Depends(get_db), admin: dict = Depends(require_admin)
+):
+    """Remove an account and everything it owns (files included)."""
+    if user_id == admin["id"]:
+        raise HTTPException(400, "You cannot delete your own admin account.")
+    user = db.get(User, user_id)
+    if user is None:
+        raise HTTPException(404, "User not found")
+    for project in db.query(Project).filter_by(owner_user_id=user_id).all():
+        retention.delete_project_cascade(db, project)
+    db.delete(user)
+    db.commit()
+    return None
+
+
+# ----------------------------------------------------------- failed runs
+@router.get("/jobs/failed")
+def failed_jobs(db: Session = Depends(get_db), _admin: dict = Depends(require_admin)):
+    rows = (
+        db.query(Job)
+        .filter(Job.status == "failed")
+        .order_by(Job.created_at.desc())
+        .limit(50)
+        .all()
+    )
+    out = []
+    for j in rows:
+        corpus = db.get(Corpus, j.corpus_id)
+        out.append(
+            {
+                "id": j.id,
+                "created_at": j.created_at,
+                "model_name": j.model_name,
+                "language": j.language,
+                "corpus_filename": corpus.filename if corpus else "",
+                "corpus_file_available": bool(corpus and storage.exists(corpus.path)),
+                "error_tail": (j.error or "").strip().splitlines()[-1] if j.error else "",
+            }
+        )
+    return out
+
+
+@router.post("/jobs/{job_id}/requeue")
+def requeue_job(
+    job_id: str, db: Session = Depends(get_db), _admin: dict = Depends(require_admin)
+):
+    job = db.get(Job, job_id)
+    if job is None:
+        raise HTTPException(404, "Job not found")
+    if job.status != "failed":
+        raise HTTPException(409, f"Only failed jobs can be requeued (status: {job.status}).")
+    corpus = db.get(Corpus, job.corpus_id)
+    if corpus is None or not storage.exists(corpus.path):
+        raise HTTPException(
+            410, "The corpus file is gone (anonymous retention); the run cannot be repeated."
+        )
+    job.status = "queued"
+    job.error = ""
+    job.progress = 0.0
+    job.started_at = ""
+    job.finished_at = ""
+    db.commit()
+    jobs_module.submit_job(job.id)
+    return {"id": job.id, "status": "queued"}
+
+
+# ------------------------------------------------------ verification queue
+@router.get("/constructs")
+def constructs_for_review(
+    status: str = "",
+    db: Session = Depends(get_db),
+    _admin: dict = Depends(require_admin),
+):
+    q = db.query(Construct).filter_by(is_seed=True)
+    if status:
+        q = q.filter(Construct.verification_status == status)
+    return [
+        {
+            "id": c.id,
+            "name": c.name,
+            "slug": c.construct_slug,
+            "category": c.category or "",
+            "n_items": len(json.loads(c.items_json)),
+            "verification_status": c.verification_status or "draft",
+            "reference": c.reference or "",
+        }
+        for c in q.order_by(Construct.name).all()
+    ]
+
+
+@router.post("/constructs/{construct_id}/verification")
+def set_verification(
+    construct_id: str,
+    body: dict,
+    db: Session = Depends(get_db),
+    _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)."""
+    status = str(body.get("status", "")).strip()
+    if status not in ("verified", "needs_verification"):
+        raise HTTPException(400, "Status must be 'verified' or 'needs_verification'.")
+    construct = db.get(Construct, construct_id)
+    if construct is None:
+        raise HTTPException(404, "Construct not found")
+    construct.verification_status = status
+    db.commit()
+    return {"id": construct.id, "verification_status": construct.verification_status}

backend/app/auth.py

@@ -73,6 +73,17 @@ def cookies_secure() -> bool:
     return os.environ.get("CCR_COOKIE_SECURE") == "1"
 
 
+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."""
+    raw = os.environ.get("ADMIN_EMAILS", "")
+    return {e.strip().lower() for e in raw.split(",") if e.strip()}
+
+
+def is_admin(email: str | None) -> bool:
+    return bool(email) and email.strip().lower() in admin_emails()
+
+
 # ---------------------------------------------------------- passwords
 def hash_password(password: str) -> str:
     salt = secrets.token_bytes(16)

backend/app/main.py

@@ -22,6 +22,7 @@ from fastapi.responses import FileResponse, JSONResponse, PlainTextResponse
 from fastapi.staticfiles import StaticFiles
 from sqlalchemy.orm import Session
 
+from . import admin as admin_module
 from . import auth, auth_google, retention, storage
 from . import jobs as jobs_module
 from . import registry
@@ -84,6 +85,7 @@ async def lifespan(_: FastAPI):
 
 
 app = FastAPI(title="CCR Platform", version="0.1.0", lifespan=lifespan)
+app.include_router(admin_module.router)
 
 app.add_middleware(GZipMiddleware, minimum_size=1024)  # constructs payload + SPA compress ~4-5x
 app.add_middleware(
@@ -208,14 +210,19 @@ def auth_me(
     user: dict | None = Depends(auth.get_current_user),
 ):
     if user:
+        row = db.get(User, user["id"])
+        role = (row.role if row else None) or "member"
         return {
             "signed_in": True,
             "name": user["name"],
             "email": user["email"],
+            "role": role,
+            "is_admin": auth.is_admin(user["email"]),
             "limits": {"max_bytes": MAX_UPLOAD_BYTES, "max_rows": None},
             "usage": {
                 "saved_runs": _saved_runs_used(db, user["id"]),
-                "max_saved_runs": auth.user_max_saved_runs(),
+                # lab accounts: unlimited saved runs (admin-granted role)
+                "max_saved_runs": None if role == "lab" else auth.user_max_saved_runs(),
             },
         }
     return {
@@ -617,8 +624,12 @@ def create_job(
                 "Sign in (top right) to keep running - accounts are free.",
             )
     else:
-        # Signed-in tier: saved-run cap instead of deletion (their data, their call).
-        if _saved_runs_used(db, user["id"]) >= auth.user_max_saved_runs():
+        # Signed-in tier: saved-run cap instead of deletion (their data, their
+        # call). Lab-role accounts (admin-granted) are uncapped.
+        row = db.get(User, user["id"])
+        if (row.role if row else "member") != "lab" and (
+            _saved_runs_used(db, user["id"]) >= auth.user_max_saved_runs()
+        ):
             raise HTTPException(
                 409,
                 f"You have {auth.user_max_saved_runs()} saved runs (the maximum). "
@@ -766,6 +777,16 @@ def testing_guide():
     return FileResponse(GUIDE_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
+    (and shows access-denied unless /api/auth/me says is_admin)."""
+    index = Path(__file__).resolve().parent.parent / "static" / "index.html"
+    if not index.exists():
+        raise HTTPException(404, "UI not built.")
+    return FileResponse(index, media_type="text/html")
+
+
 if SAMPLES_DIR.exists():
     app.mount("/samples", StaticFiles(directory=SAMPLES_DIR), name="samples")
 

backend/app/models.py

@@ -29,6 +29,9 @@ 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).
     created_at: Mapped[str] = mapped_column(String(32), default=_now)
 
 

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-DrFcy6bH.js"></script>
+    <script type="module" crossorigin src="/assets/index-CeDfDyqW.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-CN_FzJfm.css">
   </head>
   <body>

backend/tests/test_admin.py

@@ -0,0 +1,220 @@
+"""Admin surface: env-allowlist gate, roles + lab-tier cap bypass, password
+reset, user deletion cascade, failed-run requeue, verification queue."""
+
+import io
+import time
+
+import pytest
+from fastapi.testclient import TestClient
+
+from app.main import app
+
+ADMIN_EMAIL = "admin@lab.test"
+
+
+@pytest.fixture()
+def client(monkeypatch):
+    monkeypatch.setenv("ADMIN_EMAILS", f"{ADMIN_EMAIL}, other-admin@lab.test")
+    with TestClient(app) as c:
+        yield c
+
+
+def register(client, email, name="User"):
+    resp = client.post(
+        "/api/auth/register", json={"email": email, "password": "password123", "name": name}
+    )
+    assert resp.status_code == 201
+    return resp.json()
+
+
+def sign_in_as(client, email, name="User"):
+    """Login-or-register: the test DB persists across tests in this module."""
+    client.post("/api/auth/logout")
+    resp = client.post("/api/auth/login", json={"email": email, "password": "password123"})
+    if resp.status_code != 200:
+        register(client, email, name)
+
+
+def csv_rows(n: int) -> bytes:
+    return ("text\n" + "\n".join(f"sample sentence number {i} here" for i in range(n))).encode()
+
+
+def upload(client, project_id, name, payload):
+    return client.post(
+        f"/api/projects/{project_id}/corpora",
+        files={"file": (name, io.BytesIO(payload), "text/csv")},
+    )
+
+
+def run_job(client, project_id, corpus_id, construct_id):
+    return client.post(
+        "/api/jobs",
+        json={
+            "project_id": project_id,
+            "corpus_id": corpus_id,
+            "construct_id": construct_id,
+            "text_column": "text",
+            "model_name": "fake-deterministic",
+        },
+    )
+
+
+def wait_for_job(client, job_id, timeout=10.0):
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        job = client.get(f"/api/jobs/{job_id}").json()
+        if job["status"] in ("completed", "failed"):
+            return job
+        time.sleep(0.05)
+    raise TimeoutError(job_id)
+
+
+# ------------------------------------------------------------------ access
+def test_admin_requires_allowlisted_signed_in_user(client):
+    assert client.get("/api/admin/overview").status_code == 403  # anonymous
+
+    register(client, "normal@lab.test")
+    assert client.get("/api/admin/overview").status_code == 403  # signed in, not allowlisted
+    me = client.get("/api/auth/me").json()
+    assert me["is_admin"] is False
+    client.post("/api/auth/logout")
+
+    register(client, ADMIN_EMAIL, "Admin")
+    me = client.get("/api/auth/me").json()
+    assert me["is_admin"] is True
+    resp = client.get("/api/admin/overview")
+    assert resp.status_code == 200
+    assert resp.json()["users"] >= 2
+
+
+def test_admin_page_route_serves_ui(client):
+    resp = client.get("/admin")
+    assert resp.status_code == 200
+    assert "text/html" in resp.headers["content-type"]
+
+
+# ------------------------------------------------------ roles and lab tier
+def test_lab_role_bypasses_saved_run_cap(client, monkeypatch):
+    monkeypatch.setenv("CCR_USER_MAX_SAVED_RUNS", "1")
+    register(client, "phd@lab.test", "PhD")
+    project = client.post("/api/projects", json={"name": "LabTier"}).json()
+    corpus = upload(client, project["id"], "c.csv", csv_rows(5)).json()
+    construct = client.get("/api/constructs").json()[0]
+
+    resp = run_job(client, project["id"], corpus["id"], construct["id"])
+    assert resp.status_code == 201
+    wait_for_job(client, resp.json()["id"])
+    assert run_job(client, project["id"], corpus["id"], construct["id"]).status_code == 409
+
+    phd_id = next(
+        u["id"] for u in _as_admin(client).get("/api/admin/users").json()
+        if u["email"] == "phd@lab.test"
+    )
+    resp = client.post(f"/api/admin/users/{phd_id}/role", json={"role": "lab"})
+    assert resp.status_code == 200 and resp.json()["role"] == "lab"
+    client.post("/api/auth/logout")
+
+    client.post("/api/auth/login", json={"email": "phd@lab.test", "password": "password123"})
+    me = client.get("/api/auth/me").json()
+    assert me["role"] == "lab" and me["usage"]["max_saved_runs"] is None
+    resp = run_job(client, project["id"], corpus["id"], construct["id"])
+    assert resp.status_code == 201  # cap no longer applies
+
+
+def _as_admin(client):
+    sign_in_as(client, ADMIN_EMAIL, "Admin")
+    return client
+
+
+# --------------------------------------------------------- reset + delete
+def test_password_reset_issues_working_temp_password(client):
+    register(client, "forgetful@lab.test")
+    sign_in_as(client, ADMIN_EMAIL, "Admin")
+
+    uid = next(
+        u["id"] for u in client.get("/api/admin/users").json()
+        if u["email"] == "forgetful@lab.test"
+    )
+    temp = client.post(f"/api/admin/users/{uid}/reset-password").json()["temporary_password"]
+    client.post("/api/auth/logout")
+
+    bad = client.post(
+        "/api/auth/login", json={"email": "forgetful@lab.test", "password": "password123"}
+    )
+    assert bad.status_code == 401  # old password dead
+    good = client.post(
+        "/api/auth/login", json={"email": "forgetful@lab.test", "password": temp}
+    )
+    assert good.status_code == 200
+
+
+def test_delete_user_cascades_and_protects_self(client):
+    register(client, "doomed@lab.test")
+    project = client.post("/api/projects", json={"name": "DoomedData"}).json()
+    upload(client, project["id"], "c.csv", csv_rows(5))
+    client.post("/api/auth/logout")
+
+    sign_in_as(client, ADMIN_EMAIL, "Admin")
+    users = client.get("/api/admin/users").json()
+    doomed_id = next(u["id"] for u in users if u["email"] == "doomed@lab.test")
+    my_id = next(u["id"] for u in users if u["email"] == ADMIN_EMAIL)
+
+    assert client.delete(f"/api/admin/users/{my_id}").status_code == 400  # self-protect
+    assert client.delete(f"/api/admin/users/{doomed_id}").status_code == 204
+    assert all(
+        u["email"] != "doomed@lab.test" for u in client.get("/api/admin/users").json()
+    )
+    assert client.get(f"/api/projects/{project['id']}/corpora").status_code in (403, 404)
+
+
+# ------------------------------------------------------------ failed runs
+def test_failed_job_requeue(client, monkeypatch):
+    sign_in_as(client, ADMIN_EMAIL, "Admin")
+    project = client.post("/api/projects", json={"name": "FailThenFix"}).json()
+    corpus = upload(client, project["id"], "c.csv", csv_rows(5)).json()
+    construct = client.get("/api/constructs").json()[0]
+
+    # Force a failure: point the job at a column that exists in the DB row but
+    # sabotage the stored file? Simpler: monkeypatch the engine to raise once.
+    from app import jobs as jobs_module
+
+    original = jobs_module.run_ccr
+    calls = {"n": 0}
+
+    def flaky(*args, **kwargs):
+        calls["n"] += 1
+        if calls["n"] == 1:
+            raise RuntimeError("synthetic failure for admin requeue test")
+        return original(*args, **kwargs)
+
+    monkeypatch.setattr(jobs_module, "run_ccr", flaky)
+
+    job = run_job(client, project["id"], corpus["id"], construct["id"]).json()
+    assert wait_for_job(client, job["id"])["status"] == "failed"
+
+    failed = client.get("/api/admin/jobs/failed").json()
+    entry = next(f for f in failed if f["id"] == job["id"])
+    assert entry["corpus_file_available"] is True
+    assert "synthetic failure" in entry["error_tail"]
+
+    assert client.post(f"/api/admin/jobs/{job['id']}/requeue").status_code == 200
+    assert wait_for_job(client, job["id"])["status"] == "completed"
+
+
+# ------------------------------------------------------------ verification
+def test_verification_queue_marks_verified(client):
+    sign_in_as(client, ADMIN_EMAIL, "Admin")
+    queue = client.get("/api/admin/constructs?status=needs_verification").json()
+    assert len(queue) > 0
+    target = queue[0]
+
+    resp = client.post(
+        f"/api/admin/constructs/{target['id']}/verification", json={"status": "verified"}
+    )
+    assert resp.status_code == 200 and resp.json()["verification_status"] == "verified"
+
+    remaining = client.get("/api/admin/constructs?status=needs_verification").json()
+    assert all(c["id"] != target["id"] for c in remaining)
+    # 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"

backend/tests/test_guide_and_samples.py

@@ -1,38 +0,0 @@
-"""Tester-facing extras: the /guide page and the /samples demo-data mount.
-
-Both exist for the hosted dev instance so the PI/students can test without
-being handed files out of band. They are static content, but regressions here
-(a renamed sample file, a moved directory) would silently break the guide's
-download links, so pin the contract.
-"""
-
-import re
-from pathlib import Path
-
-from fastapi.testclient import TestClient
-
-from app.main import SAMPLES_DIR, app
-
-client = TestClient(app)
-
-
-def test_guide_serves_html():
-    r = client.get("/guide")
-    assert r.status_code == 200
-    assert "text/html" in r.headers["content-type"]
-    assert "Testing Guide" in r.text
-
-
-def test_samples_mount_serves_files():
-    r = client.get("/samples/sample_corpus.csv")
-    assert r.status_code == 200
-    assert r.text.splitlines()[0].startswith("id,")
-
-
-def test_every_sample_link_in_guide_resolves():
-    """Every /samples/<file> href in guide.html must exist in sample_data/."""
-    html = (Path(__file__).resolve().parents[1] / "app" / "guide.html").read_text()
-    linked = set(re.findall(r'href="/samples/([^"]+)"', html))
-    assert linked, "guide.html should link to sample files"
-    missing = sorted(f for f in linked if not (SAMPLES_DIR / f).exists())
-    assert not missing, f"guide links to samples that do not exist: {missing}"

frontend/src/AdminPage.jsx

@@ -0,0 +1,255 @@
+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.
+
+async function adminFetch(path, options = {}) {
+  const resp = await fetch(path, options);
+  if (!resp.ok) {
+    let detail = resp.statusText;
+    try {
+      detail = (await resp.json()).detail || detail;
+    } catch { /* non-JSON */ }
+    throw new Error(detail);
+  }
+  return resp.status === 204 ? null : resp.json();
+}
+
+const post = (path, body) =>
+  adminFetch(path, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body || {}),
+  });
+
+export default function AdminPage({ auth }) {
+  const [overview, setOverview] = useState(null);
+  const [users, setUsers] = useState([]);
+  const [failed, setFailed] = useState([]);
+  const [constructs, setConstructs] = useState([]);
+  const [onlyUnverified, setOnlyUnverified] = useState(true);
+  const [error, setError] = useState("");
+  const [notice, setNotice] = useState("");
+
+  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/constructs" + (onlyUnverified ? "?status=needs_verification" : "")
+    ).then(setConstructs).catch(() => {});
+  }, [onlyUnverified]);
+
+  useEffect(() => { reload(); }, [reload]);
+
+  if (!auth?.signed_in || !auth?.is_admin) {
+    return (
+      <div className="card">
+        <h3>Admin</h3>
+        <p className="hint">
+          This page requires an admin account.{" "}
+          <a href="/">Back to the platform</a>.
+        </p>
+      </div>
+    );
+  }
+
+  async function act(fn) {
+    setError("");
+    setNotice("");
+    try {
+      await fn();
+      reload();
+    } catch (e) {
+      setError(e.message);
+    }
+  }
+
+  return (
+    <>
+      {error && <div className="error-banner" onClick={() => setError("")}>{error}</div>}
+      {notice && (
+        <div className="card" style={{ borderColor: "var(--maroon)" }}>
+          <p><b>{notice}</b> (shown once - copy it now)</p>
+        </div>
+      )}
+
+      <div className="project-header">
+        <span className="project-title">Admin</span>
+        <a className="ghost header-btn" href="/">Back to platform</a>
+      </div>
+
+      {/* Overview */}
+      <div className="card">
+        <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>{" "}
+            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) ·{" "}
+            <b>{overview.constructs_unverified}</b> library scales awaiting verification
+          </p>
+        ) : (
+          <p className="hint">Loading…</p>
+        )}
+      </div>
+
+      {/* Users */}
+      <div className="card">
+        <h3>Users</h3>
+        <div className="table-wrap">
+          <table className="docs">
+            <thead>
+              <tr><th>Email</th><th>Name</th><th>Role</th><th>Saved runs</th><th>Sign-in</th><th /></tr>
+            </thead>
+            <tbody>
+              {users.map((u) => (
+                <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",
+                        }))
+                      }
+                    >
+                      {u.role === "lab" ? "Make member" : "Make lab (unlimited)"}
+                    </button>{" "}
+                    <button
+                      className="linkish"
+                      onClick={() =>
+                        act(async () => {
+                          const r = await post(`/api/admin/users/${u.id}/reset-password`);
+                          setNotice(`Temporary password for ${r.email}: ${r.temporary_password}`);
+                        })
+                      }
+                    >
+                      Reset password
+                    </button>{" "}
+                    {!u.is_admin && (
+                      <button
+                        className="linkish danger"
+                        onClick={() => {
+                          if (window.confirm(`Delete ${u.email} and ALL their data?`)) {
+                            act(() => adminFetch(`/api/admin/users/${u.id}`, { method: "DELETE" }));
+                          }
+                        }}
+                      >
+                        Delete
+                      </button>
+                    )}
+                  </td>
+                </tr>
+              ))}
+              {users.length === 0 && (
+                <tr><td colSpan={6} className="muted">No accounts yet.</td></tr>
+              )}
+            </tbody>
+          </table>
+        </div>
+      </div>
+
+      {/* Failed runs */}
+      <div className="card">
+        <h3>Failed runs</h3>
+        {failed.length === 0 ? (
+          <p className="hint">None. 🎉</p>
+        ) : (
+          <div className="table-wrap">
+            <table className="docs">
+              <thead>
+                <tr><th>When</th><th>Corpus</th><th>Model</th><th>Error</th><th /></tr>
+              </thead>
+              <tbody>
+                {failed.map((j) => (
+                  <tr key={j.id}>
+                    <td className="muted">{j.created_at.replace("T", " ").slice(0, 16)}</td>
+                    <td>{j.corpus_filename}</td>
+                    <td className="muted small">{j.model_name}</td>
+                    <td className="small" title={j.error_tail}>{j.error_tail.slice(0, 90)}</td>
+                    <td>
+                      {j.corpus_file_available ? (
+                        <button
+                          className="linkish"
+                          onClick={() => act(() => post(`/api/admin/jobs/${j.id}/requeue`))}
+                        >
+                          Requeue
+                        </button>
+                      ) : (
+                        <span className="muted small">file expired</span>
+                      )}
+                    </td>
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+          </div>
+        )}
+      </div>
+
+      {/* Verification queue */}
+      <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.
+          {" "}
+          <button className="linkish" onClick={() => setOnlyUnverified((v) => !v)}>
+            {onlyUnverified ? "Show all" : "Show unverified only"}
+          </button>
+        </p>
+        <div className="table-wrap">
+          <table className="docs">
+            <thead>
+              <tr><th>Scale</th><th>Category</th><th>Items</th><th>Status</th><th /></tr>
+            </thead>
+            <tbody>
+              {constructs.map((c) => (
+                <tr key={c.id}>
+                  <td title={c.reference}>{c.name}</td>
+                  <td className="muted small">{c.category}</td>
+                  <td>{c.n_items}</td>
+                  <td>
+                    <span className={`pill ${c.verification_status === "verified" ? "completed" : "queued"}`}>
+                      {c.verification_status.replace("_", " ")}
+                    </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>
+                  </td>
+                </tr>
+              ))}
+              {constructs.length === 0 && (
+                <tr><td colSpan={5} className="muted">Nothing awaiting verification. 🎉</td></tr>
+              )}
+            </tbody>
+          </table>
+        </div>
+      </div>
+    </>
+  );
+}

frontend/src/App.jsx

@@ -1,7 +1,10 @@
 import { useEffect, useState } from "react";
 import { api } from "./api.js";
+import AdminPage from "./AdminPage.jsx";
 import Workspace from "./Workspace.jsx";
 
+const IS_ADMIN_PATH = window.location.pathname === "/admin";
+
 function relativeTime(iso) {
   if (!iso) return "";
   const then = new Date(iso.endsWith("Z") || iso.includes("+") ? iso : iso + "Z");
@@ -141,6 +144,9 @@ export default function App() {
           {auth?.signed_in ? (
             <>
               <span className="small">Hi, {auth.name}</span>
+              {auth.is_admin && !IS_ADMIN_PATH && (
+                <a className="header-btn" href="/admin">Admin</a>
+              )}
               <button className="header-btn" onClick={handleLogout}>
                 Sign out
               </button>
@@ -251,6 +257,11 @@ export default function App() {
         </div>
       )}
 
+      {IS_ADMIN_PATH ? (
+        <main className="main" style={{ maxWidth: 1100, margin: "0 auto", padding: "0 1rem" }}>
+          <AdminPage auth={auth} />
+        </main>
+      ) : (
       <div className="layout">
         <aside className="sidebar">
           <h2>
@@ -351,6 +362,7 @@ export default function App() {
           )}
         </main>
       </div>
+      )}
     </div>
   );
 }