From b957c7bae35aa757e57033834975ef1ff248d505 Mon Sep 17 00:00:00 2001
From: "Austin L." <86896075+rvnminers-A-and-N@users.noreply.github.com>
Date: Sat, 18 Jul 2026 18:16:59 +0000
Subject: [PATCH] feat: in-app 'How it works' explainer
A collapsible, pitch-friendly panel under the tour chips: structure->numbers,
the six taste heads + two rules, the 24 odor heads with their honest AUROC bar,
the measured/predicted/estimate tagging and data-gates, the Formulation Studio,
and the on-prem / commercial-clean posture. Points to the deeper docs.
Closes the demo-features epic (#179).
Signed-off-by: Austin L. <86896075+rvnminers-A-and-N@users.noreply.github.com>
---
training/workbench.html | 32 ++++++++++++++++++++++++++++++++
1 file changed, 32 insertions(+)
diff --git a/training/workbench.html b/training/workbench.html
index 3b51192..848c2b0 100644
--- a/training/workbench.html
+++ b/training/workbench.html
@@ -312,6 +312,16 @@
.mix-btn{font-family:var(--ui);font-weight:600;font-size:14px;padding:9px 18px;border:none;border-radius:8px;background:var(--accent);color:#fff;cursor:pointer}
.mix-btn:disabled{opacity:.5}
#mixResults{margin-top:14px}
+ /* how it works */
+ .how-grid{display:grid;grid-template-columns:repeat(3,1fr);gap:12px;margin:4px 0 4px}
+ @media(max-width:820px){.how-grid{grid-template-columns:1fr 1fr}}
+ @media(max-width:560px){.how-grid{grid-template-columns:1fr}}
+ .how-card{border:1px solid var(--line);border-radius:10px;padding:12px 14px;background:var(--surface)}
+ .how-card h4{font-family:'Cinzel',Georgia,serif;font-size:13px;margin:0 0 7px;color:var(--brand-2)}
+ .how-card p{font-size:12.5px;line-height:1.55;color:var(--muted);margin:0}
+ .how-card p b{color:var(--ink)}
+ .how-foot{font-size:11.5px;color:var(--muted);margin:11px 2px 0;line-height:1.5}
+ .how-foot b{color:var(--cream)}
/* formulation studio */
.form-ex{font:inherit;font-size:11.5px;padding:3px 10px;border:1px solid var(--line);border-radius:16px;background:transparent;color:var(--brand-2);cursor:pointer}
.form-ex:hover{border-color:var(--brand-2)}
@@ -675,6 +685,22 @@
Flavormancer
+
+
▸ How it works
+ — what's real, what's predicted, and where it gets sharper. Honest by design; a read runs 100% on-prem.
+
+
+
1 · Structure → numbers
Every molecule becomes a 2,048-bit Morgan fingerprint (which substructures it contains) plus a block of physicochemical descriptors (logP, MW, TPSA, H-bonding…). That one shared vector feeds every model — the same structure-to-property representation QSAR has leaned on for decades.
+
2 · Taste — 6 trained heads + 2 rules
Six random-forest classifiers (sweet, bitter, umami…) each return a probability, scored by an honest held-out CV-AUROC. Sour and salty are solution / ionic effects, not molecule-shape ones, so they're transparent rules — not faked models. A sweetness-intensity regressor estimates relative-to-sucrose potency.
+
3 · Aroma — 24 odor heads
One random forest per descriptor (citrus, floral, woody…), trained on public-domain odor text. A head ships only if it clears CV-AUROC ≥ 0.70 — 24 survive, each shown with its own score. It reads presence, not intensity (free text carries none) — an honest ceiling, stated in the UI.
+
4 · Honest by design
Every value is tagged measured / predicted / estimate, so nothing reads as more precise than it is. Where a quantitative feature needs data we can't ship free-commercially (odor thresholds, panel intensities), the UI says so — and it lights up with your data.
+
5 · Formulation, not just molecules
The Formulation Studio reads a whole recipe before you pour — weighting each ingredient by odor impact, aggregating the blend's note-profile, flagging the overpowering component, and closing the gap to your target. That's single-molecule ML turned into a bench tool.
+
6 · On-prem & commercial-clean
Nothing leaves the box — a read makes no cloud calls. The shipped models train only on public-domain or permissively-licensed data, so the commercial edition stays clean (provenance tracked in the repo).
+
+
Deeper dives in the repo: docs/HOW-IT-WORKS.md (the full method) · docs/DATA-SOURCES.md (every source + license) · docs/AROMA.md (the odor heads).
+
+
+
▾ Flavor Studio
— pick any mix of flavors and notes (explained below); Studio ranks the food-safe molecules that carry them, with 2D/3D structures + drop-in swaps.