UX: signpost the queue + guide the first 60 seconds

The demo was technically rich but hard to read on first contact — a flat queue,
domain jargon undefined, the wow buried behind a hunt. This makes the value land
fast without burying the UI in explanations:

  - Queue signposting (lib/display.ts scenarioKind/scenarioBadge + dashboard):
    a "Start here" chip on INV-2042 (price mismatch → the full investigate +
    pause loop), an "exception"/"blocked" badge on the noteworthy rows, and
    NOTHING on clean rows — so the marks draw the eye to the 3-4 cases worth
    running, not a wall of colour.
  - A one-line idle hint at the top of the trace pane pointing at INV-2042
    (the other half of the cue), no second Run button.
  - A "How it works" glossary in the header (gate / 2-3-way match / verdict /
    investigator), closed by default — zero noise for those who know, one line
    each for those who don't, instead of inline tooltips everywhere.
  - The approval pause now says WHY: "Paused — Awaiting <approver>. <variance>."
    composed from the trace (Zod-validated, no cast).

Balance over volume: clean rows stay unmarked, the glossary stays collapsed, no
intro modal, no queue reordering (would break order-aware duplicate detection).
Verified visually (screenshots) and fixed two placement bugs the render exposed.
Test: lib/display.test.ts pins every seeded scenario to the right signpost.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: DylanMerigaud

app/page.tsx

@@ -66,19 +66,81 @@ const Header = () => {
           </p>
         </div>
       </div>
-      <a
-        href="https://github.com/DylanMerigaud/ledgerloop"
-        target="_blank"
-        rel="noreferrer noopener"
-        className="hidden shrink-0 items-center gap-1.5 rounded-full bg-subtle px-3 py-1.5 text-[12px] font-medium text-muted ring-1 ring-inset ring-line-strong transition-colors hover:text-ink sm:inline-flex"
-      >
-        <span className="size-1.5 rounded-full bg-ok" aria-hidden />
-        Live demo · source on GitHub
-      </a>
+      <div className="flex shrink-0 items-center gap-2">
+        <HowItWorks />
+        <a
+          href="https://github.com/DylanMerigaud/ledgerloop"
+          target="_blank"
+          rel="noreferrer noopener"
+          className="hidden items-center gap-1.5 rounded-full bg-subtle px-3 py-1.5 text-[12px] font-medium text-muted ring-1 ring-inset ring-line-strong transition-colors hover:text-ink sm:inline-flex"
+        >
+          <span className="size-1.5 rounded-full bg-ok" aria-hidden />
+          Live demo · source on GitHub
+        </a>
+      </div>
     </header>
   );
 };
 
+/**
+ * An on-demand glossary — closed by default so it adds zero noise for anyone who
+ * knows the domain, and a one-line definition for anyone who doesn't (gate, the
+ * match types, the verdicts, the agent). The terms appear all over the trace and
+ * the workflow; this is the single place they're defined, without peppering the UI
+ * with inline tooltips.
+ */
+const HowItWorks = () => {
+  return (
+    <details className="group relative">
+      <summary className="flex cursor-pointer list-none items-center gap-1.5 rounded-full bg-subtle px-3 py-1.5 text-[12px] font-medium text-muted ring-1 ring-inset ring-line-strong transition-colors hover:text-ink">
+        How it works
+        <span
+          aria-hidden
+          className="text-faint transition-transform group-open:rotate-180"
+        >
+          ▾
+        </span>
+      </summary>
+      <div className="absolute right-0 z-20 mt-2 w-[300px] rounded-xl bg-surface p-3 text-[12px] leading-snug text-muted shadow-lift ring-1 ring-inset ring-line">
+        <dl className="space-y-1.5">
+          <Term name="Gate">
+            an approval step that fires on a condition (amount, variance, …) and
+            pauses for a human.
+          </Term>
+          <Term name="2-way / 3-way match">
+            invoice ↔ PO, or invoice ↔ PO ↔ goods receipt (did we receive it?).
+          </Term>
+          <Term name="Verdict">
+            <span className="text-ink">clean</span> (reconciles),{" "}
+            <span className="text-ink">exception</span> (a variance needs a
+            decision), <span className="text-ink">duplicate</span> (blocked,
+            never paid twice).
+          </Term>
+          <Term name="Investigator">
+            an AI agent that reads messy records on an exception and recommends
+            — a human still decides.
+          </Term>
+        </dl>
+      </div>
+    </details>
+  );
+};
+
+const Term = ({
+  name,
+  children,
+}: {
+  name: string;
+  children: React.ReactNode;
+}) => {
+  return (
+    <div>
+      <dt className="inline font-medium text-ink">{name}: </dt>
+      <dd className="inline">{children}</dd>
+    </div>
+  );
+};
+
 /** Logo mark: an "ll" monogram whose strokes curl into a loop — the ledgerloop
     glyph (matches app/icon.svg). The second stroke is the accent. */
 const LogoMark = () => {

components/dashboard.tsx

@@ -25,6 +25,8 @@ import {
   outcomeDot,
   outcomeLabel,
   outcomeTone,
+  scenarioBadge,
+  scenarioKind,
   type Outcome,
 } from "@/lib/display";
 import { formatMoney } from "@/lib/format";
@@ -115,6 +117,33 @@ const PlayIcon = () => {
   );
 };
 
