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

package/README.md

@@ -27,6 +27,7 @@ derive by rule from both. Every answer is either grounded or an honest miss.
 | `data/` | seed data assets: sprites, phrasebook, games, response templates |
 | `ontology/` | the software ontology (`tmct-core.ttl`) and memory shapes, in Turtle |
 | `scripts/` | build, check, and maintenance scripts (`npm run` targets live here) |
+| `infra/` | the AWS CDK app that provisions the deployed site and its OIDC/deploy roles |
 | `examples/` | runnable example scripts and fixture repos used by the README's own examples and the test suite |
 | `demo/` | standalone demo scripts (e.g. the agentic-loop demo) |
 | `electron/` | the Electron desktop app wrapper |
@@ -37,7 +38,7 @@ derive by rule from both. Every answer is either grounded or an honest miss.
 | `reports/` | benchmark write-ups (`BENCHMARK_*.md`) and `PAGE_WEIGHTS.md` — see the root `STATUS.md` for the one-page summary these feed |
 | `playtests/` | numbered playtest session logs, one edge found and fixed per entry |
 | `archive/` | delivered `PLAN_*.md`/`BENCHMARK_*.md` docs, kept for history |
-| `public/` | the built demo site — a gitignored output of `npm run demo:build`, never hand-edited |
+| `public/` | the demo site: the hand-written home page, the eleven about pages, the shared stylesheet and the model/screenshot assets. The demo pages and browser bundles beside them are gitignored build outputs of `npm run demo:build` |
 
 `node_modules/` (dependencies) and dotfiles/hidden tooling directories are omitted above.
 
