@polycode-projects/the-mechanical-code-talker 1.11.0 → 1.11.5

package/README.md

@@ -121,7 +121,7 @@ focus the ledger.
 Two more surfaces, both generated by tmct itself:
 
 ```bash
-npx tmct viz --ledger                 # ledger.html — your own memory as the same
+npx tmct viz                          # ledger.html — your own memory as the same
                                       # readable, self-contained explorer
 npx tmct init
 npx tmct import --file .tmct/imports/games/hanoi-3.txt
@@ -427,7 +427,7 @@ tmct                                  # bare = chat (the headline)
 tmct chat --repo /abs/path/to/repo    # chat over a specific repo's graph
 tmct init                             # scaffold .tmct/, tmct.toml, seed + provenance
 tmct syllogise                        # offline: pre-derive entailed facts (maintenance)
-npm run viz -- --output graph.html && open graph.html   # self-contained HTML graph view
+npm run viz && open ledger.html       # self-contained HTML memory-ledger explorer
 ```
 
 Inside the chat: `/help` lists commands, `/memory` inspects what tmct remembers
@@ -552,25 +552,18 @@ inference" above:
        [--config <path>]      bounded, low-trust, retractable entailed facts (never on the chat path)
 ```
 
-`tmct viz` renders the memory graph to a single HTML file you can open in a browser:
+`tmct viz` renders the memory graph as the ledger explorer — a single,
+self-contained HTML file you can open in a browser:
 
 ```
