@polycode-projects/the-mechanical-code-talker 3.0.1 → 3.0.3

package/src/services/chat.mjs

@@ -22,6 +22,7 @@ import { dispatchTool, loadGraph, TOOLS } from "../tools/server.mjs";
 import { ToolError } from "../adapters/config.mjs";
 import { parseEntities, edgesOfKind, moduleCountOf, renderAuthorCard, renderAuthorTouches, renderCommitAuthor, resolveSymbol, renderCompare } from "../domain/codegraph.mjs";
 import { classDisplayName, DYNAMIC_TAIL_OK_RE } from "../domain/ask.mjs";
+import { emptyRecord as emptyDiscourseRecord, advanceTurn as advanceDiscourseTurn, register as registerReferent, bind as bindDiscourseForm } from "../domain/discourse.mjs";
 import { uuidv7 } from "../adapters/uuid.mjs";
 import * as defaultSource from "../adapters/source.mjs";
 import { loadTemplates, render as renderTemplate } from "../adapters/corpus/templates.mjs";
@@ -1074,6 +1075,15 @@ const CAPABILITY_PHRASES = [
   /^(?:can you\s+)?walk me through (?:this|the)\s+(?:app|codebase|repo|repository|project|code)\??$/i,
   /^(?:what(?:'s|s|\s+is)|give me|show me|gimme) the big picture(?:\s+(?:here|(?:on|of|for|about)\s+(?:this|the)\s+(?:app|codebase|repo|repository|project|code)))?\??$/i,
   /^(?:give me|what's) the lay of the land\??$/i,
+  // "give me an overview" / "an overview" — the plain-word sibling of "the
+  // big picture" just above, same optional here/of-this-repo tail. Without a
+  // closed entry the word "overview" prose-matches real symbols in an
+  // indexed graph (moduleOverviewText) and the describe rescue dumps that
+  // symbol's card. The detailed forms ("give me a detailed overview of X")
+  // carry a mandatory "detailed"+of-term and stay with the completions
+  // rescue, untouched by this anchor.
+  /^(?:(?:can|could|would) you\s+)?(?:give me|show me|gimme)\s+an overview(?:\s+(?:here|(?:on|of|for|about)\s+(?:this|the)\s+(?:app|codebase|repo|repository|project|code)))?\??$/i,
+  /^an overview(?:\s+please)?\??$/i,
   // "what have we got here"/"what've we got here" — a casual, self-answering
   // opener (matches after a leading "so" strips via LEADING_CONNECTIVE_RE,
   // leaving this as the bare remainder).
@@ -5545,9 +5555,24 @@ async function moduleOrientLane(query, { graph }) {
   // to end in a module path would be claimed here.
   const tailLooksLikePath = !!(m || identityMatch) && phraseWords.length > 1 && MODULE_PATH_RE.test(pathTail);
   // The identity phrasing ("what is <term>") only ever claims a path-shaped
-  // term — bare, or with modifier words ahead of a path-shaped tail; the
-  // orient/purpose phrasings carry their own anchors.
-  if (!m && !MODULE_PATH_RE.test(bare) && !tailLooksLikePath) return null;
+  // term — bare, or with modifier words ahead of a path-shaped tail — or,
+  // below, a bare extensionless module basename.
+  //
+  // "what is codegraph": both siblings of that question already resolve the
+  // module ("what is codegraph.mjs" via MODULE_PATH_RE, "describe codegraph"
+  // via resolveSymbol's basename tier), so the extensionless identity form
+  // resolves by the same evidence — exact basename-stem equality against
+  // exactly ONE module. The gate stays strict: a single bare word with no
+  // article (an articled "what is a dog" keeps its vocabulary reading), and
+  // any tie or non-module term declines unchanged.
+  if (!m && !MODULE_PATH_RE.test(bare) && !tailLooksLikePath) {
+    if (!identityMatch || !/^[\w$][\w$.-]*$/.test(identityMatch)) return null;
+    const stemLc = bare.toLowerCase();
+    const stemHits = graph.individuals.filter((i) => i.class === "Module"
+      && String(i.label).toLowerCase().split("/").pop().replace(/\.[a-z0-9]+$/, "") === stemLc);
+    if (stemHits.length !== 1) return null;
+    return { text: moduleOverviewText(graph, stemHits[0]), via: "meta" };
+  }
   const ent = await resolveEntity(graph, m ? phrase : bare);
   if (ent) {
     const ind = graph.byId?.get?.(ent.id);
@@ -5921,6 +5946,10 @@ async function presuppositionNudge(query, { graph, memoryDir }) {
  *  WALL_MISS_RE: the suppression keys on the PREVIOUS answer matching it, so this
  *  text self-limits — a third consecutive miss re-offers the tailored hint. */
 const WALL_REPEAT_ONELINER = "still couldn't parse that — /help lists every query shape.";
+/** The graph-less bootstrap wall's opening line — shared with the teach-offer
+ *  collapse below, which treats this wall (like the shortened generic wall)
+ *  as text a term-specific offer REPLACES rather than stacks under. */
+const NO_GRAPH_BOOTSTRAP_WALL_LEAD = "I can't answer that as a code question — no code graph is loaded in this session.";
 
 /** The orientation-repeat one-liner. The conversational
  *  orientation branch sits OUTSIDE the composed-only wall-shortening gate (it
@@ -6411,6 +6440,37 @@ function senseSplitFactList(hits, rows, subjectVariants, { indent = "" } = {}) {
   return { lines, grouped };
 }
 
+// A subject-scan term answer longer than this many flat fact lines leads with a
+// deterministic digest paragraph (src/domain/digest) and holds the full list
+// behind the escape; a shorter answer is already readable as a list.
+const DIGEST_READBACK_THRESHOLD = 8;
+
+/** The digest lead for a subject-scan term answer: a bounded narrative first
+ *  (selection, sentence structures, composition — all deterministic, no model),
+ *  the full fact list held behind the "show the facts"/"more" escape. `termRows`
+ *  are the term's own fact rows, `allRows` the whole store the statistics scan
+ *  over, `lines` the already-rendered flat fact list the escape reveals.
+ *
+ *  Returns { text, pending } or null. Null when the structure bank is
+ *  unavailable (the in-browser dock stubs the filesystem loader out) or the
+ *  selector kept nothing renderable, so the caller falls back to the flat list —
+ *  the same graceful degradation the construction banks take in a browser
+ *  bundle. Deterministic; the digest reads only stored facts. */
+async function termDigestReadBack(term, termRows, allRows, lines) {
+  let digestTermFromRows;
+  try { ({ digestTermFromRows } = await import("../adapters/corpus/digest-bank.mjs")); }
+  catch { return null; }
+  let article;
+  try { article = digestTermFromRows(term, termRows, allRows); }
+  catch { return null; }
+  if (!article || !article.paragraphs.length) return null;
+  const sources = [...new Set((article.sources || []).map((s) => s.provenance).filter(Boolean))];
+  const sourceLine = sources.length ? `(sources: ${sources.join("; ")})\n` : "";
+  const escape = `Say 'show the facts' for all ${lines.length} stored facts.`;
+  const text = `${article.paragraphs.join("\n\n")}\n\n${sourceLine}${escape}`;
+  return { text, pending: { items: lines, noun: "facts" } };
+}
+
 /** "a"/"an" for a term, through the SAME grammar-rules.toml "article" rule and
  *  finish.mjs's beginsWithVowelSound every other agreement site in this file
  *  uses — never a hardcoded "a", which is ungrammatical for a vowel-initial
@@ -7274,8 +7334,8 @@ function withDeducedGoal(res, envelope, query) {
 }
 
 async function factAnswerReaders(memoryDir, query, envelope, miss, biasByBundle = {}, cache = null, focusLabel = null) {
-  let normFactTerm;
-  try { ({ normFactTerm } = await import("../adapters/memory/core.mjs")); } catch { return null; }
+  let normFactTerm; let normFactPredicate;
+  try { ({ normFactTerm, normFactPredicate } = await import("../adapters/memory/core.mjs")); } catch { return null; }
   const q = String(query).trim();
 
   // (a-pre) "what is used for riding" / "what can be used for riding" / "what
@@ -7497,7 +7557,29 @@ async function factAnswerReaders(memoryDir, query, envelope, miss, biasByBundle
     // matched against fact subjects, and — the actual bug — the result is
     // FILTERED to just that one predicate (mgx:usedFor) instead of every
     // relation about the subject undifferentiated.
-    const { subject, predicate } = splitMetaPredicate(metaTerm);
+    const split = splitMetaPredicate(metaTerm);
+    const { predicate } = split;
+    // A leading article survives the T5/BARE_WHATIS capture ("what is the car
+    // used for" → "the car") — stripped the same way normFactTerm strips it,
+    // so the article never decides whether the subject matches.
+    let subject = split.subject.replace(/^(?:the|an?)\s+/i, "").trim() || split.subject;
+    // A predicate-shaped ask whose subject is the session anaphor ("what is
+    // it used for") resolves against the standing focus, exactly as the
+    // IS_ADJECTIVE/ISA yes/no readers resolve theirs. With no focus standing
+    // the pronoun is named and declined (the cold-pronoun voice) — never a
+    // fact lookup on the literal word "it", and never a teach-offer for it.
+    let focusSubstituted = false;
+    if (predicate && IS_ADJECTIVE_PRONOUN_RE.test(subject)) {
+      if (!focusLabel) {
+        const tail = String(FACT_PREDICATE_PHRASES[predicate] || "").replace(/^(?:is|are)\s+/, "");
+        return {
+          text: `not sure what "${subject.toLowerCase()}" refers to yet — name the subject directly, e.g. "what is a <name>${tail ? ` ${tail}` : ""}".`,
+          replace: miss, miss: true, selfContainedMiss: true,
+        };
+      }
+      subject = focusLabel;
+      focusSubstituted = true;
+    }
     const variants = factTermVariants(normFactTerm, subject);
     // factRows (trust+sourceIds-bearing), not the plain memoryFacts shape — the
     // bias-weighted ranking below needs each hit's sourceIds to resolve which
@@ -7506,16 +7588,23 @@ async function factAnswerReaders(memoryDir, query, envelope, miss, biasByBundle
     // back where it's hidden or that it's the objective (WORLD_INTERNAL_PREDICATES).
     const subjectHits = (await factRows(memoryDir, cache))
       .filter((f) => variants.has(f.subject) && !WORLD_INTERNAL_PREDICATES.has(f.predicate));
-    let hits = predicate ? subjectHits.filter((f) => f.predicate === predicate) : subjectHits;
+    // Matched through normFactPredicate, so a fact stored under a minted
+    // spelling of the same relation ("mgx:used-for", from the participle
+    // teach frame, in a store written before the spellings converged) is
+    // found by the curated spelling it means.
+    let hits = predicate ? subjectHits.filter((f) => normFactPredicate(f.predicate) === predicate) : subjectHits;
     if (!hits.length) {
-      // The subject itself is known, but not under this specific relation —
-      // an honest, specific "no" rather than falling through to the generic
-      // "isn't a term in this graph's own vocabulary" wall (which would be
-      // actively misleading here: the subject IS a known term).
-      if (predicate && subjectHits.length) {
+      // The subject itself is known — as a fact subject, or as the standing
+      // focus a pronoun just resolved to — but not under this specific
+      // relation: an honest, specific "no" rather than falling through to
+      // the generic "isn't a term in this graph's own vocabulary" wall
+      // (which would be actively misleading here: the subject IS a known
+      // term).
+      if (predicate && (subjectHits.length || focusSubstituted)) {
         return {
           text: `I don't have any "${FACT_PREDICATE_PHRASES[predicate]}" facts about ${subject}.`,
           replace: miss,
+          ...(subjectHits.length ? {} : { miss: true }),
         };
       }
       // The term names nothing as a fact SUBJECT, but may exist only as the
@@ -7538,7 +7627,17 @@ async function factAnswerReaders(memoryDir, query, envelope, miss, biasByBundle
     // "disclosed, never dropped" contract). Unconfigured/tied bias degrades to
     // trust-desc, byte-identical to before this feature existed.
     hits = rankByBiasThenTrust(hits, biasByBundle);
-    const { lines, grouped } = senseSplitFactList(hits, await factRows(memoryDir, cache), variants);
+    const allRows = await factRows(memoryDir, cache);
+    const { lines, grouped } = senseSplitFactList(hits, allRows, variants);
+    // A long undifferentiated "what is X" leads with the digest — a bounded
+    // narrative over the same facts — and holds the full list behind the escape.
+    // It wins over the sense-split grouping here: the digest's own selector
+    // filters the mis-sensed branch that grouping would otherwise surface as its
+    // own block. Falls back to grouping/flat when the digest is unavailable.
+    const digested = (!predicate && lines.length > DIGEST_READBACK_THRESHOLD)
+      ? await termDigestReadBack(subject, hits, allRows, lines)
+      : null;
+    if (digested) return { ...digested, replace: miss };
     if (grouped) return { ...grouped, replace: miss };
     const shown = lines.slice(0, FACT_ANSWER_CAP);
     const rest = lines.slice(FACT_ANSWER_CAP);
@@ -8355,6 +8454,14 @@ const HAS_METHOD_OPEN_RE = /^what\s+methods\s+does\s+([\w'-]+)\s+have[?.!\s]*$/i
  *  cascade/orientation nudge that already handles it. */
 const IS_ADJECTIVE_YESNO_RE = /^(?:is|are|was|were)\s+(.+?)\s+([A-Za-z][\w-]*)[?.!\s]*$/i;
 const IS_ADJECTIVE_PRONOUN_RE = /^(?:it|this|that)$/i;
+/** A backtracked subject that is really a cross-turn temporal comparison —
+ *  a bindable form followed by a comparison word ("that before chat.mjs
+ *  was", from "was that before chat.mjs was touched"). The comparison lane
+ *  owns the closed-participle family; a cousin with a participle outside
+ *  that set still lands here, and offering to teach a fact about "that
+ *  before chat.mjs was" is a category error, so the property readers
+ *  decline it the way they decline a personal-pronoun subject. */
+const BINDABLE_COMPARISON_SUBJECT_RE = /^(?:it|this|that)(?:\s+one)?\s+(?:before|after)\b/i;
 /** IS_ADJECTIVE_YESNO_RE's
  *  subject capture is unbounded/unrestricted (see its own docblock above), so
  *  a pronoun-subject IDENTITY question ("are you happy", "are you like
@@ -8571,6 +8678,7 @@ async function factReadBackReaders(memoryDir, query, envelope, miss, graph = nul
         // "you", so `subject` itself would already carry the pronoun verbatim).
         if (subject && !/^there\b/i.test(subject) && !envelope?.parsed
           && !IS_ADJECTIVE_YESNO_PRONOUN_SUBJECT_RE.test(rawSubject)
+          && !BINDABLE_COMPARISON_SUBJECT_RE.test(rawSubject)
           && !PLACE_ADVERB_OBJECT_RE.test(emptyIsAdj[2].trim())) {
           return unknownAdjectiveOffer(subject, emptyIsAdj[2].trim().toLowerCase());
         }
@@ -9631,7 +9739,7 @@ async function factReadBackReaders(memoryDir, query, envelope, miss, graph = nul
     // this whole reader decline HONESTLY — no fact lookup, no teach-offer —
     // and fall through to whatever handles identity/small-talk questions
     // instead, rather than special-casing a return here.
-    const subject = IS_ADJECTIVE_YESNO_PRONOUN_SUBJECT_RE.test(rawSubject) ? null
+    const subject = IS_ADJECTIVE_YESNO_PRONOUN_SUBJECT_RE.test(rawSubject) || BINDABLE_COMPARISON_SUBJECT_RE.test(rawSubject) ? null
       : IS_ADJECTIVE_PRONOUN_RE.test(rawSubject) ? (focusLabel || null) : rawSubject;
     const adjective = isAdj[2].trim().toLowerCase();
     if (subject) {
@@ -11813,7 +11921,31 @@ const DECISION_RECALL_RE = /^(?:remind\s+me\s+)?what\s+(?:did\s+)?(?:we|i|you)\s
  *  than silently accepted alongside the current location. */
 const MOVE_HISTORY_RE = /^where\s+did\s+(.+?)\s+(?:move|get\s+moved|go)(?:\s+to)?[?.!\s]*$/i;
 
-async function runAsk(query, { config, source, graph, focus, last, templates, memoryDir, sessionId = "", lexicon = null, env, trace, vocabHint = null, tel = null, biasByBundle = {}, cache = null, vocabAntecedent = null, planHolder = null, gameConfig = DEFAULT_GAME_CONFIG, liveReference = false, onLiveLookup = null, uiContext = "cli", synthesisBudget = AUTO_SYNTHESIS_BUDGET }) {
+/** "was that before logger.mjs was touched" — a singular bindable form, a
+ *  comparison word, and an embedded passive clause. The closed participle set
+ *  is the touch family the when-question path answers; anything else keeps
+ *  the honest miss. */
+const TEMPORAL_COMPARISON_RE = /^(?:was|is)\s+(this one|that one|it|this|that)\s+(before|after)\s+(.+?)\s+(?:was|were)\s+(touched|changed|modified|edited|updated)[?.!\s]*$/i;
+
+/** ARCHITECTURE-OVERVIEW intent — "show me the architecture", "what is the
+ *  architecture of this repo": the whole-repo map the /arch command renders.
+ *  A closed phrase set, because the literal word "architecture" is also a
+ *  plausible SYMBOL substring in many graphs (renderArchitecture,
+ *  tmct_architecture) — the symbol-describe rescues would otherwise resolve
+ *  the word to one such symbol and dump its definition card instead of the
+ *  map. Every phrasing here names the architecture as a TOPIC (an article,
+ *  an of-this-repo tail, or an overview/map noun); a query that NAMES a
+ *  symbol ("describe renderArchitecture") never matches. */
+const ARCH_OVERVIEW_LEAD = "(?:(?:can|could|would)\\s+you\\s+(?:please\\s+)?)?(?:(?:show|give)\\s+(?:me|us)\\s+|describe\\s+|explain\\s+|what(?:'s|s|\\s+is)\\s+)?";
+const ARCH_OVERVIEW_TAIL = "(?:\\s+(?:of|for)\\s+(?:this|the)\\s+(?:app|codebase|repo|repository|project|code))?";
+const ARCH_OVERVIEW_PHRASES = [
+  // Article-carried: "the architecture" alone, or wrapped/tailed.
+  new RegExp(`^${ARCH_OVERVIEW_LEAD}the\\s+architecture(?:\\s+(?:overview|map|diagram))?${ARCH_OVERVIEW_TAIL}(?:\\s+here)?\\??$`, "i"),
+  // Article-less: anchored by the of-this-repo tail or the overview/map noun instead.
+  new RegExp(`^${ARCH_OVERVIEW_LEAD}architecture\\s+(?:(?:of|for)\\s+(?:this|the)\\s+(?:app|codebase|repo|repository|project|code)|overview|map|diagram)\\??$`, "i"),
+];
+
+async function runAsk(query, { config, source, graph, focus, last, templates, memoryDir, sessionId = "", lexicon = null, env, trace, vocabHint = null, tel = null, biasByBundle = {}, cache = null, vocabAntecedent = null, planHolder = null, discourseHolder = null, gameConfig = DEFAULT_GAME_CONFIG, liveReference = false, onLiveLookup = null, uiContext = "cli", synthesisBudget = AUTO_SYNTHESIS_BUDGET }) {
   const ts = new Date().toISOString();
   // The surface this turn runs on ("cli" default; "browser" from a web entry) —
   // the honest-miss tail below points a browser/adventure miss at the teach
@@ -11842,6 +11974,61 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
       .replace(/^(?:and|so|then|also)\s+/i, "")
       .replace(/how many\s+/i, "how many of those ");
   }
+  // TEMPORAL COMPARISON ACROSS TURNS — "was that before logger.mjs was
+  // touched": a singular bindable form, a comparison word, and an embedded
+  // passive clause. The form binds against the session's discourse record (a
+  // dated referent a previous answer established), the embedded clause runs
+  // fresh through the same when-question path a standalone turn takes, and
+  // the two ISO dates compare with both sides cited. Checked BEFORE the ask
+  // engine (the same precedence RENAME_HISTORY_RE takes, below) so the
+  // sentence never reaches the keyword-spot strategy's multi-token patient
+  // guard. A form this shape that CANNOT compose still ends here, with a
+  // specific miss naming what's missing (no referent for the form, an
+  // undated referent, no graph, an undatable clause) — falling through used
+  // to hand the sentence to the teach-offer cascade, which read "that before
+  // X was" as a subject to learn facts about.
+  {
+    const cmp = String(query).trim().match(TEMPORAL_COMPARISON_RE);
+    if (cmp) {
+      const [, form, cmpOp, clauseSubject, participle] = cmp;
+      const verb = participle.toLowerCase();
+      const refMiss = (text) => {
+        note(trace, "goal: compare a prior answer's dated referent against a freshly read event (cross-turn temporal composition)");
+        note(trace, `lane: TEMPORAL_COMPARISON_RE — "${form}" could not compose a comparison; a specific miss names why, never the teach-offer cascade`);
+        return plainTurn(query, text, { via: "miss", miss: true, focus });
+      };
+      const bound = discourseHolder ? bindDiscourseForm(discourseHolder.record, form) : null;
+      if (!bound?.referent) {
+        return refMiss(`I don't have a referent for "${form}" yet — nothing answered earlier in this conversation binds it. Ask about the event first (e.g. "when was ${clauseSubject} last ${verb}"), then ask the comparison again.`);
+      }
+      const refDay = String(bound.referent.attrs?.date || "").slice(0, 10);
+      if (!refDay) {
+        return refMiss(`"${form}" refers to ${bound.referent.label}, but I have no date on record for it — so I can't place it before or after ${clauseSubject} was ${verb}.`);
+      }
+      if (!graph) {
+        return refMiss(`"${form}" refers to ${bound.referent.label} (${refDay}), but I need a code graph to date when ${clauseSubject} was last ${verb} — no code graph is loaded.`);
+      }
+      const { ask } = await import("../domain/ask.mjs");
+      const fresh = ask(graph, `when was ${clauseSubject} ${participle}`);
+      const freshHit = (!fresh?.tmct_ask?.miss && !fresh?.tmct_ask?.ambiguous) ? fresh?.tmct_ask?.matches?.[0] : null;
+      const freshCommit = freshHit?.id ? graph.byId?.get?.(freshHit.id) : null;
+      const clauseDay = freshCommit?.class === "Commit"
+        ? String((freshCommit.attributes || []).find((a) => a.key === "date")?.value || "").slice(0, 10)
+        : "";
+      if (!clauseDay) {
+        return refMiss(`"${form}" refers to ${bound.referent.label} (${refDay}), but I couldn't date when ${clauseSubject} was last ${verb} in this index — so I can't compare the two.`);
+      }
+      const holds = cmpOp.toLowerCase() === "before" ? refDay < clauseDay : refDay > clauseDay;
+      const relation = refDay < clauseDay ? "came before" : refDay > clauseDay ? "came after" : "landed on the same day as";
+      const text = `${holds ? "Yes" : "No"} — ${bound.referent.label} (${refDay}) ${relation} ${clauseSubject} was last ${verb} (${freshCommit.label}, ${clauseDay}).`;
+      note(trace, "goal: compare a prior answer's dated referent against a freshly read event (cross-turn temporal composition)");
+      note(trace, `lane: TEMPORAL_COMPARISON_RE — "${form}" bound ${bound.referent.label} (${refDay}) through the discourse record; the embedded clause re-ran as its own when-question`);
+      const turn = plainTurn(query, text, { via: "composed", miss: false, focus });
+      const cited = [graph.byId?.get?.(bound.referent.ids[0]), freshCommit].filter(Boolean);
+      turn.detail = { traversal: `discourse ${bound.referent.ref} (${refDay}) vs last-${verb} of ${clauseSubject} (${clauseDay})`, matches: cited };
+      return turn;
+    }
+  }
   // RENAME HISTORY — "what was X called before" and its siblings. The index
   // records current names only, and without this gate "called" fuzzes onto
   // the calls relation ("before" simply drops), so the reply read as fluent
@@ -12020,6 +12207,17 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
       "isn't resolved to anything yet — name the term directly, or ask a question that resolves one first.",
     );
     if (envJson) { try { envelope = JSON.parse(envJson); } catch { envelope = null; } }
+    // Typed discourse referents the answer established (the ask envelope's
+    // additive `discourse` field, emitted beside the eval where the answer's
+    // content is still typed) register into the session's record here — the
+    // one point both ask paths (direct call and dispatchTool) converge.
+    if (discourseHolder && Array.isArray(envelope?.discourse)) {
+      for (const { lane, ...spec } of envelope.discourse) {
+        discourseHolder.record = registerReferent(discourseHolder.record, {
+          ...spec, from: { turn: discourseHolder.record.turn, lane, query: askQuery },
+        });
+      }
+    }
   } catch (e) {
     const thrown = String(e?.message || e);
     // A graph-less session's ask dispatch fails reading the never-configured
@@ -12042,7 +12240,7 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
     answer = (!graph || noCodeGraph(graph)) && (!config || e?.emptyGraph || /^cannot read graph artifact\b/.test(thrown))
       // A browser session has no `tmct init in a repo` to reach for, so its
       // fallback drops that CLI-only remedy and keeps just the teach pointer.
-      ? `I can't answer that as a code question — no code graph is loaded in this session. ${vocabHint
+      ? `${NO_GRAPH_BOOTSTRAP_WALL_LEAD} ${vocabHint
         || (browser
           ? "I can still remember and answer taught facts (try \"every bug is an issue\")."
           : "I can still remember and answer taught facts (try \"every bug is an issue\"), or run `tmct init` in a repo to index one.")}`
@@ -12198,10 +12396,32 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
       note(trace, `goal: ${deduced} (revised — the raw \"what else\" phrasing was recognized directly, not the relaxed/reparsed envelope)`);
     }
   }
+  // (0a) ARCHITECTURE OVERVIEW — see ARCH_OVERVIEW_PHRASES. Answered here,
+  // before the meta/orientation lanes and long before the symbol-resolve
+  // rescues (4d), so the closed architecture phrasings reach the map instead
+  // of a literal-token symbol card or the vocabulary-touch teach offer.
+  if (!handled && miss && graph && !noCodeGraph(graph)) {
+    // The RAW text is tried alongside the peeled one: applyPreambleFrames'
+    // show/give-me bridge rewrites "show me the architecture" into "describe
+    // architecture", which drops the article this closed set anchors on.
+    const archRaw = correctMisspellings(String(query).trim());
+    const archPeeled = applyPreambleFrames(archRaw);
+    if (ARCH_OVERVIEW_PHRASES.some((re) => re.test(archRaw) || re.test(archPeeled))) {
+      try {
+        const archText = await dispatchTool("tmct_architecture", {}, { config, source, tel });
+        if (archText) {
+          answer = archText; via = "meta"; recordMiss = false; handled = true;
+          deduced = "understand the overall architecture (package/module boundaries)";
+          note(trace, `goal: ${deduced} (revised — a closed architecture-overview phrasing was recognized directly)`);
+          note(trace, "lane: (0a) ARCHITECTURE OVERVIEW — routed to the whole-repo architecture map (/arch), never a literal symbol lookup on the word \"architecture\"");
+        }
+      } catch { /* the tool couldn't load a graph — the ordinary lanes decide */ }
+    }
+  }
   // (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) {
+  if (!handled && miss) {
     const meta = await metaLane(query, { graph, memoryDir, last, templates, vocabHint, focus });
     if (meta) {
       // A lane may answer with a better-worded decline (the module-orient
@@ -12509,6 +12729,7 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
     if (fallback) bareMetaHit = { text: fallback.text, replace: true };
   }
   const coldPronounDecline = focus?.label ? null : coldPronounDeclineText(query);
+  let selfContainedMiss = false;
   if (bareMetaHit?.reference) {
     // The bare-form reference hit mirrors (4h): the cited answer replaces the
     // miss, the turn is no longer recorded as one, and the article's grounded
@@ -12632,6 +12853,10 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
       // (the isa ladder's "I can't confirm that" closers) — the turn record
       // keeps miss=true and via stays untouched, so miss-rate metrics and
       // recall's own miss-gated lanes see it exactly like the wall it replaced.
+      // One flagged `selfContainedMiss` already names its own recovery, so
+      // the empty-graph orientation pointer below stays off it — a pronoun
+      // decline with an index pointer under it is two answers to one turn.
+      if (fact.selfContainedMiss) selfContainedMiss = true;
       if (!fact.miss) {
         via = "fact";
         recordMiss = false;
@@ -12980,6 +13205,7 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
   // WALL KINDNESS: a second consecutive wall collapses to a one-liner whose
   // text does NOT match WALL_MISS_RE — self-limiting, so a third consecutive
   // miss re-offers the tailored hint instead of droning.
+  let genericWallMiss = false;
   if (miss && recordMiss && via === "composed" && WALL_MISS_RE.test(answer)) {
     const repeat = last?.answer && WALL_MISS_RE.test(String(last.answer));
     // A GRAPH-LESS session's wall must not hand a vocabulary question a list
@@ -12990,33 +13216,17 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
         ? `I couldn't read that as a question I can answer. ${vocabHint} Type /help for all query shapes.`
         : shortMissHint(query));
     via = "miss";
+    genericWallMiss = true;
     note(trace, `lane: (5) SHORT TAILORED MISS — every lane above declined; ${repeat ? "REPEAT collapsed to one-liner (wall kindness)" : "the full grammar wall was shortened + tailored to the query's keywords"}`);
   }
-  // #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. The CLI keeps the --repo/example pointer verbatim; a
-  // browser or a live adventure has no such command to reach for, so each gets
-  // a teach-forward pointer (and the adventure also names the world asides that
-  // are guaranteed to hit).
-  const adventureLive = !!planHolder?.state?.adventure;
-  if (recordMiss && (via === "composed" || via === "miss")
-      && noCodeGraph(graph) && !/--repo|tmct init|no code graph/i.test(answer)) {
-    if (adventureLive) {
-      answer = `${answer}\n(I don't know that yet — you can teach me: say "remember: <thing> is a <kind>". Or ask the world: "look", "where is the key", "talk to the butler".)`;
-      note(trace, "intermediate: HONEST-EMPTY POLISH — a live adventure miss points at the teach lane and the world asides, not the --repo remedy");
-    } else if (browser) {
-      answer = `${answer}\n(I don't know that yet — you can teach me: say "remember: <thing> is a <kind>".)`;
-      note(trace, "intermediate: HONEST-EMPTY POLISH — a browser miss points at the teach lane, not the CLI-only --repo remedy");
-    } else {
-      answer = `${answer}\n(this repo has no code graph — index it with \`tmct index\`, point me at a \`.tmct/graph.json\` with \`--repo <path>\`, or run \`npm run example:mini\`.)`;
-      note(trace, "intermediate: HONEST-EMPTY POLISH — the loaded graph has 0 modules, so the dead-end got a tmct index/--repo pointer appended");
-    }
-  }
-  // TEACH-OFFER: a "what is X" miss where X is genuinely unknown EVERYWHERE —
-  // not a real graph entity, not a schema/vocab term, and not already in
-  // memory — gets a short offer appended UNDER the existing miss text, never
-  // replacing it.
+  // TEACH-OFFER (computed first, applied after the polish below): a "what is
+  // X" miss where X is genuinely unknown EVERYWHERE — not a real graph
+  // entity, not a schema/vocab term, and not already in memory. Computed
+  // ahead of the empty-graph polish because the two are alternative
+  // recoveries for the same dead-end: a miss that is about to offer the
+  // teach lane must not ALSO grow an index-this-repo pointer, or one
+  // unparsed turn stacks three separate messages.
+  let teachOffer = null;
   if (recordMiss && (via === "composed" || via === "miss") && memoryDir) {
     // "what do you know about X" is its OWN sibling shape — checked FIRST,
     // without a resolveEntity(graph) gate: it's inherently a MEMORY question,
@@ -13027,7 +13237,12 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
     const offerSrc = expandContractions(String(query).trim());
     const knowAboutTerm = offerSrc.match(KNOW_ABOUT_RE)?.[1]?.trim();
     const offerTerm = knowAboutTerm || metaTermOf(offerSrc, envelope);
-    if (offerTerm) {
+    // A term that LEADS with a bindable anaphor ("it used for", from an
+    // unresolved "what is it used for") is a pronoun that failed to bind,
+    // not a teachable subject — offering to learn facts about it would echo
+    // the garble back as an invitation to store it.
+    const anaphorLedTerm = offerTerm && /^(?:it|this|that|these|those|them)\b/i.test(offerTerm.trim());
+    if (offerTerm && !anaphorLedTerm) {
       let normFactTerm;
       try { ({ normFactTerm } = await import("../adapters/memory/core.mjs")); } catch { normFactTerm = null; }
       if (normFactTerm) {
@@ -13036,14 +13251,46 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
         if (!ent) {
           const variants = factTermVariants(normFactTerm, offerTerm);
           const known = (await memoryFacts(memoryDir)).some((f) => variants.has(f.subject) || variants.has(f.object));
-          if (!known) {
-            answer = `${answer}\n${unknownVocabTermOffer(cleanTerm)}`;
-            note(trace, `intermediate: TEACH-OFFER — "${cleanTerm}" is unknown to both the graph and memory, so the miss got an offer to learn appended`);
-          }
+          if (!known) teachOffer = unknownVocabTermOffer(cleanTerm);
         }
       }
     }
   }
+  // #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 — or unless the
+  // turn already names its own recovery (a self-contained decline, or a
+  // teach-offer about to land). Only when genuinely empty. The CLI keeps the
+  // --repo/example pointer verbatim; a browser or a live adventure has no
+  // such command to reach for, so each gets a teach-forward pointer (and the
+  // adventure also names the world asides that are guaranteed to hit).
+  // A live adventure keeps its polish even beside a teach-offer: the world
+  // asides ("look", "talk to the butler") are guidance the offer can't carry.
+  const adventureLive = !!planHolder?.state?.adventure;
+  if (recordMiss && (via === "composed" || via === "miss") && !selfContainedMiss
+      && (adventureLive || !teachOffer)
+      && noCodeGraph(graph) && !/--repo|tmct init|no code graph/i.test(answer)) {
+    if (adventureLive) {
+      answer = `${answer}\n(I don't know that yet — you can teach me: say "remember: <thing> is a <kind>". Or ask the world: "look", "where is the key", "talk to the butler".)`;
+      note(trace, "intermediate: HONEST-EMPTY POLISH — a live adventure miss points at the teach lane and the world asides, not the --repo remedy");
+    } else if (browser) {
+      answer = `${answer}\n(I don't know that yet — you can teach me: say "remember: <thing> is a <kind>".)`;
+      note(trace, "intermediate: HONEST-EMPTY POLISH — a browser miss points at the teach lane, not the CLI-only --repo remedy");
+    } else {
+      answer = `${answer}\n(this repo has no code graph — index it with \`tmct index\`, point me at a \`.tmct/graph.json\` with \`--repo <path>\`, or run \`npm run example:mini\`.)`;
+      note(trace, "intermediate: HONEST-EMPTY POLISH — the loaded graph has 0 modules, so the dead-end got a tmct index/--repo pointer appended");
+    }
+  }
+  if (teachOffer) {
+    // On a GENERIC wall (the shortened "couldn't read that", or the
+    // graph-less bootstrap wall) the offer IS the whole answer — the wall
+    // names no term, so keeping it above the offer stacks two messages
+    // where one carries everything. A receipt-bearing specific miss keeps
+    // the offer appended beneath it, unchanged.
+    const genericWall = genericWallMiss || answer.startsWith(NO_GRAPH_BOOTSTRAP_WALL_LEAD);
+    answer = genericWall ? teachOffer : `${answer}\n${teachOffer}`;
+    note(trace, `intermediate: TEACH-OFFER — the term is unknown to both the graph and memory, so the miss ${genericWall ? "collapsed to the offer to learn" : "got an offer to learn appended"}`);
+  }
   // COLLISION RESTORE (pairs with relaxedTeachCollision, above): if nothing in
   // the would-miss cascade actually stored/answered anything, fall back to
   // the ORIGINAL ask-engine answer computed before this turn was forced into
@@ -13751,7 +13998,11 @@ async function assertTurn(line, { memoryDir, sessionId, focus, lexicon = null, c
 // 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;
+// "show the facts"/"show the chains" are the digest read-back's own escape
+// (the digest holds the full fact list — chains included, since the flat lines
+// carry their is-a ancestry — on the same pending remainder), folded in here so
+// they page the held list exactly as "more" does.
+const MORE_RE = /^(?:more|show more|see more|the rest|next|continue|go on|show(?: me)? the facts|show the chains)\b[.!?]*$/i;
 
 /** The impact-intent gate — "what would break if I change X" and its natural
  *  neighbours, routed to the same /impact closure. Sibling of normalize.mjs's
@@ -14337,7 +14588,7 @@ function vocabAntecedentFrom(last) {
   return m[1];
 }
 
-export async function runTurn(input, { config, source = defaultSource, graph = null, focus = null, last = null, memoryDir = null, sessionId = "", env = process.env, lexicon = null, narrate = false, liveReference = false, onLiveLookup = null, vocabHint = null, tel = null, biasByBundle = {}, factRowsCache: injectedFactRowsCache = null, planState = null, gameConfig = null, uiContext = "cli", synthesisBudget = AUTO_SYNTHESIS_BUDGET, researchState = null, researchConfig = null, _noSplit = false } = {}) {
+export async function runTurn(input, { config, source = defaultSource, graph = null, focus = null, last = null, memoryDir = null, sessionId = "", env = process.env, lexicon = null, narrate = false, liveReference = false, onLiveLookup = null, vocabHint = null, tel = null, biasByBundle = {}, factRowsCache: injectedFactRowsCache = null, planState = null, gameConfig = null, uiContext = "cli", synthesisBudget = AUTO_SYNTHESIS_BUDGET, researchState = null, researchConfig = null, discourse = null, _noSplit = false } = {}) {
   // Every game's tuning knobs (spider-fly's mass economy, guess-the-number's
   // bounds, the shared plan lane's search-depth cap) — a caller's own
   // gameConfig (chat-session.mjs resolves one per session from tmct.toml)
@@ -14402,7 +14653,12 @@ export async function runTurn(input, { config, source = defaultSource, graph = n
   // the PLAN NEXT block below write planHolder.state; every other path leaves
   // it untouched, and the caller re-threads whatever comes back.
   const planHolder = { state: planState };
-  const ctx = { config, source, graph, focus, last, memoryDir, sessionId, templates, env, lexicon, trace, narrate, liveReference, onLiveLookup, vocabHint: resolvedVocabHint, tel, biasByBundle, cache: factRowsCache, vocabAntecedent, planHolder, gameConfig: resolvedGameConfig, uiContext, synthesisBudget };
+  // The session's typed discourse record rides the same holder pattern,
+  // threaded turn-to-turn beside focus and last. Registration happens where
+  // an answer's typed content is in hand (runAsk, off the ask envelope's
+  // `discourse` referents); the caller re-threads whatever comes back.
+  const discourseHolder = { record: discourse ?? emptyDiscourseRecord() };
+  const ctx = { config, source, graph, focus, last, memoryDir, sessionId, templates, env, lexicon, trace, narrate, liveReference, onLiveLookup, vocabHint: resolvedVocabHint, tel, biasByBundle, cache: factRowsCache, vocabAntecedent, planHolder, discourseHolder, gameConfig: resolvedGameConfig, uiContext, synthesisBudget };
   // A DISPATCHED turn (count / slash-command / ask) becomes the new "last
   // answer" that why/say-more re-renders; a conversational turn does not.
   // Every dispatched turn's result passes through finish() here — the LAST
@@ -14446,10 +14702,16 @@ export async function runTurn(input, { config, source = defaultSource, graph = n
       detail: finished.detail ?? null,
       grounded: finished.record?.miss ? (last?.grounded ?? null) : finished.answer,
     };
+    // Every dispatched turn advances the discourse record's turn counter —
+    // the counter is the registration ordinal that makes a same-turn tie
+    // detectable, so it moves once, here, on the one path every dispatched
+    // turn shares. Conversational turns bypass withLast and leave the record
+    // untouched, exactly as they leave `last`.
+    discourseHolder.record = advanceDiscourseTurn(discourseHolder.record);
     // Goal/canonical lines append onto the PRE-narration `finished` result
     // `nextLast` was captured from, so a narrated turn still gets both short
     // lines up top plus the full trace block after.
-    return { ...withNarration(withCanonicalLine(withGoalLine(finished)), trace, fallbackGoal), last: nextLast };
+    return { ...withNarration(withCanonicalLine(withGoalLine(finished)), trace, fallbackGoal), last: nextLast, discourse: discourseHolder.record };
   };
 
   // Slash-optional system commands: a bare leading command word ("stats",
@@ -14692,17 +14954,18 @@ export async function runTurn(input, { config, source = defaultSource, graph = n
         && await everySentenceTeaches(sentences.slice(0, -1), lexicon);
       const finalIsPayload = endsInPlanTrigger || teachesThenAsks;
       if (finalIsPayload || await everySentenceTeaches(sentences, lexicon)) {
-        let f = focus; let l = last; let ps = planHolder.state;
+        let f = focus; let l = last; let ps = planHolder.state; let d = discourseHolder.record;
         const receipts = [];
         let finalRec = null;
         for (const sentence of sentences) {
           const r = await runTurn(sentence, {
             config, source, graph, focus: f, last: l, memoryDir, sessionId, env, lexicon,
-            narrate: false, vocabHint, tel, biasByBundle, planState: ps, _noSplit: true,
+            narrate: false, vocabHint, tel, biasByBundle, planState: ps, discourse: d, _noSplit: true,
           });
           f = r.focus ?? f;
           l = r.last ?? l;
           if ("planState" in r) ps = r.planState;
+          if ("discourse" in r) d = r.discourse;
           finalRec = r;
           receipts.push(String(r.answer ?? "").split("\n")[0]);
         }
@@ -14725,6 +14988,7 @@ export async function runTurn(input, { config, source = defaultSource, graph = n
         combined.planState = ps;
         combined.focus = f;
         combined.last = l;
+        combined.discourse = d;
         // Each per-sentence turn recorded only its OWN sentence; the transcript
         // echo and the turn record must quote the whole multi-sentence line the
         // user actually typed, not just its last sentence.