@polycode-projects/the-mechanical-code-talker 2.3.1 → 2.5.2

package/src/domain/ask.mjs

@@ -13,10 +13,10 @@
 // and any tie surfaces as ambiguity.
 //
 // ask.mjs's own `touches`/`cochange` verbs answer one-hop structural edges
-// (mgx:touchedByCommit / mgx:changeCoupledWith) — a different, simpler
-// question than temporal.mjs's time-scrubbing Chronograph surface.
+// (mgx:touchedByCommit / mgx:changeCoupledWith).
 
 import { relationKind, impactClosure, moduleCountOf, normPath, HISTORY_CAP } from "./codegraph.mjs";
+import { isTestPath } from "./module-paths.mjs";
 import {
   RELATIONS,
   VERB_TO_KIND, ENTITY_TO_TYPE, MODIFIER_TO_KIND,
@@ -112,6 +112,16 @@ function verbFor(kind) {
   return REVERSE_MISS_VERB[kind] || kind;
 }
 
+// The base (plural-subject) verb form a universal-over-a-set answer reads with:
+// "all modules IMPORT X" / "…do not IMPORT X", not the stored 3rd-person
+// "imports". Keyed on the stored relation kind, curated alongside the vocabulary.
+const PLURAL_SUBJECT_VERB = {
+  imports: "import", calls: "call", callsSymbol: "call", inherits: "inherit from",
+  contains: "contain", tests: "test", touches: "touch", cochange: "cochange",
+  reexports: "export", uses: "use",
+};
+const pluralVerbFor = (kind) => PLURAL_SUBJECT_VERB[kind] || verbFor(kind);
+
 // Strips a leading relation verb from the tests-kind honest-empty object
 // ("do any tests touch f.mjs" -> object "touch f.mjs"), so the miss template
 // doesn't render "No tests cover touch f.mjs." Longest phrase first.
@@ -212,6 +222,7 @@ function parseComposite(text, nlp) {
   const lc = w.map((x) => x.toLowerCase());
   return parseExistence(w, lc)
     || parseQualifierCheck(w, lc)
+    || parseUniversal(w, lc, nlp)
     || parseNegation(text, nlp, 0)
     || parseNegatedAsk(w, lc)
     || parseForwardNegation(w, lc, nlp)
@@ -242,6 +253,42 @@ function complementAst(entityType, diffAtom) {
   };
 }
 
+// Universal over a set: "do all <kind> <verb> X" / "does every module import X"
+// holds iff the bounded complement (the <kind> that do NOT <verb> X) is empty;
+// a non-empty complement is a grounded "no" that names the counterexamples.
+// Reuses the very allOfClass-minus-positive complement parseNegation builds for
+// "which <kind> do not <verb> X", so the two shapes can never disagree on the
+// set they compute. The object is grounded at eval — an unknown one still misses
+// honestly rather than reading every member as a counterexample.
+const UNIVERSAL_DET = new Set(["all", "every", "each"]);
+function parseUniversal(w, lc, nlp) {
+  if (!["do", "does", "did"].includes(lc[0])) return null;   // needs the polar auxiliary
+  if (!UNIVERSAL_DET.has(lc[1])) return null;                // needs a universal determiner
+  const noun = entityNoun(lc[2]);
+  if (!noun || noun.placeholder || !noun.entityType) return null;  // needs a concrete kind noun
+  const entityType = noun.entityType;
+  if (entityType === "Change") {
+    return { node: "miss", reason: `"${lc[2]}" isn't an enumerable kind — a universal check needs a concrete kind (functions, classes, modules, …)` };
+  }
+  const entWord = lc[2];
+  const predWords = w.slice(3);
+  const predLc = lc.slice(3);
+  if (!predWords.length) return null;
+  const vh = findPhrase(predLc, VERB_TO_KIND);
+  if (!vh) return { node: "miss", reason: "a universal check needs a known relation verb (import, call, inherit from, test, …)" };
+  const objWords = predWords.filter((_, i) => (i < vh.start || i >= vh.end) && !STOPWORDS.has(predLc[i]) && predLc[i] !== "from");
+  const object = objWords.join(" ").trim();
+  if (!object) return null;                                  // "do all modules import" — no object to ground against
+  const positive = parseSetPhrase(`which ${entWord} ${predWords.join(" ")}`, nlp, 1);
+  if (!positive || positive.node === "miss") {
+    return { node: "miss", reason: (positive && positive.reason) || "the universal clause didn't parse" };
+  }
+  return {
+    node: "universal", entityType, kind: vh.kind, object,
+    complement: complementAst(entityType, { op: "difference", kind: "set", ast: positive }),
+  };
+}
+
 function parseNegation(text, nlp, depth = 0) {
   const neg = matchNegationSet(text);
   if (!neg) return null;                             // no set-negation marker → not this shape
@@ -1190,10 +1237,16 @@ function qualSets(graph) {
     const ind = graph.byId.get(e.object);
     if (ind) exported.add(String(ind.label).toLowerCase());
   }
-  const testedModules = new Set(edgesOfKind(graph, "tests").map((e) => e.object));
+  const testedModules = new Set();
+  // The TEST modules themselves — the subjects of the same edges. A coverage
+  // qualifier is a claim about SOURCE modules, so these are neither tested nor
+  // untested and are excluded from both (see qualHolds). renderUntested and
+  // untestedModules have always excluded them; this route did not.
+  const testModules = new Set();
+  for (const e of edgesOfKind(graph, "tests")) { testedModules.add(e.object); testModules.add(e.subject); }
   const moduleOfSymbol = new Map();
   for (const e of edgesOfKind(graph, "defines")) moduleOfSymbol.set(e.object, e.subject);
-  c = { exported, testedModules, moduleOfSymbol };
+  c = { exported, testedModules, testModules, moduleOfSymbol };
   qualCache.set(graph, c);
   return c;
 }
@@ -1213,7 +1266,12 @@ function moduleIdOf(graph, ind) {
  *  classes, so "what is a Record" answers even though Record isn't a graph
  *  vocabulary term. Uniqueness is global across all these classes together —
  *  a name colliding across two classes stays an honest miss. Returns null on
- *  anything less than a unique exact hit. */
+ *  anything less than a unique exact hit.
+ *
+ *  Module is absent by design, not by omission: chat.mjs's module-overview
+ *  lane already orients a module in far more detail (defines/imports/coverage
+ *  counts) and gates itself on this lookup missing, so claiming modules here
+ *  would replace that answer with a thinner one. */
 const META_FALLBACK_CLASSES = new Set(["Class", "Function", "Method", "GlobalVariable", "Attribute"]);
 export function metaFallbackEntityAnswer(graph, term) {
   const termLc = String(term || "").trim().toLowerCase();
@@ -1300,7 +1358,19 @@ function qualHolds(graph, ind, spec) {
     }
     case "tested": {
       const mid = moduleIdOf(graph, ind);
-      return (!!mid && qualSets(graph).testedModules.has(mid)) === spec.value;
+      const sets = qualSets(graph);
+      // A TEST module is neither tested nor untested. Coverage is a claim about
+      // SOURCE modules, so asking whether a test covers itself is a category
+      // error that made "show me the untested modules" list the test modules as
+      // their own gaps. Excluded on BOTH polarities, by the same two tests the
+      // tool applies: the edge subject (a module that tests something) and the
+      // path shape (a test-named module that happens to test nothing).
+      const mind = mid ? graph.byId?.get?.(mid) : null;
+      if (mid && (sets.testModules.has(mid) || (mind && isTestPath(String(mind.label).toLowerCase())))) return false;
+      // An entity whose defining module can't be resolved (a class with no
+      // defines edge) is not a test module — it reads as "not tested", so it
+      // stays in the untested set instead of dropping out of both polarities.
+      return (!!mid && sets.testedModules.has(mid)) === spec.value;
     }
     default: return false;
   }
@@ -1534,13 +1604,32 @@ function evalSet(graph, ast, opts) {
 /** Fold a boolean AST left-to-right into a result set. A qualifier atom acts as a
  *  set filter on the accumulator (intersection keeps satisfiers, difference removes
  *  them); a set atom contributes its own id-set for the op. */
+/** The opposite of a qualifier, for a complement — or null where it has none.
+ *
+ *  A qualifier carrying a BOOLEAN value is three-valued in practice: tested,
+ *  untested, or not a subject of the question at all. A test module is neither
+ *  tested nor untested, so "modules that are not tested" is NOT the set
+ *  complement of "tested modules" — complementing would hand back every
+ *  individual the question does not apply to. Asking the OPPOSITE qualifier
+ *  drops those from both sides, and makes this route agree with the
+ *  QUALIFIERS-keyed one ("untested modules") that already reads it that way.
+ *
+ *  Qualifiers with no boolean polarity (visibility, exported, attr) have no
+ *  opposite to ask and keep the plain complement, which is the right reading
+ *  for them: "not exported" really is everything that is not exported. */
+const oppositeQualifierSpec = (spec) => (spec && typeof spec.value === "boolean" ? { ...spec, value: !spec.value } : null);
+
 function evalBoolean(graph, ast, opts) {
   let acc = [];
   for (const atom of ast.atoms) {
     if (atom.op === "seed") { acc = evalSet(graph, atom.ast, opts); continue; }
     if (atom.kind === "qual") {
       const holds = (ind) => atom.filters.every((f) => qualHolds(graph, ind, QUALIFIERS[f]));
-      acc = atom.op === "difference" ? acc.filter((i) => !holds(i)) : acc.filter((i) => holds(i));
+      const complementHolds = (ind) => atom.filters.every((f) => {
+        const opposite = oppositeQualifierSpec(QUALIFIERS[f]);
+        return opposite ? qualHolds(graph, ind, opposite) : !qualHolds(graph, ind, QUALIFIERS[f]);
+      });
+      acc = atom.op === "difference" ? acc.filter(complementHolds) : acc.filter(holds);
       continue;
     }
     const oids = new Set(evalSet(graph, atom.ast, opts).map((i) => i.id));
@@ -1784,12 +1873,32 @@ function evalQualCheck(graph, ast, opts) {
   return { compositeKind: "qualCheck", subject: r.match, qualifier, negated, holds, matches: [r.match] };
 }
 
+/** Universal-over-a-set: the object is grounded first (an unknown one is an
+ *  honest miss, never a blanket "no"), then the answer is read off the bounded
+ *  complement — empty means every member satisfies it, non-empty is the "no"
+ *  whose members are the counterexamples. */
+function evalUniversal(graph, ast, opts) {
+  const r = resolveObject(graph, ast.object);
+  if (!r || !r.match) {
+    return { compositeKind: "universal", universalMiss: "unresolved", object: ast.object, matches: [] };
+  }
+  const all = evalSet(graph, { node: "allOfClass", entityType: ast.entityType }, opts);
+  const counter = evalBoolean(graph, ast.complement, opts);
+  const holds = counter.length === 0;
+  return {
+    compositeKind: "universal", entityType: ast.entityType, kind: ast.kind,
+    object: r.match.label, holds, total: all.length, counter,
+    matches: holds ? all : counter,
+  };
+}
+
 /** Compile any compositional AST to a result object traverse() returns for the
  *  simple path — {matches, …} plus compositeKind/compositeMiss flags render() reads. */
 function evalComposite(graph, ast, opts = {}) {
   if (ast.node === "miss") return { compositeMiss: true, reason: ast.reason || null, matches: [] };
   if (ast.node === "exists") return evalExists(graph, ast);
   if (ast.node === "qualCheck") return evalQualCheck(graph, ast, opts);
+  if (ast.node === "universal") return evalUniversal(graph, ast, opts);
   if (ast.node === "count") return { compositeKind: "count", count: evalSet(graph, ast.base, opts).length, entityType: ast.entityType, matches: [] };
   if (ast.node === "list") return { compositeKind: "list", matches: evalSet(graph, ast.base, opts), entityType: ast.entityType, scoped: ast.scoped };
   if (ast.node === "superlative") return evalSuperlative(graph, ast);
@@ -1890,6 +1999,21 @@ function renderComposite(parsed, result, graph) {
       miss: false, ambiguous: false, matches: result.matches,
     };
   }
+  if (result.compositeKind === "universal") {
+    if (result.universalMiss === "unresolved") {
+      return { content: `couldn't find "${result.object}" in the index to check.`, miss: true, ambiguous: false, matches: [] };
+    }
+    const kindPlural = nounFor(result.entityType, result.total);
+    const verb = pluralVerbFor(result.kind);
+    if (result.holds) {
+      return { content: `Yes — all ${result.total} ${kindPlural} ${verb} ${result.object}.`, miss: false, ambiguous: false, matches: result.matches };
+    }
+    const n = result.counter.length;
+    return {
+      content: `No — ${n} of ${result.total} ${kindPlural} do not ${verb} ${result.object}: ${compositeList(result.counter)}.`,
+      miss: false, ambiguous: false, matches: result.counter,
+    };
+  }
   if (result.compositeKind === "count") {
     const noun = result.entityType ? nounFor(result.entityType, result.count) : (result.count === 1 ? "result" : "results");
     return { content: `${result.count} ${noun}.`, miss: false, ambiguous: false, matches: [] };
@@ -2379,11 +2503,57 @@ const LEADING_ARTICLE_RE = /^(?:the|a|an)\s+/i;
  *  the module against a same-stem Class/Method. Reuses ENTITY_TO_TYPE. */
 const TRAILING_GRAIN_WORD_RE = new RegExp(`\\s+(${Object.keys(ENTITY_TO_TYPE).join("|")})$`, "i");
 
+/** Words of `term` that neither the resolved label nor the closed grammar
+ *  vocabulary can account for. A word is placed when the label's own letters
+ *  carry it (so "payment system" is placed by PaymentSystem, and a component
+ *  match is placed by construction), when a derivational bridge reaches one of
+ *  the label's components ("logging" for "logger"), or when it is a word the
+ *  grammar or the curated noise list already gives a job to (a leaked relation
+ *  verb in "cover app/lib/b.mjs" is the parser's residue, not the user's).
+ *  Everything else is a word this index has no reading for at all. */
+function unplacedTermWords(term, label) {
+  const labelJoined = joinedForm(label);
+  const labelComps = [...componentSet(label)];
+  const out = [];
+  for (const w of componentSet(term)) {
+    if (labelJoined.includes(w)) continue;
+    if (labelComps.some((c) => derivationalStem(c) === derivationalStem(w))) continue;
+    if (CONTENT_VOCAB.has(w) || NOISE_OR_SCAFFOLD.has(w)) continue;
+    out.push(w);
+  }
+  return out;
+}
+
+/** Tier 3 scores candidates by how much of the term overlaps each label, so a
+ *  term can narrow to exactly one candidate on a SUBSET of its own words and
+ *  the leftovers go unread: "the deprecated legacy model.mjs" outscores every
+ *  other module on "model"/"mjs" alone and answers about model.mjs, a
+ *  different thing from what was asked for. A same-tier tie is already an
+ *  honest ambiguity; a term carrying words the index has no reading for is the
+ *  same failure with one candidate instead of five, so it declines the same
+ *  way, naming the words it could not place and the near-match it would
+ *  otherwise have silently answered about.
+ *
+ *  Tier 3 only: the prose and fuzzy tiers resolve BY not matching the label
+ *  (doc-comment words, a typo'd spelling), and announce themselves in the
+ *  answer where tier 3 says nothing. */
+function declineOnUnplacedWords(result, term) {
+  if (!result?.match || result.ambiguous || result.tier !== 3 || result.matchedVia) return result;
+  const unplaced = unplacedTermWords(term, result.match.label);
+  if (!unplaced.length) return result;
+  return {
+    match: null, candidates: [], tier: null, ambiguous: false,
+    unplacedWords: unplaced, nearestLabel: result.match.label,
+  };
+}
+
 /** resolveObject: a grain-aware disambiguation pre-pass wrapping
  *  resolveObjectCore, only when the caller hasn't pinned an expectedClass.
  *  Tries a trailing grain word (narrows the pool, retries the head noun),
  *  then a plain leading-article strip. Either retry is used only on an
- *  unambiguous hit; any miss/tie falls through unchanged to the original term. */
+ *  unambiguous hit; any miss/tie falls through unchanged to the original term.
+ *  Whatever tier answers, a term with unreadable words left over declines
+ *  instead of resolving past them. */
 export function resolveObject(graph, term, opts = {}) {
   const { expectedClass = null } = opts;
   if (!expectedClass) {
@@ -2394,14 +2564,15 @@ export function resolveObject(graph, term, opts = {}) {
       const head = stripped.slice(0, grainMatch.index).trim();
       const grainClass = ENTITY_TO_TYPE[grainMatch[1].toLowerCase()];
       if (head && grainClass) {
-        const rGrain = resolveObjectCore(graph, head, { expectedClass: grainClass });
+        const rGrain = declineOnUnplacedWords(resolveObjectCore(graph, head, { expectedClass: grainClass }), head);
         if (rGrain?.match?.id && !rGrain.ambiguous) return rGrain;
       }
     }
     if (stripped && stripped !== raw) {
-      const rStripped = resolveObjectCore(graph, stripped, opts);
+      const rStripped = declineOnUnplacedWords(resolveObjectCore(graph, stripped, opts), stripped);
       if (rStripped?.match?.id && !rStripped.ambiguous) return rStripped;
     }
+    return declineOnUnplacedWords(resolveObjectCore(graph, term, opts), term);
   }
   return resolveObjectCore(graph, term, opts);
 }
@@ -2666,8 +2837,13 @@ export function traverse(graph, parsed, { contextId = null, prev = null, pinnedO
       if (collision) objRes = { ...objRes, ambiguous: true, candidates: [collision, ...(objRes.candidates || [])] };
     }
   }
-  const { match: objMatch, candidates, ambiguous, unresolvedPronoun, matchedVia } = objRes;
-  if (!objMatch) return { matches: [], objMatch: null, candidates, traversal: null, ambiguous: false, unresolvedPronoun };
+  const { match: objMatch, candidates, ambiguous, unresolvedPronoun, matchedVia, unplacedWords, nearestLabel } = objRes;
+  if (!objMatch) {
+    return {
+      matches: [], objMatch: null, candidates, traversal: null, ambiguous: false, unresolvedPronoun,
+      unplacedWords, nearestLabel,
+    };
+  }
   // BREADTH-FIRST ENTITY-TIE RESOLUTION: mirrors the
   // parsed.ambiguousParse branch above — every tied candidate is independently
   // traversed and rendered for real (via the pinnedObjMatch short-circuit just
@@ -3217,6 +3393,19 @@ function renderCore(parsed, result, graph) {
     const fallback = parsed.entityType && PLURAL_FORMS[parsed.entityType] ? nounFor(parsed.entityType, 1) : "module";
     const what = /^(?:commit[:\s])?[0-9a-f]{7,40}$/i.test(objText) ? "commit"
       : (!objText.includes("/") && /^[\w$]+(\.[\w$]+)+$/.test(objText) ? "symbol" : fallback);
+    // Words the term carried that nothing in the index reads (resolveObject's
+    // unplaced-word decline) are named here with the near match they would
+    // otherwise have been quietly dropped in favour of: the reader gets to
+    // decide whether the near match was the question.
+    if (result.unplacedWords?.length) {
+      const quoted = listJoin(result.unplacedWords.map((w) => `"${w}"`));
+      const was = result.unplacedWords.length === 1 ? "names" : "name";
+      const near = result.nearestLabel ? ` Did you mean ${result.nearestLabel}?` : "";
+      return {
+        content: `no ${what} matching "${parsed.object}" found in the index. ${quoted} ${was} nothing here, and reading past ${result.unplacedWords.length === 1 ? "it" : "them"} would answer a different question.${near}`,
+        miss: true, ambiguous: false, candidates: [],
+      };
+    }
     return {
       content: `no ${what} matching "${parsed.object}" found in the index. ${touchesRephraseHint(graph)}`,
       miss: true, ambiguous: false, candidates: [],
@@ -3448,8 +3637,13 @@ const CASCADE_FUZZY_TARGETS = [...new Set([
 ])].filter((wd) => /^[a-z]+$/.test(wd) && wd.length >= 4 && !STOPWORDS.has(wd));
 
 /** Unique within-bound fuzzy correction of `w` toward CASCADE_FUZZY_TARGETS,
- *  or null — a distance tie between two distinct targets is refused. */
+ *  or null — a distance tie between two distinct targets is refused. The
+ *  4-char floor holds on the word being corrected as well as on the targets:
+ *  a 1-edit budget on three letters reaches real vocabulary from words that
+ *  were never a typo of it ("old" -> "hold"), and the correction is announced
+ *  as though the asker had typed it. */
 function fuzzyCascadeWord(w) {
+  if (w.length < 4) return null;
   const bound = fuzzyBound(w);
   let best = bound + 1; let hit = null; let tied = false;
   for (const target of CASCADE_FUZZY_TARGETS) {
@@ -3589,6 +3783,23 @@ function relaxParse(graph, query, { nlp = undefined, contextId = null, prev = nu
   }
 
   // Layer 2 — DROP-UNMATCHED (plain-lowercase unknowns beside the real terms)
+  //
+  // Words INSIDE the term survive this layer's DROP (its fuzzy-correct still
+  // repairs them — a typo is a word the asker meant, and the receipt shows the
+  // spelling it was read as). "what imports the deprecated legacy model.mjs"
+  // names a thing the asker believes exists; drop "deprecated" and "legacy"
+  // and the survivors answer about model.mjs, a different thing, under a
+  // receipt that reads as though the question was merely tidied. Layer 1's
+  // curated noise list earns that receipt because every word it removes is
+  // packaging. This layer drops whatever it doesn't recognize, so inside the
+  // term it holds off and lets the original miss stand, unknown words and all.
+  const termParse = parseQuery(tokens.join(" "), { nlp });
+  const termWords = new Set();
+  if (termParse && !termParse.node && TERM_SHAPES.has(termParse.shape)) {
+    for (const part of [termParse.object, termParse.subject]) {
+      for (const w of splitWords(String(part || "").toLowerCase())) termWords.add(w);
+    }
+  }
   const survivors = [];
   const nowDropped = [];
   const corrected = [];
@@ -3604,6 +3815,7 @@ function relaxParse(graph, query, { nlp = undefined, contextId = null, prev = nu
     // restored rather than discarded.
     const fix = fuzzyCascadeWord(lc);
     if (fix && fix !== lc) { survivors.push(fix); corrected.push(`${t}→${fix}`); continue; }
+    if (termWords.has(lc)) { survivors.push(t); continue; }
     nowDropped.push(t);
   }
   if ((corrected.length || nowDropped.length) && survivors.length) {

package/src/domain/cli-verbs.mjs

@@ -0,0 +1,201 @@
+// The CLI's verb list — the one place a tmct subcommand is written down. Both
+// surfaces that name the verbs read this: `tmct --help` renders the Usage block
+// from it (renderUsage), and an unknown invocation restates it
+// (unknownInvocationMessage). Two hand-kept copies of one list is how the two
+// drifted before.
+//
+// `mode` is the argv[2] the bin/tmct.mjs dispatcher switches on, and null for
+// an entry that is not a mode of its own (a bare invocation, --help).
+// `errorLabel` is how the unknown-invocation line names the verb; an entry
+// without one is not something to suggest.
+//
+// Layout: two columns. The verb or flag starts at column 2 (a continuation
+// flag at column 7), and its prose at column 31, or two spaces further right
+// when the left column runs past that.
+const PROSE_COLUMN = 31;
+
+export const CLI_VERBS = [
+  {
+    mode: null,
+    usage: "tmct",
+    prose: ["interactive chat (the headline surface)"],
+  },
+  {
+    mode: "chat",
+    errorLabel: "chat",
+    usage: "tmct chat [--repo <abs>]",
+    prose: ["chat over a specific repo's graph"],
+    flags: [
+      { flag: "[--graph <path>]", prose: ["explicit graph file (repeatable — multiple graphs merge;", "see src/adapters/graph-merge.mjs); wins over --repo/TMCT_GRAPH_FILE/tmct.toml"] },
+      { flag: "[--config <path>]", prose: ["an alternate tmct.toml location (a file or a directory)"] },
+      { flag: "[--ephemeral]", prose: ["read the graph but write nothing back (demo/read-only)"] },
+      { flag: "[--prompt \"<text>\"]", prose: ["one-shot: run the prompt's sentences as turns and print", "the final answer (teach state first, trigger last)"] },
+      { flag: "[--render blocks]", prose: ["with --prompt: when the final turn produced a plan,", "write it as a self-contained animated page"] },
+      { flag: "[--output <path>]", prose: ["the rendered page's path (default plan.html)"] },
+      { flag: "[--narrate]", prose: ["start with narrate mode on — a verbose, developer-facing", "trace of decision points/matched pattern/results/goal per", "turn, appended under a \"--- narrate ---\" marker (also", "TMCT_NARRATE=1; toggle mid-session with /narrate on|off)"] },
+      { flag: "[--plain]", prose: ["force the plain readline shell (the default when", "stdin/stdout is not a terminal)"] },
+      { flag: "[--memory-backend <default|memory|sqlite>]", prose: ["storage backend for taught facts this", "session (CLI flag > TMCT_MEMORY_BACKEND env > tmct.toml's", "[memory] backend > \"default\", the flat .tmct/ JSON file)"] },
+    ],
+  },
+  {
+    mode: "memory",
+    errorLabel: "memory",
+    usage: "tmct memory [--repo <abs>]",
+    prose: ["what tmct remembers: facts, utterances, sessions,"],
+    flags: [
+      { flag: "[--config <path>]", prose: ["folded blocks (the /memory chat command, from the shell)"] },
+      { flag: "[--verbose]", prose: [] },
+    ],
+  },
+  {
+    mode: "init",
+    errorLabel: "init",
+    usage: "tmct init [--repo <abs>]",
+    prose: ["initialize a repo for tmct (default: cwd): .tmct/,"],
+    flags: [
+      { flag: "[--force]", prose: ["tmct.toml, .tmct/TOOLS.md (the cold-tool catalog),", "tier-1 corpus seed, provenance record"] },
+      { flag: "[--corpus <id|path>]", prose: ["also seed a corpus — a tier-2 manifest id (aws|python|java|", "general) or a jsonl file path — opt-in, offline, $0"] },
+      { flag: "[--ontology <name|path>]", prose: ["activate+seed an ontology bundle (a recognized name or a path)"] },
+      { flag: "[--lexicon <name|path>]", prose: ["activate a lexicon bundle (recognized name or a path;", "merged read-time, never seeded — see mergedLexiconExtra)"] },
+      { flag: "[--graph <path>]", prose: ["set graph_file/graph_files in tmct.toml (repeatable)"] },
+      { flag: "[--config <path>]", prose: ["write to an alternate tmct.toml location"] },
+      { flag: "[--detect]", prose: ["suggest a tier-2 corpus from the repo's manifests", "(pyproject.toml → python, pom.xml → java); never seeds unasked"] },
+      { flag: "[--with-persona <name>]", prose: ["write an explicit [extensions]/[bias] preset into tmct.toml", "(\"code\" — today's implicit default, made explicit)"] },
+      { flag: "[--persona-size <medium|large>]", prose: ["grow the default \"human\" persona's fact count", "beyond Small (the default): \"medium\" activates", "human-medium.jsonl (~1,608 facts total), \"large\" also", "activates human-large.jsonl (~13,600 facts total,", "with genuine multi-hop hypernym chains) — additive", "size tiers of the SAME bundle, not separate personas"] },
+      { flag: "[--memory-backend <default|memory|sqlite>]", prose: ["write tmct.toml's [memory] backend", "(same flag name as `tmct chat`) — a later `tmct chat`", "in this repo picks it up with no flag needed"] },
+    ],
+  },
+  {
+    mode: "import",
+    errorLabel: "import",
+    usage: "tmct import [--repo <abs>]",
+    prose: ["activate+seed into an ALREADY-initialized repo (any"],
+    flags: [
+      { flag: "[--corpus <id|path>]", prose: ["combination of these flags in one call). --graph is a"] },
+      { flag: "[--ontology <name|path>]", prose: ["DIFFERENT operation from the others: it APPENDS to"] },
+      { flag: "[--lexicon <name|path>]", prose: ["tmct.toml's graph_files array (multi-graph growth),"] },
+      { flag: "[--graph <path>]", prose: ["never an extensions-bundle activation."] },
+      { flag: "[--file <definition.txt>]", prose: ["teach a plain-text definition file sentence by", "sentence (# lines are comments); any declined", "sentence exits non-zero with the sentence named"] },
+      { flag: "[--memory-backend <default|memory|sqlite>]", prose: ["same knob as `tmct init`"] },
+      { flag: "[--config <path>]", prose: [] },
+    ],
+  },
+  {
+    mode: "extract",
+    errorLabel: "extract",
+    usage: "tmct extract <text-file>",
+    prose: ["read a plain text file's sentences through the chat's own"],
+    flags: [
+      { flag: "[--file <text-file>]", prose: ["teach recognizer and keep the facts it grounds; every", "other sentence is skipped and counted, never paraphrased"] },
+      { flag: "[--repo <abs>]", prose: ["write the facts into that repo's own tmct memory; without", "it nothing on disk is mutated and the facts print as JSONL"] },
+      { flag: "[--out <file.jsonl>]", prose: ["write that JSONL to a file instead of stdout"] },
+    ],
+  },
+  {
+    mode: "extend",
+    errorLabel: "extend --validate",
+    usage: "tmct extend --validate <dir>",
+    prose: ["validate a third-party extension pack's declared"],
+    flags: [
+      { flag: "[--config <path>]", prose: ["resources (corpus/lexicon/templates) before activating", "it in any repo's tmct.toml; exits non-zero on failure"] },
+    ],
+  },
+  {
+    mode: "syllogise",
+    errorLabel: "syllogise",
+    usage: "tmct syllogise [--repo <abs>]",
+    prose: ["speculative inference (offline maintenance job): forward-"],
+    flags: [
+      { flag: "[--depth <n>] [--budget <n>]", prose: ["chain the memory's rdfs:subClassOf closure, materialising"] },
+      { flag: "[--config <path>]", prose: ["bounded, low-trust, retractable entailed facts (never on the chat path)"] },
+    ],
+  },
+  {
+    mode: "viz",
+    errorLabel: "viz",
+    usage: "tmct viz [--repo <abs>]",
+    prose: ["write one self-contained HTML page: the memory graph as a"],
+    flags: [
+      { flag: "[--focus <term>]", prose: ["readable ledger of fact-sentences around one focus term,"] },
+      { flag: "[--term <word>]", prose: ["with segments, a two-hop minimap, and an in-page chat dock"] },
+      { flag: "[--limit <n>]", prose: ["that answers from the embedded graph. Focuses on the newest"] },
+      { flag: "[--output <path>]", prose: ["taught fact's subject by default (--focus <term> or"] },
+      { flag: "[--config <path>]", prose: ["--term <word> override it); --output defaults to", "ledger.html in the cwd; --limit caps the embedded fact", "rows; --term resolves via the same normalization chat uses."] },
+    ],
+  },
+  {
+    mode: "serve",
+    errorLabel: "serve",
+    usage: "tmct serve [--repo <abs>]",
+    prose: ["run the Anthropic Messages API-compatible endpoint"],
+    flags: [
+      { flag: "[--host <h>] [--port <n>]", prose: ["(POST /v1/messages) over the graph — a deterministic,"] },
+      { flag: "[--graph <path>]", prose: ["no-LLM \"model\" a tool-loop client can call; $0 usage."] },
+      { flag: "[--config <path>]", prose: ["Defaults: host 127.0.0.1, port 8787. Ctrl+C to stop."] },
+    ],
+  },
+  {
+    mode: "plan",
+    errorLabel: "plan",
+    usage: "tmct plan \"<request>\"",
+    prose: ["the capability router: compose/execute read-only graph-"],
+    flags: [
+      { flag: "[--repo <abs>]", prose: ["query tool calls for a compound or maintenance-goal"] },
+      { flag: "[--graph <path>]", prose: ["request (\"of the modules impacted by X, which are"] },
+      { flag: "[--config <path>]", prose: ["untested\", \"what most needs a test\") — a real STRIPS/"] },
+      { flag: "[--tools <a,b,...>]", prose: ["PDDL planner (src/domain/router/*), never a guessed call."] },
+      { flag: "[--json]", prose: ["Prints the grounded step sequence + composed answer,", "or an honest \"no plan found\". --tools restricts the", "declared toolset; --json prints the full loop result."] },
+    ],
+  },
+  {
+    mode: "cli",
+    errorLabel: "cli <tool> …",
+    usage: "tmct cli <tool> '{…}'",
+    prose: ["invoke a graph tool directly (carry-over, de-emphasized)"],
+    flags: [
+      { flag: "[--repo <abs>]", prose: ["the repo to answer from; the payload's \"repo_path\" says"] },
+      { flag: "[--graph <path>]", prose: ["the same thing. --graph names the graph file outright"] },
+      { flag: "[--config <path>]", prose: ["(repeatable), --config an alternate tmct.toml"] },
+    ],
+  },
+  {
+    mode: "cli",
+    errorLabel: "cli digest …",
+    usage: "tmct cli digest '{…}'",
+    prose: ["architecture map + per-module context bundles"],
+  },
+  {
+    mode: null,
+    usage: "tmct --help",
+    prose: ["show this help"],
+  },
+];
+
+function twoColumn(indent, left, prose) {
+  const head = " ".repeat(indent) + left;
+  if (!prose.length) return [head];
+  const column = Math.max(PROSE_COLUMN, head.length + 2);
+  return [head.padEnd(column) + prose[0], ...prose.slice(1).map((p) => " ".repeat(PROSE_COLUMN) + p)];
+}
+
+/** The `Usage:` block of `tmct --help`, rendered from CLI_VERBS. */
+export function renderUsage() {
+  const lines = [];
+  for (const { usage, prose, flags = [] } of CLI_VERBS) {
+    lines.push(...twoColumn(2, usage, prose));
+    for (const f of flags) lines.push(...twoColumn(7, f.flag, f.prose));
+  }
+  return lines.join("\n");
+}
+
+/** Every verb the dispatcher answers to, deduplicated (`cli` is two entries). */
+export function dispatchableModes() {
+  return [...new Set(CLI_VERBS.map((v) => v.mode).filter(Boolean))];
+}
+
+/** What an unknown invocation is told, naming every verb there is. */
+export function unknownInvocationMessage(invocation) {
+  const labels = CLI_VERBS.map((v) => v.errorLabel).filter(Boolean).map((l) => `\`${l}\``);
+  const suggestions = `${labels.slice(0, -1).join(", ")}, or ${labels.at(-1)}`;
+  return `tmct: unknown invocation "${invocation}". Use ${suggestions}.\n`;
+}