@polycode-projects/the-mechanical-code-talker 1.9.2 → 1.10.0

package/README.md

@@ -3,161 +3,117 @@
 `@polycode-projects/the-mechanical-code-talker`
 
 A pure-JS, **no-LLM**, offline, **$0** chatbot in the ELIZA/PARRY lineage:
-pattern-driven, best-efforts, and obsessed with software the way PARRY was
-obsessed with the mafia. No model calls anywhere.
+pattern-driven, best-efforts, and focused on software as its subject matter.
+It makes no model calls.
 
 tmct turns natural language directly into a graph database. On first run it
-seeds an everyday **human-world persona** — people, places, objects, nature,
-time — so it already has a vocabulary before you teach it anything. A
+seeds an everyday **human-world persona**: people, places, objects, nature,
+time. It already has a vocabulary before you teach it anything. A
 code-focused persona is available as an opt-in alternative: a software
 **ontology** (real definitions), a **lexicon** (everyday words mapped onto
 it), and a wider ConceptNet **corpus**. Point tmct at a real codebase's graph
-and it reasons over that too, whichever persona is active. Teach it a fact in
-plain English and it mints a node. Ask it a question and it answers from what
-it was seeded with, what you taught it, and what it can derive by rule from
-both. Every answer is either grounded or an honest miss.
+and it reasons over that too, whichever persona is active.
+
+Teach it a fact in plain English and it mints a node. Ask it a question and
+it answers from what it was seeded with, what you taught it, and what it can
+derive by rule from both. Every answer is either grounded or an honest miss.
 
 ## Teach it, then ask it to reason
 
 This is real, runnable output. No cherry-picking, no model anywhere in the
-loop. Copy it into a file and run it:
+loop. The script lives at `examples/teach-and-infer.mjs` in this repo; run it
+yourself with `node examples/teach-and-infer.mjs`, or copy the source below:
 
 ```js
 import { runChat } from "@polycode-projects/the-mechanical-code-talker";
 import { Readable, PassThrough } from "node:stream";
-import { mkdtemp, mkdir, writeFile } from "node:fs/promises";
+import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-// A graph producer feeds tmct a code graph like this one (see "The repository
-// interface" below). This is a 4-node slice: two modules, a base class, and a
-// class that inherits it.
-const graph = {
-  individuals: [
-    { id: "mod:src/handlers/base.mjs", label: "src/handlers/base.mjs", class: "Module" },
-    { id: "mod:src/handlers/tasks.mjs", label: "src/handlers/tasks.mjs", class: "Module" },
-    { id: "fn:src/handlers/base.mjs#Controller", label: "Controller", class: "Class" },
-    { id: "fn:src/handlers/tasks.mjs#TaskController", label: "TaskController", class: "Class" },
-  ],
-  objectProperties: [{
-    predicate: "inherits", prop: "seon:hasSuperType", count: 1,
-    examples: [{ subject: "fn:src/handlers/tasks.mjs#TaskController", object: "fn:src/handlers/base.mjs#Controller",
-                 subjectLabel: "TaskController", objectLabel: "Controller" }],
-  }],
-};
-
-const repoPath = await mkdtemp(join(tmpdir(), "tmct-demo-"));
-await mkdir(join(repoPath, ".tmct"), { recursive: true });
-await writeFile(join(repoPath, ".tmct", "graph.json"), JSON.stringify(graph));
-
-// tmct has one API surface for both teaching and asking: a chat turn, in
-// English. Each call below is a short session over the same repo, so what
-// gets taught in the first call is still remembered in the second.
-async function tell(line) {
-  const out = new PassThrough();
-  let transcript = "";
-  out.on("data", (chunk) => { transcript += chunk; });
-  await runChat({ repoPath, input: Readable.from([line + "\n", "/exit\n"]), output: out });
-  return transcript.split("\n").find((l) => l.startsWith("tmct> "));
-}
-
-await tell("a controller is a kind of handler");         // Learn
-console.log(await tell("is TaskController a handler"));  // Infer from learnings
+const TEACH = [
+  "ahab is the father of john",
+  "john is the father of ishmael",
+  "a father is a kind of parent",
+  "remember that ahab is male",
+  "a grandparent is a parent of a parent",
+  "a grandfather is a grandparent who is male",
+];
+const ASK = "is ahab the grandfather of ishmael";
+
+// memoryBackend: "memory" keeps this whole session in the live handle only —
+// no repo, no graph file, no disk write.
+const repoPath = await mkdtemp(join(tmpdir(), "tmct-example-"));
+const output = new PassThrough();
+let transcript = "";
+output.on("data", (chunk) => { transcript += chunk; });
+const lines = [...TEACH, ASK].map((line) => line + "\n");
+await runChat({ repoPath, memoryBackend: "memory", input: Readable.from([...lines, "/exit\n"]), output });
 ```
 
