docs: define AUROC, threshold and precision where people actually land

HOW-IT-WORKS.md used CV-AUROC eleven times and never said what it is beyond a parenthetical, and
never mentioned threshold, precision or recall at all — the real explanation lived only in
ACCURACY.md, one click further than most readers go. A six-term glossary now sits at section 0.5,
before any number is used: head, AUROC (0.5 is a coin flip, 1.0 is never wrong), threshold (not a
flat 0.5 — 0.16 to 0.85, fitted per head), precision (when it says yes, how often is it right),
recall, out-of-fold, and confident vs indicative. Two sentences each.

The same glossary, compressed to a definition list, is now a card in the site's own How-it-works
grid, so it reaches someone who will never open the docs folder.

Also tightens the taste wording, which was loose in both places: there are FIVE basic tastes and
SIX taste heads. `tasteless` is a head that predicts the documented absence of taste — genuinely
useful, since it is how you find a clean carrier — but it is not a sixth basic taste, and calling
it one is the kind of small inaccuracy a flavorist would notice immediately.

Signed-off-by: Austin L. <86896075+rvnminers-A-and-N@users.noreply.github.com>

Author: rvnminers-A-and-N

docs/ACCURACY.md

@@ -18,7 +18,7 @@ it believes the answer is yes.
 
 | modality | heads | what they answer |
 |---|---|---|
-| Taste | 6 | sweet, bitter, umami, sour, salty, tasteless |
+| Taste | 6 | the five basics — sweet, bitter, umami, sour, salty — plus `tasteless` |
 | Aroma | 167 | vanilla, citrus, smoky, pine, jasmine… |
 | Mouthfeel | 5 | cooling, warming, pungent, tingling, astringent |
 | Safety | 12 | Tox21 assay screens — caution flags, never a clearance |

docs/HOW-IT-WORKS.md

@@ -17,6 +17,42 @@ the difference between **prediction** and **lookup**, and it's the whole point.
 
 ---
 
+## 0.5. Reading the numbers — a two-sentence glossary
+
+Every head reports the same handful of numbers. They are used throughout this document, and three
+of them are routinely misread, so here is what each one actually means. The long version, with
+worked examples, is in [`ACCURACY.md`](ACCURACY.md).
+
+**Head** — one yes/no expert for one property. *Does this smell like vanilla?* is a head; so is
+*does this taste bitter?* There are 190 of them, and each returns a number from 0 to 1 for how
+strongly it believes the answer is yes.
+
+**AUROC** — a **ranking** score. Hand a head one true vanilla molecule and one non-vanilla: how
+often does it score the vanilla one higher? **0.5 is a coin flip, 1.0 is never wrong.** It says
+nothing about how often the head is right when it actually fires — see precision.
+
+**Threshold** — the score at or above which a head counts as *firing*. It is **not** a flat 0.5;
+each head has its own, fitted on data it never trained on, and they range 0.16–0.85. A head with
+13 examples hedges, so a real `pine` match can land at 0.42 — a shared cut-off would have silently
+withheld it.
+
+**Precision** — **when it says yes, how often is it right?** This is trustworthiness, and it is the
+number AUROC cannot see. A head with 11 positives among 2,403 molecules can score AUROC 0.979 and
+have precision 0.10 — right one time in ten. Both are true of `ginger`.
+
+**Recall** — **of all the real ones, how many did it catch?** This is thoroughness. It trades
+against precision: raise a head's threshold and you get fewer false alarms but more misses.
+
+**Out-of-fold** — scored by a model that never saw that molecule. Every accuracy number here is
+out-of-fold; none of them are a model grading its own homework. See 5-fold cross-validation below.
+
+**Confident vs indicative** — a head may only be called *confident* if it clears **50% precision**;
+it has to be right more often than not. The 73 aroma heads that cannot are shipped as
+**indicative** — they keep their score, their chips and every molecule they find, but they are
+never dressed up as a confident call.
+
+---
+
 ## 1. How a molecule becomes numbers
 
 Everything starts by turning a structure into something math can chew on:

training/workbench.html

@@ -529,6 +529,11 @@
      particular stuck out against the flavor and note chips they sit beside. */
   .atag.mf{border-style:solid;position:relative;padding-left:14px}
   .atag.mf::before{content:'';position:absolute;left:6px;top:50%;width:4px;height:4px;margin-top:-2px;border-radius:50%;background:currentColor}
+  .how-card.gloss .gl{margin:0;display:grid;grid-template-columns:auto 1fr;gap:5px 10px;align-items:baseline}
+  .how-card.gloss dt{font-family:var(--mono);font-size:10.5px;letter-spacing:.04em;text-transform:uppercase;color:var(--accent);white-space:nowrap}
+  .how-card.gloss dd{margin:0;font-size:11.5px;line-height:1.55;color:var(--muted)}
+  .how-card.gloss dd b{color:var(--ink);font-weight:600}
+  @media(max-width:560px){.how-card.gloss .gl{grid-template-columns:1fr;gap:2px}.how-card.gloss dt{margin-top:7px}}
   .ss-why{font-size:11.5px;line-height:1.62;color:var(--muted);margin:2px 0 11px;max-width:74ch}
   .ss-why b{color:var(--ink);font-weight:600}
   .ss-why code{font-family:var(--mono);font-size:10.5px;background:var(--panel);border:1px solid var(--line);border-radius:4px;padding:0 4px}
