Upload folder using huggingface_hub

AGENTS.md

@@ -192,6 +192,7 @@ For outer fingers the ROI is shrunk and rotation is centered on the proximal pha
 | `/m` | `templates/mobile.html` | v6 paginated six-step flow (intro → form → guide → capture → confirm → result). |
 | `/dev`, `/debug` | `templates/index.html` | Desktop with `dev_mode=True` (AI-explanation toggle visible). |
 | `/admin` | `templates/admin.html` | Token-gated KOL dashboard. |
+| `/feedback` | `templates/feedback.html` | v8 public post-shipment fit-feedback form (all UAs, no redirect). |
 
 `/api/measure` is the single contract both surfaces speak. Any algorithm change in `measure_finger.py` improves both surfaces with zero front-end work. See `doc/v5/` for the in-browser capture coach (distance + level gates) and `doc/v6/` for the mobile flow.
 
@@ -216,6 +217,68 @@ alter table public.measurements
   add column if not exists feedback_message text;
 ```
 
+### KOL identity field: email (the cross-table join key)
+
+Both web surfaces collect a single required identity field, now labelled
+**Email** (`type="email"`, `autocomplete="email"`, `inputmode="email"`,
+posted as `kol_email`). The server normalizes it **trim + lowercase**.
+Email — not name — is the key used to join `measurements` ↔ the v8
+`feedback` table ↔ the ops shipping-records CSV (names mis-merge and the
+shipping source is email-native). See `doc/v8/PRD.md`.
+
+Two columns on `measurements`:
+
+| Column | Notes |
+|---|---|
+| `kol_email` | `text`, normalized address; the join key for new rows. |
+| `kol_name` | `text`, **legacy only** — pre-email historical rows; NULL on new rows. |
+
+```sql
+alter table public.measurements add column if not exists kol_email text;
+```
+
+Stored object paths slug the **email local-part only** (`_email_local_part`
+in `web_demo/app.py`), never the full address, to keep PII out of bucket
+paths. Admin grouping/display and CSV export prefer `kol_email` and fall
+back to `kol_name` for legacy rows.
+
+### v8 post-shipment feedback (`/feedback` + `feedback` table)
+
+A **separate** flow from the post-result rating above — different
+lifecycle (5–7 days after the ring ships, not right after measurement)
+and a different table. Don't confuse the two:
+
+| | Post-result rating | v8 fit feedback |
+|---|---|---|
+| Route (POST) | `/api/feedback` | `/api/fit-feedback` |
+| Storage | columns on `measurements` (patched by `run_id`) | new `feedback` table (standalone row) |
+| Question | "did the website work?" | "which finger did the shipped ring fit?" |
+
+The `feedback` table is **intentionally decoupled** — no `run_id`, no
+foreign key. The only link to `measurements` is the normalized
+`kol_email`, joined at analysis time in a pandas notebook (see
+`doc/v8/analysis.md`). `GET /feedback` renders `templates/feedback.html`
+(single-page form, reuses `mobile.css`; **not** the `/m` step framework).
+`POST /api/fit-feedback` normalizes the email, uploads the optional photo
+under `feedback/` (local-part slug only, same PII stance), and inserts
+via `save_feedback`. The photo upload + insert are **synchronous** (no
+heavy compute, unlike `/api/measure`), so the row lands complete. RLS is
+enabled on the table (the app's service key bypasses it; this blocks
+anon-key reads of the email PII). The admin dashboard has a **Feedback**
+tab (`/api/admin/feedback` → `list_feedback`) that lists the rows
+read-only; deeper analysis is still pandas-only (`doc/v8/analysis.md`).
+Table columns:
+
+```sql
+create table public.feedback (
+  id uuid primary key default gen_random_uuid(),
+  submitted_at timestamptz not null default now(),
+  kol_email text not null,          -- normalized join key
+  received_size text, received_model text, best_fit_finger text,
+  fit_quality text, hand text, photo_url text, notes text
+);
+```
+
 ---
 
 ## Important Technical Details

CLAUDE.md

@@ -192,6 +192,7 @@ For outer fingers the ROI is shrunk and rotation is centered on the proximal pha
 | `/m` | `templates/mobile.html` | v6 paginated six-step flow (intro → form → guide → capture → confirm → result). |
 | `/dev`, `/debug` | `templates/index.html` | Desktop with `dev_mode=True` (AI-explanation toggle visible). |
 | `/admin` | `templates/admin.html` | Token-gated KOL dashboard. |
+| `/feedback` | `templates/feedback.html` | v8 public post-shipment fit-feedback form (all UAs, no redirect). |
 
 `/api/measure` is the single contract both surfaces speak. Any algorithm change in `measure_finger.py` improves both surfaces with zero front-end work. See `doc/v5/` for the in-browser capture coach (distance + level gates) and `doc/v6/` for the mobile flow.
 
@@ -216,6 +217,68 @@ alter table public.measurements
   add column if not exists feedback_message text;
 ```
 
