@polycode-projects/the-mechanical-code-talker 2.3.1 → 2.5.2

package/README.md

@@ -2,9 +2,8 @@
 
 `@polycode-projects/the-mechanical-code-talker`
 
-A pure-JS, **no-LLM**, offline, **$0** chatbot in the ELIZA/PARRY lineage:
-pattern-driven, best-efforts, and focused on software as its subject matter.
-It makes no model calls.
+A pure-JS, **no-LLM**, offline, **$0** chatbot in the ELIZA/PARRY lineage.
+It is pattern-driven and focused on software, and 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,
@@ -100,8 +99,12 @@ parts are real provenance receipts. Every fact tmct stores records where it
 came from and when (more on that below).
 
 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.
+live product, this transcript included. Every line shown must be a line the
+product prints, in the order shown, so if the chat behavior drifts from the
+output above, the suite fails and says so. Two blocks below are marked `skip=`
+and never run: one would touch the network, the other needs an LLM judge.
+`docs/public-examples.md` maps every example on every public surface to the
+test that holds it.
 
 Point it at a codebase's graph and the same engine answers structural questions.
 `examples/mini-webapp` ships in this repo, so this runs as written:
@@ -160,7 +163,7 @@ Text that doesn't fit the grammar still gets the tolerant strategies. Nothing
 is rejected for being loose, fuzzy, or misspelled.
 
 On top of that base, tmct reads the shapes people actually use, and each one
-resolves to a real graph traversal or declines honestly:
+resolves to a real graph traversal or declines cleanly:
 
 - everyday question forms: "what is Commit", "what's model.mjs for",
   "recent commits" as real dated history;
@@ -190,7 +193,7 @@ under a guard that proves the protected spans came through byte-for-byte.
 
 A frozen regression suite plays out full multi-turn dialogues built from these
 phrasings, from a single question up to a messy, typo-ridden real user.
-Tier-by-tier detail is in `HANDOVER.md` and `ROADMAP.md`.
+Tier-by-tier detail is in `HANDOVER.md`.
 
 ## How it guides you
 
