@polycode-projects/the-mechanical-code-talker 0.5.0 → 0.7.0

package/src/chat.mjs

@@ -39,7 +39,8 @@
 
 import { join, dirname } from "node:path";
 import { createWriteStream } from "node:fs";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
 import { createInterface } from "node:readline/promises";
 import { spawnSync } from "node:child_process";
 import { dispatchTool } from "./server.mjs";
@@ -104,6 +105,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. ----
@@ -191,6 +223,45 @@ async function countFromFacts(graph, memoryDir, query) {
   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) {
@@ -234,6 +305,12 @@ const STRUCT_WORDS = new Set([
   "subclass", "subclasses", "inherit", "inherits", "test", "tests", "touch", "touches",
   "commit", "commits", "export", "exports", "caller", "callers", "callee", "callees",
   "history", "where", "mentioned", "signature", "impact",
+  // relation-concept vocabulary (gerunds + relation nouns) so a SHORT relation touch
+  // ("what is calling", "what about inheritance") is a structural question, not
+  // small-talk — otherwise a ≤3-word relation touch is grabbed by the conversational
+  // orientation before the relation concept force can serve it.
+  "importing", "calling", "invoking", "inheriting", "containing", "contains", "containment",
+  "testing", "defining", "touching", "extending", "inheritance", "coverage", "member", "members",
 ]);
 
 /** Does this look like small-talk / an orientation request rather than a
@@ -269,6 +346,15 @@ 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 CONCEPT FORCE (concept.mjs): the three-band answer to a vague "what is a X"
+ *  that names a known concept WITH instances — {definition}/{examples}/{followups}. */
+const T_CONCEPT = "concept-force";
 
 /** 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. */
@@ -369,9 +455,189 @@ 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 (imports, calls, definitions) yet. "
+      + "For those I need a `.tmct/graph.json` produced by a graph producer — point me at one with `--repo <path>`, "
+      + "or try the shipped example `npm run example:mini`. tmct reads graphs; it doesn't index code itself. "
+      + 'For general vocabulary, `tmct init` seeds concepts — 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;
 }
 
@@ -543,11 +809,18 @@ const FACT_PREDICATE_PHRASES = {
 };
 const factPhrase = (f) => `${f.subject} ${FACT_PREDICATE_PHRASES[f.predicate] || f.predicate} ${f.object}`;
 
-/** One rendered fact line: "you told me" when the chat asserted it (an ace:chat
- *  provenance tag), "i learned" for corpus-only facts — provenance VERBATIM. */
+/** One rendered fact line. An OPERATOR-asserted fact keeps the true first-person
+ *  provenance ("you told me: …"). A CORPUS fact is presented as clean DATA with its
+ *  source cited — NEVER "i learned: …", which over-claims and anthropomorphises
+ *  (especially when the corpus row is noise); the relation and its provenance speak
+ *  for themselves. Provenance stays VERBATIM either way. */
 function renderFactLine(f) {
-  const lead = f.provenance.includes("ace:chat") ? "you told me" : "i learned";
-  return `${lead}: ${factPhrase(f)}${f.provenance ? ` (source: ${f.provenance})` : ""}`;
+  const cite = f.provenance ? ` (source: ${f.provenance})` : "";
+  if (f.provenance.includes("ace:chat")) return `you told me: ${factPhrase(f)}${cite}`;
+  // CORPUS facts are background DATA — present the relation plainly, cited to its
+  // source, NEVER "i learned: …" (the footgun: a first-person claim over corpus noise).
+  if (f.provenance.includes("corpus:")) return `${factPhrase(f)}${cite}`;
+  return `i learned: ${factPhrase(f)}${cite}`;
 }
 
 /** Read every reified Fact out of the memory graph as plain {subject, predicate,
@@ -597,8 +870,8 @@ const ISA_ASK_RE = /^(?:is|are)\s+(?:an?\s+)?(.+?)\s+(?:a\s+kind\s+of|a\s+type\s
 const ISA_PREDICATES = new Set(["rdfs:subClassOf", "rdf:type"]);
 /** "what do you know about caches" — the open recall-everything form. */
 const KNOW_ABOUT_RE = /^what\s+do\s+you\s+know\s+about\s+(.+?)[?.!\s]*$/i;
