@polycode-projects/the-mechanical-code-talker 0.2.0

package/ROADMAP.md

@@ -0,0 +1,209 @@
+# tmct ROADMAP
+
+tmct v0.1.0 was a **whole-package lift** of the seonix chat surface (published
+as `@polycode-projects/mct`): identical shape, green tests, new branding. That
+was deliberate — it gave every ambition below a working, tested starting point
+instead of a green field. v0.2.0 is the **reshape**: the lift's LLM fallback,
+extraction stack, and MCP server are gone, and the package, naming, and license
+now match the product this document describes.
+
+This roadmap is organized into phases. The original 16 ambition items are
+mapped into them (item numbers retained for traceability); the seven sketches
+formerly held in `code-talker-ideas.txt` are folded into items 8–11 below and
+the file has been deleted.
+
+## The umbrella product definition (item 1)
+
+**A tolerant, ELIZA/PARRY-style chat, obsessed with software.** A best-efforts
+conversational surface that guides users toward precision queries.
+ELIZA/PARRY-style pattern reflection, but domain-obsessed the way PARRY was
+obsessed with the mafia — tmct may heavily assume a narrow context (you are
+asking about *this* codebase, or about what tmct itself remembers) and exploit
+that assumption to answer cheaply and confidently. Tolerant of loose, fuzzy,
+misspelled input; never silently wrong; **no LLM anywhere in the product**.
+Every phase below serves this definition.
+
+---
+
+## Phase 0 — Reshape (v0.2.0) — the current work
+
+One commit per step, `npm test` green at each.
+
+- **DONE — Strip the LLM fallback** (`--with-claude` / `--with-copilot` and the
+  `hook-augment` mode removed; the product path is now provably model-free).
+- **DONE — Drop the extraction/viz stack** *(item 12: shed the codebase-index
+  dependency)*: Python `ast`, tree-sitter, Roslyn/Java extractors, walk/viz/
+  timeline/temporal modules, `roslyn/`, `java/`, `templates/` all deleted. tmct
+  consumes a graph via the provider seam; it produces none.
+- **DONE — Drop the MCP server**: `@modelcontextprotocol/sdk` removed;
+  `dispatchTool` survives as the plain internal tool switch.
+- **DONE — Carve `buildEntities`** into `src/graph-build.mjs`: the pure
+  in-memory graph assembly function, kept as the future memory writer
+  primitive.
+- **DONE — Empty-graph bootstrap** *(item 14, partial)*: a missing graph file
+  is no longer an error; tmct starts empty, says so, and creates
+  `.tmct/graph.json` from the conversation. The full provider adapter contract
+  is Phase 1.
+- **DONE — tmct naming purge** *(item 15, widened)*: seonix AND the interim
+  "mct" replaced throughout — package
+  `@polycode-projects/the-mechanical-code-talker`, bin `tmct`
+  (`bin/tmct.mjs`), tool prefix `tmct_*`, artifact dir `.tmct/`, env
+  `TMCT_GRAPH_FILE`, prompt `tmct>`.
+- **DONE — License swap to MPL-2.0** (from AGPL-3.0): free commercial use,
+  file-level publish-and-attribute copyleft.
+- **DONE — README rewrite + GitLab Pages home page** (`public/index.html`,
+  `pages` CI job): https://polycode-projects.gitlab.io/the-mechanical-code-talker/
+- **DONE — `docs/references/` skeleton + `ontology/`**: the reference-library
+  index (canonical URL / retrieval date / licence / consumer per entry), OWL 2
+  vocabulary notes, ACE-OWL sub-fragment pattern table, ConceptNet relation
+  list, and the `ontology/tmct-core.ttl` placeholder. This feeds the Phase 2
+  grammar work; the library grows as sources are web-verified.
+- **DONE — Publish 0.2.0** under the new name; deprecate
+  `@polycode-projects/mct@0.1.0` with a rename pointer.
+
+---
+
+## Phase 1 — Interpretation pipeline + memory foundations
+
+### Item 8 — Multi-strategy request classification and ranking → `src/interpret/`
+Instead of a single best-guess parse, run the request through **all the classes
+of thing it could be**, parse it with each class's own strategy (grammar parse,
+keyword picking, noise-word removal, fuzzy matching — later the ACE strategy
+from Phase 2), execute the strategies that look like winners, then **merge
+same-class results** and surround **distinct-class results** with "if you mean
+X then …". Grows from `ask.mjs`'s existing 2-way merge into
+`interpret/pipeline.mjs` + `interpret/merge.mjs` + `interpret/strategies/*`.
+*(Covers sketch 1 of the former `code-talker-ideas.txt`: "request → all the
+classes of things it could be → parse using each class-specific strategy →
+execute winners → combine similar result classes and rank".)*
+
+### Item 13 — The clean chat / primitives split
+Pull the movable conversational grammar out of the core primitives
+(`resolveObject`, `edgesOfKind`, `refineToEntities`, `traverse`) so the chat
+engine stands alone. `chat.mjs` slims to the conversational layer + `runTurn`
+orchestration.
+
+### Item 10 — Input normalization pass (grammar / spell / style checks)
+Run a grammar check, spell check, and style check over input as a
+normalization pass alongside classification (item 8), so misspelled or
+ungrammatical input is repaired or scored before template matching — the
+concrete mechanism behind item 1's "tolerant of loose, fuzzy, misspelled
+input" promise. The same checks later serve the "observe" ambition (item 6)
+over repo prose. *(Covers sketches 3, 4, and 5 of the former ideas file:
+grammar check, spell check, style check.)*
+
+### Item 9 — Conversational memory as its own graph → `src/memory/`
+Record every parsed request as an "a-visitor-said" item and every response
+alongside it, in tmct's own OWL-labelled graph (`memory/core.mjs`), with text
+blocks under a PageRank-style relevance index (`memory/blocks.mjs`) and
+session-log cleaning/folding (`memory/fold.mjs`). Future input can then match
+against **prior questions** by similarity, not just against a provided code
+graph. This is tmct's own data under `.tmct/`, distinct from any
+provider-supplied graph and not written back through the provider adapter.
+*(Covers sketch 2 of the former ideas file: "once parsed the text is added to
+the graph as a-visitor-said item; responses from queries go in the graph; text
+matching may find similar questions".)*
+
+### Item 14 (finish) — The graph-provider adapter contract
+Define the provider touchpoint interface — a loader yielding
+`{ individuals, byId, relations, proseIndex }` plus the published primitives —
+so seonix or any other producer can feed tmct without tmct importing an
+indexer. Phase 0 shipped the bootstrap seam; this finishes the contract.
+
+### Item 16 — Library-first design for extension
+Keep the `exports` map and the primitives stable and documented as the
+internals are refactored.
+
+### Shell work
+- **OpenTUI console shell** around `runTurn`; readline `runChat` stays as
+  `--plain` and as the test surface.
+- Fold the surviving `bin/cli.mjs` arms into `bin/tmct.mjs`; delete `cli.mjs`.
+
+---
+
+## Phase 2 — Grammar → OWL + corpus
+
+### Item 2 — Its own well-defined grammar → `src/grammar/ace.mjs`
+A first-class, documented, testable grammar — an **ACE-inspired controlled
+fragment** (~8 sentence patterns; see
+`docs/references/schemas/ace-owl-fragment.md`) that emits **OWL-labelled
+triples** when text fits it, backed by a declared lexicon
+(`grammar/lexicon.mjs`, TOML/JSONL data). Plugs into the item-8 pipeline as
+one strategy among several: fitting the grammar is a strong signal, missing it
+falls back to the tolerant strategies.
+
+### Item 3 — Ontology grounding: core OWL/RDF + SE vocabularies
+Ground the memory vocabulary in real ontologies: core **OWL 2 / RDF / RDFS**
+scaffolding plus software-entity concepts (the SEON-derived terms the graph
+already uses — `seon:`, `mgx:` prefixes — with **OWL-SEON** and **FAMIX** as
+reference vocabularies). Deliverable: `ontology/tmct-core.ttl`.
+
+### Items 4 + 7 — Template libraries, phrase book, plain data formats
+Sentence-fragment template libraries for matching input and generating
+responses, plus a software-engineering phrase book — all in plain, diffable
+formats (**JSONL**, **TOML**, **.txt** line files).
+
+### ConceptNet corpus slice
+A committed, filtered English/tech-domain **ConceptNet slice** (CC-BY-SA 4.0
+notice, size-budgeted) with the ~35-row relation→ACE-OWL-pattern mapping table
+(`src/corpus/conceptnet.mjs` + `conceptnet-map.toml`; relation list in
+`docs/references/schemas/conceptnet-relations.md`). The corpus seeds the
+bootstrap graph so an empty tmct still has a vocabulary.
+
+### Reference library growth
+Grow `docs/references/` with web-verified sources: ACE/APE papers, ConceptNet
+docs, ELIZA/PARRY lineage papers (only redistributable licences committed) —
+and finish `ontology/tmct-core.ttl` alongside the grammar work.
+
+---
+
+## Phase 3 — Chat tuning cycle (autonomous)
+
+The measurement loop that turns the above into a tunable product — specified
+in `SKILL_TUNING_CYCLE.md`:
+
+- a fixed, versioned **chatbench case set** (`chatbench/cases.jsonl`);
+- a **deterministic replay runner** over `runTurn` (the product is
+  deterministic — one run per arm suffices);
+- **LLM-as-judge** scoring (N≥3 samples per case; groundedness / correctness /
+  honesty-on-miss / rephrase-hint helpfulness). The judge lives in the **eval
+  harness only** — the product stays no-LLM;
+- `CHATBENCH_0NN.md` artifacts and an autonomous cycle loop (no hard pause;
+  each cycle logs its ranked decision menu and continues).
+
+Inside this loop, two earlier ambitions become **tuning levers** rather than
+standalone features:
+
+### Item 5 — Calculation surfaced as reasoning
+Derived facts presented as lightweight reasoning ("there are a lot of tests
+for a codebase of that size", "this module is unusually central") —
+calculations, not inference: deterministic, explainable, cheap.
+
+### Item 6 — Optionally running linters/tests to *observe*
+Let tmct run linters or tests to observe whether something actually worked,
+reporting the observation — measurement, not reasoning.
+
+### Item 11 — Formal logical reasoning over the ontology (Prolog / Progol) — exploratory, gated
+Apply real rules of inference (modus tollens, etc.) to formulas extracted from
+parsed prose, checked against the axioms in the ontology (item 3) — a step
+beyond item 5's arithmetic. The sketch: map OWL constructs into templates over
+parameter expressions (Prolog terms or similar), then use a theorem prover —
+Progol (inductive logic programming) is the named candidate — to prove goals
+against parsed prose. Materially bigger than item 5 and dependent on the
+Phase 2 ontology landing; **exploratory until a spike confirms the
+OWL-to-template mapping is tractable**. *(Covers sketches 6 and 7 of the
+former ideas file: "reasoning as the application of logic rules to the formula
+created from prose against the set of axioms in the graph, possibly search
+using Prolog" and "fit OWL constructs into templates / parameter expressions,
+then use Progol to theorem-prove against parsed prose".)*
+
+---
+
+## Explicitly out of scope (for now)
+
+- No AWS, no benchmark rig — tmct is a published npm library + CLI with a
+  static GitLab Pages home page only.
+- No auto-publish: releasing a version is gated on a deliberate version-bump
+  commit plus a configured `NPM_TOKEN` in CI.
+- No MCP server, no LLM in the product path — permanently out of scope, not
+  just "for now".

package/bin/cli.mjs

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+// tmct — local typed-edge code-graph tools over a pre-built graph artifact:
+//
+//   tmct cli digest '{"repo_path":"<abs>","modules":[…]}' → architecture map + per-module
+//                                                             context bundles to stdout
+//   tmct cli digest '{"repo_path":"<abs>","query":"<free text>"}' → same, but auto-locates +
+//     score-gap-selects the modules (R1b, the shipped default) instead of requiring an explicit
+//     `modules` list — one call from a question to a digest. `modules` wins if both are given.
+//   tmct cli <toolName> '{…args}'                     → invoke ANY tool via Bash
+//     (e.g. tmct cli tmct_ask '{"query":"<free text>"}' — mechanical, no-LLM NL question
+//      over the graph; no bespoke wiring needed, this fallback covers it)
+//   tmct chat [--repo <abs>] → interactive prompt over the mechanical tmct_ask engine; /exit to leave; session log → <repo>/.tmct/session-<uuidv7>.log
+//
+// The graph artifact lives at <repo_path>/.tmct/graph.json; the tools (run with
+// cwd = that repo) load it by default. No flags, no config files.
+
+import { join } from "node:path";
+import { dispatchTool, buildContextBundle } from "../src/server.mjs";
+import { loadConfig, DEFAULT_GRAPH_REL } from "../src/config.mjs";
+import * as source from "../src/source.mjs";
+import { parseEntities, rankModulesByProximity, searchModulesRanked, selectRankedModules, DEFAULT_SCORE_GAP } from "../src/codegraph.mjs";
+
+/** Build a config pointed at a specific repo's artifact (for `cli` sub-commands that
+ *  take a repo_path), or fall back to the cwd-derived default. */
+function configFor(repoPath) {
+  return repoPath ? { graphFile: join(repoPath, DEFAULT_GRAPH_REL) } : loadConfig();
+}
+
+/** Parse the trailing JSON payload of a `cli` sub-command (best-effort). */
+function parsePayload(payload) {
+  if (!payload) return {};
+  try { return JSON.parse(payload); }
+  catch { return null; }
+}
+
+const DIGEST_MODULE_CAP = 12;   // bound the digest — a handful of changed modules
+const DIGEST_SECONDARY_CAP = 2; // B2: at most this many SECONDARY modules get a (trimmed) bundle
+const TIER_RANK = { NONE: 0, TINY: 1, MID: 2, LARGE: 3, FULL: 4 };
+
+/** `cli digest` — print a machine-readable header + a repo architecture map + the
+ *  tmct_context edit bundle for each requested module to stdout (reuses the server's exact
+ *  renderer via buildContextBundle, so no render logic is duplicated). This stdout is injected
+ *   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
+ *  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.
+ *
+ *  B2: the FIRST (primary) module gets a full size-adaptive bundle; the remaining modules are
+ *  RANKED by import/cochange proximity to the primary and only the top few get a TRIMMED
+ *  (signatures + insertion region) bundle — so a 2-module task no longer pays for two full
+ *  bundles. The leading header line lets the rig record tier/topup telemetry. */
+async function runDigest(args) {
+  const repoPath = args.repo_path;
+  if (!repoPath) { process.stderr.write("tmct: digest requires repo_path\n"); process.exit(2); }
+  let modules = Array.isArray(args.modules) ? args.modules.slice(0, DIGEST_MODULE_CAP) : [];
+  let autoSelected = null; // for the header, when `query` drove selection
+  if (!modules.length && args.query) {
+    const graph = parseEntities(await source.fetchEntities(configFor(repoPath)));
+    // SHIPPED DEFAULT (0.5.0): the digest's query-mode auto-locate resolves literal-mention ON
+    // (a fresh invocation with no tmct.toml), disable-able via `literal_mention:false`. Kept in
+    // lockstep with the `tmct_locate` handler so `cli digest '{query}'` ≡ `cli tmct_locate` for the
+    // same query. A strict no-op unless the query carries a ≥3-component dotted path / repo-relative
+    // path; searchModulesRanked derives rawQuery from the query when literalMention is on.
+    const ranked = searchModulesRanked(graph, args.query, { literalMention: args.literal_mention !== false });
+    const scoreGapK = args.score_gap === false ? null : (Number.isFinite(args.score_gap) ? args.score_gap : DEFAULT_SCORE_GAP);
+    modules = selectRankedModules(ranked, { top_k: Number.isFinite(args.top_k) ? args.top_k : 2, scoreGapK }).slice(0, DIGEST_MODULE_CAP);
+    autoSelected = modules;
+    if (!modules.length) process.stderr.write(`tmct: digest query "${args.query}" matched no modules — empty digest\n`);
+  }
+  // Tuning-flag contract (threaded to buildContextBundle → sizeBundle): `min` → leanest TINY/no
+  // top-up; `untuned` → the earlier escalation. Neither → the tuned default. The digest header still
+  // reports the EFFECTIVE tier/topup returned per module, so rig telemetry stays correct.
+  const min = Boolean(args.min);
+  const untuned = Boolean(args.untuned);
+  // tmct-max: the injection CEILING — every requested module gets a FULL (untrimmed) bundle,
+  // not just the primary + 2 trimmed secondaries. Tests whether maximal injection re-bloats.
+  const max = Boolean(args.max);
+  const secondaryCap = max ? modules.length : DIGEST_SECONDARY_CAP;
+  const config = configFor(repoPath);
+  const body = [];
+  let effTier = "NONE"; // largest tier emitted across all modules
+  let topup = false;    // whether any module's auto-sizing escalated above TINY
+  let emitted = 0;      // module bundles actually emitted (primary + trimmed secondaries)
+
+  try {
+    body.push("# Repository architecture\n" + (await dispatchTool("tmct_architecture", {}, { config })));
+  } catch (e) {
+    body.push(`# Repository architecture\n(unavailable: ${e?.message || e})`);
+  }
+
+  const emit = async (m, trim) => {
+    try {
+      const { text, tier, topup: t } = await buildContextBundle({ symbol: m, min, untuned, max }, { config, source, trim });
+      body.push(`\n# Context bundle: ${m}${trim ? " (secondary, trimmed)" : ""}\n` + text);
+      if ((TIER_RANK[tier] || 0) > (TIER_RANK[effTier] || 0)) effTier = tier;
+      if (t) topup = true;
+      emitted += 1;
+    } catch (e) {
+      body.push(`\n# Context bundle: ${m}\n(no bundle: ${e?.message || e})`);
+    }
+  };
+
+  if (modules.length) {
+    const [primary, ...rest] = modules;
+    // rank the secondaries by proximity to the primary (best-effort: keep input order on error)
+    let ranked = rest;
+    if (rest.length) {
+      try { ranked = rankModulesByProximity(parseEntities(await source.fetchEntities(config)), primary, rest); }
+      catch { ranked = rest; }
+    }
+    const secondaries = ranked.slice(0, secondaryCap);
+    const overflow = ranked.slice(secondaryCap);
+    await emit(primary, false);
+    for (const m of secondaries) await emit(m, max ? false : true);
+    if (overflow.length) body.push(`\n# Related modules (not expanded; query tmct_context if needed): ${overflow.join(", ")}`);
+  }
+
+  // HARD CONTRACT: first line is the machine-readable digest header the rig greps. Fields are
+  // append-only — `selected=` is new (query mode only) and never changes the existing ones the
+  // rig's own parser depends on.
+  const header = `# tmct-digest tier=${effTier} topup=${topup} modules=${emitted}`
+    + (autoSelected ? ` selected=${autoSelected.join(",") || "(none)"}` : "");
+  process.stdout.write([header, ...body].join("\n") + "\n");
+}
+
+async function main() {
+  const [mode, sub, payload] = process.argv.slice(2);
+
+  if (mode === "cli") {
+    // digest mode: architecture map + per-module context bundles → stdout
+    if (sub === "digest") {
+      const args = parsePayload(payload);
+      if (args === null) {
+        process.stderr.write("tmct: digest expects a JSON arg, e.g. '{\"repo_path\":\"/abs\",\"modules\":[…]}'\n");
+        process.exit(2);
+      }
+      await runDigest(args);
+      return;
+    }
+
+    // locate mode (TUNING #3): `cli tmct_locate '{"query":"…","repo_path":"<abs>"}'` emits the
+    // ranked modules as `<relpath>\t<score>`, one per line (highest first), using renderSearch's
+    // exact ranking. The rig keeps rank-1 always and rank-2 only when score2/score1 is close — it
+    // needs the raw scores, which the text renderer hides. Independent of the tuning flags.
+    if (sub === "tmct_locate") {
+      const args = parsePayload(payload);
+      if (args === null) {
+        process.stderr.write("tmct: tmct_locate expects a JSON arg, e.g. '{\"query\":\"…\",\"repo_path\":\"/abs\"}'\n");
+        process.exit(2);
+      }
+      const config = configFor(args.repo_path);
+      try {
+        const graph = parseEntities(await source.fetchEntities(config));
+        // B016 recall-lever flags (LOCATE-phase, per-arm; output byte-identical when absent).
+        const ranked = searchModulesRanked(graph, args.query || "", {
+          demoteNonProd: !!args.demote_nonprod, // R1a: demote examples//fixtures//test-* paths
+          callAdjacency: !!args.call_adjacency, // E1a: resolved-call adjacency bonus
+          implOfInterface: !!args.impl_of_interface, // E1b: C# impl-of-interface boost
+          beamSearch: !!args.beam_search, // §5.15: multi-ply discriminative expansion
+          ...(Number.isFinite(Number(args.beam_width)) ? { beamWidth: Number(args.beam_width) } : {}),
+          // B018 §8.1.3 literal-mention lever: match verbatim dotted-name/path mentions in the RAW
+          // query (which the locate tokenizer destroys). searchModulesRanked derives rawQuery from the
+          // query arg when literalMention is on; the rig passes the raw problem as the query, so literal
+          // matching keys off the untokenized text. raw_query is forwarded too for callers that normalize
+          // the query arg separately from the raw problem text.
+          // SHIPPED DEFAULT (0.5.0): literal-mention is ON for a fresh invocation (no arg, no
+          // tmct.toml) — pass `literal_mention:false` to disable. It is a strict no-op on queries
+          // with no ≥3-component dotted path / repo-relative path, so it never perturbs the cells the
+          // headline B018 numbers were measured on. The low-level scoreModules default (codegraph.mjs)
+          // stays literalMention=false; the product surface opts in explicitly, right here.
+          literalMention: args.literal_mention !== false,
+          ...(args.raw_query != null ? { rawQuery: String(args.raw_query) } : {}),
+        });
+        process.stdout.write(ranked.map((r) => `${r.path}\t${r.score}`).join("\n") + "\n");
+      } catch (e) {
+        process.stderr.write(`tmct: ${e?.message || e}\n`);
+        process.exit(1);
+      }
+      return;
+    }
+
+    // tool-query fallback: any other `cli <toolName> '{…}'` routes to dispatchTool,
+    // so "cold" tools are invokable from Bash directly.
+    if (sub) {
+      const args = parsePayload(payload);
+      if (args === null) {
+        process.stderr.write(`tmct: ${sub} expects a JSON arg, e.g. '{"symbol":"<name>"}'\n`);
+        process.exit(2);
+      }
+      const config = configFor(args.repo_path);
+      try {
+        const text = await dispatchTool(sub, args, { config });
+        process.stdout.write(text + "\n");
+      } catch (e) {
+        process.stderr.write(`tmct: ${e?.message || e}\n`);
+        process.exit(1);
+      }
+      return;
+    }
+
+    process.stderr.write("tmct: `cli` needs a sub-command (digest | <toolName>)\n");
+    process.exit(2);
+  }
+
+  if (mode === "chat") {
+    const { runChat } = await import("../src/chat.mjs");
+    const i = process.argv.indexOf("--repo");
+    await runChat({
+      repoPath: i !== -1 ? process.argv[i + 1] : undefined,
+    });
+    return;
+  }
+
+  // Bare invocation: no server to start any more — print the usage line and exit 2.
+  // (bin/tmct.mjs splices in `chat` for bare invocations, so nothing user-facing is lost.)
+  process.stderr.write(`tmct: ${mode === undefined ? "missing mode" : `unknown invocation "${process.argv.slice(2).join(" ")}"`}. ` +
+    "Use `cli digest …`, `cli <tool> …`, or `chat`.\n");
+  process.exit(2);
+}
+
+main().catch((e) => {
+  process.stderr.write(`tmct: ${e?.message || e}\n`);
+  process.exit(1);
+});

package/bin/tmct.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+// tmct — The Mechanical Code Talker. The headline entry is CHAT: a bare
+// invocation drops you into a tolerant, offline, $0 prompt that guides you
+// toward precision queries about a repository (ELIZA/PARRY-style, but obsessed
+// with software). No model calls; tmct keeps no codebase index of its own.
+//
+//   tmct                                   → interactive chat (the headline)
+//   tmct chat [--repo <abs>]               → same, explicit
+//   tmct cli <tool> '{…json}'              → invoke a graph tool directly (de-emphasized carry-over)
+//   tmct --help                            → this help
+//
+// tmct began as a whole-package lift of an earlier chat surface (see README
+// provenance): internal module filenames and symbols were kept to preserve the
+// shape and the green test suite. The non-chat modes are carried but
+// de-emphasized — see README.md for what tmct is and deliberately is NOT, and
+// ROADMAP.md for where it is going.
+
+const HELP = `tmct — The Mechanical Code Talker
+
+A tolerant, offline, $0 chat that guides you toward precision queries about a
+software repository. No model calls; no codebase index of its own.
+
+Usage:
+  tmct                         interactive chat (the headline surface)
+  tmct chat [--repo <abs>]     chat over a specific repo's graph
+  tmct cli <tool> '{…}'        invoke a graph tool directly (carry-over, de-emphasized)
+  tmct --help                  show this help
+
+In chat: /help lists slash-commands; /exit leaves. Session log → <repo>/.tmct/session-<id>.log.
+`;
+
+const args = process.argv.slice(2);
+
+if (args[0] === "--help" || args[0] === "-h" || args[0] === "help") {
+  process.stdout.write(HELP);
+  process.exit(0);
+}
+
+// Headline behaviour: a bare invocation is CHAT. We rewrite argv so the carried
+// dispatcher (bin/cli.mjs, kept verbatim for the test suite) sees `chat`, then
+// hand off to it. Any explicit mode passes straight through unchanged.
+if (args.length === 0) {
+  process.argv.splice(2, 0, "chat");
+}
+
+// Delegate to the carried dispatcher. It runs its own main() on import.
+await import("./cli.mjs");

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@polycode-projects/the-mechanical-code-talker",
+  "version": "0.2.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.",
+  "license": "MPL-2.0",
+  "author": "Polycode Limited",
+  "homepage": "https://polycode-projects.gitlab.io/the-mechanical-code-talker/",
+  "engines": {
+    "node": ">=24"
+  },
+  "bin": {
+    "tmct": "./bin/tmct.mjs"
+  },
+  "main": "./src/index.mjs",
+  "exports": {
+    ".": "./src/index.mjs",
+    "./chat": "./src/chat.mjs",
+    "./resolveObject": "./src/ask.mjs",
+    "./ask": "./src/ask.mjs",
+    "./relationKind": "./src/codegraph.mjs",
+    "./impactClosure": "./src/codegraph.mjs",
+    "./dispatchTool": "./src/server.mjs",
+    "./fetchEntities": "./src/source.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "ROADMAP.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "smol-toml": "^1.7.0",
+    "wink-eng-lite-web-model": "^1.8.1",
+    "wink-nlp": "^2.4.0"
+  },
+  "scripts": {
+    "test": "node --test \"test/**/*.test.mjs\"",
+    "chat": "node bin/tmct.mjs"
+  }
+}

package/src/ask-nlp.mjs

@@ -0,0 +1,73 @@
+// ask-nlp.mjs — the OPTIONAL wink-nlp adapter behind ask.mjs's lemma/POS tier.
+//
+// BOUNDARY (hard, do not move): this file is Node-only and is NEVER inlined into
+// the viewer bundle. viz.mjs's askSource() inlines codegraph.mjs + ask-vocab.mjs +
+// ask.mjs ONLY and strips their import lines, so the portable single-file HTML has
+// no wink, no model, and no `nlpAdapter` binding at all — ask.mjs reaches this
+// module exclusively through a `typeof nlpAdapter === "function"` guard and
+// degrades to adapter-less parsing (lemma/POS tiers off; the curated tables and
+// the bounded edit-distance tier still work, browser and Node alike). Keeping the
+// ~1MB CJS model out of the page is the point of the split.
+//
+// wink-nlp and wink-eng-lite-web-model are CJS — loaded via createRequire, the
+// same Node-module-resolution approach viz.mjs uses to locate cytoscape (resolve
+// through the module system, never a guessed path). The require happens lazily on
+// first use and failure is cached as null: a checkout without the optional deps
+// installed answers exactly like the browser bundle, it never throws.
+
+import { createRequire } from "node:module";
+
+let cached; // undefined = not tried yet; null = unavailable (tried once, honestly off)
+
+/** Lazily build the {lemma, posTags} adapter, or null when wink isn't loadable.
+ *  Deterministic: wink-nlp's tagger/lemmatiser is a fixed model with no sampling,
+ *  so the same input always yields the same tags/lemmas across processes. */
+export function nlpAdapter() {
+  if (cached !== undefined) return cached;
+  try {
+    const require = createRequire(import.meta.url);
+    const winkNLP = require("wink-nlp");
+    const model = require("wink-eng-lite-web-model");
+    const nlp = winkNLP(model);
+    const its = nlp.its;
+    cached = {
+      /** Lowercase lemma of a single token ("imported" -> "import"); the word
+       *  itself when wink has nothing better (unknown words come back as-is). */
+      lemma(word) {
+        const w = String(word || "");
+        try {
+          const out = nlp.readDoc(w).tokens().out(its.lemma);
+          return String(out[0] || w).toLowerCase();
+        } catch {
+          return w.toLowerCase();
+        }
+      },
+      /** UPOS tags aligned to the CALLER's word array. wink re-tokenizes (it
+       *  splits "walk.mjs" into three tokens), so each input word is greedily
+       *  matched to the run of wink tokens that spell it and takes its FIRST
+       *  sub-token's tag; null per word on any surprise, never a throw. */
+      posTags(words) {
+        try {
+          const toks = nlp.readDoc(words.join(" ")).tokens();
+          const texts = toks.out();
+          const tags = toks.out(its.pos);
+          const out = [];
+          let k = 0;
+          for (const w of words) {
+            if (k >= texts.length) { out.push(null); continue; }
+            out.push(tags[k]);
+            let acc = texts[k];
+            k += 1;
+            while (acc.length < w.length && k < texts.length) { acc += texts[k]; k += 1; }
+          }
+          return out;
+        } catch {
+          return words.map(() => null);
+        }
+      },
+    };
+  } catch {
+    cached = null;
+  }
+  return cached;
+}