@polycode-projects/the-mechanical-code-talker 0.4.0 → 0.6.0

package/src/chat.mjs

@@ -104,6 +104,37 @@ export const COMMANDS = {
  *  back to the focus for, and that update the focus on a successful resolve. */
 const ENTITY_ARGS = new Set(["symbol", "module", "class"]);
 
+/** System-command words that a forgiving shell accepts WITHOUT the leading "/":
+ *  `stats`, `memory`, `describe X`, `members X`, … all work bare. "help" is left
+ *  out on purpose — bare "help" stays the friendly orientation; "/help" is the
+ *  full command list. */
+const COMMAND_WORDS = new Set(["stats", "memory", "focus", ...Object.keys(COMMANDS)]);
+
+/** Query connectives that mark a line as a COMPOSITIONAL question the ask engine
+ *  should own, even when it happens to start with a command word ("untested modules
+ *  IMPORTING x", "find functions THAT CALL y"). Their presence blocks slash-routing. */
+const QUERY_CONNECTIVES = /\b(that|which|and|or|imports?|importing|calls?|calling|uses?|using|covers?|covering|tests?|testing|touch(?:es|ed|ing)?|inherits?|of|with|from|into|by|most|least)\b/i;
+
+/** A bare leading command word → its slash form ("stats" → "/stats", "describe x"
+ *  → "/describe x"), so the system commands are slash-optional. Conservative on the
+ *  entity/arg commands: it routes a bare word or a SHORT name-like argument, but
+ *  falls through (returns null) for a multi-word compositional query so the ask
+ *  engine still owns things like "untested modules importing a.mjs". Returns null
+ *  when the first token is not a command word. */
+export function asBareCommand(line) {
+  const trimmed = String(line || "").trim();
+  if (!trimmed || trimmed.startsWith("/")) return null;
+  const [first, ...restTok] = trimmed.split(/\s+/);
+  if (!COMMAND_WORDS.has(first.toLowerCase())) return null;
+  const rest = restTok.join(" ");
+  // Zero-arg system commands are always the command; a bare command word is too.
+  if (!rest || first.toLowerCase() === "stats" || first.toLowerCase() === "memory") return `/${trimmed}`;
+  // Arg commands: route only a short, name-like argument (no query connectives),
+  // so "describe Widget" / "members my class" route but a compositional query does not.
+  if (restTok.length <= 3 && !QUERY_CONNECTIVES.test(rest)) return `/${trimmed}`;
+  return null;
+}
+
 // ---- aggregate / count queries — answered MECHANICALLY off the loaded graph
 // header (individuals grouped by class, relation groups by predicate), not by
 // dispatching to the ask engine. Deterministic, fully in-ethos. ----
@@ -138,11 +169,22 @@ function countableKinds(graph) {
   return Object.keys(CLASS_LABELS).filter((c) => present.has(c)).map((c) => CLASS_LABELS[c][1]);
 }
 
+/** A discourse-anaphoric count/list head — "how many [of] those/them/these",
+ *  "count them/those/these". These refer to the previous answer set and are owned
+ *  by the ask engine's anaphora node, never the header-count path. */
+const ANAPHORA_COUNT_RE = /\b(?:how many|how much|count|number of)\s+(?:of\s+)?(?:those|them|these)\b/i;
+
 /** Recognise a count/aggregate question and answer it from the graph header, or
  *  null if it isn't one (→ fall through to tmct_ask). "how many X [are there]",
  *  "count [the] X", "number of X". An unknown kind lists what it CAN count. */
 export function answerCount(graph, query) {
   if (!graph) return null;
+  // ANAPHORIC counts ("how many of those are tested", "count them", "how many of
+  // them") count the PREVIOUS answer's set, not a graph kind — decline so the turn
+  // falls through to the ask engine's anaphora node (which threads `prev`). Without
+  // this the bare "of"/pronoun head is mis-reported as an uncountable kind and the
+  // discourse+count follow-up dies before it can resolve (CHATBENCH_006 lever 1).
+  if (ANAPHORA_COUNT_RE.test(String(query))) return null;
   const m = String(query).match(/\b(?:how many|number of|count(?:\s+the)?)\s+([a-z]+)\b/i);
   if (!m) return null;
   const noun = m[1].toLowerCase();
@@ -155,6 +197,70 @@ export function answerCount(graph, query) {
   return `${n} ${classNoun(cls, n)}.`;
 }
 
+/** ASSERTED-VOCABULARY count (CHATBENCH_006 lever 3): once "every class is a type"
+ *  is remembered, "how many types are there" counts as many types as there are
+ *  classes — the asserted object noun inherits the subject class's cardinality.
+ *  Consulted only when answerCount can't map the noun to a graph class (an unknown
+ *  kind) AND a session's memory is in hand. Returns the count string or null (no
+ *  such fact → the honest "I can't count …" from answerCount stands). */
+async function countFromFacts(graph, memoryDir, query) {
+  if (!graph || !memoryDir) return null;
+  const m = String(query).match(/\b(?:how many|number of|count(?:\s+the)?)\s+([a-z]+)\b/i);
+  if (!m) return null;
+  const asked = m[1].toLowerCase();
+  if (COUNT_NOUNS[asked]) return null; // a real graph kind — answerCount owns it
+  let normFactTerm;
+  try { ({ normFactTerm } = await import("./memory/core.mjs")); } catch { return null; }
+  const objVariants = factTermVariants(normFactTerm, asked);
+  const isa = (await factRows(memoryDir))
+    .filter((f) => ISA_PREDICATES.has(f.predicate) && objVariants.has(f.object));
+  // pick the highest-trust asserted subject that maps to a countable graph class
+  for (const f of isa.sort((a, b) => (b.trust ?? 0) - (a.trust ?? 0))) {
+    const cls = COUNT_NOUNS[String(f.subject).toLowerCase()];
+    if (cls) { const n = countClass(graph, cls); return `${n} ${asked}.`; }
+  }
+  return null;
+}
+
+// ---- memory-store counts (the .tmct/memory graph, distinct from the code graph
+// answerCount reads) — so "how many facts do you know" is answerable, consistent
+// with what `/memory` advertises. The code graph owns the structural kinds
+// (classes/functions/modules/…); the memory store owns Facts + Utterances. Sessions
+// stay with answerCount (chat writes Session individuals into the code graph as
+// first-class temporal data — see sessions.mjs), so this never shadows them. ----
+
+/** Nouns that name a MEMORY-STORE individual class, → the class to count. */
+const MEMORY_COUNT_NOUNS = {
+  fact: "Fact", facts: "Fact",
+  utterance: "Utterance", utterances: "Utterance", said: "Utterance",
+};
+const MEMORY_CLASS_LABELS = { Fact: ["fact", "facts"], Utterance: ["utterance", "utterances"] };
+
+/** Recognise a memory-store count question and answer it by loading the memory
+ *  graph, or null (→ answerCount / the ask engine own it). Handles "how many facts",
+ *  "how many utterances", and the bare "how many do you know" (→ facts). Lazy +
+ *  failure-tolerated: no memory / a broken store → null, so the honest fall-through
+ *  stands. */
+async function answerMemoryCount(memoryDir, query) {
+  if (!memoryDir) return null;
+  const q = String(query).toLowerCase();
+  let cls = null;
+  // the bare "how many do you know" (no explicit noun) defaults to remembered facts
+  if (/\bhow many(?:\s+(?:things?|facts?))?\s+(?:do|d'?)\s+(?:you|u)\s+know\b/.test(q)) cls = "Fact";
+  if (!cls) {
+    const m = q.match(/\b(?:how many|number of|count(?:\s+the)?)\s+([a-z]+)\b/);
+    if (m) cls = MEMORY_COUNT_NOUNS[m[1]] || null;
+  }
+  if (!cls) return null;
+  let loadMemory;
+  try { ({ loadMemory } = await import("./memory/core.mjs")); } catch { return null; }
+  let mem;
+  try { mem = await loadMemory(memoryDir); } catch { return null; }
+  const n = (mem.individuals || []).filter((i) => (i.class || "") === cls).length;
+  const [sing, plur] = MEMORY_CLASS_LABELS[cls];
+  return `${n} ${n === 1 ? sing : plur}.`;
+}
+
 /** `/stats`: a one-screen overview of the graph — class counts, relationship
  *  (predicate) counts, and module/package totals — read straight off the header. */
 export function renderStats(graph) {
@@ -233,6 +339,12 @@ const T_THANKS = "conversational-thanks";
 const T_FAREWELL = "conversational-farewell";
 const T_ORIENTATION = "orientation-friendly";
 const T_WHY_EMPTY = "miss-no-previous-answer";
+/** Empty / degenerate-graph variants (#3/#5): shown when the loaded graph has 0
+ *  modules (a graph-less bootstrap OR a graph.json with no code entities). They
+ *  orient toward `--repo`/`tmct init` + the seeded vocabulary instead of
+ *  over-promising "ask me about this codebase". */
+const T_GREETING_EMPTY = "conversational-greeting-empty";
+const T_ORIENTATION_EMPTY = "orientation-empty";
 
 /** The degraded line when the template library itself cannot load — a packaging
  *  failure said out loud, never a crashed turn or a silently different answer. */
@@ -333,9 +445,188 @@ function conversationalTurn(line, ctx) {
     if (v.empty) return mk(tRender(ctx.templates, T_WHY_EMPTY) ?? v.text, { miss: true });
     return mk(v.text, { via: "conversational" });
   }
-  if (GREET.has(q)) return mk(t(T_GREETING_BY_PHRASE[q] || T_GREETING));
+  if (GREET.has(q)) {
+    // #3 empty/degenerate-graph greeting: a plain "hi"/"hello" over a graph with 0
+    // modules orients toward --repo/tmct init instead of over-promising "ask me
+    // about this codebase". Phrase-specific variants (good morning, hello there)
+    // keep their wording; only the default greeting swaps.
+    const id = (!T_GREETING_BY_PHRASE[q] && noCodeGraph(ctx.graph)) ? T_GREETING_EMPTY : (T_GREETING_BY_PHRASE[q] || T_GREETING);
+    return mk(t(id));
+  }
   if (THANKS.has(q)) return mk(t(T_THANKS));
-  if (q === "help" || q === "?" || HELP_PHRASES.some((re) => re.test(raw))) return mk(t(T_ORIENTATION));
+  if (q === "help" || q === "?" || HELP_PHRASES.some((re) => re.test(raw))) return mk(orientationAnswer(ctx.templates, ctx.graph));
+  return null;
+}
+
+// ---- #1/#2/#3 conversational-UX helpers: module-aware orientation, the short
+// tailored miss, and the intent lanes (teach + meta/self). All are recognizer-
+// gated and (for the lanes) only consulted on a would-miss, so ordinary graph
+// queries are never hijacked. ----
+
+/** Code entities (Modules) in the loaded graph — the "is there a code graph here"
+ *  test. 0 means a graph-less bootstrap OR a graph.json with no code entities (the
+ *  degenerate trap); both orient rather than over-promise. */
+export function moduleCountOf(graph) {
+  if (!graph || !Array.isArray(graph.individuals)) return 0;
+  return graph.individuals.filter((i) => (i.class || "") === "Module").length;
+}
+
+/** A KNOWN-empty code graph: a loaded graph object with 0 modules. A null graph
+ *  (a bare runTurn that wasn't handed one) is "unknown", NOT empty — the empty
+ *  orientation/greeting only fires when we actually hold an empty graph. */
+const noCodeGraph = (graph) => !!graph && moduleCountOf(graph) === 0;
+
+/** The orientation surface, module-aware: the empty variant (→ --repo/tmct init +
+ *  seeded vocabulary) when there's no code graph, the standard one otherwise. */
+function orientationAnswer(templates, graph) {
+  return tRender(templates, noCodeGraph(graph) ? T_ORIENTATION_EMPTY : T_ORIENTATION) ?? TEMPLATES_UNAVAILABLE;
+}
+
+/** A dynamic orientation string for the meta/self lane: a /stats-style overview
+ *  when a code graph is loaded, else the honest empty-graph orientation. */
+function orientationText(graph) {
+  if (noCodeGraph(graph)) {
+    return "There's no code graph loaded here, so I can't answer structure questions yet. "
+      + "Point me at your code with `--repo <path>` or run `tmct init` to index this repo. "
+      + 'I do know some general vocabulary — try "what is a cache". /help for commands.';
+  }
+  const by = (cls) => (graph.individuals || []).filter((i) => (i.class || "") === cls).length;
+  const parts = [];
+  for (const [cls, sing, plur] of [["Module", "module", "modules"], ["Class", "class", "classes"], ["Function", "function", "functions"]]) {
+    const n = by(cls); if (n) parts.push(`${n} ${n === 1 ? sing : plur}`);
+  }
+  return `This is a tmct code graph — ${(graph.individuals || []).length} entities`
+    + `${parts.length ? ` (${parts.join(", ")})` : ""}. `
+    + 'Ask about imports, calls, definitions or history — e.g. "which modules import <name>", "what calls <name>". '
+    + "/stats for the full overview, /help for commands.";
+}
+
+// #1 SHORT, TAILORED MISS — the engine's full grammar cheat-sheet (rephraseHint)
+// now lives ONLY behind /help. A genuine parse-miss gets ONE line: an honest miss
+// + at most two example shapes chosen for what the user typed + a /help pointer.
+// The opening "couldn't parse this as a graph question. Try:" is preserved (the
+// honest-miss contract + the graded hm-joke case pin those words).
+const MISS_EXAMPLES = {
+  import: ['"which modules import <name>"', '"what does <name> import"'],
+  export: ['"what does <name> export"', '"which modules import <name>"'],
+  call: ['"what calls <name>"', '"which functions call <name>"'],
+  test: ['"what tests <name>"', '"which functions are tested"'],
+  inherit: ['"which classes inherit from <name>"', '"what are the subclasses of <name>"'],
+  history: ['"when did <name> change"', '"who touched <name>"'],
+  define: ['"where is <name> defined"', '"where is <name> mentioned"'],
+  meaning: ['"what is a <ClassName>"', '"what does <term> mean"'],
+  count: ['"how many classes are there"', '"how many modules are there"'],
+};
+const MISS_DEFAULT = ['"which modules import <name>"', '"what calls <name>"'];
+
+/** Choose up to two example shapes RELEVANT to the user's words. */
+function tailoredExamples(q) {
+  // membership yes/no ("is a algorithm information") — the grammar wants an article
+  // before BOTH terms; hint the working shape rather than dumping the wall.
+  if (/^is\s+(?:an?\s+)?[\w-]+\b/.test(q)) return ['"is a <thing> a <kind>" (an article before the kind, too)'];
+  const has = (re) => re.test(q);
+  if (has(/\bimport/)) return MISS_EXAMPLES.import;
+  if (has(/\bexport/)) return MISS_EXAMPLES.export;
+  if (has(/\b(?:calls?|caller|callee)\b/)) return MISS_EXAMPLES.call;
+  if (has(/\b(?:tests?|cover|covering|tested)\b/)) return MISS_EXAMPLES.test;
+  if (has(/\b(?:inherit|subclass|extends?|superclass|hierarchy|base class|parent class)\b/)) return MISS_EXAMPLES.inherit;
+  if (has(/\b(?:history|when|changed?|commit|touch(?:e[ds])?|who)\b/)) return MISS_EXAMPLES.history;
+  if (has(/\b(?:defined?|where|located?|mention)\b/)) return MISS_EXAMPLES.define;
+  if (has(/\b(?:mean|means|meaning|definition|vocab)\b/) || /\bwhat(?:'s| is)? an? \w/.test(q)) return MISS_EXAMPLES.meaning;
+  if (has(/\b(?:how many|count|number of)\b/)) return MISS_EXAMPLES.count;
+  return MISS_DEFAULT;
+}
+
+/** The one-line short miss. */
+export function shortMissHint(query) {
+  const ex = tailoredExamples(String(query || "").toLowerCase());
+  return `couldn't parse this as a graph question. Try: ${ex.join(" or ")}. Type /help for all query shapes.`;
+}
+
+/** The exact opening of the engine's full grammar-wall miss — the ONLY miss the
+ *  short-miss rewrites. Receipt-bearing misses (honest empties, unresolved terms,
+ *  the empty-graph bootstrap note, compositional misses) never match, so their
+ *  specific wording + traversal receipts stand. */
+const WALL_MISS_RE = /^couldn't parse this as a graph question\. Try:/;
+
+// #2 INTENT LANE — MEMORY/TEACH. "remember that X is a Y", "note that …", or a
+// bare "X is a Y" declarative the graph parser couldn't handle → route to the
+// assert/memory path; when it can't be stored, say what CAN be remembered
+// (LOUD, the working shape) — never the grammar wall, never a silent data loss.
+const TEACH_RE = /^(?:please\s+)?(?:remember|note|keep in mind|jot down|for the record|fyi)\b[:,]?\s*(?:that\s+)?(.+?)[.?!]*$/i;
+const BARE_DECLARATIVE_RE = /^(?:every |each |all |a |an )?[\w-]+ (?:is|are) (?:a |an )?[\w-]+$/i;
+/** Interrogative / auxiliary leads that make an "X is a Y"-shaped line a QUESTION
+ *  ("what is a cache", "is a module a component"), never a teach declarative. */
+const QUESTION_LEAD_RE = /^(?:what|who|which|where|when|why|how|is|are|do|does|did|can|could|should|would|will|has|have)\b/i;
+
+/** Sentence forms to try asserting for a teach payload: the payload as-is, and
+ *  (if it carries no determiner) its "every …" universal — the ACE-OWL shape the
+ *  grammar actually lands. */
+function assertCandidates(payload) {
+  const p = String(payload).trim();
+  const out = [p];
+  if (!/^(?:every|each|all|a|an)\b/i.test(p)) out.push(`every ${p}`);
+  return [...new Set(out)];
+}
+/** The "every X is a Y" rewrite of a declarative, for the "did you mean …" hint. */
+function teachSuggestion(payload) {
+  const m = String(payload).match(/^(?:every |each |all |a |an )?([\w-]+) (?:is|are) (?:a |an )?([\w-]+)$/i);
+  return m ? `every ${m[1].toLowerCase()} is a ${m[2].toLowerCase()}` : null;
+}
+
+async function teachLane(query, { memoryDir, sessionId = "", lexicon = null }) {
+  const raw = String(query).trim();
+  let payload = null;
+  const m = raw.match(TEACH_RE);
+  if (m && /\b(?:is|are)\b/i.test(m[1])) payload = m[1].trim();
+  else if (BARE_DECLARATIVE_RE.test(raw) && !QUESTION_LEAD_RE.test(raw)) payload = raw;
+  if (!payload) return null;
+  // Try to store it (a live session provides the write target). assertTurn returns
+  // the "noted — remembered …" confirmation or null (grammar miss / unknown words).
+  if (memoryDir) {
+    for (const cand of assertCandidates(payload)) {
+      const stored = await assertTurn(cand, { memoryDir, sessionId, focus: null, lexicon });
+      if (stored) return { text: stored.answer, via: "assert", miss: false };
+    }
+  }
+  const suggestion = teachSuggestion(payload);
+  const did = suggestion && suggestion !== payload.toLowerCase() ? ` Did you mean: "${suggestion}"?` : "";
+  return {
+    text: 'I couldn\'t store that — I remember facts in the shape "every X is a Y", where X and Y are '
+      + `words I know.${did} Type /memory to see what I already remember.`,
+    via: "teach-miss", miss: true,
+  };
+}
+
+// #2 INTENT LANE — META/SELF. Bare self/session questions answered from stats /
+// memory / orientation, never the grammar wall or the raw fact-dump. WOULD-MISS
+// ONLY (the caller gates on a miss) and every pattern is a WHOLE-LINE self/session
+// reference with no graph entity or predicate, so real graph queries ("what does X
+// import", the meta "what does imports mean", "what did i ask before") never match.
+const WHAT_KNOW_RE = /^what\s+(?:do\s+you|d'?you)\s+know(?:\s+so\s+far)?$/;
+const META_ORIENT_RE = /^(?:what(?:'s| is| are)?\s+this(?:\s+(?:codebase|repo|repository|project|code|thing))?|what\s+(?:codebase|repo|repository|project)\s+is\s+this|what\s+am\s+i\s+looking\s+at|what\s+is\s+tmct|how\s+do\s+i\s+(?:start|begin|get\s+started|get\s+going|load\s+(?:my\s+)?code|index\s+(?:my\s+)?(?:code|repo|repository)|use\s+(?:this|you|tmct))|where\s+do\s+i\s+(?:start|begin))$/;
+
+/** A SHORT memory summary (never a fact dump) for the bare "what do you know". */
+async function memorySummary(memoryDir, graph) {
+  const rows = memoryDir ? await memoryFacts(memoryDir) : [];
+  if (!rows.length) {
+    const hook = moduleCountOf(graph) > 0
+      ? 'ask about this codebase\'s structure (imports, calls, definitions), or teach me with "every X is a Y"'
+      : 'teach me with "every X is a Y", or try general vocabulary like "what is a cache"';
+    return `I haven't been told any facts yet — ${hook}. /memory to inspect, /help for commands.`;
+  }
+  const preds = new Set(rows.map((f) => f.predicate).filter(Boolean));
+  const n = rows.length;
+  return `I remember ${n} fact${n === 1 ? "" : "s"} across ${preds.size} relation `
+    + `type${preds.size === 1 ? "" : "s"}. Ask "what do you know about <term>", or /memory to explore.`;
+}
+
+async function metaLane(query, { graph, memoryDir }) {
+  const q = String(query).trim().toLowerCase().replace(/[?.!]+$/, "").replace(/\s+/g, " ");
+  if (WHAT_KNOW_RE.test(q) || q === "what have you learned" || q === "what have you learnt") {
+    return { text: await memorySummary(memoryDir, graph), via: "meta" };
+  }
+  if (META_ORIENT_RE.test(q)) return { text: orientationText(graph), via: "meta" };
   return null;
 }
 
@@ -623,39 +914,121 @@ async function factAnswer(memoryDir, query, envelope, miss) {
   return null;
 }
 
-/** ASSERT-RECALL READ-BACK (PLAN_CYCLE_4 tail): after "every X is a Y" is
- *  asserted, the *superclass* side is otherwise unqueryable — factAnswer's meta
- *  path matches fact SUBJECTS only, so "what is a Y" (Y the asserted OBJECT) dies
- *  as an honest miss ("'component' isn't a term in this graph's own vocabulary")
- *  even though the fact "X is a kind of Y" is remembered. This is the REVERSE-
- *  membership reader: it consults readFactRows (trust-bearing) for isa-family
- *  facts whose OBJECT is the asked term and reports the members, citing each
- *  fact's provenance verbatim, higher-trust first. Miss-only and run AFTER
- *  factAnswer returns null, so it never shadows the subject-side answer or a
- *  schema hit. Returns { text, replace:true } or null (the miss stands). */
-async function factReadBack(memoryDir, query, envelope, miss) {
+/** "what did i tell you about X" — the multi-turn recall phrasing (a sibling of
+ *  factAnswer's "what do you know about X" KNOW_ABOUT form): everything remembered
+ *  that mentions X on either side. */
+const TOLD_ABOUT_RE = /^what\s+(?:did|have)\s+(?:i|we|you)\s+(?:told|tell|said|say)\s+(?:you|me|us)?\s*about\s+(.+?)[?.!\s]*$/i;
+/** "what kind of thing is an X" — the subject-side membership phrasing the grammar
+ *  doesn't parse: reports X's OWN remembered type (falling back to X's members). */
+const KIND_OF_RE = /^what\s+kind\s+of\s+(?:thing|class|type|category|entity)?\s*(?:is|are)\s+(?:an?\s+)?(.+?)[?.!\s]*$/i;
+/** WHOLE-STORE recall (CHATBENCH_006 lever 3): "what did i tell you [last time]",
+ *  "what facts do you know", "what do you remember" — list EVERY remembered fact
+ *  (no subject/object term to filter on), cited, higher-trust first. The multi-turn
+ *  / cross-session assert-recall surfaces that carry no term the grammar can bind. */
+const WHOLE_RECALL_RE = /^(?:what\s+(?:did|have)\s+(?:i|we)\s+(?:told?|tell|said?|say)\s+(?:you|me|us)?(?:\s+(?:last\s+time|before|earlier|previously|already))?|what\s+facts?\s+do\s+you\s+(?:know|have|remember)|what\s+do\s+you\s+(?:know|remember)|what\s+have\s+you\s+(?:learned|learnt|remembered))[?.!\s]*$/i;
+
+/** The singular class-noun of the graph entity a term names ("app/lib/a.mjs" →
+ *  "module", "Widget" → "class"), via the ask engine's own resolver + the loaded
+ *  graph's class map — or null on a miss/ambiguity/no-graph. Lets forward
+ *  membership answer over a graph INSTANCE, not just a bare class word. */
+async function entityClassNoun(graph, term) {
+  const ent = await resolveEntity(graph, term);
+  if (!ent) return null;
+  const cls = (graph?.byId?.get?.(ent.id) || (graph?.individuals || []).find((i) => i?.id === ent.id))?.class;
+  return cls && CLASS_LABELS[cls] ? CLASS_LABELS[cls][0] : null;
+}
+
+/** ASSERT-RECALL MULTI-TURN READ-BACK (PLAN_CYCLE_4 tail → cycle-005 lever 2):
+ *  once "every X is a Y" is asserted in an earlier turn, the graded assert-recall
+ *  cells (B2/C1 assert) query it back across turns in shapes the graph grammar
+ *  can't parse — so each dies as an honest miss even though "X is a kind of Y" is
+ *  remembered. This reader answers those declare-then-recall shapes from the
+ *  reified Facts (readFactRows — trust-bearing), citing each fact's provenance
+ *  verbatim, higher-trust first:
+ *    (a) FORWARD membership "is an X a Y" — X a class WORD ("is a module a
+ *        component") OR a graph INSTANCE ("is app/lib/a.mjs a component", resolved
+ *        to its class-noun) — yes iff a remembered isa-family fact says so;
+ *    (b) RECALL "what did i tell you about X" — every remembered fact mentioning X;
+ *    (c) REVERSE membership — "what is a Y" reports Y's members (object-side), and
+ *        "what kind of thing is an X" reports X's own type (subject-side first).
+ *  Miss-only and run AFTER factAnswer returns null, so it never shadows the
+ *  subject-side answer or a schema hit. Returns { text, replace:true } or null. */
+async function factReadBack(memoryDir, query, envelope, miss, graph = null) {
   if (!miss) return null;
   let normFactTerm;
   try { ({ normFactTerm } = await import("./memory/core.mjs")); } catch { return null; }
   const q = String(query).trim();
-  // The meta form the grammar's T5 template speaks ("what is a Y"), taken from the
-  // parse when present, else recognized directly on a no-parse miss (same required-
-  // article discipline as factAnswer's own meta fallback).
+  const rows = await factRows(memoryDir);
+  if (!rows.length) return null;
+  const isa = rows.filter((f) => ISA_PREDICATES.has(f.predicate));
+  const byTrust = (a, b) => b.trust - a.trust;
+  const renderMany = (hits) => {
+    const shown = hits.slice(0, FACT_ANSWER_CAP).map(renderFactLine);
+    const n = hits.length - FACT_ANSWER_CAP;
+    const extra = n > 0 ? `\n…and ${n} more remembered fact${n === 1 ? "" : "s"}.` : "";
+    return { text: shown.join("\n") + extra, replace: true };
+  };
+
+  // (d) WHOLE-STORE recall (CHATBENCH_006 lever 3) — "what did i tell you last time",
+  // "what facts do you know": no term to bind, so list every remembered fact,
+  // higher-trust first, each cited. Answers the cross-session assert-recall surfaces.
+  if (WHOLE_RECALL_RE.test(q)) {
+    const hits = (isa.length ? isa : rows).slice().sort(byTrust);
+    if (!hits.length) return null;
+    return renderMany(hits);
+  }
+
+  // (a) FORWARD membership — "is an X a Y". X's fact-subject candidates are the
+  // term itself (a class word) AND, when it resolves in the graph, its class-noun
+  // (an instance) — so "is app/lib/a.mjs a component" answers off "module …".
+  const isaAsk = q.match(ISA_ASK_RE);
+  if (isaAsk) {
+    const objVariants = factTermVariants(normFactTerm, isaAsk[2]);
+    const subjCandidates = new Set(factTermVariants(normFactTerm, isaAsk[1]));
+    const noun = await entityClassNoun(graph, isaAsk[1]);
+    if (noun) for (const v of factTermVariants(normFactTerm, noun)) subjCandidates.add(v);
+    const hit = isa
+      .filter((f) => subjCandidates.has(f.subject) && objVariants.has(f.object))
+      .sort(byTrust)[0];
+    if (hit) return { text: `yes — ${renderFactLine(hit)}`, replace: true };
+    return null; // no remembered fact — the honest miss stands (never a guessed "no")
+  }
+
+  // (b) RECALL — "what did i tell you about X": every remembered fact mentioning X.
+  const told = q.match(TOLD_ABOUT_RE);
+  if (told) {
+    const variants = factTermVariants(normFactTerm, told[1]);
+    const hits = rows.filter((f) => variants.has(f.subject) || variants.has(f.object)).sort(byTrust);
+    if (!hits.length) return null;
+    const term = variants.has(hits[0].subject) ? hits[0].subject : hits[0].object;
+    const shown = hits.slice(0, FACT_ANSWER_CAP).map((f) => `  ${renderFactLine(f)}`);
+    const extra = hits.length > FACT_ANSWER_CAP ? `\n  …and ${hits.length - FACT_ANSWER_CAP} more.` : "";
+    return { text: `${hits.length} remembered fact${hits.length === 1 ? "" : "s"} about ${term}:\n${shown.join("\n")}${extra}`, replace: true };
+  }
+
+  // (c) REVERSE / "what kind of thing" membership. The meta form ("what is a Y")
+  // comes from the parse when present, else recognized directly on a no-parse miss;
+  // "what kind of thing is an X" is recognized regardless (the grammar never parses
+  // it as meta). "what is a Y" reports Y's MEMBERS (object-side); "what kind of
+  // thing is an X" reports X's own TYPE (subject-side first), so both directions
+  // of a single remembered "X is a kind of Y" are queryable.
   let term = envelope?.parsed?.shape === "meta" ? envelope.parsed.object : null;
-  if (!term && !envelope?.parsed) {
+  let kindOf = false;
+  const mk = q.match(KIND_OF_RE);
+  if (mk) { term = mk[1]; kindOf = true; }
+  else if (!term && !envelope?.parsed) {
     const m = q.match(/^what\s+(?:is|are)\s+an?\s+(.+?)[?.!\s]*$/i);
     if (m) term = m[1];
   }
   if (!term) return null;
   const variants = factTermVariants(normFactTerm, term);
-  const hits = (await factRows(memoryDir))
-    .filter((f) => ISA_PREDICATES.has(f.predicate) && variants.has(f.object))
-    .sort((a, b) => b.trust - a.trust);
+  const subjectHits = isa.filter((f) => variants.has(f.subject)).sort(byTrust);
+  const objectHits = isa.filter((f) => variants.has(f.object)).sort(byTrust);
+  const hits = kindOf
+    ? (subjectHits.length ? subjectHits : objectHits)
+    : (objectHits.length ? objectHits : subjectHits);
   if (!hits.length) return null;
-  const shown = hits.slice(0, FACT_ANSWER_CAP).map(renderFactLine);
-  const n = hits.length - FACT_ANSWER_CAP;
-  const extra = n > 0 ? `\n…and ${n} more remembered fact${n === 1 ? "" : "s"}.` : "";
-  return { text: shown.join("\n") + extra, replace: true };
+  return renderMany(hits);
 }
 
 // ---- W5: corpus on-demand — LOCAL tier only, behind an explicit flag ----
@@ -738,14 +1111,121 @@ async function recallSummary(memoryDir) {
   }
 }
 
+/** "[and/so/…] what about X" — a discourse continuation that re-asks the previous
+ *  turn's question with X swapped in. */
+const WHAT_ABOUT_RE = /^(?:(?:and|so|but|ok|okay|now|then)\s+)*what about\s+(.+?)[?.!\s]*$/i;
+/** A code-ish name token in a prior query (a path/dotted name, or a CamelCase/
+ *  Capitalized symbol) — the subject "what about X" replaces. */
+const NAME_TOKEN_RE = /\b[\w-]+(?:[/.][\w-]+)+\b|\b[A-Z][A-Za-z0-9_]*\b/;
+
+/** DISCOURSE CONTINUATION (CHATBENCH_006 lever 2): "what about X" carries the PRIOR
+ *  turn's question shape across the turn boundary — re-asking it with X in place of
+ *  the previous subject/object. Returns the reconstructed query (parsed like any
+ *  subject question, so X resolves and becomes the new focus), or null when there's
+ *  no prior query or no name token to swap (→ the ordinary honest miss stands). */
+function discourseRewrite(query, last) {
+  const m = String(query).match(WHAT_ABOUT_RE);
+  if (!m || !last?.query) return null;
+  const prevQ = String(last.query);
+  if (!NAME_TOKEN_RE.test(prevQ)) return null;
+  const newSubj = m[1].trim();
+  return prevQ.replace(NAME_TOKEN_RE, () => newSubj);
+}
+
+// ---- curated SEON definitions (corpus/seon/definitions.jsonl) ----
+// A "what is a <term>" for a LEXICON term prefers the curated one-sentence
+// definition — the richer surface form of the same curated SEON knowledge that the
+// concept seed reifies — over the bare seon concept fact / schema-docs / honest
+// miss. Cited via:"corpus/seon". Two guards keep it honest and test-safe:
+//   - it only fires when this repo actually carries the SEON concept seed (a
+//     corpus:seon fact about the term is in memory) — so a repo seeded with only
+//     ConceptNet (or nothing) is byte-unchanged;
+//   - a fact the USER personally asserted (ace:chat) still wins — you told me beats
+//     the corpus definition.
+
+let seonDefsPromise = null;
+/** Load corpus/seon/definitions.jsonl once → Map(normFactTerm(term) → definition).
+ *  Lazy + failure-tolerated (chat.mjs ethos): any failure degrades to an empty map. */
+function seonDefinitions() {
+  if (!seonDefsPromise) {
+    seonDefsPromise = (async () => {
+      const { SEON_DEFINITIONS_FILE } = await import("./corpus/conceptnet.mjs");
+      const { normFactTerm } = await import("./memory/core.mjs");
+      const raw = await readFile(SEON_DEFINITIONS_FILE, "utf8");
+      const map = new Map();
+      for (const line of raw.split("\n")) {
+        const t = line.trim();
+        if (!t) continue;
+        try {
+          const row = JSON.parse(t);
+          if (row.term && row.definition) map.set(normFactTerm(row.term), String(row.definition));
+        } catch { /* skip a malformed line, never throw */ }
+      }
+      return map;
+    })().catch(() => new Map());
+  }
+  return seonDefsPromise;
+}
+
+/** The meta term a "what is a X" / "what does X mean" / "define X" question asks
+ *  about — from the parse when present, else recognized directly (same required-
+ *  article discipline as the grammar's T5). Null when the line isn't such a form. */
+function metaTermOf(query, envelope) {
+  if (envelope?.parsed?.shape === "meta" && envelope.parsed.object) return envelope.parsed.object;
+  const q = String(query).trim();
+  const m = q.match(/^what\s+(?:is|are)\s+an?\s+(.+?)[?.!\s]*$/i)
+    || q.match(/^what\s+(?:does|do)\s+(?:an?\s+)?(.+?)\s+means?[?.!\s]*$/i)
+    || q.match(/^define\s+(?:an?\s+)?(.+?)[?.!\s]*$/i);
+  return m ? m[1].trim() : null;
+}
+
+/** The curated SEON definition to PREFER for a "what is a <lexicon term>", or null.
+ *  Gated: the term parses as a meta question, is a grammar-lexicon noun, has a
+ *  curated definition, this repo carries the SEON concept seed for it (a corpus:seon
+ *  fact), and the user has NOT personally asserted a fact about it. Returns { text,
+ *  term } or null. Lazy + failure-tolerated throughout. */
+async function curatedDefinitionAnswer(query, envelope, { memoryDir, lexicon }) {
+  if (!memoryDir) return null;
+  const term = metaTermOf(query, envelope);
+  if (!term) return null;
+  let normFactTerm;
+  try { ({ normFactTerm } = await import("./memory/core.mjs")); } catch { return null; }
+  // lexicon-noun gate: the curated defs are keyed on SE lexicon terms only.
+  let lex = lexicon;
+  try {
+    if (!lex) { const { loadLexicon } = await import("./grammar/lexicon.mjs"); lex = loadLexicon(); }
+    const { lookupNoun } = await import("./grammar/lexicon.mjs");
+    if (!lookupNoun(lex, term)) return null;
+  } catch { return null; }
+  const def = (await seonDefinitions()).get(normFactTerm(term));
+  if (!def) return null;
+  // tie the definition to the SEON concept seed being present, and let a user fact win.
+  const variants = factTermVariants(normFactTerm, term);
+  const facts = await memoryFacts(memoryDir);
+  const about = facts.filter((f) => variants.has(f.subject) || variants.has(f.object));
+  if (about.some((f) => f.provenance.includes("ace:chat"))) return null; // you told me — that wins
+  if (!about.some((f) => f.provenance.includes("corpus:seon"))) return null; // no SEON seed here
+  return { text: `${def} (source: corpus/seon)`, term };
+}
+
 /** A bare question → tmct_ask. When a focus is set AND the graph is in hand we
  *  call ask() directly to thread the focus as contextId (so a pronoun like "it"
  *  resolves to the focus) — building the SAME delimited string dispatchTool emits;
  *  otherwise the unchanged dispatchTool path (which also yields the no-graph error).
  *  A hit updates the focus to the resolved object. Grammar miss / ToolError → a
  *  normal answer, never a crash. */
-async function runAsk(query, { config, source, graph, focus, templates, memoryDir, env }) {
+async function runAsk(query, { config, source, graph, focus, last, templates, memoryDir, sessionId = "", lexicon = null, env }) {
   const ts = new Date().toISOString();
+  // DISCOURSE ANAPHORA (CHATBENCH_006 levers 1+2): a follow-up like "which of those
+  // are tested" / "how many of those" / "count them" filters or counts the PREVIOUS
+  // answer's entity set. That set is the ids the last dispatched turn cited — carried
+  // on `last.detail.matches`. Threading it as ask()'s `prev` is what lets the anaphora
+  // node resolve instead of the "needs a previous answer" honest miss.
+  const prev = (last?.detail?.matches || []).map((m) => m?.id).filter(Boolean);
+  // The query the ENGINE parses: a "what about X" continuation is rewritten to the
+  // prior shape with X swapped in; everything else parses verbatim. The record and
+  // transcript keep the user's ACTUAL words (`query`), only the parse target changes.
+  const askQuery = discourseRewrite(query, last) ?? query;
   // W2: the explicit recall forms are answered from memory's folded blocks, never
   // the graph. Gated on memoryDir — a bare runTurn (no session shell) stays pure.
   if (memoryDir && RECALL_ASK_RE.test(String(query).trim())) {
@@ -758,12 +1238,16 @@ async function runAsk(query, { config, source, graph, focus, templates, memoryDi
   let envelope = null;
   try {
     let text;
-    if (graph && focus?.id) {
+    if (graph && (focus?.id || prev.length)) {
+      // Direct ask() when EITHER a focus is set (thread it as contextId so "it"
+      // binds) OR the previous turn produced a set to refer back to (thread it as
+      // `prev` for the anaphora node). Builds the SAME delimited envelope dispatchTool
+      // emits, so the parse below is identical either way.
       const { ask } = await import("./ask.mjs");
-      const r = ask(graph, query, { contextId: focus.id });
+      const r = ask(graph, askQuery, { contextId: focus?.id ?? null, prev });
       text = `${r.content}${ASK_ENVELOPE_DELIM}${JSON.stringify(r.tmct_ask, null, 2)}`;
     } else {
-      text = await dispatchTool("tmct_ask", { query }, { config, source });
+      text = await dispatchTool("tmct_ask", { query: askQuery }, { config, source });
     }
     const [content, envJson] = text.split(ASK_ENVELOPE_DELIM);
     answer = content;
@@ -786,21 +1270,33 @@ async function runAsk(query, { config, source, graph, focus, templates, memoryDi
   // orientation swap below is template wording, so those turns carry via:"template".
   let via = "composed";
   let recordMiss = miss;
-  // On a MISS: a conversational miss (a greeting, "what can you do", a very short
-  // non-code line) gets the friendly orientation instead of the raw grammar hint. A
-  // near-miss STRUCTURAL question keeps the precise hint the engine already produced.
-  if (miss && isConversational(query)) {
-    answer = tRender(templates, T_ORIENTATION) ?? TEMPLATES_UNAVAILABLE;
-    via = "template";
-  } else if (memoryDir) {
-    // W4: vocabulary/definition questions consult the MEMORY graph's Facts
-    // alongside the schema-docs surface — a remembered fact answers a miss (or
-    // extends a schema hit), cited with its provenance verbatim. Checked BEFORE
-    // recall: a reified fact is stronger evidence than a transcript echo.
-    // Subject-side facts first (factAnswer), then the reverse-membership read-back
-    // (factReadBack) so an asserted "every X is a Y" answers "what is a Y" too.
+  // MISS handling. The intent lanes + short-miss are RECOGNIZER-gated on the query
+  // text AND only consulted on a would-miss, so a real graph query — a hit, an honest
+  // empty with a receipt, a fuzzy repair — is never hijacked. Order: (1) META/SELF
+  // lane (would-miss), (2) conversational orientation (would-miss), (3) memory
+  // facts/recall (a fact EXTENDS a non-miss schema hit too — NOT miss-gated),
+  // (4) TEACH lane (would-miss), (5) the short tailored miss (would-miss).
+  let handled = false;
+  // (1) #2 META/SELF: bare self/session questions ("what do you know", "what is this
+  // codebase", "how do i start") → a summary / orientation, answered before the
+  // fact-dump readers so "what do you know" gets a summary, not raw facts.
+  if (miss) {
+    const meta = await metaLane(query, { graph, memoryDir });
+    if (meta) { answer = meta.text; via = meta.via; recordMiss = false; handled = true; }
+  }
+  if (!handled && miss && isConversational(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).
+    answer = orientationAnswer(templates, graph); via = "template"; handled = true;
+  } else if (!handled && memoryDir) {
+    // W4: vocabulary/definition questions consult the MEMORY graph's Facts alongside
+    // the schema-docs surface — a remembered fact answers a miss OR extends a (non-
+    // miss) schema hit, cited with its provenance verbatim. Checked BEFORE recall: a
+    // reified fact is stronger evidence than a transcript echo. Subject-side facts
+    // first (factAnswer), then the reverse-membership read-back (factReadBack) so an
+    // asserted "every X is a Y" answers "what is a Y" too.
     const fact = (await factAnswer(memoryDir, query, envelope, miss))
-      ?? (await factReadBack(memoryDir, query, envelope, miss));
+      ?? (await factReadBack(memoryDir, query, envelope, miss, graph));
     if (fact) {
       answer = fact.replace ? fact.text : `${answer}\n${fact.text}`;
       via = "fact";
@@ -817,6 +1313,34 @@ async function runAsk(query, { config, source, graph, focus, templates, memoryDi
       }
     }
   }
+  // CURATED SEON DEFINITION (corpus/seon) — a "what is a <lexicon term>" prefers the
+  // curated prose definition over the seon concept fact / schema-docs / honest miss.
+  // Runs after the fact branch and overrides its corpus-fact answer (via:"fact"), but
+  // curatedDefinitionAnswer itself defers to a user-asserted (ace:chat) fact, so a
+  // "you told me" answer already standing is left untouched. Skips the meta/self +
+  // conversational lanes (via:"meta"/"template"), which answer a different question.
+  if (via === "composed" || via === "fact") {
+    const def = await curatedDefinitionAnswer(query, envelope, { memoryDir, lexicon });
+    if (def) { answer = def.text; via = "corpus/seon"; recordMiss = false; }
+  }
+  // (4) #2 TEACH lane — a teach-shaped would-miss nothing above answered: route to
+  // memory, or say what CAN be remembered (LOUD), never the wall / a silent drop.
+  if (miss && recordMiss && via === "composed") {
+    const taught = await teachLane(query, { memoryDir, sessionId, lexicon });
+    if (taught) { answer = taught.text; via = taught.via; recordMiss = taught.miss; }
+  }
+  // (5) #1 SHORT TAILORED MISS — replace ONLY the engine's full grammar cheat-sheet
+  // wall (WALL_MISS_RE). Receipt-bearing misses keep their specific wording.
+  if (miss && recordMiss && via === "composed" && WALL_MISS_RE.test(answer)) {
+    answer = shortMissHint(query); via = "miss";
+  }
+  // #4 HONEST-EMPTY POLISH — an empty CODE graph: any still-standing engine
+  // dead-end (an honest empty, the short miss, the bootstrap note) carries the exit
+  // toward a real graph, unless it already points there. Only when genuinely empty.
+  if (recordMiss && (via === "composed" || via === "miss")
+      && noCodeGraph(graph) && !/--repo|tmct init|no code graph/i.test(answer)) {
+    answer = `${answer}\n(this repo has no code graph — try \`--repo <path>\` or \`tmct init\`.)`;
+  }
   // W5 (flag-gated, default OFF): an unknown-term miss may consult the LOCAL
   // committed corpus slice — a hit APPENDS a grounded, licence-cited aside under
   // the honest miss (the miss itself stands; the aside is context, not an answer).
@@ -975,7 +1499,14 @@ export async function runTurn(input, { config, source = defaultSource, graph = n
     return { ...finished, last: { query: line, answer: finished.answer, detail: finished.detail ?? null } };
   };
 
-  // Conversational layer first (greetings, thanks, help, bye, why/say-more) — these
+  // Slash-optional system commands: a bare leading command word ("stats",
+  // "memory", "describe X") is routed to its slash form BEFORE the conversational
+  // layer, so a forgiving shell answers "stats" the way it answers "/stats" instead
+  // of falling through to the generic orientation.
+  const bareCmd = asBareCommand(line);
+  if (bareCmd) return withLast(await runCommand(bareCmd, ctx));
+
+  // Conversational layer next (greetings, thanks, help, bye, why/say-more) — these
   // resolve no entity and carry their own preserved `last`.
   const convo = conversationalTurn(line, ctx);
   if (convo) return convo;
@@ -989,10 +1520,27 @@ export async function runTurn(input, { config, source = defaultSource, graph = n
     const asserted = await assertTurn(line, ctx);
     if (asserted) return withLast(asserted);
   }
+  // MEMORY-STORE counts first ("how many facts / utterances do you know") — the
+  // memory graph owns Facts + Utterances, so these are answerable and consistent
+  // with `/memory`. Checked before answerCount (which reads the CODE graph and would
+  // otherwise say "I can't count facts"); it only speaks for a memory-class noun, so
+  // structural counts (classes/functions/…) and sessions fall through unaffected.
+  if (memoryDir) {
+    const memCount = await answerMemoryCount(memoryDir, line);
+    if (memCount != null) return withLast(plainTurn(line, memCount, { via: "count", focus }));
+  }
   // Aggregate/count questions are answered mechanically off the loaded graph header,
   // BEFORE falling through to the ask engine (focus unchanged — a count names no entity).
   const count = answerCount(graph, line);
-  if (count != null) return withLast(plainTurn(line, count, { via: "count", focus }));
+  if (count != null) {
+    // An "I can't count <noun>" from a bare kind may still be answerable from an
+    // ASSERTED vocabulary fact ("every class is a type" → "how many types" = the
+    // class count). countFromFacts declines on a real graph kind, so ordinary
+    // counts are unaffected; it only speaks for a remembered object noun.
+    const viaFact = memoryDir ? await countFromFacts(graph, memoryDir, line) : null;
+    if (viaFact != null) return withLast(plainTurn(line, viaFact, { via: "fact", focus }));
+    return withLast(plainTurn(line, count, { via: "count", focus }));
+  }
   return withLast(await runAsk(line, ctx));
 }
 
@@ -1013,11 +1561,20 @@ export const SEED_PREFER = ["rdfs:subClassOf", "rdf:type", "mgx:usedFor", "mgx:p
  *  corpus seed, so re-runs skip without even reading the slice. */
 export const SEED_MARKER_REL = join(".tmct", "memory", "corpus-seed.json");
 
-/** Seed the ConceptNet slice into <repo>/.tmct/memory once. Idempotent twice
- *  over (the marker short-circuits; seedMemory itself content-hashes fact ids)
- *  and failure-tolerated: a missing/broken corpus degrades to the unseeded
- *  bootstrap — never an error before the prompt. Returns seedMemory's
- *  { appended, skipped, total } on a fresh seed, null when skipped/failed. */
+/** Seed the starter corpus into <repo>/.tmct/memory once, in TWO passes:
+ *    1. the curated SEON ontology (corpus/seon/concepts.jsonl) FIRST and UNCAPPED
+ *       — it is small + fully curated (the SE vocabulary + orientation facts),
+ *       tagged "corpus:seon", so a fresh repo knows the curated terms before any
+ *       general ConceptNet noise;
+ *    2. THEN the capped ConceptNet slice (the definitional band first, SEED_LIMIT
+ *       facts), tagged "corpus:conceptnet".
+ *  seon runs first so its curated facts win the content-hash idempotency race — a
+ *  term the ConceptNet slice also carries keeps the seon provenance. Idempotent
+ *  twice over (the marker short-circuits; seedMemory content-hashes fact ids) and
+ *  failure-tolerated: a missing/broken corpus degrades to the unseeded bootstrap —
+ *  never an error before the prompt. Returns { appended, skipped, total, seon,
+ *  conceptnet } on a fresh seed (the banner counts stay honest), null when
+ *  skipped/failed. */
 async function seedBootstrapMemory(repo) {
   const marker = join(repo, SEED_MARKER_REL);
   try {
@@ -1025,11 +1582,22 @@ async function seedBootstrapMemory(repo) {
     return null; // already seeded — the marker is authoritative
   } catch { /* no marker → first run */ }
   try {
-    const { seedMemory } = await import("./corpus/conceptnet.mjs");
-    const res = await seedMemory(repo, { limit: SEED_LIMIT, prefer: SEED_PREFER });
+    const { seedMemory, SEON_CONCEPTS_FILE } = await import("./corpus/conceptnet.mjs");
+    // (1) curated SEON ontology — uncapped, seon-tagged, seeded FIRST.
+    const seon = await seedMemory(repo, { slicePath: SEON_CONCEPTS_FILE, provenancePrefix: "corpus:seon" });
+    // (2) the capped ConceptNet band — byte-identical to the prior single seed.
+    const conceptnet = await seedMemory(repo, { limit: SEED_LIMIT, prefer: SEED_PREFER });
+    const res = {
+      appended: seon.appended + conceptnet.appended,
+      skipped: seon.skipped + conceptnet.skipped,
+      total: seon.total + conceptnet.total,
+      seon: seon.appended,
+      conceptnet: conceptnet.appended,
+    };
     await mkdir(dirname(marker), { recursive: true });
     await writeFile(marker, JSON.stringify({
-      seededAt: new Date().toISOString(), limit: SEED_LIMIT, appended: res.appended, skipped: res.skipped,
+      seededAt: new Date().toISOString(), limit: SEED_LIMIT,
+      appended: res.appended, skipped: res.skipped, seon: res.seon, conceptnet: res.conceptnet,
     }) + "\n");
     return res;
   } catch {
@@ -1086,16 +1654,27 @@ export async function createSession({
   cwd = process.cwd(),
   gitRoot = gitToplevel,
 } = {}) {
+  // Graph resolution order for the chat surface (documented; --repo wins):
+  //   1. --repo <path>       → pins <path>/.tmct/graph.json (repo AND graph).
+  //   2. TMCT_GRAPH_FILE env → loads that graph anywhere (loadConfig reads it), so
+  //      `TMCT_GRAPH_FILE=<path> tmct chat` works even inside a git repo — the chat
+  //      surface used to ignore it (only the `cli` tool path honoured it). The repo
+  //      for logs/memory is still the git root / cwd; only the graph file is overridden.
+  //   3. git root            → <root>/.tmct/graph.json (the default target).
+  //   4. cwd                 → <cwd>/.tmct/graph.json (not a git repo).
   // Default the target to the GIT ROOT, not raw cwd: running from a nested package
   // dir (npm sets cwd there) would otherwise index only that package's ~few modules
-  // instead of the whole repo. --repo stays the explicit override.
+  // instead of the whole repo.
   let repo;
   let config;
   if (repoPath) { repo = repoPath; config = configFor(repoPath); }
   else {
     const root = gitRoot(cwd);
-    if (root) { repo = root; config = configFor(root); }
-    else { repo = cwd; config = loadConfig(env, cwd); } // not a git repo — cwd/env default
+    repo = root || cwd;
+    const envGraph = env.TMCT_GRAPH_FILE && String(env.TMCT_GRAPH_FILE).trim();
+    // TMCT_GRAPH_FILE (via loadConfig) overrides the repo-derived default graph path;
+    // otherwise the repo's own .tmct/graph.json is the target.
+    config = envGraph ? loadConfig(env, cwd) : { graphFile: join(repo, DEFAULT_GRAPH_REL) };
   }
 
   // Load the graph once up front — the banner needs the module count, and focus/`it`
@@ -1159,14 +1738,22 @@ export async function createSession({
   if (empty && String(env.TMCT_NO_SEED || "") !== "1") {
     seeded = await seedBootstrapMemory(repo);
   }
+  // #3/#5: 0 modules means no code graph to answer structure questions from —
+  // whether the graph file is absent (empty bootstrap) OR present with no code
+  // entities (the degenerate trap). Both get orienting, non-over-promising banner
+  // + greeting messaging rather than a silent dead-end.
+  const noCodeGraph = moduleCount === 0;
   const bannerLines = [
-    empty
-      // Empty-graph bootstrap: honest-miss messaging, never an error before the prompt.
-      ? `tmct chat — ${repo} — no graph loaded — starting empty; ` +
+    noCodeGraph
+      // No code graph: honest, orienting messaging — never an error before the prompt.
+      ? `tmct chat — ${repo} — no code graph loaded — ${empty ? "starting empty" : "graph has no code entities"}; ` +
         `the conversation is remembered to ${DEFAULT_GRAPH_REL} — log ${logFile}`
       : `tmct chat — ${repo} — ${moduleCount} module(s) — log ${logFile}`,
-    // the honest seed line appears ONLY on the run that actually seeded
-    ...(seeded ? [`seeded ${seeded.appended} starter facts from the ConceptNet slice — /memory to inspect`] : []),
+    // the honest seed line appears ONLY on the run that actually seeded — the count
+    // is the TOTAL appended, split into the curated SEON ontology + the ConceptNet band.
+    ...(seeded ? [`seeded ${seeded.appended} starter facts (${seeded.seon} curated SEON + ${seeded.conceptnet} ConceptNet) — /memory to inspect`] : []),
+    // no code indexed → point at how to get one, and at what IS answerable now
+    ...(noCodeGraph ? ['no code indexed yet — run `tmct init` here or pass --repo <path>; meanwhile try "what is a cache"'] : []),
     "pass --repo <path> to target a different repo",
     "ask a question, or /help for commands (/stats for an overview) — /exit to leave",
   ];