@polycode-projects/the-mechanical-code-talker 2.0.3 → 2.3.0

package/README.md

@@ -180,7 +180,7 @@ resolves to a real graph traversal or declines honestly:
   (*because/although/while*), conditionals, and false-premise flags ("why
   does X still import Y" when it no longer does).
 
-The full catalog with measured coverage lives in `CAPABILITIES_1.7.3.md` and
+The full catalog with measured coverage lives in `CAPABILITIES_2.0.3.md` and
 the `BENCHMARK_*.md` reports.
 
 **Response finishing.** Before an answer prints, it is segmented into typed

package/ROADMAP.md

@@ -100,7 +100,30 @@ blending web-sourced facts with graph/operator facts.
 
 ## Design docs
 
-Every substantial design lives in its own `PLAN_*.md` at the repo root (active) or `archive/`
-(shipped and closed) — this file points to them, it doesn't repeat their content. `SKILL_*.md` docs
-specify the repeatable measurement/build cycles (benchmarks, the background strategy advisor,
-plain-prose writing). `HANDOVER.md` is the single current-open-items list.
+Every substantial design lives in its own `PLAN_*.md` at the repo root; `archive/` holds the shipped
+and closed ones. This file points to them, it doesn't repeat their content. Each plan states its own
+status in its opening lines — read it there, because a status quoted here would rot.
+
+| Plan | What it's for |
+| --- | --- |
+| [PLAN_ADVENTURE.md](PLAN_ADVENTURE.md) | a text adventure as an architectural stretch: imperative command grammar, NPC turn scheduler, room-look digest |
+| [PLAN_AGENTS.md](PLAN_AGENTS.md) | the governing plan for the multi-repo arc (marginalia, seonix, a pluggable LLM rung), with its own phase sequencing |
+| [PLAN_CHILD_CORPUS.md](PLAN_CHILD_CORPUS.md) | a wider default seed corpus, chosen by age of acquisition |
+| [PLAN_CLASS_QUERY.md](PLAN_CLASS_QUERY.md) | "list/count all X of class Y", reconciled against what already shipped |
+| [PLAN_CODE.md](PLAN_CODE.md) | program synthesis over tmct's closed DSLs, plus JS/HTML/CSS fragments and goal-directed program repair |
+| [PLAN_CONSISTENCY_CHECK.md](PLAN_CONSISTENCY_CHECK.md) | tmct as a consistency service for an LLM tool loop |
+| [PLAN_EMBEDDINGS.md](PLAN_EMBEDDINGS.md) | the semantic-similarity axis, and the way back to it |
+| [PLAN_GRAPH_SCAN.md](PLAN_GRAPH_SCAN.md) | seed and query cost at `init:xl`/`init:xxl` corpus scale |
+| [PLAN_GUESS_NUMBER.md](PLAN_GUESS_NUMBER.md) | closed-loop planning over hidden state, via belief-interval bisection |
+| [PLAN_MUD.md](PLAN_MUD.md) | persistent, shared tmct worlds over a `server:` memory backend |
+| [PLAN_NLU_BENCHMARKS.md](PLAN_NLU_BENCHMARKS.md) | scoring tmct on the CLINC150 and HWU64 intent sets |
+| [PLAN_OPEN_ITEMS.md](PLAN_OPEN_ITEMS.md) | the build order closing the backlog `HANDOVER.md` carries |
+| [PLAN_PARAPHRASE_VERIFICATION.md](PLAN_PARAPHRASE_VERIFICATION.md) | checking a paraphrase against the graph before it prints |
+| [PLAN_PURGE.md](PLAN_PURGE.md) | promote the load-bearing code, delete the dead weight |
+| [PLAN_REPO_INDEX.md](PLAN_REPO_INDEX.md) | tmct grows its own code parsers, ported from seonix |
+| [PLAN_SYLLOGIST.md](PLAN_SYLLOGIST.md) | the reasoning engine's incrementality and retraction horizon |
+| [PLAN_SYLLOGIST_EL_DL.md](PLAN_SYLLOGIST_EL_DL.md) | beyond OWL 2 RL: an EL classifier, then a DL tableau prover |
+
+`SKILL_*.md` docs specify the repeatable measurement and build cycles (the benchmarks, the capability
+audit, the background strategy advisor, plain-prose writing). `HANDOVER.md` is the single
+current-open-items list.

package/bin/tmct.mjs

@@ -167,7 +167,7 @@ const TIER_RANK = { NONE: 0, TINY: 1, MID: 2, LARGE: 3, FULL: 4 };
  *   into a caller's prompt.
  *
  *  Two ways to say which modules: an explicit `modules` array (unchanged), or a `query` string —
- *  auto-locate + score-gap-select (R1b, the shipped default as of 2026-07-02) in one call, so a
+ *  auto-locate + score-gap-select (the shipped default) in one call, so a
  *  real caller no longer has to run `tmct_locate` and hand-pick a module themselves. `modules`
  *  wins if both are given. The header reports which modules were actually selected either way.
  *
@@ -741,8 +741,7 @@ async function main() {
     const lexiconVal = strFlag(rest, ["--lexicon"]);
     const graphFlags = repeatedFlag(rest, ["--graph"]);
 
-    // `--memory-backend <default|memory|sqlite>` (PLAN_SEED.md §6's storage-backend
-    // seam, now reachable from `tmct init`): validated BEFORE touching disk, same
+    // `--memory-backend <default|memory|sqlite>`: validated BEFORE touching disk, same
     // discipline as every other pluggable input below. Written into tmct.toml's
     // `[memory] backend` (src/services/init.mjs's renderTomlConfig); chat.mjs's
     // createSession reads it back at CLI-flag > TMCT_MEMORY_BACKEND env >
@@ -798,7 +797,7 @@ async function main() {
       personaPreset = PERSONA_PRESETS[personaName];
     }
 
-    // `--persona-size <medium|large>` (PLAN_SEED.md §3): Small/Medium/Large are
+    // `--persona-size <medium|large>`: Small/Medium/Large are
     // SIZES of the one `human` bundle, not separate corpus ids — human.jsonl
     // (Small, the default) stays exactly as-is; human-medium.jsonl/
     // human-large.jsonl hold ONLY the facts each size adds beyond the previous
@@ -1121,7 +1120,7 @@ async function main() {
   if (mode === "viz") {
     // `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
+    // the in-browser chat dock. 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);

package/corpus/generated/ace-surface-variants.jsonl

@@ -1,3 +1,4 @@
+{"kind":"rescue","sentence":"Code search is a retrieval task","rescued":"Code hunt is a retrieval task","from":"search","to":"hunt","pos":"noun","synsetId":"00947217-n","sourceFile":"PLAN_EMBEDDINGS.md","provenance":"wordnet:00947217-n"}
 {"kind":"variant","seed":"the ace of trumps is a sure winner","generated":"the one of trumps is a sure winner","from":"ace","to":"one","pos":"noun","synsetId":"13764713-n","sourceCorpus":"corpus/tier2/human-examples-large.jsonl","provenance":"wordnet:13764713-n"}
 {"kind":"variant","seed":"the ace of trumps is a sure winner","generated":"the single of trumps is a sure winner","from":"ace","to":"single","pos":"noun","synsetId":"13764713-n","sourceCorpus":"corpus/tier2/human-examples-large.jsonl","provenance":"wordnet:13764713-n"}
 {"kind":"variant","seed":"the ace of trumps is a sure winner","generated":"the unity of trumps is a sure winner","from":"ace","to":"unity","pos":"noun","synsetId":"13764713-n","sourceCorpus":"corpus/tier2/human-examples-large.jsonl","provenance":"wordnet:13764713-n"}

package/corpus/generated/manifest.json

@@ -2,8 +2,8 @@
   "version": 1,
   "generated": "by scripts/generate-template-variants.mjs",
   "file": "ace-surface-variants.jsonl",
-  "rows": 17,
-  "bytes": 4774,
-  "sha256": "5364415f73f7a366371f1fdcc072b5059f81871ef48b106088f05b1441def569",
+  "rows": 18,
+  "bytes": 5012,
+  "sha256": "28fae5a3353f5dd1df365b4407e0ac2a5c66b98b232d8bf454fe3573f2c16760",
   "license": "CC-BY-4.0 (WordNet-derived synonym substitutions of Open English WordNet / SemCor example sentences and this repo's own MPL-2.0 docs prose — see corpus/generated/README.md)"
 }

package/corpus/wordnet/generate.mjs

@@ -30,12 +30,11 @@
 //      emitting one row per edge (see RELATION_MAP / synonymPairs below).
 //
 // The hand-rolled `parseYaml` this file reuses (imported, not duplicated) is
-// scripts/extract-persona-sources.mjs's own tiny YAML-subset reader — already
-// proven against this exact OEWN dump shape by scripts/build-persona-tiers.mjs
-// and scripts/build-persona-examples.mjs. Reusing it (rather than adding a
-// general YAML dependency, or re-deriving a second hand-rolled parser) keeps
-// this converter self-consistent with the rest of the persona-tier tooling
-// that already reads this same source.
+// src/domain/wordnet/yaml.mjs's tiny YAML-subset reader — already proven
+// against this exact OEWN dump shape by the persona-tier tooling. Reusing it
+// (rather than adding a general YAML dependency, or re-deriving a second
+// hand-rolled parser) keeps this converter self-consistent with the rest of
+// the tooling that already reads this same source.
 //
 // Licence: Open English WordNet content is CC-BY-4.0 (Princeton WordNet +
 // Open English Wordnet team) — see LICENSE-NOTICE in this directory. The
@@ -47,7 +46,7 @@ import { homedir } from "node:os";
 import { createHash } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
-import { parseYaml } from "../../scripts/extract-persona-sources.mjs";
+import { parseYaml } from "../../src/domain/wordnet/yaml.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 export const WORDNET_OUT_DIR = HERE;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "2.0.3",
+  "version": "2.3.0",
   "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.",
@@ -72,8 +72,19 @@
     "test": "node --test \"test/**/*.test.mjs\"",
     "test:e2e": "node --test \"e2e/**/*.test.mjs\"",
     "e2e:browsers": "playwright install chromium",
+    "check:links": "node scripts/check-links.mjs",
+    "check:pii": "node scripts/pii-lint.mjs",
+    "check:pack": "node scripts/check-pack-manifest.mjs",
+    "check:licences": "node scripts/check-licences.mjs",
+    "check:publint": "npx --no-install publint",
+    "check:tool-docs": "node scripts/generate-tool-docs.mjs --check",
+    "check:publish": "node scripts/check-publish.mjs",
+    "check:all": "npm run check:links && npm run check:pii && npm run check:licences && npm run check:publint && npm run check:tool-docs",
+    "smoke:deploy": "node scripts/post-deploy-smoke.mjs",
     "chat": "node bin/tmct.mjs",
     "chat:repo": "node bin/tmct.mjs chat --repo",
+    "chat:plain": "node bin/tmct.mjs chat --plain",
+    "chat:narrate": "node bin/tmct.mjs chat --narrate",
     "init": "node bin/tmct.mjs init",
     "init:sqlite": "node --disable-warning=ExperimentalWarning bin/tmct.mjs init --memory-backend sqlite",
     "init:persona:human": "node bin/tmct.mjs init --with-persona human",
@@ -82,19 +93,36 @@
     "init:xl": "node bin/tmct.mjs init --persona-size large && node bin/tmct.mjs import --corpus seon && node bin/tmct.mjs import --corpus conceptnet && node bin/tmct.mjs import --corpus aws && node bin/tmct.mjs import --corpus python && node bin/tmct.mjs import --corpus java && node bin/tmct.mjs import --corpus wordnet-xl",
     "init:xxl": "node bin/tmct.mjs init --persona-size large && node bin/tmct.mjs import --corpus seon && node bin/tmct.mjs import --corpus conceptnet && node bin/tmct.mjs import --corpus aws && node bin/tmct.mjs import --corpus python && node bin/tmct.mjs import --corpus java && node bin/tmct.mjs import --corpus wordnet-full && node bin/tmct.mjs import --corpus namenet",
     "memory": "node bin/tmct.mjs memory",
+    "memory:verbose": "node bin/tmct.mjs memory --verbose",
     "syllogise": "node bin/tmct.mjs syllogise",
     "viz": "node bin/tmct.mjs viz",
+    "viz:term": "node bin/tmct.mjs viz --term",
+    "plan": "node bin/tmct.mjs plan",
+    "plan:json": "node bin/tmct.mjs plan --json",
+    "cli": "node bin/tmct.mjs cli",
+    "cli:digest": "node bin/tmct.mjs cli digest",
+    "import": "node bin/tmct.mjs import",
+    "extend": "node bin/tmct.mjs extend --validate",
+    "serve": "node bin/tmct.mjs serve",
+    "serve:public": "node bin/tmct.mjs serve --host 0.0.0.0 --port 8787",
     "example:mini": "node bin/tmct.mjs chat --repo examples/mini-webapp --ephemeral",
     "example:polyglot": "node bin/tmct.mjs chat --repo examples/polyglot --ephemeral",
     "chatbench:run": "node chatbench/run.mjs",
     "chatbench:judge": "node chatbench/judge.mjs",
-    "serve": "node bin/tmct.mjs serve",
     "agentbench:run": "node agentbench/run.mjs",
     "infbench": "node infbench/generate-cases.mjs && node infbench/run.mjs",
+    "corpus:matrix": "node scripts/corpus-matrix.mjs",
+    "corpus:matrix:gaps": "node scripts/corpus-matrix.mjs --gaps",
+    "template:coverage": "node scripts/template-coverage.mjs",
     "audit": "npm audit --audit-level=high",
     "audit:fix": "npm audit fix",
     "demo:build": "node scripts/build-demo-site.mjs",
     "build:ask-bundle": "node scripts/build-ask-bundle.mjs",
+    "build:demo-graph": "node scripts/build-demo-graph.mjs",
+    "build:demo-memory": "node scripts/build-demo-memory.mjs",
+    "gen:tool-docs": "node scripts/generate-tool-docs.mjs",
+    "gen:collisions": "node scripts/generate-real-word-collisions.mjs",
+    "gen:variants": "node scripts/generate-template-variants.mjs",
     "extract:facts": "node scripts/extract-facts-from-text.mjs"
   },
   "devDependencies": {

package/src/adapters/corpus/conceptnet.mjs

@@ -35,7 +35,7 @@ export const TIER2_MANIFEST_FILE = join(TIER2_DIR, "manifest.json");
 // conversion, same slice shape/loader path as tier-1/tier-2. "wordnet-xl"/"wordnet-full"
 // are wired as BUILTIN_EXTENSIONS corpus entries in src/extensions.mjs.
 export const WORDNET_DIR = join(PKG_ROOT, "corpus", "wordnet");
-export const WORDNET_MANIFEST_FILE = join(WORDNET_DIR, "manifest.json");
+const WORDNET_MANIFEST_FILE = join(WORDNET_DIR, "manifest.json");
 
 const ACE_PATTERNS = new Set(["subClassOf", "type", "ObjectProperty", "someValuesFrom", "disjointWith", "property", "none"]);
 

package/src/adapters/graph-build.mjs

@@ -352,7 +352,7 @@ export function buildEntities(modules, commits, { generatedAt = "", symbolHistor
   const countClass = (c) => fnIndividuals.filter((i) => i.class === c).length;
   const sampleClass = (c) => fnIndividuals.filter((i) => i.class === c).slice(0, 3).map((i) => i.label);
 
-  // Second pass (PLAN_PROSE_INDEX.md) — see the returned `proseIndex` field's comment below.
+  // Second pass — see the returned `proseIndex` field's comment below.
   const allIndividuals = attachProseTokens(
     [...moduleIndividuals, ...fnIndividuals, ...commitIndividuals], { enabled: prose },
   );
@@ -361,7 +361,7 @@ export function buildEntities(modules, commits, { generatedAt = "", symbolHistor
   return {
     generated_at: generatedAt,
     // SEON (se-on.org, FAMIX-derived) vocabulary + our `mgx:` extension, documented
-    // for readers; the graph is JSON-label-only (no RDF store — see PLAN_SEON_RDF.md).
+    // for readers; the graph is JSON-label-only (no RDF store).
     prefixes: {
       seon: "http://se-on.org/ontologies/seon.owl#",
       mgx: "urn:tmct:mgx#",
@@ -419,7 +419,7 @@ export function buildEntities(modules, commits, { generatedAt = "", symbolHistor
       rel("reexports", "mgx:reExports", reExportEdges),
     ],
     individuals: allIndividuals,
-    // Second pass (PLAN_PROSE_INDEX.md): word -> [individual ids], inverted from the
+    // Second pass: word -> [individual ids], inverted from the
     // `prose_tokens` attribute attachProseTokens just attached. Disable via
     // TMCT_PROSE_INDEX=0 (indexRepository, below) — {} when off. The typed graph above
     // (individuals' core fields, all edges) is byte-identical either way.

package/src/adapters/memory/blocks.mjs

@@ -18,8 +18,8 @@ const trustFactorOf = (trust) => 0.5 + (typeof trust === "number" ? trust : SOUR
 export const BLOCKS_DIR_REL = join(".tmct", "memory", "blocks");
 const INDEX_NAME = "index.json";
 
-export const PAGERANK_DAMPING = 0.85;
-export const PAGERANK_ITERATIONS = 20;
+const PAGERANK_DAMPING = 0.85;
+const PAGERANK_ITERATIONS = 20;
 export const OVERLAP_MIN = 2;   // shared tokens for a similarity edge
 const MAX_TOKENS_PER_BLOCK = 800; // beyond tokenizeProse's per-doc cap: union over lines
 

package/src/adapters/memory/core.mjs

@@ -43,7 +43,7 @@ export const IN_REPLY_TO_PROP = "mgx:inReplyTo";
 // The provenance-link predicate family: one umbrella object property with two
 // workhorse subproperties, minted in the owned mgx: namespace to match
 // tmct-core.ttl's object-property style.
-export const DERIVED_FROM_PROP = "mgx:derivedFrom";        // umbrella: Fact → Source|Fact
+const DERIVED_FROM_PROP = "mgx:derivedFrom";        // umbrella: Fact → Source|Fact
 export const STATED_BY_PROP = "mgx:statedBy";              // a Source directly asserts a Fact
 export const CANONICALISED_FROM_PROP = "mgx:canonicalisedFrom"; // a canonical Fact ← its raw form
 export const SOURCE_RELIABILITY_PROP = "mgx:sourceReliability"; // actor-level (session-scoped) trust nudge on a Source, [0.5,1.5]
@@ -52,7 +52,7 @@ export const SOURCE_RELIABILITY_PROP = "mgx:sourceReliability"; // actor-level (
 // with no session-id segment. A tag that does carry one mints its own
 // per-session Source instead (`${ID}:<sessionId>`, sourceIdFor below).
 export const OPERATOR_SOURCE_ID = "src:operator-chat";
-export const TEACH_SOURCE_ID = "src:teach-chat";
+const TEACH_SOURCE_ID = "src:teach-chat";
 
 const ROLES = new Set(["visitor", "tmct"]);
 const LABEL_CAP = 48;    // utterance/fact labels stay skimmable in renders
@@ -1113,13 +1113,13 @@ export const RULE_KIND_ACTION_SIGNATURE = "action-signature";
 export const RULE_KIND_ACTION_PRECOND = "action-precond";
 export const RULE_KIND_ACTION_EFFECT = "action-effect";
 export const RULE_KIND_ACTION_CONSTRAINT = "action-constraint";
-export const RULE_KINDS = Object.freeze([
+const RULE_KINDS = Object.freeze([
   RULE_KIND_COMPOSE2, RULE_KIND_FILTER, RULE_KIND_RECURSIVE,
   RULE_KIND_ACTION_SIGNATURE, RULE_KIND_ACTION_PRECOND, RULE_KIND_ACTION_EFFECT,
   RULE_KIND_ACTION_CONSTRAINT,
 ]);
 
-export const RULE_NAME_PROP = "mgx:ruleName";
+const RULE_NAME_PROP = "mgx:ruleName";
 export const RULE_KIND_PROP = "mgx:ruleKind";
 
 // Per-kind slot contract: JS slot key -> the mgx: attribute it's written under.
@@ -1514,7 +1514,7 @@ export async function removeFacts(dir, ids) {
 
 /** The trust floor a fact must clear before a differing object counts as a real
  *  contradiction (below it the fact is too weak to contradict anything). */
-export const CONTRADICTION_TRUST_FLOOR = 0.5;
+const CONTRADICTION_TRUST_FLOOR = 0.5;
 
 export const HAS_A_PREDICATE = "mgx:hasA";
 export const CAPABLE_OF_PREDICATE = "mgx:capableOf";

package/src/adapters/providers/bootstrap.mjs

@@ -13,7 +13,7 @@ import { emptyEntities } from "../source.mjs";
 import { createGraphService } from "./graph-service.mjs";
 
 /** The parsed empty bootstrap graph. */
-export function bootstrapGraph() {
+function bootstrapGraph() {
   return parseEntities(emptyEntities());
 }
 

package/src/adapters/providers/fixture.mjs

@@ -15,7 +15,7 @@ import { createGraphService } from "./graph-service.mjs";
 /** A compact but type-complete entities payload: modules, a class hierarchy
  *  (Base ← Widget ← Button), a method with a full signature, an attribute, a
  *  module global, and a commit — wired by one edge of every closed kind. */
-export const FIXTURE_ENTITIES = Object.freeze({
+const FIXTURE_ENTITIES = Object.freeze({
   generated_at: "2026-07-05T00:00:00.000Z",
   bootstrap: false,
   prefixes: { seon: "http://se-on.org/ontologies/seon.owl#", mgx: "urn:tmct:mgx#" },

package/src/adapters/toml-config.mjs

@@ -139,7 +139,6 @@ export async function normalizeConfig(raw, { configDir } = {}) {
   if (t.impl_of_interface !== undefined) tune.implOfInterface = t.impl_of_interface;
   if (t.beam_search !== undefined) tune.beamSearch = t.beam_search;
   if (t.beam_width !== undefined) tune.beamWidth = t.beam_width;
-  if (t.embed_rank !== undefined) tune.embedRank = t.embed_rank;
   if (t.prose_layers !== undefined) tune.proseLayers = t.prose_layers;
   const exp = t.expansion || {};
   const expansion = {};

package/src/adapters/wink-model.mjs

@@ -26,7 +26,7 @@ export function registerWinkModel(factory) {
 
 /** Load `{ winkNLP, model }` once, or null when wink isn't available. Prefers a
  *  registered browser factory; otherwise falls back to Node module resolution. */
-export function loadWinkModel() {
+function loadWinkModel() {
   if (cached !== undefined) return cached;
   try {
     const pair = injected ? injected() : nodeRequireWink();

package/src/adapters/wordnet-source.mjs

@@ -0,0 +1,70 @@
+// wordnet-source.mjs — reads a LOCAL Open English WordNet clone off disk and
+// indexes it. The clone is never vendored, never committed, never part of the
+// npm package: point TMCT_WORDNET_SRC at it, or keep it at the default path.
+//
+// This is the disk half of the WordNet reader. The parsing half is pure and
+// lives in src/domain/wordnet/yaml.mjs, so it is testable with no clone
+// present; everything here needs the real files.
+
+import { readFile, readdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { parseYaml } from "../domain/wordnet/yaml.mjs";
+
+export const WORDNET_SRC = process.env.TMCT_WORDNET_SRC || join(homedir(), "projects", "globalwordnet", "english-wordnet");
+export const WORDNET_YAML_DIR = join(WORDNET_SRC, "src", "yaml");
+
+/** True iff a WordNet clone is readable at `yamlDir`. Callers use this to fail
+ *  with a one-line message rather than a stack trace: these are maintainer
+ *  tools, never a build dependency. */
+export function hasWordnetSource(yamlDir = WORDNET_YAML_DIR) {
+  return existsSync(yamlDir);
+}
+
+/** Load one or more noun.<x>/verb.<x>.yaml files into a flat synset-id -> record map. */
+export async function loadSynsets(files, yamlDir = WORDNET_YAML_DIR) {
+  const map = new Map();
+  for (const f of files) {
+    const path = join(yamlDir, f);
+    if (!existsSync(path)) continue;
+    const parsed = parseYaml(await readFile(path, "utf8"));
+    for (const [id, rec] of Object.entries(parsed)) map.set(id, rec);
+  }
+  return map;
+}
+
+/** Load the entries-<letter>.yaml files that could contain any of `words`
+ *  (only the letters actually needed — 28 files, ~1MB-3MB each, no reason to
+ *  load all 28 when a clump only needs a handful of letters). Returns
+ *  word -> { n: [{id, synset}], v: [...], a: [...] }. */
+export async function loadEntriesFor(words, yamlDir = WORDNET_YAML_DIR) {
+  const letters = new Set();
+  for (const w of words) {
+    const c = w[0].toLowerCase();
+    letters.add(/[a-z]/.test(c) ? c : "0");
+  }
+  const index = new Map();
+  for (const letter of letters) {
+    const path = join(yamlDir, `entries-${letter}.yaml`);
+    if (!existsSync(path)) continue;
+    const parsed = parseYaml(await readFile(path, "utf8"));
+    for (const [word, byPos] of Object.entries(parsed)) {
+      if (!words.has(word)) continue;
+      const senses = {};
+      for (const [pos, rec] of Object.entries(byPos || {})) {
+        if (pos === "form") continue;
+        const list = Array.isArray(rec?.sense) ? rec.sense : [];
+        senses[pos] = list.map((s) => ({ id: s.id, synset: s.synset })).filter((s) => s.synset);
+      }
+      index.set(word, senses);
+    }
+  }
+  return index;
+}
+
+/** Every noun.*.yaml synset in the clone. */
+export async function loadAllNounSynsets(yamlDir = WORDNET_YAML_DIR) {
+  const files = (await readdir(yamlDir)).filter((f) => f.startsWith("noun."));
+  return loadSynsets(files, yamlDir);
+}

package/src/domain/answer-variants.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "curation": "Hand-curated. scripts/generate-answer-variants.mjs cross-checked each pool against real Open English WordNet synsets (scripts/lib/wordnet-synonyms.mjs) where a sense fit; most of these are domain-specific code-graph connector phrases WordNet's own sense-1 convention resolves to the wrong sense for -- e.g. 'locate' -> 'turn up', 'record' -> 'enter, put down', 'module' -> 'mental faculty' -- so every entry below was accepted or rejected by hand against the exact rendered sentence it replaces, never auto-accepted from a raw synset match. See src/domain/answer-variants.mjs for how these are selected at render time.",
+  "curation": "Hand-curated, and it has to stay that way: each pool was cross-checked against real Open English WordNet synsets where a sense fit, but most of these are domain-specific code-graph connector phrases whose sense-1 convention resolves to the wrong sense -- e.g. 'locate' -> 'turn up', 'record' -> 'enter, put down', 'module' -> 'mental faculty'. So every entry below was accepted or rejected by hand against the exact rendered sentence it replaces, never auto-accepted from a raw synset match. That is why no generator reproduces this file and no drift guard can check it. See src/domain/answer-variants.mjs for how these are selected at render time.",
   "pools": {
     "defined-in": {
       "base": "defined in",

package/src/domain/ask-vocab.mjs

@@ -211,7 +211,7 @@ export function stripTrailingScopeFiller(text) {
 
 /** Trailing bare discourse tags ("how many of those then"). "too" can stack
  *  ("is UserController a validator too then"), hence the double pass below. */
-export const TRAILING_DISCOURSE_TAG = Object.freeze(["then", "though", "too"]);
+const TRAILING_DISCOURSE_TAG = Object.freeze(["then", "though", "too"]);
 
 const TRAILING_DISCOURSE_TAG_RE = new RegExp(
   `\\s+(?:${TRAILING_DISCOURSE_TAG.join("|")})\\s*[?.!]*$`, "i",
@@ -219,7 +219,7 @@ const TRAILING_DISCOURSE_TAG_RE = new RegExp(
 
 /** Trailing comma-delimited discourse clauses ("what is a class, please
  *  explain"), anchored on a literal comma so this never fires mid-phrase. */
-export const TRAILING_DISCOURSE_CLAUSE = Object.freeze(["please explain", "explain"]);
+const TRAILING_DISCOURSE_CLAUSE = Object.freeze(["please explain", "explain"]);
 
 const TRAILING_DISCOURSE_CLAUSE_RE = new RegExp(
   `,\\s*(?:${TRAILING_DISCOURSE_CLAUSE.join("|")})\\s*[?.!]*$`, "i",

package/src/domain/ask.mjs

@@ -1786,7 +1786,7 @@ function evalQualCheck(graph, ast, opts) {
 
 /** Compile any compositional AST to a result object traverse() returns for the
  *  simple path — {matches, …} plus compositeKind/compositeMiss flags render() reads. */
-export function evalComposite(graph, ast, opts = {}) {
+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);
@@ -1828,7 +1828,7 @@ const compositeList = (matches) => listJoin(matches.slice(0, OVERFLOW_CAP)
   + (matches.length > OVERFLOW_CAP ? `, …and ${matches.length - OVERFLOW_CAP} more` : "");
 
 /** A compositional worked example for the rephrase hint. */
-export function compositionalHint() {
+function compositionalHint() {
   return 'compositional queries also work: "which functions call X and call Y", "what calls something that imports X", "public methods of X", "list functions" / "show me the classes", "how many classes", "which module has the most imports", "find me the payment class", or (after a listing) "which of those are tested"';
 }
 
@@ -2047,7 +2047,7 @@ export function rephraseHint() {
  *  It gets a line that says what the store actually holds instead. A NULL
  *  graph is UNKNOWN, not empty (see chat.mjs's noCodeGraph), so it keeps the
  *  index-shaped advice. */
-export function touchesRephraseHint(graph = null) {
+function touchesRephraseHint(graph = null) {
   if (graph && moduleCountOf(graph) === 0) {
     return "This store holds no code index, so it records no modules or commits to look through.";
   }
@@ -3516,7 +3516,7 @@ function isHelpRequest(query) {
  *                        they are content that may honestly fail to resolve.
  *    3. SYNONYM        — rewrite surviving near-canonical words to the closed vocab.
  *  Bounded (one token removed per noise iteration; hard guard) and deterministic. */
-export function relaxParse(graph, query, { nlp = undefined, contextId = null, prev = null } = {}) {
+function relaxParse(graph, query, { nlp = undefined, contextId = null, prev = null } = {}) {
   const from = applyNegationFrames(normalizeQuery(String(query || "")));
   let tokens = splitWords(from);
   if (!tokens.length) return null;

package/src/domain/codegraph.mjs

@@ -1,5 +1,4 @@
 import { lookupByProseTokens, proseLayerHits, splitIdentifierWords } from "./prose.mjs";
-import { cosine } from "./vector.mjs";
 import { CREATED_AT_PROP, UPDATED_AT_PROP } from "./memory/trust.mjs";
 
 // Pure (no-network, no-fs) query logic over the typed `entities` payload that the
@@ -129,11 +128,11 @@ function basename(p) {
 
 const isProvRef = (r) => /^(git|turn):/.test(String(r || ""));
 
-export function turnRefCount(ind) {
+function turnRefCount(ind) {
   return (ind?.derived_from || []).filter(isProvRef).length;
 }
 
-export function mentionTotal(ind) {
+function mentionTotal(ind) {
   const fromMentions = (ind?.mentions || []).reduce((n, m) => n + (Number(m?.count) || 0), 0);
   return fromMentions + turnRefCount(ind);
 }
@@ -511,15 +510,6 @@ const LIT_COMP_CAP = 4;
 const LIT_FRAC = 1.0;
 const LIT_CAP_FRAC = 0.9;
 
-// opt-in via embedRank + an injected embedder: static-embedding re-rank over
-// path/symbol/doc text read from the graph (never source), cached per-process in EMB_CACHE
-const EMB_FRAC = 0.2;
-const EMB_CAP_FRAC = 0.35;
-const EMB_TEXT_SYMBOL_CAP = 64;
-const EMB_TEXT_DOC_CAP = 12;
-const EMB_CACHE = new WeakMap(); // graph -> { embedder, texts, vecs: Map<moduleId, Float32Array> }
-let embedWarned = false;
-
 // opt-in via beamSearch: multi-ply adaptive expansion of the proximity nudge above.
 // Beam width is a margin relative to each ply's best score (not a fixed count), so a
 // weak-then-strong candidate isn't prematurely discarded. Successors are generated
@@ -544,30 +534,6 @@ const SPIRAL_HOP_DECAY = 0.6;
 const SPIRAL_PROX_FRAC = 0.2;
 const SPIRAL_PROX_CAP_FRAC = 0.35;
 
-/** embedRank: per-module embeddable text from path components + defined symbol
- *  names + doc first-lines, cached alongside the vectors in EMB_CACHE. */
-function moduleEmbedTexts(graph) {
-  const texts = new Map(); // moduleId -> text
-  const defIdx = definesIndex(graph);
-  const docs = new Map();  // moduleId -> [doc first-lines]
-  for (const ind of graph.individuals) {
-    const doc = (ind.attributes || []).find((a) => a.key === "doc")?.value;
-    if (!doc) continue;
-    const modId = (ind.class || "") === "Module" ? ind.id : moduleIdOf(graph, ind);
-    if (!modId) continue;
-    let arr = docs.get(modId);
-    if (!arr) docs.set(modId, (arr = []));
-    if (arr.length < EMB_TEXT_DOC_CAP) arr.push(String(doc).split("\n")[0]);
-  }
-  for (const ind of graph.individuals) {
-    if ((ind.class || "") !== "Module") continue;
-    const parts = String(ind.label).split(/[^a-zA-Z0-9_]+/).filter(Boolean);
-    const syms = (defIdx.get(ind.id) || []).slice(0, EMB_TEXT_SYMBOL_CAP);
-    texts.set(ind.id, [...parts, ...syms, ...(docs.get(ind.id) || [])].join(" "));
-  }
-  return texts;
-}
-
 /** Split a lowercased path label into boundary components: django/utils/text.py →
  *  {django,utils,text,py}. Component equality (not substring) stops "text" matching "ci<text>". */
 function pathComponents(labelLc) {
@@ -773,7 +739,7 @@ export function spiralExpand(graph, scored = [], {
  *  IDF-weights each query token, scores path/symbol/exact-symbol matches, and
  *  re-ranks with a bounded import-proximity bonus. Pure; deterministic. */
 function scoreModules(graph, tokens, opts = {}) {
-  const { demoteNonProd = false, callAdjacency = false, implOfInterface = false, beamSearch = false, spiral = false, proseBoost = false, proseLayers = false, literalMention = false, embedRank = false, rawQuery = "" } = opts;
+  const { demoteNonProd = false, callAdjacency = false, implOfInterface = false, beamSearch = false, spiral = false, proseBoost = false, proseLayers = false, literalMention = false, rawQuery = "" } = opts;
   const beamWidth = Number.isFinite(opts.beamWidth) && opts.beamWidth > 0 ? opts.beamWidth : 8;
   const defIdx = definesIndex(graph);
   // Precompute each module's path components + defined-symbol exact/component sets, once.
@@ -967,36 +933,6 @@ function scoreModules(graph, tokens, opts = {}) {
       s.score += Math.min(signal * PROSE_LAYER_FRAC, s.score * PROSE_LAYER_CAP_FRAC);
     }
   }
-  // embedRank: the embedder is injected so this module stays fs-free; absent -> a one-time
-  // stderr note, never a failure
-  if (embedRank) {
-    if (!opts.embedder) {
-      if (!embedWarned) {
-        embedWarned = true;
-        process.stderr.write("tmct: embedRank requested but no embedder available (weights not fetched? see `npm run refs:embeddings`) — flag is a no-op\n");
-      }
-    } else if (scored.length) {
-      const embedder = opts.embedder;
-      let cache = EMB_CACHE.get(graph);
-      if (!cache || cache.embedder !== embedder) {
-        cache = { embedder, texts: moduleEmbedTexts(graph), vecs: new Map() };
-        EMB_CACHE.set(graph, cache);
-      }
-      const qv = embedder.embed(rawQuery || tokens.join(" "));
-      let maxBase = 0;
-      for (const s of scored) maxBase = Math.max(maxBase, s.score);
-      for (const s of scored) {
-        let v = cache.vecs.get(s.ind.id);
-        if (!v) {
-          v = embedder.embed(cache.texts.get(s.ind.id) || String(s.ind.label));
-          cache.vecs.set(s.ind.id, v);
-        }
-        const sim = Math.max(0, cosine(qv, v)); // negative similarity never penalises
-        if (!sim) continue;
-        s.score += Math.min(sim * maxBase * EMB_FRAC, s.score * EMB_CAP_FRAC);
-      }
-    }
-  }
   // beamSearch (opt-in): multi-ply generalization of the single-hop families above.
   if (beamSearch && scored.length > 1) beamExpand(graph, scored, beamWidth);
   // SPIRAL (opt-in): bounded-radius ego walk that may introduce lexically-invisible modules — runs
@@ -1024,9 +960,9 @@ export function searchModulesRanked(graph, query, opts = {}) {
   const tokens = raw.toLowerCase().split(/[^a-z0-9_]+/).filter(Boolean);
   if (!tokens.length) return [];
   // literalMention needs the query BEFORE tokenization (the tokenizer destroys the dotted refs
-  // it matches on) and embedRank embeds the raw phrasing; threaded only when a flag that
-  // consumes it is on, so the OFF path is provably unchanged.
-  const effOpts = (opts.literalMention || opts.embedRank) ? { ...opts, rawQuery: raw } : opts;
+  // it matches on); threaded only when a flag that consumes it is on, so the OFF path is
+  // provably unchanged.
+  const effOpts = opts.literalMention ? { ...opts, rawQuery: raw } : opts;
   return scoreModules(graph, tokens, effOpts).map((s) => ({ path: String(s.ind.label), score: s.score }));
 }
 
@@ -1466,7 +1402,7 @@ const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "
 
 /** Map of lowercased author name → that author's Commit individuals (payload order).
  *  Tolerates both attribute-key conventions (author / commitAuthor), like commitLine. */
-export function authorIndex(graph) {
+function authorIndex(graph) {
   const idx = new Map();
   for (const ind of graph?.individuals || []) {
     if ((ind.class || "") !== "Commit") continue;