+(`examples/teach-and-infer.mjs` adds the parsing that turns `transcript` into
+the answers below, plus cleanup — see the file for the full script.)
+
 Output, captured from an actual run:
 
 ```
-tmct> yes — the code graph says TaskController inherits Controller, and you
-told me: controller is a kind of handler (source: ace:chat:<session-id>@<timestamp>)
-```
+tmct> ahab is the father of john
+noted — remembered: ahab fathers john
 
-Nothing here was told that "handler" and "Controller" relate. tmct combined a
-fact already in the graph (`TaskController inherits Controller`) with a fact
-you just taught it in English (`controller is a kind of handler`) and wrote
-the connecting sentence itself, citing both sources. The `source: ace:chat:…`
-part is a real provenance receipt. Every fact tmct stores records where it
-came from and when (more on that below).
+Goal (inferred): Teach/remember a new fact.
 
-The first `tell()` call above replies too: `noted — remembered 1 fact:
-controller rdfs:subClassOf handler (controller is a type of handler)`. The
-part in parentheses is a paraphrase. tmct generates it and checks it against
-its own inference rules before showing it, so it never just guesses at
-prose.
+tmct> john is the father of ishmael
+noted — remembered: john fathers ishmael
 
-```
-$ tmct
-tmct> what talks to the payment module?
-…
-tmct> /callers checkout
-…
-tmct> /exit
-```
+Goal (inferred): Teach/remember a new fact.
 