-  tmct viz [--repo <abs>]      write one self-contained, navigable HTML file rendering the
-       [--ledger]             memory graph: pan/zoom, click a node for its label/class/
-       [--focus <id>]         timestamps. Seeds from the most recently created individual
-       [--term <word>]        by default (--focus <id> or --term <word> override it);
-       [--depth <n>]          --output defaults to graph.html in the cwd. With --ledger,
-       [--limit <n>]          a readable fact ledger around one focus term instead
-                              (writes ledger.html; --limit caps the embedded fact rows).
-       [--hub-degree <n>]     --depth = max arcs (hops) from the focus node (default 3);
-       [--edge-kind <mode>]   --limit = spiral length, total nodes walked (default 300);
-       [--output <path>]      --hub-degree = stop expanding THROUGH a node above N
-       [--config <path>]      connections, still shows it (default 40); --edge-kind =
-                               meta|relation|both (default both) — which edge kinds the
-                               walk follows (provenance-only, concept-relations-only, or
-                               both — see the page's own edge-kind toggle to change this
-                               live); --term <word> resolves to the Fact(s) whose subject/
-                               object normalizes to that word and seeds from there.
+  tmct viz [--repo <abs>]      write one self-contained HTML page: the memory graph as a
+       [--focus <term>]       readable ledger of fact-sentences around one focus term,
+       [--term <word>]        with segments, a two-hop minimap, and an in-page chat dock
+       [--limit <n>]          that answers from the embedded graph. Focuses on the newest
+       [--output <path>]      taught fact's subject by default (--focus <term> or
+       [--config <path>]      --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.
 ```
 
 `tmct serve` runs an Anthropic Messages API-compatible HTTP endpoint over the graph,
@@ -620,7 +613,7 @@ recognized key set, so you can see the full surface in one place
 # Newline-delimited-file form is also accepted: repositories = "repos.txt"
 repositories = ["../other-service", "../another-service"]
 
-# Where generated output (e.g. tmct viz's default graph.html) resolves to.
+# Where generated output (e.g. tmct viz's default ledger.html) resolves to.
 out_root = "./out"
 
 # The code-graph JSON artifact. TMCT_GRAPH_FILE overrides this at runtime.

package/ROADMAP.md

@@ -11,7 +11,7 @@ A tolerant, ELIZA/PARRY-style chat surface over a codebase, obsessed with softwa
 obsessed with the mafia — deterministic, zero-cost, **no LLM anywhere in the product path**. Guides a
 user toward precision queries rather than guessing; every answer is grounded, restates every genuine
 reading it finds in full, or is an honest miss when nothing grounds it at all. Its visual surfaces —
-the ledger explorer with its in-browser chat (`tmct viz --ledger`), the animated plan page
+the ledger explorer with its in-browser chat (`tmct viz`), the animated plan page
 (`chat --prompt … --render blocks`), and the Pages homepage hero — are the same graph read out loud:
 same engine, same provenance, no LLM.
 
@@ -51,19 +51,16 @@ getting silently traded away by inherited caution:
   and an NPC turn scheduler. Design-only.
 - **`PLAN_SYLLOGIST.md`** — retraction-aware consistency checking under a hard budget and trust
   tiers, the one open piece of the reasoning engine's research horizon. Design-only.
-- **`PLAN_HANOI.md` follow-ups** — the plan itself shipped (taught game domains, the chat plan
-  lane, `tmct import --file` + the `.tmct/imports/` scaffold, the animated plan page; see its
-  implementation addendum). Remaining: river-crossing's two missing frames plus the multi-effect
-  interpreter extension, and planner-side consumption of the `taught:` capability records the
-  registry bridge now registers.
+- **`PLAN_HANOI.md`** — shipped in full, including the follow-ups: river-crossing (co-travel
+  effects, the forbidden-together constraint frame, 7-crossing oracle) and planner-side
+  consumption of `taught:` capability records (`/plan` in chat and bin). See its dated addenda.
 - **`PLAN_GUESS_NUMBER.md`** — the closed-loop (observe-and-replan) planning domain for the same
   kernels. Design-only.
-- **`PLAN_VIZ_LEDGER.md` follow-ups** — phases 1-4 shipped (the ledger explorer, its chat dock,
-  the Pages hero, this README pass). Remaining: whether the ledger becomes the default viz
-  surface; a `goal` field on `factAnswer`'s returns so the dock can carry the chat's goal line
-  (needs operator sign-off — it touches the ask engine); a predicate-cardinality question for
-  `findContradictions` (multi-valued `has`/`can` facts group under the same contract as genuine
-  disagreements); bundle weight if the ledger page outgrows its measured ~533 KB.
+- **`PLAN_VIZ_LEDGER.md`** — shipped in full, including the follow-ups, all resolved by
+  operator decision 2026-07-15: the ledger IS the `tmct viz` surface (node-link page removed),
+  `factAnswer`/`factReadBack` carry the additive `goal` field the dock renders, multi-valued
+  has/can facts are exempt from `findContradictions`, and page weight is budgeted (~561 KB
+  after this batch; revisit only if outgrown). See its dated addendum.
 - **`PLAN_CODE.md`** — small JS-function and HTML/CSS-fragment synthesis via a sandboxed headless
   browser (Track 1, program synthesis, already shipped). Blocked on a sandbox dependency decision.
 - **`PLAN_AGENTS.md`** — the governing plan for tmct's broader multi-repo arc (marginalia, seonix,

package/bin/tmct.mjs

@@ -93,22 +93,14 @@ Usage:
   tmct syllogise [--repo <abs>] speculative inference (offline maintenance job): forward-
        [--depth <n>] [--budget <n>]  chain the memory's rdfs:subClassOf closure, materialising
        [--config <path>]      bounded, low-trust, retractable entailed facts (never on the chat path)
-  tmct viz [--repo <abs>]      write one self-contained, navigable HTML file rendering the
-       [--ledger]             memory graph: pan/zoom, click a node for its label/class/
-       [--focus <id>]         timestamps. Seeds from the most recently created individual
-       [--term <word>]        by default (--focus <id> or --term <word> override it);
-       [--depth <n>]          --output defaults to graph.html in the cwd. With --ledger,
-       [--limit <n>]          a readable fact ledger around one focus term instead
-                               (writes ledger.html; --limit caps the embedded fact rows).
-       [--hub-degree <n>]     --depth = max arcs (hops) from the focus node (default 3);
-       [--edge-kind <mode>]   --limit = spiral length, total nodes walked (default 300);
-       [--output <path>]      --hub-degree = stop expanding THROUGH a node above N
-       [--config <path>]      connections, still shows it (default 40); --edge-kind =
-                               meta|relation|both (default both) — which edge kinds the
-                               walk follows (provenance-only, concept-relations-only, or
-                               both — see the page's own edge-kind toggle to change this
-                               live); --term <word> resolves to the Fact(s) whose subject/
-                               object normalizes to that word and seeds from there.
+  tmct viz [--repo <abs>]      write one self-contained HTML page: the memory graph as a
+       [--focus <term>]       readable ledger of fact-sentences around one focus term,
+       [--term <word>]        with segments, a two-hop minimap, and an in-page chat dock
+       [--limit <n>]          that answers from the embedded graph. Focuses on the newest
+       [--output <path>]      taught fact's subject by default (--focus <term> or
+       [--config <path>]      --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.
   tmct serve [--repo <abs>]    run the Anthropic Messages API-compatible endpoint
        [--host <h>] [--port <n>]  (POST /v1/messages) over the graph — a deterministic,
        [--graph <path>]        no-LLM "model" a tool-loop client can call; $0 usage.
@@ -1092,73 +1084,50 @@ async function main() {
   }
 
   if (mode === "viz") {
-    // `tmct viz` — one self-contained, navigable HTML file rendering the
-    // memory graph (PLAN_BREADTH_FIRST_NLU.md §5, PLAN_VIZ.md's design):
-    // pan/zoom, click-a-node, a concentric ring layout keyed on hop with a
-    // depth/age falloff. Same repo resolution as `memory`/`syllogise` —
-    // resolveRuntimeConfig: --repo > git root > cwd.
+    // `tmct viz` — the ledger explorer: one self-contained HTML page rendering
+    // the memory graph as readable fact-sentences around a focus term, with
+    // the in-browser chat dock (PLAN_VIZ_LEDGER.md). Same repo resolution as
+    // `memory`/`syllogise` — resolveRuntimeConfig: --repo > git root > cwd.
+    // `--ledger` is accepted as a no-op: the ledger IS the viz surface now.
     const rest = process.argv.slice(3);
-    const { strFlag, boolFlag, resolveRuntimeConfig } = await import("../src/cli-args.mjs");
-    const { computeVizGraph, renderVizHtml, readAskBundle, readMemoryAskBundle } = await import("../src/viz.mjs");
+    const retiredFlags = ["--depth", "--hub-degree", "--edge-kind"].filter((f) => rest.includes(f));
+    if (retiredFlags.length) {
+      process.stderr.write(
+        `tmct viz: ${retiredFlags.join(", ")} belonged to the retired node-link graph page and no longer exist${retiredFlags.length === 1 ? "s" : ""}.\n`
+        + "The ledger view takes: --repo <abs>, --focus <term>, --term <word>, --limit <n>, --output <path>.\n",
+      );
+      process.exitCode = 1;
+      return;
+    }
+    const { strFlag, resolveRuntimeConfig } = await import("../src/cli-args.mjs");
+    const { computeLedgerData, renderLedgerHtml, readMemoryAskBundle } = await import("../src/ledger-viz.mjs");
     const { writeFile } = await import("node:fs/promises");
     const { resolve } = await import("node:path");
-    const numFlag = (name) => {
-      const j = rest.indexOf(name);
-      const v = j !== -1 ? Number(rest[j + 1]) : NaN;
-      return Number.isFinite(v) ? v : undefined;
-    };
-    const ledger = boolFlag(rest, ["--ledger"]);
+    const limitIdx = rest.indexOf("--limit");
+    const limitRaw = limitIdx !== -1 ? Number(rest[limitIdx + 1]) : NaN;
+    const rowLimit = Number.isFinite(limitRaw) ? limitRaw : undefined;
     const focus = strFlag(rest, ["--focus"]);
-    const term = strFlag(rest, ["--term"]); // PLAN_VIZ_MEMORY.md: seed via normFactTerm-matched Fact(s), alongside --focus
-    const depth = numFlag("--depth"); // max arcs (hops) from the focus node
-    const nodeLimit = numFlag("--limit"); // spiral length: total nodes walked (ledger mode: fact-row cap)
-    const hubDegree = numFlag("--hub-degree"); // stop expanding THROUGH a node above N connections
-    const edgeKindModeRaw = strFlag(rest, ["--edge-kind"]);
-    const edgeKindMode = ["meta", "relation", "both"].includes(edgeKindModeRaw) ? edgeKindModeRaw : undefined;
-    const outPath = resolve(process.cwd(), strFlag(rest, ["--output", "--out"], ledger ? "ledger.html" : "graph.html"));
+    const term = strFlag(rest, ["--term"]); // seeds via normFactTerm; --focus wins when both are given
+    const outPath = resolve(process.cwd(), strFlag(rest, ["--output", "--out"], "ledger.html"));
     const { repo } = await resolveRuntimeConfig({ argv: rest });
-    if (ledger) {
-      const { computeLedgerData, renderLedgerHtml } = await import("../src/ledger-viz.mjs");
-      const data = await computeLedgerData(repo, {
-        ...(focus ? { focus } : {}),
-        ...(!focus && term ? { term } : {}),
-        ...(nodeLimit != null ? { rowLimit: nodeLimit } : {}),
-      });
-      const memoryAskBundle = await readMemoryAskBundle();
-      await writeFile(outPath, renderLedgerHtml({ ...data, memoryAskBundle }), "utf8");
-      process.stdout.write(
-        `tmct viz --ledger — wrote ${data.meta.shown} fact row(s) around ${data.focus ? `'${data.focus}'` : "no focus"} to ${outPath}\n`,
-      );
-      if (data.meta.truncated) {
-        process.stdout.write(
-          `showing ${data.meta.shown} of ${data.meta.total} rows — narrow with --focus <term> or raise --limit\n`,
-        );
-      }
-      return;
-    }
-    const vizGraph = await computeVizGraph(repo, {
+    const data = await computeLedgerData(repo, {
       ...(focus ? { focus } : {}),
-      ...(!focus && term ? { term } : {}), // --focus takes precedence when both are given
-      ...(depth != null ? { depth } : {}),
-      ...(nodeLimit != null ? { nodeLimit } : {}),
-      ...(hubDegree != null ? { hubDegree } : {}),
-      ...(edgeKindMode ? { edgeKindMode } : {}),
+      ...(!focus && term ? { term } : {}),
+      ...(rowLimit != null ? { rowLimit } : {}),
     });
-    // The embedded "Ask the graph" chat panels — TWO real engines, bundled for
-    // the browser (scripts/build-ask-bundle.mjs's checked-in output): the
-    // code-graph ask.mjs engine, and (PLAN_VIZ_MEMORY.md Bug 1 fix) the
-    // memory-graph factAnswer engine. Neither read*AskBundle() ever throws; an
-    // empty string degrades that ONE engine gracefully rather than breaking
-    // the page (e.g. a fresh checkout before the bundles' first build).
-    const [askBundle, memoryAskBundle] = await Promise.all([readAskBundle(), readMemoryAskBundle()]);
-    const html = renderVizHtml({ ...vizGraph, askBundle, memoryAskBundle });
-    await writeFile(outPath, html, "utf8");
-    const chatNote = askBundle || memoryAskBundle
-      ? ` (with the embedded ask-the-graph chat panel${askBundle && memoryAskBundle ? "s" : ""})`
-      : " (no chat panel — run `npm run build:ask-bundle` first)";
+    // readMemoryAskBundle never throws; an empty string renders the page with
+    // an honest "chat unavailable" note instead of the dock (e.g. a fresh
+    // checkout before the bundle's first build).
+    const memoryAskBundle = await readMemoryAskBundle();
+    await writeFile(outPath, renderLedgerHtml({ ...data, memoryAskBundle }), "utf8");
     process.stdout.write(
-      `tmct viz — wrote ${vizGraph.nodes.length} node(s), ${vizGraph.edges.length} edge(s) to ${outPath}${chatNote}\n`,
+      `tmct viz — wrote ${data.meta.shown} fact row(s) around ${data.focus ? `'${data.focus}'` : "no focus"} to ${outPath}\n`,
     );
+    if (data.meta.truncated) {
+      process.stdout.write(
+        `showing ${data.meta.shown} of ${data.meta.total} rows — narrow with --focus <term> or raise --limit\n`,
+      );
+    }
     return;
   }
 
@@ -1264,7 +1233,7 @@ async function main() {
       process.stderr.write("tmct plan: needs a request, e.g. `tmct plan \"of the modules impacted by X, which are untested\"`\n");
       process.exit(2);
     }
