@polycode-projects/the-mechanical-code-talker 5.0.5 → 5.0.7

package/src/services/code-explorer-viz.mjs

@@ -19,7 +19,7 @@
 // sidebar/centre grid, so a later panel is one more <section class="panel">,
 // not a re-architecture.
 
-import { THEME_TOKENS_CSS, SERIF_STACK, MONO_STACK, escapeHtml, embedJson, embedScriptText } from "./viz-theme.mjs";
+import { THEME_TOKENS_CSS, SERIF_STACK, MONO_STACK, escapeHtml, embedJson, embedScriptText, demoEyebrowHtml, EYEBROW_LINKS_CSS } from "./viz-theme.mjs";
 import { generateCodeHints } from "../domain/code-explorer-hints.mjs";
 import { phraseForRelation } from "../domain/ask-vocab.mjs";
 import { fetchWithProgress } from "./memory-panel-viz.mjs";
@@ -483,6 +483,7 @@ body { margin: 0; overflow: hidden; background: var(--bg); color: var(--ink); fo
 .titlebar { display: flex; align-items: center; gap: 0.7rem; flex-wrap: wrap; padding: 0.5rem 0.9rem; background: var(--card); border-bottom: 1px solid var(--line); box-shadow: inset 0 -2px 0 var(--entail-soft); }
 .titlebar .mark { width: 15px; height: 15px; color: var(--entail); flex: none; }
 .titlebar h1 { font-size: 0.95rem; margin: 0; font-weight: 600; letter-spacing: 0.02em; }
+${EYEBROW_LINKS_CSS}
 .titlebar .sub { color: var(--muted); font-size: 0.76rem; font-family: ${MONO_STACK}; }
 .titlebar .sub a { color: var(--corpus); }
 /* the fact count sits in the titlebar, not the footer status bar: it is what
@@ -544,7 +545,7 @@ ul.rows { list-style: none; margin: 0; padding: 0; }
 <div class="shell">
   <header class="titlebar">
     <svg class="mark" viewBox="0 0 16 16" aria-hidden="true"><path fill="currentColor" d="M8 0l1 2.3a5.8 5.8 0 0 1 1.9.8L13.3 2l.7.7-1.1 2.4c.4.6.6 1.2.8 1.9L16 8l-2.3 1a5.8 5.8 0 0 1-.8 1.9l1.1 2.4-.7.7-2.4-1.1a5.8 5.8 0 0 1-1.9.8L8 16l-1-2.3a5.8 5.8 0 0 1-1.9-.8L2.7 14l-.7-.7 1.1-2.4a5.8 5.8 0 0 1-.8-1.9L0 8l2.3-1c.2-.7.4-1.3.8-1.9L2 2.7l.7-.7 2.4 1.1A5.8 5.8 0 0 1 7 2.3L8 0zm0 5.2A2.8 2.8 0 1 0 8 10.8 2.8 2.8 0 0 0 8 5.2z"/></svg>
-    <h1>tmct code explorer</h1>
+    <h1>${demoEyebrowHtml("code", "code explorer")}</h1>
     <span class="sub">source: <span id="source-name">${escapeHtml(sourceName)}</span></span>
     <span class="factpill" id="fact-total" aria-live="polite" title="every fact this page's chat can draw on — the code graph's own edges plus the general-knowledge seed once it lands">
       <span class="factpill-value" id="fact-total-value">&mdash;</span> facts loaded

package/src/services/extract-facts.mjs

@@ -92,12 +92,23 @@ export function parseArgs(argv) {
  */
 async function runSentence(sentence, { config, memoryDir }) {
   const before = readFactRows(await loadMemory(memoryDir));
-  const { record } = await runTurn(sentence, { config, memoryDir, sessionId: uuidv7() });
-  if (record?.via !== "assert" || record?.miss) return { recognized: false, rows: [] };
+  const { record, answer } = await runTurn(sentence, { config, memoryDir, sessionId: uuidv7() });
+  if (record?.via !== "assert" || record?.miss) return { recognized: false, rows: [], decline: String(answer || "") };
   const after = readFactRows(await loadMemory(memoryDir));
   return { recognized: true, rows: touchedFactRows(before, after) };
 }
 
+/** The recognizer's own words for why it turned a sentence down, when it named
+ *  an ungrounded term rather than the sentence's shape. "A wombat is a
+ *  marsupial." is the same shape as "A kestrel is a bird.", which IS recognized;
+ *  the difference is that "bird" is in the vocabulary and "marsupial" is not, so
+ *  reporting every skip as an unrecognized shape blames the wrong thing. */
+const UNGROUNDED_TERM_DECLINE_RE = /I don't recognize ((?:"[^"]+"(?:\s+(?:and|or)\s+)?)+) as (?:a )?words? I know/i;
+const ungroundedTermsIn = (decline) => {
+  const m = String(decline || "").match(UNGROUNDED_TERM_DECLINE_RE);
+  return m ? m[1].match(/"([^"]+)"/g).map((q) => q.slice(1, -1)) : null;
+};
+
 // The copula lemmas that read as class membership; a following noun phrase is
 // the class the subject is-a. "has/have" and other verbs are relations, not isa.
 const OPTIMISTIC_COPULAS = new Set(["is", "are", "was", "were", "be", "been", "being", "am"]);
