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

package/corpus/seon/relations.jsonl

@@ -0,0 +1,8 @@
+{"relation":"imports","definition":"To import is to bring another module's definitions into the current one.","sense":"software"}
+{"relation":"calls","definition":"A call is one function invoking another.","sense":"software"}
+{"relation":"contains","definition":"Containment is a class or module holding a member (a method, attribute, or nested definition).","sense":"software"}
+{"relation":"inherits","definition":"Inheritance is one class deriving its structure and behaviour from another.","sense":"software"}
+{"relation":"tests","definition":"A test is code that exercises another unit and checks its behaviour.","sense":"software"}
+{"relation":"defines","definition":"A definition is where a name (a class, function, or variable) is introduced.","sense":"software"}
+{"relation":"touches","definition":"A touch is a commit changing a file or a symbol in the codebase.","sense":"software"}
+{"relation":"cochange","definition":"Change-coupling is two files that tend to be changed together in the same commits.","sense":"software"}

package/data/templates/responses.jsonl

@@ -62,9 +62,10 @@
 {"id":"conversational-farewell","class":"conversational","register":"friendly","template":"Bye — flushing the session log. Come back with a question any time."}
 {"id":"orientation-friendly","class":"orientation","register":"friendly","template":"I answer questions about THIS codebase's structure — imports, calls, definitions,\nhistory and counts. For example:\n  which modules import walk.mjs\n  what calls buildContextBundle\n  how many classes are there\n/help for commands, /stats for an overview of the graph."}
 {"id":"miss-no-previous-answer","class":"miss","register":"friendly","template":"No previous answer to expand yet — ask me a question first, then say \"why\" or \"say more\"."}
-{"id":"conversational-greeting-empty","class":"conversational","register":"friendly","template":"Hi. There's no code graph loaded here yet — point me at your code with `--repo <path>` or run `tmct init`. Meanwhile I know some general vocabulary — try \"what is a cache\". /help for commands."}
-{"id":"orientation-empty","class":"orientation","register":"friendly","template":"There's no code graph loaded here, so I can't answer structure questions (imports, calls, definitions) yet.\nPoint me at your code with `--repo <path>` or run `tmct init` to index this repo.\nI do know some general vocabulary — try \"what is a cache\". /help for commands, /memory for what I remember."}
+{"id":"conversational-greeting-empty","class":"conversational","register":"friendly","template":"Hi. There's no code graph loaded here — for code structure (imports, calls, definitions) I need a `.tmct/graph.json`: 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."}
+{"id":"orientation-empty","class":"orientation","register":"friendly","template":"There's no code graph loaded here, so I can't answer structure questions (imports, calls, definitions) yet.\nFor 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.\nFor general vocabulary, `tmct init` seeds concepts — try \"what is a cache\". /help for commands, /memory for what I remember."}
 {"id":"technical-density","class":"count","register":"technical","template":"{subject} carries {count} {noun} across {scope} — a concentration well above what a codebase of this size typically sustains ({provenance})."}
 {"id":"technical-comparison","class":"count","register":"technical","template":"At {count} {noun}, {subject} sits {comparison} the comparable-project baseline, a divergence that reflects deliberate structure rather than measurement noise ({provenance})."}
 {"id":"technical-superlative","class":"count","register":"technical","template":"No {noun} in {scope} is more {metric} than {subject}; it leads the next candidate by a clear margin of {count} ({provenance})."}
 {"id":"technical-ratio","class":"count","register":"technical","template":"{subject} sustains a ratio of {count} {noun} per {unit}, placing it in the upper band for projects of comparable {scope} ({provenance})."}