-    const { config } = await resolveRuntimeConfig({ argv: rest });
+    const { repo, config } = await resolveRuntimeConfig({ argv: rest });
     const { buildCapabilityPlanCtx, runCapabilityPlan, declaredCapabilityNames } = await import("../src/router/drive.mjs");
     const declared = declaredCapabilityNames();
     let tools = declared;
@@ -1278,34 +1247,49 @@ async function main() {
     }
     let ctx;
     try {
-      ctx = await buildCapabilityPlanCtx({ config });
+      ctx = await buildCapabilityPlanCtx({ config, memoryDir: repo });
     } catch (e) {
       process.stderr.write(`tmct plan: could not load the graph — ${e?.message || e}\n`);
       process.exit(1);
     }
-    const result = await runCapabilityPlan(request, tools, ctx);
-    if (jsonFlag) {
-      process.stdout.write(JSON.stringify({ request, ...result }, null, 2) + "\n");
-      process.exit(result.refused ? 1 : 0);
-    }
-    process.stdout.write(`tmct plan: "${request}"\n`);
-    if (result.refused) {
-      process.stdout.write(`no plan found — ${Array.isArray(result.why) ? result.why.join("; ") : result.why}\n`);
-      if (result.c1Why) {
-        process.stdout.write(`(the direct router also declined: ${Array.isArray(result.c1Why) ? result.c1Why.join("; ") : result.c1Why})\n`);
+    // The default (no --tools) toolset is re-read AFTER the ctx build: the
+    // memory store's taught: capability records only register there, and a
+    // world goal refuses when its taught record is outside the toolset.
+    if (!toolsFlag) tools = declaredCapabilityNames();
+    try {
+      const result = await runCapabilityPlan(request, tools, ctx);
+      if (jsonFlag) {
+        process.stdout.write(JSON.stringify({ request, ...result }, null, 2) + "\n");
+        process.exit(result.refused ? 1 : 0);
       }
-      process.exit(1);
-    }
-    process.stdout.write(`driver: ${result.driver}\n\nsteps:\n`);
-    for (let i = 0; i < result.calls.length; i += 1) {
-      const c = result.calls[i];
-      let text = "";
-      try { text = await ctx.dispatch(c.name, c.input || {}).then((r) => (r.ok ? r.text : `(unresolved: ${r.error})`)); }
-      catch (e) { text = `(error: ${e?.message || e})`; }
-      process.stdout.write(`  ${i + 1}. ${c.name} ${JSON.stringify(c.input || {})}\n     ${String(text).split("\n").join("\n     ")}\n`);
-    }
-    if (result.composed !== undefined && result.composed !== null) {
-      process.stdout.write(`\ncomposed answer (${result.composed.length}): ${result.composed.length ? result.composed.join(", ") : "(empty set)"}\n`);
+      process.stdout.write(`tmct plan: "${request}"\n`);
+      if (result.refused) {
+        process.stdout.write(`no plan found — ${Array.isArray(result.why) ? result.why.join("; ") : result.why}\n`);
+        if (result.c1Why) {
+          process.stdout.write(`(the direct router also declined: ${Array.isArray(result.c1Why) ? result.c1Why.join("; ") : result.c1Why})\n`);
+        }
+        process.exit(1);
+      }
+      process.stdout.write(`driver: ${result.driver}\n\nsteps:\n`);
+      for (let i = 0; i < result.calls.length; i += 1) {
+        const c = result.calls[i];
+        let text = "";
+        // taught: records are simulated, never dispatchable — dispatching one
+        // would print a misleading "unknown tool" under an honest plan step.
+        if (c.name.startsWith("taught:")) text = "(simulated over the taught rules — execute it in chat with \"next\")";
+        else {
+          try { text = await ctx.dispatch(c.name, c.input || {}).then((r) => (r.ok ? r.text : `(unresolved: ${r.error})`)); }
+          catch (e) { text = `(error: ${e?.message || e})`; }
+        }
+        process.stdout.write(`  ${i + 1}. ${c.name} ${JSON.stringify(c.input || {})}\n     ${String(text).split("\n").join("\n     ")}\n`);
+      }
+      if (result.composed !== undefined && result.composed !== null) {
+        process.stdout.write(`\ncomposed answer (${result.composed.length}): ${result.composed.length ? result.composed.join(", ") : "(empty set)"}\n`);
+      } else if (result.observed) {
+        process.stdout.write(`\n${result.observed}\n`);
+      }
+    } finally {
+      for (const dispose of ctx.disposers || []) dispose();
     }
     return;
   }

package/data/games/river.txt

@@ -0,0 +1,33 @@
+# river — the wolf/goat/cabbage crossing, taught with the same closed frames
+# as hanoi-3 plus two new families: a co-travel effect (the farmer rides every
+# crossing) and the "may not be with ... without ..." constraint.
+# Lines starting with # are skipped by import.
+#
+# After `tmct import --file river.txt`, try this in `tmct chat` (or via --prompt):
+#
+#   wolf-1 stands on bank-east. goat-1 stands on bank-east.
+#   cabbage-1 stands on bank-east. farmer-1 stands on bank-east.
+#   the goal is that every passenger stands on bank-west. solve it.
+#
+# The classic optimum is 7 crossings: goat over, farmer back, wolf over, goat
+# back, cabbage over, farmer back, goat over. From the opening position exactly
+# 1 move is legal (ferry the goat) — every other crossing leaves the wolf with
+# the goat, or the goat with the cabbage, without the farmer.
+#
+# Other things to try:
+#   legality  — "what moves are legal now?"  (one ply, no plan; shows the
+#               constraint pruning: 1 legal move at the start)
+#   read-back — "what stands on bank-east?"  (plain fact question, no planning)
+a passenger is a kind of game piece.
+a bank is a kind of place.
+wolf-1 is a wolf. wolf-1 is a passenger.
+goat-1 is a goat. goat-1 is a passenger.
+cabbage-1 is a cabbage. cabbage-1 is a passenger.
+farmer-1 is a farmer.
+bank-east is a bank. bank-west is a bank.
+you can ferry a passenger onto a bank.
+you can ferry a farmer onto a bank.
+ferrying a passenger onto a bank makes the passenger stand on the target.
+ferrying a passenger onto a bank makes the farmer stand on the target.
+to ferry a passenger onto a bank, the wolf may not be with the goat without the farmer.
+to ferry a passenger onto a bank, the goat may not be with the cabbage without the farmer.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "1.11.0",
+  "version": "1.11.5",
   "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.",

package/src/ask.mjs

@@ -31,7 +31,7 @@ import { parseAnchored } from "./interpret/strategies/grammar.mjs";
 import { parseKeywordSpot, findPhrase } from "./interpret/strategies/keywords.mjs";
 import { runStrategiesSync } from "./interpret/pipeline.mjs";
 import { mergeStrategyResults, alternateLines } from "./interpret/merge.mjs";
-import { lookupByProseTokens } from "./prose.mjs";
+import { lookupByProseTokens, splitIdentifierWords } from "./prose.mjs";
 import { pickPhrase } from "./answer-variants.mjs";
 
 // Normalization stays importable from its original site (tests + chat surface).
@@ -88,6 +88,20 @@ function nounFor(entityType, n) {
   return n === 1 ? s : p;
 }
 
+/** A class enum rendered as prose words ("GlobalVariable" -> "global
+ *  variable"), lowercase to match nounFor's own convention. For the render
+ *  sites that must name the enum itself rather than a curated PLURAL_FORMS
+ *  noun. The typeof guard is the same viewer-bundle boundary the tier-4 prose
+ *  fallback documents: viz.mjs's askSource strips the prose.mjs import. */
+export function classDisplayName(cls) {
+  const s = String(cls || "");
+  if (typeof splitIdentifierWords === "function") {
+    const words = splitIdentifierWords(s).join(" ");
+    if (words) return words;
+  }
+  return s.replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase();
+}
+
 // Every relation kind is already the correct 3rd-person-singular verb form
 // except "cochange" ("X cochanges Y") and "reexports" (human word "export").
 const REVERSE_MISS_VERB = { cochange: "cochanges", reexports: "export" };
@@ -2342,6 +2356,43 @@ function commitTouches(graph, commit, entityType, extra = {}) {
   };
 }
 