+### KOL identity field: email (the cross-table join key)
+
+Both web surfaces collect a single required identity field, now labelled
+**Email** (`type="email"`, `autocomplete="email"`, `inputmode="email"`,
+posted as `kol_email`). The server normalizes it **trim + lowercase**.
+Email — not name — is the key used to join `measurements` ↔ the v8
+`feedback` table ↔ the ops shipping-records CSV (names mis-merge and the
+shipping source is email-native). See `doc/v8/PRD.md`.
+
+Two columns on `measurements`:
+
+| Column | Notes |
+|---|---|
+| `kol_email` | `text`, normalized address; the join key for new rows. |
+| `kol_name` | `text`, **legacy only** — pre-email historical rows; NULL on new rows. |
+
+```sql
+alter table public.measurements add column if not exists kol_email text;
+```
+
+Stored object paths slug the **email local-part only** (`_email_local_part`
+in `web_demo/app.py`), never the full address, to keep PII out of bucket
+paths. Admin grouping/display and CSV export prefer `kol_email` and fall
+back to `kol_name` for legacy rows.
+
+### v8 post-shipment feedback (`/feedback` + `feedback` table)
+
+A **separate** flow from the post-result rating above — different
+lifecycle (5–7 days after the ring ships, not right after measurement)
+and a different table. Don't confuse the two:
+
+| | Post-result rating | v8 fit feedback |
+|---|---|---|
+| Route (POST) | `/api/feedback` | `/api/fit-feedback` |
+| Storage | columns on `measurements` (patched by `run_id`) | new `feedback` table (standalone row) |
+| Question | "did the website work?" | "which finger did the shipped ring fit?" |
+
+The `feedback` table is **intentionally decoupled** — no `run_id`, no
+foreign key. The only link to `measurements` is the normalized
+`kol_email`, joined at analysis time in a pandas notebook (see
+`doc/v8/analysis.md`). `GET /feedback` renders `templates/feedback.html`
+(single-page form, reuses `mobile.css`; **not** the `/m` step framework).
+`POST /api/fit-feedback` normalizes the email, uploads the optional photo
+under `feedback/` (local-part slug only, same PII stance), and inserts
+via `save_feedback`. The photo upload + insert are **synchronous** (no
+heavy compute, unlike `/api/measure`), so the row lands complete. RLS is
+enabled on the table (the app's service key bypasses it; this blocks
+anon-key reads of the email PII). The admin dashboard has a **Feedback**
+tab (`/api/admin/feedback` → `list_feedback`) that lists the rows
+read-only; deeper analysis is still pandas-only (`doc/v8/analysis.md`).
+Table columns:
+
+```sql
+create table public.feedback (
+  id uuid primary key default gen_random_uuid(),
+  submitted_at timestamptz not null default now(),
+  kol_email text not null,          -- normalized join key
+  received_size text, received_model text, best_fit_finger text,
+  fit_quality text, hand text, photo_url text, notes text
+);
+```
+
 ---
 
 ## Important Technical Details

web_demo/app.py

