@polycode-projects/the-mechanical-code-talker 1.12.0 → 2.0.2

package/README.md

@@ -56,7 +56,7 @@ the answers below, plus cleanup — see the file for the full script.)
 
 Output, captured from an actual run:
 
-```
+```output cmd="node examples/teach-and-infer.mjs" cwd=repo
 tmct> ahab is the father of john
 noted — remembered: ahab fathers john
 
@@ -99,10 +99,11 @@ alias, and the ahab-is-male property, then cited all four. The `source: …`
 parts are real provenance receipts. Every fact tmct stores records where it
 came from and when (more on that below).
 
-`test/examples-teach-and-infer.test.mjs` pins this exact output. If the
-underlying chat behavior ever drifts, that test fails and says so.
+The test suite replays every runnable example in this README against the
+live product, this transcript included. If the chat behavior ever drifts
+from the output above, the suite fails and says so.
 
-```
+```session
 $ tmct
 tmct> what talks to the payment module?
 …
@@ -118,13 +119,24 @@ The page leads with the **memory ledger**: every fact as a readable sentence,
 drill by clicking the terms inside them, and an in-page chat whose answers
 focus the ledger.
 
+From a clone, two build scripts regenerate that demo so you can check it
+offline before it deploys. The example graph, the ledger page, and the
+engine copy land in `public/`. The in-page chat's query bundle is rebuilt
+from the same `src/` the CLI runs:
+
+```bash e2e cwd=repo
+npm run demo:build        # public/: demo graph, memory, ledger page, engine copy
+npm run build:ask-bundle  # the browser query bundle the in-page chat runs
+```
+
 Two more surfaces, both generated by tmct itself:
 
-```bash
+```bash e2e
 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
+npx tmct viz --focus disk-1 --output disks.html   # the explorer again, focused on one term
 npx tmct chat --prompt 'disk-1 rests on disk-2. disk-2 rests on disk-3.
   disk-3 rests on peg-a. the goal is that every disk rests on peg-c. solve it.' \
   --render blocks --output plan.html  # an animated replay of the solved plan
@@ -216,21 +228,19 @@ handful of connector words, like "defined in", "located in", or "found in".
 The same fact doesn't read identically for every entity, but the same
 question against the same entity always renders the same way.
 
-```
+```session cwd=repo
 $ node bin/tmct.mjs chat --repo examples/mini-webapp --ephemeral
 tmct> give me a detailed overview of how the Store works
-Attribute: prose_tokens = memory record store [mgx:hasProseTokens]. Attribute:
-doc = In-memory record store. [seon:hasDoc]. Other matches: src/core/store.mjs
-(Module), loadStore (Function), saveStore (Function), testLoadStore (Function).
+Attribute: prose_tokens = memory record store [mgx:hasProseTokens]. Attribute: doc = In-memory record store. [seon:hasDoc]. Other matches: src/core/store.mjs (Module), loadStore (Function), saveStore (Function), testLoadStore (Function).
 ```
 
 Programmatically, the same pipeline is `generateCompletion()`
-(`src/completions/complete.mjs`):
+(`src/domain/completions/complete.mjs`):
 
-```js
-import { fetchEntities } from "./src/source.mjs";
-import { parseEntities } from "./src/codegraph.mjs";
-import { loadMemory } from "./src/memory/core.mjs";
+```js cwd=repo
+import { fetchEntities } from "./src/adapters/source.mjs";
+import { parseEntities } from "./src/domain/codegraph.mjs";
+import { loadMemory } from "./src/adapters/memory/core.mjs";
 import { createCompletionsGraphAdapter } from "@polycode-projects/the-mechanical-code-talker/createCompletionsGraphAdapter";
 import { generateCompletion } from "@polycode-projects/the-mechanical-code-talker/generateCompletion";
 
@@ -243,13 +253,11 @@ const { text } = await generateCompletion(dir, "Store", { query: "Store", graph,
 console.log(text);   // prints the same text as the chat answer above
 ```
 
-Full pipeline design in `archive/PLAN_COMPLETIONS.md`.
-
 ## Planning across the graph
 
 Some questions need more than one lookup. `tmct plan` is a small STRIPS/PDDL-style
 planner over the same read-only graph-query tools chat/serve use