+// ---- entry-point survey for the where-defined shape: "where is the (main)
+// entry point defined" names a ROLE, not a label, so resolveObject can only
+// miss it (or accidentally substring-match something unrelated). A closed
+// basename vocabulary stands in for the role; every candidate is ranked
+// deterministically and the ranking is disclosed in the answer, never a
+// silently picked single winner. ----
+
+/** The where-defined object phrasings that ask for the entry-point role. */
+const ENTRY_POINT_QUERY_RE = /^(?:the\s+)?(?:main\s+|primary\s+)?entry[\s-]?points?(?:\s+(?:of|to|for)\s+(?:this|the)\s+(?:codebase|code|repo|repository|project|app))?$/i;
+/** Module basenames conventionally used as a program's entry point. */
+const ENTRY_POINT_BASENAMES = new Set(["index", "main", "app", "server", "cli", "__main__"]);
+/** Directory segments marking test/fixture territory — ranked below real code. */
+const TEST_FIXTURE_PATH_SEGMENTS = new Set(["test", "tests", "__tests__", "fixture", "fixtures", "spec", "specs", "testdata"]);
+
+const moduleStemOf = (label) => String(label).toLowerCase().split("/").pop().replace(/\.[a-z0-9]+$/, "");
+const isTestFixturePath = (label) => String(label).toLowerCase().split("/").slice(0, -1)
+  .some((seg) => TEST_FIXTURE_PATH_SEGMENTS.has(seg));
+
+/** All entry-point-basename Modules, best first: a basename the query itself
+ *  names ("MAIN entry point" -> main.mjs) beats root proximity (fewer path
+ *  segments), which beats a non-test path over a test/fixture one; a full tie
+ *  falls back to label order so the ranking is stable. */
+function rankEntryPointModules(graph, term) {
+  const queryWords = new Set(String(term || "").toLowerCase().split(/[\s-]+/).filter(Boolean));
+  return (graph.individuals || [])
+    .filter((i) => i.class === "Module" && ENTRY_POINT_BASENAMES.has(moduleStemOf(i.label)))
+    .map((ind) => ({
+      ind,
+      named: queryWords.has(moduleStemOf(ind.label)) ? 1 : 0,
+      depth: String(ind.label).split("/").length,
+      fixture: isTestFixturePath(ind.label) ? 1 : 0,
+    }))
+    .sort((a, b) => (b.named - a.named) || (a.depth - b.depth) || (a.fixture - b.fixture)
+      || String(a.ind.label).localeCompare(String(b.ind.label)))
+    .map((x) => x.ind);
+}
+
 /** Safety net: a {shape, kind, entityType} combination must be explicitly
  *  listed here to receive real non-"direct" modifier behavior; anything else
  *  gets an honest "not supported yet" response, never a silent fallback to
@@ -2414,6 +2465,18 @@ export function traverse(graph, parsed, { contextId = null, prev = null, pinnedO
     };
   }
 
+  // where + an entry-point ROLE phrasing: checked before object resolution,
+  // which could only miss the role term or accidentally land on an unrelated
+  // partial match.
+  if (shape === "where" && ENTRY_POINT_QUERY_RE.test(String(parsed.object || "").trim())) {
+    const ranked = rankEntryPointModules(graph, parsed.object);
+    return {
+      matches: ranked, objMatch: ranked[0] || null, candidates: ranked.slice(1, 5),
+      ambiguous: false, entryPointShape: true,
+      traversal: `Module individuals with an entry-point basename (${[...ENTRY_POINT_BASENAMES].join("/")}), ranked query-named basename first, then shallower path, then non-test path`,
+    };
+  }
+
   // Checked before object resolution, so an unsupported modifier+kind
   // combination gets its own honest capability-gap message.
   if (parsed.modifier && parsed.modifier !== "direct" && !modifierIsWired(shape, kind, entityType)) {
@@ -2598,7 +2661,7 @@ export function traverse(graph, parsed, { contextId = null, prev = null, pinnedO
         return {
           matches: [], objMatch, candidates, ambiguous, matchedVia,
           forwardGrainMiss: true, wantClasses: [...wantClasses],
-          traversal: `${fwdKinds.join("+")} edges where subject = ${objMatch.label} (grain mismatch: this "${kind}" relation never targets a ${entityType})`,
+          traversal: `${fwdKinds.join("+")} edges where subject = ${objMatch.label} (grain mismatch: this "${kind}" relation never targets a ${classDisplayName(entityType)})`,
         };
       }
     }
@@ -2705,7 +2768,7 @@ export function traverse(graph, parsed, { contextId = null, prev = null, pinnedO
         return {
           matches: [], objMatch: gObjMatch, candidates: gCandidates, ambiguous: gAmbiguous, matchedVia: gMatchedVia,
           wrongGrainMiss: true, wantClass,
-          traversal: `"${parsed.object}" resolved to ${gObjMatch.class} ${gObjMatch.label} (grain mismatch: this "${kind}" question needs a ${wantClass}, and no containing module could be found to refine to)`,
+          traversal: `"${parsed.object}" resolved to ${classDisplayName(gObjMatch.class)} ${gObjMatch.label} (grain mismatch: this "${kind}" question needs a ${classDisplayName(wantClass)}, and no containing module could be found to refine to)`,
         };
       }
     } else {
@@ -2714,7 +2777,7 @@ export function traverse(graph, parsed, { contextId = null, prev = null, pinnedO
       return {
         matches: [], objMatch: gObjMatch, candidates: gCandidates, ambiguous: gAmbiguous, matchedVia: gMatchedVia,
         wrongGrainMiss: true, wantClass,
-        traversal: `"${parsed.object}" resolved to ${gObjMatch.class} ${gObjMatch.label} (grain mismatch: this "${kind}" question needs a ${wantClass})`,
+        traversal: `"${parsed.object}" resolved to ${classDisplayName(gObjMatch.class)} ${gObjMatch.label} (grain mismatch: this "${kind}" question needs a ${classDisplayName(wantClass)})`,
       };
     }
   }
@@ -2764,7 +2827,7 @@ export function traverse(graph, parsed, { contextId = null, prev = null, pinnedO
     } else if (entityType !== "Module" && subjects.some((s) => s.class === "Module")) {
       const moduleIds = new Set(subjects.filter((s) => s.class === "Module").map((s) => s.id));
       matches = refineToEntities(graph, moduleIds, entityType);
-      grainNote = `, then ${entityType} defined in the matched module(s)`;
+      grainNote = `, then ${classDisplayName(entityType)} defined in the matched module(s)`;
     } else {
       matches = [];
     }
@@ -2883,6 +2946,7 @@ function renderCore(parsed, result) {
       return {
         content: `this could mean more than one thing:\n${options}\n(ask one of these directly, or try rephrasing more specifically, to get just that reading)`,
         miss: false, ambiguous: true, candidates: parsed.candidates.map(describeParse),
+        candidateParses: parsed.candidates,
       };
     }
     // Fallback (no `result.branches` — e.g. a caller invoking render() directly
@@ -2891,6 +2955,7 @@ function renderCore(parsed, result) {
     return {
       content: `this could mean more than one thing: ${options} — try rephrasing more specifically.`,
       miss: false, ambiguous: true, candidates: parsed.candidates.map(describeParse),
+      candidateParses: parsed.candidates,
     };
   }
   if (result.unresolvedPronoun) {
@@ -2967,6 +3032,25 @@ function renderCore(parsed, result) {
       miss: false, ambiguous: false, matches: result.matches,
     };
   }
+  // entry-point survey: every candidate is disclosed with the rank order,
+  // never a silently picked single winner; zero candidates is an honest miss
+  // naming the closed basename vocabulary that was searched.
+  if (result.entryPointShape) {
+    if (!result.matches.length) {
+      return {
+        content: `no entry-point module found in the index — no module basename matches ${listJoin([...ENTRY_POINT_BASENAMES])}.`,
+        miss: true, ambiguous: false, candidates: [],
+      };
+    }
+    const [top, ...rest] = result.matches;
+    const shownRest = rest.slice(0, OVERFLOW_CAP).map((i) => i.label);
+    const extra = rest.length > OVERFLOW_CAP ? `, …and ${rest.length - OVERFLOW_CAP} more` : "";
+    const also = rest.length ? ` — also matched: ${listJoin(shownRest)}${extra}` : "";
+    return {
+      content: `ranked ${result.matches.length} entry-point match${result.matches.length === 1 ? "" : "es"}; top: ${top.label}${also}.`,
+      miss: false, ambiguous: false, matches: result.matches,
+    };
+  }
   if (!result.objMatch && (!result.candidates || result.candidates.length === 0) && parsed.shape !== "ask") {
     // Name what kind of thing was looked for: a sha-shaped term reads as
     // "commit", a dotted slash-free term as "symbol" (both keep priority over
@@ -3491,6 +3575,12 @@ function dynamicClassQuery(graph, query) {
 // extract the term for the article-insertion fallback rather than duplicating it.
 const BARE_META_WHATIS_RE = /^what\s+(?:is|are)\s+(?:an?\s+)?(.+?)[?.!\s]*$/i;
 
+// "what is X for" / "what is X used for" with a bare entity term — the lead
+// refuses a/an articles and pronouns so the vocabulary phrasings ("what is a
+// horse for", "what is it for") never read as an entity term; a leading "the"
+// is entity-term noise (resolveObject's own article strip) and is dropped.
+const WHATIS_FOR_FALLBACK_RE = /^what\s+is\s+(?:the\s+)?(?!(?:an?|it|this|that|these|those)\s)(.+?)\s+(?:used\s+)?for[?.!\s]*$/i;
+
 export function ask(graph, query, { contextId = null, nlp = undefined, prev = null } = {}) {
   if (isHelpRequest(query)) {
     return {
@@ -3540,6 +3630,29 @@ export function ask(graph, query, { contextId = null, nlp = undefined, prev = nu
       }
     }
   }
+  // "what is X for" — the purpose paraphrase of the same bare-whatis intent,
+  // excluded from the block above (and from the phrasing frames) because
+  // chat.mjs's module-overview lane owns this phrasing and gates on an ask()
+  // miss. The meta reading is adopted ONLY when it actually answers (a unique
+  // metaFallback entity); on a miss, every byte — parsed, canonical, the miss
+  // text — stays exactly as the lane cascade expects. Article/pronoun-led
+  // terms ("what is a horse for") belong to the memory-facts readers and are
+  // never claimed.
+  if (parsed === null && rendered.miss && !rendered.ambiguous) {
+    const forM = normalizeQuery(String(query || "")).match(WHATIS_FOR_FALLBACK_RE);
+    const forTerm = forM?.[1]?.trim();
+    if (forTerm) {
+      const forParsed = parseQuery(`what is a ${forTerm}`, { nlp });
+      if (forParsed?.shape === "meta") {
+        const forResult = traverse(graph, forParsed, { contextId, prev });
+        const forRendered = render(forParsed, forResult);
+        if (!forRendered.miss && !forRendered.ambiguous) {
+          result = forResult;
+          rendered = forRendered;
+        }
+      }
+    }
+  }
   // If relaxation materially rewrote the query and produced a real answer,
   // note it lightly so the reader knows how the question was read.
   let content = (relaxed && !rendered.miss && relaxed.to !== relaxed.from)
@@ -3586,7 +3699,7 @@ export function ask(graph, query, { contextId = null, nlp = undefined, prev = nu
       // edit-distance, announced in the content as "assuming you meant …");
       // null for every literal-identifier tier.
       matchedVia: result.matchedVia || null,
-      ...(rendered.ambiguous ? { candidates: rendered.candidates } : {}),
+      ...(rendered.ambiguous ? { candidates: rendered.candidates, candidateParses: rendered.candidateParses } : {}),
     },
   };
 }