@polycode-projects/the-mechanical-code-talker 2.11.10 → 2.11.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "2.11.10",
+  "version": "2.11.12",
   "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.",

package/src/adapters/research-queue-store.mjs

@@ -0,0 +1,76 @@
+// research-queue-store.mjs — persists the "research <topic>" queue as one JSON
+// file under the repo's .tmct/ (research-queue.json, beside the memory dir), so
+// a run started in one CLI session resumes in the next: "research next" steps
+// the queue, "research status" reports it, "research stop" clears it, all
+// across process restarts. The file is per-repo and machine-local (.tmct/ is
+// gitignored), exactly like the graph/sqlite store it sits next to.
+//
+// The seam is the memoryDir backend token runTurn already carries:
+//   - a repo-path string (Backend A): the queue file is <repo>/.tmct/…;
+//   - a sqlite handle carrying dbPath (Backend C, the CLI default): the queue
+//     file is the dbPath's .tmct/ sibling;
+//   - an in-memory handle (Backend B) or null (the browser session): no path,
+//     so persistence is a silent no-op and the in-page queue behaves as before.
+//
+// Fail closed: an absent, unreadable, or invalid file reads as "no run" — never
+// a crash, never a fabricated queue.
+
+import { readFile, writeFile, mkdir, unlink } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+const QUEUE_FILE = "research-queue.json";
+
+/** The on-disk path for `memoryDir`'s queue file, or null when this session has
+ *  nowhere to persist (in-memory backend, or a browser session with no store).
+ *  A repo-path string keys off <repo>/.tmct; a store handle keys off its own
+ *  dbPath's .tmct/ sibling — any handle without a real dbPath has no home. */
+function researchQueuePath(memoryDir) {
+  if (!memoryDir) return null;
+  if (typeof memoryDir === "string") return join(memoryDir, ".tmct", QUEUE_FILE);
+  if (typeof memoryDir.dbPath === "string") return join(dirname(dirname(memoryDir.dbPath)), QUEUE_FILE);
+  return null;
+}
+
+/** A parsed value is a resumable queue only if it carries the run identity and
+ *  the three lists the lifecycle mutates. Anything else fails closed to null. */
+function isQueueState(state) {
+  return !!state && typeof state === "object"
+    && typeof state.topic === "string"
+    && typeof state.key === "string"
+    && Array.isArray(state.pending)
+    && Array.isArray(state.done)
+    && Array.isArray(state.skipped);
+}
+
+/** The persisted queue for `memoryDir`, or null when none is stored, the store
+ *  cannot persist, or the file is missing/corrupt/ill-shaped. */
+export async function loadResearchQueue(memoryDir) {
+  const path = researchQueuePath(memoryDir);
+  if (!path) return null;
+  let raw;
+  try { raw = await readFile(path, "utf8"); } catch { return null; }
+  let state;
+  try { state = JSON.parse(raw); } catch { return null; }
+  return isQueueState(state) ? state : null;
+}
+
+/** Write-through the current queue. A null/absent state clears the file, so a
+ *  stopped or completed-and-cleared run leaves nothing behind. A store with no
+ *  path is a no-op. A write that fails leaves the in-memory queue standing. */
+export async function saveResearchQueue(memoryDir, state) {
+  const path = researchQueuePath(memoryDir);
+  if (!path) return;
+  if (!state) { await clearResearchQueue(memoryDir); return; }
+  try {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, JSON.stringify(state), "utf8");
+  } catch { /* a queue we can't persist stays in memory for this session */ }
+}
+
+/** Delete the persisted queue file (idempotent — an already-absent file is the
+ *  cleared state we want). A store with no path is a no-op. */
+export async function clearResearchQueue(memoryDir) {
+  const path = researchQueuePath(memoryDir);
+  if (!path) return;
+  try { await unlink(path); } catch { /* already gone */ }
+}

package/src/adapters/toml-config.mjs