+/**
+ * The pre-run hint on a queue row: a "Start here" chip on the showcase invoice,
+ * and a coloured badge ONLY for exception/blocked scenarios (clean rows stay
+ * unmarked, so the marks draw the eye to the cases worth running). Renders nothing
+ * for an unmarked clean row.
+ */
+const QueueHint = ({
+  scenario,
+  startHere,
+}: {
+  scenario: string | null;
+  startHere: boolean;
+}) => {
+  const badge = scenarioBadge(scenarioKind(scenario));
+  if (!startHere && !badge) return null;
+  return (
+    <span className="flex shrink-0 items-center gap-1.5">
+      {startHere && (
+        <span className="inline-flex items-center gap-0.5 rounded-full bg-accent-soft px-1.5 py-0.5 text-[10px] font-medium text-accent ring-1 ring-inset ring-accent/20">
+          <span aria-hidden>⚡</span> Start here
+        </span>
+      )}
+      {badge && <Badge tone={badge.tone}>{badge.label}</Badge>}
+    </span>
+  );
+};
+
 /** Small spinner shown while a run is in flight. */
 const Spinner = () => {
   return (
@@ -395,18 +424,20 @@ export const Dashboard = ({
                             {item.poNumber ? ` · ${item.poNumber}` : ""}
                           </span>
                           {/* Once a run is active for the selected row, show its live
-                      outcome badge; otherwise always show the seeded scenario
-                      hint (so selecting a row never blanks the label). */}
+                      outcome badge; otherwise signpost the seeded scenario so the
+                      eye goes to the interesting cases. Only exception/blocked rows
+                      get a coloured badge — clean rows stay unmarked, so the marks
+                      mean something. INV-2042 (price mismatch → investigator +
+                      pause: the full wow) also gets a single "Start here" chip. */}
                           {isSelected && state.status !== "idle" ? (
                             <Badge tone={outcomeTone(outcome)}>
                               {outcomeLabel(outcome)}
                             </Badge>
                           ) : (
-                            item.scenario && (
-                              <span className="shrink-0 text-[10px] text-muted/80">
-                                {item.scenario}
-                              </span>
-                            )
+                            <QueueHint
+                              scenario={item.scenario}
+                              startHere={item.id === "INV-2042"}
+                            />
                           )}
                         </span>
                       </span>
@@ -457,6 +488,16 @@ export const Dashboard = ({
               </p>
             )}
             <RunningAgainst workflow={workflow} />
+            {/* Idle: a one-line "what to do" at the top of the pane (where the eye
+            lands), pointing at the showcase invoice. The queue's "Start here" chip
+            is the other half of the cue. */}
+            {state.status === "idle" && (
+              <p className="mt-1.5 max-w-md text-[11.5px] leading-snug text-muted">
+                {selected?.id === "INV-2042"
+                  ? "Hit Run pipeline — the agent investigates the price variance, then pauses for your approval."
+                  : "New here? Run INV-2042 (the “Start here” row) to see the agent investigate a variance and pause for approval. Clean invoices post straight through."}
+              </p>
+            )}
           </div>
           {state.status === "awaiting" && selected && gates.length >= 2 ? (
             // Several gates pend in parallel — decide each on its node in the graph,
@@ -519,6 +560,7 @@ export const Dashboard = ({
               <Button
                 size="sm"
                 data-testid="run-btn"
+                className="shrink-0 whitespace-nowrap"
                 disabled={state.status === "running"}
                 onClick={() => run(selected.id)}
               >

components/trace-timeline.tsx

@@ -10,6 +10,49 @@ import { formatDuration, humanize } from "@/lib/format";
 import type { TraceEvent } from "@/lib/trace";
 import type { PipelineRunState } from "@/lib/use-pipeline-run";
 
+/**
+ * Compose a one-line reason the run paused, from the trace data already on screen:
+ * which gate(s) are pending (the approval step's `steps`) and why (the top
+ * matching exception's message). Read defensively with `isRecord` — a trace whose
+ * shape we don't recognise just yields no extras, so the banner degrades to the
+ * plain "needs a human decision" rather than guessing. Keeps the pause LEGIBLE
+ * without a paragraph: "Paused at <gate> — <reason>."
+ */
+/* The slices of the trace data this banner reads, Zod-validated so the unknown
+   `data` is narrowed without a cast (same discipline as the rest of the app). */
+const ApprovalData = z.object({
+  steps: z
+    .array(z.object({ status: z.string(), detail: z.string() }))
+    .optional(),
+});
+const MatchingData = z.object({
+  exceptions: z.array(z.object({ message: z.string() })).optional(),
+});
+
+const pauseReason = (trace: TraceEvent[]): string => {
+  const approval = trace.find((e) => e.stage === "approval");
+  const matching = trace.find((e) => e.stage === "matching");
+
+  // Pending gate label — the engine's pending detail reads "Awaiting <approver>…".
+  let gates = "";
+  const ap = ApprovalData.safeParse(approval?.data);
+  if (ap.success) {
+    const pending = (ap.data.steps ?? []).find((s) => s.status === "pending");
+    if (pending) gates = pending.detail.replace(/\.$/, "");
+  }
+
+  // The top exception message (e.g. "Line STL-BAR-20: invoiced at 8.18/unit vs PO
+  // 7.50/unit (9.1% over).") — the "why".
+  let why = "";
+  const mt = MatchingData.safeParse(matching?.data);
+  if (mt.success) why = mt.data.exceptions?.[0]?.message ?? "";
+
+  if (gates && why) return `Paused — ${gates}. ${why}`;
+  if (gates) return `Paused — ${gates}.`;
+  if (why) return `Paused — ${why}`;
+  return "Paused — this invoice needs a human decision.";
+};
+
 /**
  * The execution trace — a vertical timeline streamed in live as the run
  * progresses. Each node is one TraceEvent: the deterministic steps, the
@@ -34,8 +77,8 @@ export const TraceTimeline = ({
         title="Run the pipeline"
         body={
           invoiceLabel
-            ? `Run ${invoiceLabel} through matching, routing, and reconciliation — live. Pick a flagged invoice (price or quantity mismatch) to watch the investigator agent dig into the variance, then pause for your decision.`
-            : "Select an invoice to begin. Flagged ones — a price or quantity mismatch — trigger the investigator agent and pause for your decision."
+            ? `Run ${invoiceLabel} through matching, routing, and reconciliation — live.`
+            : "Select an invoice to begin."
         }
         action={
           canRun ? (
@@ -80,8 +123,7 @@ export const TraceTimeline = ({
 
       {state.status === "awaiting" && (
         <div className="ml-8 mt-1 rounded-lg bg-warn-soft/60 px-3 py-2 text-[12px] text-warn ring-1 ring-inset ring-warn-line">
-          Paused — this invoice needs a human decision. Approve or reject it
-          above to continue.
+          {pauseReason(state.trace)} Approve or reject above to continue.
         </div>
       )}
 

lib/display.test.ts

@@ -0,0 +1,65 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { SEED_BUNDLES } from "@/db/seed-data";
+import { scenarioKind, scenarioBadge } from "@/lib/display";
+
+/**
+ * The queue signposting helpers — what marks a seeded row BEFORE it's run, so a
+ * first-time visitor's eye lands on the interesting cases. Classification is
+ * derived from the scenario label; these pin that every seeded scenario lands in
+ * the right bucket (a mislabel would mark a clean row as an exception, or hide a
+ * blocked one).
+ */
+
+test("classifies the variance/control scenarios as exceptions", () => {
+  for (const s of [
+    "Price mismatch",
+    "Quantity mismatch",
+    "Arithmetic error",
+    "Line not on PO",
+    "Inactive vendor (ERP)",
+  ]) {
+    assert.equal(scenarioKind(s), "exception", s);
+  }
+});
+
+test("classifies the duplicate scenarios as blocked", () => {
+  assert.equal(scenarioKind("Duplicate invoice"), "blocked");
+  assert.equal(scenarioKind("Already paid (ERP duplicate)"), "blocked");
+});
+
+test("classifies clean matches (and the paid original) as clean", () => {
+  for (const s of [
+    "Clean 3-way match",
+    "Clean 2-way (services)",
+    "Original (paid)",
+    null,
+  ]) {
+    assert.equal(scenarioKind(s), "clean", String(s));
+  }
+});
+
+test("scenarioBadge marks exception (warn) and blocked (danger), not clean", () => {
+  assert.deepEqual(scenarioBadge("exception"), {
+    tone: "warn",
+    label: "exception",
+  });
+  assert.deepEqual(scenarioBadge("blocked"), {
+    tone: "danger",
+    label: "blocked",
+  });
+  // Clean rows stay unmarked, so the marks draw the eye.
+  assert.equal(scenarioBadge("clean"), null);
+});
+
+test("every seeded scenario classifies without falling through wrongly", () => {
+  // A guard against a future seed label that the classifier would silently treat
+  // as clean when it's actually an exception/blocked. We assert the known kinds
+  // line up with the labels the demo depends on.
+  const byId = new Map(SEED_BUNDLES.map((b) => [b.id, b.scenario]));
+  assert.equal(scenarioKind(byId.get("INV-2042") ?? null), "exception"); // price
+  assert.equal(scenarioKind(byId.get("INV-2048") ?? null), "exception"); // qty
+  assert.equal(scenarioKind(byId.get("INV-1990") ?? null), "blocked"); // already paid
+  assert.equal(scenarioKind(byId.get("INV-2040") ?? null), "clean"); // clean 3-way
+});

lib/display.ts

@@ -63,6 +63,47 @@ export const outcomeDot = (outcome: Outcome): string => {
   }
 };
 
+/**
+ * How a SEEDED scenario should be signposted in the queue BEFORE it's run — so a
+ * first-time visitor's eye goes straight to the interesting cases instead of a
+ * flat list. Derived from the scenario label (already on every QueueItem), not a
+ * new query. Three kinds, deliberately coarse:
+ *   • "exception" — a flagged invoice (variance / control) that routes to a human
+ *   • "blocked"   — a duplicate that's stopped before approval
+ *   • "clean"     — a straight-through match (gets NO badge; only the noteworthy
+ *                   rows are marked, so the marks mean something)
+ */
+export type ScenarioKind = "exception" | "blocked" | "clean";
+
+export const scenarioKind = (scenario: string | null): ScenarioKind => {
+  const s = (scenario ?? "").toLowerCase();
+  if (s.includes("duplicate") || s.includes("already paid")) return "blocked";
+  if (
+    s.includes("mismatch") ||
+    s.includes("error") ||
+    s.includes("not on po") ||
+    s.includes("inactive")
+  ) {
+    return "exception";
+  }
+  return "clean";
+};
+
+/** The badge tone + short label for a signposted scenario kind (queue, pre-run).
+ *  `clean` returns null — clean rows stay unmarked so the marks draw the eye. */
+export const scenarioBadge = (
+  kind: ScenarioKind,
+): { tone: BadgeTone; label: string } | null => {
+  switch (kind) {
+    case "exception":
+      return { tone: "warn", label: "exception" };
+    case "blocked":
+      return { tone: "danger", label: "blocked" };
+    case "clean":
+      return null;
+  }
+};
+
 /** Map a trace step's status to a badge tone (for the timeline). */
 export const statusTone = (status: TraceStatus): BadgeTone => {
   switch (status) {