Switch storage to Hugging Face Dataset; add /admin review console

README.md

@@ -1,14 +1,11 @@
 # Clinical Trial AI Reproduction Benchmark — Intake
 
-A Next.js + Tailwind single-page intake form. Statisticians enter:
+A Next.js + Tailwind intake form for trial statisticians. Submissions are saved to a **Hugging Face Dataset** repo. An `/admin` page lets reviewers triage submissions (pending / reviewed / needs_fix).
 
-- `trial_id`, `username`
-- A list of questions, each with `design_element`, `question_type` (`extraction_only` / `derivation_required`), and an Evaluation block (`artifact`, `dimension`, `points`, `criterion`, `tolerance`).
+## What it does
 
-Buttons:
-
-- **Save draft** — persists current form to `localStorage`.
-- **Submit** — opens a GitHub issue and commits the raw JSON file to the repo.
+- **Public form (`/`)** — statisticians enter `trial_id`, `username`, and a list of questions. Each question has `design_element` (dropdown), `question_type` (dropdown), and an auto-generated rubric block. Buttons: **Save draft** (localStorage), **Submit** (writes to HF Dataset).
+- **Admin (`/admin`)** — password-gated review console. Lists every submission with its current status, lets you change status, add a reviewer name + note. Updates are committed back to the dataset.
 
 ## Run locally
 
@@ -18,73 +15,99 @@ npm run dev
 # open http://localhost:3000
 ```
 
-Without GitHub env vars set, submissions fall back to `./data/submissions/<trial_id>__<username>__<timestamp>/prompts.json` on disk.
-
-## Deploy on Vercel + store submissions on GitHub
-
-### 1. Create a private submissions repo
+Without HF env vars set, submissions land in `./data/submissions/<...>.json` on disk — fine for dev.
 
-Create an empty repo, e.g. `ttt-77/tdb-intake-submissions`. Every submission will:
+## Deploy on Vercel + store on Hugging Face
 
-- open a new **issue** there (Markdown summary + raw JSON in a fenced block).
-- commit the raw JSON file to `submissions/<trial_id>__<username>__<timestamp>.json` in the same repo.
+### 1. Create a private HF Dataset repo
 
-### 2. Make a fine-grained PAT
+- Sign in at <https://huggingface.co>
+- Click your avatar → **New Dataset**
+- Owner: your username (e.g. `ttt-77`)
+- Name: e.g. `tdb-intake-submissions`
+- Visibility: **Private**
+- Create. Leave it empty — files will appear as submissions arrive.
 
-GitHub → Settings → Developer settings → **Fine-grained tokens** → Generate new token.
+### 2. Generate an HF access token
 
-- **Repository access:** only the submissions repo.
-- **Permissions → Repository:**
-  - **Contents:** Read and write (for the file commit).
-  - **Issues:** Read and write (for the issue).
-
-Save the token — you'll paste it into Vercel next.
+- <https://huggingface.co/settings/tokens> → **New token**
+- Type: **Write**
+- Save the `hf_...` string.
 
 ### 3. Push this repo to GitHub and import on Vercel
 
 ```bash
