@polycode-projects/the-mechanical-code-talker 2.11.9 → 2.11.11

package/README.md

@@ -124,14 +124,14 @@ page answers codebase questions live, and eight more pages each ground their
 own domain: a full chat seeded with 32,646 facts (the same nine bands as
 `npm run init:xl`, capped to a 38.7 MB download, 2.1 MB on the wire), the
 **memory ledger** (every fact as a readable sentence; drill by clicking the
-terms inside), the **code explorer** (the same ledger UI refocused on a code
-graph, with a hint rail of suggested next questions), an **ingest page** that
-turns pasted or dropped text into grounded facts and downloads them as
-canonical JSONL, a Towers-of-Hanoi plan replayed move by move, the
-spider-and-fly and text-adventure games, and a sprite gallery whose chat dock
-answers from 1,033 generated sprite facts. The chat page and the ledger take
-the same paste-or-drop text in place; every page that holds a fact store
-exports it as JSONL.
+terms inside), and the **code explorer** (the same ledger UI refocused on a
+code graph, with a hint rail of suggested next questions). An **ingest
+page** turns pasted or dropped text into grounded facts and downloads them
+as canonical JSONL. The rest are a Towers-of-Hanoi plan replayed move by
+move, the spider-and-fly and text-adventure games, and a sprite gallery
+whose chat dock answers from 1,033 generated sprite facts. The chat page and
+the ledger take the same paste-or-drop text in place; every page that holds
+a fact store exports it as JSONL.
 The site hosts its own copy of wink-nlp, ships its assets precompressed,
 and a service worker precaches the big ones, so a second visit works
 offline. `tmct chat --render spider-fly|adventure|sprites [--output <path>]`
