space: add email signup for Microfactory updates

FIELD-NOTES.md

@@ -109,8 +109,25 @@ refusing any prefix that isn't `<username>/`, etc.) so the next adapter is a
 ten-minute job, not a half-day. Done means someone you've never met can pull
 and run it in one line. Build the publishing in.
 
+Got it. To capture interest without pretending the product is finished, I added a simple email signup at the bottom of the Space. It is opt-in only: checkbox + email, clear privacy note, stored as a local JSONL and optionally synced to a private HF dataset when `HF_TOKEN` is set. No print data, no uploaded files, no third-party trackers. The same pattern as the field log, but for people instead of jobs.
+
 ---
 
+### Build paper trail
+
+Everything that is part of the judged artifact is linked from the Space README and mirrored in the
+GitHub repo:
+
+- **Model cards:** [`learn/finetune/MODEL_CARD.md`](https://github.com/kylebrodeur/microfactory-lab/blob/main/chief-engineer/learn/finetune/MODEL_CARD.md) · [`MODEL_CARD_QAT.md`](https://github.com/kylebrodeur/microfactory-lab/blob/main/chief-engineer/learn/finetune/MODEL_CARD_QAT.md)
+- **Local run / publish:** [`SERVING.md`](https://github.com/kylebrodeur/microfactory-lab/blob/main/chief-engineer/learn/finetune/SERVING.md) · [`OLLAMA_PUBLISHING.md`](https://github.com/kylebrodeur/microfactory-lab/blob/main/chief-engineer/learn/finetune/OLLAMA_PUBLISHING.md)
+- **Fine-tune pipeline:** [`learn/finetune/README.md`](https://github.com/kylebrodeur/microfactory-lab/blob/main/chief-engineer/learn/finetune/README.md) · [`PIPELINE.md`](https://github.com/kylebrodeur/microfactory-lab/blob/main/chief-engineer/learn/finetune/PIPELINE.md) · [`RUNBOOK.md`](https://github.com/kylebrodeur/microfactory-lab/blob/main/chief-engineer/learn/finetune/RUNBOOK.md) · [`BUDGET.md`](https://github.com/kylebrodeur/microfactory-lab/blob/main/chief-engineer/learn/finetune/BUDGET.md)
+- **Session report + activity trace:** [`SESSION_REPORT.md`](https://github.com/kylebrodeur/microfactory-lab/blob/main/chief-engineer/learn/finetune/SESSION_REPORT.md) · [`activity.jsonl`](https://github.com/kylebrodeur/microfactory-lab/blob/main/chief-engineer/learn/finetune/activity.jsonl)
+- **Calibration:** [`sim/calibration/CALIBRATION-REPORT.md`](https://github.com/kylebrodeur/microfactory-lab/blob/main/chief-engineer/sim/calibration/CALIBRATION-REPORT.md) · [`sim/calibration/README.md`](https://github.com/kylebrodeur/microfactory-lab/blob/main/chief-engineer/sim/calibration/README.md)
+- **Ingestion + assets + outputs:** [`ingest/README.md`](https://github.com/kylebrodeur/microfactory-lab/blob/main/chief-engineer/ingest/README.md) · [`assets/screenshots/README.md`](https://github.com/kylebrodeur/microfactory-lab/blob/main/chief-engineer/assets/screenshots/README.md) · [`dist/README.md`](https://github.com/kylebrodeur/microfactory-lab/blob/main/chief-engineer/dist/README.md) · [`dist/deliberation/README.md`](https://github.com/kylebrodeur/microfactory-lab/blob/main/chief-engineer/dist/deliberation/README.md)
+
+Internal planning docs, raw workorders, and archived iterations stay in the GitHub repo but are
+kept out of the Space so the public-facing card stays curated.
+
 *Microfactory Node: 3D Printer runs fully local (Ollama / llama.cpp, Gemma E4B/E2B), falls back
 to a deterministic advisor, and publishes both its lesson ledger and its live interaction log as open
 datasets. It is the first node of the Microfactory, a network of small machines and the people who

README.md

@@ -141,9 +141,9 @@ Local dev uses [uv](https://docs.astral.sh/uv); the HF Space installs via `requi
 **Layout:** `app.py` (Space entrypoint) + `test_core.py` at the root; the core library lives in
 `core/`, runnable helpers in `scripts/` (run via `make <target>` or `uv run python -m scripts.<name>`),
 and the simulator / learning-loop / ingestion packages in `sim/`, `learn/`, `ingest/`. See
-`docs/RUNBOOK.md` for the full run-and-test order of operations.
+[`docs/RUNBOOK.md`](https://github.com/kylebrodeur/microfactory-lab/blob/main/chief-engineer/docs/RUNBOOK.md) for the full run-and-test order of operations.
 
-**HF Space deployment** (source repo): `docs/reference/DEPLOYMENT.md` + `docs/RUNBOOK.md`
+**HF Space deployment** (source repo): [`docs/reference/DEPLOYMENT.md`](https://github.com/kylebrodeur/microfactory-lab/blob/main/chief-engineer/docs/reference/DEPLOYMENT.md) + [`docs/RUNBOOK.md`](https://github.com/kylebrodeur/microfactory-lab/blob/main/chief-engineer/docs/RUNBOOK.md)
 ("Deploy to the Space") cover Space variables, the dual local/Space config, build strategy,
 the `@spaces.GPU`-on-inference-only pattern, and field-log setup.
 
@@ -239,7 +239,16 @@ Storytelling is a judging principle, not a badge.
   - **Field log (live):** [build-small-hackathon/chief-engineer-field-log](https://huggingface.co/datasets/build-small-hackathon/chief-engineer-field-log)
 - **Demo video:** [<!-- TODO: add video URL after recording -->]()
 - **Social post:** [<!-- TODO: add social post URL after publishing -->]()
+- **Stay in the loop:** an email signup lives at the bottom of the live Space. Opt-in only, clear privacy note, no third-party trackers.
 - **How to use it (guided tour):** [`docs/RUNBOOK.md` §2](https://github.com/kylebrodeur/microfactory-lab/blob/main/chief-engineer/docs/RUNBOOK.md#2--use-the-tool-the-guided-tour--also-the-judges-tour)
+- **Build story / field notes:** [`docs/writeup/06-FIELD-NOTES.md`](https://github.com/kylebrodeur/microfactory-lab/blob/main/chief-engineer/docs/writeup/06-FIELD-NOTES.md)
+- **Build paper trail (on this Space):**
+  - **Model cards:** [`LoRA v2`](learn/finetune/MODEL_CARD.md) · [`LoRA v3 QAT`](learn/finetune/MODEL_CARD_QAT.md)
+  - **Local run / publish:** [`SERVING.md`](learn/finetune/SERVING.md) · [`OLLAMA_PUBLISHING.md`](learn/finetune/OLLAMA_PUBLISHING.md)
+  - **Fine-tune pipeline:** [`learn/finetune/README.md`](learn/finetune/README.md) · [`PIPELINE.md`](learn/finetune/PIPELINE.md) · [`RUNBOOK.md`](learn/finetune/RUNBOOK.md) · [`BUDGET.md`](learn/finetune/BUDGET.md)
+  - **Session report + activity trace:** [`SESSION_REPORT.md`](learn/finetune/SESSION_REPORT.md) · [`activity.jsonl`](learn/finetune/activity.jsonl)
+  - **Calibration:** [`sim/calibration/CALIBRATION-REPORT.md`](sim/calibration/CALIBRATION-REPORT.md) · [`sim/calibration/README.md`](sim/calibration/README.md)
+  - **Ingestion + assets:** [`ingest/README.md`](ingest/README.md) · [`assets/screenshots/README.md`](assets/screenshots/README.md) · [`dist/README.md`](dist/README.md) · [`dist/deliberation/README.md`](dist/deliberation/README.md)
 - **Source:** [kylebrodeur/microfactory-lab](https://github.com/kylebrodeur/microfactory-lab)
 
 ## License

app.py

@@ -39,6 +39,7 @@ from core import field_log
 from core import inspector
 from core import llm
 from core import seed_lessons
+from core import signups
 from core.theme import (
     THEME, CSS, rule, command_bar, footer_bar, inspector_panel, icon, loader, tab_intro,
     CLOCK_JS,
@@ -783,7 +784,7 @@ def run_print(state, iterations, nozzle, bed, fan, retract, progress=gr.Progress
         + (f"first clean print at **iteration {first}**, now **{traj[-1]:.2f}**."
            if first else f"still improving — best **{max(traj):.2f}** after {len(traj)} runs.")
         + " The Engineer proposed; a separate simulated world reported the outcome; the **Inspector** "
-        "graded each run; the policy and ledger learned. *(Simulated — see SIMULATION.md.)*"
+        "graded each run; the policy and ledger learned. *(Simulated — see [SIMULATION.md](https://github.com/kylebrodeur/microfactory-lab/blob/main/chief-engineer/docs/reference/SIMULATION.md).)*"
     )
     policy_html = (f"{before_html}<div style='text-align:center;color:var(--ao-orange);font-size:11px;"
                    f"letter-spacing:2px;'>{icon('arrow')} LEARNED</div>{policy_cell_html(after, key)}")
@@ -1144,6 +1145,18 @@ def build() -> gr.Blocks:
         footer = gr.HTML(footer_bar())
         privacy_line = gr.HTML(visible=field_log.is_active())
 
+        # Email signup for Microfactory updates (opt-in, privacy-first)
+        with gr.Group(elem_classes=["ce-card"]):
+            gr.HTML(rule("STAY IN THE LOOP"))
+            gr.HTML("<div class='ce-sub'>Get Microfactory updates: new nodes, build notes, and when this thing learns to stream g-code straight to the printer. One email. No spam. Unsub any time.</div>")
+            with gr.Row():
+                signup_email = gr.Textbox(placeholder="you@example.com", label="EMAIL", show_label=False,
+                                          elem_classes=["ce-notes-inline"], scale=3)
+                signup_consent = gr.Checkbox(label="Yes, email me Microfactory updates", scale=2)
+            signup_btn = gr.Button("SUBSCRIBE", elem_classes=["ce-pillbtn"])
+            signup_status = gr.HTML()
+            signup_privacy = gr.HTML(signups.privacy_notice())
+
         # ── wiring ──
         reset_outs = _reset_outputs(ledger_panel, node_cards, review_summary, p_curve, p_policy,
                                     p_log, p_headline, outcome_panel, results_group, real_log_msg,
@@ -1167,6 +1180,9 @@ def build() -> gr.Blocks:
         demo.load(None, None, None, js=CLOCK_JS)
         demo.load(lambda: field_log.privacy_notice() if field_log.is_active() else "",
                   None, [privacy_line])
+        signup_btn.click(signups.record_signup,
+                         [signup_email, signup_consent, gr.State("space" if signups.is_active() else "local")],
+                         [signup_status])
         roll_btn.click(randomize_sensors, None, sensor_outs).then(status_footer, foot_in, [footer])
         for c in (temp, humidity, bed_position, material):
             c.change(sync_readout, [temp, humidity, bed_position], [sensors_readout]).then(

core/signups.py

@@ -0,0 +1,114 @@
+"""Email signup for Microfactory updates.
+
+Lightweight, privacy-first opt-in collection. Stores one JSONL row per signup:
+{ts, email, consent, source, app_version}. Local runs write to data/signups.jsonl.
+Space runs can additionally push to a private HF dataset via CommitScheduler if
+SIGNUPS_DATASET and HF_TOKEN are set. Never writes without explicit consent.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import threading
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+SIGNUPS_FILE = Path(__file__).resolve().parent.parent / "data" / "signups.jsonl"
+SIGNUPS_DATASET = os.environ.get("SIGNUPS_DATASET", "kylebrodeur/microfactory-signups").strip()
+FLUSH_MINUTES = 5
+
+_scheduler: Any = None
+_lock = threading.Lock()
+
+_EMAIL_RE = re.compile(r"^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$")
+
+
+def _get_scheduler():
+    """Lazy-init CommitScheduler for the private signup dataset."""
+    global _scheduler
+    token = os.environ.get("HF_TOKEN", "").strip()
+    if not token:
+        return None
+    if not SIGNUPS_DATASET or "/" not in SIGNUPS_DATASET:
+        return None
+    if _scheduler is None:
+        with _lock:
+            if _scheduler is None:
+                try:
+                    from huggingface_hub import CommitScheduler
+                except ImportError:
+                    return None
+                SIGNUPS_FILE.parent.mkdir(parents=True, exist_ok=True)
+                if not SIGNUPS_FILE.exists():
+                    SIGNUPS_FILE.write_text("", encoding="utf-8")
+                _scheduler = CommitScheduler(
+                    repo_id=SIGNUPS_DATASET,
+                    repo_type="dataset",
+                    folder_path=str(SIGNUPS_FILE.parent),
+                    every=FLUSH_MINUTES,
+                    token=token,
+                    allow_patterns=["signups.jsonl"],
+                )
+    return _scheduler
+
+
+def is_active() -> bool:
+    """True if signup syncing to HF is configured and active."""
+    return _get_scheduler() is not None
+
+
+def validate_email(email: str) -> str | None:
+    """Return normalized email or None if invalid."""
+    if not email:
+        return None
+    email = email.strip().lower()
+    if not _EMAIL_RE.match(email):
+        return None
+    return email
+
+
+def record_signup(email: str, consent: bool, source: str = "local") -> tuple[bool, str]:
+    """Record one signup. Returns (ok, message).
+
+    Requires explicit consent. Email is validated. Writes locally always;
+    pushes to HF only when HF_TOKEN + SIGNUPS_DATASET are present.
+    """
+    if not consent:
+        return False, "Please check the box to opt in before submitting."
+    normalized = validate_email(email)
+    if normalized is None:
+        return False, "Enter a valid email address."
+
+    row = {
+        "ts": datetime.now(timezone.utc).isoformat(),
+        "email": normalized,
+        "consent": True,
+        "source": source,
+        "app_version": os.environ.get("CHIEF_ENGINEER_VERSION", "0.1.0"),
+    }
+
+    try:
+        SIGNUPS_FILE.parent.mkdir(parents=True, exist_ok=True)
+        with _lock:
+            with SIGNUPS_FILE.open("a", encoding="utf-8") as f:
+                f.write(json.dumps(row, ensure_ascii=False) + "\n")
+        sched = _get_scheduler()
+        if sched is not None:
+            try:
+                sched.trigger()
+            except Exception:
+                pass
+        return True, "You're on the list. Microfactory updates will hit that inbox."
+    except Exception as e:
+        return False, f"Could not save signup: {e}"
+
+
+def privacy_notice() -> str:
+    return (
+        "<div class='ce-sub' style='font-size:10px;opacity:0.7;margin-top:4px;'>"
+        "📬 Microfactory updates: one email, no spam, unsub any time. "
+        "We store only your email and this timestamp. No print data, no uploaded files.</div>"
+    )