-/** How many facts a single answer lists before "…and N more". */
-const FACT_ANSWER_CAP = 5;
+/** How many facts a single answer lists before the remainder is paged with "more". */
+const FACT_ANSWER_CAP = 32;
 
 /** W4 seam: answer (or extend) a vocabulary/definition question from the MEMORY
  *  graph's Facts. Returns { text, replace } — `replace:false` means the engine's
@@ -625,9 +898,11 @@ async function factAnswer(memoryDir, query, envelope, miss) {
     const variants = factTermVariants(normFactTerm, metaTerm);
     const hits = (await memoryFacts(memoryDir)).filter((f) => variants.has(f.subject));
     if (!hits.length) return null;
-    const shown = hits.slice(0, FACT_ANSWER_CAP).map(renderFactLine);
-    const extra = hits.length > FACT_ANSWER_CAP ? `\n…and ${hits.length - FACT_ANSWER_CAP} more remembered fact${hits.length - FACT_ANSWER_CAP === 1 ? "" : "s"}.` : "";
-    return { text: shown.join("\n") + extra, replace: miss };
+    const lines = hits.map(renderFactLine);
+    const shown = lines.slice(0, FACT_ANSWER_CAP);
+    const rest = lines.slice(FACT_ANSWER_CAP);
+    const extra = rest.length ? `\n…and ${rest.length} more — say 'more' to see them.` : "";
+    return { text: shown.join("\n") + extra, replace: miss, ...(rest.length ? { pending: { items: rest, noun: "facts" } } : {}) };
   }
   if (!miss) return null;
 
@@ -652,9 +927,11 @@ async function factAnswer(memoryDir, query, envelope, miss) {
     if (!hits.length) return null;
     // echo the STORED spelling ("caches" asked → "cache" known), never a guess
     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 };
+    const lines = hits.map((f) => `  ${renderFactLine(f)}`);
+    const shown = lines.slice(0, FACT_ANSWER_CAP);
+    const rest = lines.slice(FACT_ANSWER_CAP);
+    const extra = rest.length ? `\n  …and ${rest.length} more — say 'more' to see them.` : "";
+    return { text: `${hits.length} remembered fact${hits.length === 1 ? "" : "s"} about ${term}:\n${shown.join("\n")}${extra}`, replace: true, ...(rest.length ? { pending: { items: rest.map((l) => l.trim()), noun: "facts" } } : {}) };
   }
   return null;
 }
@@ -708,10 +985,11 @@ async function factReadBack(memoryDir, query, envelope, miss, graph = 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 };
+    const lines = hits.map(renderFactLine);
+    const shown = lines.slice(0, FACT_ANSWER_CAP);
+    const rest = lines.slice(FACT_ANSWER_CAP);
+    const extra = rest.length ? `\n…and ${rest.length} more — say 'more' to see them.` : "";
+    return { text: shown.join("\n") + extra, replace: true, ...(rest.length ? { pending: { items: rest, noun: "facts" } } : {}) };
   };
 
   // (d) WHOLE-STORE recall (CHATBENCH_006 lever 3) — "what did i tell you last time",
@@ -746,9 +1024,11 @@ async function factReadBack(memoryDir, query, envelope, miss, graph = null) {
     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 };
+    const lines = hits.map((f) => `  ${renderFactLine(f)}`);
+    const shown = lines.slice(0, FACT_ANSWER_CAP);
+    const rest = lines.slice(FACT_ANSWER_CAP);
+    const extra = rest.length ? `\n  …and ${rest.length} more — say 'more' to see them.` : "";
+    return { text: `${hits.length} remembered fact${hits.length === 1 ? "" : "s"} about ${term}:\n${shown.join("\n")}${extra}`, replace: true, ...(rest.length ? { pending: { items: rest.map((l) => l.trim()), noun: "facts" } } : {}) };
   }
 
   // (c) REVERSE / "what kind of thing" membership. The meta form ("what is a Y")
@@ -877,13 +1157,233 @@ function discourseRewrite(query, last) {
   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;
+}
+
+let seonRelsPromise = null;
+/** Load corpus/seon/relations.jsonl once → Map(relationTerm → definition), keyed on
+ *  the concept key ("imports","calls",…). Sits beside definitions.jsonl (same seon
+ *  dir), loaded the same lazy + failure-tolerated way — any failure degrades to an
+ *  empty map, so the relation force simply declines rather than throwing. */
+function relationDefinitions() {
+  if (!seonRelsPromise) {
+    seonRelsPromise = (async () => {
+      const { SEON_DEFINITIONS_FILE } = await import("./corpus/conceptnet.mjs");
+      const relFile = join(dirname(SEON_DEFINITIONS_FILE), "relations.jsonl");
+      const raw = await readFile(relFile, "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.relation && row.definition) map.set(String(row.relation).toLowerCase(), String(row.definition));
+        } catch { /* skip a malformed line, never throw */ }
+      }
+      return map;
+    })().catch(() => new Map());
+  }
+  return seonRelsPromise;
+}
+
+/** 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 };
+}
+
+/** The concept term a vague "what is a X" / "tell me about X" / "what does X mean" /
+ *  "define X" asks about — metaTermOf's forms plus the "tell me about …" opener that
+ *  the graph parser reads as a count. Null when the line isn't such a touch. The
+ *  concept force is gated further downstream (a KNOWN, instance-bearing concept), so
+ *  this only has to recognize the SHAPE, not vet the term. */
+function conceptTermOf(query, envelope) {
+  const base = metaTermOf(query, envelope);
+  if (base) return base;
+  const q = String(query).trim();
+  const m = q.match(/^tell me about\s+(?:an?\s+)?(.+?)[?.!\s]*$/i)
+    // "[and/so/…] what about X" with no good discourse continuation — the concept
+    // KIND word is a concept touch, not a bare module lookup (DEAD-END 4). Gated
+    // downstream by CONCEPT_CLASS/RELATION_TERM, so a real entity name declines here.
+    || q.match(/^(?:(?:and|so|but|ok|okay|now|then)\s+)*what about\s+(?:an?\s+|the\s+)?(.+?)[?.!\s]*$/i);
+  return m ? m[1].trim() : null;
+}
+
+/** The RELATION term a vague touch names — reuses conceptTermOf's shapes ("what is
+ *  X"/"what does X mean"/"tell me about X"/"what about X"), plus the relation-only
+ *  openers the graph parser reads as something else: "what are the imports", "what
+ *  calls are there", "what is calling". Null when the line isn't such a touch. Gated
+ *  downstream by RELATION_TERM, so this only has to recognize the SHAPE. */
+function relationTermOf(query, envelope) {
+  const base = conceptTermOf(query, envelope);
+  if (base) return base;
+  const q = String(query).trim().toLowerCase().replace(/[?.!]+$/, "").replace(/\s+/g, " ");
+  let m;
+  // "what are the imports", "what is the containment", "what are all the calls"
+  if ((m = q.match(/^what\s+(?:are|is)\s+(?:all\s+)?(?:the\s+)?([a-z][a-z-]*?)(?:\s+(?:edges|relationships|relations))?$/))) return m[1];
+  // "what calls are there", "what imports are there"
+  if ((m = q.match(/^what\s+([a-z][a-z-]*?)\s+are\s+there$/))) return m[1];
+  // "what is calling", "what is importing" (bare gerund, no object)
+  if ((m = q.match(/^what\s+(?:is|are)\s+([a-z][a-z-]*ing)$/))) return m[1];
+  return null;
+}
+
+/** THE RELATION CONCEPT FORCE — compose the three-band answer (curated relation
+ *  definition + real example EDGES + pre-validated follow-ups) for a vague touch on a
+ *  relation/edge kind ("what about imports", "what are the calls", "tell me about
+ *  contains"), or null when it isn't one: not a recognizable relation touch, not a
+ *  known edge concept (RELATION_TERM), no curated definition, or the graph has NO
+ *  edges of that kind (composeRelation's own honest-miss gate). Loads the definition
+ *  from the shipped corpus/seon/relations.jsonl, so it works without per-repo memory
+ *  seeding. Lazy + failure-tolerated throughout. Returns { text, pending }. */
+async function relationForceAnswer(query, envelope, { graph, config, source, templates }) {
+  const rawTerm = relationTermOf(query, envelope);
+  if (!rawTerm) return null;
+  let composeRelation; let RELATION_TERM;
+  try { ({ composeRelation, RELATION_TERM } = await import("./concept.mjs")); }
+  catch { return null; }
+  const term = String(rawTerm).toLowerCase();
+  if (!RELATION_TERM[term]) return null; // not an enumerable edge concept — ordinary path owns it
+  const definition = (await relationDefinitions()).get(RELATION_TERM[term]) ?? null;
+  if (!definition) return null;
+  // Same graph-load fallback as conceptForceAnswer: the shell hands the loaded graph
+  // straight in; the pure runTurn(config) path loads it the way dispatchTool does.
+  let g = graph;
+  if (!g && config && source) {
+    try { g = parseEntities(await source.fetchEntities(config)); } catch { g = null; }
+  }
+  if (!g) return null;
+  let composed;
+  try { composed = composeRelation(g, term, { definition }); }
+  catch { return null; }
+  if (!composed) return null;
+  const rendered = tRender(templates, T_CONCEPT, {
+    definition: composed.definition, examples: composed.examples, followups: composed.followups,
+  });
+  const text = rendered ?? `${composed.definition}\n${composed.examples}${composed.followups}`;
+  const pending = composed.remainder && composed.remainder.length
+    ? { items: composed.remainder, noun: composed.noun }
+    : null;
+  return { text, pending };
+}
+
+/** THE CONCEPT FORCE — compose the three-band answer (corpus/seon definition + real
+ *  graph/memory instances + pre-validated follow-ups) for a vague concept touch, or
+ *  null when it isn't one: not a "what is a X"/"tell me about X" shape, not a known
+ *  enumerable concept (CONCEPT_CLASS), no curated definition, or NO instances anywhere
+ *  (composeConcept's own honest-miss gate). Loads the definition DIRECTLY from the
+ *  shipped corpus/seon file (seonDefinitions), so it works without per-repo memory
+ *  seeding; the memory fact rows only ADD remembered "A is a X" examples when present.
+ *  Lazy + failure-tolerated throughout (chat.mjs ethos). Returns { text, instances }. */
+async function conceptForceAnswer(query, envelope, { graph, config, source, memoryDir, templates }) {
+  const rawTerm = conceptTermOf(query, envelope);
+  if (!rawTerm) return null;
+  let normFactTerm; let composeConcept; let CONCEPT_CLASS;
+  try {
+    ({ normFactTerm } = await import("./memory/core.mjs"));
+    ({ composeConcept, CONCEPT_CLASS } = await import("./concept.mjs"));
+  } catch { return null; }
+  const term = normFactTerm(rawTerm);
+  if (!CONCEPT_CLASS[term]) return null; // not an enumerable code concept — ordinary path owns it
+  const definition = (await seonDefinitions()).get(term) ?? null;
+  if (!definition) return null;
+  // The runChat shell hands the loaded graph straight in; the pure runTurn(config)
+  // path (tests, chatbench) does not, so load it the same way dispatchTool does when
+  // it's missing. Failure-tolerated: no loadable graph → no concept force.
+  let g = graph;
+  if (!g && config && source) {
+    try { g = parseEntities(await source.fetchEntities(config)); } catch { g = null; }
+  }
+  if (!g) return null;
+  const rows = memoryDir ? await factRows(memoryDir) : [];
+  let composed;
+  try { composed = composeConcept(g, term, { definition, factRows: rows }); }
+  catch { return null; }
+  if (!composed) return null;
+  const rendered = tRender(templates, T_CONCEPT, {
+    definition: composed.definition, examples: composed.examples, followups: composed.followups,
+  });
+  const text = rendered ?? `${composed.definition}\n${composed.examples}${composed.followups}`;
+  const pending = composed.remainder && composed.remainder.length
+    ? { items: composed.remainder, noun: composed.noun }
+    : null;
+  return { text, instances: composed.instances, pending };
+}
+
 /** 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, last, 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
@@ -939,25 +1439,39 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
   // 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.
+  let factPending = null; // a truncated fact listing's held remainder (for "more" paging)
+  // 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, graph));
     if (fact) {
       answer = fact.replace ? fact.text : `${answer}\n${fact.text}`;
       via = "fact";
       recordMiss = false;
+      if (fact.pending) factPending = fact.pending; // a truncated fact list → paginable remainder
     } else if (miss) {
       // W2: after the honest miss is composed, consult the folded-session memory. A
       // relevant enough block ANSWERS — recalled Q/A framed + cited first, with the
@@ -970,6 +1484,66 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
       }
     }
   }
+  // 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; }
+  }
+  // THE CONCEPT FORCE (concept.mjs) — a vague "what is a X" / "tell me about X" that
+  // names a KNOWN code concept WITH real instances composes the three-band answer
+  // (definition + real examples + pre-validated follow-ups), superseding the bare
+  // schema-doc / curated-definition surface (both corpus-sourced). It declines unless
+  // the term is a known, instance-bearing concept, so a precise query, an unknown
+  // term, or an instance-less concept is never hijacked — the ordinary answer stands.
+  // Runs after the corpus-fact/curated branches (via composed|corpus/seon) but not
+  // over a "you told me" fact, a meta/self summary, or the conversational lanes.
+  let conceptInstances = null;
+  let conceptPending = null;
+  if (via === "composed" || via === "corpus/seon") {
+    const concept = await conceptForceAnswer(query, envelope, { graph, config, source, memoryDir, templates });
+    if (concept) {
+      answer = concept.text; via = "corpus/seon"; recordMiss = false;
+      conceptInstances = concept.instances;
+      conceptPending = concept.pending;
+    } else {
+      // THE RELATION CONCEPT FORCE — the noun force declined, so try the edge-kind
+      // touch ("what about imports", "what are the calls", "tell me about contains").
+      // Same three-band shape over real EDGES; declines unless the term is a known,
+      // edge-bearing relation, so a precise query / unknown word is never hijacked.
+      // For a "what about <relation>" this also SUPERSEDES the discourse rewrite's
+      // dead-end (rewriting the prior question with a relation word rarely resolves) —
+      // but only when the touched word is a relation concept; a real entity name in
+      // "what about X" declines here and the discourse continuation stands.
+      const relation = await relationForceAnswer(query, envelope, { graph, config, source, templates });
+      if (relation) {
+        answer = relation.text; via = "corpus/seon"; recordMiss = false;
+        conceptPending = relation.pending;
+      }
+    }
+  }
+  // (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 — for structure, point me at a \`.tmct/graph.json\` with \`--repo <path>\` or run \`npm run example:mini\`; tmct doesn't index code itself.)`;
+  }
   // 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).
@@ -980,11 +1554,23 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
       via = "corpus";
     }
   }
-  const record = { type: "turn", ts, query, via, resolvedIds, answeredIds, miss: recordMiss };
+  // The concept force answers WITH real example instances — those are the entities the
+  // turn "asked about" (the SchemaClass meta-node is documentation, not a code entity),
+  // so record + expand them, not the schema match.
+  const finalAnsweredIds = conceptInstances ? conceptInstances.map((i) => i.id) : answeredIds;
+  const record = { type: "turn", ts, query, via, resolvedIds, answeredIds: finalAnsweredIds, miss: recordMiss };
   const logLines = [ts, `> ${query}`, answer, ""];
   // `detail` feeds why/say-more's verbose re-render: the traversal receipt + the
-  // matched entities the terse render trims (see renderVerbose).
-  const detail = envelope ? { traversal: envelope.traversal || null, matches: envelope.matches || [] } : null;
+  // matched entities the terse render trims (see renderVerbose). `pending` carries a
+  // truncated listing's held remainder for "more" paging — the concept/relation force
+  // holds it on conceptPending (the relation force resolves no instance ids, so it can
+  // still page even with an empty matches set); a fact listing holds it on factPending.
+  const pending = conceptPending ?? factPending;
+  const detail = conceptInstances
+    ? { traversal: envelope?.traversal || null, matches: conceptInstances, ...(pending ? { pending } : {}) }
+    : (envelope
+      ? { traversal: envelope.traversal || null, matches: envelope.matches || [], ...(pending ? { pending } : {}) }
+      : (pending ? { traversal: null, matches: [], pending } : null));
   return { answer, logLines, record, focus: newFocus, detail };
 }
 
@@ -1111,6 +1697,29 @@ async function assertTurn(line, { memoryDir, sessionId, focus, lexicon = null })
  * subject), `answeredIds` the entity ids an ask answer cited; a slash-command turn
  * also carries its `command` name. Both drive the mgx:asksAbout graph append.
  */