-git add . && git commit -m "Initial intake form"
-git push -u origin main
+git push
 ```
 
 Then go to <https://vercel.com>, import the repo (auto-detects Next.js).
 
 ### 4. Add env vars in Vercel
 
-Project → Settings → Environment Variables (set for Production + Preview):
+Project → Settings → Environment Variables (set for Production + Preview + Development):
 
-| Name | Value |
-| --- | --- |
-| `GITHUB_TOKEN` | the fine-grained PAT from step 2 |
-| `GITHUB_OWNER` | repo owner, e.g. `ttt-77` |
-| `GITHUB_REPO` | repo name, e.g. `tdb-intake-submissions` |
+| Name | Value | Required |
+| --- | --- | --- |
+| `HF_TOKEN` | the token from step 2 | ✅ |
+| `HF_DATASET_REPO` | `ttt-77/tdb-intake-submissions` | ✅ |
+| `HF_DATASET_BRANCH` | `main` (default) | optional |
+| `ADMIN_PASSWORD` | a password you'll give to reviewers | ✅ for `/admin` |
 
 Redeploy after saving.
 
 ### 5. Test
 
-Fill the form on the deployed URL → **Submit**. In your submissions repo you should see:
+- Open the deployed URL, fill the form, **Submit**. A new file appears in the HF dataset at `submissions/<trial_id>__<username>__<timestamp>.json`.
+- Open `/admin`, enter the password, you'll see the new submission with status `pending`. Click to expand, set reviewer/note, change status — every change becomes a commit on the dataset.
+
+## Submission record shape
+
+Each `submissions/*.json` file looks like:
+
+```json
+{
+  "submissionId": "submissions/NCT0001__jdoe__2026-06-01T...Z.json",
+  "submittedAt": "2026-06-01T...Z",
+  "trial_id": "NCT0001",
+  "username": "jdoe",
+  "status": "pending",
+  "reviewer": "",
+  "reviewerNote": "",
+  "reviewedAt": "...",
+  "comparison": { ... full form payload ... }
+}
+```
 
-- A new file at `submissions/<trial_id>__<username>__<timestamp>.json`.
-- A new issue titled `[Intake] <trial_id> — <username>`, labeled `intake-submission`, linking to that file.
+Load all submissions in Python:
 
-The UI shows links to both right after submit.
+```python
+from huggingface_hub import HfApi
+api = HfApi()
+# Either clone the dataset:
+#   from huggingface_hub import snapshot_download
+#   snapshot_download("ttt-77/tdb-intake-submissions", repo_type="dataset")
+# Or list the files via API and read each.
+```
 
 ## Privacy notes
 
-- The submissions repo should be **private**.
-- `GITHUB_TOKEN` lives only in Vercel env vars — never commit it.
-- Rotate the PAT periodically; update the env var and redeploy.
+- The dataset repo should be **private**.
+- `HF_TOKEN` lives only in Vercel env vars — never commit it.
+- Rotate the token periodically; update the env var and redeploy.
+- `ADMIN_PASSWORD` is a shared secret — anyone with it can change submission statuses.
 
 ## Project structure
 
 ```text
 app/
-  layout.tsx, page.tsx, globals.css
-  api/submit/route.ts  POST — commits JSON file + opens issue (or writes locally)
+  layout.tsx, page.tsx, globals.css      — public form
+  admin/page.tsx                         — review console
+  api/submit/route.ts                    POST — create submission
+  api/submissions/route.ts               GET  — list submissions (admin)
+  api/submissions/[...path]/route.ts     GET, PATCH — one submission (admin)
 components/
   StepCompare.tsx
 lib/
   types.ts, storage.ts
-data/submissions/      — created at runtime in dev (local fallback only)
+data/submissions/                        — created at runtime in dev only
 ```

app/admin/page.tsx

@@ -0,0 +1,288 @@
+"use client";
+import { useCallback, useEffect, useMemo, useState } from "react";
+
+type Status = "pending" | "reviewed" | "needs_fix";
+
+type Summary = {
+  submissionId: string;
+  trial_id: string;
+  username: string;
+  submittedAt: string;
+  status: Status;
+  reviewedAt?: string;
+};
+
+type Detail = Summary & {
+  reviewer?: string;
+  reviewerNote?: string;
+  comparison: unknown;
+};
+
+const statusColor = (s: Status) =>
+  s === "reviewed"
+    ? "bg-emerald-100 text-emerald-800 border-emerald-200"
+    : s === "needs_fix"
+    ? "bg-rose-100 text-rose-800 border-rose-200"
+    : "bg-amber-100 text-amber-800 border-amber-200";
+
+const PW_KEY = "admin-pw";
+
+export default function AdminPage() {
+  const [pw, setPw] = useState("");
+  const [authed, setAuthed] = useState(false);
+  const [items, setItems] = useState<Summary[]>([]);
+  const [filter, setFilter] = useState<"all" | Status>("all");
+  const [openId, setOpenId] = useState<string | null>(null);
+  const [detail, setDetail] = useState<Detail | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [reviewer, setReviewer] = useState("");
+  const [reviewerNote, setReviewerNote] = useState("");
+
+  useEffect(() => {
+    const stored = sessionStorage.getItem(PW_KEY) || "";
+    if (stored) {
+      setPw(stored);
+      setAuthed(true);
+    }
+  }, []);
+
+  const headers = useMemo(
+    () => ({ "Content-Type": "application/json", "x-admin-password": pw }),
+    [pw],
+  );
+
+  const refresh = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+    try {
+      const res = await fetch("/api/submissions", { headers });
+      if (res.status === 401) {
+        setAuthed(false);
+        sessionStorage.removeItem(PW_KEY);
+        throw new Error("Wrong password.");
+      }
+      const json = await res.json();
+      if (!json.ok) throw new Error(json.error || "List failed");
+      setItems(json.items);
+    } catch (e: any) {
+      setError(e?.message || "List failed");
+    } finally {
+      setLoading(false);
+    }
+  }, [headers]);
+
+  useEffect(() => {
+    if (authed) refresh();
+  }, [authed, refresh]);
+
+  const openDetail = async (id: string) => {
+    if (openId === id) {
+      setOpenId(null);
+      setDetail(null);
+      return;
+    }
+    setOpenId(id);
+    setDetail(null);
+    setError(null);
+    try {
+      const res = await fetch(`/api/${id}`, { headers });
+      const json = await res.json();
+      if (!json.ok) throw new Error(json.error || "Fetch failed");
+      setDetail(json.record);
+      setReviewer(json.record.reviewer || "");
+      setReviewerNote(json.record.reviewerNote || "");
+    } catch (e: any) {
+      setError(e?.message || "Fetch failed");
+    }
+  };
+
+  const setStatus = async (id: string, status: Status) => {
+    setError(null);
+    try {
+      const res = await fetch(`/api/${id}`, {
+        method: "PATCH",
+        headers,
+        body: JSON.stringify({ status, reviewer, reviewerNote }),
+      });
+      const json = await res.json();
+      if (!json.ok) throw new Error(json.error || "Update failed");
+      setDetail(json.record);
+      setItems((prev) =>
+        prev.map((p) =>
+          p.submissionId === id ? { ...p, status, reviewedAt: json.record.reviewedAt } : p,
+        ),
+      );
+    } catch (e: any) {
+      setError(e?.message || "Update failed");
+    }
+  };
+
+  const filtered = filter === "all" ? items : items.filter((i) => i.status === filter);
+
+  if (!authed) {
+    return (
+      <div className="card max-w-sm mx-auto space-y-3">
+        <h2 className="text-base font-semibold">Admin login</h2>
+        <input
+          type="password"
+          className="input"
+          placeholder="Admin password"
+          value={pw}
+          onChange={(e) => setPw(e.target.value)}
+          onKeyDown={(e) => {
+            if (e.key === "Enter") {
+              sessionStorage.setItem(PW_KEY, pw);
+              setAuthed(true);
+            }
+          }}
+        />
+        <button
+          className="btn-primary w-full"
+          onClick={() => {
+            sessionStorage.setItem(PW_KEY, pw);
+            setAuthed(true);
+          }}
+        >
+          Continue
+        </button>
+        {error && (
+          <div className="text-xs text-rose-700">{error}</div>
+        )}
+        <p className="text-xs text-slate-500">
+          If <code>ADMIN_PASSWORD</code> is unset on the server, any value (including empty) is accepted.
+        </p>
+      </div>
+    );
+  }
+
+  return (
+    <div className="space-y-4">
+      <div className="flex items-center justify-between flex-wrap gap-2">
+        <h2 className="text-base font-semibold">Submissions ({items.length})</h2>
+        <div className="flex items-center gap-2 flex-wrap">
+          {(["all", "pending", "reviewed", "needs_fix"] as const).map((s) => (
+            <button
+              key={s}
+              onClick={() => setFilter(s)}
+              className={
+                "px-2.5 py-1 rounded text-xs border " +
+                (filter === s
+                  ? "bg-slate-900 text-white border-slate-900"
+                  : "bg-white text-slate-700 border-slate-300 hover:bg-slate-100")
+              }
+            >
+              {s}
+            </button>
+          ))}
+          <button className="btn-secondary !py-1 !text-xs" onClick={refresh} disabled={loading}>
+            {loading ? "Refreshing…" : "Refresh"}
+          </button>
+        </div>
+      </div>
+
+      {error && (
+        <div className="rounded-md bg-rose-50 border border-rose-200 px-3 py-2 text-xs text-rose-900">
+          {error}
+        </div>
+      )}
+
+      {filtered.length === 0 && !loading && (
+        <div className="text-sm text-slate-500">No submissions match this filter.</div>
+      )}
+
+      <ul className="space-y-2">
+        {filtered.map((it) => {
+          const isOpen = openId === it.submissionId;
+          return (
+            <li key={it.submissionId} className="card !p-0 overflow-hidden">
+              <button
+                className="w-full flex items-center justify-between gap-3 p-3 text-left hover:bg-slate-50"
+                onClick={() => openDetail(it.submissionId)}
+              >
+                <div className="flex items-center gap-3 min-w-0">
+                  <span
+                    className={
+                      "px-2 py-0.5 rounded text-xs border font-medium " + statusColor(it.status)
+                    }
+                  >
+                    {it.status}
+                  </span>
+                  <div className="truncate">
+                    <div className="text-sm font-medium truncate">
+                      {it.trial_id}{" "}
+                      <span className="text-slate-500 font-normal">— {it.username}</span>
+                    </div>
+                    <div className="text-xs text-slate-500 truncate">
+                      {it.submittedAt}
+                    </div>
+                  </div>
+                </div>
+                <span className="text-xs text-slate-400">{isOpen ? "▲" : "▼"}</span>
+              </button>
+
+              {isOpen && (
+                <div className="border-t border-slate-200 p-4 bg-slate-50 space-y-3">
+                  {!detail && <div className="text-xs text-slate-500">Loading…</div>}
+                  {detail && (
+                    <>
+                      <div className="grid grid-cols-1 md:grid-cols-2 gap-3">
+                        <div>
+                          <label className="label">Reviewer</label>
+                          <input
+                            className="input"
+                            value={reviewer}
+                            onChange={(e) => setReviewer(e.target.value)}
+                            placeholder="your name"
+                          />
+                        </div>
+                        <div>
+                          <label className="label">Reviewer note</label>
+                          <input
+                            className="input"
+                            value={reviewerNote}
+                            onChange={(e) => setReviewerNote(e.target.value)}
+                          />
+                        </div>
+                      </div>
+                      <div className="flex items-center gap-2 flex-wrap">
+                        <span className="text-xs text-slate-500 mr-1">Set status:</span>
+                        {(["pending", "reviewed", "needs_fix"] as const).map((s) => (
+                          <button
+                            key={s}
+                            className={
+                              "px-2.5 py-1 rounded text-xs border " +
+                              (detail.status === s
+                                ? statusColor(s)
+                                : "bg-white text-slate-700 border-slate-300 hover:bg-slate-100")
+                            }
+                            onClick={() => setStatus(it.submissionId, s)}
+                          >
+                            {s}
+                          </button>
+                        ))}
+                        {detail.reviewedAt && (
+                          <span className="text-xs text-slate-500 ml-2">
+                            last updated {detail.reviewedAt}
+                          </span>
+                        )}
+                      </div>
+                      <details className="text-xs">
+                        <summary className="cursor-pointer text-slate-600">
+                          Raw submission JSON
+                        </summary>
+                        <pre className="mt-2 p-3 rounded bg-white border border-slate-200 overflow-x-auto text-[11px]">
+                          {JSON.stringify(detail, null, 2)}
+                        </pre>
+                      </details>
+                    </>
+                  )}
+                </div>
+              )}
+            </li>
+          );
+        })}
+      </ul>
+    </div>
+  );
+}

app/api/submissions/[...path]/route.ts

@@ -0,0 +1,64 @@
+import { NextResponse } from "next/server";
+import {
+  SubmissionStatus,
+  getSubmission,
+  isAdminAuthorized,
+  updateSubmission,
+} from "@/lib/storage";
+
+const VALID_STATUSES: SubmissionStatus[] = ["pending", "reviewed", "needs_fix"];
+
+function buildId(params: { path: string[] }): string {
+  // The catch-all route gives us segments like ["submissions","foo.json"].
+  // We prepend "submissions/" only if it isn't already the first segment.
+  const parts = params.path;
+  return parts[0] === "submissions" ? parts.join("/") : `submissions/${parts.join("/")}`;
+}
+
+export async function GET(
+  req: Request,
+  { params }: { params: { path: string[] } },
+) {
+  if (!isAdminAuthorized(req)) {
+    return NextResponse.json({ ok: false, error: "unauthorized" }, { status: 401 });
+  }
+  const id = buildId(params);
+  const record = await getSubmission(id);
+  if (!record) {
+    return NextResponse.json({ ok: false, error: "not found" }, { status: 404 });
+  }
+  return NextResponse.json({ ok: true, record });
+}
+
+export async function PATCH(
+  req: Request,
+  { params }: { params: { path: string[] } },
+) {
+  if (!isAdminAuthorized(req)) {
+    return NextResponse.json({ ok: false, error: "unauthorized" }, { status: 401 });
+  }
+  const id = buildId(params);
+  const body = await req.json().catch(() => ({}));
+  const patch: { status?: SubmissionStatus; reviewer?: string; reviewerNote?: string } = {};
+  if (body.status) {
+    if (!VALID_STATUSES.includes(body.status)) {
+      return NextResponse.json({ ok: false, error: "invalid status" }, { status: 400 });
+    }
+    patch.status = body.status;
+  }
+  if (typeof body.reviewer === "string") patch.reviewer = body.reviewer;
+  if (typeof body.reviewerNote === "string") patch.reviewerNote = body.reviewerNote;
+
+  try {
+    const updated = await updateSubmission(id, patch);
+    if (!updated) {
+      return NextResponse.json({ ok: false, error: "not found" }, { status: 404 });
+    }
+    return NextResponse.json({ ok: true, record: updated });
+  } catch (e: any) {
+    return NextResponse.json(
+      { ok: false, error: e?.message || "Update failed" },
+      { status: 500 },
+    );
+  }
+}

app/api/submissions/route.ts

@@ -0,0 +1,18 @@
+import { NextResponse } from "next/server";
+import { isAdminAuthorized, listSubmissions } from "@/lib/storage";
+
+export async function GET(req: Request) {
+  if (!isAdminAuthorized(req)) {
+    return NextResponse.json({ ok: false, error: "unauthorized" }, { status: 401 });
+  }
+  try {
+    const items = await listSubmissions();
+    items.sort((a, b) => (a.submittedAt < b.submittedAt ? 1 : -1));
+    return NextResponse.json({ ok: true, items });
+  } catch (e: any) {
+    return NextResponse.json(
+      { ok: false, error: e?.message || "List failed" },
+      { status: 500 },
+    );
+  }
+}

app/layout.tsx

@@ -12,9 +12,14 @@ export default function RootLayout({ children }: { children: React.ReactNode })
       <body>
         <div className="min-h-screen">
           <header className="border-b border-slate-200 bg-white">
-            <div className="mx-auto max-w-4xl px-6 py-4">
-              <h1 className="text-lg font-semibold">Clinical Trial AI Reproduction Benchmark</h1>
-              <p className="text-xs text-slate-500">Statistician intake & evaluation form</p>
+            <div className="mx-auto max-w-4xl px-6 py-4 flex items-center justify-between">
+              <div>
+                <h1 className="text-lg font-semibold">Clinical Trial AI Reproduction Benchmark</h1>
+                <p className="text-xs text-slate-500">Statistician intake & evaluation form</p>
+              </div>
+              <a href="/admin" className="text-xs text-slate-500 hover:text-slate-900 underline">
+                Admin
+              </a>
             </div>
           </header>
           <main className="mx-auto max-w-4xl px-6 py-8">{children}</main>

lib/storage.ts

@@ -1,42 +1,40 @@
-// Storage backend: GitHub Issues (production) or local filesystem (dev fallback).
+// Storage backend: Hugging Face Dataset repo (production) or local filesystem (dev).
 //
-// In production set the following env vars (Vercel → Project → Settings → Environment Variables):
-//   GITHUB_TOKEN  — fine-grained PAT with Issues: read/write on the submissions repo
-//   GITHUB_OWNER  — repo owner (e.g. ttt-77)
-//   GITHUB_REPO   — repo name (e.g. tdb-intake-submissions)
+// In production set these env vars in Vercel:
+//   HF_TOKEN              — HF user access token with "Write" permission on the dataset repo
+//   HF_DATASET_REPO       — e.g. "ttt-77/tdb-intake-submissions"
+//   HF_DATASET_BRANCH     — optional, defaults to "main"
 //
-// If any of those are missing, writes go to ./data/submissions/<id>/*.json on disk.
+// If HF_TOKEN or HF_DATASET_REPO is missing, the code falls back to ./data/submissions/*.json
+// on disk so local development still works without HF credentials.
 
 import { promises as fs } from "fs";
 import path from "path";
 
-const token = process.env.GITHUB_TOKEN;
-const owner = process.env.GITHUB_OWNER;
-const repo = process.env.GITHUB_REPO;
-export const githubConfigured = !!(token && owner && repo);
+const HF_BASE = "https://huggingface.co";
+const HF_TOKEN = process.env.HF_TOKEN;
+const HF_DATASET = process.env.HF_DATASET_REPO;
+const HF_BRANCH = process.env.HF_DATASET_BRANCH || "main";
+
+export const hfConfigured = !!(HF_TOKEN && HF_DATASET);
 
 const safe = (s: string) => (s || "").trim().replace(/[^a-zA-Z0-9-_]/g, "_");
 
-async function gh<T = any>(pathname: string, init?: RequestInit): Promise<T> {
-  const res = await fetch(`https://api.github.com${pathname}`, {
-    ...init,
-    cache: "no-store",
-    headers: {
-      Accept: "application/vnd.github+json",
-      Authorization: `Bearer ${token}`,
-      "X-GitHub-Api-Version": "2022-11-28",
-      "Content-Type": "application/json",
-      ...(init?.headers || {}),
-    },
-  });
-  if (!res.ok) {
-    const text = await res.text();
-    throw new Error(`GitHub ${res.status}: ${text}`);
-  }
-  return res.json();
-}
+// ---- Types ----------------------------------------------------------------
 
-// ---- Submissions ----------------------------------------------------------
+export type SubmissionStatus = "pending" | "reviewed" | "needs_fix";
+
+export type SubmissionRecord = {
+  submissionId: string;        // == path inside the dataset repo, e.g. "submissions/foo.json"
+  submittedAt: string;
+  trial_id: string;
+  username: string;
+  status: SubmissionStatus;
+  reviewedAt?: string;
+  reviewer?: string;
+  reviewerNote?: string;
+  comparison: unknown;
+};
 
 export type CreateSubmissionInput = {
   trial_id: string;
@@ -45,95 +43,215 @@ export type CreateSubmissionInput = {
   comparison: unknown;
 };
 
-export type CreateSubmissionResult = { submissionId: string; url?: string };
+export type CreateSubmissionResult = {
+  submissionId: string;
+  url?: string;
+};
+
+export type SubmissionSummary = {
+  submissionId: string;
+  trial_id: string;
+  username: string;
+  submittedAt: string;
+  status: SubmissionStatus;
+  reviewedAt?: string;
+};
+
+// ---- HF helpers -----------------------------------------------------------
+
+async function hfCommit(
+  filePath: string,
+  contentBase64: string,
+  summary: string,
+): Promise<void> {
+  // HF commit API takes NDJSON: a header line, then one file line per upload.
+  const url = `${HF_BASE}/api/datasets/${HF_DATASET}/commit/${HF_BRANCH}`;
+  const body =
+    JSON.stringify({ key: "header", value: { summary, description: "" } }) +
+    "\n" +
+    JSON.stringify({
+      key: "file",
+      value: { path: filePath, encoding: "base64", content: contentBase64 },
+    }) +
+    "\n";
+  const res = await fetch(url, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${HF_TOKEN}`,
+      "Content-Type": "application/x-ndjson",
+    },
+    body,
+  });
+  if (!res.ok) {
+    throw new Error(`HF commit failed (${res.status}): ${await res.text()}`);
+  }
+}
+
+async function hfReadFile(filePath: string): Promise<string | null> {
+  const url = `${HF_BASE}/datasets/${HF_DATASET}/resolve/${HF_BRANCH}/${filePath}`;
+  const res = await fetch(url, {
+    headers: { Authorization: `Bearer ${HF_TOKEN}` },
+    cache: "no-store",
+  });
+  if (!res.ok) return null;
+  return res.text();
+}
+
+async function hfListSubmissions(): Promise<string[]> {
+  const url = `${HF_BASE}/api/datasets/${HF_DATASET}/tree/${HF_BRANCH}/submissions`;
+  const res = await fetch(url, {
+    headers: { Authorization: `Bearer ${HF_TOKEN}` },
+    cache: "no-store",
+  });
+  if (res.status === 404) return [];
+  if (!res.ok) {
+    throw new Error(`HF tree failed (${res.status}): ${await res.text()}`);
+  }
+  const items = (await res.json()) as Array<{ path: string; type: string }>;
+  return items
+    .filter((i) => i.type === "file" && i.path.endsWith(".json"))
+    .map((i) => i.path);
+}
+
+// ---- Public API -----------------------------------------------------------
 
 export async function createSubmission(
   input: CreateSubmissionInput,
-): Promise<CreateSubmissionResult & { fileUrl?: string }> {
-  if (githubConfigured) {
-    // 1. Commit the raw submission JSON to the repo.
-    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
-    const baseName = `${safe(input.trial_id)}__${safe(input.username)}__${stamp}`;
-    const filePath = `submissions/${baseName}.json`;
-    const fileContent = JSON.stringify(input, null, 2);
-    const commitMsg = `Add submission: ${input.trial_id} — ${input.username}`;
-    const fileRes = await gh<{ content: { html_url: string } }>(
-      `/repos/${owner}/${repo}/contents/${encodeURIComponent(filePath).replace(/%2F/g, "/")}`,
-      {
-        method: "PUT",
-        body: JSON.stringify({
-          message: commitMsg,
-          content: Buffer.from(fileContent, "utf-8").toString("base64"),
-        }),
-      },
-    );
+): Promise<CreateSubmissionResult> {
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const fileName = `${safe(input.trial_id)}__${safe(input.username)}__${stamp}.json`;
+  const submissionId = `submissions/${fileName}`;
 
-    // 2. Open an issue referencing the file.
-    const title = `[Intake] ${input.trial_id} — ${input.username}`;
-    const body = renderIssueBody(input, fileRes.content.html_url);
-    const issue = await gh<{ number: number; html_url: string }>(
-      `/repos/${owner}/${repo}/issues`,
-      {
-        method: "POST",
-        body: JSON.stringify({ title, body, labels: ["intake-submission"] }),
-      },
+  const record: SubmissionRecord = {
+    submissionId,
+    submittedAt: input.submittedAt,
+    trial_id: input.trial_id,
+    username: input.username,
+    status: "pending",
+    comparison: input.comparison,
+  };
+  const content = JSON.stringify(record, null, 2);
+
+  if (hfConfigured) {
+    await hfCommit(
+      submissionId,
+      Buffer.from(content, "utf-8").toString("base64"),
+      `Add submission: ${input.trial_id} — ${input.username}`,
     );
     return {
-      submissionId: String(issue.number),
-      url: issue.html_url,
-      fileUrl: fileRes.content.html_url,
+      submissionId,
+      url: `${HF_BASE}/datasets/${HF_DATASET}/blob/${HF_BRANCH}/${submissionId}`,
     };
   }
 
-  // local fs fallback
-  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
-  const submissionId = `${safe(input.trial_id)}__${safe(input.username)}__${stamp}`;
-  const dir = path.join(process.cwd(), "data", "submissions", submissionId);
+  const dir = path.join(process.cwd(), "data", "submissions");
   await fs.mkdir(dir, { recursive: true });
-  await fs.writeFile(
-    path.join(dir, "prompts.json"),
-    JSON.stringify({ ...input, submissionId }, null, 2),
-    "utf-8",
-  );
+  await fs.writeFile(path.join(dir, fileName), content, "utf-8");
   return { submissionId };
 }
 
-function renderIssueBody(input: CreateSubmissionInput, fileUrl?: string): string {
-  const c = input.comparison as { prompts?: any[] };
-  const rows = (c?.prompts ?? [])
-    .map(
-      (p: any) =>
-        `| \`${p.id}\` | ${escapeCell(p.design_element)} | ${escapeCell(p.question)} | \`${
-          p.question_type
-        }\` |`,
-    )
-    .join("\n");
-  const table =
-    rows.length > 0
-      ? `| id | design_element | question | question_type |\n|---|---|---|---|\n${rows}`
-      : "_No questions submitted._";
-
-  return [
-    `**Submitted:** ${input.submittedAt}`,
-    `**trial_id:** \`${input.trial_id}\``,
-    `**username:** \`${input.username}\``,
-    fileUrl ? `**Raw submission file:** ${fileUrl}` : "",
-    "",
-    "### Questions",
-    "",
-    table,
-    "",
-    "### Raw submission",
-    "",
-    "```json",
-    JSON.stringify(input, null, 2),
-    "```",
-  ]
-    .filter(Boolean)
-    .join("\n");
+export async function listSubmissions(): Promise<SubmissionSummary[]> {
+  if (hfConfigured) {
+    const paths = await hfListSubmissions();
+    const records = await Promise.all(
+      paths.map(async (p) => {
+        const text = await hfReadFile(p);
+        if (!text) return null;
+        try {
+          const r = JSON.parse(text) as SubmissionRecord;
+          return summarize(r);
+        } catch {
+          return null;
+        }
+      }),
+    );
+    return records.filter((x): x is SubmissionSummary => x !== null);
+  }
+
+  const dir = path.join(process.cwd(), "data", "submissions");
+  let files: string[] = [];
+  try {
+    files = await fs.readdir(dir);
+  } catch {
+    return [];
+  }
+  const records = await Promise.all(
+    files
+      .filter((f) => f.endsWith(".json"))
+      .map(async (f) => {
+        try {
+          const raw = await fs.readFile(path.join(dir, f), "utf-8");
+          return summarize(JSON.parse(raw));
+        } catch {
+          return null;
+        }
+      }),
+  );
+  return records.filter((x): x is SubmissionSummary => x !== null);
+}
+
+export async function getSubmission(submissionId: string): Promise<SubmissionRecord | null> {
+  if (!submissionId.startsWith("submissions/")) return null;
+  if (hfConfigured) {
+    const txt = await hfReadFile(submissionId);
+    if (!txt) return null;
+    try {
+      return JSON.parse(txt);
+    } catch {
+      return null;
+    }
+  }
+  const fullPath = path.join(process.cwd(), "data", submissionId);
+  try {
+    return JSON.parse(await fs.readFile(fullPath, "utf-8"));
+  } catch {
+    return null;
+  }
 }
 
-function escapeCell(s: string | undefined): string {
-  return (s || "").replace(/\|/g, "\\|").replace(/\n/g, " ");
+export async function updateSubmission(
+  submissionId: string,
+  patch: Partial<Pick<SubmissionRecord, "status" | "reviewer" | "reviewerNote">>,
+): Promise<SubmissionRecord | null> {
+  const existing = await getSubmission(submissionId);
+  if (!existing) return null;
+  const updated: SubmissionRecord = {
+    ...existing,
+    ...patch,
+    reviewedAt: patch.status ? new Date().toISOString() : existing.reviewedAt,
+  };
+  const content = JSON.stringify(updated, null, 2);
+
+  if (hfConfigured) {
+    await hfCommit(
+      submissionId,
+      Buffer.from(content, "utf-8").toString("base64"),
+      `Update: ${submissionId.split("/").pop()}`,
+    );
+    return updated;
+  }
+  const fullPath = path.join(process.cwd(), "data", submissionId);
+  await fs.writeFile(fullPath, content, "utf-8");
+  return updated;
+}
+
+function summarize(r: SubmissionRecord): SubmissionSummary {
+  return {
+    submissionId: r.submissionId,
+    trial_id: r.trial_id,
+    username: r.username,
+    submittedAt: r.submittedAt,
+    status: r.status ?? "pending",
+    reviewedAt: r.reviewedAt,
+  };
 }
 
+// ---- Admin gate (shared password) ----------------------------------------
+
+export const ADMIN_PASSWORD = process.env.ADMIN_PASSWORD || "";
+
+export function isAdminAuthorized(req: Request): boolean {
+  if (!ADMIN_PASSWORD) return true; // no password set = open (dev mode)
+  const header = req.headers.get("x-admin-password") || "";
+  return header === ADMIN_PASSWORD;
+}