@polycode-projects/the-mechanical-code-talker 0.5.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. ----
@@ -191,6 +222,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) {
@@ -269,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. */
@@ -369,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;
 }
 
@@ -877,13 +1132,89 @@ 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;
+}
+
+/** 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, 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,19 +1270,31 @@ 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.
+  // 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) {
@@ -970,6 +1313,34 @@ 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; }
+  }
+  // (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).
@@ -1128,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;
@@ -1142,6 +1520,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);
@@ -1174,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 {
@@ -1186,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 {
@@ -1247,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`
@@ -1320,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",
   ];