-(`src/router/*`): it decomposes a compound request, resolves and executes each
+(`src/domain/router/*`): it decomposes a compound request, resolves and executes each
 step in order with a provable causal-link proof chain, and folds the results
 into one answer. A request neither the planner nor a single lookup can ground
 escalates to a closed-world goal-reasoner, which deduces maintenance goals
@@ -257,7 +265,7 @@ escalates to a closed-world goal-reasoner, which deduces maintenance goals
 keywords in your question. Anything none of that grounds is an honest "no plan
 found", the same "grounded or an honest miss" rule as everywhere else in tmct.
 
-```
+```session cwd=repo
 $ node bin/tmct.mjs plan "of the modules impacted by src/lib/http.mjs, which are untested" --repo examples/mini-webapp
 tmct plan: "of the modules impacted by src/lib/http.mjs, which are untested"
 driver: resolver-0.8.0
@@ -294,7 +302,7 @@ you'd have to cross-reference by hand.
 Leave the entity out and ask a maintenance question instead, and the goal-reasoner
 picks up where the planner refuses:
 
-```
+```session cwd=repo
 $ node bin/tmct.mjs plan "what most needs a test in this codebase" --repo examples/mini-webapp
 tmct plan: "what most needs a test in this codebase"
 driver: goal-0.8.1
@@ -325,9 +333,8 @@ and refusing (exit 1) if any sentence declines.
 Then one message states the board and the goal, and "solve it" searches the
 taught rules for the shortest move sequence:
 
-```
-tmct> disk-1 rests on disk-2. disk-2 rests on disk-3. disk-3 rests on peg-a.
-      the goal is that every disk rests on peg-c. solve it.
+```session e2e setup="npx tmct init && npx tmct import --file .tmct/imports/games/hanoi-3.txt" cmd="npx tmct chat"
+tmct> disk-1 rests on disk-2. disk-2 rests on disk-3. disk-3 rests on peg-a. the goal is that every disk rests on peg-c. solve it.
 plan found — 7 moves (shortest):
   1. move disk-1 onto peg-c
   2. move disk-2 onto peg-b
@@ -375,7 +382,7 @@ the shipped `npm run example:*` demos) reads a graph but writes nothing back.
 The default persona also comes in three sizes: Small (~664 facts, the
 default), Medium (~1,608, `tmct init --persona-size medium`) and Large
 (~13,609, `--persona-size large`, deep enough to chain real multi-hop
-reasoning). Design detail and the full fact-count tables are in `archive/PLAN_SEED.md`.
+reasoning).
 
 ### Memory backends
 
@@ -388,6 +395,15 @@ Precedence is `--memory-backend` flag > `TMCT_MEMORY_BACKEND` env >
 tmct.toml's `[memory] backend` > the default. A library caller sets the same
 thing directly: `runChat({ memoryBackend: "sqlite" })`.
 
+Three init presets in `package.json` wrap the common setups. What each one
+runs (`--force` re-initializes the same directory):
+
+```bash
+npx tmct init --memory-backend sqlite        # npm run init:sqlite
+npx tmct init --force --with-persona human   # npm run init:persona:human — the default persona, made explicit
+npx tmct init --force --with-persona empty   # npm run init:persona:empty — no seeded vocabulary at all
+```
+
 Teaching isn't limited to the ACE grammar's fixed shapes. Tell tmct an
 arbitrary fact, like "margo really eats ribs", and it mints a fact you can
 ask about directly: "what does margo eat". New vocabulary compounds as you
@@ -398,6 +414,25 @@ nudges you to ground one side first. Quantified teaching stores the
 quantifier ("some functions are risky" … "how many functions are risky" →
 "A few."), and "how many facts are there" counts the store back.
 
+Teaching doesn't have to be typed, either. `npm run extract:facts` (from a
+clone) runs a plain text file through the same recognizer the chat's teach
+lane uses. Sentences the recognizer grounds become fact rows; everything
+else is skipped and counted, never paraphrased:
+
+```bash cwd=repo
+printf 'We deployed redis last week. a cache is a kind of store. Why was it slow?\n' > /tmp/notes.txt
+node scripts/extract-facts-from-text.mjs /tmp/notes.txt
+```
+
+```output
+{"subject":"cache","predicate":"rdfs:subClassOf","object":"store","provenance":"extracted:notes.txt","quantifier":"","sentence":"a cache is a kind of store."}
+3 sentences found, 1 recognized as fact (1 fact row), 2 skipped — not a recognized declarative shape (an honest, expected gap; this is an attempt, not full NLU).
+```
+
+Pass `--repo <path>` instead to write the recognized facts straight into
+that repo's memory, or `--out <file.jsonl>` to save the rows. Each one
+carries an `extracted:<file>` provenance tag at its own trust tier.
+
 ### Provenance and trust
 
 Every fact and text block records **where it came from and when**. Sources are