@@ -319,16 +320,19 @@ tmct> /exit
 
 **[Try it live in your browser →](https://tmct.polycode.co.uk/)**
 runs the actual query engine client-side. No server, no install. The landing
-page answers codebase questions live, and eight more pages each ground their
+page answers codebase questions live, and eleven more pages each ground their
 own domain: a full chat seeded with 63,470 facts (the same nine bands as
 `npm run init:xl`), the
 **memory ledger** (every fact as a readable sentence; drill by clicking the
 terms inside), and the **code explorer** (the same ledger UI refocused on a
 code graph, with a hint rail of suggested next questions). An **ingest
 page** turns pasted or dropped text into grounded facts and downloads them
-as canonical JSONL. The rest are a Towers-of-Hanoi plan replayed move by
-move, the spider-and-fly and text-adventure games, and a sprite gallery
-whose chat dock answers from 1,033 generated sprite facts. The chat page and
+as canonical JSONL, and a **research page** walks a stub wiki graph link by
+link. The rest are a Towers-of-Hanoi plan replayed move by move, the
+spider-and-fly and text-adventure games, a sprite gallery whose chat dock
+answers from 1,480 generated sprite facts, and two multi-agent worlds: a
+burrow that shares one world across browsers over WebRTC, and a Three.js
+town square where a wolf hunts goblins. The chat page and
 the ledger take the same paste-or-drop text in place; every page that holds
 a fact store exports it as JSONL.
 The site hosts its own copy of wink-nlp, ships its assets precompressed,
@@ -373,8 +377,8 @@ functions". Every suggestion resolves to a real answer.
 The identical page also runs as a plain hosted page over the demo code
 graph, with nothing to install:
 **[try it live →](https://tmct.polycode.co.uk/code.html)**.
-The desktop build below is for exploring your own repo or graph, which the
-hosted page cannot reach.
+The desktop build below is for exploring your own repo or graph: a browser page
+gets no filesystem access, so the hosted page reads the demo graph it ships with.
 
 Electron is a dev-only dependency and never ships in the npm package. Because
 `.npmrc` sets `ignore-scripts=true`, installing it does not fetch the runtime
@@ -659,7 +663,7 @@ now consults two shipped, lazily-loaded packs before giving up:
   triples into memory (provenance `child:conceptnet:kettle`, ranked below
   anything you teach) and answers from them; the next ask answers from
   memory directly.
-- `corpus/reference/`: 3,887 Simple English Wikipedia summaries. When the
+- `corpus/reference/`: 3,888 Simple English Wikipedia summaries. When the
   triples cannot answer, a matching article answers as a cited read-out
   (`source: reference article "Otter"…, CC BY-SA 4.0`).
 
@@ -712,7 +716,7 @@ the shipped `npm run example:*` demos) reads a graph but writes nothing back.
 
 The default persona also comes in three sizes: Small (~664 facts, the
 default), Medium (~1,608, `tmct init --persona-size medium`) and Large
-(~13,609, `--persona-size large`, deep enough to chain real multi-hop
+(~13,600, `--persona-size large`, deep enough to chain real multi-hop
 reasoning).
 
 ### Memory backends
@@ -935,6 +939,17 @@ provenance record. Most of its flags choose what gets seeded and where config is
                                in this repo picks it up with no flag needed
 ```
 
+`tmct index` is the producer side of the graph seam. It walks a repo's own source
+and writes the `.tmct/graph.json` that chat, serve and the CLI then read.
+
+```output:help:index
+  tmct index [--repo <abs>]    produce a code graph from a repo's OWN source (default: cwd):
+       [--no-history]          walk the tree, parse JS/TS with the TypeScript compiler
+                               API, read git history, and write <repo>/.tmct/graph.json —
+                               the artifact chat/serve/cli then read. --no-history skips
+                               the git passes (no commit/touches/cochange edges)
+```
+
 `tmct import` does the same activation as `tmct init`, but against a repo that is
 already set up. Its `--graph` flag works differently from the others: it appends to
 `tmct.toml`'s `graph_files` array instead of activating a bundle.
@@ -1055,6 +1070,15 @@ kill $SERVE_PID
        [--graph <path>]        the same thing. --graph names the graph file outright
        [--config <path>]       (repeatable), --config an alternate tmct.toml
   tmct cli digest '{…}'        architecture map + per-module context bundles
+  tmct --help                  show this help
+```
+
+The help closes with two notes on where a chat session runs and what it leaves
+behind:
+
+```output:help:notes
+On a terminal, chat opens the full-screen TUI; piped input gets the plain shell.
+In chat: /help lists slash-commands; /exit leaves. Session log → <repo>/.tmct/session-<id>.md.
 ```
 
 Two precedence chains apply across every command above, in this order:
@@ -1116,6 +1140,12 @@ graph_file = ".tmct/graph.json"
 # Extra graphs, merged alongside graph_file (ids that collide are auto-prefixed).
 graph_files = [".tmct/graph.json", ".tmct/legacy-graph.json"]
 
+[graph]
+# A chat session reads this repo's graph and writes nothing back into its
+# .tmct/: no session upsert, no transcript, no memory. The committed example
+# fixtures set it so `tmct chat --repo examples/<x>` can't rewrite them.
+read_only = false
+
 [corpus]
 # "tier1" (committed slice only, $0/offline, the default), "tier2" (also fetch
 # growable corpora at seed time), or "tier3" (also consult live sources per query).
@@ -1124,6 +1154,8 @@ tier = "tier1"
 [seed]
 enabled = true      # seed the committed corpus into .tmct/memory during init
 limit = 500         # cap the seeded fact count (definitional band first); unset = no cap
+capture_unknown_context = true   # keep the sentence around an unrecognized term
+unknown_context_limit = 200      # cap how many of those contexts are kept
 
 # One [extensions.<name>] table per bundle. A recognized name (human, seon,
 # conceptnet, human-medium, human-large, tier2-aws, tier2-python, tier2-java,
@@ -1177,7 +1209,6 @@ call_adjacency = true       # boost callers/callees of a matched symbol
 impl_of_interface = true    # boost an interface's implementations
 beam_search = true          # use beam search over the graph walk
 beam_width = 8
-embed_rank = false          # rerank by embedding similarity (off by default)
 prose_layers = 2            # how many prose-generation passes to run
 
 [tune.expansion]
@@ -1186,6 +1217,17 @@ nodes = 50                  # node budget for the walk
 q = 0.5                     # expansion breadth parameter
 depth = 3                   # max hops
 
+# Research-lane knobs (src/services/research.mjs).
+[research]
+fanout_limit = 8            # links followed per page
+max_depth = 3               # hops from the starting topic
+max_topics = 40             # topics visited in one crawl
+min_interval_ms = 1000      # politeness delay between fetches
+
+# Discourse record (src/domain/discourse.mjs).
+[discourse]
+max_referents = 12          # how many referents stay resolvable across turns
+
 [telemetry]
 enabled = false             # local-only counters; never phones home
 
@@ -1202,10 +1244,13 @@ spider_initial_mass = 15
 spider_mass_decrement_per_turn = 0.5   # lower = slower to starve
 fly_initial_mass = 10
 fly_mass_decrement_per_turn = 1
-vision_radius = 4                      # Chebyshev radius an agent can see other agents within
+spider_vision_radius = 4               # Chebyshev radius a spider sees other agents within
+fly_vision_radius = 4                  # the same radius for a fly
 egg_hatch_delay_turns = 3              # turns between a lay and its hatch
 fly_spawn_interval_turns = 3           # a new fly arrives every Nth turn
-eggs_eaten_threshold = 2               # flies eaten since the last egg before the next one lays
+egg_lay_mass_threshold = 25            # mass a spider must reach before it lays
+egg_hatch_count = 2                    # hatchlings per egg
+min_hatchling_mass = 3                 # mass a hatchling starts with
 web_duration_turns = 10                # turns a spider-built web stays active
 
 [games.guess-number]
@@ -1219,8 +1264,9 @@ max_depth = 300  # the "solve it" plan lane's search-depth cap (hanoi, river-cro
 
 ### Try it on an example graph
 
-tmct *consumes* a code graph at `<repo>/.tmct/graph.json`. It does not build
-one. Two ready-made example graphs live in `examples/` in this repo (clone the
+tmct reads a code graph at `<repo>/.tmct/graph.json`. `tmct index` builds one
+from a repo's own source, and any other producer can write the same file. Two
+ready-made example graphs live in `examples/` in this repo (clone the
 repo to use them; they are not in the published npm package), so you can see
 it answer real questions with no setup:
 
@@ -1402,7 +1448,7 @@ and transcripts are in the linked write-ups.
 | Determinism | Byte-identical on rerun: a 379-case `--replay` clean across 2 runs, no LLM, no network, $0 per turn | A property of the no-model pipeline. | `archive/BENCHMARK_INFERENCE_2.7.12.md` |
 | Dialogue robustness (persona sweep) | A 6-persona sweep (textbook logician, casual newcomer, new developer, adversarial sceptic, returning user, planning user) fixed 25 of the prior cycle's 29 routed findings (21 clean, 4 with a residual noted); 4 remain broken, 2 in a shape distinct from the original complaint | Free exploration across all six personas surfaced roughly 60 fresh findings beyond the ratchet check. The single highest-signal pattern: tmct's own suggested repair text was itself frequently broken when followed verbatim (since fixed, see `NEXT.md`). | `archive/BENCHMARK_CONVERSATION_2.7.11.md` |
 
-Three offline benchmark rigs live in a clone (they are not in the npm
+Seven offline benchmark rigs live in a clone (they are not in the npm
 package). Each replays a committed case set through the real product and
 writes graded rows you can diff between runs:
 
@@ -1412,7 +1458,14 @@ writes graded rows you can diff between runs:
 - `npm run infbench` generates inference cases, then runs each through both
   drive points, the reasoning kernel and the chat surface;
 - `npm run agentbench:run` measures the tool-loop behaviour, and every
-  verdict carries a hallucination axis.
+  verdict carries a hallucination axis;
+- `npm run idxbench:run` grades how faithfully the code-index producer
+  restates source as a graph;
+- `npm run ingestbench:run` (with `ingestbench:judge`) grades text-to-facts
+  extraction;
+- `npm run researchbench:run` grades the research lane's link traversal
+  against a frozen stub wiki graph;
+- `npm run synthbench:code` grades deterministic code synthesis.
 
 The smallest real slice of each, the same invocations the test suite's
 bench-smoke lane replays:
@@ -1457,7 +1510,7 @@ tmct's vocabulary is grounded in published standards where they exist, and says
 Each alignment below is a triple in `ontology/tmct-core.ttl` and a test in
 `test/adapters/grammar-ontology.test.mjs`. `docs/references/` holds an entry per source: the
 edition, the retrieval date, the terms tmct uses, and what could not be verified.
-`PLAN_NORMATIVE.md` holds the reconciliation, one verdict per term.
+`archive/PLAN_NORMATIVE.md` holds the reconciliation, one verdict per term.
 
 ### The data model
 
@@ -1476,7 +1529,7 @@ edition, the retrieval date, the terms tmct uses, and what could not be verified
 | [Attempto Controlled English](http://attempto.ifi.uzh.ch/site/docs/) | ACE 6.7, 2013 | The controlled-English fragment. tmct implements 9 of ACE's declarative sentence patterns. |
 | Kuhn, "A Survey and Classification of Controlled Natural Languages" | *Computational Linguistics* 40(1), 2014 | Where ACE sits among controlled languages. |
 | [ConceptNet](https://github.com/commonsense/conceptnet5/wiki/Relations) | slice pins 5.7.0 | The commonsense corpus. 25 relations are mirrored into `mgx:` and each cites its `/r/` origin. |
-| Damerau, *CACM* 7(3), 1964 · Levenshtein, *Soviet Physics Doklady* 10(8), 1966 | — | Fuzzy matching. `fuzzy.mjs` implements **Optimal String Alignment** — restricted Damerau-Levenshtein, which allows adjacent transposition but edits no substring twice. |
+| Damerau, *CACM* 7(3), 1964 · Levenshtein, *Soviet Physics Doklady* 10(8), 1966 | — | Fuzzy matching. `src/domain/interpret/fuzzy.mjs` implements **Optimal String Alignment** — restricted Damerau-Levenshtein, which allows adjacent transposition but edits no substring twice. |
 
 ### Reasoning and planning
 
@@ -1492,7 +1545,7 @@ edition, the retrieval date, the terms tmct uses, and what could not be verified
 
 | source | edition | what tmct uses it for |
 |---|---|---|
-| Jensen et al., "A Consensus Glossary of Temporal Database Concepts" | *SIGMOD Record* 23(1), 1994 | The time vocabulary. `mgx:utteranceTs` is valid time; `mgx:createdAt` is a transaction-time start. tmct is **not** bitemporal: `mgx:updatedAt` is an audit stamp, so tmct cannot answer what it believed last Tuesday. |
+| Jensen et al., "A Consensus Glossary of Temporal Database Concepts" | *SIGMOD Record* 23(1), 1994 | The time vocabulary. `mgx:utteranceTs` is valid time; `mgx:createdAt` is a transaction-time start. tmct is **not** bitemporal: `mgx:updatedAt` is an audit stamp, so "what did it believe last Tuesday" lands on the honest miss wall. |
 | RFC 9923, "The FNV Non-Cryptographic Hash Algorithm" | Informational, 2026 | FNV hashes the narrow non-fact-id pools (paraphrase keys, per-URL source ids, corpus dedupe). Fact ids are content-addressed with a **64-bit truncation of SHA-256**, so a fact id is collision-resistant at tmct's corpus sizes; tmct is still **not** a Merkle tree and offers no tamper-evidence. |
 | Green, Karvounarakis, Tannen, "Provenance Semirings" | PODS 2007 | The distinction tmct's docs keep: it records source annotation and PROV-style attribution, not how-provenance. |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "5.0.5",
+  "version": "5.0.6",
   "private": false,
   "type": "module",
   "description": "The Mechanical Code Talker (tmct) — a tolerant, offline, $0 chat surface that guides you toward precision queries about a software repository. ELIZA/PARRY-style but domain-obsessed with code. No model calls; indexes a repo on request (tmct index) or reads any producer's graph.",

package/src/domain/ask.mjs

@@ -15,7 +15,7 @@
 // ask.mjs's own `touches`/`cochange` verbs answer one-hop structural edges
 // (mgx:touchedByCommit / mgx:changeCoupledWith).
 
-import { relationKind, impactClosure, moduleCountOf, normPath, packageCounts, modulesOf, HISTORY_CAP } from "./codegraph.mjs";
+import { relationKind, impactClosure, moduleCountOf, normPath, packageCounts, modulesOf, HISTORY_CAP, NO_CODE_INDEX_NOTE } from "./codegraph.mjs";
 import { isTestPath } from "./module-paths.mjs";
 import {
   RELATIONS,
@@ -2491,9 +2491,7 @@ export function rephraseHint() {
  *  graph is UNKNOWN, not empty (see chat.mjs's noCodeGraph), so it keeps the
  *  index-shaped advice. */
 function touchesRephraseHint(graph = null) {
-  if (graph && moduleCountOf(graph) === 0) {
-    return "This store holds no code index, so it records no modules or commits to look through.";
-  }
+  if (graph && moduleCountOf(graph) === 0) return NO_CODE_INDEX_NOTE;
   return 'Try "who touched <a module that actually has commits>" or "/describe <module>" to see what\'s in the index.';
 }
 

package/src/domain/codegraph.mjs

@@ -57,6 +57,10 @@ export function moduleCountOf(graph) {
   return graph.individuals.filter((i) => (i.class || "") === "Module").length;
 }
 
+/** What a store with zero modules actually holds, said once so every lane that
+ *  has to decline for that reason declines in the same words. */
+export const NO_CODE_INDEX_NOTE = "This store holds no code index, so it records no modules or commits to look through.";
+
 // ---- relation-kind classifier (for impact + tests-coverage) -------------------
 
 const KINDS = ["imports", "calls", "defines", "tests", "touches", "contains", "inherits", "callsSymbol", "touchesSymbol"];
@@ -1360,7 +1364,13 @@ export function renderTestsFor(graph, ind) {
 }
 
 /** Source modules with no covering test module — a coverage gap view. Test
- *  modules (subjects of test edges, or test-named paths) are excluded. */
+ *  modules (subjects of test edges, or test-named paths) are excluded.
+ *
+ *  "Nothing is uncovered" and "I hold nothing to look at" are opposite
+ *  statements, so the empty survey has to say which one it means: with no
+ *  source module recorded there is no coverage claim to make at all, and the
+ *  full-coverage sentence would be an assertion about a repo this store has
+ *  never seen. */
 export function renderUntested(graph) {
   const covered = new Set();
   const testModules = new Set();
@@ -1368,14 +1378,18 @@ export function renderUntested(graph) {
     covered.add(e.object);
     testModules.add(e.subject);
   }
-  const untested = graph.individuals
-    .filter(
-      (i) =>
-        (i.class || "") === "Module" &&
-        !testModules.has(i.id) &&
-        !isTestPath(String(i.label).toLowerCase()) &&
-        !covered.has(i.id),
-    )
+  const sourceModules = graph.individuals.filter(
+    (i) => (i.class || "") === "Module"
+      && !testModules.has(i.id)
+      && !isTestPath(String(i.label).toLowerCase()),
+  );
+  if (!sourceModules.length) {
+    return moduleCountOf(graph) === 0
+      ? `no modules to check for test coverage in this index. ${NO_CODE_INDEX_NOTE}`
+      : "no source modules to check for test coverage in this index — only test modules are recorded.";
+  }
+  const untested = sourceModules
+    .filter((i) => !covered.has(i.id))
     .map((i) => i.label)
     .sort();
   if (!untested.length) return "every source module has at least one covering test module.";

package/src/domain/game-config.mjs

@@ -90,6 +90,16 @@ export const DEFAULT_GAME_CONFIG = Object.freeze({
     // this is the one switch that turns that off (visionRadius: Infinity for
     // the food-only belief call) without any new belief machinery.
     foodVisionGated: true,
+    // Whether prey weigh the predator and the crumb in one score instead of
+    // running the evade rung ahead of the forage one. Off by default: strict
+    // priority is what ships, and the blend is the alternative a comparison
+    // run measures against it (scripts/compare-prey-decision.mjs).
+    blendPreyDecision: false,
+    // How much of that score belongs to keeping away from the predator, with
+    // the rest going to closing on food. 1 evades exactly as the priority
+    // chain does, 0 ignores the predator, and the middle takes a crumb that
+    // costs little distance. Read only when blendPreyDecision is on.
+    preyThreatWeight: 0.5,
     // Whether the town-square lane accepts teaching. Its own knob rather than
     // a share of the adventure one below: the board's sentence table is a
     // different vocabulary, and a page checkbox on the town square should not
@@ -166,6 +176,8 @@ const MUDIII_KEY_MAP = Object.freeze({
   max_prey_population: "maxPreyPopulation",
   max_food_items: "maxFoodItems",
   food_vision_gated: "foodVisionGated",
+  blend_prey_decision: "blendPreyDecision",
+  prey_threat_weight: "preyThreatWeight",
   teach: "teach",
 });
 

package/src/services/adventure-viz.mjs

@@ -92,7 +92,7 @@
 // an edit implies run through the browser bundle's own `session.applyEdit`
 // (adventure-browser-entry.mjs), never here — this module only renders and
 // reads.
-import { THEME_TOKENS_CSS, SERIF_STACK, MONO_STACK, escapeHtml, embedJson, embedScriptText, scenarioLabel, rowsForWorld, wordBeforeCursor } from "./viz-theme.mjs";
+import { THEME_TOKENS_CSS, SERIF_STACK, MONO_STACK, escapeHtml, embedJson, embedScriptText, scenarioLabel, rowsForWorld, wordBeforeCursor, demoEyebrowHtml, EYEBROW_LINKS_CSS } from "./viz-theme.mjs";
 import { createTicker, createSerialQueue } from "./viz-ticker.mjs";
 import { directedGridLayout } from "./viz-room-graph.mjs";
 import { worldDigestRows, roomAffordances, foldWorldState } from "./adventure.mjs";
@@ -628,7 +628,9 @@ ${THEME_TOKENS_CSS}
   body { margin: 0; background: var(--bg); color: var(--ink); font-family: ${SERIF_STACK}; font-size: 16px; line-height: 1.5; }
   .mono { font-family: ${MONO_STACK}; }
   main { max-width: 920px; margin: 0 auto; padding: 1.4rem 1.2rem 2.2rem; }
+  .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: .12em; text-transform: uppercase; color: var(--gilt); }
+  ${EYEBROW_LINKS_CSS}
   .titlebar { display: flex; align-items: baseline; justify-content: space-between; gap: 1rem; flex-wrap: wrap; margin: .3rem 0 1rem; }
   button { font: inherit; color: inherit; background: none; cursor: pointer; }
   button:focus-visible { outline: 2px solid var(--ink); outline-offset: 2px; }
@@ -993,8 +995,9 @@ ${THEME_TOKENS_CSS}
 </head>
 <body>
 <main>
+  <h1 class="visually-hidden">the adventure</h1>
   <div class="titlebar">
-    <div class="eyebrow">tmct &middot; the adventure</div>
+    <div class="eyebrow">${demoEyebrowHtml("adventure", "the adventure")}</div>
     <button id="editModeBtn" type="button" class="mode-toggle" disabled>edit the world</button>
   </div>
   <p class="page-note" id="pageNote">${escapeHtml(scenarioList[0].worldPayload.opening || "")}</p>

package/src/services/chat-page-viz.mjs

@@ -28,7 +28,7 @@
 // input. scripts/build-demo-site.mjs calls it directly and writes the result
 // to public/chat.html, after chat-browser.bundle.js/chat-seed.json already
 // exist (both built earlier in that same script, for the embedded widget).
-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 {
   SHARE_OVERLAY_CSS, shareOverlayHtml, shareStepStates, activeWaves, offerBlobIn, peerTerm,
   shareMessageFor, replyMessageFor, whatsAppShareUrl, isProbablyMobile, copyTextToClipboard, flashCopyTip,
@@ -498,7 +498,9 @@ ${THEME_TOKENS_CSS}
      get folded onto a second line by a wide one. */
   .topbar { flex: 0 0 auto; display: flex; align-items: center; gap: 1rem; padding: .55rem 1.1rem; border-bottom: 1px solid var(--line); flex-wrap: wrap; }
   .brand { display: flex; align-items: baseline; gap: .55rem; }
+  .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: .78rem; letter-spacing: .08em; color: var(--muted); }
+  ${EYEBROW_LINKS_CSS}
   .legend { display: flex; gap: .8rem; margin-left: auto; font-family: ${MONO_STACK}; font-size: .68rem; color: var(--muted); }
   .legend-item { display: inline-flex; align-items: center; gap: .32rem; white-space: nowrap; }
   .dot { width: 7px; height: 7px; border-radius: 50%; display: inline-block; }
@@ -691,9 +693,10 @@ ${SHARE_OVERLAY_CSS}
 <body>
 ${shareOverlayHtml({ withTape: true })}
   <div class="chatCol">
+    <h1 class="visually-hidden">talk to it</h1>
     <header class="topbar">
       <div class="brand">
-        <span class="eyebrow">the-mechanical-code-talker</span>
+        <span class="eyebrow">${demoEyebrowHtml("chat", "chat")}</span>
       </div>
       <div class="chrome">
         <span class="fact-pill" id="factPill" aria-live="polite"

package/src/services/chat.mjs

@@ -1413,6 +1413,35 @@ export function isConversational(query) {
   return expandContractions(q).split(/\s+/).filter(Boolean).length <= 3 && !codeish;
 }
 
+/** The words that, in the slot of a short "what is X" / "who is X", name the
+ *  SESSION rather than a term to look up ("what is this", "what is up").
+ *  Closed and hand-curated, the same discipline every small-talk set in this
+ *  file uses: a word listed here keeps today's orientation card, and anything
+ *  else is a question about a term. */
+const SESSION_REFERENT_TERMS = new Set([
+  "this", "that", "it", "they", "them", "you", "u", "yours", "tmct",
+  "up", "new", "next", "now", "here", "there", "left", "wrong", "more", "else",
+  "all", "everything", "anything", "something", "nothing",
+  "going", "happening", "possible", "available", "supported", "included",
+]);
+
+/** The term a short "what is X" / "who is X" asks about, or null when the line
+ *  isn't that shape or names the session itself.
+ *
+ *  isConversational's catch-all counts words, so "what is grelb" (three) took
+ *  the orientation card while "what is a grelb" (four, one article apart)
+ *  refused — the same question answered two different ways, and the shorter
+ *  one answered with a paragraph about tmct that reads as if the term had been
+ *  looked up. A term question that resolves to nothing belongs on the miss
+ *  wall; only the closed set above is really about the product. */
+function shortTermQuestionTerm(query) {
+  const m = String(query).trim().replace(/[?.!]+\s*$/, "")
+    .match(/^(?:what|who)\s+(?:is|are|was|were)\s+([a-z][\w'-]*)$/i);
+  if (!m) return null;
+  const term = m[1].toLowerCase();
+  return SESSION_REFERENT_TERMS.has(term) ? null : term;
+}
+
 /** The tmct tools dispatchTool can back (the set a tool-emitting caller may use).
  *  A declared tool outside this set is never emitted — the request falls through
  *  to a text answer. The COMMANDS map names the richer graph tools; TOOLS names
@@ -2959,6 +2988,23 @@ function singularizeSurface(word) {
 
 export { singularizeSurface };
 
+/** Does the complement of this payload wear its own article ("all foxes are A
+ *  SPECIES")? An article marks the complement singular already, so the plural
+ *  fold below must leave it alone. */
+const objectCarriesArticle = (payload) => /\s(?:is|are)\s+(?:an?\s+)/i.test(String(payload || ""));
+
+/** The complement as it should be STORED. The subject of a plural membership
+ *  sentence has always folded ("all foxes are mammals" stores "fox"); the
+ *  object had not, so the pair landed as fox ⊑ mammals and the next turn's
+ *  "is a fox a mammal" looked up a class spelled a different way and missed
+ *  the fact it had just been told. Gated exactly as the subject fold is: only
+ *  a genuinely plural "are" phrasing, and only where no article already marks
+ *  the complement singular. */
+function storedObjectTerm(objectRaw, { verb, payload, lex, lookupNoun }) {
+  if (!/^are$/i.test(verb) || objectCarriesArticle(payload)) return objectRaw;
+  return lookupNoun(lex, objectRaw)?.lemma || singularizeSurface(objectRaw);
+}
+
 /** "(every|each|all|a|an )?X is/are (a|an )?Y" — the shape the unknown-subject
  *  fallback recognizes (group 2 = X, group 4 = Y); group 1 (when present)
  *  names the determiner, so the caller can tell a genuine "every" universal
@@ -3103,19 +3149,25 @@ async function ungroundedPairHint(payload, lexicon, memoryDir, cache = null, gra
   if (!memoryDir) return "";
   const m = String(payload).trim().match(UNKNOWN_SUBJECT_RE);
   if (!m) return "";
-  const [, , subjectRaw, , objectRaw] = m;
-  const { loadLexicon } = await import("../domain/grammar/lexicon.mjs");
+  const [, , subjectRaw, verb, objectRaw] = m;
+  const { loadLexicon, lookupNoun } = await import("../domain/grammar/lexicon.mjs");
   const lex = lexicon || loadLexicon();
   if (await isGroundedTerm(subjectRaw, lex, memoryDir, cache, graph)) return "";
   if (await isGroundedTerm(objectRaw, lex, memoryDir, cache, graph)) return "";
+  // The sentences suggested here have to be the ones that actually store, so
+  // both sides fold to the singular a plural surface named ("all zorps are
+  // florbs" → "every zorp is a thing"). Following the plural verbatim teaches
+  // a second class under a spelling nothing else uses.
+  const subject = /^are$/i.test(verb) ? singularOf(subjectRaw, lex, lookupNoun) : subjectRaw;
+  const object = storedObjectTerm(objectRaw, { verb, payload, lex, lookupNoun });
   // Chaining the second term UNDER the first's now-grounded proper name
   // ("every man is a john") is technically accepted by the grammar (once
   // "john" is grounded, ANY term can be taught as a kind of it), but reads as
   // nonsense to a human, since a proper name is never a category. Ground both
   // sides independently instead — two clear, parallel, semantically sane
   // suggestions, not a confusing chain through an arbitrary first term.
-  return ` I don't know "${subjectRaw}" or "${objectRaw}" yet. Try grounding each one first, e.g. `
-    + `"every ${subjectRaw} is a thing" and "every ${objectRaw} is a thing", then re-teach the`
+  return ` I don't know "${subject}" or "${object}" yet. Try grounding each one first, e.g. `
+    + `"every ${subject} is a thing" and "every ${object} is a thing", then re-teach the`
     + ` original fact.`;
 }
 
@@ -3192,7 +3244,12 @@ async function unknownSubjectFallback(payload, { memoryDir, sessionId, lexicon,
   if (lookupNoun(lex, objectRaw) || GENERIC_ANCHOR_NOUNS.has(String(objectRaw).toLowerCase())
     || (await isGroundedByFact(objectRaw, memoryDir, cache))) {
     return teachFact(memoryDir, sessionId, {
-      subject, predicate: SUBCLASS_PREDICATE, object: objectRaw, quantifier, observedAt, dateText,
+      subject,
+      predicate: SUBCLASS_PREDICATE,
+      object: storedObjectTerm(objectRaw, { verb, payload, lex, lookupNoun }),
+      quantifier,
+      observedAt,
+      dateText,
     });
   }
   if (lookupAdjective(lex, objectRaw)) {
@@ -3321,7 +3378,12 @@ async function unknownObjectFallback(payload, { memoryDir, sessionId, lexicon, c
     ? (lookupNoun(lex, subjectRaw)?.lemma || singularizeSurface(subjectRaw))
     : subjectRaw;
   return teachFact(memoryDir, sessionId, {
-    subject, predicate: SUBCLASS_PREDICATE, object: objectRaw, quantifier, observedAt, dateText,
+    subject,
+    predicate: SUBCLASS_PREDICATE,
+    object: storedObjectTerm(objectRaw, { verb, payload, lex, lookupNoun }),
+    quantifier,
+    observedAt,
+    dateText,
   });
 }
 
@@ -4160,9 +4222,20 @@ function matchBareCanTeach(text) {
 function teachSuggestion(payload) {
   const m = String(payload).match(/^(?:every |each |all |a |an )?([\w-]+) (is|are) (a |an )?([\w-]+)[.!?]*$/i);
   if (!m) return null;
-  const subject = (/^are$/i.test(m[2]) ? singularizeSurface(m[1]) : m[1]).toLowerCase();
-  const object = m[4].toLowerCase();
-  if (!m[3]) return `every ${subject} is ${object}`;
+  const plural = /^are$/i.test(m[2]);
+  const subject = (plural ? singularizeSurface(m[1]) : m[1]).toLowerCase();
+  let object = m[4].toLowerCase();
+  let articled = !!m[3];
+  // A plural complement with no article of its own ("all lynxes are mammals")
+  // folds like the subject does, and the fold itself is what proves it was a
+  // plural NOUN rather than a bare adjective — so it earns the article the
+  // singular membership sentence needs. Without this the repair suggested the
+  // very spelling the same sentence had just called unrecognized.
+  if (plural && !articled) {
+    const folded = singularizeSurface(object);
+    if (folded !== object) { object = folded; articled = true; }
+  }
+  if (!articled) return `every ${subject} is ${object}`;
   const articleRule = grammarRules().find((r) => r.kind === "article");
   const article = articleRule && beginsWithVowelSound(object, articleRule) ? "an" : "a";
   return `every ${subject} is ${article} ${object}`;
@@ -4799,9 +4872,11 @@ async function teachLane(query, { memoryDir, sessionId = "", lexicon = null, cac
     // the SHAPE of a retraction sentence — it says nothing about whether
     // subject⊑object was ever actually taught, or taught by THIS session.
     // retractSubClassOf is asked for real and is the only thing that decides:
-    //   - found:false  → subject⊑object was never a stored fact, and this
-    //     falls through to the rest of teachLane's ordinary cascade below
-    //     rather than claiming a specific, possibly-wrong reason.
+    //   - found:false  → subject⊑object was never a stored fact, so there is
+    //     nothing to withdraw and the turn says exactly that. It must NOT
+    //     fall through to the rest of the cascade: the teach frames below
+    //     read the unconsumed sentence from the top, take "forget bertha" as
+    //     a two-word subject, and confirm a fact the user asked to destroy.
     //   - found:true, ownRecord:false → some OTHER source taught it; this
     //     session has nothing of its own to withdraw.
     //   - found:true, stillStands:true → this session's own record is gone,
@@ -4849,7 +4924,10 @@ async function teachLane(query, { memoryDir, sessionId = "", lexicon = null, cac
           via: "retract", miss: false,
         };
       }
-      // found:false — fall through to the rest of the cascade (see docblock above).
+      return {
+        text: `"${retractSubject} is a kind of ${retractObject}" isn't stored, so there's nothing to forget.`,
+        via: "retract", miss: true,
+      };
     }
   }
 
@@ -13336,9 +13414,11 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
     dialogueLaneOverride = "game-inform";
     note(trace, "lane: (2) MID-GAME NUDGE — an unparsed short turn stayed inside the live game frame instead of the identity card");
     note(trace, "goal: keep the running guess-the-number game on track");
-  } else if (isConversationalCandidate) {
+  } else if (isConversationalCandidate && !shortTermQuestionTerm(gateQuery) && !shortTermQuestionTerm(query)) {
     // A conversational miss (a greeting, "what can you do", a very short non-code
     // line) gets the friendly orientation (module-aware: empty → --repo/tmct init).
+    // A short question naming a TERM is excluded: nothing above resolved it, so
+    // it belongs on the miss wall its four-word twin already reaches.
     // This branch carries via:"template" and never reaches the composed-only
     // wall-shortening gate below, so it needs its own repeat collapse,
     // mirroring WALL_REPEAT_ONELINER.
@@ -13530,7 +13610,10 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
       // all, so it would otherwise be confidently WRONG or silently absent.
       // Every successfully-recognized teach attempt gets this consistent goal
       // line instead.
-      deduced = "teach/remember a new fact";
+      // A retraction reaches this lane too, and its goal is the opposite one:
+      // saying "teach/remember a new fact" under a sentence asking for a fact
+      // to go describes the turn backwards.
+      deduced = taught.via === "retract" ? "withdraw a remembered fact" : "teach/remember a new fact";
       note(trace, `goal: ${deduced} (revised — the teach lane recognized this shape where the raw structural parse never should have)`);
       // A canonical whose verb only matched through the fuzzy edit-distance
       // tier ("disk-1 rests on peg-a." read as an ask about "tests") restates
@@ -13791,7 +13874,12 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
     // does. Both shapes below anchor on the written-out copula.
     const offerSrc = expandContractions(String(query).trim());
     const knowAboutTerm = offerSrc.match(KNOW_ABOUT_RE)?.[1]?.trim();
-    const offerTerm = knowAboutTerm || metaTermOf(offerSrc, envelope);
+    // "who is grelb" asks about a term the same way "what is grelb" does, and
+    // a name is exactly what a person teaches next — without this the who-form
+    // dead-ends on the bare grammar wall while its what-form twin offers the
+    // teach phrasing.
+    const whoTerm = shortTermQuestionTerm(offerSrc) ? offerSrc.match(WHO_IS_BARE_RE)?.[1]?.trim() : null;
+    const offerTerm = knowAboutTerm || metaTermOf(offerSrc, envelope) || whoTerm;
     // A term that LEADS with a bindable anaphor ("it used for", from an
     // unresolved "what is it used for") is a pronoun that failed to bind,
     // not a teachable subject — offering to learn facts about it would echo

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