+// ---- "more" pagination — a long examples/facts listing shows the first PAGE
+// entries and holds the remainder on the turn's `last.detail.pending`; a bare
+// "more"/"show more"/"the rest" in the NEXT turn renders the next batch, advancing
+// the same pending state. Any other (real) query produces a fresh `last` without
+// `pending`, so the remainder is naturally cleared — no stale continuation. ----
+const PAGE = 32;
+const MORE_RE = /^(?:more|show more|see more|the rest|next|continue|go on)\b[.!?]*$/i;
+const joinList = (a) => (a.length > 1 ? `${a.slice(0, -1).join(", ")} and ${a[a.length - 1]}` : (a[0] ?? ""));
+
+/** Render the next page of a held remainder (pending: {items:[str], noun}). Returns a
+ *  plain turn whose `detail.pending` carries what's still unseen (null when the batch
+ *  finished the list), so a follow-on "more" continues. */
+function morePage(query, { last, focus }) {
+  const p = last.detail.pending;
+  const batch = p.items.slice(0, PAGE);
+  const rest = p.items.slice(PAGE);
+  const tail = rest.length ? ` …and ${rest.length} more — say 'more' to see them.` : "";
+  const answer = `${joinList(batch)}.${tail}`;
+  const turn = plainTurn(query, answer, { via: "count", focus });
+  turn.detail = { traversal: null, matches: [], ...(rest.length ? { pending: { items: rest, noun: p.noun } } : {}) };
+  return turn;
+}
+
 export async function runTurn(input, { config, source = defaultSource, graph = null, focus = null, last = null, memoryDir = null, sessionId = "", env = process.env, lexicon = null } = {}) {
   const line = String(input ?? "").trim();
   const templates = await chatTemplates(); // failure-tolerated: null degrades, never throws
@@ -1128,11 +1737,25 @@ 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;
 
+  // "more" — page the remainder of a previous long listing, if one is held. Gated on
+  // an actual pending remainder so a bare "more" with nothing to continue falls through
+  // to the ordinary path (an honest miss), never a pretend page.
+  if (MORE_RE.test(line) && Array.isArray(last?.detail?.pending?.items) && last.detail.pending.items.length) {
+    return withLast(morePage(line, ctx));
+  }
+
   if (line.startsWith("/")) return withLast(await runCommand(line, ctx));
   // Declarative ACE sentences ("every module is a artifact") ASSERT into tmct's
   // own memory and confirm — they are statements to remember, not graph queries.
@@ -1142,6 +1765,15 @@ 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);
@@ -1159,26 +1791,40 @@ export async function runTurn(input, { config, source = defaultSource, graph = n
 
 // ---- W3: seedMemory → bootstrap (first run in a graph-less repo) ----
 
-/** How many corpus facts the first-run bootstrap seeds. Measured curve (dev
- *  laptop, appendFact's read-modify-write per fact): 100→~0.16s, 250→~0.54s,
- *  500→~1.7s — the full 500 stays inside a session-start budget, so the seed
- *  runs synchronously and complete (no partial-sync cap needed). */
-export const SEED_LIMIT = 500;
-
-/** Which predicates the capped seed prefers (stable order — see seedMemory's
- *  `prefer`): the definitional band first, so a bootstrap's 500 facts answer
- *  "what is a cache?"-style vocabulary questions rather than location trivia. */
+/** The first-run bootstrap seeds the WHOLE shipped ConceptNet band (no cap) — the
+ *  operator's "seed all 40k" call. `undefined` means seedMemory writes every
+ *  seedable fact in the committed slice (~6.3k). The batched appendFacts write
+ *  (src/memory/core.mjs) makes this a single O(N) pass — the full slice seeds in a
+ *  couple of seconds, inside a session-start budget, so it still runs synchronously
+ *  and complete. A finite value here would re-impose the old cap; keep it undefined
+ *  to mean "all". (Kept as a named export so init.mjs and tests share the intent.) */
+export const SEED_LIMIT = undefined;
+
+/** Which predicates the seed lists FIRST (stable order — see seedMemory's `prefer`):
+ *  the definitional band leads, so the on-disk memory opens with the vocabulary that
+ *  answers "what is a cache?"-style questions rather than location trivia. With the
+ *  cap lifted this only sets ORDER (every fact seeds either way), but a well-ordered
+ *  memory keeps inspection and any future re-cap honest. */
 export const SEED_PREFER = ["rdfs:subClassOf", "rdf:type", "mgx:usedFor", "mgx:partOf", "mgx:capableOf"];
 
 /** The seed marker: its presence means this repo's memory already carries the
  *  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 {
@@ -1186,11 +1832,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 {
@@ -1246,19 +1903,43 @@ export async function createSession({
   env = process.env,
   cwd = process.cwd(),
   gitRoot = gitToplevel,
+  ephemeral = false,
 } = {}) {
+  // EPHEMERAL mode (--ephemeral, or TMCT_EPHEMERAL=1): read the target graph but
+  // write NOTHING back into it. The shipped examples run this way so a demo never
+  // dirties the committed code graph (`npm run example:mini` used to fold a session
+  // into examples/*/.tmct/graph.json and rewrite it). We still read config.graphFile
+  // for structure; only the WRITE base (logs, memory, sessions) is diverted to an OS
+  // temp dir and the read-time graph upsert is suppressed.
+  ephemeral = ephemeral || /^(1|true|yes)$/i.test(String(env.TMCT_EPHEMERAL || ""));
+  // 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) };
   }
 