@@ -541,11 +552,17 @@ export async function ingestText(text, {
   let sentenceCount = 0;
   let recognizedSentences = 0;
   let optimisticSentences = 0;
+  // The terms a skipped sentence named that nothing grounds yet. Reported with
+  // the skip count so the summary names the real obstacle instead of blaming
+  // the sentence's shape for a shape it actually recognizes.
+  const ungroundedTerms = new Set();
 
   // One recognized read of some text form: null when the strict recognizer
   // grounds nothing, else the Fact rows it touched.
+  let lastDecline = "";
   const strictRows = async (form) => {
-    const { recognized, rows } = await runSentence(form, { config: cfg, memoryDir: dir });
+    const { recognized, rows, decline } = await runSentence(form, { config: cfg, memoryDir: dir });
+    if (!recognized) lastDecline = decline || lastDecline;
     return recognized && rows.length ? rows : null;
   };
 
@@ -557,6 +574,7 @@ export async function ingestText(text, {
       let carrySubject = null;
       for (const sentence of splitSentencesPreservingPaths(paragraph)) {
         sentenceCount += 1;
+        lastDecline = "";
         const cleaned = stripCitationResidue(sentence);
         // Whole sentence first, then each closed-marker clause as a fallback.
         let rows = null;
@@ -592,6 +610,8 @@ export async function ingestText(text, {
           }
           continue;
         }
+        const ungrounded = ungroundedTermsIn(lastDecline);
+        if (ungrounded) for (const term of ungrounded) ungroundedTerms.add(term);
         if (!optimistic) continue;
         const candidates = optimisticTriples(cleaned, { lexicon: lex, nlp });
         if (!candidates.length) continue;
@@ -612,6 +632,7 @@ export async function ingestText(text, {
       extracted,
       optimistic: optimisticFacts,
       skipped: sentenceCount - recognizedSentences - optimisticSentences,
+      ungroundedTerms: [...ungroundedTerms],
     };
     if (canonical) {
       result.canonical = canonicalLines([...extracted, ...optimisticFacts], readFactRows(await loadMemory(dir)));
@@ -641,9 +662,23 @@ export async function main(argv = process.argv.slice(2)) {
   const filePath = resolve(process.cwd(), file);
   const text = await readFile(filePath, "utf8");
   const sourceTag = basename(filePath);
-  const memoryDir = repo ? resolve(process.cwd(), repo) : null;
+  // A repo path is not a store handle. Resolve the SAME backend every other verb
+  // reads back through, or the facts land in the retired flat file and the
+  // "facts written into …" line below reports a write chat can never see.
+  const repoRoot = repo ? resolve(process.cwd(), repo) : null;
+  const { openConfiguredMemoryBackend } = await import("../adapters/memory/core.mjs");
+  const store = repoRoot ? await openConfiguredMemoryBackend(repoRoot) : null;
 
-  const result = await ingestText(text, { memoryDir, sourceTag, optimistic, canonical });
+  let result;
+  try {
+    result = await ingestText(text, {
+      memoryDir: store ? store.dir : null,
+      config: repoRoot ? loadConfig(process.env, repoRoot) : null,
+      sourceTag, optimistic, canonical,
+    });
+  } finally {
+    if (store) await store.close();
+  }
   const emitted = optimistic ? [...result.extracted, ...result.optimistic] : result.extracted;
 
   if (out) {
@@ -663,9 +698,14 @@ export async function main(argv = process.argv.slice(2)) {
     + `(${result.extracted.length} fact row${result.extracted.length === 1 ? "" : "s"})`
     + (optimistic ? `, ${optimisticCount} optimistic candidate${optimisticCount === 1 ? "" : "s"}` : "")
     + `, ${result.skipped} skipped — not a recognized declarative shape (an honest, expected gap; this is `
-    + `an attempt, not full NLU).`,
+    + `an attempt, not full NLU).`
+    + (result.ungroundedTerms?.length
+      ? `\nSome of those skips were shapes I do read, held up by terms nothing grounds yet: `
+        + `${result.ungroundedTerms.map((t) => `"${t}"`).join(", ")}. `
+        + `Ground one side first (e.g. "every ${result.ungroundedTerms[0]} is a thing") and re-run.`
+      : ""),
   );
-  if (repo) console.error(`facts written into ${memoryDir}'s tmct memory, tagged ${sourceTag}`);
+  if (repo) console.error(`facts written into ${repoRoot}'s tmct memory, tagged ${sourceTag}`);
   if (out) console.error(`facts written to ${out}`);
   return { sentences, recognized, extracted: result.extracted, optimistic: result.optimistic, skipped: result.skipped };
 }

package/src/services/ingest-viz.mjs

@@ -25,12 +25,13 @@
 // renderIngestHtml() is pure: no I/O, deterministic output for identical
 // input. scripts/build-demo-site.mjs calls it directly and writes the result
 // to public/ingest.html, after ingest-browser.bundle.js already exists.
-import { THEME_TOKENS_CSS, SERIF_STACK, MONO_STACK, escapeHtml } from "./viz-theme.mjs";
+import { THEME_TOKENS_CSS, SERIF_STACK, MONO_STACK, escapeHtml, demoEyebrowHtml, EYEBROW_LINKS_CSS } from "./viz-theme.mjs";
 import {
   bandLabelFor,
   statsSummaryLine,
   clearSiteAssetCaches,
   fetchWithProgress,
+  loadSeedPayload,
   renderStatsPanelInto,
   loadProgressLine,
   factTripleParts,
@@ -43,7 +44,7 @@ const DEFAULT_TITLE = "the-mechanical-code-talker — ingest";
 /** The self-contained ingest page. Pure — the same output for the same
  *  `title` every time; every piece of state (the session, each grounded fact)
  *  is computed live in the browser once the sibling ingest bundle loads. */
-export function renderIngestHtml({ title = DEFAULT_TITLE, seedStamp = "" } = {}) {
+export function renderIngestHtml({ title = DEFAULT_TITLE, seedStamp = "", seedBytes = 0 } = {}) {
   return `<!doctype html>
 <html lang="en">
 <head>
@@ -75,7 +76,8 @@ ${THEME_TOKENS_CSS}
   header.topbar { flex: 0 0 auto; display: flex; align-items: center; justify-content: space-between; gap: 1rem; padding: .7rem 1.1rem; border-bottom: 1px solid var(--line); flex-wrap: wrap; }
   .brand { display: flex; flex-direction: column; gap: .1rem; }
   .eyebrow { font-family: ${MONO_STACK}; font-size: .78rem; letter-spacing: .08em; color: var(--muted); }
-  .subtitle { font-size: .82rem; color: var(--muted); }
+  ${EYEBROW_LINKS_CSS}
+  .subtitle { margin: 0; font-size: .82rem; font-weight: 400; color: var(--muted); }
 
   /* the live memory count, in the topbar rather than the status line: it is
      the one number that says what this page's memory actually holds, and the
@@ -83,6 +85,14 @@ ${THEME_TOKENS_CSS}
   .topbar-right { display: flex; align-items: center; gap: .7rem; }
   .fact-pill { display: inline-flex; align-items: baseline; gap: .34rem; font-family: ${MONO_STACK}; font-size: .66rem; letter-spacing: .06em; text-transform: uppercase; color: var(--muted); border: 1px solid var(--corpus-t1); border-radius: 99px; padding: .2rem .8rem; background: var(--corpus-soft); white-space: nowrap; }
   .fact-pill .fact-pill-value { font-size: .94rem; letter-spacing: 0; font-variant-numeric: tabular-nums; font-weight: 600; color: var(--ink); }
+  /* While the starter memory streams in, the pill says so and breathes — the
+     same three-state pill chat.html carries, for the same reason: what this
+     page knows grows while you watch it. */
+  .fact-pill[data-state="loading"] { animation: pill-breathe 1.6s ease-in-out infinite; }
+  .fact-pill[data-state="loading"] .fact-pill-value { font-size: .66rem; letter-spacing: .06em; text-transform: uppercase; font-weight: 600; }
+  .fact-pill[data-state="failed"] { border-color: var(--miss-t1, var(--corpus-t1)); }
+  @keyframes pill-breathe { 0%, 100% { opacity: 1; } 50% { opacity: .55; } }
+  @media (prefers-reduced-motion: reduce) { .fact-pill[data-state="loading"] { animation: none; } }
 
   /* mode pills — Text | Document — the translate-tool idiom: two segments in
      one rounded track, the active one filled. */
@@ -181,13 +191,13 @@ ${THEME_TOKENS_CSS}
   <div class="ingestCol">
     <header class="topbar">
       <div class="brand">
-        <span class="eyebrow">the-mechanical-code-talker</span>
-        <span class="subtitle">ingest &mdash; paste or drop text. It keeps the facts it can ground and skips the rest.</span>
+        <span class="eyebrow">${demoEyebrowHtml("ingest", "ingest")}</span>
+        <h1 class="subtitle">ingest &mdash; paste or drop text. It keeps the facts it can ground and skips the rest.</h1>
       </div>
       <div class="topbar-right">
-        <span class="fact-pill" id="factPill" aria-live="polite"
+        <span class="fact-pill" id="factPill" aria-live="polite" data-state="loading"
           title="every fact this page's memory holds right now — the starter memory it booted with plus everything it has grounded since">
-          <span class="fact-pill-value" id="factPillValue">&mdash;</span> facts in memory
+          <span class="fact-pill-value" id="factPillValue">loading</span><span id="factPillUnit"> starter memory&hellip;</span>
         </span>
         <div class="pills" role="group" aria-label="Input mode">
           <button type="button" id="modeText" aria-pressed="true">Text</button>
@@ -253,6 +263,7 @@ ${THEME_TOKENS_CSS}
   const statsSummaryLine = ${statsSummaryLine.toString()};
   const clearSiteAssetCaches = ${clearSiteAssetCaches.toString()};
   const fetchWithProgress = ${fetchWithProgress.toString()};
+  const loadSeedPayload = ${loadSeedPayload.toString()};
   const renderStatsPanelInto = ${renderStatsPanelInto.toString()};
   const el = (id) => document.getElementById(id);
 
@@ -274,7 +285,9 @@ ${THEME_TOKENS_CSS}
   const seedToggleEl = el("seedToggle");
   const fuzzyToggleEl = el("fuzzyToggle");
   const statsPanelEl = el("statsPanel");
+  const factPillEl = el("factPill");
   const factPillValueEl = el("factPillValue");
+  const factPillUnitEl = el("factPillUnit");
   const askFormEl = el("askForm");
   const askInputEl = el("askq");
   const askGoBtn = el("askGo");
@@ -469,7 +482,8 @@ ${THEME_TOKENS_CSS}
       try { stats = await window.tmct.page.memoryStats(session.memoryDir); }
       catch { return; }
     }
-    factPillValueEl.textContent = Number(stats.total || 0).toLocaleString();
+    lastStatsTotal = Number(stats.total || 0);
+    renderFactPill();
     renderStatsPanelInto(statsPanelEl, stats, {
       bandLabel: bandLabelFor,
       taughtHint: "nothing yet. Ingest some text and its grounded facts land here, with their source.",
@@ -495,6 +509,12 @@ ${THEME_TOKENS_CSS}
   // ever return the copy this page asked for. Empty in a build with no seed.
   const SEED_STAMP = ${JSON.stringify(seedStamp)};
   const SEED_QUERY = SEED_STAMP ? "?b=" + SEED_STAMP : "";
+  // The builder's own measurement of chat-seed.json, in decompressed bytes.
+  // The response cannot supply this: over a compressed transfer Content-Length
+  // is the wire size while the stream yields decompressed bytes, so the two
+  // are not the same quantity. Both numbers in the percentage below are
+  // decompressed bytes, which is what makes it a real fraction.
+  const SEED_BYTES = ${Number(seedBytes) || 0};
 
   let seedPayload = null;
   let seedFacts = 0;
@@ -508,29 +528,89 @@ ${THEME_TOKENS_CSS}
   // The one branch this page's seed choice makes: checked, fetch and parse
   // the same chat-seed.json chat.html embeds; unchecked, skip the request
   // outright and stay on the previous empty-store fast path.
-  //
-  // One retry with a cache-busting query param: a CDN edge can serve a
-  // corrupted or truncated precompressed response (a transient bad cache
-  // entry, not a code defect — real bytes decompress fine, and the same URL
-  // fetched moments later is clean), and JSON.parse throwing is the only
-  // signal of that. The bust param forces a fresh fetch past that one entry.
+  let seedLoadedBytes = 0;
+  let seedTotalBytes = SEED_BYTES;
+  let seedPercentShown = -1;
+  let lastStatsTotal = null;
+
+  /**
+   * What the starter memory is doing right now, published as tmct.seed —
+   * loading, indexing, ready, failed, or skipped when the seed toggle is off.
+   * The same five phases chat.html publishes, for the same reasons: the pill
+   * can say the memory is still growing, and a test that asserts on seeded
+   * content can wait for "ready" instead of guessing.
+   */
+  function setSeedPhase(phase, extra) {
+    window.tmct.seed = Object.assign({ state: phase, facts: seedFacts }, extra || {});
+    renderFactPill();
+  }
+  setSeedPhase("loading");
+
+  function noteSeedBytes(loaded, total) {
+    seedLoadedBytes = loaded;
+    seedTotalBytes = total;
+    const percent = seedProgressPercent();
+    if (percent === seedPercentShown) return;
+    seedPercentShown = percent;
+    renderFactPill();
+  }
+
+  /** Real progress, 0-100, or null when no true total is known — the pill then
+   *  shows that it is loading and no number, never a figure inferred from how
+   *  long it has been going. */
+  function seedProgressPercent() {
+    if (!(seedTotalBytes > 0)) return null;
+    return Math.min(100, Math.floor((seedLoadedBytes / seedTotalBytes) * 100));
+  }
+
+  function renderFactPill() {
+    const seedState = window.tmct.seed ? window.tmct.seed.state : "loading";
+    if (seedState === "loading") {
+      const percent = seedProgressPercent();
+      factPillEl.dataset.state = "loading";
+      factPillValueEl.textContent = percent === null ? "loading" : percent + "%";
+      factPillUnitEl.textContent = percent === null ? " starter memory\\u2026" : " of starter memory";
+      return;
+    }
+    // "ready" lands a moment before the first memoryStats read returns, and
+    // there is no count to show until it does. Holding the indexing words over
+    // that gap keeps the pill from flashing a zero it does not mean.
+    if (seedState === "indexing" || (seedState === "ready" && lastStatsTotal === null)) {
+      factPillEl.dataset.state = "loading";
+      factPillValueEl.textContent = "indexing";
+      factPillUnitEl.textContent = " " + seedFacts.toLocaleString() + " facts\\u2026";
+      return;
+    }
+    if (seedState === "failed" && lastStatsTotal === null) {
+      factPillEl.dataset.state = "failed";
+      factPillValueEl.textContent = "no";
+      factPillUnitEl.textContent = " starter memory";
+      return;
+    }
+    factPillEl.dataset.state = seedState === "failed" ? "failed" : "ready";
+    factPillValueEl.textContent = Number(lastStatsTotal || 0).toLocaleString();
+    factPillUnitEl.textContent = " facts in memory";
+  }
+
   async function fetchSeedIfWanted() {
-    if (!seedToggleEl.checked) { seedPayload = null; seedFacts = 0; return; }
-    for (let attempt = 1; attempt <= 2; attempt++) {
-      try {
-        const bust = attempt === 1 ? "" : (SEED_QUERY ? "&" : "?") + "retry=1";
-        const blob = await fetchWithProgress("./chat-seed.json" + SEED_QUERY + bust, (loaded, total) => noteProgress("seed", loaded, total));
-        seedPayload = JSON.parse(await blob.text());
-        seedFacts = (seedPayload.individuals || []).filter((i) => i.class === "Fact").length;
-        return;
-      } catch (err) {
-        if (attempt === 2) {
-          seedPayload = null;
-          seedFacts = 0;
-          console.warn("tmct ingest: chat-seed.json unavailable — starting unseeded", err);
-        }
-      }
+    if (!seedToggleEl.checked) {
+      seedPayload = null;
+      seedFacts = 0;
+      setSeedPhase("skipped");
+      return;
+    }
+    const outcome = await loadSeedPayload(fetchWithProgress, "./chat-seed.json", SEED_QUERY, (loaded, total) => {
+      noteProgress("seed", loaded, total || SEED_BYTES);
+      noteSeedBytes(loaded, total || SEED_BYTES);
+    });
+    seedPayload = outcome.payload;
+    seedFacts = outcome.status.facts;
+    if (outcome.status.state === "failed") {
+      console.error("tmct ingest: chat-seed.json unavailable — starting unseeded (" + outcome.status.error + ")");
+      setSeedPhase("failed", { error: outcome.status.error, attempts: outcome.status.attempts });
+      return;
     }
+    setSeedPhase("indexing", { attempts: outcome.status.attempts });
   }
   const cloneMemoryPayload = ${cloneMemoryPayload.toString()};
   async function newSession() {
@@ -609,6 +689,7 @@ ${THEME_TOKENS_CSS}
     session = await newSession();
     clearFactsPane();
     askLogEl.textContent = "";
+    if (window.tmct.seed.state === "indexing") setSeedPhase("ready");
     const stats = await window.tmct.page.memoryStats(session.memoryDir);
     statusEl.textContent = statsSummaryLine(stats, bandLabelFor) + ". Ready.";
     await renderStatsPanel(stats);
@@ -639,6 +720,9 @@ ${THEME_TOKENS_CSS}
     setMode(false);
     updateIngestEnabled();
     updateAskEnabled();
+    // The session holds the seed now, so the phase settles here rather than
+    // when the bytes landed: "ready" means queryable.
+    if (window.tmct.seed.state === "indexing") setSeedPhase("ready");
     const stats = await window.tmct.page.memoryStats(session.memoryDir);
     const winkPart = winkStatus === "loaded"
       ? "wink-nlp: loaded"

package/src/services/ledger-viz.mjs

@@ -15,7 +15,7 @@
 // doesn't do: it reads the checked-in chat-dock engine bundle.
 
 import { loadMemory, readFactRows, findContradictions, normFactTerm } from "../adapters/memory/core.mjs";
-import { THEME_TOKENS_CSS, MONO_STACK, escapeHtml, embedJson, countLabel, TOKENS } from "./viz-theme.mjs";
+import { THEME_TOKENS_CSS, MONO_STACK, escapeHtml, embedJson, countLabel, TOKENS, demoEyebrowHtml, EYEBROW_LINKS_CSS } from "./viz-theme.mjs";
 import { createTicker, prefersReducedMotion } from "./viz-ticker.mjs";
 import { bfsLevels } from "../domain/planning.mjs";
 import { pluralOf } from "../domain/inflect.mjs";
@@ -644,7 +644,9 @@ ${DASH_DARK_CHROME_CSS}
   body { margin: 0; background: var(--bg); color: var(--ink); font-family: ${DASH_SANS_STACK}; font-size: 15px; line-height: 1.5; }
   .mono { font-family: ${MONO_STACK}; }
   main { max-width: 1200px; margin: 0 auto; padding: 1.4rem 1.2rem 3rem; }
+  .visually-hidden { position: absolute; width: 1px; height: 1px; margin: -1px; padding: 0; overflow: hidden; clip: rect(0,0,0,0); white-space: nowrap; border: 0; }
   .eyebrow { font-family: ${MONO_STACK}; font-size: .7rem; letter-spacing: .08em; text-transform: uppercase; color: var(--muted); display: flex; flex-wrap: wrap; gap: .4em 1.2em; margin-bottom: .9rem; }
+  ${EYEBROW_LINKS_CSS}
   button { font: inherit; color: inherit; background: none; border: none; padding: 0; cursor: pointer; }
   button:focus-visible, input:focus-visible { outline: 2px solid var(--corpus); outline-offset: 2px; border-radius: 4px; }
   .topbar { display: flex; flex-wrap: wrap; align-items: center; gap: .8rem; background: var(--card); border: 1px solid var(--line); border-radius: 6px; padding: .5rem .7rem; margin-bottom: 1.1rem; }
@@ -789,7 +791,8 @@ ${DASH_DARK_CHROME_CSS}
 </head>
 <body>
 <main>
-  <div class="eyebrow"><span>tmct &middot; memory ledger</span><span id="counts"></span></div>
+  <h1 class="visually-hidden">memory ledger</h1>
+  <div class="eyebrow"><span>${demoEyebrowHtml("ledger", "memory ledger")}</span><span id="counts"></span></div>
   ${dashboardHtml(stats)}
   <div class="topbar">
     <nav class="crumbs" id="crumbs" aria-label="Focus trail"></nav>
@@ -1234,7 +1237,9 @@ ${ledgerBundleAvailable ? `<script src="./ledger-browser.bundle.js"></script>` :
             // hold it), and resolveAnsweredTerm has no way to tell that
             // apart from the term genuinely being discussed.
             const hit = resolveAnsweredTerm(result.answer, q, LEDGER.terms, tmct.page.normFactTerm);
-            if (hit) refocusWithLabel(hit, q);
+            // No label: the breadcrumb falls back to the term itself
+            // (c.label || c.term) rather than showing the whole question.
+            if (hit) refocusWithLabel(hit);
           }
         } catch {
           pending.className = "a miss";
@@ -1437,7 +1442,7 @@ ${ledgerBundleAvailable ? `<script src="./ledger-browser.bundle.js"></script>` :
           // full-stop-terminated, rendered only when the engine deduced one.
           if (data && data.goal) addLine("a goal", "Goal (inferred): " + esc(data.goal.charAt(0).toUpperCase() + data.goal.slice(1)) + ".");
           const hit = resolveAnsweredTerm(answer, q, LEDGER.terms, tmct.page.normFactTerm);
-          if (hit) refocusWithLabel(hit, q);
+          if (hit) refocusWithLabel(hit);
         } else {
           const tips = LEDGER.terms.filter((t) => t.term.length >= 3).slice(0, 2)
             .map((t) => '"what is ' + esc(t.term) + '"').join(" \\u00b7 ");

package/src/services/memory-panel-viz.mjs

@@ -104,6 +104,50 @@ export async function fetchWithProgress(url, onProgress) {
   return new Blob(chunks);
 }
 
+/**
+ * Fetch and parse the starter-memory seed, and say what actually happened.
+ *
+ * Resolves to `{ payload, status }` and never rejects. `payload` is the parsed
+ * seed, or null. `status` is the small, payload-free record a page publishes
+ * as `tmct.seed` and a test reads back:
+ *
+ *   { state: "loaded", facts, attempts }
+ *   { state: "failed", facts: 0, attempts, error }
+ *
+ * The record exists because a seed that failed to download and a store that is
+ * empty on purpose both leave the fact count at zero, and until now nothing
+ * downstream could tell them apart — not the page, which went on answering as
+ * a normal empty chat, and not a test, which could only report the zero. A
+ * page that cannot ground an answer must be able to say WHY it cannot, and
+ * that starts with knowing.
+ *
+ * It resolves rather than throwing because a failed seed is not a failed boot:
+ * you can still teach the page facts of your own. Boot carries on, and the
+ * caller decides what to show.
+ *
+ * Two attempts, the second under a cache-busting query param: a CDN edge can
+ * serve a corrupt, truncated or wrongly-encoded response, and a throw out of
+ * the read or the parse is the only signal of that. `seedQuery` already
+ * carries the build's own content-hash query string, if any, so the bust param
+ * joins with `&` or `?` accordingly.
+ */
+export async function loadSeedPayload(fetcher, url, seedQuery, onProgress) {
+  let lastError = null;
+  for (let attempt = 1; attempt <= 2; attempt++) {
+    try {
+      const bust = attempt === 1 ? "" : (seedQuery ? "&" : "?") + "retry=1";
+      const blob = await fetcher(url + seedQuery + bust, onProgress);
+      const payload = JSON.parse(await blob.text());
+      const facts = (payload.individuals || []).filter((i) => i.class === "Fact").length;
+      return { payload, status: { state: "loaded", facts, attempts: attempt } };
+    } catch (err) {
+      lastError = err;
+    }
+  }
+  const reason = lastError && lastError.message ? lastError.message : String(lastError);
+  return { payload: null, status: { state: "failed", facts: 0, attempts: 2, error: reason } };
+}
+
 /**
  * (Re)render the docked "this session's memory" panel into `panelEl` from a
  * memoryStats() result: a total-facts row, one row per seed band the session

package/src/services/mud-viz.mjs

@@ -76,7 +76,7 @@
 // actually executed, never a race between panes.
 import {
   THEME_TOKENS_CSS, SERIF_STACK, MONO_STACK, escapeHtml, embedJson, embedScriptText, scenarioLabel,
-  wordBeforeCursor, rowsForWorld, appendLogLine,
+  wordBeforeCursor, rowsForWorld, appendLogLine, demoEyebrowHtml, EYEBROW_LINKS_CSS,
 } from "./viz-theme.mjs";
 import { createTicker, createSerialQueue } from "./viz-ticker.mjs";
 import { directedGridLayout, roomGraphSvg, levelsOf, EXIT_DELTA } from "./viz-room-graph.mjs";
@@ -392,7 +392,7 @@ ${MUD_SHARE_SKIN}
 <body>
 <main>
   <header class="mud-topbar">
-    <h1 class="eyebrow">tmct &middot; mud</h1>
+    <h1 class="eyebrow">${demoEyebrowHtml("mud", "mud")}</h1>
     <div class="mud-topbar-actions">
       <button type="button" class="state-pill" id="statePill" aria-expanded="false" aria-controls="netPanel"
               title="whether this burrow is shared with anyone"><i class="state-dot"></i><span id="statePillWord">not shared</span></button>
@@ -406,12 +406,13 @@ ${MUD_SHARE_SKIN}
     <section class="deck" aria-label="simulation controls">
       <div class="deck-controls">
         <button type="button" class="deck-play" id="autoToggle" aria-pressed="false">&#9654; play</button>
+        <button type="button" id="stepBtn">step</button>
         <button type="button" id="resetBtn">reset</button>
 ${scenarioList.length > 1 ? `        <select id="scenarioSelect" class="deck-select" aria-label="which burrow to play">
 ${scenarioList.map((s, i) => `          <option value="${i}"${i === 0 ? " selected" : ""}>${escapeHtml(s.label || scenarioLabel(s.worldPayload?.name))}</option>`).join("\n")}
         </select>` : ""}
         <button type="button" id="editModeBtn" aria-pressed="false">edit</button>
-        <label class="deck-teach" title="With this on, a sentence like &quot;Candle is in the study.&quot; writes a fact into the world instead of running as a command.">
+        <label class="deck-teach" title="With this on, a sentence like &quot;Pebble lies in the garden.&quot; writes a fact into the world instead of running as a command.">
           <input type="checkbox" id="teachToggle">
           teach
         </label>
@@ -590,6 +591,7 @@ const MUD_STYLE = `
   .mono { font-family: ${MONO_STACK}; }
   main { max-width: 1280px; margin: 0 auto; padding: 1.1rem 1.2rem 2.4rem; }
   .eyebrow { font-family: ${MONO_STACK}; font-weight: 500; font-size: .72rem; letter-spacing: .16em; text-transform: uppercase; color: var(--parchment); opacity: .9; margin: 0 0 .8rem; }
+  ${EYEBROW_LINKS_CSS}
 
   /* ---- the header: brand on the left, the sharing chrome on the right ----
      The same arrangement chat.html's topbar holds — sharing is page chrome,
@@ -2091,6 +2093,7 @@ function pageScript() {
   // that could start one is disabled for as long as the editor is open.
   function setPlayControlsEnabled(on) {
     el("autoToggle").disabled = !on;
+    el("stepBtn").disabled = !on || autoOn;
     el("playerCountSlider").disabled = !on;
     el("resetBtn").disabled = !on;
     for (const character of cast) {
@@ -2888,6 +2891,7 @@ function pageScript() {
 
   function wireDeck() {
     const playBtn = el("autoToggle");
+    const stepBtn = el("stepBtn");
     const delaySlider = el("delaySlider");
     const maxTurnsSlider = el("maxTurnsSlider");
     const playerCountSlider = el("playerCountSlider");
@@ -2897,6 +2901,7 @@ function pageScript() {
       autoOn = !autoOn;
       playBtn.setAttribute("aria-pressed", autoOn ? "true" : "false");
       playBtn.textContent = autoOn ? "\\u23F8 pause" : "\\u25B6 play";
+      stepBtn.disabled = autoOn;
       // Every animal in the world, pane or none: the deck's play control is the
       // world running, and an npc has no other control that could start it.
       for (const character of everyone()) {
@@ -2905,6 +2910,19 @@ function pageScript() {
         if (autoOn) ticker.play(); else ticker.pause();
       }
     });
+    // One whole turn: every animal in the world (pane or none, same "everyone"
+    // the play toggle above drives) takes exactly one tick, so every pane's own
+    // "turn N" reading is one higher once every stepOnce() below has settled.
+    // Each character keeps its own independent tick count (mud has no single
+    // shared "round" the way adventure/spider-fly's one-ticker world does), so
+    // stepping the whole deck is stepping every one of those counters once,
+    // not advancing one shared counter by one.
+    stepBtn.addEventListener("click", function () {
+      if (!session || autoOn) return;
+      stepBtn.disabled = true;
+      const steps = everyone().map(function (character) { return ensureTicker(character).stepOnce(); });
+      Promise.all(steps).finally(function () { stepBtn.disabled = autoOn; });
+    });
     delaySlider.addEventListener("input", function () {
       delayMs = Number(delaySlider.value);
       el("delayValue").textContent = delayMs + "ms";