@@ -168,13 +168,14 @@ The same ledger UI, refocused on a code graph, also runs as a desktop app. It
 reads a `graph.json` (or a repo's `.tmct/` folder), shows every import, call and
 `contains` edge as a plain sentence around a focus symbol, and docks a live chat
 over the same graph. A hint rail suggests the next question from what the graph
-actually holds — "what does X import", "which functions call Y", "list
-functions" — so every suggestion resolves to a real answer.
+actually holds: "what does X import", "which functions call Y", "list
+functions". Every suggestion resolves to a real answer.
 
-The identical page also runs as a plain hosted page, over the demo code
-graph — **[try it live →](https://polycode-projects.gitlab.io/the-mechanical-code-talker/code.html)**
-— for a look with nothing to install. The desktop build below is for
-exploring your own repo or graph, which the hosted page cannot reach.
+The identical page also runs as a plain hosted page over the demo code
+graph, with nothing to install:
+**[try it live →](https://polycode-projects.gitlab.io/the-mechanical-code-talker/code.html)**.
+The desktop build below is for exploring your own repo or graph, which the
+hosted page cannot reach.
 
 Electron is a dev-only dependency and never ships in the npm package. Because
 `.npmrc` sets `ignore-scripts=true`, installing it does not fetch the runtime
@@ -188,8 +189,8 @@ npm run electron                        # open the code explorer on the demo gra
 ```
 
 Open a graph or a repo from the window's title bar to explore your own code.
-The UI is channel-agnostic — only the Electron shell (`electron/main.mjs` +
-`electron/preload.cjs`) is desktop-specific; the same page stays servable as a
+The UI is channel-agnostic. Only the Electron shell (`electron/main.mjs` +
+`electron/preload.cjs`) is desktop-specific. The same page stays servable as a
 plain web page. `npm run test:electron` runs the shell smoke via Playwright and
 skips cleanly when the binary is absent.
 
@@ -226,8 +227,8 @@ resolves to a real graph traversal or declines cleanly:
   (*because/although/while*), conditionals, and false-premise flags ("why
   does X still import Y" when it no longer does).
 
-The full catalog with measured coverage lives in `CAPABILITIES_2.7.12.md` and
-the `BENCHMARK_*.md` reports.
+The full catalog with measured coverage lives in the `BENCHMARK_*.md`
+reports.
 
 **Response finishing.** Before an answer prints, it is segmented into typed
 spans: prose versus *protected* entities, paths, numbers, code, provenance,
@@ -310,7 +311,7 @@ planner over the same read-only graph-query tools chat/serve use
 step in order with a provable causal-link proof chain, and folds the results
 into one answer. A request neither the planner nor a single lookup can ground
 escalates to a closed-world goal-reasoner, which deduces maintenance goals
-(coverage gaps, change-coupling risk) straight from the graph — never from
+(coverage gaps, change-coupling risk) straight from the graph, never from
 keywords in your question. Anything none of that grounds is an honest "no plan
 found", the same "grounded or an honest miss" rule as everywhere else in tmct.
 
@@ -344,7 +345,7 @@ composed answer (4): src/handlers/base.mjs, src/handlers/users.mjs, src/server/a
 ```
 
 tmct planned two calls (`tmct_impact` then `tmct_untested`), ran both against the
-real graph, and intersected the results itself — you get the four modules that
+real graph, and intersected the results itself. You get the four modules that
 are both downstream of the change AND missing coverage, not two separate lists
 you'd have to cross-reference by hand.
 
@@ -361,7 +362,7 @@ composed answer (1): src/lib/http.mjs
 
 It deduced the goal ("an impactful module must be tested"), gathered every
 untested module, ranked each by blast radius, and named the one worth testing
-first — `src/lib/http.mjs`, the module with the widest reach.
+first: `src/lib/http.mjs`, the module with the widest reach.
 
 `--tools tmct_impact,tmct_untested` restricts which capabilities the planner is
 allowed to use; `--json` prints the full machine-readable loop result (calls,
@@ -372,9 +373,9 @@ flag reference.
 ## Teach it a game, then ask it to plan
 
 The planner above works over a fixed toolset. This one works over rules you
-teach. A game definition is a plain-text file of controlled English — the
+teach. A game definition is a plain-text file of controlled English: the
 classes, the pieces, the ordering, and the legal moves as taught action
-rules — with `#` comment lines carrying example prompts. `tmct init`
+rules, with `#` comment lines carrying example prompts. `tmct init`
 scaffolds one at `.tmct/imports/games/hanoi-3.txt`, and
 `tmct import --file` teaches it sentence by sentence, reporting every line
 and refusing (exit 1) if any sentence declines.
@@ -402,8 +403,8 @@ Goal (inferred): Plan a move sequence from the current state to the goal (7 move
 facts stamped with the step that produced them ("disk-1@step1 rests on peg-c",
 sourced to the plan). The final step re-reads the store and confirms the goal
 from those written facts, never assuming success. The stamp is what makes each
-step a separate record; a question about the piece itself ("where does disk-1
-rest?", "is disk-1 clear?") reads the current board — the latest step's facts,
+step a separate record. A question about the piece itself ("where does disk-1
+rest?", "is disk-1 clear?") reads the current board: the latest step's facts,
 not every step at once. The search is
 domain-general: the test
 suite teaches Towers of Hanoi purely as sentences for 1 to 8 disks and
@@ -417,17 +418,17 @@ the plan as a self-contained animated page (see "Two more surfaces" above).
 Three games run inside an ordinary chat session, no setup.
 
 **Guess the number.** Say `I'm thinking of a number between 1 and 100` and
-tmct guesses by narrowing an interval — answer `higher`, `lower`, or
+tmct guesses by narrowing an interval: answer `higher`, `lower`, or
 `correct`. It finds any number in at most 7 guesses, and if your answers
 contradict each other it names the contradicting pair and stops rather than
 guessing on. Say `think of a number` to swap seats: tmct commits to a secret
-and answers your guesses honestly, reveals on request, and corrects you from
-its own record if you claim it already said `correct`. The behaviour is
-pinned by `test/corpus/games/guess-number.jsonl`.
+and sticks to it. It answers your guesses, reveals the number on request, and
+corrects you from its own record if you claim it already said `correct`. The
+behaviour is pinned by `test/corpus/games/guess-number.jsonl`.
 
 **A text adventure.** Say `start the adventure` (or `play ashcombe hall`)
 and tmct loads a small country-house mystery from a lazily-fetched worlds
-pack (`corpus/worlds/`) into the session's ordinary memory graph — rooms,
+pack (`corpus/worlds/`) into the session's ordinary memory graph: rooms,
 objects and people become graph facts, and the verbs (`go`, `take`, `open`,
 `unlock`, `look`…) are taught action rules, not hard-wired code. Every move
 writes per-turn snapshot facts, `look` is an extractive digest of the graph,
@@ -436,30 +437,30 @@ schedule whether you are there to see it or not. The full worked mystery is
 pinned step by step in `test/corpus/games/adventure.jsonl`.
 
 **Two agents, planning against each other.** Say `play spider and fly` (or
-`watch the spider and the fly`) and tmct runs both sides itself — neither is
+`watch the spider and the fly`) and tmct runs both sides itself. Neither is
 player-controlled. A spider hunts a fly across a 10×10 web; each side only
 believes what it can currently see (`vision_radius`, tunable), a fly wanders
 when nothing threatens it and evades when something does, a spider avoids
 other spiders, chases what it believes it sees, and builds a web when it
 holds position. Mass is real: both sides waste away each turn they don't
 eat, and a spider gains exactly the mass of what it catches. You can address
-either side directly (`@spider the fly is east`) to feed it a belief — true
-or false — and watch a wrong assertion mislead it for as long as the real
+either side directly (`@spider the fly is east`) to feed it a belief, true
+or false, and watch a wrong assertion mislead it for as long as the real
 target stays out of sight. `tmct.toml`'s `[games.spider-fly]` table tunes
 every rate; the full mechanic is pinned in `test/corpus/games/spider-fly.jsonl`.
 
 ## Learning on a miss
 
-A question tmct cannot ground is still an honest miss — but on the cleanest
-kind of miss (a recognised word, a clean parse, simply no facts anywhere) it
+A question tmct cannot ground is still an honest miss. But on the cleanest
+kind of miss (a recognised word, a clean parse, simply no facts anywhere), it
 now consults two shipped, lazily-loaded packs before giving up:
 
-- `corpus/child/` — 93k everyday-world triples filtered from ConceptNet by a
+- `corpus/child/`: 93k everyday-world triples filtered from ConceptNet by a
   child-concept seed. Asked `what is a kettle` cold, tmct loads the term's
   triples into memory (provenance `child:conceptnet:kettle`, ranked below
   anything you teach) and answers from them; the next ask answers from
   memory directly.
-- `corpus/reference/` — 3,887 Simple English Wikipedia summaries. When the
+- `corpus/reference/`: 3,887 Simple English Wikipedia summaries. When the
   triples cannot answer, a matching article answers as a cited read-out
   (`source: reference article "Otter"…, CC BY-SA 4.0`).
 
@@ -495,7 +496,7 @@ by cleaned session logs:
   relevance rather than loaded wholesale.
 
 Every session also writes its own human-readable transcript,
-`.tmct/session-<id>.md` — a glow-friendly Markdown file with one heading per
+`.tmct/session-<id>.md`, a glow-friendly Markdown file with one heading per
 turn, the question as a blockquote, the reply in a fenced block. The
 browser chat page's "export .md" button writes the same shape.
 
@@ -538,7 +539,7 @@ Teaching isn't limited to the ACE grammar's fixed shapes. Tell tmct an
 arbitrary fact, like "margo really eats ribs", and it mints a fact you can
 ask about directly: "what does margo eat". New vocabulary compounds as you
 teach: "redis is a cache" mints "redis" even though it was never in the
-built-in lexicon, as long as one side of the sentence is already grounded —
+built-in lexicon, as long as one side of the sentence is already grounded.
 tmct never mints a fact between two totally ungrounded terms; it declines and
 nudges you to ground one side first. Quantified teaching stores the
 quantifier ("some functions are risky" … "how many functions are risky" →
@@ -553,13 +554,13 @@ rather than the code graph. A taught class answers both shapes too: after
 
 When you ask about a term, the read-back shows each "is a kind of" object with
 its own superclass chain: "what is rover" answers "rover is a kind of dog →
-canine → mammal → animal". If one label carries two unrelated senses — you
-taught "rover is a dog" and a corpus row says "rover is a scout" — the answer
+canine → mammal → animal". If one label carries two unrelated senses (you
+taught "rover is a dog" and a corpus row says "rover is a scout"), the answer
 groups by concept ("rover, the dog:" / "rover, the scout:") instead of listing
 two unrelated lines as if they were one thing. The split is deterministic over
 the stored hierarchy: two senses part when a stored disjointness separates
 their ancestors, when their chains never meet, or when they meet only at the
-very top. When the evidence is thin the answer stays a flat list — grouping is
+very top. When the evidence is thin the answer stays a flat list. Grouping is
 presentation, and it never retracts or reranks a fact.
 
 Teaching doesn't have to be typed, either. `tmct extract` runs a plain text
@@ -586,14 +587,14 @@ carries an `extracted:<file>` provenance tag at its own trust tier.
 recognizer skips: a copula or a known relation verb flanked by two nouns
 becomes a candidate triple, stored under its own `optimistic-extract:<file>`
 provenance (prior 0.35, below every curated pack) with no operator tag riding
-alongside — so a fuzzy guess can never corroborate a curated fact. It is an
+alongside, so a fuzzy guess can never corroborate a curated fact. It is an
 attempt, not full NLU: a sentence with no clean pair yields nothing.
 `--canonical` prints each grounded fact as a triple, noting how each endpoint
 already links into the store.
 
 The same pipeline is one library seam, `ingestText(text, options)` (exported
 as `@polycode-projects/the-mechanical-code-talker/ingest`), and one cold tool,
-`tmct_ingest` — so a browser page, a script, or a tool-calling agent can ground
+`tmct_ingest`. A browser page, a script, or a tool-calling agent can ground
 text without the CLI.
 
 ### Provenance and trust
@@ -754,7 +755,7 @@ already set up. Its `--graph` flag works differently from the others: it appends
 ```
 
 `tmct extract` is the document route into memory described under "Teach it"
-above — the same teach recognizer, reading a file instead of your typing:
+above: the same teach recognizer, reading a file instead of your typing:
 
 ```output:help:extract
   tmct extract <text-file>     read a plain text file's sentences through the chat's own
@@ -787,7 +788,7 @@ inference" above:
                                retractable entailed facts (never on the chat path)
 ```
 
-`tmct viz` renders the memory graph as the ledger explorer — a single,
+`tmct viz` renders the memory graph as the ledger explorer, a single,
 self-contained HTML file you can open in a browser:
 
 ```output:help:viz
@@ -867,7 +868,7 @@ aws/python/java) into ~7,380 facts on the default sqlite backend, a working
 example to copy from. `init:xl` starts from the large persona tier and adds
 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:
+vocabulary, so expect its imports to take a minute). The xl chain, spelled out:
 
 ```bash e2e heavy
 npx tmct init --persona-size large   # npm run init:xl runs this whole chain from a clone
@@ -1171,12 +1172,12 @@ The full tables, judge scores, and transcripts are in the linked write-ups.
 
 | What it does | Result (2.7.12) | Read the number with this | Method |
 |---|---|---|---|
-| Multi-hop entailment | 379/379 chat cases and 100/100 kernel cases, 0% fabrication, all bands pass | The case set is unchanged from 2.6.0 (same templates, same counts) — the one real move this cycle is INF-4's ceiling-graded count dropping 35→30, five cases that now pass as genuine capability instead of against the declared honest-miss floor. | `BENCHMARK_INFERENCE_2.7.12.md` |
-| Tool-call planning | 68/68 cases, 100% plan-completion, 100% result-completion, 0% hallucination, every rung A0→C2 | Goal driver. 2.6.0 gated at TOOL-7 (62/66, 94%) — this cycle's router uplift (a guarded RECOVER step, a tied-candidate composer) cleared it, a real capability move, not a ruler change. | `BENCHMARK_AGENT_2.7.12.md` |
+| Multi-hop entailment | 379/379 chat cases and 100/100 kernel cases, 0% fabrication, all bands pass | The case set is unchanged from 2.6.0 (same templates, same counts). The one real move this cycle is INF-4's ceiling-graded count dropping 35→30: five cases that now pass as genuine capability instead of against the declared honest-miss floor. | `BENCHMARK_INFERENCE_2.7.12.md` |
+| Tool-call planning | 68/68 cases, 100% plan-completion, 100% result-completion, 0% hallucination, every rung A0→C2 | Goal driver. 2.6.0 gated at TOOL-7 (62/66, 94%). This cycle's router uplift (a guarded RECOVER step, a tied-candidate composer) cleared it: a real capability move, not a ruler change. | `BENCHMARK_AGENT_2.7.12.md` |
 | Groundedness | Every answer carries a source, and an empty graph reports itself empty. Judge-scored mean 1.809/2 over 138 cases, 5 hard fails, 136/138 tier-1. | Judged (`claude-haiku-4-5-20251001`, `judge-prompt-v2`) at N=1. The judge prompt moved v1→v2 since 2.6.0, so this is a measurement, not a clean lever comparison against the prior cycle. The judge runs in the offline eval harness, never in the product. | `BENCHMARK_CEFR_ENGLISH_2.7.12.md` |
 | Abstention (the honest miss) | 0% fabrication across 479 inference rows (379 chat + 100 kernel) and 0% hallucination across 272 agent rows | Structural, not a tuned threshold. tmct abstains because nothing matched, so the rows test a property of a no-model design rather than a score. | `BENCHMARK_INFERENCE_2.7.12.md`, `BENCHMARK_AGENT_2.7.12.md` |
-| Determinism | Byte-identical on rerun — a 379-case `--replay` clean across 2 runs, no LLM, no network, $0 per turn | A property of the no-model pipeline. | `BENCHMARK_INFERENCE_2.7.12.md` |
-| Dialogue robustness (persona sweep) | A 6-persona sweep (textbook logician, casual newcomer, new developer, adversarial sceptic, returning user, planning user) fixed 25 of the prior cycle's 29 routed findings (21 clean, 4 with a residual noted); 4 remain broken, 2 in a shape distinct from the original complaint | Free exploration across all six personas surfaced roughly 60 fresh findings beyond the ratchet check — the single highest-signal pattern: tmct's own suggested repair text was itself frequently broken when followed verbatim (since fixed, see `NEXT.md`). | `BENCHMARK_CONVERSATION_2.7.11.md` |
+| Determinism | Byte-identical on rerun: a 379-case `--replay` clean across 2 runs, no LLM, no network, $0 per turn | A property of the no-model pipeline. | `BENCHMARK_INFERENCE_2.7.12.md` |
+| Dialogue robustness (persona sweep) | A 6-persona sweep (textbook logician, casual newcomer, new developer, adversarial sceptic, returning user, planning user) fixed 25 of the prior cycle's 29 routed findings (21 clean, 4 with a residual noted); 4 remain broken, 2 in a shape distinct from the original complaint | Free exploration across all six personas surfaced roughly 60 fresh findings beyond the ratchet check. The single highest-signal pattern: tmct's own suggested repair text was itself frequently broken when followed verbatim (since fixed, see `NEXT.md`). | `BENCHMARK_CONVERSATION_2.7.11.md` |
 
 Three offline benchmark rigs live in a clone (they are not in the npm
 package). Each replays a committed case set through the real product and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "2.11.9",
+  "version": "2.11.11",
   "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/domain/grammar/ace.mjs

@@ -641,7 +641,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

@@ -682,6 +682,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 +766,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 +920,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 it, take it&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">
@@ -960,6 +1003,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 +1031,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 +1110,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 +1132,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 +1233,97 @@ ${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("");
+  }
+  // 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>';
   }
@@ -1268,12 +1418,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" }));