+  // Ephemeral: keep config.graphFile pointing at the READ graph, but divert the
+  // write base (repo → logs/memory/sessions) to a throwaway temp dir. The committed
+  // target is never touched; the demo's memory simply doesn't persist across runs.
+  if (ephemeral) repo = await mkdtemp(join(tmpdir(), "tmct-ephemeral-"));
+
   // Load the graph once up front — the banner needs the module count, and focus/`it`
   // resolution and contextId threading need it in hand. A missing artifact loads as
   // the empty bootstrap graph (source.mjs) — the banner says so; never an error.
@@ -1305,6 +1986,7 @@ export async function createSession({
   // artifact mid-session must degrade the recording, never kill the chat.
   const turnRecords = [];
   const upsertGraph = async (ended) => {
+    if (ephemeral) return; // a demo/read-only session never writes back to the graph
     if (!turnRecords.length) return; // a zero-turn session never pollutes the graph
     try { await appendSessionToGraph(config.graphFile, { id: sessionId, started: startIso, ended, turns: turnRecords }); }
     catch { /* best-effort — see above */ }
@@ -1320,14 +2002,24 @@ 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 graph → point at how to GET one (a graph producer / --repo / the shipped
+    // example), honest that `tmct init` seeds VOCABULARY, not a code graph, and at what
+    // IS answerable now. tmct reads graphs; it never indexes code itself.
+    ...(noCodeGraph ? ['for code structure, point me at a .tmct/graph.json with --repo <path> or try `npm run example:mini` (tmct reads graphs, it doesn\'t index code); `tmct init` only seeds vocabulary — 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",
   ];
@@ -1400,8 +2092,9 @@ export async function runChat({
   env = process.env,
   cwd = process.cwd(),
   gitRoot = gitToplevel,
+  ephemeral = false,
 } = {}) {
-  const session = await createSession({ repoPath, source, env, cwd, gitRoot });
+  const session = await createSession({ repoPath, source, env, cwd, gitRoot, ephemeral });
 
   const dim = (s) => (env.NO_COLOR || !output.isTTY ? s : `\x1b[2m${s}\x1b[0m`);
   for (const line of session.bannerLines) output.write(dim(line) + "\n");