+{"id":"concept-force","class":"concept","register":"friendly","template":"{definition}\n{examples}{followups}"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "private": false,
   "type": "module",
   "description": "The Mechanical Code Talker (tmct) — a tolerant, offline, $0 chat surface that guides you toward precision queries about a software repository. ELIZA/PARRY-style but domain-obsessed with code. No model calls; no codebase index of its own.",
@@ -78,8 +78,11 @@
     "test": "node --test \"test/**/*.test.mjs\"",
     "chat": "node bin/tmct.mjs",
     "chat:repo": "node bin/tmct.mjs chat --repo",
-    "example:mini": "node bin/tmct.mjs chat --repo examples/mini-webapp",
-    "example:polyglot": "node bin/tmct.mjs chat --repo examples/polyglot",
+    "init": "node bin/tmct.mjs init",
+    "memory": "node bin/tmct.mjs memory",
+    "syllogise": "node bin/tmct.mjs syllogise",
+    "example:mini": "node bin/tmct.mjs chat --repo examples/mini-webapp --ephemeral",
+    "example:polyglot": "node bin/tmct.mjs chat --repo examples/polyglot --ephemeral",
     "chatbench:run": "node chatbench/run.mjs",
     "chatbench:judge": "node chatbench/judge.mjs",
     "audit": "npm audit --audit-level=high",

package/src/ask.mjs

@@ -51,7 +51,7 @@ import {
 // grammar, split out of this file: normalization pre-pass, the two parsing
 // strategies, and the bounded-fuzzy service. Re-exported below where existing
 // callers/tests import them from here.
-import { normalizeQuery, applyNegationFrames, matchNegationSet, STOPWORDS, splitWords, wordsOf } from "./interpret/normalize.mjs";
+import { normalizeQuery, applyNegationFrames, applyPhrasingFrames, matchNegationSet, STOPWORDS, splitWords, wordsOf } from "./interpret/normalize.mjs";
 import { editDistance, fuzzyBound } from "./interpret/fuzzy.mjs";
 import { parseAnchored } from "./interpret/strategies/grammar.mjs";
 import { parseKeywordSpot, findPhrase } from "./interpret/strategies/keywords.mjs";
@@ -168,7 +168,7 @@ export function parseQuery(query, { nlp = undefined } = {}) {
   const adapter = nlp === undefined ? defaultNlp() : nlp;
   const raw = String(query || "").trim().replace(/\s+/g, " ");
   if (!raw) return null;
-  const text = applyNegationFrames(normalizeQuery(raw));
+  const text = applyPhrasingFrames(applyNegationFrames(normalizeQuery(raw)));
   if (!text) return null;
   // COMPOSITIONAL PARSE PATH (PLAN §5.16 P3) — the new PRIMARY layer: a recursive
   // descent over CLAUSES for the compositional shapes (nested/relative, boolean,

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";
@@ -304,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
@@ -345,6 +352,9 @@ const T_WHY_EMPTY = "miss-no-previous-answer";
  *  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. */
@@ -486,9 +496,10 @@ function orientationAnswer(templates, graph) {
  *  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.';
+    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 = [];
@@ -798,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,
@@ -852,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
@@ -880,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;
 
@@ -907,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;
 }
@@ -963,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",
@@ -1001,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")
@@ -1167,6 +1192,32 @@ function seonDefinitions() {
   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. */
@@ -1208,6 +1259,132 @@ async function curatedDefinitionAnswer(query, envelope, { memoryDir, lexicon })
   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. */
+/** The VAGUE-TOUCH shapes ("tell me about X", "[and] what about X") — a concept
+ *  touch that is NOT the "what is a X" / "what does X mean" META shape. The meta shape
+ *  has its own established handling (a noun definition, a predicate definition, or the
+ *  honest ambiguity surround for a term that is BOTH a noun and a predicate — e.g.
+ *  "imports"), which the RELATION force must never preempt (frozen case
+ *  am-meta-imports). Gated downstream by CONCEPT_CLASS / RELATION_TERM, so a real
+ *  entity name declines here. */
+function vagueTouchTermOf(query) {
+  const q = String(query).trim();
+  const m = q.match(/^tell me about\s+(?:an?\s+)?(.+?)[?.!\s]*$/i)
+    || 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;
+}
+
+function conceptTermOf(query, envelope) {
+  return metaTermOf(query, envelope) || vagueTouchTermOf(query);
+}
+
+/** The RELATION term a vague touch names — the VAGUE-touch shapes only ("tell me
+ *  about X", "what about X"), NOT the "what is a X"/"what does X mean" meta shape (a
+ *  relation term that is also a vocabulary word, like "imports", keeps its established
+ *  ambiguity/predicate-definition answer — frozen case am-meta-imports). 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 = vagueTouchTermOf(query);
+  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;
@@ -1270,6 +1447,7 @@ 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;
+  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
@@ -1301,6 +1479,7 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
       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
@@ -1323,6 +1502,38 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
     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") {
@@ -1339,7 +1550,7 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
   // 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\`.)`;
+    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
@@ -1351,11 +1562,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 };
 }
 
@@ -1482,6 +1705,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
@@ -1511,6 +1757,13 @@ export async function runTurn(input, { config, source = defaultSource, graph = n
   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.
@@ -1546,15 +1799,20 @@ 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
@@ -1653,7 +1911,15 @@ 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
@@ -1677,6 +1943,11 @@ export async function createSession({
     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.
@@ -1723,6 +1994,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 */ }
@@ -1752,8 +2024,10 @@ export async function createSession({
     // 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"'] : []),
+    // 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",
   ];
@@ -1826,8 +2100,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");