@@ -421,7 +456,7 @@ stated fact, and this never runs on the chat's hot path.
 
 ## Install & use
 
-```bash
+```bash skip=network
 npm install -g @polycode-projects/the-mechanical-code-talker
 tmct                                  # bare = chat (the headline)
 tmct chat --repo /abs/path/to/repo    # chat over a specific repo's graph
@@ -452,17 +487,17 @@ package or a bare user gets a working install in one command.
 same output, split into one block per command with a short note on what each
 one is for, so it is easier to scan than the raw dump.
 
-Every subcommand shares one flag/config resolver (`src/cli-args.mjs`), which
+Every subcommand shares one flag/config resolver (`src/services/cli-args.mjs`), which
 is why `--repo`, `--graph`, and `--config` behave the same way everywhere.
 
 The bare command and `tmct chat` open the interactive session:
 
-```
+```output:help:chat
 Usage:
   tmct                         interactive chat (the headline surface)
   tmct chat [--repo <abs>]     chat over a specific repo's graph
        [--graph <path>]        explicit graph file (repeatable — multiple graphs merge;
-                               see src/graph-merge.mjs); wins over --repo/TMCT_GRAPH_FILE/tmct.toml
+                               see src/adapters/graph-merge.mjs); wins over --repo/TMCT_GRAPH_FILE/tmct.toml
        [--config <path>]       an alternate tmct.toml location (a file or a directory)
        [--ephemeral]           read the graph but write nothing back (demo/read-only)
        [--prompt "<text>"]     one-shot: run the prompt's sentences as turns and print
@@ -483,7 +518,7 @@ Usage:
 
 `tmct memory` is the CLI-side view of the same data the `/memory` chat command shows:
 
-```
+```output:help:memory
   tmct memory [--repo <abs>]   what tmct remembers: facts, utterances, sessions,
        [--config <path>]       folded blocks (the /memory chat command, from the shell)
        [--verbose]
@@ -492,9 +527,10 @@ Usage:
 `tmct init` sets up a repo for the first time: `.tmct/`, `tmct.toml`, a seed, and a
 provenance record. Most of its flags choose what gets seeded and where config is written:
 
-```
+```output:help:init
   tmct init [--repo <abs>]     initialize a repo for tmct (default: cwd): .tmct/,
-       [--force]               tmct.toml, tier-1 corpus seed, provenance record
+       [--force]               tmct.toml, .tmct/TOOLS.md (the cold-tool catalog),
+                               tier-1 corpus seed, provenance record
        [--corpus <id|path>]    also seed a corpus — a tier-2 manifest id (aws|python|java|
                                general) or a jsonl file path — opt-in, offline, $0
        [--ontology <name|path>]  activate+seed an ontology bundle (a recognized name or a path)
@@ -521,7 +557,7 @@ provenance record. Most of its flags choose what gets seeded and where config is
 already set up. Its `--graph` flag works differently from the others: it appends to
 `tmct.toml`'s `graph_files` array instead of activating a bundle.
 
-```
+```output:help:import
   tmct import [--repo <abs>]   activate+seed into an ALREADY-initialized repo (any
        [--corpus <id|path>]    combination of these flags in one call). --graph is a
        [--ontology <name|path>]  DIFFERENT operation from the others: it APPENDS to
@@ -537,7 +573,7 @@ already set up. Its `--graph` flag works differently from the others: it appends
 `tmct extend --validate` checks a third-party extension pack's declared resources
 before you switch any repo's `tmct.toml` over to it:
 
-```
+```output:help:extend
   tmct extend --validate <dir>  validate a third-party extension pack's declared
        [--config <path>]      resources (corpus/lexicon/templates) before activating
                                it in any repo's tmct.toml; exits non-zero on failure
@@ -546,7 +582,7 @@ before you switch any repo's `tmct.toml` over to it:
 `tmct syllogise` is the offline maintenance job described under "Speculative
 inference" above:
 
