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

package/README.md

@@ -142,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
 ```
@@ -869,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

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.5",
+  "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.",
@@ -86,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",

package/src/adapters/corpus/wikipedia-live.mjs

@@ -13,24 +13,55 @@
 // The provider seam mirrors reference-pack.mjs's: registerLiveReferenceProvider
 // swaps the whole lookup behind one async { lookup(normTerm) } contract (tests
 // and the demo page stub it); null restores the default provider below.
+//
+// The research lane rides the same provider factory against
+// simple.wikipedia.org (registerResearchProvider/getResearchProvider below),
+// adding two fan-out reads: pageByTitle (an exact linked title costs ONE
+// round trip, no opensearch) and linkedTitles (the lead section's
+// namespace-0 links, document-ordered). Requests identify themselves per
+// Wikimedia's robot etiquette (WIKIMEDIA_USER_AGENT) and carry maxlag so an
+// overloaded replica set is backed off from, not hammered.
 
 import { normFactTerm } from "../../domain/hash.mjs";
 import { loadLexicon } from "../../domain/grammar/lexicon.mjs";
 import { isReferenceArticleRow, sentencesUpTo, isaOf, SUMMARY_CHAR_CAP } from "../../domain/reference-pack.mjs";
 
 export const WIKIPEDIA_LIVE_ORIGIN = "https://en.wikipedia.org";
+export const SIMPLE_WIKIPEDIA_ORIGIN = "https://simple.wikipedia.org";
+
+/** The identification string Wikimedia's robot policy asks API clients to
+ *  carry, pointing at this project's public site as the contact. Browsers
+ *  refuse to override the User-Agent request header, so the API-recognised
+ *  Api-User-Agent header carries the same string there; under Node both are
+ *  sent. */
+export const WIKIMEDIA_USER_AGENT = "the-mechanical-code-talker (+https://polycode-projects.gitlab.io/the-mechanical-code-talker/)";
 
 const DEFAULT_TIMEOUT_MS = 4000;
 const DEFAULT_MIN_INTERVAL_MS = 2000;
 const RETRY_AFTER_FLOOR_MS = 5000;
+// Action-API requests carry maxlag so an overloaded replica set answers with
+// an error we back off from instead of adding to its load (Wikimedia's own
+// recommended default for non-interactive clients).
+const MAXLAG_SECONDS = 5;
 
 /**
- * A live-lookup provider: { lookup(normTerm) -> article row | null }.
+ * A live-lookup provider: { lookup(normTerm) -> article row | null }, plus
+ * the research fan-out surface: pageByTitle(title) fetches an exact title's
+ * summary in ONE round trip (no opensearch — a linked title is already
+ * exact), and linkedTitles(title) lists the namespace-0 articles the page's
+ * LEAD section links to, in document order.
  *
  * `fetchImpl` defaults to the global fetch; `origin` to en.wikipedia.org;
  * `lexicon` (optional) feeds the isa extraction. The row shape is the shipped
  * pack's own ({ term, title, text, summary, url, revid, isa? }), validated by
  * isReferenceArticleRow before it is ever returned.
+ *
+ * Throttle posture: every public method takes one "slot" gated by the
+ * minimum interval, the single-flight guard and any open cool-off. By
+ * default a caller that asks too soon gets null (the chat's clean-miss hook
+ * must never block a turn); with `waitForSlot: true` the method WAITS for
+ * the slot instead — the research queue's posture, where a false miss would
+ * be dishonest and the caller is already paced turn-by-turn.
  */
 export function createWikipediaLiveProvider({
   fetchImpl,
@@ -38,6 +69,8 @@ export function createWikipediaLiveProvider({
   timeoutMs = DEFAULT_TIMEOUT_MS,
   minIntervalMs = DEFAULT_MIN_INTERVAL_MS,
   lexicon = null,
+  userAgent = WIKIMEDIA_USER_AGENT,
+  waitForSlot = false,
 } = {}) {
   const doFetch = fetchImpl ?? ((...args) => globalThis.fetch(...args));
   const cache = new Map(); // key -> row | null (hits AND settled misses)
@@ -45,18 +78,43 @@ export function createWikipediaLiveProvider({
   let coolOffUntil = 0;
   let inFlight = false;
 
+  const identifyingHeaders = () => {
+    if (!userAgent) return null;
+    const headers = { "Api-User-Agent": userAgent };
+    // A browser strips User-Agent as a forbidden header; only set it where
+    // no DOM says we are one (Node ships a global `navigator` these days, so
+    // `document` is the discriminating global).
+    if (typeof document === "undefined") headers["User-Agent"] = userAgent;
+    return headers;
+  };
+
+  function openCoolOff(retryAfterSeconds) {
+    const retryAfterMs = Number(retryAfterSeconds) * 1000;
+    coolOffUntil = Date.now() + Math.max(retryAfterMs || 0, RETRY_AFTER_FLOOR_MS);
+  }
+
   async function fetchJson(url) {
     const controller = typeof AbortController === "function" ? new AbortController() : null;
     const timer = controller ? setTimeout(() => controller.abort(), timeoutMs) : null;
     try {
-      const res = await doFetch(url, controller ? { signal: controller.signal } : {});
+      const opts = {};
+      if (controller) opts.signal = controller.signal;
+      const headers = identifyingHeaders();
+      if (headers) opts.headers = headers;
+      const res = await doFetch(url, opts);
       if (res.status === 429) {
-        const retryAfterMs = Number(res.headers?.get?.("retry-after")) * 1000;
-        coolOffUntil = Date.now() + Math.max(retryAfterMs || 0, RETRY_AFTER_FLOOR_MS);
+        openCoolOff(res.headers?.get?.("retry-after"));
         return null;
       }
       if (!res.ok) return null;
-      return await res.json();
+      const body = await res.json();
+      // A maxlag rejection arrives as HTTP 200 with an error body (and a
+      // Retry-After header) — back off exactly as a 429 asks.
+      if (body?.error?.code === "maxlag") {
+        openCoolOff(res.headers?.get?.("retry-after"));
+        return null;
+      }
+      return body;
     } catch {
       return null;
     } finally {
@@ -64,6 +122,26 @@ export function createWikipediaLiveProvider({
     }
   }
 
+  /** When the next network slot opens: past the cool-off, past the minimum
+   *  interval since the last taken slot. */
+  const slotOpensAt = () => Math.max(coolOffUntil, lastLookupAt + minIntervalMs);
+
+  /** Take the one network slot, or report it unavailable. Default posture
+   *  returns false immediately (the clean-miss hook's "null, never block");
+   *  `waitForSlot` sleeps until the slot opens instead. */
+  async function takeSlot() {
+    for (;;) {
+      const now = Date.now();
+      if (!inFlight && now >= slotOpensAt()) {
+        lastLookupAt = now;
+        inFlight = true;
+        return true;
+      }
+      if (!waitForSlot) return false;
+      await new Promise((resolve) => setTimeout(resolve, Math.max(slotOpensAt() - now, 25)));
+    }
+  }
+
   /** The opensearch title whose normFactTerm fold equals or extends the key —
    *  the topic-drift guard: "quasar" may resolve to "Quasar" or "Quasars",
    *  never to a first suggestion about something else. */
@@ -76,12 +154,7 @@ export function createWikipediaLiveProvider({
     return null;
   }
 
-  async function roundTrips(key) {
-    const search = await fetchJson(
-      `${origin}/w/api.php?action=opensearch&format=json&origin=*&search=${encodeURIComponent(key)}&limit=3`,
-    );
-    const title = search ? matchingTitle(key, search) : null;
-    if (!title) return null;
+  async function summaryRow(key, title) {
     const summary = await fetchJson(
       `${origin}/api/rest_v1/page/summary/${encodeURIComponent(title.replace(/ /g, "_"))}`,
     );
@@ -103,25 +176,77 @@ export function createWikipediaLiveProvider({
     return isReferenceArticleRow(row) ? row : null;
   }
 
+  async function roundTrips(key) {
+    const search = await fetchJson(
+      `${origin}/w/api.php?action=opensearch&format=json&origin=*&maxlag=${MAXLAG_SECONDS}&search=${encodeURIComponent(key)}&limit=3`,
+    );
+    const title = search ? matchingTitle(key, search) : null;
+    if (!title) return null;
+    return summaryRow(key, title);
+  }
+
+  /** One slot-gated, cached operation: cache first (a settled hit or miss is
+   *  never refetched), then the slot, then `work()`, with every failure
+   *  cached as null so it never costs a second round trip. */
+  async function cachedFetch(cacheKey, work) {
+    if (cache.has(cacheKey)) return cache.get(cacheKey);
+    if (!(await takeSlot())) return null;
+    let value = null;
+    try {
+      value = await work();
+    } catch {
+      value = null;
+    } finally {
+      inFlight = false;
+    }
+    cache.set(cacheKey, value);
+    return value;
+  }
+
   return {
     async lookup(normTerm) {
       const key = String(normTerm ?? "");
       if (!key) return null;
-      if (cache.has(key)) return cache.get(key);
-      const now = Date.now();
-      if (inFlight || now < coolOffUntil || now - lastLookupAt < minIntervalMs) return null;
-      lastLookupAt = now;
-      inFlight = true;
-      let row = null;
-      try {
-        row = await roundTrips(key);
-      } catch {
-        row = null;
-      } finally {
-        inFlight = false;
-      }
-      cache.set(key, row);
-      return row;
+      return cachedFetch(key, () => roundTrips(key));
+    },
+
+    /** The summary for an EXACT title — one round trip, no opensearch. The
+     *  research queue's depth-1 fetch: a linked title came from the wiki
+     *  itself, so the fuzzy title match would only waste a request. */
+    async pageByTitle(title) {
+      const t = String(title ?? "").trim();
+      if (!t) return null;
+      return cachedFetch(`title\0${normFactTerm(t)}`, () => summaryRow(normFactTerm(t), t));
+    },
+
+    /** The namespace-0 articles the page's LEAD section links to, in document
+     *  order, capped at `limit`. One action-API round trip
+     *  (action=parse&prop=links&section=0): the lead is the smallest payload
+     *  that still orders links by how the article introduces its topic —
+     *  a full-page prop=links listing is alphabetical, which would make the
+     *  fan-out pick by spelling instead of relevance. Null on any failure. */
+    async linkedTitles(title, { limit = 25 } = {}) {
+      const t = String(title ?? "").trim();
+      if (!t) return null;
+      const listed = await cachedFetch(`links\0${normFactTerm(t)}`, async () => {
+        const parsed = await fetchJson(
+          `${origin}/w/api.php?action=parse&format=json&formatversion=2&origin=*&maxlag=${MAXLAG_SECONDS}&prop=links&redirects=1&page=${encodeURIComponent(t)}&section=0`,
+        );
+        const links = parsed?.parse?.links;
+        if (!Array.isArray(links)) return null;
+        const seen = new Set();
+        const out = [];
+        for (const link of links) {
+          if (!link || link.ns !== 0 || link.exists === false) continue;
+          const linkTitle = String(link.title ?? link["*"] ?? "").trim();
+          const folded = normFactTerm(linkTitle);
+          if (!linkTitle || !folded || seen.has(folded)) continue;
+          seen.add(folded);
+          out.push(linkTitle);
+        }
+        return out;
+      });
+      return Array.isArray(listed) ? listed.slice(0, Math.max(0, limit)) : null;
     },
   };
 }
@@ -143,3 +268,34 @@ export function getLiveReferenceProvider() {
   if (!defaultProvider) defaultProvider = createWikipediaLiveProvider();
   return defaultProvider;
 }
+
+// ---- the research lane's provider: Simple English Wikipedia, waiting slots --
+
+let defaultResearchProvider = null;
+let registeredResearchProvider = null;
+
+/** Swap the research lane's lookup: provider = { lookup, pageByTitle,
+ *  linkedTitles } (tests and the demo pages stub it, same seam shape as
+ *  registerLiveReferenceProvider). Pass null to restore the default
+ *  simple.wikipedia.org provider. */
+export function registerResearchProvider(provider) {
+  registeredResearchProvider = provider && typeof provider.lookup === "function" ? provider : null;
+}
+
+/** The research lane's active provider — the registered one, else one lazily
+ *  created singleton against simple.wikipedia.org with `waitForSlot` on: the
+ *  queue is paced turn-by-turn, so a throttled step WAITS for its polite slot
+ *  rather than reporting a false miss. `minIntervalMs` (first call only —
+ *  the singleton keeps its throttle clock) can only ever RAISE the interval;
+ *  the shipped minimum stays the floor. */
+export function getResearchProvider({ minIntervalMs } = {}) {
+  if (registeredResearchProvider) return registeredResearchProvider;
+  if (!defaultResearchProvider) {
+    defaultResearchProvider = createWikipediaLiveProvider({
+      origin: SIMPLE_WIKIPEDIA_ORIGIN,
+      waitForSlot: true,
+      minIntervalMs: Math.max(DEFAULT_MIN_INTERVAL_MS, Number(minIntervalMs) || 0),
+    });
+  }
+  return defaultResearchProvider;
+}