@@ -129,8 +129,9 @@ export async function normalizeConfig(raw, { configDir } = {}) {
 
   // Research-lane knobs (src/services/research.mjs): sparse PASS-THROUGH,
   // same discipline as [games.*] — the raw `[research]` table
-  // (fanout_limit / depth_limit / min_interval_ms, snake_case) rides through
-  // unmodified; clamping and default-filling is resolveResearchConfig's job.
+  // (fanout_limit / max_depth / max_topics / min_interval_ms, snake_case)
+  // rides through unmodified; clamping and default-filling is
+  // resolveResearchConfig's job.
   if (src.research !== undefined) cfg.research = src.research;
 
   const idx = src.index || {};

package/src/domain/grammar/ace.mjs

@@ -528,6 +528,15 @@ export function parseAce(sentence, lexicon = loadLexicon()) {
 const IMPERATIVE_VERBS = new Set(["go", "take", "drop", "open", "unlock", "close", "give", "look", "talk", "examine"]);
 const IMPERATIVE_DIRECTIONS = new Set(["north", "south", "east", "west", "up", "down"]);
 
+// The object pronouns an imperative object slot may carry ("examine it", "take
+// them", "talk to him"). This parser only MARKS such a slot with the bare
+// pronoun as its term — the antecedent lives in the running world, not the
+// sentence, so binding it to a concrete object is the adventure lane's job (it
+// alone holds the session's FOCUS). Kept out of resolveNP's lexicon gate on
+// purpose: a pronoun is never a declared noun, so without this it rides out as
+// residue and mis-declines as an unknown word.
+export const OBJECT_PRONOUNS = new Set(["it", "them", "him", "her"]);
+
 const VERB_SYNONYMS = new Map([
   ["pick up", "take"], ["pick", "take"], ["grab", "take"],
   ["put down", "drop"], ["set down", "drop"], ["leave", "drop"],
@@ -603,8 +612,14 @@ function resolveImperativeVerb(toks) {
   return { ...retried, corrected: { from: first, to: fixedFirst } };
 }
 
-/** Resolve one imperative object phrase to its bare lexicon term. */
+/** Resolve one imperative object phrase to its bare lexicon term. A lone
+ *  object pronoun ("it", "them", "him", "her") rides through as its own term
+ *  for the lane to bind against the session focus — never a lexicon lookup,
+ *  never residue. */
 function imperativeNP(lexicon, tokens) {
+  if (tokens.length === 1 && OBJECT_PRONOUNS.has(tokens[0].toLowerCase())) {
+    return { term: tokens[0].toLowerCase(), unknown: [] };
+  }
   const np = resolveNP(lexicon, tokens);
   if (np.term == null) return { term: null, unknown: np.unknown };
   return { term: local(lexicon, np.term), unknown: [] };
@@ -641,7 +656,14 @@ export function parseImperative(sentence, lexicon = loadLexicon()) {
 
   if (verb === "look") {
     if (!rest.length || (rest.length === 1 && lower[0] === "around")) return command({});
-    return null;
+    // "look <object>" — a bare noun after look reads as a close look at that
+    // thing, routed through the same object handler examine/talk share (which
+    // resolves presence and declines an absent thing by name). "look at <x>"
+    // never reaches here — its 2-token synonym prefix already resolved to
+    // examine — so this arm only ever sees the bare-noun form.
+    const object = imperativeNP(lexicon, rest);
+    if (object.term == null) return miss(object.unknown);
+    return command({ object: object.term });
   }
   if (verb === "examine" || verb === "talk") {
     if (!rest.length) return null;

package/src/services/adventure-viz.mjs

@@ -428,6 +428,20 @@ export function pillsForRoom(rows, state, here) {
   return roomAffordances(rows, state, here);
 }
 
+/** The chat input's grounding placeholder, built from an affordance list: the
+ *  first couple of OBJECT commands (examine/take/open/unlock/talk to <thing>)
+ *  spelled with the room's real props, so the empty input teaches the grounded
+ *  noun form ("examine lamp, take letter…") rather than a bare pronoun the
+ *  player has no antecedent for yet. `fallback` stands in when the list holds
+ *  no object command (a room with only exits, or a just-emptied object dock).
+ *  Pure and `.toString()`-splice-safe — the page splices it in and drives both
+ *  input docks off it every redraw. */
+export function groundedPlaceholder(actions, fallback) {
+  const objectActions = (actions || []).filter((a) => /^(?:examine|take|open|unlock|talk to) /.test(a));
+  if (!objectActions.length) return fallback;
+  return objectActions.slice(0, 2).join(", ") + "…";
+}
+
 /** Edit mode's cursor-driven suggestion pills for one typed `term`: the
  *  lateral SKOS neighbourhood (`relatedForTerm`'s own synonyms/related
  *  concepts) plus the vertical rdfs:subClassOf ancestor chain
@@ -682,6 +696,13 @@ ${THEME_TOKENS_CSS}
      underneath always names the real, specific thing (the cabinet, the
      butler) — chrome around honest content, never instead of it. */
   .sprite-card { display: flex; flex-direction: column; align-items: center; width: 70px; }
+  /* a room sprite the visitor can click for a lights-down close look — a
+     pointer cursor and a gilt ring on hover. Wall-mounted cards live in a
+     pointer-events: none band (so the band never eats a floor click), so a
+     clickable one re-enables its own pointer events. */
+  .sprite-card.clickable { cursor: pointer; }
+  .sprite-card.clickable:hover .sprite-frame { border-color: var(--gilt); box-shadow: inset 0 0 0 3px var(--parchment), 0 0 0 2px var(--gilt), 0 2px 3px rgba(0, 0, 0, .22); }
+  .wall-row .sprite-card.clickable { pointer-events: auto; }
   /* a squared inventory-slot tile (the 90s-RPG idiom) instead of the old
      thin circular ring: a raised card with an inner mat, the class color on
      the outer border, and a soft ground shadow so the tile sits ON the
@@ -759,6 +780,29 @@ ${THEME_TOKENS_CSS}
   .roommap .room-node.clickable:hover rect { stroke: var(--gilt); stroke-width: 2.5; }
   .roommap .room-node.selected rect { stroke: var(--alert); stroke-width: 2.5; }
 
+  /* the object lightbox — the SAME lights-down treatment the map lightbox
+     uses (fixed dimmed backdrop, z-index 60, close on backdrop click/Escape),
+     framed as a parchment case-file card: the clicked object's large sprite
+     (the sprites-page 400px tier, via the same resolveObjectSprite the room
+     cards use), its live "look <object>" reply, and an object-scoped chat
+     dock — its own affordance pills filtered to this object, plus free text.
+     Every dock turn runs through the ONE live session, so the main
+     transcript/quest/satchel reflect it. */
+  .obj-lightbox { position: fixed; inset: 0; z-index: 60; display: flex; align-items: center; justify-content: center; padding: 2.4rem; background: rgba(10, 8, 4, .74); }
+  .obj-lightbox[hidden] { display: none; }
+  .obj-lightbox-inner { width: min(92vw, 560px); max-height: 88vh; overflow-y: auto; background: var(--parchment); color: var(--ink); border: 3px solid var(--gilt); box-shadow: inset 0 0 0 2px var(--parchment-strong), 0 12px 48px rgba(0, 0, 0, .5); padding: 1.1rem 1.2rem 1.2rem; box-sizing: border-box; }
+  .obj-title { font-family: ${SERIF_STACK}; font-variant: small-caps; font-size: 1rem; letter-spacing: .06em; color: var(--gilt); font-weight: 600; margin: 0 0 .6rem; padding-bottom: .3rem; border-bottom: 1px solid var(--line); }
+  .obj-scene { display: flex; align-items: center; justify-content: center; padding: .5rem 0 1rem; }
+  .obj-sprite { width: min(46vmin, 300px); height: min(46vmin, 300px); }
+  .obj-sprite svg { width: 100%; height: 100%; display: block; }
+  .obj-look { font-size: .9rem; line-height: 1.45; white-space: pre-wrap; background: var(--card); border-left: 3px solid var(--gilt); padding: .55rem .7rem; margin: 0 0 .8rem; }
+  .obj-look:empty { display: none; }
+  .docklog { display: flex; flex-direction: column; gap: .4rem; max-height: 200px; overflow-y: auto; margin-bottom: .5rem; }
+  .docklog:empty { display: none; }
+  .docklog .u { font-family: ${MONO_STACK}; font-size: .74rem; color: var(--muted); }
+  .docklog .u::before { content: "tmct> "; color: var(--taught); }
+  .docklog .a { font-size: .86rem; line-height: 1.4; white-space: pre-wrap; }
+
   .goal-status { display: flex; flex-direction: column; gap: .4rem; }
   .goal-status .g { display: flex; align-items: baseline; gap: .4rem; font-size: .86rem; line-height: 1.35; }
   .goal-status .dot { width: .5rem; height: .5rem; border-radius: 50%; flex: none; background: var(--muted); }
@@ -890,6 +934,19 @@ ${THEME_TOKENS_CSS}
   <div class="map-lightbox" id="mapLightbox" role="dialog" aria-modal="true" aria-label="The manor map, enlarged" hidden>
     <div class="map-lightbox-inner roommap" id="mapLightboxInner"></div>
   </div>
+  <div class="obj-lightbox" id="objLightbox" role="dialog" aria-modal="true" aria-label="A closer look at an object" hidden>
+    <div class="obj-lightbox-inner" id="objLightboxInner">
+      <h2 class="obj-title" id="objTitle"></h2>
+      <div class="obj-scene" id="objScene"></div>
+      <div class="obj-look" id="objLook"></div>
+      <div class="pills" id="objPills"></div>
+      <div class="docklog" id="objDockLog" aria-live="polite"></div>
+      <form class="chatask" id="objForm">
+        <span class="prompt mono">tmct&gt;</span>
+        <input id="objInput" type="text" placeholder="examine lamp, take key&hellip;" aria-label="Type a command for this object">
+      </form>
+    </div>
+  </div>
 
   <div class="stage editor-stage" id="editStage" aria-label="The world editor">
     <div class="panel edittext">
@@ -932,6 +989,7 @@ ${engineBundleJs ? `<script>\n${embedScriptText(engineBundleJs)}\n</script>` : `
   const carriedItems = ${carriedItems.toString()};
   const visitedRoomGraph = ${visitedRoomGraph.toString()};
   const allRoomIds = ${allRoomIds.toString()};
+  const groundedPlaceholder = ${groundedPlaceholder.toString()};
   const spriteAncestryRows = ${spriteAncestryRows.toString()};
   const factsForSubject = ${factsForSubject.toString()};
   const renderWorldEditorText = ${renderWorldEditorText.toString()};
@@ -960,6 +1018,14 @@ ${engineBundleJs ? `<script>\n${embedScriptText(engineBundleJs)}\n</script>` : `
   const mapViewportEl = el("mapViewport");
   const mapLightboxEl = el("mapLightbox");
   const mapLightboxInnerEl = el("mapLightboxInner");
+  const objLightboxEl = el("objLightbox");
+  const objTitleEl = el("objTitle");
+  const objSceneEl = el("objScene");
+  const objLookEl = el("objLook");
+  const objPillsEl = el("objPills");
+  const objDockLogEl = el("objDockLog");
+  const objFormEl = el("objForm");
+  const objInputEl = el("objInput");
   const goalListEl = el("goalList");
   const editModeBtn = el("editModeBtn");
   const editorTextEl = el("editorText");
@@ -980,6 +1046,7 @@ ${engineBundleJs ? `<script>\n${embedScriptText(engineBundleJs)}\n</script>` : `
   let lastTicks = 0;
   let lastSnapshot = null;
   let selectedRoomId = null;
+  let objLightboxSubject = null;
   let editRows = [];
   let editState = { placements: new Map(), openness: new Map(), exits: new Map() };
   let allStoreRows = [];
@@ -1058,8 +1125,15 @@ ${engineBundleJs ? `<script>\n${embedScriptText(engineBundleJs)}\n</script>` : `
   // the caption text — is never replaced by it.
   const CLASS_BADGE = { adventurer: "hero", person: "townsfolk", container: "fixture", furniture: "fixture", portable: "item", room: "room" };
   const badgeFor = (cls) => CLASS_BADGE[cls] || cls;
-  function spriteCardHtml(label, cls, svg) {
-    return '<div class="sprite-card"><div class="sprite-frame" data-cls="' + esc(cls) + '"><div class="sprite" data-cls="' + esc(cls) + '">' + svg + '</div></div>'
+  // A truthy subject marks the card clickable and tags it with the object it
+  // names, so the room frame's own delegated handler can open the object
+  // lightbox for it. The player's own "you" card and the edit-mode / legend /
+  // satchel cards pass none, so only real room props are clickable.
+  function clickAttrs(subject) {
+    return subject ? ' clickable" data-look-subject="' + esc(subject) + '"' : '"';
+  }
+  function spriteCardHtml(label, cls, svg, subject) {
+    return '<div class="sprite-card' + clickAttrs(subject) + '><div class="sprite-frame" data-cls="' + esc(cls) + '"><div class="sprite" data-cls="' + esc(cls) + '">' + svg + '</div></div>'
       + '<div class="sprite-label">' + esc(label) + '</div>'
       + '<div class="class-badge" data-cls="' + esc(cls) + '">' + esc(badgeFor(cls)) + "</div></div>";
   }
@@ -1073,8 +1147,8 @@ ${engineBundleJs ? `<script>\n${embedScriptText(engineBundleJs)}\n</script>` : `
   // spriteCardHtml identification; every item resting on something else
   // shows an aria-label in its place, so the name is still available to
   // assistive tech even though the sighted layout stays compact.
-  function stackedSpriteCardHtml(label, cls, svg) {
-    return '<div class="sprite-card" aria-label="' + esc(label) + '"><div class="sprite-frame" data-cls="' + esc(cls) + '"><div class="sprite" data-cls="' + esc(cls) + '">' + svg + "</div></div></div>";
+  function stackedSpriteCardHtml(label, cls, svg, subject) {
+    return '<div class="sprite-card' + clickAttrs(subject) + ' aria-label="' + esc(label) + '"><div class="sprite-frame" data-cls="' + esc(cls) + '"><div class="sprite" data-cls="' + esc(cls) + '">' + svg + "</div></div></div>";
   }
 
   function captionFor(rows, state, here) {
@@ -1174,6 +1248,100 @@ ${engineBundleJs ? `<script>\n${embedScriptText(engineBundleJs)}\n</script>` : `
   mapLightboxEl.addEventListener("click", (e) => { if (e.target === mapLightboxEl) closeMapLightbox(); });
   document.addEventListener("keydown", (e) => { if (e.key === "Escape" && !mapLightboxEl.hidden) closeMapLightbox(); });
 
+  // ---- the object lightbox — clicking a room sprite opens a lights-down
+  // close look at that thing (the SAME lights-down/backdrop/Escape pattern as
+  // the map lightbox): its large sprite, its live "look <object>" reply
+  // (adventure.mjs's grounded look, run through THIS session), and an
+  // object-scoped chat dock. The dock's pills are the room's own affordance
+  // list filtered to this object (pillsFor, the same source the main hint
+  // pills read), plus a free-text input. Every dock turn runs through the ONE
+  // live session, echoes into the MAIN transcript and redraws the main page,
+  // so the satchel/quest/room all reflect it after close — no forked state.
+  function addObjDockLine(cls, html) {
+    const d = document.createElement("div");
+    d.className = cls; d.innerHTML = html;
+    objDockLogEl.appendChild(d); objDockLogEl.scrollTop = objDockLogEl.scrollHeight;
+  }
+  function objectPillsFor(rows, state, here, subject) {
+    return pillsFor(rows, state, here).filter((a) => a.split(" ").pop() === subject);
+  }
+  function renderObjScene() {
+    if (!lastSnapshot || !objLightboxSubject) { objSceneEl.innerHTML = ""; return; }
+    const cls = spriteClassForObject(lastSnapshot.rows, objLightboxSubject);
+    const svg = resolveObjectSprite(lastSnapshot.rows, { subject: objLightboxSubject, spriteClass: cls });
+    objSceneEl.innerHTML = '<div class="obj-sprite" data-cls="' + esc(cls) + '">' + svg + "</div>";
+  }
+  function renderObjPills() {
+    if (!lastSnapshot || !objLightboxSubject) { objPillsEl.innerHTML = ""; return; }
+    const actions = objectPillsFor(lastSnapshot.rows, lastSnapshot.state, lastSnapshot.here, objLightboxSubject);
+    objPillsEl.innerHTML = actions.map((a) => '<button type="button" class="pill">' + esc(a) + "</button>").join("");
+    // Grounded to the open object itself ("take lamp…"), so the dock teaches
+    // the noun form even though a bare pronoun now binds here too.
+    objInputEl.placeholder = groundedPlaceholder(actions, "examine " + objLightboxSubject);
+  }
+  // A dock turn: paused, echoed into the main transcript AND the dock, run on
+  // the one session, then the main page and the lightbox both redraw off the
+  // fresh snapshot — the board stays open.
+  function runObjTurn(line) {
+    ticker.pause();
+    addChatLine("u", esc(line));
+    addObjDockLine("u", esc(line));
+    return withLock(async () => {
+      const result = await session.turn(line);
+      addChatLine("a", esc(result.answer).replace(/\\n/g, "<br>"));
+      addObjDockLine("a", esc(result.answer).replace(/\\n/g, "<br>"));
+      const snap = await session.snapshot();
+      redraw(snap);
+      renderObjScene();
+      renderObjPills();
+    });
+  }
+  async function openObjectLightbox(subject) {
+    if (!session || !lastSnapshot) return;
+    ticker.pause();
+    objLightboxSubject = subject;
+    objTitleEl.textContent = "the " + subject;
+    objDockLogEl.innerHTML = "";
+    objLookEl.textContent = "";
+    objInputEl.value = "";
+    renderObjScene();
+    renderObjPills();
+    objLightboxEl.hidden = false;
+    objInputEl.focus();
+    // The initial look is a real, read-only turn on the live session (it writes
+    // nothing, so it needs no main-transcript echo — it IS the board's own
+    // content); pill/typed turns below do echo, since they can change state.
+    await withLock(async () => {
+      const result = await session.turn("look " + subject);
+      objLookEl.textContent = result.answer;
+    });
+  }
+  function closeObjectLightbox() {
+    objLightboxEl.hidden = true;
+    objLightboxSubject = null;
+    objDockLogEl.innerHTML = "";
+    objInputEl.value = "";
+  }
+  roomFrameEl.addEventListener("click", (e) => {
+    const card = e.target.closest(".sprite-card[data-look-subject]");
+    if (!card) return;
+    openObjectLightbox(card.getAttribute("data-look-subject"));
+  });
+  objPillsEl.addEventListener("click", (e) => {
+    const btn = e.target.closest(".pill");
+    if (!btn) return;
+    runObjTurn(btn.textContent);
+  });
+  objFormEl.addEventListener("submit", (e) => {
+    e.preventDefault();
+    const q = objInputEl.value.trim();
+    if (!q || !session) return;
+    objInputEl.value = "";
+    runObjTurn(q);
+  });
+  objLightboxEl.addEventListener("click", (e) => { if (e.target === objLightboxEl) closeObjectLightbox(); });
+  document.addEventListener("keydown", (e) => { if (e.key === "Escape" && !objLightboxEl.hidden) closeObjectLightbox(); });
+
   function renderEditMap(rows, state) {
     editMapWrapEl.innerHTML = roomMapSvg(visitedRoomGraph(state, allRoomIds(rows)), true) || '<span class="empty-note">this world defines no rooms</span>';
   }
@@ -1219,6 +1387,10 @@ ${engineBundleJs ? `<script>\n${embedScriptText(engineBundleJs)}\n</script>` : `
   function renderPills(rows, state, here) {
     const actions = pillsFor(rows, state, here);
     pillsEl.innerHTML = actions.map((a) => '<button type="button" class="pill">' + esc(a) + "</button>").join("");
+    // The empty input teaches the grounded noun form off the same affordance
+    // list the pills read — real props from THIS room, so a first-time player
+    // types "examine lamp", not a pronoun with nothing to bind to yet.
+    chatqEl.placeholder = groundedPlaceholder(actions, "go north");
   }
   pillsEl.addEventListener("click", (e) => {
     const btn = e.target.closest(".pill");
@@ -1268,12 +1440,12 @@ ${engineBundleJs ? `<script>\n${embedScriptText(engineBundleJs)}\n</script>` : `
   function redraw(snap) {
     lastSnapshot = snap;
     const layout = roomSceneLayout(snap.rows, snap.state, snap.here);
-    wallRowEl.innerHTML = layout.wall.map((s) => spriteCardHtml(s.subject, s.spriteClass, resolveObjectSprite(snap.rows, s))).join("");
+    wallRowEl.innerHTML = layout.wall.map((s) => spriteCardHtml(s.subject, s.spriteClass, resolveObjectSprite(snap.rows, s), s.subject)).join("");
     floorRowEl.innerHTML = layout.floor.map((stack) => {
       const baseIndex = stack.items.length - 1;
       return '<div class="sprite-stack">' + stack.items.map((s, i) => {
         const svg = resolveObjectSprite(snap.rows, s);
-        return i === baseIndex ? spriteCardHtml(s.subject, s.spriteClass, svg) : stackedSpriteCardHtml(s.subject, s.spriteClass, svg);
+        return i === baseIndex ? spriteCardHtml(s.subject, s.spriteClass, svg, s.subject) : stackedSpriteCardHtml(s.subject, s.spriteClass, svg, s.subject);
       }).join("") + "</div>";
     }).join("");
     youSlotEl.innerHTML = spriteCardHtml("you", "adventurer", resolveObjectSprite(snap.rows, { subject: "you", spriteClass: "adventurer" }));

package/src/services/adventure.mjs

@@ -9,7 +9,7 @@
 // share the slot.
 
 import { worldProvenanceTag } from "../domain/worlds-pack.mjs";
-import { parseImperative } from "../domain/grammar/ace.mjs";
+import { parseImperative, OBJECT_PRONOUNS } from "../domain/grammar/ace.mjs";
 import { createCompletionsGraphAdapter } from "../domain/completions/graph-adapter.mjs";
 import { actionFamilies } from "../domain/router/taught.mjs";
 import { compileDomain, precondHolds, roleBinding } from "../domain/domain.mjs";
@@ -556,6 +556,44 @@ export function worldDigestRows(rows, state) {
   return out;
 }
 
+/** The physical-property lines a close "look <object>" states: the object's
+ *  own world facts, phrased through the SAME worldDigestRows view a room look
+ *  reads (so mgx:knows-*, the NPC schedule, is-objective and the rest of the
+ *  puzzle wiring are already excluded there), minus its bare rdf:type line —
+ *  the class hierarchy renders that as its own is-a chain instead. A carried
+ *  object surfaces through the "carries the" line the digest already produces.
+ *  Pure. */
+export function objectLookProperties(rows, state, object) {
+  const subjectCased = sentenceCase(object);
+  return worldDigestRows(rows, state)
+    .filter((r) => (r.subject === subjectCased && r.predicate !== "is a" && r.predicate !== "is an")
+      || (r.predicate === "carries the" && r.object === object))
+    .map((r) => `${r.subject} ${r.predicate} ${r.object}.`);
+}
+
+/** An object's class hierarchy as an is-a chain, nearest-first and opening
+ *  with the object itself ("housekeeper → person"): a breadth-first walk up
+ *  the world's OWN rdf:type and rdfs:subClassOf edges (worldActionRows, so a
+ *  merged corpus's taxonomy for the same word never joins the chain), the same
+ *  upward-class rendering chat's "what do you know about X" shows. Pure. */
+export function objectClassChain(rows, object) {
+  const worldRows = worldActionRows(rows);
+  const parentsOf = (node) => worldRows
+    .filter((r) => r.subject === node && (r.predicate === "rdf:type" || r.predicate === "rdfs:subClassOf"))
+    .map((r) => r.object);
+  const seen = new Set([object]);
+  const chain = [object];
+  const queue = [...parentsOf(object)];
+  while (queue.length) {
+    const node = queue.shift();
+    if (seen.has(node)) continue;
+    seen.add(node);
+    chain.push(node);
+    queue.push(...parentsOf(node));
+  }
+  return chain;
+}
+
 async function worldDigest(prompt, { memoryDir, memory, rows, state, graph }) {
   const view = worldDigestRows(rows, state);
   const store = {
@@ -689,7 +727,7 @@ async function runWorldCommand(cmd, { world, memoryDir, env, graph, cache }) {
     );
   }
 
-  if (cmd.verb === "look") {
+  if (cmd.verb === "look" && !cmd.object) {
     const digest = await worldDigest(here, { memoryDir, memory, rows, state, graph });
     const actions = roomAffordances(rows, state, here);
     return answer(
@@ -699,13 +737,13 @@ async function runWorldCommand(cmd, { world, memoryDir, env, graph, cache }) {
     );
   }
 
-  if (cmd.verb === "examine" || cmd.verb === "talk") {
+  if (cmd.verb === "examine" || cmd.verb === "talk" || cmd.verb === "look") {
     const object = cmd.object;
     // A carried object has no room to be "visible in" (visibleRoomOf returns
-    // null for anything held by the player) — examine still applies to it,
-    // the same way "what am I carrying" already reads inventory contents.
+    // null for anything held by the player) — examine and look still apply to
+    // it, the same way "what am I carrying" already reads inventory contents.
     // talk has no carried exception: NPCs are never portable.
-    const carried = cmd.verb === "examine" && carriedByPlayer(state, object);
+    const carried = (cmd.verb === "examine" || cmd.verb === "look") && carriedByPlayer(state, object);
     // The room the player is standing in is never the SUBJECT of a placement
     // fact (only ever the OBJECT other things are placed in), so
     // visibleRoomOf(object) can never equal `here` for a room's own name —
@@ -730,7 +768,7 @@ async function runWorldCommand(cmd, { world, memoryDir, env, graph, cache }) {
         { miss: true },
       );
     }
-    if (notHere && !(cmd.verb === "examine" && backgroundOnlyMention(rows, state, object))) {
+    if (notHere && !((cmd.verb === "examine" || cmd.verb === "look") && backgroundOnlyMention(rows, state, object))) {
       return answer(
         `I don't see a ${object} here.`,
         noteFor(`${cmd.verb} — ${object} isn't visible in the ${here}; declined, hidden things stay hidden`),
@@ -738,6 +776,27 @@ async function runWorldCommand(cmd, { world, memoryDir, env, graph, cache }) {
       );
     }
     const person = isTyped(rows, object, "person");
+    // "look <object>" on a real placed prop is the grounded close look: every
+    // physical fact the world writes about the thing (its placement, its
+    // within-room position, any datatype property — all via the SAME
+    // worldDigestRows view that already drops the puzzle wiring and the
+    // staff-knowledge pointers), plus its class hierarchy as an is-a chain,
+    // plus a container's open/locked state. A background-only mention has no
+    // placed facts of its own, so it falls through to the examine digest below
+    // (the same general-knowledge answer "what is a flower" gives).
+    if (cmd.verb === "look" && !backgroundOnlyMention(rows, state, object)) {
+      const propLines = objectLookProperties(rows, state, object);
+      const chain = objectClassChain(rows, object);
+      const parts = [`you look closely at the ${object}.`];
+      if (propLines.length) parts.push(propLines.join(" "));
+      if (chain.length > 1) parts.push(`Class: ${chain.join(" → ")}.`);
+      if (!person && isContainer(rows, object)) parts.push(containerStatusPhrase(object, { state }));
+      return answer(
+        parts.join(" "),
+        noteFor(`look at ${object} — its world-fact properties (via worldDigestRows, knows-*/puzzle-wiring excluded) and its rdf:type/subClassOf is-a chain`),
+        { goal: `take a closer look at the ${object}` },
+      );
+    }
     // Talking to a person is the game's reveal channel: the staff share what
     // they know (a hiding place, the quest, a topic) and report their own
     // room, all resolved from the live fold this turn.
@@ -1165,6 +1224,63 @@ function renderedImperativeCommand(cmd) {
   return parts.join(" ");
 }
 
+// ---- pronoun binding: the session focus ---------------------------------------
+//
+// A world command may name its object with a pronoun ("examine it", "take
+// them", "talk to him") instead of a noun. The antecedent is not in the
+// sentence — it's the last thing the player successfully acted on this
+// session, the FOCUS — so the parser leaves the pronoun bare (ace.mjs's
+// OBJECT_PRONOUNS) and the lane binds it here, through ONE seam that every
+// object-taking verb passes on its way to runWorldCommand. With no focus
+// standing, a pronoun gets an honest reference nudge, never the vocabulary
+// decline (a pronoun is a reference, not an unknown word).
+
+const PRONOUN_SLOTS = ["object", "indirectObject", "instrument"];
+
+const commandHasPronoun = (cmd) => PRONOUN_SLOTS.some((s) => cmd[s] && OBJECT_PRONOUNS.has(cmd[s]));
+
+/** A pronoun command with no focus standing: the reference nudge, embedding a
+ *  real, actionable object from the current room when one is on show (else a
+ *  static example). Never the "I don't know the word" line — the vocabulary
+ *  misdiagnosis is unreachable for a pronoun. */
+async function noFocusPronounNudge(pronoun, { memoryDir }) {
+  let example = null;
+  try {
+    const rows = readFactRows(await loadMemory(memoryDir));
+    const state = foldWorldState(worldActionRows(rows));
+    const here = state.placements.get("player")?.object ?? null;
+    if (here) {
+      for (const action of roomAffordances(rows, state, here)) {
+        const m = action.match(/^(?:examine|take|open|unlock|talk to) (.+)$/);
+        if (m) { example = m[1]; break; }
+      }
+    }
+  } catch { /* no probe available — the static example carries the nudge */ }
+  const eg = example ?? "lamp";
+  return answer(
+    `I'm not sure what "${pronoun}" refers to yet — name the thing, e.g. "examine ${eg}".`,
+    `ADVENTURE — pronoun "${pronoun}" arrived with no focus standing; asked which thing it means, never the vocabulary decline`,
+    { miss: true },
+  );
+}
+
+/** Bind any pronoun object/indirect/instrument slot to the session focus.
+ *  Returns `{ cmd }` with the pronouns rewritten to the focus term, or `{
+ *  nudge }` (the reference nudge) when a pronoun stands but no focus does. A
+ *  command with no pronoun passes straight through untouched. */
+async function bindPronouns(cmd, { focus, memoryDir }) {
+  if (!commandHasPronoun(cmd)) return { cmd };
+  if (!focus) {
+    const pronoun = PRONOUN_SLOTS.map((s) => cmd[s]).find((v) => v && OBJECT_PRONOUNS.has(v));
+    return { nudge: await noFocusPronounNudge(pronoun, { memoryDir }) };
+  }
+  const bound = { ...cmd };
+  for (const s of PRONOUN_SLOTS) {
+    if (bound[s] && OBJECT_PRONOUNS.has(bound[s])) bound[s] = focus;
+  }
+  return { cmd: bound };
+}
+
 // ---- the lane ----------------------------------------------------------------
 
 /**
@@ -1233,9 +1349,18 @@ export async function adventureTurn(line, { planHolder, memoryDir, sessionId = "
     };
   }
   if (INVENTORY_RE.test(line)) return inventoryAnswer({ memoryDir, graph });
-  const cmd = parseImperative(line, lexicon ?? undefined);
-  if (cmd) {
+  const parsed = parseImperative(line, lexicon ?? undefined);
+  if (parsed) {
+    const bound = await bindPronouns(parsed, { focus: adventure.focus, memoryDir });
+    if (bound.nudge) return bound.nudge;
+    const cmd = bound.cmd;
     const result = await runWorldCommand(cmd, { world: adventure.world, memoryDir, env, graph, cache });
+    // The object a command SUCCESSFULLY named becomes the focus a later
+    // pronoun binds to — so "look lamp" then "examine it" reads the lamp, and
+    // "talk to housekeeper" makes "him"/"her" the housekeeper. A miss leaves
+    // the standing focus untouched; a bare room look or a move carries no
+    // object and so never disturbs it.
+    if (!result.miss && cmd.object) adventure.focus = cmd.object;
     if (!cmd.corrected?.length) return result;
     // A fuzzy-repaired verb or direction still executes normally, but the
     // response says what it read the line as, so a genuine miss is never