@@ -353,8 +356,13 @@ Goal (inferred): Plan a move sequence from the current state to the goal (7 move
 ```
 
 "next" executes one move at a time, writing each board state into memory as
-facts; the final step re-reads those facts and confirms the goal from them,
-never assuming success. The search is genuine and domain-general: the test
+facts stamped with the step that produced them ("disk-1@step1 rests on peg-c",
+sourced to the plan). The final step re-reads the store and confirms the goal
+from those written facts, never assuming success. The stamp is what makes each
+step a separate record; a question about the piece itself ("where does disk-1
+rest?", "is disk-1 clear?") reads the current board — the latest step's facts,
+not every step at once. The search is
+domain-general: the test
 suite teaches Towers of Hanoi purely as sentences for 1 to 8 disks and
 asserts the plan is exactly 2^n − 1 moves every time, and a second game
 (`crates.txt`, stacking crates with different rules and a two-goal
@@ -417,14 +425,15 @@ 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:
+Teaching doesn't have to be typed, either. `tmct extract` 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. Add `--repo <abs>` to write them into that repo's own
+memory; without it nothing on disk is mutated and the facts print as JSONL:
 
 ```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
+node bin/tmct.mjs extract /tmp/notes.txt
 ```
 
 ```output
@@ -537,13 +546,13 @@ provenance record. Most of its flags choose what gets seeded and where config is
        [--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;
+       [--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
+       [--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
@@ -564,7 +573,7 @@ already set up. Its `--graph` flag works differently from the others: it appends
   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),
+       [--lexicon <name|path>]  tmct.toml's graph_files array (multi-graph growth),
        [--graph <path>]        never an extensions-bundle activation.
        [--file <definition.txt>]  teach a plain-text definition file sentence by
                                sentence (# lines are comments); any declined
@@ -573,12 +582,24 @@ already set up. Its `--graph` flag works differently from the others: it appends
        [--config <path>]
 ```
 
+`tmct extract` is the document route into memory described under "Teach it"
+above — the same teach recognizer, reading a file instead of your typing:
+
+```output:help:extract
+  tmct extract <text-file>     read a plain text file's sentences through the chat's own
+       [--file <text-file>]    teach recognizer and keep the facts it grounds; every
+                               other sentence is skipped and counted, never paraphrased
+       [--repo <abs>]          write the facts into that repo's own tmct memory; without
+                               it nothing on disk is mutated and the facts print as JSONL
+       [--out <file.jsonl>]    write that JSONL to a file instead of stdout
+```
+
 `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
+       [--config <path>]       resources (corpus/lexicon/templates) before activating
                                it in any repo's tmct.toml; exits non-zero on failure
 ```
 
@@ -586,9 +607,9 @@ before you switch any repo's `tmct.toml` over to it:
 inference" above:
 
 ```output:help:syllogise
-  tmct syllogise [--repo <abs>] speculative inference (offline maintenance job): forward-
+  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)
+       [--config <path>]       bounded, low-trust, retractable entailed facts (never on the chat path)
 ```
 
 `tmct viz` renders the memory graph as the ledger explorer — a single,
@@ -596,11 +617,11 @@ 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
-       [--limit <n>]          that answers from the embedded graph. Focuses on the newest
-       [--output <path>]      taught fact's subject by default (--focus <term> or
-       [--config <path>]      --term <word> override it); --output defaults to
+       [--focus <term>]        readable ledger of fact-sentences around one focus term,
+       [--term <word>]         with segments, a two-hop minimap, and an in-page chat dock
+       [--limit <n>]           that answers from the embedded graph. Focuses on the newest
+       [--output <path>]       taught fact's subject by default (--focus <term> or
+       [--config <path>]       --term <word> override it); --output defaults to
                                ledger.html in the cwd; --limit caps the embedded fact
                                rows; --term resolves via the same normalization chat uses.
 ```
@@ -927,7 +948,7 @@ node bin/tmct.mjs cli tmct_untested '{"repo_path":"examples/mini-webapp"}'
 ## 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),
+producer can implement. That contract is first-class: a **versioned (1.1.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. The interface returns a miss as a normal value. It never throws to
@@ -942,6 +963,19 @@ service. The LLM agent stays outside tmct, as the no-LLM ethos requires.
 
 ## Measuring it
 
+What the 2.0.3 cycle measured, on 2026-07-16. Each figure links to its method
+and carries, in the same row, the caveat that changes what it means. The full
+tables, judge scores, and transcripts are in the linked write-ups.
+
+| What it does | Result (2.0.3) | Read the number with this | Method |
+|---|---|---|---|
+| Multi-hop entailment | 219/219 chat cases and 80/80 kernel cases, 0% fabrication, all six bands pass | 50 of the 219 greens (23%) are graded against a declared floor, not the classical answer. INF-C2's 20/20 grades that the engine answers contradictory memory without fabricating, never that it detects the clash. | `BENCHMARK_INFERENCE_2.0.3.md` |
+| Tool-call planning | 56/56 cases, 100% plan-completion, 100% result-completion, 0% hallucination, every rung A0→C2 | Goal driver. All 11 C2 cases pass, so the ladder now has more headroom than the case set exercises. | `BENCHMARK_AGENT_2.0.3.md` |
+| Groundedness | Every answer carries a source, and an empty graph reports itself empty (`bootstrap-empty` 2.000/2). Judge-scored groundedness 1.857/2 over 98 cases. | The 1.857 is judged (`claude-haiku-4-5-20251001`, `judge-prompt-v1`) at N=1 over 9 of 23 construction shapes, so read it as indicative. The judge runs in the offline eval harness, never in the product. | `BENCHMARK_CEFR_ENGLISH_2.0.3.md` |
+| Abstention (the honest miss) | 0% fabrication across 299 inference rows and 0% hallucination across 168 agent rows | Structural, not a tuned threshold. tmct abstains because nothing matched, so the rows test a property of a no-model design rather than a score. | `BENCHMARK_INFERENCE_2.0.3.md`, `BENCHMARK_AGENT_2.0.3.md` |
+| Determinism | Byte-identical on rerun, 0 verdict changes across 299 inference rows against the prior cycle, a 109-case replay in 877ms at $0 per turn | A property of the no-model pipeline. | `BENCHMARK_INFERENCE_2.0.3.md`, `CAPABILITIES_2.0.3.md` |
+| Dialogue robustness (role and polarity) | An adversarial persona sweep could not force a single role or polarity inversion in 55 probes — active/passive, forward/reverse, negation and the converse trap all compiled to the correct canonical shape | The same five-frame sweep (~200 probes) surfaced 25 dialogue dead-ends, eight of them confidently wrong, all from words dropped before the parser rather than from the reasoning. | `BENCHMARK_CONVERSATION_2.0.3.md` |
+
 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:
@@ -960,7 +994,7 @@ 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 infbench/run.mjs --cases /tmp/infbench-cases.jsonl --only inf-1-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
 ```
 
@@ -971,9 +1005,6 @@ one place an LLM is allowed, never the product:
 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
@@ -992,8 +1023,76 @@ cross-version-stable fact-id contract has exactly one definition.
 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
-naming, license, and memory model were reset to the vision above. See
-`ROADMAP.md` for the phase plan.
+naming, license, and memory model were reset to the vision above. See the
+`PLAN_*.md` design docs for what's planned next.
+
+## Standards and bibliography
+
+tmct's vocabulary is grounded in published standards where they exist, and says where they don't.
+Each alignment below is a triple in `ontology/tmct-core.ttl` and a test in
+`test/adapters/grammar-ontology.test.mjs`. `docs/references/` holds an entry per source: the
+edition, the retrieval date, the terms tmct uses, and what could not be verified.
+`PLAN_NORMATIVE.md` holds the reconciliation, one verdict per term.
+
+### The data model
+
+| source | edition | what tmct uses it for |
+|---|---|---|
+| [W3C OWL 2 Primer](https://www.w3.org/TR/owl2-primer/) · [Profiles](https://www.w3.org/TR/owl2-profiles/) | Recommendation, 2012-12-11 | The triple model. The grammar emits `rdfs:subClassOf`, `owl:Restriction`, `owl:someValuesFrom`, `owl:disjointWith` and cardinality axioms. The inference engine implements OWL 2 RL/RDF rules and uses their names: `scm-sco`, `cax-sco`, `cax-dw`, `cls-svf1`, `scm-svf1`. |
+| [RDF 1.1 Semantics](https://www.w3.org/TR/rdf11-mt/) | Recommendation, 2014-02-25 | Facts are reified statements. Appendix D.1 endorses reification for provenance, which is what tmct uses it for. [RDF 1.2](https://www.w3.org/TR/rdf12-concepts/) (Candidate Recommendation, 2026-04-07) reclassifies that vocabulary as legacy and points new systems at triple terms and `rdf:reifies`. tmct has not moved, and `docs/references/schemas/rdf-reification-and-rdf-star.md` says why. |
+| [W3C PROV-O](https://www.w3.org/TR/prov-o/) | Recommendation, 2013-04-30 | Provenance. A fact's source links sit under `prov:wasInfluencedBy`; a fact cleaned from a raw utterance is a `prov:wasDerivedFrom`; a session is a `prov:Activity` and the utterances in it are `prov:Entity`s it generated. |
+| [W3C SKOS](https://www.w3.org/TR/skos-reference/) | Recommendation, 2009-08-18 | Read, and mostly not used. `skos:related` needs `skos:Concept` at both ends, and tmct's corpus terms are bare strings. `docs/references/schemas/skos.md` records what a concept-identity pass would need. |
+| [SEON](http://se-on.org/) `code.owl` | 2012/02 | Code-graph vocabulary: `seon:hasSuperType`, `seon:containsCodeEntity`, `seon:declaresMethod`, `seon:invokesMethod` and 15 more. Where SEON has no term, tmct coins under its own `mgx:` prefix rather than borrowing SEON's. |
+
+### Language
+
+| source | edition | what tmct uses it for |
+|---|---|---|
+| [Attempto Controlled English](http://attempto.ifi.uzh.ch/site/docs/) | ACE 6.7, 2013 | The controlled-English fragment. tmct implements 9 of ACE's declarative sentence patterns. |
+| Kuhn, "A Survey and Classification of Controlled Natural Languages" | *Computational Linguistics* 40(1), 2014 | Where ACE sits among controlled languages. |
+| [ConceptNet](https://github.com/commonsense/conceptnet5/wiki/Relations) | slice pins 5.7.0 | The commonsense corpus. 25 relations are mirrored into `mgx:` and each cites its `/r/` origin. |
+| Damerau, *CACM* 7(3), 1964 · Levenshtein, *Soviet Physics Doklady* 10(8), 1966 | — | Fuzzy matching. `fuzzy.mjs` implements **Optimal String Alignment** — restricted Damerau-Levenshtein, which allows adjacent transposition but edits no substring twice. |
+
+### Reasoning and planning
+
+| source | edition | what tmct uses it for |
+|---|---|---|
+| Fikes & Nilsson, "STRIPS" | *Artificial Intelligence* 2(3–4), 1971 | The action model: operator, precondition, effect. |
+| McDermott et al., PDDL | Yale CVC TR-98-003, 1998 | The action-rule vocabulary. |
+| Doyle, "A Truth Maintenance System" | *Artificial Intelligence* 12(3), 1979 | Justification and premise. tmct records which rule entailed a fact; it does not yet record which facts fed the rule. |
+| Meszaros, *xUnit Test Patterns* | Addison-Wesley, 2007 | The test-double taxonomy — stub, spy, mock, fake, dummy — and the fixture patterns. `docs/references/testing-vocabulary.md` records where tmct's own tiers depart from the standard taxonomy, and that "blast radius" is an ops metaphor for what the literature calls Regression Test Selection. |
+| Aristotle, *Prior Analytics* I.1 (24b18–20) · Bobzien, "Ancient Logic", *SEP* | — | **Why the command is called `syllogise`.** The word is used in the older, broader sense of *sullogismos* — Aristotle's own definition is "discourse in which, certain things being stated, something other than what is stated follows of necessity", with no mention of three terms or two premises, and the Stoics used the same word for a system in which modus ponens is a *sullogismos*. Two of tmct's rules are the narrow thing exactly: `scm-sco` is **Barbara**, `cax-sco` is the **Socrates syllogism**. The others reach past term logic. The operation's own names are **forward chaining** and **materialisation**, and the code uses those. |
+
+### Storage
+
+| source | edition | what tmct uses it for |
+|---|---|---|
+| Jensen et al., "A Consensus Glossary of Temporal Database Concepts" | *SIGMOD Record* 23(1), 1994 | The time vocabulary. `mgx:utteranceTs` is valid time; `mgx:createdAt` is a transaction-time start. tmct is **not** bitemporal: `mgx:updatedAt` is an audit stamp, so tmct cannot answer what it believed last Tuesday. |
+| RFC 9923, "The FNV Non-Cryptographic Hash Algorithm" | Informational, 2026 | FNV hashes the narrow non-fact-id pools (paraphrase keys, per-URL source ids, corpus dedupe). Fact ids are content-addressed with a **64-bit truncation of SHA-256**, so a fact id is collision-resistant at tmct's corpus sizes; tmct is still **not** a Merkle tree and offers no tamper-evidence. |
+| Green, Karvounarakis, Tannen, "Provenance Semirings" | PODS 2007 | The distinction tmct's docs keep: it records source annotation and PROV-style attribution, not how-provenance. |
+
+### Measuring it
+
+| source | edition | what tmct uses it for |
+|---|---|---|
+| Council of Europe, CEFR — Companion volume | 2020, ISBN 978-92-871-8621-8 | The band labels A1–C2 the chat benchmark grades against. CEFR measures what a *person* can do communicatively; grading the difficulty of *prompts* by band is tmct's adaptation, not a CEFR-validated use. The band descriptions in `chatbench/GRADED.md` are tmct's own prose. |
+| Reiter, "On Closed World Data Bases" | *Logic and Data Bases*, Plenum, 1978, pp. 55–76 | Both halves of the honest miss. The planner's operator model is **closed-world**, which is what makes a plan checkable. The chat layer is **open-world**: it will not read "no matching rule" as "the answer is no". |
+| Chow, "On optimum recognition error and reject tradeoff" | *IEEE Trans. Information Theory* 16(1), 1970 | Prior art for the goal. The literature calls a refusal **abstention**, or selective prediction, and Chow's reject option is its root. Those methods threshold a confidence score; tmct has none, and abstains because nothing matched — which is why the row above names the mechanism. |
+| Ji et al., "Survey of Hallucination in Natural Language Generation" | *ACM Computing Surveys* 55(12), 2023 | Groundedness, and what tmct is avoiding by having no model to hallucinate with. |
+
+### Where no standard fits
+
+- **Trust.** PROV records who said a thing, not whether to believe them, and no W3C Recommendation
+  covers trust. `mgx:trustScore` and its inputs are tmct's own. Candidate literature: Artz & Gil,
+  "A survey of trust in computer science and the Semantic Web", *Journal of Web Semantics* 5(2),
+  2007.
+- **Negation.** tmct negates with its own `mgxneg:` prefix, which applies to any predicate.
+  `owl:disjointWith` would over-claim, since "john is not a man" denies one membership rather than
+  a class axiom, and OWL 2's `negativePropertyAssertion` needs a reified shape the flat JSON store
+  has no room for.
+- **Dialogue acts.** tmct has no intent vocabulary. ISO 24617-2 (SemAF) is the standard for one, and
+  `docs/references/schemas/iso-24617-2-dialogue-acts.md` maps tmct's behaviour onto it so that if
+  one is built it uses the standard's names.
 
 ## Licensing
 

package/bin/tmct.mjs

@@ -26,7 +26,13 @@
 // 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. See README.md for what tmct is and
-// deliberately is NOT, and ROADMAP.md for where it is going.
+// deliberately is NOT, and the PLAN_*.md docs for where it is going.
+
+// The verb list itself is data (src/domain/cli-verbs.mjs) and both the Usage
+// block below and the unknown-invocation line read it, so a new verb is one
+// entry rather than two edits that drift. It is pure and imports nothing, so a
+// static import here costs `tmct --help` nothing.
+import { renderUsage, unknownInvocationMessage } from "../src/domain/cli-verbs.mjs";
 
 const HELP = `tmct — The Mechanical Code Talker
 
@@ -34,94 +40,7 @@ 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
-       [--graph <path>]        explicit graph file (repeatable — multiple graphs merge;
-                               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
-                               the final answer (teach state first, trigger last)
-       [--render blocks]       with --prompt: when the final turn produced a plan,
-                               write it as a self-contained animated page
-       [--output <path>]       the rendered page's path (default plan.html)
-       [--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 [--repo <abs>]   what tmct remembers: facts, utterances, sessions,
-       [--config <path>]       folded blocks (the /memory chat command, from the shell)
-       [--verbose]
-  tmct init [--repo <abs>]     initialize a repo for tmct (default: cwd): .tmct/,
-       [--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)
-       [--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 [--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.
-       [--file <definition.txt>]  teach a plain-text definition file sentence by
-                               sentence (# lines are comments); any declined
-                               sentence exits non-zero with the sentence named
-       [--memory-backend <default|memory|sqlite>]  same knob as \`tmct init\`
-       [--config <path>]
-  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 [--repo <abs>] speculative inference (offline maintenance job): forward-
-       [--depth <n>] [--budget <n>]  chain the memory's rdfs:subClassOf closure, materialising
-       [--config <path>]      bounded, low-trust, retractable entailed facts (never on the chat path)
-  tmct viz [--repo <abs>]      write one self-contained HTML page: the memory graph as a
-       [--focus <term>]       readable ledger of fact-sentences around one focus term,
-       [--term <word>]        with segments, a two-hop minimap, and an in-page chat dock
-       [--limit <n>]          that answers from the embedded graph. Focuses on the newest
-       [--output <path>]      taught fact's subject by default (--focus <term> or
-       [--config <path>]      --term <word> override it); --output defaults to
-                               ledger.html in the cwd; --limit caps the embedded fact
-                               rows; --term resolves via the same normalization chat uses.
-  tmct serve [--repo <abs>]    run the Anthropic Messages API-compatible endpoint
-       [--host <h>] [--port <n>]  (POST /v1/messages) over the graph — a deterministic,
-       [--graph <path>]        no-LLM "model" a tool-loop client can call; $0 usage.
-       [--config <path>]       Defaults: host 127.0.0.1, port 8787. Ctrl+C to stop.
-  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 <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
-  tmct --help                  show this help
+${renderUsage()}
 
 On a terminal, chat opens the full-screen TUI; piped input gets the plain shell.
 In chat: /help lists slash-commands; /exit leaves. Session log → <repo>/.tmct/session-<id>.log.
@@ -1117,6 +1036,15 @@ async function main() {
     return;
   }
 
+  if (mode === "extract") {
+    // `tmct extract` — run a text file's sentences through the chat's own teach
+    // recognizer and keep what it grounds. Lazily imported: it pulls the whole
+    // chat stack, which `tmct --help` and chat startup must not pay for.
+    const { main: extractFacts } = await import("../src/services/extract-facts.mjs");
+    await extractFacts(process.argv.slice(3));
+    return;
+  }
+
   if (mode === "viz") {
     // `tmct viz` — the ledger explorer: one self-contained HTML page rendering
     // the memory graph as readable fact-sentences around a focus term, with
@@ -1336,8 +1264,7 @@ async function main() {
 
   // An unknown mode gets the instructive usage line and exit 2. (A bare invocation
   // never lands here — the argv splice above rewrote it to `chat`.)
-  process.stderr.write(`tmct: unknown invocation "${process.argv.slice(2).join(" ")}". ` +
-    "Use `chat`, `memory`, `init`, `import`, `extend --validate`, `syllogise`, `serve`, `plan`, `cli digest …`, or `cli <tool> …`.\n");
+  process.stderr.write(unknownInvocationMessage(process.argv.slice(2).join(" ")));
   process.exit(2);
 }
 

package/corpus/README.md

@@ -1,9 +1,9 @@
 # corpus/ — committed corpus data
 
-The corpuses tmct ships so that an **empty** tmct still has a vocabulary
-(ROADMAP Phase 2). Everything here is plain, diffable data; the loaders live
+The corpuses tmct ships so that an **empty** tmct still has a vocabulary.
+Everything here is plain, diffable data; the loaders live
 in `src/adapters/corpus/`. Related committed data lives in `data/` (response templates
-+ the SE phrase book — items 4+7).
++ the SE phrase book).
 
 ## The tiering policy (tier-1 / tier-2 / tier-3)
 

package/corpus/seon/README.md

@@ -20,6 +20,7 @@ CC-BY-SA like the ConceptNet slice.
 |------|-------|-------|
 | `concepts.jsonl`    | relation facts, byte-identical shape to `corpus/conceptnet/slice.jsonl` | 399 facts |
 | `definitions.jsonl` | `{ "term", "definition", "sense": "software" }`, one per line             | 288 definitions |
+| `relations.jsonl`   | `{ "relation", "definition", "sense": "software" }`, one per line — what each edge kind means, so "what does imports mean" answers without per-repo seeding | 9 relations |
 | `LICENSE-NOTICE`    | MPL-2.0 provenance for this directory | — |
 
 ### `concepts.jsonl` — same shape as the ConceptNet slice

package/corpus/tier2/generate.mjs

@@ -241,7 +241,7 @@ export const CORPUSES = {
     ],
   },
 
-  // PLAN_SEED.md — the default "human-world" persona (the operator's own
+  // The default "human-world" persona (the operator's own
   // framing: SEON+ConceptNet's code-domain bias was never the only sensible
   // default; this is the general-knowledge seed set that REPLACES it as the
   // default active bundle, per src/services/extensions.mjs's builtinExtensions()).
@@ -252,20 +252,20 @@ export const CORPUSES = {
   // IsA/HasA/UsedFor/CapableOf/etc. facts; Schema.org's vocabulary
   // (Apache-2.0) supplies `human-base`'s top-level category classes and
   // `human-bridge`'s showcase connection between the two independently-built
-  // taxonomies (PLAN_SEED.md §8) — both hand-authored in homage to their
+  // taxonomies — both hand-authored in homage to their
   // source's real class shape, never copied verbatim (SEON's own
-  // LICENSE-NOTICE discipline). 9 clumps, Small tier (PLAN_SEED.md §3):
+  // LICENSE-NOTICE discipline). 9 clumps, Small tier:
   // human-base (scaffolding, always first), 7 content clumps, human-bridge
   // (the cross-ontology showcase). "Breadth over depth" throughout, per the
   // operator's explicit instruction — flat one-hop IsA facts, no gender/
   // kinship taxonomy, no formal role hierarchy.
   human: {
     kind: "domain",
-    description: "The default human-world persona (PLAN_SEED.md): everyday people, places, objects, nature, time/events, body/food and mind vocabulary, hand-curated from Open English WordNet (CC-BY-4.0) and bridged to Schema.org's (Apache-2.0) top-level classes — replaces the code-domain SEON+ConceptNet default.",
+    description: "The default human-world persona: everyday people, places, objects, nature, time/events, body/food and mind vocabulary, hand-curated from Open English WordNet (CC-BY-4.0) and bridged to Schema.org's (Apache-2.0) top-level classes — replaces the code-domain SEON+ConceptNet default.",
     // Every noun/verb/adjective this corpus's facts depend on, so a live
     // sentence built from the SAME curated vocabulary ("a man has a hat") can
     // actually parse — src/domain/grammar/lexicon-core.json carries the real
-    // entries (PLAN_SEED.md §4's "two vocabulary surfaces", gated
+    // entries (a second vocabulary surface, gated
     // independently); this list is the --verify drift-guard's source of
     // truth (below), not a second copy of the lexicon file itself.
     lexicon: {
@@ -351,9 +351,9 @@ export const CORPUSES = {
       // ---- human-base (scaffolding, ~18 facts) — the top-level category
       // classes, `rdfs:subClassOf` children of a "schema thing" concept
       // representing Schema.org's real `:Thing` root (hand-authored in
-      // homage to schema.org/Thing's shape — PLAN_SEED.md §5 — never a
+      // homage to schema.org/Thing's shape, never a
       // verbatim copy of Schema.org's own class definitions/comments).
-      // Always active regardless of tier (PLAN_SEED.md §3).
+      // Always active regardless of tier.
       ["schema_person", "/r/IsA", "schema_thing"],
       ["schema_place", "/r/IsA", "schema_thing"],
       ["schema_object", "/r/IsA", "schema_thing"],
@@ -681,8 +681,8 @@ export const CORPUSES = {
       ["smile", "/r/CapableOf", "show_happiness"], ["smile", "/r/PartOf", "a_face"],
       ["silence", "/r/HasProperty", "quiet"], ["silence", "/r/CapableOf", "calm_the_mind"],
 
-      // ---- human-bridge (~10 facts) — the cross-ontology showcase
-      // (PLAN_SEED.md §8): a WordNet-side root/common term paired with its
+      // ---- human-bridge (~10 facts) — the cross-ontology showcase:
+      // a WordNet-side root/common term paired with its
       // Schema.org-inspired counterpart from human-base, above. scm-sco
       // (src/domain/syllogise.mjs, unmodified) proves a chain spanning both
       // sources once a WordNet-side ⊑-chain reaches one of these —
@@ -700,20 +700,20 @@ export const CORPUSES = {
     ],
   },
   // Medium tier — INCREMENTAL facts beyond Small (corpus/tier2/human.jsonl) only
-  // (PLAN_SEED.md §3's tier-selection design: Small/Medium/Large are SIZES of
+  // (Small/Medium/Large are SIZES of
   // one bundle, not separate corpus ids — this file holds only what Medium
   // ADDS beyond the previous tier). Built by scripts/build-persona-tiers.mjs
   // from the same two locally-cloned WordNet source files as Small
   // (~/projects/globalwordnet/english-wordnet/src/yaml/), automatically
   // curated: candidate words ranked by WordNet sense-count (a commonness
-  // proxy, PLAN_SEED.md §12), restricted to each word's own TOP senses (not
+  // proxy), restricted to each word's own TOP senses (not
   // some rare/slang meaning that happens to live in this domain), obscure/
   // archaic/offensive/pharmaceutical content excluded via a definition-text
   // blocklist plus an explicit word denylist, reviewed by hand before being
   // spliced in here (scripts/apply-persona-tiers.mjs). Medium stays flat, one hop per word, same style as Small.
   "human-medium": {
     kind: "domain",
-    description: "The Medium tier of the default human-world persona (PLAN_SEED.md): incremental facts beyond Small only — activated alongside \"human\" via --persona-size medium, never active by default.",
+    description: "The Medium tier of the default human-world persona: incremental facts beyond Small only — activated alongside \"human\" via --persona-size medium, never active by default.",
     lexicon: {
       nouns: [
         // human-core (+186 words: people, family, common roles)
@@ -1800,20 +1800,20 @@ export const CORPUSES = {
   },
 
   // Large tier — INCREMENTAL facts beyond Medium (corpus/tier2/human-medium.jsonl) only
-  // (PLAN_SEED.md §3's tier-selection design: Small/Medium/Large are SIZES of
+  // (Small/Medium/Large are SIZES of
   // one bundle, not separate corpus ids — this file holds only what Large
   // ADDS beyond the previous tier). Built by scripts/build-persona-tiers.mjs
   // from the same two locally-cloned WordNet source files as Small
   // (~/projects/globalwordnet/english-wordnet/src/yaml/), automatically
   // curated: candidate words ranked by WordNet sense-count (a commonness
-  // proxy, PLAN_SEED.md §12), restricted to each word's own TOP senses (not
+  // proxy), restricted to each word's own TOP senses (not
   // some rare/slang meaning that happens to live in this domain), obscure/
   // archaic/offensive/pharmaceutical content excluded via a definition-text
   // blocklist plus an explicit word denylist, reviewed by hand before being
-  // spliced in here (scripts/apply-persona-tiers.mjs). Large's own facts walk real multi-hop hypernym chains (up to 4 hops, PLAN_SEED.md §3's own "surgeon ⊑ doctor ⊑ … ⊑ person" example) wherever WordNet's real structure supports it, not a flat one-hop-per-word cap.
+  // spliced in here (scripts/apply-persona-tiers.mjs). Large's own facts walk real multi-hop hypernym chains (up to 4 hops, e.g. "surgeon ⊑ doctor ⊑ … ⊑ person") wherever WordNet's real structure supports it, not a flat one-hop-per-word cap.
   "human-large": {
     kind: "domain",
-    description: "The Large tier of the default human-world persona (PLAN_SEED.md): incremental facts beyond Medium only — activated alongside \"human\" via --persona-size large, never active by default.",
+    description: "The Large tier of the default human-world persona: incremental facts beyond Medium only — activated alongside \"human\" via --persona-size large, never active by default.",
     lexicon: {
       nouns: [
         // human-core (+1469 words: people, family, common roles)
@@ -14881,8 +14881,8 @@ export async function fetchCorpus(url, expectedSha) {
 
 /**
  * Alignment drift-guard for a corpus entry that declares an optional
- * `lexicon` sub-key (today: only `human` — PLAN_SEED.md §4's "two vocabulary
- * surfaces" seam): the corpus fact set and the ACE parser's closed-set
+ * `lexicon` sub-key (today: only `human` — the two-vocabulary-surfaces
+ * seam): the corpus fact set and the ACE parser's closed-set
  * vocabulary (src/domain/grammar/lexicon-core.json) are two SEPARATE files, gated
  * independently, so nothing stops them drifting apart over time. Two
  * directions, both real (mirroring conceptnet-map.toml's own "slice relation

package/corpus/tier2/manifest.json

@@ -61,7 +61,7 @@
     {
       "id": "human",
       "kind": "domain",
-      "description": "The default human-world persona (PLAN_SEED.md): everyday people, places, objects, nature, time/events, body/food and mind vocabulary, hand-curated from Open English WordNet (CC-BY-4.0) and bridged to Schema.org's (Apache-2.0) top-level classes — replaces the code-domain SEON+ConceptNet default.",
+      "description": "The default human-world persona: everyday people, places, objects, nature, time/events, body/food and mind vocabulary, hand-curated from Open English WordNet (CC-BY-4.0) and bridged to Schema.org's (Apache-2.0) top-level classes — replaces the code-domain SEON+ConceptNet default.",
       "source": {
         "kind": "curated",
         "tool": "corpus/tier2/generate.mjs"
@@ -75,7 +75,7 @@
     {
       "id": "human-medium",
       "kind": "domain",
-      "description": "The Medium tier of the default human-world persona (PLAN_SEED.md): incremental facts beyond Small only — activated alongside \"human\" via --persona-size medium, never active by default.",
+      "description": "The Medium tier of the default human-world persona: incremental facts beyond Small only — activated alongside \"human\" via --persona-size medium, never active by default.",
       "source": {
         "kind": "curated",
         "tool": "corpus/tier2/generate.mjs"
@@ -89,7 +89,7 @@
     {
       "id": "human-large",
       "kind": "domain",
-      "description": "The Large tier of the default human-world persona (PLAN_SEED.md): incremental facts beyond Medium only — activated alongside \"human\" via --persona-size large, never active by default.",
+      "description": "The Large tier of the default human-world persona: incremental facts beyond Medium only — activated alongside \"human\" via --persona-size large, never active by default.",
       "source": {
         "kind": "curated",
         "tool": "corpus/tier2/generate.mjs"

package/data/games/hanoi-3.txt

@@ -5,8 +5,14 @@
 #   the goal is that every disk rests on peg-c. solve it.
 #
 # Variations, each stretching a different direction:
-#   scale      — first teach: "disk-4 is a disk. disk-3 is smaller than disk-4."
-#                start all four on peg-a, same goal. 15 moves (2^4 - 1).
+#   scale      — first teach: "disk-4 is a disk."
+#                then: "disk-1 is smaller than disk-4. disk-2 is smaller than disk-4.
+#                disk-3 is smaller than disk-4."
+#                then: "disk-1 rests on disk-2. disk-2 rests on disk-3. disk-3 rests on
+#                disk-4. disk-4 rests on peg-a." — same goal. 15 moves (2^4 - 1).
+#                Every smaller-than pair is taught: the relation is stored as given and
+#                is not chased transitively, so disk-3 < disk-4 alone leaves disk-1 and
+#                disk-2 with no legal move onto disk-4 and no plan exists.
 #   any start  — disk-1 rests on peg-b. disk-2 rests on peg-c. disk-3 rests on peg-a.
 #                the goal is that every disk rests on peg-c. solve it.
 #   other goal — same start, "the goal is that every disk rests on peg-b. solve it."