-**[Try it live in your browser →](https://polycode-projects.gitlab.io/the-mechanical-code-talker/)**
-is a real, interactive chat demo running client-side. Your browser runs the
-actual query engine against a small example codebase, no server, no install.
+tmct> a father is a kind of parent
+noted — remembered 1 fact: father rdfs:subClassOf parent (father is a type of parent)
 
-## Compared to other JS libraries
+Goal (inferred): Teach/remember a new fact.
 
-Nothing found in the JS ecosystem does this exact combination: teach in
-English, reason over a seeded ontology, answer in English, with no model call
-anywhere. Three kinds of library each cover one piece of it well.
+Canonical: does "father" inherits "parent"? — ask(inherits, subject="father", "parent")
 
-**[compromise](https://github.com/spencermountain/compromise)** (`npm i
-compromise`, 12k+ GitHub stars, describes itself as "modest natural language
-processing") is the general-purpose NLP toolkit of the three. Its own README
-example:
+tmct> remember that ahab is male
+noted — remembered: ahab is male
 
-```js
-import nlp from 'compromise'
-let doc = nlp('she sells seashells by the seashore.')
-doc.verbs().toPastTense()
-doc.text()
-// 'she sold seashells by the seashore.'
-```
+Goal (inferred): Teach/remember a new fact.
 
-It tags part-of-speech, conjugates verbs, and parses fractions and money far
-more broadly than tmct attempts to. It has no graph, no ontology, and no
-memory between calls. Each call is stateless text in, text out.
+tmct> a grandparent is a parent of a parent
+noted — remembered: a grandparent is a parent of a parent
 
-**[N3.js](https://github.com/rdfjs/N3.js)** (`npm i n3`) is a mature,
-spec-compliant RDF/OWL toolkit: parsing, writing, and in-memory storage of
-triples. Its own README example:
+Goal (inferred): Teach/remember a new fact.
 
-```js
-const parser = new N3.Parser();
-parser.parse(tomAndJerry, (error, quad, prefixes) => {
-  if (quad) console.log(quad);
-  else console.log("That's all, folks!", prefixes);
-});
+tmct> a grandfather is a grandparent who is male
+noted — remembered: a grandfather is a grandparent who is male
+
+Goal (inferred): Teach/remember a new fact.
+
+tmct> is ahab the grandfather of ishmael
+yes — you told me: ahab fathers john (source: teach:chat:<session-id>@<timestamp>); father is a kind of parent (source: ace:chat:<session-id>@<timestamp>); you told me: john fathers ishmael (source: teach:chat:<session-id>@<timestamp>); you told me: ahab is male (source: teach:chat:<session-id>@<timestamp>)
 ```
 
-(`tomAndJerry` is Turtle text the caller writes by hand: `c:Tom a c:Cat.
-c:Jerry a c:Mouse; c:smarterThan c:Tom.`) N3.js is the right choice if you
-already have RDF and need to parse or serialize it fast. It has no
-natural-language front end (you write the triples yourself) and no built-in
-reasoning beyond an optional, limited basic-graph-pattern reasoner.
+Nobody told tmct that ahab is ishmael's grandfather. It combined four facts
+taught across six turns: the two father facts, the father-is-a-kind-of-parent
+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).
 
-**[elizabot](https://github.com/tkafka/node-elizabot)** (`npm i elizabot`) is
-the direct ELIZA lineage in JS, the same territory tmct's chat surface sits
-in. Its own README example:
+`test/examples-teach-and-infer.test.mjs` pins this exact output. If the
+underlying chat behavior ever drifts, that test fails and says so.
 
-```js
-var eliza = new ElizaBot();
-var initial = eliza.getInitial();
-var reply = eliza.transform(inputstring);
+```
+$ tmct
+tmct> what talks to the payment module?
+…
+tmct> /callers checkout
+…
+tmct> /exit
 ```
 
-It is deterministic and needs no model, same as tmct. But it has no graph and
-no persistent memory: a fact from one line never carries into the next, and
-its "reasoning" is pattern substitution, not a stored, queryable fact.
-
-Put together: broad NLP without a graph (compromise), a graph without a
-natural-language front end (N3.js), or a conversational front end without a
-graph (elizabot). Combining ontology-seeded graph memory, English teaching,
-and rule-based inference into one no-model pipeline is what looks distinctive
-about tmct as of this writing.
+**[Try it live in your browser →](https://polycode-projects.gitlab.io/the-mechanical-code-talker/)**
+is a real, interactive chat demo running client-side. Your browser runs the
+actual query engine against a small example codebase, no server, no install.
 
 ## How it interprets you
 
@@ -168,7 +124,7 @@ results are grouped by class.
 One of the strategies is an **ACE-inspired controlled grammar**: when your
 text fits the controlled fragment, tmct emits OWL-labelled triples from it.
 Those triples are statements it can store, retrieve, and answer from later.
-Text that doesn't fit the grammar still gets the tolerant strategies; nothing
+Text that doesn't fit the grammar still gets the tolerant strategies. Nothing
 is rejected for being loose, fuzzy, or misspelled.
 
 **Everyday question shapes.** Bare "what is Commit" (no article) now resolves
@@ -182,9 +138,9 @@ you to remember X" teaches like bare "remember X"; "please tell me about X"
 and "search for X" describe and find exactly as their direct forms do.
 
 **Negation and passive.** "Which modules do *not* import X?" computes a bounded
-**set complement** over the graph, and an honestly empty result stays a miss
-rather than a fabricated list (a non-enumerable type, like arbitrary *changes*,
-is refused outright). Reversible-passive questions traverse the right direction:
+**set complement** over the graph. An empty result stays a miss rather than a
+fabricated list (a non-enumerable type, like arbitrary *changes*, is refused
+outright). Reversible-passive questions traverse the right direction:
 "what is imported by Y" and "what does Y import" are understood as opposite
 edges, not the same one.
 
@@ -223,13 +179,13 @@ still import Y" when it no longer does.
 spans: prose versus *protected* entities, paths, numbers, code, provenance, and
 receipts. A small data-driven grammar pass then runs on the prose spans only,
 under a guard that proves the protected spans came through byte-for-byte. Today
-that pass fixes the a/an article defect; broader voice and agreement rules are
+that pass fixes the a/an article defect. Broader voice and agreement rules are
 implemented but parked until they earn their place on the benchmark.
 
 A frozen regression suite plays out full multi-turn dialogues built from these
-phrasings, at every complexity level this project defines, from a single
-question up to a messy, typo-ridden real user. Tier-by-tier detail is in
-`HANDOVER.md` and `ROADMAP.md`.
+phrasings, at every complexity level this project defines. That ranges from a
+single question up to a messy, typo-ridden real user. Tier-by-tier detail is
+in `HANDOVER.md` and `ROADMAP.md`.
 
 ## How it guides you
 
@@ -250,11 +206,11 @@ bands instead of dead-ending:
 
 It fires for both **noun** concepts (class, module, function, method) and
 **relation** concepts (imports, calls, contains, inherits, tests), and only
-when tmct genuinely knows the concept *and* has instances of it. Otherwise the
-honest miss stands. The effect is a conversation that drills down from a vague
-opener to a useful answer without ever hitting a wall. Natural phrasings are
-routed to the capability you meant: *"what functions are in Task"* → its
-members, *"what defined saveStore"* → where it's defined.
+when tmct knows the concept and has instances of it. Otherwise the honest miss
+stands. This lets you start from a vague opener and still reach a useful
+answer. Natural phrasings are routed to the capability you meant: *"what
+functions are in Task"* → its members, *"what defined saveStore"* → where
+it's defined.
 
 ## Detailed, grounded answers
 
@@ -262,7 +218,7 @@ Ask a precise question and tmct gives you a precise answer. Ask for more and
 it gives you more: "give me a detailed summary of how X works" (or "explain
 in detail how X works", or "...detailed overview/explanation of X") gets a
 longer, multi-sentence account instead of one line. Every sentence in it is
-lifted from a real graph edge, attribute, or taught fact — never generated
+lifted from a real graph edge, attribute, or taught fact. tmct never generates
 free text.
 
 The wording varies a little too. A small, curated, deterministic pool swaps a
@@ -305,6 +261,73 @@ doc = In-memory record store. [seon:hasDoc]. Other matches: src/core/store.mjs
 
 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
+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
+(coverage gaps, change-coupling risk) straight from the graph — never from
+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.
+
+```
+$ 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
+
+steps:
+  1. tmct_impact {"module":"src/lib/http.mjs"}
+     Impact of changing src/lib/http.mjs (reverse closure over imports/calls edges, module- and function-level):
+     total: 5 dependent(s) across 2 depth level(s) (lists capped for brevity).
+     depth 1 (3 direct dependents):
+       - src/handlers/base.mjs (imports it) — tests: none recorded
+       - src/handlers/tasks.mjs (imports it) — tests: test/tasks.test.mjs
+       - src/server/router.mjs (imports it) — tests: none recorded
+     depth 2 (2):
+       - src/handlers/users.mjs (imports it) — tests: none recorded
+       - src/server/app.mjs (imports it) — tests: none recorded
+  2. tmct_untested {}
+     7 source module(s) with no covering test module:
+       src/core/validate.mjs
+       src/handlers/base.mjs
+       src/handlers/users.mjs
+       src/lib/http.mjs
+       src/lib/logger.mjs
+       src/server/app.mjs
+       src/server/router.mjs
+
+composed answer (4): src/handlers/base.mjs, src/handlers/users.mjs, src/server/app.mjs, src/server/router.mjs
+```
+
+tmct planned two calls (`tmct_impact` then `tmct_untested`), ran both against the
+real graph, and intersected the results itself — you get the four modules that
+are both downstream of the change AND missing coverage, not two separate lists
+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:
+
+```
+$ 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
+...
+composed answer (1): src/lib/http.mjs
+```
+
+It deduced the goal ("an impactful module must be tested"), gathered every
+untested module, ranked each by blast radius, and named the one worth testing
+first — `src/lib/http.mjs`, the module with the widest reach.
+
+`--tools tmct_impact,tmct_untested` restricts which capabilities the planner is
+allowed to use; `--json` prints the full machine-readable loop result (calls,
+proof chain, composed answer) for a caller that wants to consume this
+programmatically rather than read the report. `tmct plan --help` has the full
+flag reference.
+
 ## How it remembers
 
 tmct's memory has two layers, both fed by every parsed request and response and
@@ -318,10 +341,10 @@ by cleaned session logs:
 With no graph at all, tmct starts empty and remembers what you tell it. The
 `.tmct/` graph is created from the conversation. On a first run it seeds the
 committed vocabulary so it knows what it's talking about from turn one: an
-everyday **human-world** persona — people, places, objects, nature, time/
-events, body/food and mind vocabulary hand-curated from Open English WordNet
-and bridged to Schema.org's top-level classes — so "what is a dog?" answers
-offline, from disk, on turn one. A code-domain persona (a curated **SEON**
+everyday **human-world** persona covering people, places, objects, nature,
+time and events, body and food, and mind vocabulary. It's hand-curated from
+Open English WordNet and bridged to Schema.org's top-level classes, so "what
+is a dog?" answers offline, from disk, on turn one. A code-domain persona (a curated **SEON**
 software ontology plus the whole filtered **ConceptNet slice**, CC-BY-SA 4.0)
 is available opt-in: `tmct init --with-persona code`. `--ephemeral` (used by
 the shipped `npm run example:*` demos) reads a graph but writes nothing back.
@@ -338,7 +361,7 @@ Two more exist: `memory` keeps taught facts in the process only, nothing
 written to disk; `sqlite` persists them to a local SQLite file instead
 (`.tmct/memory/graph.sqlite`).
 
-Pick one at init time and it sticks — `tmct init --memory-backend sqlite`
+Pick one at init time and it sticks. `tmct init --memory-backend sqlite`
 writes the choice into `tmct.toml`, and every later `tmct chat` in that repo
 uses it with no flag needed:
 
@@ -360,10 +383,10 @@ New vocabulary compounds as you teach it. "redis is a cache" mints "redis" as
 a class-level concept even though it was never in the built-in lexicon, and a
 later "every cache is a store" does the same for "store," the other way
 round, as long as one side of the sentence is already grounded. tmct never
-mints a fact between two totally ungrounded terms; it declines and nudges you
-to ground one side first. Quantified teaching works too: "some functions are
-risky" stores the quantifier, and a later "how many functions are risky"
-answers "A few."
+mints a fact between two totally ungrounded terms. It declines instead, and
+nudges you to ground one side first. Quantified teaching works too: "some
+functions are risky" stores the quantifier, and a later "how many functions
+are risky" answers "A few."
 
 Once you've taught a few facts, "how many facts are there" counts them back.
 That's the same count phrasing a code graph answers "how many classes are
@@ -376,9 +399,9 @@ first-class individuals: operator chat, a curated corpus, a provider graph, a
 web scrape, a rule-derived entailment. A fact links back to *all* of them
 (`mgx:derivedFrom` / `mgx:statedBy` / `mgx:canonicalisedFrom`), timestamped with
 `mgx:createdAt`. From those links tmct computes a **deterministic, explainable
-trust score**: a source-type prior combined with corroboration (how many
-independent sources agree) and recency. It is never hand-set, always traceable
-to its inputs. Retrieval then ranks by **relevance × trust**, so a corroborated,
+trust score**, combining a source-type prior with corroboration (how many
+independent sources agree) and recency. It is never hand-set. Every value
+traces back to its inputs. Retrieval then ranks by **relevance × trust**, so a corroborated,
 operator-stated fact outranks a lone web scrape on the same question. When two
 trusted sources *disagree*, the `/memory` inspector shows **both sides with their
 provenance** rather than silently picking a winner.
@@ -408,7 +431,7 @@ Inside the chat: `/help` lists commands, `/memory` inspects what tmct remembers
 `TMCT_GRAPH_FILE` overrides the graph location.
 
 `tmct --help` (or `npm run help` from a clone of this repo) is the full,
-up-to-date flag reference for every subcommand — a bare `npm run` only lists
+up-to-date flag reference for every subcommand. A bare `npm run` only lists
 script names, so `npm run help` is the documented way in from there.
 
 `tmct init` is the onboarding surface for the repository interface below: it
@@ -419,57 +442,262 @@ package or a bare user gets a working install in one command.
 > Install-size note: tmct depends on wink-nlp's deterministic English language
 > model (~3.8 MB installed). That model is a lookup table, not an LLM.
 
-### Flags, config, and multiple graphs
+### Full command reference (`tmct --help`)
 
-Every subcommand shares one flag/config resolver (`src/cli-args.mjs`). The
-graph-path precedence is the same everywhere: `--graph` flag(s) beat
-`TMCT_GRAPH_FILE`, which beats `tmct.toml`'s `graph_file`/`graph_files`, which
-beats the `--repo`-derived `<repo>/.tmct/graph.json` default.
+`tmct --help` always prints the real, current flags. What follows is that
+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.
 
-```bash
-tmct init --repo /abs/path                    # scaffold a specific repo, not just cwd
-tmct init --corpus <id|path>                  # a tier-2 manifest id (aws|python|java|general)
-                                               # or your own corpus jsonl file
-tmct init --ontology <name|path>              # activate+seed an ontology bundle
-tmct init --lexicon <name|path>               # activate a lexicon bundle (never seeded)
-tmct init --graph <path> [--graph <path> …]   # set tmct.toml's graph_file/graph_files
-tmct init --config <path>                     # write to an alternate tmct.toml location
-tmct init --persona-size medium|large         # grow the default persona (Small is default)
-tmct init --memory-backend default|memory|sqlite  # write tmct.toml's [memory] backend —
-                                               # every later `tmct chat` here uses it
-
-tmct import --corpus <id|path>                # activate+seed into an ALREADY-initialized
-tmct import --ontology <name|path>            # repo — any combination of these flags in
-tmct import --lexicon <name|path>             # one call. --graph is a DIFFERENT, purely
-tmct import --graph <path>                    # additive op: it appends to graph_files,
-                                               # never activates an extensions bundle.
-tmct import --memory-backend default|memory|sqlite  # same knob as `tmct init`, for a
-                                               # repo that's already initialized
-
-tmct chat --graph <path> [--graph <path> …]   # explicit graph file(s) — multiple merge
-                                               # (ids that collide across graphs are
-                                               # auto-prefixed; see src/graph-merge.mjs)
-tmct chat --config <path>                     # an alternate tmct.toml (a file or a dir)
-tmct chat --memory-backend default|memory|sqlite  # override tmct.toml's backend for
-                                               # just this session
-tmct serve --graph <path> --config <path>     # same two flags, for the HTTP endpoint
-```
-
-`--corpus`/`--ontology`/`--lexicon` each take one value; chain multiple `tmct
-import` calls to combine several. `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.
-
-`tmct extend --validate <dir> --config <path>` validates a third-party
-extension pack against an alternate tmct.toml, without mutating anything.
+Every subcommand shares one flag/config resolver (`src/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:
+
+```
+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
+       [--config <path>]       an alternate tmct.toml location (a file or a directory)
+       [--ephemeral]           read the graph but write nothing back (demo/read-only)
+       [--narrate]             start with narrate mode on — a verbose, developer-facing
+                               trace of decision points/matched pattern/results/goal per
+                               turn, appended under a "--- narrate ---" marker (also
+                               TMCT_NARRATE=1; toggle mid-session with /narrate on|off)
+       [--plain]               force the plain readline shell (the default when
+                               stdin/stdout is not a terminal)
+       [--memory-backend <default|memory|sqlite>]  storage backend for taught facts this
+                               session (CLI flag > TMCT_MEMORY_BACKEND env > tmct.toml's
+                               [memory] backend > "default", the flat .tmct/ JSON file)
+```
+
+`tmct memory` is the CLI-side view of the same data the `/memory` chat command shows:
+
+```
+  tmct memory [--repo <abs>]   what tmct remembers: facts, utterances, sessions,
+       [--config <path>]       folded blocks (the /memory chat command, from the shell)
+       [--verbose]
+```
+
+`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:
+
+```
+  tmct init [--repo <abs>]     initialize a repo for tmct (default: cwd): .tmct/,
+       [--force]               tmct.toml, 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)
+       [--lexicon <name|path>]   activate a lexicon bundle (recognized name or a path;
+                               merged read-time, never seeded — see mergedLexiconExtra)
+       [--graph <path>]        set graph_file/graph_files in tmct.toml (repeatable)
+       [--config <path>]       write to an alternate tmct.toml location
+       [--detect]              suggest a tier-2 corpus from the repo's manifests
+                               (pyproject.toml → python, pom.xml → java); never seeds unasked
+       [--with-persona <name>] write an explicit [extensions]/[bias] preset into tmct.toml
+                               ("code" — today's implicit default, made explicit)
+       [--persona-size <medium|large>]  grow the default "human" persona's fact count
+                               beyond Small (the default): "medium" activates
+                               human-medium.jsonl (~1,608 facts total), "large" also
+                               activates human-large.jsonl (~13,600 facts total,
+                               with genuine multi-hop hypernym chains) — additive
+                               size tiers of the SAME bundle, not separate personas
+       [--memory-backend <default|memory|sqlite>]  write tmct.toml's [memory] backend
+                               (same flag name as `tmct chat`) — a later `tmct chat`
+                               in this repo picks it up with no flag needed
+```
+
+`tmct import` does the same activation as `tmct init`, but against a repo that 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.
+
+```
+  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
+       [--lexicon <name|path>]   tmct.toml's graph_files array (multi-graph growth),
+       [--graph <path>]        never an extensions-bundle activation.
+       [--memory-backend <default|memory|sqlite>]  same knob as `tmct init`
+       [--config <path>]
+```
+
+`tmct extend --validate` checks a third-party extension pack's declared resources
+before you switch any repo's `tmct.toml` over to it:
+
+```
+  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
+```
+
+`tmct syllogise` is the offline maintenance job described under "Speculative
+inference" above:
+
+```
+  tmct syllogise [--repo <abs>] speculative inference (offline maintenance job): forward-
+       [--depth <n>] [--budget <n>]  chain the memory's rdfs:subClassOf closure, materialising
+       [--config <path>]      bounded, low-trust, retractable entailed facts (never on the chat path)
+```
+
+`tmct viz` renders the memory graph to a single HTML file you can open in a browser:
+
+```
+  tmct viz [--repo <abs>]      write one self-contained, navigable HTML file rendering the
+       [--focus <id>]         memory graph: pan/zoom, click a node for its label/class/
+       [--term <word>]        timestamps. Seeds from the most recently created individual
+       [--depth <n>]          by default (--focus <id> or --term <word> override it);
+       [--limit <n>]          --output defaults to graph.html in the cwd.
+       [--hub-degree <n>]     --depth = max arcs (hops) from the focus node (default 3);
+       [--edge-kind <mode>]   --limit = spiral length, total nodes walked (default 300);
+       [--output <path>]      --hub-degree = stop expanding THROUGH a node above N
+       [--config <path>]      connections, still shows it (default 40); --edge-kind =
+                               meta|relation|both (default both) — which edge kinds the
+                               walk follows (provenance-only, concept-relations-only, or
+                               both — see the page's own edge-kind toggle to change this
+                               live); --term <word> resolves to the Fact(s) whose subject/
+                               object normalizes to that word and seeds from there.
+```
+
+`tmct 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:
+
+```
+  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:
+
+```
+  tmct cli <tool> '{…}'        invoke a graph tool directly (carry-over, de-emphasized)
+  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) >
+TMCT_GRAPH_FILE env > tmct.toml graph_file/graph_files > --repo-derived
+<repo>/.tmct/graph.json > git-root/cwd default.
+
+Memory-backend precedence (chat; see src/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.
+```
+
+`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.
+
+### 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
+`[extensions.*]`/`[bias]` shape).
+
+```toml
+# Newline-delimited-file form is also accepted: repositories = "repos.txt"
+repositories = ["../other-service", "../another-service"]
+
+# Where generated output (e.g. tmct viz's default graph.html) resolves to.
+out_root = "./out"
+
+# The code-graph JSON artifact. TMCT_GRAPH_FILE overrides this at runtime.
+graph_file = ".tmct/graph.json"
+# Extra graphs, merged alongside graph_file (ids that collide are auto-prefixed).
+graph_files = [".tmct/graph.json", ".tmct/legacy-graph.json"]
+
+[corpus]
+# "tier1" (committed slice only, $0/offline, the default), "tier2" (also fetch
+# growable corpora at seed time), or "tier3" (also consult live sources per query).
+tier = "tier1"
+
+[seed]
+enabled = true      # seed the committed corpus into .tmct/memory during init
+limit = 500         # cap the seeded fact count (definitional band first); unset = no cap
+
+# One [extensions.<name>] table per bundle. A recognized name (human, seon,
+# conceptnet, human-medium, human-large, tier2-aws, tier2-python, tier2-java,
+# tier2-general, wordnet-xl, wordnet-full, namenet) overrides that bundle's
+# shipped defaults. Any other name declares a new bundle and must set `kind`.
+[extensions.human]
+active = true
+
+[extensions.seon]
+active = true
+
+[extensions.conceptnet]
+active = true
+
+[extensions.tier2-aws]
+active = true
+
+[extensions.my-custom-pack]
+kind = "pack"                       # corpus | lexicon | templates | pack | ontology
+active = true
+corpus_path = "./vendor/my-pack/corpus.jsonl"
+lexicon_path = "./vendor/my-pack/lexicon.json"
+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.
+[bias]
+human = 1.0
+seon = 0.8
+conceptnet = 0.6
+my-custom-pack = 1.2
+
+[index]
+languages = ["js", "py"]                     # restrict indexing to these languages
+exclude = ["**/node_modules/**", "**/dist/**"]
+secret_exclude = ["**/*.env", "**/secrets/**"]  # never indexed, even under a broad include
+history_depth = 200                          # commits of git history to consider
+# The five keys below parse and normalize but have no consumer wired up yet:
+include_text = true
+include_structure = true
+respect_gitignore = true
+markdown_sections = true
+vue = true
+
+[tune]
+score_gap_k = 0.25          # retrieval score-gap threshold
+literal_mention = true      # boost literal-name mentions
+demote_non_prod = true      # rank test/fixture code below production code
+call_adjacency = true       # boost callers/callees of a matched symbol
+impl_of_interface = true    # boost an interface's implementations
+beam_search = true          # use beam search over the graph walk
+beam_width = 8
+embed_rank = false          # rerank by embedding similarity (off by default)
+prose_layers = 2            # how many prose-generation passes to run
+
+[tune.expansion]
+strategy = "beam"           # graph-walk expansion strategy
+nodes = 50                  # node budget for the walk
+q = 0.5                     # expansion breadth parameter
+depth = 3                   # max hops
+
+[telemetry]
+enabled = false             # local-only counters; never phones home
+
+[memory]
+retention_versions = 5      # snapshot generations memory/core.mjs keeps on manifest bootstrap
+backend = "sqlite"          # default | memory | sqlite (see "Memory backends" above)
+```
 
 ### Try it on an example graph
 
-tmct *consumes* a code graph at `<repo>/.tmct/graph.json`; it does not build
-one. Two ready-made example graphs live in `examples/` in this repo (not in the
-published npm package — clone the repo to use them) so you can see it answer
-real questions with no setup:
+tmct *consumes* a code graph at `<repo>/.tmct/graph.json`. It does not build
+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
 npm run example:mini       # "Questboard" — a small task-tracker web app (12 modules)
@@ -507,28 +735,38 @@ import { runChat, ask, resolveObject, fetchEntities } from "@polycode-projects/t
 ```
 
 `runChat` is the full teach-and-ask surface (see "Teach it, then ask it to
-reason" above — it works over injectable streams, so a script can drive a
-session the same way the tests do). `ask`/`resolveObject` are the lower-level,
+reason" above). It works over injectable streams, so a script can drive a
+session the same way the tests do. `ask`/`resolveObject` are the lower-level,
 read-only query primitives over an already-loaded graph, for a caller that
 wants to query without a chat session. The `exports` map and the chat
 primitives (`ask`, `resolveObject`, `relationKind`, `impactClosure`,
 `dispatchTool`, `fetchEntities`) are the extension surface.
 
+```js
+import { buildCapabilityPlanCtx, runCapabilityPlan, declaredCapabilityNames } from "@polycode-projects/the-mechanical-code-talker/plan";
+```
+
+The same planner `tmct plan` runs, callable directly: `buildCapabilityPlanCtx`
+loads a repo's graph into a `{ dispatch, resolve, graph }` context,
+`runCapabilityPlan(request, tools, ctx)` runs a request through it, and
+`declaredCapabilityNames()` lists every capability a caller can declare. See
+"Planning across the graph" above.
+
 ## The repository interface
 
 tmct is not an indexer, so it consumes a graph through a typed contract any
 producer can implement. That contract is first-class: a **versioned (1.0.0),
 OWL-grounded, machine-readable service definition** (`docs/repository-interface.md`
 plus a JSON schema) of every service, its arguments, result types, and error
-contract. A **miss is a value, not a throw**: the interface models "no answer"
-explicitly. tmct ships **reference providers** (a fixture graph and the
+contract. The interface returns a miss as a normal value. It never throws to
+signal "no answer." tmct ships **reference providers** (a fixture graph and the
 empty/bootstrap graph) that implement every service, and a **runnable conformance
 suite**. tmct's own providers pass it in `npm test`. Any external graph producer
 (seonix first) runs the same suite against its native implementation to claim
-conformance. Conformance is the suite, not prose. This inverts the 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.
+conformance. Passing the suite is what conformance means here. This inverts the
+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.
 
 ## Security and supply chain
 
@@ -546,16 +784,17 @@ cross-version-stable fact-id contract has exactly one definition.
 ## Provenance
 
 tmct began as a whole-package lift of the seonix chat surface (v0.1.0, then
-published as `@polycode-projects/mct`), and was then reshaped: the LLM
-fallback, the code-extraction stack, and the MCP server were all removed; the
+published as `@polycode-projects/mct`), and was then reshaped. The LLM
+fallback, the code-extraction stack, and the MCP server were all removed. The
 naming, license, and memory model were reset to the vision above. See
 `ROADMAP.md` for the phase plan.
 
 ## Licensing
 
-**MPL-2.0.** Free for commercial use; if you modify the covered files and
+**MPL-2.0.** Free for commercial use. If you modify the covered files and
 distribute them, you must publish those files' source under the MPL with
-attribution. The copyleft is file-level, not project-level. See `LICENSE`.
+attribution. The copyleft applies file by file, not to the whole project. See
+`LICENSE`.
 
 Corpus data carries its own licenses, separate from the code: the shipped
 ConceptNet slice is **CC-BY-SA 4.0**, with its own notice alongside it.