@@ -36,11 +36,14 @@ from src.ai_recommendation import ai_explain_recommendation
 from web_demo.supabase_client import (
     upload_file,
     save_measurement,
+    save_feedback,
+    persistence_enabled,
     update_measurement_feedback,
     FEEDBACK_OK,
     FEEDBACK_NO_ROW,
     FEEDBACK_DISABLED,
     list_measurements,
+    list_feedback,
     list_measurements_for_stats,
     update_ground_truth,
     delete_measurement,
@@ -115,11 +118,21 @@ def _slugify(name: str) -> str:
     return slug or "anon"
 
 
-def _make_base_name(kol_name: str) -> Tuple[str, str]:
-    """Return (base_name, run_id). base_name = '{slug}_{timestamp}_{shortid}'."""
+def _email_local_part(email: str) -> str:
+    """Return the part of an email before '@'. Used only for naming the
+    stored object — we deliberately keep the full address out of bucket
+    paths (it's PII; relevant for EU KOLs)."""
+    return (email or "").split("@", 1)[0]
+
+
+def _make_base_name(kol_email: str) -> Tuple[str, str]:
+    """Return (base_name, run_id). base_name = '{slug}_{timestamp}_{shortid}'.
+
+    The slug is derived from the email local-part only — never the full
+    address — so stored object paths don't leak the domain/full email."""
     run_id = uuid.uuid4().hex[:8]
     timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
-    base_name = f"{_slugify(kol_name)}_{timestamp}_{run_id}"
+    base_name = f"{_slugify(_email_local_part(kol_email))}_{timestamp}_{run_id}"
     return base_name, run_id
 
 
@@ -184,7 +197,10 @@ def _read_form_settings() -> Dict[str, Any]:
     return {
         "finger_index": request.form.get("finger_index", "index"),
         "mode": request.form.get("mode", "single"),
-        "kol_name": request.form.get("kol_name", "").strip(),
+        # Email is the cross-table join key (see doc/v8/PRD.md). Normalize
+        # to trim + lowercase so the same address matches across the
+        # measurement, feedback, and shipping data sources.
+        "kol_email": request.form.get("kol_email", "").strip().lower(),
         "ring_model": ring_model,
         "capture_method": capture_method,
         "gate_telemetry": gate_telemetry,
@@ -231,6 +247,14 @@ def index_dev():
     return render_template("index.html", default_sample_url=DEFAULT_SAMPLE_URL, dev_mode=True)
 
 
+@app.route("/feedback")
+def feedback_form():
+    """Public post-shipment KOL fit-feedback form (v8). Mobile-first but
+    served to all UAs — desktop KOLs must be able to fill it too, so no
+    UA redirect here (unlike `/`)."""
+    return render_template("feedback.html")
+
+
 @app.route("/results/<path:filename>")
 def serve_result(filename: str):
     return send_from_directory(RESULTS_DIR, filename)
@@ -254,7 +278,7 @@ def api_measure():
         return jsonify({"success": False, "error": "Unsupported file type"}), 400
 
     settings = _read_form_settings()
-    base_name, run_id = _make_base_name(settings["kol_name"])
+    base_name, run_id = _make_base_name(settings["kol_email"])
     suffix = Path(secure_filename(file.filename)).suffix.lower() or ".jpg"
     upload_name = f"{base_name}{suffix}"
     upload_path = UPLOAD_DIR / upload_name
@@ -269,7 +293,7 @@ def api_measure():
         image=image,
         input_image_url=f"/uploads/{upload_name}",
         ring_model=settings["ring_model"],
-        kol_name=settings["kol_name"],
+        kol_email=settings["kol_email"],
         capture_method=settings["capture_method"],
         gate_telemetry=settings["gate_telemetry"],
         upload_path=upload_path,
@@ -292,13 +316,13 @@ def api_measure_default():
         return jsonify({"success": False, "error": "Failed to load default sample image"}), 500
 
     settings = _read_form_settings()
-    base_name, run_id = _make_base_name(settings["kol_name"] or "sample")
+    base_name, run_id = _make_base_name(settings["kol_email"] or "sample")
 
     common_kwargs = dict(
         image=image,
         input_image_url=DEFAULT_SAMPLE_URL,
         ring_model=settings["ring_model"],
-        kol_name=settings["kol_name"],
+        kol_email=settings["kol_email"],
         capture_method=settings["capture_method"],
         gate_telemetry=settings["gate_telemetry"],
         base_name=base_name,
@@ -314,7 +338,7 @@ def _run_measurement(
     finger_index: str,
     input_image_url: str,
     ring_model: str = DEFAULT_RING_MODEL,
-    kol_name: str = "",
+    kol_email: str = "",
     capture_method: str = DEFAULT_CAPTURE_METHOD,
     gate_telemetry: Optional[Dict[str, Any]] = None,
     upload_path: Optional[Path] = None,
@@ -374,7 +398,9 @@ def _run_measurement(
         result_png_name=result_png_name,
         record={
             "run_id": run_id,
-            "kol_name": kol_name,
+            # kol_name is left unset for new rows — it is retained on the
+            # table only for pre-email historical data. Email is the key.
+            "kol_email": kol_email,
             "mode": "single",
             "ring_model": ring_model,
             "finger_index": finger_index,
@@ -395,7 +421,7 @@ def _run_multi_measurement(
     image,
     input_image_url: str,
     ring_model: str = DEFAULT_RING_MODEL,
-    kol_name: str = "",
+    kol_email: str = "",
     capture_method: str = DEFAULT_CAPTURE_METHOD,
     gate_telemetry: Optional[Dict[str, Any]] = None,
     upload_path: Optional[Path] = None,
@@ -474,7 +500,8 @@ def _run_multi_measurement(
         result_png_name=result_png_name,
         record={
             "run_id": run_id,
-            "kol_name": kol_name,
+            # kol_name left unset for new rows (see _run_measurement).
+            "kol_email": kol_email,
             "mode": "multi",
             "ring_model": ring_model,
             "overall_best_size": result.get("overall_best_size"),
@@ -558,6 +585,62 @@ def api_feedback():
     return jsonify({"success": False, "error": "Could not save feedback, please retry"}), 500
 
 
+# Post-shipment fit-feedback (v8). Distinct from /api/feedback above: that
+# attaches a post-measurement star rating to a measurements row; this writes
+# a standalone row to the decoupled `feedback` table (no run_id, no FK). The
+# only link between the two tables is the normalized kol_email. See
+# doc/v8/PRD.md.
+@app.route("/api/fit-feedback", methods=["POST"])
+def api_fit_feedback():
+    # Multipart because the photo is optional; non-file fields arrive in
+    # request.form regardless.
+    kol_email = (request.form.get("kol_email") or "").strip().lower()
+    if not kol_email or "@" not in kol_email:
+        return jsonify({"success": False, "error": "A valid email is required"}), 400
+
+    def _field(name: str) -> Optional[str]:
+        v = (request.form.get(name) or "").strip()
+        return v or None
+
+    # Optional photo of the ring on the best-fit finger. Uploaded to the
+    # existing bucket under feedback/, slugging the email local-part only
+    # (never the full address) so the bucket path doesn't leak PII.
+    photo_url = None
+    file = request.files.get("photo")
+    if file and file.filename:
+        if not _allowed_file(file.filename):
+            return jsonify({"success": False, "error": "Unsupported photo type"}), 400
+        base_name, _ = _make_base_name(kol_email)
+        suffix = Path(secure_filename(file.filename)).suffix.lower() or ".jpg"
+        photo_name = f"{base_name}{suffix}"
+        photo_path = UPLOAD_DIR / photo_name
+        file.save(str(photo_path))
+        # Synchronous upload (no heavy compute here, unlike /api/measure) so
+        # the inserted row already carries photo_url — no follow-up patch.
+        photo_url = upload_file(str(photo_path), f"feedback/{photo_name}")
+
+    record = {
+        "kol_email": kol_email,
+        "received_size": _field("received_size"),
+        "received_model": _field("received_model"),
+        "best_fit_finger": _field("best_fit_finger"),
+        "fit_quality": _field("fit_quality"),
+        "hand": _field("hand"),
+        "photo_url": photo_url,
+        "notes": _field("notes"),
+    }
+
+    row_id = save_feedback(record)
+    if row_id is not None:
+        return jsonify({"success": True})
+    if not persistence_enabled():
+        # RING_DISABLE_SUPABASE / unconfigured env (local dev) — the form did
+        # what it could; report success rather than a scary error.
+        return jsonify({"success": True})
+    # Persistence is on but the insert returned nothing / raised.
+    return jsonify({"success": False, "error": "Could not save feedback, please retry"}), 500
+
+
 # ---------------------------------------------------------------------------
 # Admin routes
 # ---------------------------------------------------------------------------
@@ -583,6 +666,14 @@ def api_admin_measurements():
     return jsonify(rows)
 
 
+@app.route("/api/admin/feedback")
+def api_admin_feedback():
+    if not _check_admin_token():
+        return jsonify({"error": "Unauthorized"}), 401
+    rows = list_feedback(limit=500)
+    return jsonify(rows)
+
+
 @app.route("/api/admin/measurements/<measurement_id>/ground-truth", methods=["POST"])
 def api_admin_update_gt(measurement_id: str):
     if not _check_admin_token():
@@ -622,12 +713,13 @@ def _parse_iso_to_utc_date(iso_str: str) -> Optional[date]:
         return None
 
 
-def _kol_key(name: Optional[str]) -> Optional[str]:
-    """Normalize kol_name for grouping (trim + lower). Empty → None so we
-    don't count anonymous sample runs as a distinct KOL."""
-    if not name:
+def _kol_key(identifier: Optional[str]) -> Optional[str]:
+    """Normalize a KOL identifier for grouping (trim + lower). Empty → None
+    so we don't count anonymous sample runs as a distinct KOL. Callers pass
+    the email (the join key) with kol_name as a fallback for legacy rows."""
+    if not identifier:
         return None
-    s = name.strip().lower()
+    s = identifier.strip().lower()
     return s or None
 
 
@@ -683,12 +775,15 @@ def _compute_stats(rows: List[Dict[str, Any]], days: int = 30) -> Dict[str, Any]
 
         d = _parse_iso_to_utc_date(created_at)
 
-        kkey = _kol_key(row.get("kol_name"))
+        # Prefer email (the join key); fall back to kol_name for rows that
+        # predate the email switch.
+        kol_ident = row.get("kol_email") or row.get("kol_name")
+        kkey = _kol_key(kol_ident)
         in_window = d is not None and window_start <= d <= today
         if kkey:
             kol_counts[kkey] += 1
             if kkey not in kol_display:
-                kol_display[kkey] = (row.get("kol_name") or "").strip()
+                kol_display[kkey] = (kol_ident or "").strip()
             if in_window:
                 kol_counts_window[kkey] += 1
                 if created_at and (kkey not in kol_last_seen or created_at > kol_last_seen[kkey]):
@@ -770,7 +865,9 @@ def _compute_stats(rows: List[Dict[str, Any]], days: int = 30) -> Dict[str, Any]
 
     top_kols = [
         {
-            "kol_name": kol_display.get(k, k),
+            # Display label is the email (the join key) or, for legacy
+            # rows, the name — hence kol_ident, not kol_name.
+            "kol_ident": kol_display.get(k, k),
             "count": c,
             "last_at": kol_last_seen.get(k),
         }
@@ -876,7 +973,7 @@ def api_admin_export_csv():
     rows = list_measurements(limit=5000)
     output = io.StringIO()
     fieldnames = [
-        "kol_name", "created_at", "mode", "ring_model",
+        "kol_email", "kol_name", "created_at", "mode", "ring_model",
         "overall_best_size", "overall_range_min", "overall_range_max",
         "index_size", "index_diameter", "index_confidence",
         "middle_size", "middle_diameter", "middle_confidence",
@@ -890,6 +987,7 @@ def api_admin_export_csv():
     writer.writeheader()
     for row in rows:
         flat = {
+            "kol_email": _csv_safe(row.get("kol_email", "")),
             "kol_name": _csv_safe(row.get("kol_name", "")),
             "created_at": row.get("created_at", ""),
             "mode": row.get("mode", ""),

web_demo/static/app.js

@@ -111,7 +111,10 @@ const RING_SIZE_TABLES = {
 };
 const RING_MODEL_LABELS = { gen: "Gen1/Gen2", air: "Air" };
 
-const kolNameInput = document.getElementById("kolNameInput");
+const kolEmailInput = document.getElementById("kolEmailInput");
+// Loose RFC-ish check — `something@something.tld`. Email is the
+// cross-table join key (see doc/v8/PRD.md), so validate before submit.
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
 
 const buildMeasureSettings = () => {
   const fingerSelect = form.querySelector('[name="finger_index"]');
@@ -127,7 +130,7 @@ const buildMeasureSettings = () => {
     mode: mode,
     ring_model: ringModel,
     ai_explain: aiOn ? "1" : "0",
-    kol_name: kolNameInput ? kolNameInput.value.trim() : "",
+    kol_email: kolEmailInput ? kolEmailInput.value.trim().toLowerCase() : "",
   };
 };
 
@@ -318,9 +321,9 @@ form.addEventListener("submit", async (event) => {
   event.preventDefault();
 
   const settings = buildMeasureSettings();
-  if (!settings.kol_name) {
-    setStatus("Please enter your Name / ID before measuring.", { error: true });
-    kolNameInput.focus();
+  if (!EMAIL_RE.test(settings.kol_email)) {
+    setStatus("Please enter a valid email before measuring.", { error: true });
+    kolEmailInput.focus();
     return;
   }
   const formData = new FormData();
@@ -329,7 +332,7 @@ form.addEventListener("submit", async (event) => {
   formData.append("mode", settings.mode);
   formData.append("ring_model", settings.ring_model);
   formData.append("ai_explain", settings.ai_explain);
-  formData.append("kol_name", settings.kol_name);
+  formData.append("kol_email", settings.kol_email);
 
   const file = imageInput.files[0];
   if (file) {

web_demo/static/feedback/feedback.css

@@ -0,0 +1,100 @@
+/* Page-specific styles for /feedback. The bulk of the look comes from
+   mobile.css (imported first): .step / .panel / .controls / .primary /
+   .form-error / hero-* are all reused so this form matches the /m flow.
+   This file only adds what the step CSS doesn't already cover: the two
+   control types unique to this form (textarea + file), the link-styled
+   primary button on the success screen, and the success screen itself. */
+
+/* Slightly more breathing room between questions than the shared
+   .controls default (14px) — this form reads as a vertical
+   questionnaire, so the questions want clearer separation. */
+.step-feedback .controls {
+  gap: 22px;
+}
+
+/* Textarea + file input inside .controls — mobile.css styles
+   input[type="text"|"email"] and select, but not these two. */
+.controls textarea {
+  width: 100%;
+  border: 1px solid var(--border);
+  border-radius: 12px;
+  padding: 10px 14px;
+  /* ≥16px keeps iOS Safari from auto-zooming on focus. */
+  font-size: 1rem;
+  line-height: 1.4;
+  font-family: inherit;
+  background: white;
+  color: var(--ink);
+  resize: vertical;
+  min-height: 72px;
+}
+
+.controls input[type="file"] {
+  width: 100%;
+  font-size: 1rem;
+  color: var(--ink-soft);
+}
+
+/* Enlarge the native "Choose File" button — iOS Safari renders it small
+   by default. Both selectors cover Safari (-webkit-) and the standard. */
+.controls input[type="file"]::-webkit-file-upload-button,
+.controls input[type="file"]::file-selector-button {
+  font-size: 1rem;
+  padding: 10px 16px;
+  margin-right: 12px;
+  border: 1px solid var(--border);
+  border-radius: 10px;
+  background: white;
+  color: var(--accent);
+  cursor: pointer;
+}
+
+/* Inline per-field validation error — sits directly under the offending
+   control (injected by feedback.js). Bottom-of-form errors are invisible
+   on mobile once the field is focused and the keyboard covers them, so
+   the message lives next to the field instead. */
+.field-error {
+  display: block;
+  margin-top: 2px;
+  font-size: 0.82rem;
+  font-weight: 600;
+  color: var(--accent);
+}
+
+/* Red ring on the control flagged invalid, so the field itself reads as
+   the error target, not just the text below it. */
+.controls input[aria-invalid="true"],
+.controls select[aria-invalid="true"] {
+  border-color: var(--accent);
+}
+
+/* --- Success screen --------------------------------------------- */
+
+.fb-success {
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+}
+
+.fb-success-inner {
+  text-align: center;
+  max-width: 36ch;
+  margin: 0 auto;
+}
+
+.fb-success .hero-sub {
+  margin: 0 auto 20px;
+}
+
+.fb-success-check {
+  width: 64px;
+  height: 64px;
+  margin: 0 auto 20px;
+  border-radius: 50%;
+  background: #d8f1de;
+  color: #1f6b34;
+  font-size: 34px;
+  line-height: 64px;
+  font-weight: 700;
+}
+

web_demo/static/feedback/feedback.js

@@ -0,0 +1,138 @@
+// /feedback — post-shipment KOL fit-feedback form (v8).
+//
+// A single self-contained screen (no step framework — that's the /m
+// capture coach's machinery and irrelevant here). Validates the
+// required fields, POSTs multipart to /api/fit-feedback, and swaps the
+// form for a thank-you + "measure now" CTA on success.
+//
+// Email is the cross-table join key (see doc/v8/PRD.md), so it is the
+// one field validated for format; the rest are required-but-free.
+//
+// Validation errors render INLINE, directly under the offending field
+// (not in one spot at the bottom): on mobile we focus the bad field, so
+// the keyboard would hide a bottom-of-form message entirely.
+
+// Loose RFC-ish check — `something@something.tld`. Mirrors the desktop /
+// mobile measurement forms so a KOL who uses both sees the same rule.
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+const form = document.getElementById("feedbackForm");
+const errorEl = document.getElementById("formError");
+const submitBtn = document.getElementById("submitBtn");
+
+const el = (id) => document.getElementById(id);
+const val = (id) => (el(id).value || "").trim();
+
+// Required selects/inputs and the human label used in the error message
+// when one is left blank.
+const REQUIRED = [
+  ["receivedSize", "the ring size you received"],
+  ["receivedModel", "the ring model"],
+  ["bestFitFinger", "which finger fit best"],
+  ["fitQuality", "how it fit"],
+  ["hand", "which hand"],
+];
+
+// Every field that can produce a validation error, in DOM order.
+const FIELD_IDS = ["kolEmail", ...REQUIRED.map(([id]) => id)];
+
+// Inject an inline error slot under each validatable field and clear it
+// as soon as the user edits that field.
+const errSlots = {};
+for (const id of FIELD_IDS) {
+  const input = el(id);
+  const slot = document.createElement("small");
+  slot.className = "field-error";
+  slot.hidden = true;
+  input.closest("label").appendChild(slot);
+  errSlots[id] = slot;
+  input.addEventListener(input.tagName === "SELECT" ? "change" : "input", () => {
+    slot.hidden = true;
+    input.removeAttribute("aria-invalid");
+  });
+}
+
+function clearErrors() {
+  errorEl.hidden = true;
+  for (const id of FIELD_IDS) {
+    errSlots[id].hidden = true;
+    el(id).removeAttribute("aria-invalid");
+  }
+}
+
+// Inline error on a specific field: show the message under it, focus it,
+// and scroll it to mid-screen so the message clears the on-screen keyboard.
+function showFieldError(id, msg) {
+  const input = el(id);
+  const slot = errSlots[id];
+  slot.textContent = msg;
+  slot.hidden = false;
+  input.setAttribute("aria-invalid", "true");
+  input.focus({ preventScroll: true });
+  input.closest("label").scrollIntoView({ block: "center", behavior: "smooth" });
+}
+
+// Global error (network / server failures — not tied to one field).
+function showFormError(msg) {
+  errorEl.textContent = msg;
+  errorEl.hidden = false;
+}
+
+// Returns [fieldId, message] for the first invalid field, or null.
+function firstInvalid() {
+  if (!EMAIL_RE.test(val("kolEmail").toLowerCase())) {
+    return ["kolEmail", "Please enter a valid email."];
+  }
+  for (const [id, label] of REQUIRED) {
+    if (!val(id)) return [id, `Please tell us ${label}.`];
+  }
+  return null;
+}
+
+function showSuccess() {
+  document.getElementById("formView").hidden = true;
+  document.getElementById("formFoot").hidden = true;
+  document.getElementById("successView").hidden = false;
+  window.scrollTo(0, 0);
+}
+
+form.addEventListener("submit", async (event) => {
+  event.preventDefault();
+  clearErrors();
+
+  const invalid = firstInvalid();
+  if (invalid) {
+    showFieldError(invalid[0], invalid[1]);
+    return;
+  }
+
+  const fd = new FormData();
+  fd.append("kol_email", val("kolEmail").toLowerCase());
+  fd.append("received_size", val("receivedSize"));
+  fd.append("received_model", val("receivedModel"));
+  fd.append("best_fit_finger", val("bestFitFinger"));
+  fd.append("fit_quality", val("fitQuality"));
+  fd.append("hand", val("hand"));
+  fd.append("notes", val("notes"));
+  const photo = el("photo").files[0];
+  if (photo) fd.append("photo", photo, photo.name);
+
+  submitBtn.disabled = true;
+  const originalLabel = submitBtn.textContent;
+  submitBtn.textContent = "Submitting…";
+
+  try {
+    const resp = await fetch("/api/fit-feedback", { method: "POST", body: fd });
+    const data = await resp.json().catch(() => ({}));
+    if (resp.ok && data.success) {
+      showSuccess();
+      return;
+    }
+    showFormError(data.error || "Could not submit. Please try again.");
+  } catch (err) {
+    showFormError("Network error. Please check your connection and retry.");
+  } finally {
+    submitBtn.disabled = false;
+    submitBtn.textContent = originalLabel;
+  }
+});

web_demo/static/mobile/mobile.css

@@ -208,6 +208,7 @@ body {
 }
 
 .controls input[type="text"],
+.controls input[type="email"],
 .controls select {
   /* Lock both controls to the same height. iOS Safari's native
      <select> renders at a slightly shorter intrinsic height than

web_demo/static/mobile/session.js

@@ -8,7 +8,7 @@
 // next run starts fresh).
 
 export const session = {
-  kolName: "",
+  kolEmail: "",
   ringModel: "gen",
   // Either an uploaded File or a Blob captured from the camera step.
   imageBlob: null,
@@ -26,7 +26,7 @@ export const session = {
 };
 
 // Wipe just the photo + result — used by "Measure again" so the user
-// keeps their entered name + ring model on the next capture without
+// keeps their entered email + ring model on the next capture without
 // re-typing. A full reset isn't a separate function: a page refresh
 // reloads this module and reinitializes `session` to the defaults.
 export function resetForRetake() {

web_demo/static/mobile/steps/confirm.js

@@ -94,7 +94,7 @@ export default {
       try {
         const result = await postMeasure({
           blob: session.imageBlob,
-          kol_name: session.kolName,
+          kol_email: session.kolEmail,
           ring_model: session.ringModel,
           gate_telemetry: session.gateTelemetry,
           capture_method: session.imageSource === "camera" ? "camera" : "upload",

web_demo/static/mobile/steps/form.js

@@ -1,6 +1,7 @@
-// Step 2 — Name / ID + Ring Model.
+// Step 2 — Email + Ring Model.
 // Mirrors the desktop hero-card's top "controls" block.
 // Persists answers in session so back-nav preserves them.
+// Email (not name) is the cross-table join key — see doc/v8/PRD.md.
 
 import { session } from "../session.js";
 
@@ -24,12 +25,13 @@ export default {
                 </select>
               </label>
               <label>
-                <span>Name / ID</span>
+                <span>Email</span>
                 <input
-                  type="text"
-                  id="formKolName"
-                  placeholder="e.g. Your Name"
-                  autocomplete="name"
+                  type="email"
+                  id="formKolEmail"
+                  placeholder="you@example.com"
+                  autocomplete="email"
+                  inputmode="email"
                 />
               </label>
             </div>
@@ -42,25 +44,31 @@ export default {
       </section>
     `;
 
-    const nameInput = container.querySelector("#formKolName");
+    const emailInput = container.querySelector("#formKolEmail");
     const modelSelect = container.querySelector("#formRingModel");
     const errorEl = container.querySelector("#formError");
 
     // Pre-fill from session — back-nav from upload/camera should not
     // ask the user to retype.
-    nameInput.value = session.kolName || "";
+    emailInput.value = session.kolEmail || "";
     modelSelect.value = session.ringModel || "gen";
 
+    // Loose RFC-ish check — `something@something.tld`. The browser's
+    // native type="email" validity is the first line of defense; this
+    // guards against the field being left blank or obviously malformed
+    // since email is the cross-table join key.
+    const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
     container.querySelector(".step-back").addEventListener("click", nav.back);
     container.querySelector(".step-next").addEventListener("click", () => {
-      const name = nameInput.value.trim();
-      if (!name) {
-        errorEl.textContent = "Please enter a name or ID before continuing.";
+      const email = emailInput.value.trim().toLowerCase();
+      if (!EMAIL_RE.test(email)) {
+        errorEl.textContent = "Please enter a valid email before continuing.";
         errorEl.hidden = false;
-        nameInput.focus();
+        emailInput.focus();
         return;
       }
-      session.kolName = name;
+      session.kolEmail = email;
       session.ringModel = modelSelect.value;
       nav.next();
     });

web_demo/static/shared/measure-api.js

@@ -20,17 +20,17 @@ const DEFAULTS = {
 
 export async function postMeasure({
   blob,
-  kol_name,
+  kol_email,
   gate_telemetry = null,
   ...overrides
 } = {}) {
   if (!blob) throw new Error("postMeasure: blob is required");
-  if (!kol_name) throw new Error("postMeasure: kol_name is required");
+  if (!kol_email) throw new Error("postMeasure: kol_email is required");
 
   const settings = { ...DEFAULTS, ...overrides };
   const formData = new FormData();
   formData.append("image", blob, "capture.jpg");
-  formData.append("kol_name", kol_name);
+  formData.append("kol_email", kol_email);
   formData.append("finger_index", settings.finger_index);
   formData.append("mode", settings.mode);
   formData.append("edge_method", settings.edge_method);

web_demo/static/styles.css

@@ -169,7 +169,8 @@ body {
 }
 
 select,
-.controls input[type="text"] {
+.controls input[type="text"],
+.controls input[type="email"] {
   border: 1px solid var(--border);
   border-radius: 12px;
   padding: 10px 12px;

web_demo/supabase_client.py

@@ -53,6 +53,14 @@ def _get_client():
     return _client
 
 
+def persistence_enabled() -> bool:
+    """True when Supabase persistence is active (env configured and not
+    opted out via RING_DISABLE_SUPABASE). Lets an endpoint distinguish
+    'disabled in this env' (still report success to the user) from a real
+    write failure (surface an error)."""
+    return _get_client() is not None
+
+
 BUCKET = "ring-measurements"
 
 
@@ -101,6 +109,46 @@ def save_measurement(record: Dict[str, Any]) -> Optional[str]:
         return None
 
 
+def save_feedback(record: Dict[str, Any]) -> Optional[str]:
+    """Insert a post-shipment fit-feedback row into the `feedback` table.
+
+    Intentionally decoupled from `measurements` (no run_id, no FK) — the
+    only link between the two is the normalized `kol_email`, joined at
+    analysis time. See doc/v8/PRD.md. Returns row UUID or None (None also
+    when persistence is disabled, which the caller treats as success).
+    """
+    client = _get_client()
+    if client is None:
+        return None
+    try:
+        resp = client.table("feedback").insert(record).execute()
+        if resp.data and len(resp.data) > 0:
+            return resp.data[0].get("id")
+        return None
+    except Exception as e:
+        logger.error("Failed to save feedback: %s", e)
+        return None
+
+
+def list_feedback(limit: int = 500, offset: int = 0) -> List[Dict[str, Any]]:
+    """Fetch post-shipment feedback rows for the admin page, newest first."""
+    client = _get_client()
+    if client is None:
+        return []
+    try:
+        resp = (
+            client.table("feedback")
+            .select("*")
+            .order("submitted_at", desc=True)
+            .range(offset, offset + limit - 1)
+            .execute()
+        )
+        return resp.data or []
+    except Exception as e:
+        logger.error("Failed to list feedback: %s", e)
+        return []
+
+
 def list_measurements(limit: int = 200, offset: int = 0) -> List[Dict[str, Any]]:
     """Fetch measurements for admin page, newest first."""
     client = _get_client()
@@ -121,7 +169,7 @@ def list_measurements(limit: int = 200, offset: int = 0) -> List[Dict[str, Any]]
 
 
 STATS_COLUMNS = (
-    "id,created_at,kol_name,mode,ring_model,confidence,fail_reason,"
+    "id,created_at,kol_name,kol_email,mode,ring_model,confidence,fail_reason,"
     "overall_best_size,ring_fit,gt_index_size,gt_middle_size,gt_ring_size,"
     "finger_index,photo_url,per_finger,feedback_rating,feedback_message"
 )

web_demo/templates/admin.html

@@ -175,6 +175,7 @@
     <div class="tabs">
       <button class="tab active" data-pane="recordsPane">Records</button>
       <button class="tab" data-pane="dashboardPane">Dashboard</button>
+      <button class="tab" data-pane="feedbackPane">Feedback</button>
     </div>
 
     <!-- Records pane -->
@@ -265,6 +266,36 @@
         </div>
       </div>
     </div>
+
+    <!-- Feedback pane (v8 post-shipment fit feedback) -->
+    <div class="pane" id="feedbackPane">
+      <div class="toolbar">
+        <a href="/">Back to Demo</a>
+        <button id="fbRefreshBtn">Refresh</button>
+        <span class="count" id="fbCountLabel">Loading...</span>
+      </div>
+
+      <div class="scroll-wrap">
+        <table>
+          <thead>
+            <tr>
+              <th>Email</th>
+              <th>Submitted</th>
+              <th>Size</th>
+              <th>Model</th>
+              <th>Best finger</th>
+              <th>Fit</th>
+              <th>Hand</th>
+              <th>Photo</th>
+              <th>Notes</th>
+            </tr>
+          </thead>
+          <tbody id="fbTableBody">
+            <tr><td colspan="9" class="empty">Loading...</td></tr>
+          </tbody>
+        </table>
+      </div>
+    </div>
   </div>
 
   <script>
@@ -294,6 +325,7 @@
       document.getElementById("exportCsvLink").href = `/api/admin/export-csv?token=${encodeURIComponent(adminToken)}`;
       loadStats();
       loadData();
+      loadFeedback();
       return true;
     };
 
@@ -357,7 +389,7 @@
         ? `<img class="thumb" loading="lazy" src="${r.result_url}" onclick="window.open('${r.result_url}')" />`
         : "-";
       return `<tr data-id="${r.id}">
-        <td><strong>${r.kol_name || "-"}</strong></td>
+        <td><strong>${r.kol_email || r.kol_name || "-"}</strong></td>
         <td>${fmtDate(r.created_at)}</td>
         <td>${r.ring_model || "-"}</td>
         <td>${photoThumb}</td>
@@ -445,6 +477,68 @@
       });
     });
 
+    // ------------------------------------------------------------------
+    // Feedback (v8 post-shipment fit feedback)
+    // ------------------------------------------------------------------
+    const fbTableBody = document.getElementById("fbTableBody");
+    const fbCountLabel = document.getElementById("fbCountLabel");
+
+    // Map the stored value codes back to human labels (mirrors the
+    // /feedback form's <option> text).
+    const FB_MODEL = { gen: "Gen1/Gen2", air: "Air" };
+    const FB_FINGER = {
+      thumb: "Thumb", index: "Index", middle: "Middle", ring: "Ring",
+      pinky: "Pinky", none_too_small: "None (too small)", none_too_big: "None (too big)",
+    };
+    const FB_FIT = {
+      perfect: "Perfect", snug: "Snug", loose: "Loose but stays on",
+      falls_off: "Falls off", too_tight: "Can't get it on",
+    };
+    const FB_HAND = { left: "Left", right: "Right" };
+    const fbLabel = (map, v) => (v ? (map[v] || v) : "-");
+
+    const fbRowHtml = (r) => {
+      const photoThumb = r.photo_url
+        ? `<img class="thumb" loading="lazy" src="${esc(r.photo_url)}" onclick="window.open('${esc(r.photo_url)}')" />`
+        : "-";
+      return `<tr>
+        <td><strong>${esc(r.kol_email) || "-"}</strong></td>
+        <td>${fmtDate(r.submitted_at)}</td>
+        <td>${esc(r.received_size) || "-"}</td>
+        <td>${fbLabel(FB_MODEL, r.received_model)}</td>
+        <td>${fbLabel(FB_FINGER, r.best_fit_finger)}</td>
+        <td>${fbLabel(FB_FIT, r.fit_quality)}</td>
+        <td>${fbLabel(FB_HAND, r.hand)}</td>
+        <td>${photoThumb}</td>
+        <td>${fmtComment(r.notes)}</td>
+      </tr>`;
+    };
+
+    const loadFeedback = async () => {
+      try {
+        const resp = await fetch(`/api/admin/feedback?token=${encodeURIComponent(adminToken)}`);
+        if (resp.status === 401) {
+          sessionStorage.removeItem("admin_token");
+          loginGate.style.display = "";
+          adminContent.style.display = "none";
+          loginError.textContent = "Session expired. Please log in again.";
+          return;
+        }
+        const rows = await resp.json();
+        if (!rows.length) {
+          fbCountLabel.textContent = "0 feedback rows";
+          fbTableBody.innerHTML = '<tr><td colspan="9" class="empty">No feedback yet</td></tr>';
+          return;
+        }
+        fbCountLabel.textContent = `${rows.length} feedback rows`;
+        fbTableBody.innerHTML = rows.map(fbRowHtml).join("");
+      } catch (e) {
+        fbTableBody.innerHTML = `<tr><td colspan="9" class="empty">Error loading feedback: ${e.message}</td></tr>`;
+      }
+    };
+
+    document.getElementById("fbRefreshBtn").addEventListener("click", loadFeedback);
+
     // ------------------------------------------------------------------
     // Dashboard
     // ------------------------------------------------------------------
@@ -504,7 +598,7 @@
       }
       topKolList.innerHTML = kols.map((k) => {
         const last = k.last_at ? new Date(k.last_at).toISOString().slice(0, 10) : "";
-        return `<li><span class="name">${k.kol_name}</span><span class="count">${k.count} · ${last}</span></li>`;
+        return `<li><span class="name">${k.kol_ident}</span><span class="count">${k.count} · ${last}</span></li>`;
       }).join("");
     };
 

web_demo/templates/feedback.html

@@ -0,0 +1,131 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+  <meta name="theme-color" content="#f5f1e7" />
+  <title>Ring Fit Feedback — Femometer Smart Ring</title>
+  <meta name="description" content="Tell us how your ring fit so we can improve sizing." />
+  <meta name="robots" content="noindex" />
+  <!-- Reuse the /m flow's stylesheet so this form matches the mobile
+       capture flow's look; feedback.css only adds the success screen +
+       a couple of form niceties the step CSS doesn't cover. -->
+  <link rel="stylesheet" href="/static/mobile/mobile.css" />
+  <link rel="stylesheet" href="/static/feedback/feedback.css" />
+</head>
+<body>
+  <main class="step step-feedback">
+    <!-- Form view -->
+    <div class="step-body" id="formView">
+      <p class="hero-eyebrow">Femometer Smart Ring</p>
+      <h1 class="hero-headline">How did your ring fit?</h1>
+
+      <form class="panel" id="feedbackForm" novalidate>
+        <div class="controls">
+          <label>
+            <span>Email</span>
+            <input
+              type="email"
+              id="kolEmail"
+              placeholder="you@example.com"
+              autocomplete="email"
+              inputmode="email"
+              required
+            />
+          </label>
+
+          <label>
+            <span>Ring size received</span>
+            <input
+              type="text"
+              id="receivedSize"
+              placeholder="e.g. 7 (read it off the package)"
+              autocomplete="off"
+            />
+          </label>
+
+          <label>
+            <span>Ring model</span>
+            <select id="receivedModel">
+              <option value="" disabled selected>Choose…</option>
+              <option value="gen">Gen1/Gen2</option>
+              <option value="air">Air</option>
+            </select>
+          </label>
+
+          <label>
+            <span>Which finger did it fit best?</span>
+            <select id="bestFitFinger">
+              <option value="" disabled selected>Choose…</option>
+              <option value="index">Index</option>
+              <option value="middle">Middle</option>
+              <option value="ring">Ring</option>
+              <option value="pinky">Pinky</option>
+              <option value="thumb">Thumb</option>
+              <option value="none_too_small">None — too small for all</option>
+              <option value="none_too_big">None — too big for all</option>
+            </select>
+          </label>
+
+          <label>
+            <span>How did it fit on that finger?</span>
+            <select id="fitQuality">
+              <option value="" disabled selected>Choose…</option>
+              <option value="perfect">Perfect</option>
+              <option value="snug">Snug</option>
+              <option value="loose">Loose but stays on</option>
+              <option value="falls_off">Falls off</option>
+              <option value="too_tight">Can't get it on</option>
+            </select>
+          </label>
+
+          <label>
+            <span>Which hand?</span>
+            <select id="hand">
+              <option value="" disabled selected>Choose…</option>
+              <option value="left">Left</option>
+              <option value="right">Right</option>
+            </select>
+          </label>
+
+          <label>
+            <span>Photo of the ring on your finger (optional)</span>
+            <input type="file" id="photo" accept="image/*" />
+          </label>
+
+          <label>
+            <span>Anything else? (optional)</span>
+            <textarea
+              id="notes"
+              rows="3"
+              placeholder="Tell us anything the questions above missed."
+            ></textarea>
+          </label>
+        </div>
+
+        <p class="form-error" id="formError" hidden></p>
+      </form>
+    </div>
+
+    <div class="step-foot" id="formFoot">
+      <button type="submit" class="primary" id="submitBtn" form="feedbackForm">
+        Submit feedback
+      </button>
+    </div>
+
+    <!-- Success view (swapped in on submit) -->
+    <div class="step-body fb-success" id="successView" hidden>
+      <div class="fb-success-inner">
+        <div class="fb-success-check">✓</div>
+        <h1 class="hero-headline">Thank you!</h1>
+        <p class="hero-sub">
+          Your feedback is in. It directly helps us improve ring-size
+          accuracy.
+        </p>
+      </div>
+    </div>
+  </main>
+
+  <script type="module" src="/static/feedback/feedback.js"></script>
+</body>
+</html>

web_demo/templates/index.html

@@ -43,8 +43,8 @@
 
         <div class="controls">
           <label>
-            <span>Name / ID</span>
-            <input type="text" name="kol_name" id="kolNameInput" placeholder="e.g. Your Name" />
+            <span>Email</span>
+            <input type="email" name="kol_email" id="kolEmailInput" placeholder="you@example.com" autocomplete="email" inputmode="email" />
           </label>
           <label>
             <span>Ring Model</span>