Add metrics key + plain-English legend

app.py

@@ -142,6 +142,48 @@ def board_html(extra=None, sort_key="yield"):
     out.append('<div class="mb-foot">\u03a5 bar is log-scaled \u00b7 MO\u00a7ES leads the field by ~4 orders of magnitude \u00b7 $/1M blended cost (~ = list-price estimate) \u00b7 * = structural estimation \u00b7 volume can\'t buy rank</div>')
     return "".join(out)
 
+# raw token pillars: I=input  O=output  Cw=cache-create  Cr=cache-read
+_METRIC_KEY = [
+    ("\u03a5 yield", "(Cache \u00b7 Output) / Input\u00b2", "the main efficiency score",
+     "How well you reuse stored info (cache) to produce strong output while keeping new "
+     "input low. Squaring input heavily penalizes wasted tokens \u2014 a high \u03a5 means you're "
+     "getting value from smart reuse, not just throwing more data at the model."),
+    ("SNR", "O / (I+O)", "signal-to-noise",
+     "How much useful, meaningful output (signal) you get versus repetitive or low-value "
+     "fluff (noise). Rewards clean, focused generations over long, rambling ones."),
+    ("leverage", "Cr / I", "cache leverage",
+     "How effectively you reuse previously computed results (cache-read) instead of "
+     "recomputing from fresh input. Big \u2018free\u2019 value from smart memory \u2014 the core "
+     "architectural signal that separates a compounding cache from a stateless pipe."),
+    ("velocity", "O / I", "throughput",
+     "Output produced per input token spent \u2014 single-pass processing speed."),
+    ("10x DEV", "log\u2081\u2080(transmission \u00d7 commitment \u00d7 reuse)", "cascade velocity",
+     "How efficiently the run chains steps together \u2014 the 10\u00d710\u00d720 cascade. The three "
+     "factors telescope to Cr/I, so this is the cascade expressed in orders of magnitude "
+     "(log\u2081\u2080 of leverage). Smoother chaining = higher."),
+    ("$/1M", "blended cost / 1M tokens", "across all states",
+     "Average cost per million tokens across input, output, and cache. Efficient "
+     "architecture is also the cheapest. ~ = recomputed at list price."),
+]
+
+def metrics_key_html():
+    """Collapsible legend for the board columns. Definitions match metrics.compute exactly."""
+    rows = "".join(
+        f'<div class="mk-row"><span class="mk-name">{n}</span>'
+        f'<span class="mk-form">{f}</span>'
+        f'<span class="mk-alias">{a}</span>'
+        f'<span class="mk-desc">{d}</span></div>'
+        for n, f, a, d in _METRIC_KEY
+    )
+    return (
+        '<details class="metric-key"><summary>What do these metrics mean? '
+        '<span class="mk-hint">(tap to expand)</span></summary>'
+        '<div class="mk-legend">'
+        '<div class="mk-note">Raw pillars: <b>I</b> input \u00b7 <b>O</b> output \u00b7 '
+        '<b>Cw</b> cache-create \u00b7 <b>Cr</b> cache-read</div>'
+        f'{rows}</div></details>'
+    )
+
 # ---------- profile ----------
 def classify(m):
     if m["non_compounding"]: return "Non-Compounding \u00b7 stateless pipe"
@@ -442,6 +484,7 @@ def _build_demo():
                                        label="Rank by", elem_id="rank-by")
                     lb = gr.HTML(board_html())
                     rank_by.change(resort_board, rank_by, lb)
+                    gr.HTML(metrics_key_html())
                     gr.Markdown("*Curated corpus \u00b7 pasting scores you live but isn't persisted unless you sign in \u00b7 $/1M is a list-price recompute (~) \u00b7 \\* = structural estimation.*", elem_id="moses-foot")
                 with gr.Column(scale=5):
                     gr.Markdown("### Operator profile inspector")

theme.py

@@ -235,6 +235,32 @@ button.primary:hover, #compute-btn:hover { background: #d8a449 !important; }
 
 footer { display: none !important; }
 
+/* ---------- metrics key (collapsible legend under the board) ---------- */
+.metric-key { margin: 10px 2px 0; border: 1px solid #3A3324; border-radius: 6px;
+  background: rgba(196,146,58,0.04); }
+.metric-key summary { cursor: pointer; padding: 9px 12px; color: #C4923A;
+  font-size: 12px; font-weight: 700; letter-spacing: 0.04em; text-transform: uppercase;
+  list-style: none; }
+.metric-key summary::-webkit-details-marker { display: none; }
+.metric-key summary::before { content: "▸ "; color: #8a7f68; }
+.metric-key[open] summary::before { content: "▾ "; }
+.metric-key .mk-hint { color: #8a7f68; font-weight: 400; text-transform: none;
+  letter-spacing: 0; font-size: 11px; }
+.mk-legend { padding: 4px 12px 12px; }
+.mk-note { color: #8a7f68; font-size: 11px; margin: 2px 0 10px; }
+.mk-note b { color: #C4923A; }
+.mk-row { display: grid; grid-template-columns: 96px 150px 130px 1fr; gap: 8px;
+  align-items: baseline; padding: 6px 0; border-top: 1px solid #2c2718; }
+.mk-name { color: #E8E0CF; font-weight: 700; font-size: 12px; }
+.mk-form { color: #C4923A; font-family: ui-monospace, monospace; font-size: 11px; }
+.mk-alias { color: #8a7f68; font-size: 11px; font-style: italic; }
+.mk-desc { color: #a89e85; font-size: 11px; line-height: 1.45; }
+@media (max-width: 700px) {
+  /* stack each metric into a card on phones */
+  .mk-row { grid-template-columns: 1fr; gap: 2px; }
+  .mk-form { font-size: 10px; }
+}
+
 @media (max-width: 700px) {
   /* mobile: collapse both boards to rank · operator · Υ. The numeric middle
      columns drop out entirely instead of being crushed into too-few tracks.