-```
+```output:help:syllogise
   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)
@@ -555,7 +591,7 @@ inference" above:
 `tmct viz` renders the memory graph as the ledger explorer — a single,
 self-contained HTML file you can open in a browser:
 
-```
+```output:help:viz
   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
@@ -569,28 +605,57 @@ self-contained HTML file you can open in a browser:
 `tmct serve` runs an Anthropic Messages API-compatible HTTP endpoint over the graph,
 so a tool-loop client can call tmct like a model, at $0:
 
-```
+```output:help:serve
   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.
        [--config <path>]       Defaults: host 127.0.0.1, port 8787. Ctrl+C to stop.
 ```
 
-`tmct cli` is a lower-level, carry-over surface for invoking a graph tool directly:
+A tool-loop client talks to it like any Messages endpoint. One round trip
+against the example graph, end to end:
 
+```bash e2e cwd=repo
+node bin/tmct.mjs serve --repo examples/mini-webapp --port 8791 &
+SERVE_PID=$!
+until curl -s -o /dev/null http://127.0.0.1:8791/v1/messages; do sleep 0.2; done
+curl -s http://127.0.0.1:8791/v1/messages -H 'content-type: application/json' \
+  -d '{"model":"tmct","max_tokens":256,"messages":[{"role":"user","content":"which modules import src/core/model.mjs?"}]}'
+kill $SERVE_PID
 ```
+
+`tmct plan` is the capability router described under "Planning across the graph" above:
+
+```output:help:plan
+  tmct plan "<request>"        the capability router: compose/execute read-only graph-
+       [--repo <abs>]          query tool calls for a compound or maintenance-goal
+       [--graph <path>]        request ("of the modules impacted by X, which are
+       [--config <path>]       untested", "what most needs a test") — a real STRIPS/
+       [--tools <a,b,...>]     PDDL planner (src/domain/router/*), never a guessed call.
+       [--json]                Prints the grounded step sequence + composed answer,
+                               or an honest "no plan found". --tools restricts the
+                               declared toolset; --json prints the full loop result.
+```
+
+`tmct cli` is a lower-level, carry-over surface for invoking a graph tool directly:
+
+```output:help:cli
   tmct cli <tool> '{…}'        invoke a graph tool directly (carry-over, de-emphasized)
+       [--repo <abs>]          the repo to answer from; the payload's "repo_path" says
+       [--graph <path>]        the same thing. --graph names the graph file outright
+       [--config <path>]       (repeatable), --config an alternate tmct.toml
   tmct cli digest '{…}'        architecture map + per-module context bundles
 ```
 
 Two precedence chains apply across every command above, in this order:
 
-```
-Shared graph-path precedence (chat/serve; see src/cli-args.mjs): --graph flag(s) >
+```output:help:precedence
+Shared graph-path precedence (chat/serve/cli; see src/services/cli-args.mjs): --graph flag(s) >
 TMCT_GRAPH_FILE env > tmct.toml graph_file/graph_files > --repo-derived
-<repo>/.tmct/graph.json > git-root/cwd default.
+<repo>/.tmct/graph.json > git-root/cwd default. On the `cli` route, a payload's
+"repo_path" fills the --repo tier when the flag is absent.
 
-Memory-backend precedence (chat; see src/chat.mjs createSession): --memory-backend
+Memory-backend precedence (chat; see src/services/chat.mjs createSession): --memory-backend
 flag > TMCT_MEMORY_BACKEND env > tmct.toml [memory] backend > "default" (the flat
 .tmct/ JSON file). Set it once with `tmct init --memory-backend <...>` and every
 later `tmct chat` in that repo picks it up with no flag needed.
@@ -599,14 +664,27 @@ later `tmct chat` in that repo picks it up with no flag needed.
 `npm run init:large` in `package.json` chains one `init` and five `import --corpus`
 calls to combine every shipped bundle (human persona + seon + conceptnet +
 aws/python/java) into ~7,380 facts on the default flat-JSON backend, a working
-example to copy from.
+example to copy from. `init:xl` starts from the large persona tier and adds
+the wordnet-xl corpus (~72,000 facts); `init:xxl` swaps wordnet-xl for the
+full WordNet slice plus namenet (~239,000 facts, the biggest committed
+vocabulary — expect its imports to take a minute). The xl chain, spelled out:
+
+```bash e2e
+npx tmct init --persona-size large   # npm run init:xl runs this whole chain from a clone
+npx tmct import --corpus seon
+npx tmct import --corpus conceptnet
+npx tmct import --corpus aws
+npx tmct import --corpus python
+npx tmct import --corpus java
+npx tmct import --corpus wordnet-xl  # init:xxl instead ends with wordnet-full and namenet
+```
 
 ### tmct.toml reference
 
 `tmct init` writes a sparse `tmct.toml` with just the keys it needs. The file
 recognizes more keys than that default covers. Below is one config with every
 recognized key set, so you can see the full surface in one place
-(`src/toml-config.mjs` is the source of truth; `src/extensions.mjs` defines the
+(`src/adapters/toml-config.mjs` is the source of truth; `src/services/extensions.mjs` defines the
 `[extensions.*]`/`[bias]` shape).
 
 ```toml
@@ -655,7 +733,7 @@ templates_path = "./vendor/my-pack/templates"
 phrasebook_path = "./vendor/my-pack/phrasebook.json"
 provenance_prefix = "corpus:my-custom-pack"
 
-# Flat bundle-name -> weight table, consumed by src/memory/bias.mjs's ranking.
+# Flat bundle-name -> weight table, consumed by src/domain/memory/bias.mjs's ranking.
 [bias]
 human = 1.0
 seon = 0.8
@@ -706,15 +784,15 @@ one. Two ready-made example graphs live in `examples/` in this repo (clone the
 repo to use them; they are not in the published npm package), so you can see
 it answer real questions with no setup:
 
-```bash
+```bash cwd=repo
 npm run example:mini       # "Questboard" — a small task-tracker web app (12 modules)
 npm run example:polyglot   # one shared OWL vocabulary across Java / Python / C#
-npm run chat:repo -- ./any/path   # chat over any repo that has a .tmct/graph.json
+npm run chat:repo -- examples/mini-webapp   # any repo with a .tmct/graph.json works here
 ```
 
 Questions the **mini-webapp** graph answers:
 
-```
+```text
 what classes are there
 describe Task
 how many modules
@@ -726,7 +804,7 @@ The **polyglot** graph shows the language-neutral idea: Java, Python and C#
 entities all typed to the same `seon:Class` / `seon:Method` / `seon:Module`
 concepts, so one query reasons across every language at once:
 
-```
+```text
 how many classes          # 9 — Java + Python + C# counted as one concept
 what classes are there     # Order (Java), Inventory (Python), PaymentService (C#), …
 which modules define PaymentService
@@ -759,6 +837,90 @@ loads a repo's graph into a `{ dispatch, resolve, graph }` context,
 `declaredCapabilityNames()` lists every capability a caller can declare. See
 "Planning across the graph" above.
 
+<!-- generated by scripts/generate-tool-docs.mjs from src/tools/definitions.mjs — do not edit by hand -->
+
+## The tool surface
+
+Everything above runs on the same 22 tools. Each one is read-only, answers one question in a single call, and returns bounded output. None of them calls a model. A tool that cannot ground an answer says so — the same honest miss you get everywhere else in tmct.
+
+Three of them are **hot**: their schemas stay resident, so an agent driving tmct sees them every turn and reaches for one call instead of a Read/Grep loop.
+
+- **`tmct_context`** — A sized edit bundle for one symbol — exemplar source, sibling signatures, registration anchor and the insertion region, in one call.
+  Arguments: `symbol` (required), `depth`.
+- **`tmct_snippet`** — The exact source of one function, class or Class.method — its line span only, plus a one-line in-repo call hint.
+  Arguments: `symbol` (required).
+- **`tmct_ask`** — A structural question in plain English, answered from the graph in one call — no model, and a clean miss instead of a guess.
+  Arguments: `query` (required).
+
+### Asking in plain English
+
+`tmct_ask` is the chat-facing tool. It takes a structural question as you would type it and resolves it to a real traversal. These are the shapes it reads:
+
+| you type | it answers with |
+| --- | --- |
+| which modules import src/core/model.mjs | the imports edge, read forwards |
+| what is imported by src/core/store.mjs | the same edge, read backwards — a passive is the opposite direction, not a synonym |
+| what uses src/lib/http.mjs | the uses union: imports plus calls |
+| where is saveStore defined | the definition's file and line span |
+| when did src/core/store.mjs change | the commits that touched it, newest first |
+
+The `<where-marker>` slot takes any of *defined*, *declared*, *located*, *implemented*. The relation verb is the part that carries the meaning, and each relation has its own vocabulary rather than one blessed keyword:
+
+- **imports** — *couples to*, *couple to*, *depends on*, *imports*, and more
+- **uses** — *uses*, *use*, *makes use of*, *make use of*, and more
+- **calls** — *invokes*, *invoke*, *calls*, *call*, and more
+- **defines** — *defines*, *define*, *declares*, *declare*, and more
+- **contains** — *contains*, *contain*, *lives in*, *live in*, and more
+- **tests** — *tests*, *test*, *covers*, *cover*, and more
+- **inherits** — *inherits from*, *inherit from*, *inherits*, *inherit*, and more
+- **touches** — *touched*, *touches*, *changed*, *change*, and more
+- **cochange** — *changed with*, *co-changes with*, *co-change with*, *changes alongside*, and more
+- **reexports** — *exports*, *export*, *re-exports*, *re-export*, and more
+
+Every question in that table runs against the example graph:
+
+```bash cwd=repo
+node bin/tmct.mjs cli tmct_ask '{"query":"which modules import src/core/model.mjs","repo_path":"examples/mini-webapp"}'
+node bin/tmct.mjs cli tmct_ask '{"query":"what is imported by src/core/store.mjs","repo_path":"examples/mini-webapp"}'
+node bin/tmct.mjs cli tmct_ask '{"query":"what uses src/lib/http.mjs","repo_path":"examples/mini-webapp"}'
+node bin/tmct.mjs cli tmct_ask '{"query":"where is saveStore defined","repo_path":"examples/mini-webapp"}'
+node bin/tmct.mjs cli tmct_ask '{"query":"when did src/core/store.mjs change","repo_path":"examples/mini-webapp"}'
+```
+
+### The rest of the tools
+
+The remaining tools are **cold**: still served, but not billed to an agent every turn. Reach one through `tmct cli <tool>`, passing its arguments as JSON:
+
+| tool | what it answers | arguments |
+| --- | --- | --- |
+| `tmct_describe` | Locate one symbol and list its typed edges (both directions) with provenance. | `symbol` (required) |
+| `tmct_signature` | One symbol's API surface (params, returns, raises/catches, flags, decorators, doc) without the body. | `symbol` (required) |
+| `tmct_impact` | Transitive reverse closure over imports/calls — what breaks if a module changes, by depth, with tests. | `module` (required) |
+| `tmct_search` | Free-text/ranked lookup over the code-map to find the right module or symbol. | `query`, `kind`, `decorator`, `name` |
+| `tmct_members` | A class's methods + attributes (file:line, decorators) in one slice. | `class` (required) |
+| `tmct_subclasses` | A class's base classes plus the transitive set of classes that extend it. | `class` (required) |
+| `tmct_architecture` | Package/module map + the most-imported hub modules (optionally scoped to a package). | `package` |
+| `tmct_exports` | A module's public __all__ surface, each name resolved to the module that defines it. | `module` (required) |
+| `tmct_tests_for` | The test modules covering a symbol or module, from the typed test edges. | `symbol` (required) |
+| `tmct_untested` | Source modules with no covering test module — a coverage-gap view (no arguments). | none |
+| `tmct_history` | Recent commits that touched a symbol's module (newest first). | `symbol` (required) |
+| `tmct_file_history` | Commits that touched a symbol's module, each with author / date / subject. | `symbol` (required) |
+| `tmct_method_history` | Commits that touched a specific method symbol (fine-grained), with author / date / subject. | `symbol` (required) |
+| `tmct_class_history` | Commits that touched a specific class symbol (fine-grained), with author / date / subject. | `symbol` (required) |
+| `tmct_callers` | Modules that call into a symbol's module (one hop). | `symbol` (required) |
+| `tmct_callees` | Modules a symbol's module calls into (one hop). | `symbol` (required) |
+| `tmct_calls` | The in-repo symbols a function calls (fn→fn), each with file:line. | `symbol` (required) |
+| `tmct_cochanges` | Modules that historically change in the same commit as a symbol's module (git co-change). | `symbol` (required) |
+| `tmct_context_more` | The bundle sections a lean tmct_context omitted (siblings / tests / cochange / class members / re-exports). | `symbol` (required) |
+
+Add `repo_path` to any of them to point at a repository other than the working directory. `tmct init` also writes this catalog, with a worked invocation per tool, to `.tmct/TOOLS.md` inside the repo it indexed.
+
+```bash cwd=repo
+node bin/tmct.mjs cli tmct_untested '{"repo_path":"examples/mini-webapp"}'
+```
+
+<!-- end generated tool section -->
+
 ## The repository interface
 
 tmct is not an indexer, so it consumes a graph through a typed contract any
@@ -775,6 +937,40 @@ original relationship: tmct was lifted out of seonix, and seonix now reorients
 as a *user* that imports the tmct library and exposes its graph to tmct as a
 service. The LLM agent stays outside tmct, as the no-LLM ethos requires.
 
+## Measuring it
+
+Three offline benchmark rigs live in a clone (they are not in the npm
+package). Each replays a committed case set through the real product and
+writes graded rows you can diff between runs:
+
+- `npm run chatbench:run` measures chat quality against CEFR-graded English
+  cases with deterministic tier-1 checks (the full tuning loop is in
+  `SKILL_BENCHMARK_CEFR_ENGLISH.md`);
+- `npm run infbench` generates inference cases, then runs each through both
+  drive points, the reasoning kernel and the chat surface;
+- `npm run agentbench:run` measures the tool-loop behaviour, and every
+  verdict carries a hallucination axis.
+
+The smallest real slice of each, the same invocations the test suite's
+bench-smoke lane replays:
+
+```bash cwd=repo
+node chatbench/run.mjs --stamp smoke --only g-a1-naming-1 --out /tmp/chatbench-smoke
+node infbench/generate-cases.mjs --out /tmp/infbench-cases.jsonl
+node infbench/run.mjs --cases /tmp/infbench-cases.jsonl --only inf-a1-lookup-subClassOf-001 --stamp smoke --out /tmp/infbench-smoke
+node agentbench/run.mjs --stamp smoke --driver stub --only ab-a0-describe-widget --out /tmp/agentbench-smoke
+```
+
+Grading beyond tier 1 uses an LLM as judge. The offline eval harness is the
+one place an LLM is allowed, never the product:
+
+```bash skip=offline-eval-only
+npm run chatbench:judge -- --product /tmp/chatbench-smoke/product.jsonl
+```
+
+The headline numbers and their conditions live in the `BENCHMARK_*.md`
+write-ups.
+
 ## Security and supply chain
 
 tmct is $0 to run and meant to be trusted offline, so the supply chain is
@@ -785,7 +981,7 @@ hardened:
 - Releases are published with **npm provenance** (`--provenance`).
 - A coordinated-disclosure `SECURITY.md` policy covers reports.
 
-The content-address hash is single-sourced in `src/hash.mjs`, so the
+The content-address hash is single-sourced in `src/domain/hash.mjs`, so the
 cross-version-stable fact-id contract has exactly one definition.
 
 ## Provenance

package/ROADMAP.md

@@ -28,41 +28,29 @@ getting silently traded away by inherited caution:
   clipping/pagination limits. L
 - **Paraphrase alongside the original, verified, never instead of it.** A surface-realization variant
   sits next to the literal grounded answer, never replacing it, and its accuracy is checked, not
-  assumed — by running tmct's own deterministic inference/consistency machinery (`src/syllogise.mjs`)
+  assumed — by running tmct's own deterministic inference/consistency machinery (`src/domain/syllogise.mjs`)
   against both the original and the paraphrase: they must entail the same conclusions, and neither may
   contradict the other sentence-by-sentence..
 
 
 ## What's next (feature-shaped — see `HANDOVER.md` for the current task-level list)
 
-- **`archive/PLAN_BREADTH_FIRST_NLU.md`'s own remaining scope** — all six tracks shipped (entity-tie
-  ambiguity, router candidate enrichment, `tmct viz` + its embedded chat panel, template-coverage
-  harness, alternates-on-hits, canonical representation for the ask/teach lanes — all now in "Current
-  capability surface" above). Two named items are satisfied and closed, per their own track's
-  original scope (an explicit operator decision, not a silent drop): (a) canonical representation
-  for every OTHER chat lane (conversational, commands, recall, ~78 `chat.mjs` return sites) —
-  Track 6's own deliverable was the `canonical` field present on every response (even `null` where
-  unpopulated), which is met; full population everywhere was always a bigger, separately-scoped
-  follow-on. (b) growing the ACE grammar's free-form coverage past its measured 0/2,949-sentence
-  baseline — §6's own stated non-goal was a harness + baseline + first generated batch, not closing
-  the gap itself, which is met.
-- **`PLAN_ADVENTURE.md`** — a text-adventure architectural stretch: an imperative command grammar,
-  mutable turn-by-turn world/player state as ordinary graph nodes (no special player-state store),
-  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.
-- **`archive/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.
-- **`archive/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_ADVENTURE.md`** — a text-adventure architectural stretch. Its world-state and
+  actions-as-data substrate shipped generically with the planning lane (action rule kinds,
+  per-step board snapshots, legal-move enumeration); what remains its own is the imperative
+  command grammar ("go north", "take the key"), the NPC turn scheduler, the Ashcombe Hall
+  corpus, and the room-look digest.
+- **`PLAN_SYLLOGIST.md`** — the reasoning engine's research horizon. The single-justification
+  retraction slice shipped (`retractSubClassOf`, justification persistence and cascade across all
+  five rules); still open there: the ATMS generalization (alternate justification sets per fact),
+  incremental matching (§2), and relevance under budget (§4).
+- **`PLAN_GUESS_NUMBER.md`** — closed-loop planning over hidden state (belief-interval bisection,
+  thinker-mode secret commitment, observation folding) on top of the shipped planner substrate.
+  Design-only.
+- **`PLAN_CODE.md`** — small JS-function and HTML/CSS-fragment synthesis, plus goal-directed
+  program repair (tests as the goal state, mutation templates as planning actions), via a sandboxed
+  headless browser (Track 1, rule/frame synthesis, already shipped). Blocked on a sandbox
+  dependency decision.
 - **`PLAN_AGENTS.md`** — the governing plan for tmct's broader multi-repo arc (marginalia, seonix,
   a pluggable LLM rung for Claude Code/Bedrock/Copilot). Check its own sequencing table for current
   phase status, not this file.
@@ -88,8 +76,9 @@ citations, not stop signs:
 - **Bounded, incremental, trust-tiered, retraction-safe justification tracking** — `PLAN_SYLLOGIST.md`
   §3. Doyle's JTMS (1979) and de Kleer's ATMS (1986) solve retraction; DRed/RDFox's Backward-Forward
   solve incremental Datalog maintenance; nobody's published the combination with tmct's
-  multi-trust-tier, hard-budget requirement. Speculative angle: an ATMS-lite extension to
-  `syllogise.mjs`'s currently-flat provenance tag, sketched but unbuilt.
+  multi-trust-tier, hard-budget requirement. The JTMS-lite slice shipped (one persisted
+  justification per entailed fact, VERIFY-backed retraction, all five rules); the open piece is the
+  ATMS generalization — alternate justification SETS per fact (see that doc's 2026-07-15 addendum).
 - **A shared ~2M-word cross-domain ontology** (general-English + technical/scientific/programming).
   Merging collides senses of lexically-shared words (`class`, `cache`, `thread`, `field`, `state`)
   across registers; knowledge-based WSD is real but weaker than supervised/neural WSD (Lesk 1986;
@@ -99,7 +88,7 @@ citations, not stop signs:
   terms in tmct's own closed graph (a bounded reading of Gale/Church/Yarowsky's "one sense per
   discourse" regularity) — not published anywhere found for this application. Fresh live instance
   (2026-07-11): `"tail"` (Unix process vs. animal body part) collides under `normFactTerm`'s
-  cross-corpus flattening, `src/memory/core.mjs:1109-1134`.
+  cross-corpus flattening, `src/adapters/memory/core.mjs:1109-1134`.
 
 **Tier-4: learn-on-miss acquisition**. The strongest
 miss signal tmct can emit: lexicon term recognized, query built cleanly, zero matches anywhere — the
@@ -113,5 +102,5 @@ blending web-sourced facts with graph/operator facts.
 
 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, capability audits, the fast-loop
-trap-catching pattern). `HANDOVER.md` is the single current-open-items list.
+specify the repeatable measurement/build cycles (benchmarks, the background strategy advisor,
+plain-prose writing). `HANDOVER.md` is the single current-open-items list.