@@ -826,8 +831,17 @@ <h1>Flavormancer</h1>
         <div class="how-card"><h4>3 · Aroma — 167 odor heads</h4><p>One random forest per descriptor (citrus, floral, woody…), trained on <b>public-domain odor text</b>. A head ships only if it clears <b>CV-AUROC ≥ 0.70</b> — 167 survive, each shown with its own score. It reads <b>presence, not intensity</b> (free text carries none) — an honest ceiling, stated in the UI.</p></div>
         <div class="how-card"><h4>4 · Honest by design</h4><p>Every value is tagged <b>measured / predicted / estimate</b>, 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 <b>says so</b> — and it lights up with <b>your</b> data.</p></div>
         <div class="how-card"><h4>5 · How good is a head, really?</h4><p><b>AUROC alone will lie to you.</b> It measures <i>ranking</i> and is blind to how rare a note is — a head with 11 examples among 2,403 molecules can score <b>0.979</b> and still be right just <b>1 time in 10</b> when it fires. So every head also publishes its <b>precision</b>: when it says yes, how often it's actually right, measured only on molecules it never trained on. Each head gets its <b>own</b> firing threshold (0.16&nbsp;–&nbsp;0.85, not a flat 0.5), fitted so a <b>confident</b> call is right more than half the time. <b>23 heads have never been wrong</b> on unseen molecules; the 73 that can't clear 50% are shown as <b>indicative</b> — hatched bars, kept in full, never dressed up as confident.</p></div>
-        <div class="how-card"><h4>6 · Formulation, not just molecules</h4><p>The <b>Formulation Studio</b> 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.</p></div>
-        <div class="how-card"><h4>7 · On-prem &amp; commercial-clean</h4><p>Nothing leaves the box — a read makes <b>no cloud calls</b>. The shipped models train only on <b>public-domain or permissively-licensed</b> data, so the commercial edition stays clean (provenance tracked in the repo).</p></div>
+        <div class="how-card gloss"><h4>6 · Reading the numbers</h4>
+        <dl class="gl">
+          <dt>AUROC</dt><dd>A <b>ranking</b> score: given one true example and one false one, how often is the true one scored higher? <b>0.5 = coin flip, 1.0 = never wrong.</b> Says nothing about how often a head is right when it fires.</dd>
+          <dt>Threshold</dt><dd>The score at which a head counts as <b>firing</b>. Not a flat 0.5 — each head has its own, fitted on data it never trained on, ranging <b>0.16&nbsp;–&nbsp;0.85</b>.</dd>
+          <dt>Precision</dt><dd><b>When it says yes, how often is it right?</b> Trustworthiness — and the number AUROC can't see.</dd>
+          <dt>Recall</dt><dd><b>Of all the real ones, how many did it catch?</b> Thoroughness. Trades against precision.</dd>
+          <dt>Out&#8209;of&#8209;fold</dt><dd>Scored by a model that <b>never saw that molecule</b>. Every number here is out-of-fold — no model grades its own homework.</dd>
+          <dt>Indicative</dt><dd>A head that can't reach <b>50% precision</b> at any threshold. Kept in full, shown with a hatched bar, never called confident.</dd>
+        </dl></div>
+        <div class="how-card"><h4>7 · Formulation, not just molecules</h4><p>The <b>Formulation Studio</b> 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.</p></div>
+        <div class="how-card"><h4>8 · On-prem &amp; commercial-clean</h4><p>Nothing leaves the box — a read makes <b>no cloud calls</b>. The shipped models train only on <b>public-domain or permissively-licensed</b> data, so the commercial edition stays clean (provenance tracked in the repo).</p></div>
       </div>
       <p class="how-foot">Deeper dives in the repo: <a href="https://github.com/echelonts/flavormancer/blob/main/docs/HOW-IT-WORKS.md" target="_blank" rel="noopener">docs/HOW-IT-WORKS.md</a> (the full method) · <a href="https://github.com/echelonts/flavormancer/blob/main/docs/DATA-SOURCES.md" target="_blank" rel="noopener">docs/DATA-SOURCES.md</a> (every source + license) · <a href="https://github.com/echelonts/flavormancer/blob/main/docs/AROMA.md" target="_blank" rel="noopener">docs/AROMA.md</a> (the odor heads).</p>
     </div>
@@ -2468,7 +2482,7 @@ <h4>Software &amp; type</h4>
     }
     // Taste — the basic tastes, namespaced so they don't collide with the like-named aroma notes
     if(tastes.length){
-      html += `<div class="studio-section"><div class="ss-head"><svg class="ic"><use href="#ic-flavors"/></svg> Taste <span class="ss-sub">what the tongue reads — distinct from a sweet <i>smell</i></span></div><p class="ss-why"><b>Taste is only the five basics</b> the tongue detects — sweet, bitter, umami, sour, salty (plus tasteless). It is a genuinely different channel from smell, which is why <code>taste:sweet</code> and the aroma note <code>sweet</code> are separate heads: vanillin <i>smells</i> sweet without being a sweetener. Use taste to set the backbone, notes to give it character.</p><div class="ss-body">`+
+      html += `<div class="studio-section"><div class="ss-head"><svg class="ic"><use href="#ic-flavors"/></svg> Taste <span class="ss-sub">what the tongue reads — distinct from a sweet <i>smell</i></span></div><p class="ss-why"><b>Taste is the five basics</b> the tongue detects — sweet, bitter, umami, sour, salty. We train <b>six</b> heads: those five plus <code>tasteless</code>, which predicts the documented <i>absence</i> of taste and is how you find a clean carrier. It is a genuinely different channel from smell, which is why <code>taste:sweet</code> and the aroma note <code>sweet</code> are separate heads: vanillin <i>smells</i> sweet without being a sweetener. Use taste to set the backbone, notes to give it character.</p><div class="ss-body">`+
         `<div class="studio-group studio-group-notes">`+
         tastes.map(t=>{const lbl=t.replace(/^taste:/,'');
           // set --chip, don't override border/text colour: the per-taste hue now flows through the