@polycode-projects/the-mechanical-code-talker 4.1.8 → 5.0.0

package/README.md

@@ -1408,7 +1408,7 @@ writes graded rows you can diff between runs:
 
 - `npm run chatbench:run` measures chat quality against CEFR-graded English
   cases with deterministic tier-1 checks (the full tuning loop is in
-  `SKILL_BENCHMARK_CEFR_ENGLISH.md`);
+  `.claude/skills/benchmark-cefr-english/SKILL.md`);
 - `npm run infbench` generates inference cases, then runs each through both
   drive points, the reasoning kernel and the chat surface;
 - `npm run agentbench:run` measures the tool-loop behaviour, and every

package/data/mudiii-assets.json

@@ -0,0 +1,201 @@
+{
+  "_readme": [
+    "Closed allowlist. A later copy agent may copy ONLY the exact sourcePath -> destPath pairs listed in `assets` below, and must not read, list, or copy anything else out of ../world-of-claudecraft. If a model isn't a row here, it doesn't get copied, no matter how well it fits.",
+    "The eastbrook_* trap: those files sit alphabetically right next to the correct ones and look better, but CREDITS.md licenses the whole eastbrook_* kit 'With the project only' (ships with that project, not extractable into a standalone demo like mudiii.html). Take the unprefixed sibling every time: market_stand_1.glb not eastbrook_market_stall.glb, inn.glb not eastbrook_inn.glb, blacksmith.glb not eastbrook_smithy.glb, well.glb not eastbrook_civic_well_beacon.glb.",
+    "Every GLB listed here uses EXT_meshopt_compression and KHR_mesh_quantization (verified by parsing each file's JSON chunk directly, not by trusting docs). Three additionally use EXT_texture_webp: creatures/goblin.glb, foliage/oak_1.glb, foliage/bush.glb. three.js's GLTFLoader decodes KHR_mesh_quantization and EXT_texture_webp natively, so nobody needs to hunt for a decoder for either of those. EXT_meshopt_compression is the one exception and needs exactly one line: loader.setMeshoptDecoder(MeshoptDecoder). See commands.vendorMeshoptDecoderLine below, and commands.fallbackTranscodeToPlainGlb if vendoring the decoder turns out to be undesirable.",
+    "Food markers (cheese, apples, apple crate) are primitive geometry in v1, not models. The KayKit food props (food_cheese, food_apple_*, food_crate_large_apples) are almost certainly CC0 at source, but no CREDITS.md row names a KayKit resource pack, so they're unrecorded rather than free to take and are excluded here. Fetching the genuine KayKit Resource Bits pack from source (https://kaykit.itch.io) and adding a CREDITS.md row for it is a clean later upgrade, not a wall.",
+    "The predator is creatures/fox.glb, not creatures/wolf_basic.glb. wolf_basic.glb looks like the obvious predator model and is close in name to the CREDITS 'Animated creatures' row, but wolf_basic.glb itself is an unrecorded custom Tripo-generated project asset, not the CC0 Quaternius wolf. fox.glb is covered by the CC0 Quaternius creatures row by name, shares the same quadruped rig (Idle/Walk/Gallop/Attack/hit-react/Death via manifest.ts's animal() clip map), and additionally ships an 'Eating' clip verified in the GLB itself -- useful for an eaten-flourish. goblin.glb is the prey/scavenger, matching world-of-claudecraft's own mob_kobold casting (Idle/Walk/Run/Attack/HitRecieve/Death) -- note HitRecieve is misspelled in the asset itself and is reproduced verbatim below, not corrected.",
+    "targetHeight is the model's own measured bounding-box height in metres (computed from each GLB's POSITION accessor bounds through its node transform chain, dequantizing normalized SHORT/BYTE components first), not an arbitrary guess -- these packs already ship in a consistent real-world scale, so no further per-item normalization judgment call was needed for the static props. The two character rigs (fox, goblin) use world-of-claudecraft's own manifest.ts height values instead, since their POSITION accessors are in skinned bind-pose space and a plain node-transform bbox walk (as used for the static props) does not account for joint transforms."
+  ],
+  "commands": {
+    "verifyBytes": "stat -f '%z' <file>   # BSD/macOS; use `stat -c '%s' <file>` on GNU/Linux",
+    "verifySha256": "shasum -a 256 <file>",
+    "vendorMeshoptDecoderLine": "loader.setMeshoptDecoder(MeshoptDecoder)  // three.js GLTFLoader; the only line meshopt compression needs -- quantization and webp need nothing",
+    "fallbackTranscodeToPlainGlb": "npx gltf-transform copy <in>.glb <out>.glb   # decodes EXT_meshopt_compression on read; since no compress step is re-applied, the written GLB carries plain (uncompressed) buffers -- use only if vendoring the decoder is undesirable"
+  },
+  "assets": [
+    {
+      "key": "fox",
+      "sourcePath": "public/models/creatures/fox.glb",
+      "destPath": "public/models/creatures/fox.glb",
+      "licence": "CC0-1.0",
+      "author": "Quaternius",
+      "source": "https://poly.pizza/u/Quaternius · https://quaternius.com",
+      "bytes": 332748,
+      "sha256": "2694028b47e84bad3b9d985aa7743dae02a3bcfddd6becd73b46c747a1e067b3",
+      "targetHeight": 1.0,
+      "clips": {
+        "idle": "Idle",
+        "walk": "Walk",
+        "run": "Gallop",
+        "attack": "Attack",
+        "hit": ["Idle_HitReact_Left", "Idle_HitReact_Right"],
+        "death": "Death",
+        "eat": "Eating"
+      }
+    },
+    {
+      "key": "goblin",
+      "sourcePath": "public/models/creatures/goblin.glb",
+      "destPath": "public/models/creatures/goblin.glb",
+      "licence": "CC0-1.0",
+      "author": "Quaternius",
+      "source": "https://poly.pizza/u/Quaternius · https://quaternius.com",
+      "bytes": 47924,
+      "sha256": "2f02ce927a8871554f3931655d75f1abb8237d36be8a19a35b09920d0812bc3c",
+      "targetHeight": 2.1,
+      "clips": {
+        "idle": "Idle",
+        "walk": "Walk",
+        "run": "Run",
+        "attack": "Attack",
+        "hit": ["HitRecieve"],
+        "death": "Death"
+      }
+    },
+    {
+      "key": "well",
+      "sourcePath": "public/models/props/well.glb",
+      "destPath": "public/models/props/well.glb",
+      "licence": "CC0-1.0",
+      "author": "Quaternius",
+      "source": "https://quaternius.com/packs/medievalvillage.html",
+      "bytes": 27788,
+      "sha256": "9308ba09ea3bed048984eeb14307b0557c5ea11404556d33afa9ed904b6ee123",
+      "targetHeight": 1.25,
+      "clips": null
+    },
+    {
+      "key": "house-1",
+      "sourcePath": "public/models/props/house_1.glb",
+      "destPath": "public/models/props/house_1.glb",
+      "licence": "CC0-1.0",
+      "author": "Quaternius",
+      "source": "https://quaternius.com/packs/medievalvillage.html",
+      "bytes": 84484,
+      "sha256": "87c8306f95e335ce01150ef3fb90b52cabc15e047077f98d1f25df8d76a95b9e",
+      "targetHeight": 3.39,
+      "clips": null
+    },
+    {
+      "key": "house-2",
+      "sourcePath": "public/models/props/house_2.glb",
+      "destPath": "public/models/props/house_2.glb",
+      "licence": "CC0-1.0",
+      "author": "Quaternius",
+      "source": "https://quaternius.com/packs/medievalvillage.html",
+      "bytes": 103180,
+      "sha256": "ede3299a2b09bdf66fc56cb56187ae1cdd673ee23eb44b75a40aa38cd8855e93",
+      "targetHeight": 3.25,
+      "clips": null
+    },
+    {
+      "key": "house-3",
+      "sourcePath": "public/models/props/house_3.glb",
+      "destPath": "public/models/props/house_3.glb",
+      "licence": "CC0-1.0",
+      "author": "Quaternius",
+      "source": "https://quaternius.com/packs/medievalvillage.html",
+      "bytes": 43696,
+      "sha256": "3b426a1d8894d3423c0a32c61527dfcbf79e9c0727fa9b83889cf6fa93d9b969",
+      "targetHeight": 1.07,
+      "clips": null
+    },
+    {
+      "key": "inn",
+      "sourcePath": "public/models/props/inn.glb",
+      "destPath": "public/models/props/inn.glb",
+      "licence": "CC0-1.0",
+      "author": "Quaternius",
+      "source": "https://quaternius.com/packs/medievalvillage.html",
+      "bytes": 92748,
+      "sha256": "a1386fe4db504f5110df670b91f4e5f6fdc3baf545cc023fb21ebcc457867a04",
+      "targetHeight": 3.49,
+      "clips": null
+    },
+    {
+      "key": "blacksmith",
+      "sourcePath": "public/models/props/blacksmith.glb",
+      "destPath": "public/models/props/blacksmith.glb",
+      "licence": "CC0-1.0",
+      "author": "Quaternius",
+      "source": "https://quaternius.com/packs/medievalvillage.html",
+      "bytes": 97444,
+      "sha256": "893c49e06a5c7e5967caad0a666666fb898f3d6823e81dec66b8cf96b3aca3ac",
+      "targetHeight": 3.0,
+      "clips": null
+    },
+    {
+      "key": "market-stall-1",
+      "sourcePath": "public/models/props/market_stand_1.glb",
+      "destPath": "public/models/props/market_stand_1.glb",
+      "licence": "CC0-1.0",
+      "author": "Quaternius",
+      "source": "https://quaternius.com/packs/medievalvillage.html",
+      "bytes": 25184,
+      "sha256": "d59645bb16549882280e091e41804cca09dac4a693772960bde0418e5d0229b5",
+      "targetHeight": 1.05,
+      "clips": null
+    },
+    {
+      "key": "market-stall-2",
+      "sourcePath": "public/models/props/market_stand_2.glb",
+      "destPath": "public/models/props/market_stand_2.glb",
+      "licence": "CC0-1.0",
+      "author": "Quaternius",
+      "source": "https://quaternius.com/packs/medievalvillage.html",
+      "bytes": 18868,
+      "sha256": "b81f32ab47d17e5b76386814554fe5c1419189049c727d5b84a46a2278ce3597",
+      "targetHeight": 1.04,
+      "clips": null
+    },
+    {
+      "key": "cart",
+      "sourcePath": "public/models/props/cart.glb",
+      "destPath": "public/models/props/cart.glb",
+      "licence": "CC0-1.0",
+      "author": "Quaternius",
+      "source": "https://quaternius.com/packs/medievalvillage.html",
+      "bytes": 30972,
+      "sha256": "8bb07d235482439d0e4f1d9152d932b6487cdb09b3331c668f882461401f43d9",
+      "targetHeight": 0.8,
+      "clips": null
+    },
+    {
+      "key": "fence",
+      "sourcePath": "public/models/props/fence.glb",
+      "destPath": "public/models/props/fence.glb",
+      "licence": "CC0-1.0",
+      "author": "Quaternius",
+      "source": "https://quaternius.com/packs/medievalvillage.html",
+      "bytes": 4836,
+      "sha256": "ff22bf2593398774f20e7e6f82f3a9184e326cc4c45cd780a0981590a54172c0",
+      "targetHeight": 0.33,
+      "clips": null
+    },
+    {
+      "key": "oak-tree",
+      "sourcePath": "public/models/foliage/oak_1.glb",
+      "destPath": "public/models/foliage/oak_1.glb",
+      "licence": "CC0-1.0",
+      "author": "Quaternius",
+      "source": "https://quaternius.itch.io/stylized-nature-megakit",
+      "bytes": 184216,
+      "sha256": "e8c8b7e02173490bfe5e802fad47c1b7824b787bb6c9274163bde7fda065c102",
+      "targetHeight": 7.26,
+      "clips": null
+    },
+    {
+      "key": "bush",
+      "sourcePath": "public/models/foliage/bush.glb",
+      "destPath": "public/models/foliage/bush.glb",
+      "licence": "CC0-1.0",
+      "author": "Quaternius",
+      "source": "https://quaternius.itch.io/stylized-nature-megakit",
+      "bytes": 49064,
+      "sha256": "614172ada35fc6048487a6af6d77059a5c031e0a93eff9d58036649ea0d16c12",
+      "targetHeight": 1.57,
+      "clips": null
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "4.1.8",
+  "version": "5.0.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; indexes a repo on request (tmct index) or reads any producer's graph.",
@@ -162,11 +162,13 @@
     "build:research-bundle": "node scripts/build-research-bundle.mjs",
     "build:code-explorer-bundle": "node scripts/build-code-explorer-bundle.mjs",
     "build:mud-bundle": "node scripts/build-mud-bundle.mjs",
+    "build:mudiii-bundle": "node scripts/build-mudiii-bundle.mjs",
     "build:electron": "node scripts/build-electron-app.mjs",
     "electron": "electron electron/main.mjs",
     "test:electron": "node --test electron/smoke.test.mjs",
     "build:sprites-bundle": "node scripts/build-sprites-bundle.mjs",
     "build:wink-vendor": "node scripts/build-wink-vendor.mjs",
+    "build:three-vendor": "node scripts/build-three-vendor.mjs",
     "build:chat-seed": "node scripts/build-chat-seed.mjs",
     "build:demo-graph": "node scripts/build-demo-graph.mjs",
     "build:demo-pack": "node scripts/build-demo-pack.mjs",
@@ -190,6 +192,7 @@
     "ink-testing-library": "4.0.0",
     "playwright": "1.61.1",
     "publint": "0.3.21",
+    "three": "0.185.1",
     "yaml": "2.9.0"
   }
 }

package/src/domain/agent-belief.mjs

@@ -0,0 +1,96 @@
+// agent-belief.mjs — what one agent believes about where another agent or
+// item is, this tick. Ground truth inside its own vision radius, else the
+// newest position it was told, else nothing at all. The "nothing at all" rung
+// is the point: an agent that has not seen and has not been told believes
+// nothing, and a deceived agent stays visibly wrong until it looks.
+//
+// Vision is a plain Chebyshev radius with NO line of sight. Buildings block
+// movement (a world pack omits its mgx:has-exit-* edges into an occupied cell)
+// and do not block sight. Anyone tempted to add a raycast here should know
+// that nothing else in the engine models occlusion, so belief would then
+// disagree with the planner, the goal line and the belief panel at once.
+//
+// The module imports nothing, deliberately. Every world that runs on the
+// planning engine shares it, and each world sizes its own board, so belief
+// must not inherit any one world's grid constants. Asking a world for its
+// clipped list of visible cells is what once bound this test to a 10x10 board
+// and made every cell outside it invisible on a larger one.
+
+export const DEFAULT_VISION_RADIUS = 4;
+
+const CELL_ID_RE = /^cell-(\d+)-(\d+)$/;
+
+const cellCoordsOf = (id) => {
+  const m = CELL_ID_RE.exec(String(id ?? ""));
+  return m ? { x: Number(m[1]), y: Number(m[2]) } : null;
+};
+
+const cellIdOf = (x, y) => `cell-${x}-${y}`;
+
+const chebyshevSteps = (ax, ay, bx, by) => Math.max(Math.abs(ax - bx), Math.abs(ay - by));
+
+/** Where `observerSubject` currently believes `targetSubject` to be, as an
+ *  `{ x, y }` cell, or null for no belief at all.
+ *
+ *  Four rungs, in order:
+ *
+ *  1. A target the board has removed (eaten, starved, hatched) is believed
+ *     nowhere, and no told fact can put it back. A claim about an id that was
+ *     never placed at all is a different case and still lands, which is what
+ *     keeps deception working.
+ *  2. Ground truth, when the target's real cell sits within `visionRadius`
+ *     Chebyshev steps of `observerCell`.
+ *  3. The newest told fact addressed to this observer about this target —
+ *     `opts.toldFacts` rows shaped `{ subject, toAgent, cell, turn }`.
+ *  4. Otherwise null.
+ *
+ *  `state` is a folded world state: `.placements` (subject -> `{ cell }`) and
+ *  `.removed` (a Set of subjects off the board). Pure. */
+export function believedCellOf(targetSubject, observerSubject, observerCell, state, opts = {}) {
+  if (state.removed.has(targetSubject)) return null;
+  const { visionRadius = DEFAULT_VISION_RADIUS, toldFacts = [] } = opts;
+  const place = state.placements.get(targetSubject);
+  const at = place ? cellCoordsOf(place.cell) : null;
+  if (at && chebyshevSteps(observerCell.x, observerCell.y, at.x, at.y) <= visionRadius) return at;
+  const told = toldFacts
+    .filter((f) => f.toAgent === observerSubject && f.subject === targetSubject)
+    .sort((a, b) => (b.turn ?? 0) - (a.turn ?? 0))[0];
+  return told ? cellCoordsOf(told.cell) : null;
+}
+
+/** The nearest candidate (by believed Chebyshev distance) an observer has
+ *  any belief about at all — null when the observer believes nothing about
+ *  any candidate. `candidates` must already be in a deterministic order
+ *  (ties favor the earlier candidate). */
+export function nearestBelievedTarget(observerSubject, observerCell, candidates, state, opts = {}) {
+  let best = null;
+  let bestDist = Infinity;
+  for (const subject of candidates) {
+    const cell = believedCellOf(subject, observerSubject, observerCell, state, opts);
+    if (!cell) continue;
+    const dist = chebyshevSteps(observerCell.x, observerCell.y, cell.x, cell.y);
+    if (dist < bestDist) { bestDist = dist; best = { subject, cell }; }
+  }
+  return best;
+}
+
+/** A full "world knowledge graph" snapshot for one observer this tick: every
+ *  OTHER named candidate's believed cell (believedCellOf — ground truth
+ *  inside vision, else the newest told fact addressed to this observer,
+ *  else null for "unknown") — feeds a per-agent belief panel. Deliberately
+ *  never ground truth: showing the observer's own honest gap
+ *  between belief and reality (visibly widened by a deceiving pill or a fed
+ *  false fact) is the whole point of that panel. Returns a plain
+ *  `{ [candidateId]: cellId | null }` map. Exported as the read path for
+ *  what one agent can currently observe — every caller (a tick loop, a viz
+ *  panel, a chat lane) reads the same computation, never a re-derived copy
+ *  of it. */
+export function beliefSnapshotFor(observerSubject, observerCell, candidateIds, state, opts) {
+  const belief = {};
+  for (const candidateId of candidateIds) {
+    if (candidateId === observerSubject) continue;
+    const cell = believedCellOf(candidateId, observerSubject, observerCell, state, opts);
+    belief[candidateId] = cell ? cellIdOf(cell.x, cell.y) : null;
+  }
+  return belief;
+}

package/src/domain/answer-variants.json

@@ -10,7 +10,7 @@
         "ask.mjs metaFallbackEntityAnswer (\"X is a Y in this codebase, defined in Z ...\")"
       ],
       "deliberatelyNotUsedBy": [
-        "ask.mjs renderCore whereShape (\"X is defined in Y at line(s) Z\" / \"X is defined in Y (no line span...)\") -- test-benchmarks/chatbench/graded-pool-max.jsonl pins this exact substring as ground truth for 11 'where is X defined' cases (2 in the always-run promoted subset), and that pool is append-only/never-edited-mid-arc per SKILL_BENCHMARK_CEFR_ENGLISH.md."
+        "ask.mjs renderCore whereShape (\"X is defined in Y at line(s) Z\" / \"X is defined in Y (no line span...)\") -- test-benchmarks/chatbench/graded-pool-max.jsonl pins this exact substring as ground truth for 11 'where is X defined' cases (2 in the always-run promoted subset), and that pool is append-only/never-edited-mid-arc per .claude/skills/benchmark-cefr-english/SKILL.md."
       ]
     },
     "is-dated": {

package/src/domain/game-config.mjs

@@ -56,11 +56,43 @@ export const DEFAULT_GAME_CONFIG = Object.freeze({
     meerkatSpeed: 1,
     meerkatDigReach: 1,
   }),
+  // The town square's knobs are keyed by role, not by species: its cast is a
+  // predator/prey pair by construction, so a later pair is a new roles object
+  // and no edit here. (mud above went the other way because its cast is
+  // authored per world.) The drains sit on mud's scale against the deck's own
+  // 400-turn default: a prey that never eats starves after about 133 turns, a
+  // predator after 250.
+  //
+  // maxPreyPopulation and maxFoodItems are the two knobs that keep that
+  // arithmetic from running away. Prey arrive every 5 turns and live ~133, so
+  // an uncapped 400-turn run ends with roughly 80 of them on a 144-cell board
+  // — a solid carpet of goblins, and every tick paying for their planning.
+  // Food spawns faster still. Both caps are checked before a spawn, so
+  // reaching one simply skips that turn's arrival.
+  mudiii: Object.freeze({
+    predatorInitialMass: 20,
+    predatorMassDecrementPerTurn: 0.08,
+    predatorVisionRadius: 4,
+    preyInitialMass: 8,
+    preyMassDecrementPerTurn: 0.06,
+    preyVisionRadius: 3,
+    preySpawnIntervalTurns: 5,
+    foodSpawnIntervalTurns: 3,
+    spawnedFoodMass: 1,
+    placedFoodMass: 2,
+    maxPreyPopulation: 6,
+    maxFoodItems: 8,
+  }),
   guessNumber: Object.freeze({
     defaultLo: 1,
     defaultHi: 100,
     maxBound: 1_000_000_000,
   }),
+  // Whether the adventure surface accepts teaching. One knob behind a page
+  // checkbox, the CLI flag and the corpus rows, so all three agree.
+  adventure: Object.freeze({
+    teach: false,
+  }),
   planning: Object.freeze({
     maxDepth: 300,
   }),
@@ -107,6 +139,25 @@ const MUD_KEY_MAP = Object.freeze({
   meerkat_dig_reach: "meerkatDigReach",
 });
 
+const MUDIII_KEY_MAP = Object.freeze({
+  predator_initial_mass: "predatorInitialMass",
+  predator_mass_decrement_per_turn: "predatorMassDecrementPerTurn",
+  predator_vision_radius: "predatorVisionRadius",
+  prey_initial_mass: "preyInitialMass",
+  prey_mass_decrement_per_turn: "preyMassDecrementPerTurn",
+  prey_vision_radius: "preyVisionRadius",
+  prey_spawn_interval_turns: "preySpawnIntervalTurns",
+  food_spawn_interval_turns: "foodSpawnIntervalTurns",
+  spawned_food_mass: "spawnedFoodMass",
+  placed_food_mass: "placedFoodMass",
+  max_prey_population: "maxPreyPopulation",
+  max_food_items: "maxFoodItems",
+});
+
+const ADVENTURE_KEY_MAP = Object.freeze({
+  teach: "teach",
+});
+
 const GUESS_NUMBER_KEY_MAP = Object.freeze({
   default_lo: "defaultLo",
   default_hi: "defaultHi",
@@ -154,6 +205,18 @@ export function massScaleFor(cls, config) {
   return null;
 }
 
+/** The mass denominator a town-square HUD bar scales against, from a resolved
+ *  `mudiii` section. `role` is "predator" or "prey"; anything else — a crumb,
+ *  a prop, a role a later cast adds — has no denominator and gets null, never
+ *  a guessed number. Separate from massScaleFor above on purpose: that one
+ *  takes a species literal off the spider-and-fly page, and folding a second
+ *  vocabulary into it would turn a two-line read into a registry. Pure. */
+export function mudiiiMassScaleFor(role, config) {
+  if (role === "predator") return config?.predatorInitialMass ?? null;
+  if (role === "prey") return config?.preyInitialMass ?? null;
+  return null;
+}
+
 /**
  * Fold a normalized tmct.toml's `games`/`planning` tables (the raw sparse
  * pass-through src/adapters/toml-config.mjs's normalizeConfig produces —
@@ -168,7 +231,9 @@ export function resolveGameConfig(toml) {
   return {
     spiderFly: mergeSection(DEFAULT_GAME_CONFIG.spiderFly, games["spider-fly"], SPIDER_FLY_KEY_MAP),
     mud: mergeSection(DEFAULT_GAME_CONFIG.mud, games.mud, MUD_KEY_MAP),
+    mudiii: mergeSection(DEFAULT_GAME_CONFIG.mudiii, games.mudiii, MUDIII_KEY_MAP),
     guessNumber: mergeSection(DEFAULT_GAME_CONFIG.guessNumber, games["guess-number"], GUESS_NUMBER_KEY_MAP),
+    adventure: mergeSection(DEFAULT_GAME_CONFIG.adventure, games.adventure, ADVENTURE_KEY_MAP),
     planning: mergeSection(DEFAULT_GAME_CONFIG.planning, toml?.planning, PLANNING_KEY_MAP),
   };
 }

package/src/services/adventure-editor.mjs

@@ -358,6 +358,42 @@ export function planWorldEditorSync(rows, state, triples) {
   return { toAppend, toRemoveIds };
 }
 
+/** The additive half of planWorldEditorSync, for ONE already-parsed triple:
+ *  the rows a single taught sentence implies, and never a retraction. A whole
+ *  document says what the world contains, so a fact missing from it has gone;
+ *  one sentence only ever says what it says, so nothing it leaves out is
+ *  evidence of anything. Re-asserting a fact the world already holds appends
+ *  nothing — `reason` says which of the two happened, in the caller's own
+ *  words. Pure. */
+export function planTaughtTriple(rows, state, triple) {
+  if (!triple?.subject || !triple?.object) return { toAppend: [], reason: "nothing parsed" };
+  if (triple.kind === PLACEMENT_KIND) {
+    const current = state?.placements?.get(triple.subject);
+    if (current && current.predicate === triple.predicate && current.object === triple.object) {
+      return { toAppend: [], reason: `${triple.subject} is already ${triple.predicate} ${triple.object}` };
+    }
+    return {
+      toAppend: [triple],
+      reason: current
+        ? `${triple.subject} moves from ${current.object} to ${triple.object}`
+        : `${triple.subject} is placed ${triple.predicate} ${triple.object}`,
+    };
+  }
+  if (triple.kind === OPENNESS_KIND) {
+    const current = state?.openness?.get(triple.subject);
+    const wantOpen = triple.object === "true";
+    if (current && current.open === wantOpen) {
+      return { toAppend: [], reason: `${triple.subject} is already ${wantOpen ? "open" : "closed"}` };
+    }
+    return { toAppend: [triple], reason: `${triple.subject} becomes ${wantOpen ? "open" : "closed"}` };
+  }
+  const key = tripleKey(triple);
+  if (editableOtherRows(rows).some((r) => tripleKey(r) === key)) {
+    return { toAppend: [], reason: `the world already says ${key}` };
+  }
+  return { toAppend: [triple], reason: `the world gains ${key}` };
+}
+
 // ---- cursor-driven suggestions ---------------------------------------------
 
 export { wordBeforeCursor } from "./viz-theme.mjs";

package/src/services/adventure.mjs

@@ -18,6 +18,9 @@ import { compileDomain, precondHolds, roleBinding } from "../domain/domain.mjs";
 import { getWorldsPackProvider } from "../adapters/corpus/worlds-pack.mjs";
 import { appendFacts, appendRule, loadMemory, normFactTerm, readFactRows, readRuleRows } from "../adapters/memory/core.mjs";
 import { COMPLETIONS_STORE, generateCompletion } from "./completions.mjs";
+import { parseEditorLine, planTaughtTriple } from "./adventure-editor.mjs";
+import { parseMudEditorLine, planTaughtMudTriple } from "./mud-editor.mjs";
+import { worldTeachTurn } from "./world-teach.mjs";
 
 // ---- recognizers: the closed opening/stop set --------------------------------
 
@@ -563,6 +566,20 @@ export function roomAffordances(rows, state, here, actingSubject = "player") {
 
 const affordanceSuffix = (actions) => (actions.length ? ` You can: ${actions.join(", ")}.` : "");
 
+/** The auto-relook line every state-changing turn ends on: the room read back
+ *  from a FRESH load of the store, in the same shape a manual "look"
+ *  produces, so nobody has to retype "look" to see what just changed. Every
+ *  writer that changes the world shares this one renderer — a second copy
+ *  would drift the moment the digest or the affordance list moved. */
+export async function worldRelook(room, { memoryDir, graph = null, actingSubject = "player" }) {
+  const memory = await loadMemory(memoryDir);
+  const rows = readFactRows(memory);
+  const state = foldWorldState(worldActionRows(rows));
+  const digest = await worldDigest(room, { memoryDir, memory, rows, state, graph, actingSubject });
+  const actions = roomAffordances(rows, state, room, actingSubject);
+  return `you are in the ${room}. ${digest ?? "Nothing more about it is written down yet."}${affordanceSuffix(actions)}`;
+}
+
 /** The effect predicate a family writes (its action-effect row's slot, with
  *  the mgx: prefix rule readers re-attach). Null when the family carries no
  *  effect row — unlock's family stays signature-only (its instrument match
@@ -1218,7 +1235,7 @@ function freshRoomId(rows, here, direction) {
  *  whole nested dig path ("carrot-sett-1-north-east-east"), which is an id, not
  *  a name anyone can read. `alsoTaken` holds the ids minted earlier in this
  *  same dig, which are not in `rows` yet. Pure. */
-function freshObjectId(rows, kind, alsoTaken) {
+export function freshObjectId(rows, kind, alsoTaken = new Set()) {
   const taken = (id) => alsoTaken.has(id) || (rows || []).some((r) => r.subject === id || r.object === id);
   for (let n = 1; n <= (rows || []).length + 2; n += 1) {
     if (!taken(`${kind}-${n}`)) return `${kind}-${n}`;
@@ -1237,7 +1254,7 @@ function declaredKindsOr(rows, roomClass, predicate, fallback) {
  *  nothing when the class declares no mass. eat reads the instance's mass, so a
  *  dug carrot with none would be worth the flat default however the world
  *  values a carrot. Pure. */
-function classMassFacts(rows, instance, kind) {
+export function classMassFacts(rows, instance, kind) {
   const mass = factObjects(rows, kind, MASS_PREDICATE)[0];
   return mass ? [{ subject: instance, predicate: MASS_PREDICATE, object: mass }] : [];
 }
@@ -1911,15 +1928,7 @@ export async function runWorldCommand(cmd, { world, memoryDir, env, graph, cache
     const npcPass = runNpcPass({ rows, state, k, families, playerRoomAfter });
     await writeWorldTurn(memoryDir, world, k, [...facts, ...npcPass.writes], cache);
     const text2 = npcPass.lines.length ? `${text} ${npcPass.lines.join(" ")}` : text;
-    // Auto-relook: every state-changing command ends in the same shape a
-    // manual "look" produces, read from the FRESH post-write state, so the
-    // player is never left to retype "look" to see what just changed.
-    const freshMemory = await loadMemory(memoryDir);
-    const freshRows = readFactRows(freshMemory);
-    const freshState = foldWorldState(worldActionRows(freshRows));
-    const relookDigest = await worldDigest(playerRoomAfter, { memoryDir, memory: freshMemory, rows: freshRows, state: freshState, graph, actingSubject });
-    const actions = roomAffordances(freshRows, freshState, playerRoomAfter, actingSubject);
-    const relook = `you are in the ${playerRoomAfter}. ${relookDigest ?? "Nothing more about it is written down yet."}${affordanceSuffix(actions)}`;
+    const relook = await worldRelook(playerRoomAfter, { memoryDir, graph, actingSubject });
     return answer(
       `${text2} ${relook}`,
       noteFor(`${detail}; turn ${k} snapshots written through appendFacts${npcPass.writes.length ? `; NPC pass fired ${npcPass.writes.length} scheduled move(s)` : ""}; auto-relook appended for the ${playerRoomAfter}`),
@@ -2362,7 +2371,7 @@ async function addressedLine(line, { memoryDir }) {
  * recognizer, injected so the two lanes can never disagree about what a plan
  * frame is.
  */
-export async function adventureTurn(line, { planHolder, memoryDir, sessionId = "", env, lexicon = null, graph = null, cache = null, isPlanFrameLine = () => false, discourseHolder = null, actingSubject = "player" }) {
+export async function adventureTurn(line, { planHolder, memoryDir, sessionId = "", env, lexicon = null, graph = null, cache = null, isPlanFrameLine = () => false, discourseHolder = null, actingSubject = "player", gameConfig = null }) {
   const slot = planHolder?.state ?? null;
   const adventure = slot?.adventure ?? null;
   const opening = matchAdventureOpening(line);
@@ -2418,11 +2427,11 @@ export async function adventureTurn(line, { planHolder, memoryDir, sessionId = "
       note: "ADVENTURE — a plan frame arrived mid-adventure; the slot holds one thing at a time",
     };
   }
-  const direct = await liveWorldAnswer(line, { world: adventure.world, memoryDir, env, graph, cache, lexicon, discourseHolder, actingSubject });
+  const direct = await liveWorldAnswer(line, { world: adventure.world, memoryDir, env, graph, cache, lexicon, discourseHolder, actingSubject, gameConfig });
   if (direct) return direct;
   const addressed = await addressedLine(line, { memoryDir });
   if (addressed) {
-    const readdressed = await liveWorldAnswer(addressed, { world: adventure.world, memoryDir, env, graph, cache, lexicon, discourseHolder, actingSubject });
+    const readdressed = await liveWorldAnswer(addressed, { world: adventure.world, memoryDir, env, graph, cache, lexicon, discourseHolder, actingSubject, gameConfig });
     if (readdressed) return readdressed;
   }
   return null; // a mid-game aside — the ordinary lanes answer, world untouched
@@ -2433,8 +2442,29 @@ export async function adventureTurn(line, { planHolder, memoryDir, sessionId = "
  *  lets an ordinary mid-game question keep its own lane. Split out from the
  *  lane itself so a line carrying a vocative can be re-offered here once,
  *  stripped, without the two paths ever drifting apart. */
-async function liveWorldAnswer(line, { world, memoryDir, env, graph, cache, lexicon, discourseHolder, actingSubject }) {
+async function liveWorldAnswer(line, { world, memoryDir, env, graph, cache, lexicon, discourseHolder, actingSubject, gameConfig }) {
   if (INVENTORY_RE.test(line)) return inventoryAnswer({ memoryDir, graph, actingSubject });
+  // The teach switch runs BEFORE the imperative parse, and that ordering is
+  // the point. parseImperative fuzzy-repairs a leading noun into a verb when
+  // one is an edit away ("book" -> "look"), so a declarative sentence about
+  // such a noun would be executed as a command and decline on its own
+  // residue. With teach on, the sentence is read as a fact first; with teach
+  // off, nothing here runs and the lane behaves exactly as it always has.
+  if (gameConfig?.adventure?.teach && memoryDir) {
+    const teachRows = readFactRows(await loadMemory(memoryDir));
+    const taught = await worldTeachTurn(line, {
+      // A burrow says placement with different words than a manor does, so
+      // the sentence table follows the world, never the lane. The world's own
+      // origin fact is the test: only a burrow measures digs from one.
+      ...(originRoomOf(teachRows)
+        ? { parseLine: parseMudEditorLine, planTriple: planTaughtMudTriple }
+        : { parseLine: parseEditorLine, planTriple: planTaughtTriple }),
+      rows: teachRows,
+      state: foldWorldState(worldActionRows(teachRows)),
+      memoryDir, world, actingSubject, cache, graph,
+    });
+    if (taught) return taught;
+  }
   const parsed = parseImperative(line, await worldAwareLexicon(memoryDir, lexicon));
   if (parsed) {
     const bound = await bindPronouns(parsed, { discourseHolder, memoryDir, actingSubject });

package/src/services/chat.mjs

@@ -15376,7 +15376,7 @@ async function dispatchTurn(input, { config, source = defaultSource, graph = nul
   // otherwise read as a declarative or an orientation ask.
   {
     const advTurn = await adventureTurn(workingLine, {
-      planHolder, memoryDir, sessionId, env, lexicon, graph, cache: factRowsCache, isPlanFrameLine, discourseHolder, actingSubject,
+      planHolder, memoryDir, sessionId, env, lexicon, graph, cache: factRowsCache, isPlanFrameLine, discourseHolder, actingSubject, gameConfig,
     });
     if (advTurn) {
       note(trace, `lane: ${advTurn.note}`);