@polycode-projects/the-mechanical-code-talker 2.10.3 → 2.11.0

package/README.md

@@ -120,13 +120,18 @@ tmct> /exit
 
 **[Try it live in your browser →](https://polycode-projects.gitlab.io/the-mechanical-code-talker/)**
 runs the actual query engine client-side. No server, no install. The landing
-page answers codebase questions live, and six more pages each ground their
-own domain: a full chat seeded with 19,228 facts (the same nine bands as
-`npm run init:xl`, capped to a 22.8 MB download), the **memory ledger**
-(every fact as a readable sentence; drill by clicking the terms inside), a
-Towers-of-Hanoi plan replayed move by move, the spider-and-fly and
-text-adventure games, and a sprite gallery whose chat dock answers from
-1,033 generated sprite facts.
+page answers codebase questions live, and eight more pages each ground their
+own domain: a full chat seeded with 32,646 facts (the same nine bands as
+`npm run init:xl`, capped to a 38.7 MB download, 2.1 MB on the wire), the
+**memory ledger** (every fact as a readable sentence; drill by clicking the
+terms inside), the **code explorer** (the same ledger UI refocused on a code
+graph, with a hint rail of suggested next questions), an **ingest page** that
+turns pasted or dropped text into grounded facts and downloads them as
+canonical JSONL, a Towers-of-Hanoi plan replayed move by move, the
+spider-and-fly and text-adventure games, and a sprite gallery whose chat dock
+answers from 1,033 generated sprite facts. The chat page and the ledger take
+the same paste-or-drop text in place; every page that holds a fact store
+exports it as JSONL.
 The site hosts its own copy of wink-nlp, ships its assets precompressed,
 and a service worker precaches the big ones, so a second visit works
 offline. `tmct chat --render spider-fly|adventure|sprites [--output <path>]`
@@ -137,7 +142,7 @@ offline before it deploys. The example graph, the chat seed, the pages, 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
+```bash e2e heavy 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
 ```
@@ -166,6 +171,11 @@ over the same graph. A hint rail suggests the next question from what the graph
 actually holds — "what does X import", "which functions call Y", "list
 functions" — so every suggestion resolves to a real answer.
 
+The identical page also runs as a plain hosted page, over the demo code
+graph — **[try it live →](https://polycode-projects.gitlab.io/the-mechanical-code-talker/code.html)**
+— for a look with nothing to install. The desktop build below is for
+exploring your own repo or graph, which the hosted page cannot reach.
+
 Electron is a dev-only dependency and never ships in the npm package. Because
 `.npmrc` sets `ignore-scripts=true`, installing it does not fetch the runtime
 binary; fetch it once, then build and launch:
@@ -469,6 +479,11 @@ cited read-out, CC BY-SA, pinned to the revision it read (provenance
 `reference:wikipedia-live:<Title>@<revid>`). A failed lookup (no matching
 title, a timeout, a rate limit) leaves the honest miss byte-identical.
 
+A live article carries its own source-type prior (`referenceLive`, 0.5) below
+the curated revision-pinned pack (`reference`, 0.6). A fact fetched live never
+outranks the shipped article on the same term, and a fact you teach outranks
+both.
+
 ## How it remembers
 
 tmct's memory has two layers, both fed by every parsed request and response and
@@ -479,6 +494,11 @@ by cleaned session logs:
 - **text blocks under a PageRank-style index**, pulled into context on
   relevance rather than loaded wholesale.
 
+Every session also writes its own human-readable transcript,
+`.tmct/session-<id>.md` — a glow-friendly Markdown file with one heading per
+turn, the question as a blockquote, the reply in a fenced block. The
+browser chat page's "export .md" button writes the same shape.
+
 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
@@ -531,6 +551,17 @@ rather than the code graph. A taught class answers both shapes too: after
 "dog is a kind of animal", "how many animals are there" counts its members and
 "list all animals" reads them back, each cited to where it came from.
 
+When you ask about a term, the read-back shows each "is a kind of" object with
+its own superclass chain: "what is rover" answers "rover is a kind of dog →
+canine → mammal → animal". If one label carries two unrelated senses — you
+taught "rover is a dog" and a corpus row says "rover is a scout" — the answer
+groups by concept ("rover, the dog:" / "rover, the scout:") instead of listing
+two unrelated lines as if they were one thing. The split is deterministic over
+the stored hierarchy: two senses part when a stored disjointness separates
+their ancestors, when their chains never meet, or when they meet only at the
+very top. When the evidence is thin the answer stays a flat list — grouping is
+presentation, and it never retracts or reranks a fact.
+
 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,
@@ -551,6 +582,20 @@ 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.
 
+`--optimistic` adds a second, lower-trust tier over the sentences the strict
+recognizer skips: a copula or a known relation verb flanked by two nouns
+becomes a candidate triple, stored under its own `optimistic-extract:<file>`
+provenance (prior 0.35, below every curated pack) with no operator tag riding
+alongside — so a fuzzy guess can never corroborate a curated fact. It is an
+attempt, not full NLU: a sentence with no clean pair yields nothing.
+`--canonical` prints each grounded fact as a triple, noting how each endpoint
+already links into the store.
+
+The same pipeline is one library seam, `ingestText(text, options)` (exported
+as `@polycode-projects/the-mechanical-code-talker/ingest`), and one cold tool,
+`tmct_ingest` — so a browser page, a script, or a tool-calling agent can ground
+text without the CLI.
+
 ### Provenance and trust
 
 Every fact and text block records **where it came from and when**. Sources are
@@ -571,8 +616,15 @@ provenance** rather than silently picking a winner.
 batch: a forward-chaining materialisation over the memory's OWL 2 RL rule
 kernels (the classical syllogism is one of them, and the verb keeps Aristotle's
 broader sense; see the bibliography) that writes new **entailed** facts. They
-are low-trust and retractable, never outranking a stated fact, and this never
-runs on the chat's hot path.
+are low-trust and retractable, never outranking a stated fact.
+
+The full-store batch is a maintenance job, off the chat's hot path. One bounded
+sibling does run inline: when a learn-on-miss load pulls new facts in (a child
+pack, a reference or live-Wikipedia article), a small focus-scoped pass around
+the loaded term connects those new facts to what's already remembered, so a load
+becomes durable knowledge rather than an island. It shares the same kernels, the
+same `entailed:*` provenance and the same low, retractable trust; only its scope
+and budget shrink.
 
 ## Install & use
 
@@ -711,6 +763,9 @@ above — the same teach recognizer, reading a file instead of your typing:
        [--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
+       [--optimistic]          also run a lower-trust fuzzy tier over the sentences the
+                               strict recognizer skips; candidates rank below every curated pack
+       [--canonical]           print each grounded fact as a triple linked into the store
 ```
 
 `tmct extend --validate` checks a third-party extension pack's declared resources
@@ -814,7 +869,7 @@ 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
+```bash e2e heavy
 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
@@ -1009,7 +1064,7 @@ loads a repo's graph into a `{ dispatch, resolve, graph }` context,
 
 ## The tool surface
 
-Everything above runs on the same 24 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.
+Everything above runs on the same 25 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.
 
@@ -1082,6 +1137,7 @@ The remaining tools are **cold**: still served, but not billed to an agent every
 | `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) |
 | `tmct_export` | Every stored memory fact as JSONL (subject/predicate/object/provenance) — the shape `tmct extract` emits, for backup or audit. | none |
+| `tmct_ingest` | Ground plain text into memory facts with the same deterministic recognizer the chat teach lane uses — the strict tier, plus an optional lower-trust fuzzy tier — and report the canonical triples. | `text` (required), `optimistic` |
 
 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.
 

package/bin/tmct.mjs

@@ -55,7 +55,7 @@ Usage:
 ${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.
+In chat: /help lists slash-commands; /exit leaves. Session log → <repo>/.tmct/session-<id>.md.
 
 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
@@ -266,7 +266,10 @@ async function runCliMode() {
     }
     const config = await configFor(args.repo_path);
     try {
-      const text = await dispatchTool(sub, args, { config });
+      // The recognizer seam a tool like tmct_ingest needs: injected here (bin
+      // sits above the service layer) rather than imported by the tool layer.
+      const { ingestText } = await import("../src/services/extract-facts.mjs");
+      const text = await dispatchTool(sub, args, { config, ingest: ingestText });
       process.stdout.write(text + "\n");
     } catch (e) {
       process.stderr.write(`tmct: ${e?.message || e}\n`);

package/corpus/sprites/src/sprite-facts.jsonl

@@ -19,6 +19,7 @@
 {"subject":"birthday sprite","predicate":"rdf:type","object":"sprite class"}
 {"subject":"boat sprite","predicate":"rdf:type","object":"sprite class"}
 {"subject":"body of water sprite","predicate":"rdf:type","object":"sprite class"}
+{"subject":"book sprite","predicate":"rdf:type","object":"sprite class"}
 {"subject":"boss sprite","predicate":"rdf:type","object":"sprite class"}
 {"subject":"boy sprite","predicate":"rdf:type","object":"sprite class"}
 {"subject":"bread sprite","predicate":"rdf:type","object":"sprite class"}
@@ -31,6 +32,7 @@
 {"subject":"car sprite","predicate":"rdf:type","object":"sprite class"}
 {"subject":"castle sprite","predicate":"rdf:type","object":"sprite class"}
 {"subject":"cat sprite","predicate":"rdf:type","object":"sprite class"}
+{"subject":"cellar sprite","predicate":"rdf:type","object":"sprite class"}
 {"subject":"chair sprite","predicate":"rdf:type","object":"sprite class"}
 {"subject":"champion sprite","predicate":"rdf:type","object":"sprite class"}
 {"subject":"cheese sprite","predicate":"rdf:type","object":"sprite class"}
@@ -52,6 +54,7 @@
 {"subject":"dinner sprite","predicate":"rdf:type","object":"sprite class"}
 {"subject":"doctor sprite","predicate":"rdf:type","object":"sprite class"}
 {"subject":"dog sprite","predicate":"rdf:type","object":"sprite class"}
+{"subject":"drawing-room sprite","predicate":"rdf:type","object":"sprite class"}
 {"subject":"dress sprite","predicate":"rdf:type","object":"sprite class"}
 {"subject":"drink sprite","predicate":"rdf:type","object":"sprite class"}
 {"subject":"driver sprite","predicate":"rdf:type","object":"sprite class"}
@@ -128,6 +131,7 @@
 {"subject":"office sprite","predicate":"rdf:type","object":"sprite class"}
 {"subject":"officer sprite","predicate":"rdf:type","object":"sprite class"}
 {"subject":"owl sprite","predicate":"rdf:type","object":"sprite class"}
+{"subject":"pan sprite","predicate":"rdf:type","object":"sprite class"}
 {"subject":"parent sprite","predicate":"rdf:type","object":"sprite class"}
 {"subject":"park sprite","predicate":"rdf:type","object":"sprite class"}
 {"subject":"person sprite","predicate":"rdf:type","object":"sprite class"}
@@ -168,6 +172,7 @@
 {"subject":"stranger sprite","predicate":"rdf:type","object":"sprite class"}
 {"subject":"street sprite","predicate":"rdf:type","object":"sprite class"}
 {"subject":"student sprite","predicate":"rdf:type","object":"sprite class"}
+{"subject":"study sprite","predicate":"rdf:type","object":"sprite class"}
 {"subject":"sugar sprite","predicate":"rdf:type","object":"sprite class"}
 {"subject":"summer sprite","predicate":"rdf:type","object":"sprite class"}
 {"subject":"sun sprite","predicate":"rdf:type","object":"sprite class"}
@@ -198,26 +203,34 @@
 {"subject":"writer sprite","predicate":"rdf:type","object":"sprite class"}
 {"subject":"adventurer sprite","predicate":"mgx:render-at","object":"icon tier"}
 {"subject":"animal sprite","predicate":"mgx:render-at","object":"icon tier"}
+{"subject":"book sprite","predicate":"mgx:render-at","object":"icon tier"}
 {"subject":"butler sprite","predicate":"mgx:render-at","object":"icon tier"}
 {"subject":"cabinet sprite","predicate":"mgx:render-at","object":"icon tier"}
+{"subject":"cellar sprite","predicate":"mgx:render-at","object":"icon tier"}
 {"subject":"container sprite","predicate":"mgx:render-at","object":"icon tier"}
 {"subject":"cook sprite","predicate":"mgx:render-at","object":"icon tier"}
 {"subject":"desk sprite","predicate":"mgx:render-at","object":"icon tier"}
 {"subject":"dog sprite","predicate":"mgx:render-at","object":"icon tier"}
+{"subject":"drawing-room sprite","predicate":"mgx:render-at","object":"icon tier"}
 {"subject":"egg sprite","predicate":"mgx:render-at","object":"icon tier"}
 {"subject":"fly sprite","predicate":"mgx:render-at","object":"icon tier"}
 {"subject":"furniture sprite","predicate":"mgx:render-at","object":"icon tier"}
+{"subject":"garden sprite","predicate":"mgx:render-at","object":"icon tier"}
 {"subject":"gardener sprite","predicate":"mgx:render-at","object":"icon tier"}
 {"subject":"housekeeper sprite","predicate":"mgx:render-at","object":"icon tier"}
 {"subject":"key sprite","predicate":"mgx:render-at","object":"icon tier"}
+{"subject":"kitchen sprite","predicate":"mgx:render-at","object":"icon tier"}
 {"subject":"lamp sprite","predicate":"mgx:render-at","object":"icon tier"}
 {"subject":"letter sprite","predicate":"mgx:render-at","object":"icon tier"}
+{"subject":"library sprite","predicate":"mgx:render-at","object":"icon tier"}
+{"subject":"pan sprite","predicate":"mgx:render-at","object":"icon tier"}
 {"subject":"person sprite","predicate":"mgx:render-at","object":"icon tier"}
 {"subject":"poodle sprite","predicate":"mgx:render-at","object":"icon tier"}
 {"subject":"portable sprite","predicate":"mgx:render-at","object":"icon tier"}
 {"subject":"portrait sprite","predicate":"mgx:render-at","object":"icon tier"}
 {"subject":"room sprite","predicate":"mgx:render-at","object":"icon tier"}
 {"subject":"spider sprite","predicate":"mgx:render-at","object":"icon tier"}
+{"subject":"study sprite","predicate":"mgx:render-at","object":"icon tier"}
 {"subject":"adult sprite","predicate":"mgx:render-at","object":"sprite tier"}
 {"subject":"adventurer sprite","predicate":"mgx:render-at","object":"sprite tier"}
 {"subject":"airport sprite","predicate":"mgx:render-at","object":"sprite tier"}
@@ -239,6 +252,7 @@
 {"subject":"birthday sprite","predicate":"mgx:render-at","object":"sprite tier"}
 {"subject":"boat sprite","predicate":"mgx:render-at","object":"sprite tier"}
 {"subject":"body of water sprite","predicate":"mgx:render-at","object":"sprite tier"}
+{"subject":"book sprite","predicate":"mgx:render-at","object":"sprite tier"}
 {"subject":"boss sprite","predicate":"mgx:render-at","object":"sprite tier"}
 {"subject":"boy sprite","predicate":"mgx:render-at","object":"sprite tier"}
 {"subject":"bread sprite","predicate":"mgx:render-at","object":"sprite tier"}
@@ -251,6 +265,7 @@
 {"subject":"car sprite","predicate":"mgx:render-at","object":"sprite tier"}
 {"subject":"castle sprite","predicate":"mgx:render-at","object":"sprite tier"}
 {"subject":"cat sprite","predicate":"mgx:render-at","object":"sprite tier"}
+{"subject":"cellar sprite","predicate":"mgx:render-at","object":"sprite tier"}
 {"subject":"chair sprite","predicate":"mgx:render-at","object":"sprite tier"}
 {"subject":"champion sprite","predicate":"mgx:render-at","object":"sprite tier"}
 {"subject":"cheese sprite","predicate":"mgx:render-at","object":"sprite tier"}
@@ -272,6 +287,7 @@
 {"subject":"dinner sprite","predicate":"mgx:render-at","object":"sprite tier"}
 {"subject":"doctor sprite","predicate":"mgx:render-at","object":"sprite tier"}
 {"subject":"dog sprite","predicate":"mgx:render-at","object":"sprite tier"}
+{"subject":"drawing-room sprite","predicate":"mgx:render-at","object":"sprite tier"}
 {"subject":"dress sprite","predicate":"mgx:render-at","object":"sprite tier"}
 {"subject":"drink sprite","predicate":"mgx:render-at","object":"sprite tier"}
 {"subject":"driver sprite","predicate":"mgx:render-at","object":"sprite tier"}
@@ -348,6 +364,7 @@
 {"subject":"office sprite","predicate":"mgx:render-at","object":"sprite tier"}
 {"subject":"officer sprite","predicate":"mgx:render-at","object":"sprite tier"}
 {"subject":"owl sprite","predicate":"mgx:render-at","object":"sprite tier"}
+{"subject":"pan sprite","predicate":"mgx:render-at","object":"sprite tier"}
 {"subject":"parent sprite","predicate":"mgx:render-at","object":"sprite tier"}
 {"subject":"park sprite","predicate":"mgx:render-at","object":"sprite tier"}
 {"subject":"person sprite","predicate":"mgx:render-at","object":"sprite tier"}
@@ -388,6 +405,7 @@
 {"subject":"stranger sprite","predicate":"mgx:render-at","object":"sprite tier"}
 {"subject":"street sprite","predicate":"mgx:render-at","object":"sprite tier"}
 {"subject":"student sprite","predicate":"mgx:render-at","object":"sprite tier"}
+{"subject":"study sprite","predicate":"mgx:render-at","object":"sprite tier"}
 {"subject":"sugar sprite","predicate":"mgx:render-at","object":"sprite tier"}
 {"subject":"summer sprite","predicate":"mgx:render-at","object":"sprite tier"}
 {"subject":"sun sprite","predicate":"mgx:render-at","object":"sprite tier"}

package/corpus/worlds/manifest.json

@@ -3,7 +3,7 @@
   "generated": "by scripts/build-worlds-pack.mjs from corpus/worlds/src/",
   "counts": {
     "worlds": 2,
-    "facts": 548,
+    "facts": 575,
     "rules": 19
   },
   "budgets": {
@@ -14,8 +14,8 @@
   "sources": [
     {
       "file": "src/ashcombe-hall.jsonl",
-      "bytes": 8795,
-      "sha256": "771ed4e7a5e9046235e8dc193b2696f83e6ef92a556ca1ca126dd070927912ce"
+      "bytes": 11754,
+      "sha256": "18e58700a59ae3876dd4f949ede7fa17e19f3a8c2dc8ae4644dbddf98c138524"
     },
     {
       "file": "src/spider-fly.jsonl",
@@ -31,8 +31,8 @@
     },
     {
       "file": "shards/ashcombe-hall.jsonl.gz",
-      "bytes": 1020,
-      "sha256": "1255ea52149c3941fafd4ee462239bae8e10175c8e7db2e54c2c2dc1a2e0d924"
+      "bytes": 1292,
+      "sha256": "a8e61a93ebf992a8b87221c5a9a9f53bf92b7798cee86fb9d6915a1844d960dd"
     },
     {
       "file": "shards/spider-fly.jsonl.gz",

package/corpus/worlds/src/ashcombe-hall.jsonl

@@ -54,6 +54,33 @@
 {"world":"ashcombe-hall","kind":"fact","subject":"ashcombe hall","predicate":"mgx:hasA","object":"6 rooms"}
 {"world":"ashcombe-hall","kind":"fact","subject":"player","predicate":"mgx:hasA","object":"satchel"}
 {"world":"ashcombe-hall","kind":"fact","subject":"satchel","predicate":"mgx:usedFor","object":"carrying what the player takes"}
+{"world":"ashcombe-hall","kind":"fact","subject":"room","predicate":"rdfs:subClassOf","object":"space"}
+{"world":"ashcombe-hall","kind":"fact","subject":"outdoor-space","predicate":"rdfs:subClassOf","object":"space"}
+{"world":"ashcombe-hall","kind":"fact","subject":"underground-space","predicate":"rdfs:subClassOf","object":"space"}
+{"world":"ashcombe-hall","kind":"fact","subject":"garden","predicate":"rdf:type","object":"outdoor-space"}
+{"world":"ashcombe-hall","kind":"fact","subject":"cellar","predicate":"rdf:type","object":"underground-space"}
+{"world":"ashcombe-hall","kind":"fact","subject":"portrait","predicate":"rdfs:subClassOf","object":"painting"}
+{"world":"ashcombe-hall","kind":"fact","subject":"painting","predicate":"mgx:default-plane","object":"wall"}
+{"world":"ashcombe-hall","kind":"fact","subject":"furniture","predicate":"mgx:default-plane","object":"floor"}
+{"world":"ashcombe-hall","kind":"fact","subject":"portable","predicate":"mgx:default-plane","object":"floor"}
+{"world":"ashcombe-hall","kind":"fact","subject":"lamp","predicate":"mgx:on-top-of","object":"desk"}
+{"world":"ashcombe-hall","kind":"fact","subject":"book","predicate":"rdfs:subClassOf","object":"portable"}
+{"world":"ashcombe-hall","kind":"fact","subject":"pan","predicate":"rdfs:subClassOf","object":"portable"}
+{"world":"ashcombe-hall","kind":"fact","subject":"library","predicate":"mgx:default-contains","object":"book"}
+{"world":"ashcombe-hall","kind":"fact","subject":"kitchen","predicate":"mgx:default-contains","object":"pan"}
+{"world":"ashcombe-hall","kind":"fact","subject":"gardener","predicate":"mgx:knows-where","object":"letter"}
+{"world":"ashcombe-hall","kind":"fact","subject":"housekeeper","predicate":"mgx:knows-where","object":"key"}
+{"world":"ashcombe-hall","kind":"fact","subject":"butler","predicate":"mgx:knows-objective","object":"letter"}
+{"world":"ashcombe-hall","kind":"fact","subject":"butler","predicate":"mgx:knows-where","object":"housekeeper"}
+{"world":"ashcombe-hall","kind":"fact","subject":"butler","predicate":"mgx:knows-where","object":"cook"}
+{"world":"ashcombe-hall","kind":"fact","subject":"butler","predicate":"mgx:knows-where","object":"gardener"}
+{"world":"ashcombe-hall","kind":"fact","subject":"cook","predicate":"mgx:knows-where","object":"gardener"}
+{"world":"ashcombe-hall","kind":"fact","subject":"gardener","predicate":"mgx:knows-about","object":"garden"}
+{"world":"ashcombe-hall","kind":"fact","subject":"housekeeper","predicate":"mgx:knows-about","object":"study"}
+{"world":"ashcombe-hall","kind":"fact","subject":"butler","predicate":"mgx:knows-about","object":"drawing-room"}
+{"world":"ashcombe-hall","kind":"fact","subject":"cook","predicate":"mgx:knows-about","object":"kitchen"}
+{"world":"ashcombe-hall","kind":"fact","subject":"garden","predicate":"mgx:hasA","object":"old apple tree"}
+{"world":"ashcombe-hall","kind":"fact","subject":"kitchen","predicate":"mgx:usedFor","object":"cooking the hall's meals"}
 {"world":"ashcombe-hall","kind":"rule","name":"go","ruleKind":"action-signature","slots":{"subjectClass":"adventurer","targetClass":"room"}}
 {"world":"ashcombe-hall","kind":"rule","name":"go","ruleKind":"action-signature","slots":{"subjectClass":"person","targetClass":"room"}}
 {"world":"ashcombe-hall","kind":"rule","name":"go","ruleKind":"action-effect","slots":{"predicate":"currently-in","subjectRole":"subject","objectRole":"target"}}

package/data/sprites/book-icon.toml

@@ -0,0 +1,12 @@
+# book — the library's default portable: a closed hardback seen spine-on, the
+# cover boards and a page block, so a taken book reads as its own thing rather
+# than the generic portable box.
+classes = ["book"]
+svg = """
+<svg viewBox="0 0 24 24" aria-hidden="true">
+  <path d="M6 3 H18 A1 1 0 0 1 19 4 V20 A1 1 0 0 1 18 21 H6 Z" fill="currentColor"/>
+  <rect x="6" y="3" width="1.8" height="18" fill="currentColor" opacity="0.4"/>
+  <path d="M9.4 3 V21" stroke="currentColor" stroke-width="0.5" opacity="0.35"/>
+  <path d="M11 7.5 H17 M11 10 H17 M11 12.5 H15" stroke="#000000" stroke-width="0.5" opacity="0.3"/>
+</svg>
+"""

package/data/sprites/cellar-icon.toml

@@ -0,0 +1,12 @@
+# cellar — an underground space: a room box with a stair stepping down and
+# stone coursing, so the room-kind icon reads as below ground rather than a
+# plain room, matching the underground border.
+classes = ["cellar"]
+svg = """
+<svg viewBox="0 0 24 24" aria-hidden="true">
+  <rect x="3" y="3" width="18" height="18" rx="1" fill="currentColor" opacity="0.14"/>
+  <rect x="3" y="3" width="18" height="18" rx="1" fill="none" stroke="currentColor" stroke-width="1.6"/>
+  <path d="M6 8 H10 V11 H14 V14 H18 V18 H6 Z" fill="currentColor" opacity="0.55"/>
+  <path d="M3 12 H21 M3 16.5 H21" stroke="currentColor" stroke-width="0.5" opacity="0.4"/>
+</svg>
+"""

package/data/sprites/drawing-room-icon.toml

@@ -0,0 +1,13 @@
+# drawing-room — a room floor plan marked by a framed picture on the wall (the
+# portrait hangs here), so the room-kind icon reads as the drawing room rather
+# than a plain room.
+classes = ["drawing-room"]
+svg = """
+<svg viewBox="0 0 24 24" aria-hidden="true">
+  <rect x="3" y="3" width="18" height="18" rx="1" fill="currentColor" opacity="0.14"/>
+  <rect x="3" y="3" width="18" height="18" rx="1" fill="none" stroke="currentColor" stroke-width="1.6"/>
+  <rect x="8.5" y="7" width="7" height="6" rx="0.4" fill="none" stroke="currentColor" stroke-width="1.3"/>
+  <circle cx="12" cy="9.4" r="1.1" fill="currentColor" opacity="0.7"/>
+  <path d="M9.6 12.4 C9.6 10.9 10.6 10 12 10 C13.4 10 14.4 10.9 14.4 12.4 Z" fill="currentColor" opacity="0.7"/>
+</svg>
+"""

package/data/sprites/garden-icon.toml

@@ -0,0 +1,12 @@
+# garden — an outdoor space, so no room box: a tree over a ground line reads
+# as open air rather than an interior, matching the outdoor room-kind border.
+classes = ["garden"]
+svg = """
+<svg viewBox="0 0 24 24" aria-hidden="true">
+  <path d="M3 20 H21" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"/>
+  <path d="M12 20 V12" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"/>
+  <circle cx="12" cy="8.5" r="5" fill="currentColor" opacity="0.7"/>
+  <circle cx="7.5" cy="17" r="1" fill="currentColor" opacity="0.5"/>
+  <circle cx="16.5" cy="17" r="1" fill="currentColor" opacity="0.5"/>
+</svg>
+"""

package/data/sprites/kitchen-icon.toml

@@ -0,0 +1,13 @@
+# kitchen — a room floor plan marked by a stove with two burners, the same
+# distinguishing cue the large tier uses, so the room-kind icon reads as a
+# kitchen rather than a plain room.
+classes = ["kitchen"]
+svg = """
+<svg viewBox="0 0 24 24" aria-hidden="true">
+  <rect x="3" y="3" width="18" height="18" rx="1" fill="currentColor" opacity="0.14"/>
+  <rect x="3" y="3" width="18" height="18" rx="1" fill="none" stroke="currentColor" stroke-width="1.6"/>
+  <rect x="8" y="10" width="8" height="7" rx="0.6" fill="none" stroke="currentColor" stroke-width="1.2"/>
+  <circle cx="10.5" cy="12.6" r="1" fill="currentColor" opacity="0.7"/>
+  <circle cx="13.5" cy="12.6" r="1" fill="currentColor" opacity="0.7"/>
+</svg>
+"""

package/data/sprites/library-icon.toml

@@ -0,0 +1,12 @@
+# library — a room floor plan marked by an open book, so the room-kind icon
+# reads as a library rather than a plain room: the washed square is room.toml's
+# own shape, the two-page V is the same open-book cue the large tier uses.
+classes = ["library"]
+svg = """
+<svg viewBox="0 0 24 24" aria-hidden="true">
+  <rect x="3" y="3" width="18" height="18" rx="1" fill="currentColor" opacity="0.14"/>
+  <rect x="3" y="3" width="18" height="18" rx="1" fill="none" stroke="currentColor" stroke-width="1.6"/>
+  <path d="M12 9 C10.4 7.9 8.2 7.6 6.4 8.1 V15.6 C8.2 15.1 10.4 15.4 12 16.5 C13.6 15.4 15.8 15.1 17.6 15.6 V8.1 C15.8 7.6 13.6 7.9 12 9 Z" fill="currentColor" opacity="0.75"/>
+  <path d="M12 9 V16.5" stroke="currentColor" stroke-width="0.5" opacity="0.5"/>
+</svg>
+"""

package/data/sprites/pan-icon.toml

@@ -0,0 +1,11 @@
+# pan — the kitchen's default portable: a frying pan seen from above with a
+# long handle, so a taken pan reads as its own thing rather than the generic
+# portable box.
+classes = ["pan"]
+svg = """
+<svg viewBox="0 0 24 24" aria-hidden="true">
+  <circle cx="10" cy="14" r="6" fill="currentColor"/>
+  <circle cx="10" cy="14" r="3.6" fill="currentColor" opacity="0.35"/>
+  <rect x="15" y="13" width="7" height="2" rx="1" fill="currentColor"/>
+</svg>
+"""

package/data/sprites/study-icon.toml

@@ -0,0 +1,12 @@
+# study — a room floor plan marked by a writing desk against one wall, so the
+# room-kind icon reads as the study you start in rather than a plain room.
+classes = ["study"]
+svg = """
+<svg viewBox="0 0 24 24" aria-hidden="true">
+  <rect x="3" y="3" width="18" height="18" rx="1" fill="currentColor" opacity="0.14"/>
+  <rect x="3" y="3" width="18" height="18" rx="1" fill="none" stroke="currentColor" stroke-width="1.6"/>
+  <rect x="7" y="11" width="10" height="2.4" fill="currentColor" opacity="0.7"/>
+  <path d="M8 13.4 V17 M16 13.4 V17" stroke="currentColor" stroke-width="1.2"/>
+  <rect x="9.6" y="7.6" width="4.8" height="3" fill="none" stroke="currentColor" stroke-width="1"/>
+</svg>
+"""

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "2.10.3",
+  "version": "2.11.0",
   "private": false,
   "type": "module",
   "description": "The Mechanical Code Talker (tmct) — a tolerant, offline, $0 chat surface that guides you toward precision queries about a software repository. ELIZA/PARRY-style but domain-obsessed with code. No model calls; no codebase index of its own.",
@@ -45,6 +45,7 @@
     "./plan": "./src/domain/router/drive.mjs",
     "./generateCompletion": "./src/services/completions.mjs",
     "./createCompletionsGraphAdapter": "./src/services/completions.mjs",
+    "./ingest": "./src/services/extract-facts.mjs",
     "./repository-interface": "./src/adapters/repository-interface.mjs",
     "./conformance": "./src/tools/conformance.mjs"
   },
@@ -85,8 +86,11 @@
     "test": "node --disable-warning=ExperimentalWarning --test --test-concurrency=8 \"test/**/*.test.mjs\"",
     "test:smoke": "node --disable-warning=ExperimentalWarning --test test/smoke/*.test.mjs",
     "test:fast": "node --disable-warning=ExperimentalWarning --test --test-concurrency=8 test/smoke/*.test.mjs test/fast/*.test.mjs test/tools/ask.test.mjs test/tools/server.test.mjs test/estate/import-layers.test.mjs",
-    "test:e2e": "node --disable-warning=ExperimentalWarning --test \"e2e/**/*.test.mjs\"",
+    "test:e2e": "node --disable-warning=ExperimentalWarning --test \"e2e/*.test.mjs\"",
+    "test:e2e:heavy": "node --disable-warning=ExperimentalWarning --test \"e2e/heavy/*.test.mjs\"",
+    "check:readme": "TMCT_CHECK_README=1 node --disable-warning=ExperimentalWarning --test e2e/readme-examples.test.mjs",
     "e2e:browsers": "playwright install chromium",
+    "gen:screenshots": "node scripts/gen-screenshots.mjs",
     "check:links": "node scripts/check-links.mjs",
     "check:pii": "node scripts/pii-lint.mjs",
     "check:pack": "node scripts/check-pack-manifest.mjs",
@@ -139,6 +143,7 @@
     "build:spider-fly-bundle": "node scripts/build-spider-fly-bundle.mjs",
     "build:plan-bundle": "node scripts/build-plan-bundle.mjs",
     "build:ledger-bundle": "node scripts/build-ledger-bundle.mjs",
+    "build:ingest-bundle": "node scripts/build-ingest-bundle.mjs",
     "build:code-explorer-bundle": "node scripts/build-code-explorer-bundle.mjs",
     "build:electron": "node scripts/build-electron-app.mjs",
     "electron": "electron electron/main.mjs",