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

package/bin/tmct.mjs

@@ -1261,7 +1261,8 @@ async function main() {
     const rest = process.argv.slice(3);
     if (rest.includes("--help") || rest.includes("-h")) {
       process.stdout.write(
-        "tmct serve — Anthropic Messages API-compatible endpoint (POST /v1/messages)\n\n" +
+        "tmct serve — Anthropic Messages API-compatible endpoint (POST /v1/messages)\n" +
+        "             plus a capability-router plan verb (POST /v1/plan)\n\n" +
         "Usage:\n" +
         "  tmct serve [--repo <abs>] [--graph <path>] [--config <path>] [--host <h>] [--port <n>]\n\n" +
         "  --repo <abs>   target a repo's graph (<abs>/.tmct/graph.json); default: git root/cwd\n" +
@@ -1270,9 +1271,14 @@ async function main() {
         "  --config <path>  an alternate tmct.toml location (a file or a directory)\n" +
         "  --host <h>     bind address (default 127.0.0.1)\n" +
         "  --port <n>     TCP port (default 8787; 0 picks an ephemeral port)\n\n" +
-        "Request:  { model, messages:[...], tools:[...], max_tokens, system? }\n" +
-        "Response: { id, type:\"message\", role:\"assistant\", content:[...blocks], stop_reason, usage }\n" +
-        "          usage is always { input_tokens: 0, output_tokens: 0 } — tmct is the $0 floor.\n",
+        "POST /v1/messages\n" +
+        "  Request:  { model, messages:[...], tools:[...], max_tokens, system? }\n" +
+        "  Response: { id, type:\"message\", role:\"assistant\", content:[...blocks], stop_reason, usage }\n" +
+        "            usage is always { input_tokens: 0, output_tokens: 0 } — tmct is the $0 floor.\n\n" +
+        "POST /v1/plan\n" +
+        "  Request:  { request: \"<NL request>\", tools?: [\"tmct_impact\", ...] }\n" +
+        "  Response: the capability-router loop result — grounded { driver, calls, proof,\n" +
+        "            composed?, usage } or an in-band honest { refused: true, why }.\n",
       );
       return;
     }
@@ -1287,13 +1293,19 @@ async function main() {
     // REPLACES serve's old cwd-only default (loadConfig had no git-root
     // fallback) with the same git-root-aware default every other subcommand
     // now shares — a deliberate, documented unification, not a regression.
-    const { config } = await resolveRuntimeConfig({ argv: rest });
-    const srv = await startServer({ config, host, port });
+    const { repo, config, toml } = await resolveRuntimeConfig({ argv: rest });
+    // Open the taught store the same env > tmct.toml > default way `tmct plan`
+    // does, so /v1/plan reasons over the taught world/rule records chat wrote —
+    // registered per request and unregistered after, never mutated by serve.
+    const { openMemoryBackend } = await import("../src/adapters/memory/core.mjs");
+    const backendChoice = String(process.env.TMCT_MEMORY_BACKEND || toml?.memory?.backend || "").trim().toLowerCase();
+    const { dir: memoryDir, close: closeMemoryStore } = await openMemoryBackend(repo, backendChoice);
+    const srv = await startServer({ config, host, port, memoryDir });
     process.stdout.write(
-      `tmct serve — Anthropic Messages API at ${srv.url}/v1/messages (POST) — ` +
+      `tmct serve — Anthropic Messages API at ${srv.url}/v1/messages (POST), plan at ${srv.url}/v1/plan (POST) — ` +
       `graph ${srv.config.graphFile} — usage billed $0 — Ctrl+C to stop\n`,
     );
-    const shutdown = async () => { await srv.close(); process.exit(0); };
+    const shutdown = async () => { await srv.close(); await closeMemoryStore(); process.exit(0); };
     process.on("SIGINT", shutdown);
     process.on("SIGTERM", shutdown);
     return; // the listening server keeps the event loop alive

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "2.11.6",
+  "version": "2.11.9",
   "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.",
@@ -144,6 +144,7 @@
     "build:plan-bundle": "node scripts/build-plan-bundle.mjs",
     "build:ledger-bundle": "node scripts/build-ledger-bundle.mjs",
     "build:ingest-bundle": "node scripts/build-ingest-bundle.mjs",
+    "build:research-bundle": "node scripts/build-research-bundle.mjs",
     "build:code-explorer-bundle": "node scripts/build-code-explorer-bundle.mjs",
     "build:electron": "node scripts/build-electron-app.mjs",
     "electron": "electron electron/main.mjs",

package/src/adapters/toml-config.mjs

@@ -108,6 +108,8 @@ export async function normalizeConfig(raw, { configDir } = {}) {
   const seedCfg = {};
   if (seed.enabled !== undefined) seedCfg.enabled = seed.enabled;
   if (seed.limit !== undefined) seedCfg.limit = seed.limit;
+  if (seed.capture_unknown_context !== undefined) seedCfg.captureUnknownContext = seed.capture_unknown_context;
+  if (seed.unknown_context_limit !== undefined) seedCfg.unknownContextLimit = seed.unknown_context_limit;
   if (Object.keys(seedCfg).length) cfg.seed = seedCfg;
 
   // Extension-pack seam (src/services/extensions.mjs): sparse PASS-THROUGH only — the

package/src/domain/ask-vocab.mjs

@@ -317,6 +317,38 @@ export const PASSIVE_PARTICIPLE_TO_KIND = Object.freeze({
   touched: "touches", changed: "touches", modified: "touches", edited: "touches", updated: "touches",
 });
 
+// ---- stacked reduced-relative clauses: a "<participle> <preposition>" bigram
+// that opens a reduced relative modifying a head noun ("classes INHERITED FROM
+// Widget DEFINED IN c.mjs"). Each entry names the relation kind and which role
+// the following term fills:
+//   role "object" — the surface is active-disguised, the preposition marks the
+//     relation's OBJECT, so the answer is the SUBJECTS pointing at the term (a
+//     reverse traversal): "inherited from Widget" -> the classes that inherit
+//     Widget.
+//   role "agent"  — a genuine passive whose "by"/"in" marks the AGENT, so the
+//     answer is the term's own FORWARD targets: "defined in c.mjs" -> what
+//     c.mjs defines.
+// Only consulted by parseStackedReducedRelative, which requires TWO such
+// bigrams on one head noun; a single reduced relative keeps its existing route.
+// Naming senses and directionally-ambiguous bigrams ("imported from", "used
+// in/for", "called <name>") are deliberately absent so they stay honest misses.
+export const REDUCED_RELATIVE_CLAUSES = Object.freeze({
+  "inherited from": { kind: "inherits", role: "object" },
+  "extended from": { kind: "inherits", role: "object" },
+  "subclassed from": { kind: "inherits", role: "object" },
+  "defined in": { kind: "defines", role: "agent" },
+  "declared in": { kind: "defines", role: "agent" },
+  "contained in": { kind: "contains", role: "agent" },
+  "imported by": { kind: "imports", role: "agent" },
+  "called by": { kind: "calls", role: "agent" },
+  "used by": { kind: "uses", role: "agent" },
+  "tested by": { kind: "tests", role: "agent" },
+  "covered by": { kind: "tests", role: "agent" },
+  "touched by": { kind: "touches", role: "agent" },
+  "changed by": { kind: "touches", role: "agent" },
+  "exported by": { kind: "reexports", role: "agent" },
+});
+
 // ---- normalization: contractions/informal spellings expanded before parsing,
 // shared by both parse strategies. ----
 export const CONTRACTIONS = Object.freeze({

package/src/domain/ask.mjs

@@ -23,7 +23,7 @@ import {
   CONTEXT_PRONOUNS, META_MEANING_VERBS,
   WHERE_MARKERS, MENTION_MARKERS,
   RELATIVE_PRONOUNS, PLACEHOLDER_NOUNS, BOOLEAN_CONNECTIVES, QUALIFIERS,
-  PASSIVE_PARTICIPLE_TO_KIND, GENERIC_AGENT_WORDS,
+  PASSIVE_PARTICIPLE_TO_KIND, GENERIC_AGENT_WORDS, REDUCED_RELATIVE_CLAUSES,
   AGGREGATE_TRIGGERS, LIST_TRIGGERS, SUPERLATIVE_EXTREMES, EDGE_NOUN_TO_METRIC, METRIC_IMPLIES_ENTITY, ANAPHORA_TRIGGERS,
   MEMBERSHIP_KINDS, CASCADE_NOISE, CASCADE_SYNONYMS, HELP_TRIGGERS,
   stripTrailingScopeFiller,
@@ -236,9 +236,57 @@ function parseComposite(text, nlp) {
     || parseList(w, lc, nlp, 0)
     || parseNested(w, lc, nlp, 0)
     || parsePluralAnaphoraObject(w, lc, nlp)
+    || parseStackedReducedRelative(w, lc)
     || parseRelationalOrQualified(w, lc, nlp, 0);
 }
 
+// Two reduced relatives stacked on one head noun ("classes INHERITED FROM
+// Widget DEFINED IN c.mjs") — a garden-path shape a naive incremental parser
+// misattaches as a second main clause. Both clauses modify the head, so the
+// reading is their intersection. Each clause's REDUCED_RELATIVE_CLAUSES entry
+// says whether its term is the relation's object (reverse: the subjects that
+// point at it) or its agent (forward: the term's own targets). The head noun's
+// entityType rides the SEED clause, so a forward "defines" leg that would
+// otherwise return every symbol is filtered to the asked kind. Anything that
+// isn't exactly [lead] head bigram term bigram term returns null, leaving
+// every other shape's behavior byte-identical.
+const STACKED_RRC_LEAD = new Set(["which", "the", "all"]);
+function parseStackedReducedRelative(w, lc) {
+  let i = 0;
+  if (STACKED_RRC_LEAD.has(lc[i])) i += 1;
+  const noun = entityNoun(lc[i]);
+  if (!noun || noun.placeholder || !noun.entityType) return null;
+  const entityType = noun.entityType;
+  i += 1;
+  const bigramAt = (k) => (k + 1 < lc.length ? REDUCED_RELATIVE_CLAUSES[`${lc[k]} ${lc[k + 1]}`] : undefined);
+  const rr1 = bigramAt(i);
+  if (!rr1) return null;
+  const term1Start = i + 2;
+  let split = -1;
+  let rr2;
+  for (let k = term1Start; k + 1 < lc.length; k += 1) {
+    const hit = bigramAt(k);
+    if (hit) { split = k; rr2 = hit; break; }
+  }
+  if (split < 0) return null;
+  const term1 = w.slice(term1Start, split).join(" ").trim();
+  const term2 = w.slice(split + 2).join(" ").trim();
+  if (!term1 || !term2) return null;
+  const clauseFor = (rr, term) => (rr.role === "object"
+    ? { shape: "reverse", kind: rr.kind, entityType, modifier: "direct", object: term }
+    : { shape: "forward", kind: rr.kind, modifier: "direct", object: term });
+  const seed = clauseFor(rr1, term1);
+  seed.entityType = entityType;   // head-noun class filter on the seed set
+  return {
+    node: "boolean",
+    entityType,
+    atoms: [
+      { op: "seed", kind: "set", ast: { node: "clause", clause: seed } },
+      { op: "intersection", kind: "set", ast: { node: "clause", clause: clauseFor(rr2, term2) } },
+    ],
+  };
+}
+
 // Negation as set complement: "which X do not <verb> Y" compiles to
 // allOfClass(kind) DIFFERENCE (the positive result set). The "Change"
 // pseudo-type has no bounded enumerable universe, so a complement over
@@ -598,6 +646,12 @@ function parsePredicateFilter(words, nlp) {
   const restLc = lc.slice(i);
   if (!rest.length) return { type: "all" };
   if (restLc.every((x) => QUALIFIERS[x])) return { type: "qual", filters: restLc };
+  // A bare concrete entity noun ("which of them are functions") narrows the
+  // prior set to one class rather than testing a relation.
+  if (rest.length === 1) {
+    const en = entityNoun(restLc[0]);
+    if (en && !en.placeholder && en.entityType) return { type: "entity", entityType: en.entityType };
+  }
   const clause = parseSimpleClause(`what ${rest.join(" ")}`, nlp);
   if (clause && (clause.shape === "reverse" || clause.shape === "forward") && clause.object) {
     return { type: "clause", clause };
@@ -1729,6 +1783,8 @@ function evalAnaphora(graph, ast, opts) {
   const f = ast.filter;
   if (f && f.type === "qual") {
     items = items.filter((ind) => f.filters.every((q) => qualHolds(graph, ind, QUALIFIERS[q])));
+  } else if (f && f.type === "entity") {
+    items = items.filter((ind) => ind.class === f.entityType);
   } else if (f && f.type === "clause") {
     const r = resolveObject(graph, f.clause.object);
     if (!r.match) items = [];
@@ -1743,9 +1799,12 @@ function evalAnaphora(graph, ast, opts) {
   }
   // A count over a prior set names the entity kind when survivors share a
   // class; fall back to the prior set's own class when the filter empties it,
-  // so the honest-empty render still names what was checked.
+  // so the honest-empty render still names what was checked. An entity-type
+  // filter that empties the set names the FILTER's kind ("functions"), not the
+  // base set's — the reader asked which of them were that kind.
   const sameClass = (list) => (list.length && list.every((x) => x.class === list[0].class) ? list[0].class : null);
-  const common = items.length ? sameClass(items) : sameClass(baseItems);
+  const emptyClass = f && f.type === "entity" ? f.entityType : sameClass(baseItems);
+  const common = items.length ? sameClass(items) : emptyClass;
   if (ast.mode === "count") return { compositeKind: "count", count: items.length, entityType: common, matches: [] };
   return { compositeKind: "set", matches: items, entityType: common };
 }
@@ -3296,6 +3355,15 @@ function bareVerbFor(kind) {
   return RELATIONS[kind]?.bare || kind;
 }
 
+/** The passive participle of a relation ("uses" -> "used", "imports" ->
+ *  "imported"), for the confirming "X is <participle> by Y" frame. The bare
+ *  forms in this vocabulary are all regular, so a single +d/+ed rule covers
+ *  them. */
+function passiveParticipleFor(kind) {
+  const bare = bareVerbFor(kind);
+  return bare.endsWith("e") ? `${bare}d` : `${bare}ed`;
+}
+
 /** English gloss of a SET-COMPLEMENT AST — the shape parseNegation compiles
  *  "which X do not <verb> Y" into (allOfClass DIFFERENCE the positive set).
  *  Restates the question in the same grammar the positive canonical uses
@@ -3747,11 +3815,28 @@ function renderCore(parsed, result, graph) {
       };
     }
     const entityWord = nounFor(parsed.entityType || "Module", 2);
+    // Name the resolved antecedent, not the raw pronoun: "who touched it" that
+    // bound "it" to fnAlpha must say so, or the receipt reads as though nothing
+    // was resolved at all. Scoped to a context pronoun so a typed term keeps the
+    // wording the reader chose, never its normalized graph label.
+    const object = (result.objMatch && CONTEXT_PRONOUNS.includes(String(parsed.object || "").toLowerCase()))
+      ? result.objMatch.label
+      : parsed.object;
     return {
-      content: `No ${entityWord} found whose module directly ${verbFor(parsed.kind)} ${parsed.object}. ${touchesRephraseHint(graph)}`,
+      content: `No ${entityWord} found whose module directly ${verbFor(parsed.kind)} ${object}. ${touchesRephraseHint(graph)}`,
       miss: true, ambiguous: false,
     };
   }
+  // A polar reverse question ("is X used anywhere") with exactly one match
+  // reads as a confirming yes that names the single subject, rather than a bare
+  // one-item list. Scoped to one match: two or more keep the plain list.
+  if (parsed.polar && result.matches.length === 1) {
+    const objLabel = result.objMatch?.label || parsed.object;
+    return {
+      content: `Yes — ${objLabel} is ${passiveParticipleFor(parsed.kind)} by ${result.matches[0].label}.`,
+      miss: false, ambiguous: false, matches: result.matches,
+    };
+  }
   // Route by the matched entities' actual class, not just the parsed hint —
   // grouping module-level matches by-module would read as nonsense ("in
   // a.mjs there is a.mjs"). Fine-grained grouping only applies to sub-module

package/src/domain/domain.mjs

@@ -228,6 +228,20 @@ export function stateFromFacts(factRows, domain) {
   return state;
 }
 
+/** The highest @stepN snapshot index present for a domain individual, or 0
+ *  when the board carries no snapshot layer yet. A freshly minted plan reads
+ *  this as its stepBase, so its own @stepK writes stack ABOVE any standing
+ *  snapshot instead of colliding with it and being read as the same layer. */
+export function maxSnapshotStep(factRows, domain) {
+  const individuals = domainIndividuals(domain);
+  let max = 0;
+  for (const row of factRows || []) {
+    const m = SNAPSHOT_RE.exec(normTerm(row.subject));
+    if (m && individuals.has(m[1])) max = Math.max(max, Number(m[2]));
+  }
+  return max;
+}
+
 /** Canonical identity for a state (rows are kept sorted). NUL-joined so
  *  multi-word terms can never collide with the separator; spelled without an
  *  escape sequence because tooling has twice turned a source-level \\0 into a

package/src/domain/interpret/strategies/keywords.mjs

@@ -19,6 +19,11 @@ import { VOCAB_WORDS, eligibleForCanon, fuzzyVocabWord } from "../fuzzy.mjs";
 const PASSIVE_AUX = new Set(["is", "are", "was", "were", "be", "been", "being", "get", "gets", "got"]);
 const WH_WORDS = new Set(["which", "what", "who", "whom", "whose"]);
 const PLACEHOLDER_SET = new Set(PLACEHOLDER_NOUNS.map((w) => w.toLowerCase()));
+// A trailing time adverb on a bare passive ("was X touched RECENTLY") is not the
+// relation's object — it modifies the whole clause. Only consulted on the
+// participle path with no agent "by", so it can never touch an active-verb
+// object slot. Mirrors ask.mjs's TEMPORAL_TRAIL_FILLER for the when-shape.
+const TEMPORAL_TRAILING_ADVERBS = new Set(["recently", "lately", "yet", "already", "ever", "again"]);
 // See ask-vocab.mjs's own HAS_FAMILY_VERBS for why a bare have-family verb
 // never resolves to `defines` in this strategy's two-named-role "ask" shape
 // below (the forward/reverse branches keep their own tested grain-check
@@ -198,7 +203,14 @@ export function parseKeywordSpot(text, nlp = null) {
     .join(" ")
     .trim();
   const beforeText = sideText(0, verbHit.start);
-  const afterText = sideText(verbHit.end, words.length);
+  let afterText = sideText(verbHit.end, words.length);
+  // A lone trailing time adverb after a bare participle ("was it touched
+  // recently") is clause-level, not the relation's object; drop it so the
+  // sentence reaches the bare-passive branch and answers over the patient
+  // instead of trying to resolve "recently" as a term.
+  if (verbFromParticiple && !lcWords.includes("by") && TEMPORAL_TRAILING_ADVERBS.has(afterText.toLowerCase())) {
+    afterText = "";
+  }
   const kind = verbHit.kind;
   // slices read canonWords, not lcWords: the entity/modifier spans were matched
   // against the canonicalized array, whose word IS the table key.
@@ -316,7 +328,11 @@ export function parseKeywordSpot(text, nlp = null) {
     // nobody asked, so this declines and the sentence misses honestly.
     if (beforeText.split(/\s+/).length > 1) return null;
     if (kind === "touches") return stamp({ shape: "when", entityType: null, modifier: "direct", kind, object: beforeText });
-    return stamp({ shape: "reverse", entityType, modifier, kind, object: beforeText });
+    // A sentence that LEADS with the passive auxiliary is an interrogative
+    // yes/no ("is X used anywhere"), not a declarative patient statement; mark
+    // it so a single reverse match can render a confirming Yes frame.
+    const polar = PASSIVE_AUX.has(lcWords[0]);
+    return stamp({ shape: "reverse", entityType, modifier, kind, object: beforeText, ...(polar ? { polar: true } : {}) });
   }
   // forward keeps the spotted entityType (traverse()'s commit-as-subject grain
   // selection); modifier stays hardcoded since no forward closure traversal exists.

package/src/domain/reference-pack.mjs

@@ -139,9 +139,16 @@ const ISA_GENERIC_HEADS = new Set([
   "type", "kind", "sort", "form", "class", "variety", "group", "part",
   "piece", "member", "way", "term", "name", "word", "thing", "example",
   "family", "genus", "species", "unit", "series", "set", "list", "number",
-  "amount",
+  "amount", "body", "mass",
 ]);
 const ISA_ARTICLES = new Set(["a", "an", "the"]);
+// The classifier heads an of-chain reads THROUGH to the real class ("a kind
+// of dog" → dog). Any other head before "of" keeps the outer phrase: "a body
+// of ice" states composition, and "a game of skill" is a game — neither
+// makes the of-object the class.
+const ISA_OF_READ_THROUGH = new Set([
+  "type", "kind", "sort", "form", "class", "variety", "species", "breed", "genus",
+]);
 
 /** The isa lemma of a lead's first sentence, or null. The copula must sit in
  *  the first sentence; an of-chain resolves to its final noun ("a kind of
@@ -158,8 +165,13 @@ export function isaOf(plain, lexicon) {
     window.push(word);
     if (window.length >= 6) break;
   }
-  const lastOf = window.lastIndexOf("of");
-  let headWords = lastOf >= 0 ? window.slice(lastOf + 1) : window;
+  let headWords = window;
+  for (let ofIdx = headWords.indexOf("of"); ofIdx > 0; ofIdx = headWords.indexOf("of")) {
+    const outer = headWords[ofIdx - 1]?.split("-").pop();
+    if (outer && ISA_OF_READ_THROUGH.has(outer)) { headWords = headWords.slice(ofIdx + 1); continue; }
+    headWords = headWords.slice(0, ofIdx);
+    break;
+  }
   while (headWords.length && ISA_ARTICLES.has(headWords[0])) headWords = headWords.slice(1);
   if (!headWords.length) return null;
   const headToken = headWords[headWords.length - 1].split("-").pop();

package/src/services/adventure-viz.mjs

@@ -570,7 +570,6 @@ ${THEME_TOKENS_CSS}
   main { max-width: 920px; margin: 0 auto; padding: 1.4rem 1.2rem 2.2rem; }
   .eyebrow { font-family: ${MONO_STACK}; font-size: .7rem; letter-spacing: .12em; text-transform: uppercase; color: var(--gilt); }
   .titlebar { display: flex; align-items: baseline; justify-content: space-between; gap: 1rem; flex-wrap: wrap; margin: .3rem 0 1rem; }
-  h1 { font-size: 1.4rem; margin: 0; text-wrap: balance; }
   button { font: inherit; color: inherit; background: none; cursor: pointer; }
   button:focus-visible { outline: 2px solid var(--ink); outline-offset: 2px; }
   .mode-toggle { font-family: ${MONO_STACK}; font-size: .72rem; letter-spacing: .04em; text-transform: uppercase; padding: .4rem .8rem; border: 1px solid var(--gilt); background: var(--parchment); color: var(--ink); white-space: nowrap; }
@@ -646,8 +645,11 @@ ${THEME_TOKENS_CSS}
   /* the room-kind icon — filled through the exact same property-aware
      sprite resolver the room's own object cards use, keyed on the room's own
      name (so library/kitchen/garden reach their large TOMLs, everything else
-     falls back through room's own ancestor chain to the generic room icon). */
-  .room-kind-icon { position: absolute; top: .55rem; right: .6rem; width: 28px; height: 28px; opacity: .92; }
+     falls back through room's own ancestor chain to the generic room icon).
+     Rendered at 120px — twice a room-object sprite's own 60px frame
+     (.sprite-frame below) — so the room itself reads as the biggest thing
+     drawn in its own scene. */
+  .room-kind-icon { position: absolute; top: .5rem; right: .6rem; width: 120px; height: 120px; opacity: .92; }
   .room-kind-icon svg { width: 100%; height: 100%; display: block; }
   .room-kind-icon:empty { display: none; }
   .sprite-row { display: flex; align-items: flex-end; gap: .9rem .7rem; min-height: 2.5rem; }
@@ -735,6 +737,19 @@ ${THEME_TOKENS_CSS}
   .map-viewport > div { width: 100%; height: 100%; }
   .map-viewport svg { width: 100%; height: 100%; display: block; }
   .map-viewport .empty-note { color: var(--parchment); opacity: .8; }
+  /* the play-mode map only: a fixed SQUARE viewport (width pinned to the
+     same 190px height above, centered) rather than stretching to the side
+     column's own width — the svg still scales to fit inside it either way,
+     this just keeps the board's own footprint stable and click-to-enlarge
+     honest about what it's enlarging. */
+  .map-viewport-fixed { width: 190px; margin: 0 auto; cursor: zoom-in; }
+  /* the lights-down map lightbox — the same board, the same roomMapSvg
+     output, just drawn bigger over a dimmed backdrop. Closes on a click
+     anywhere outside the enlarged board, or Escape. */
+  .map-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); }
+  .map-lightbox[hidden] { display: none; }
+  .map-lightbox-inner { width: min(70vmin, 640px); height: min(70vmin, 640px); background: var(--baize); border: 3px solid var(--gilt); box-shadow: inset 0 0 0 1px var(--baize-line), 0 12px 48px rgba(0, 0, 0, .5); padding: 16px; box-sizing: border-box; }
+  .map-lightbox-inner svg { width: 100%; height: 100%; display: block; }
   .roommap .room-edge { stroke: var(--board-path); stroke-width: 7; }
   .roommap .room-hint { fill: var(--board-path); opacity: .8; }
   .roommap .room-node rect { fill: var(--parchment); stroke: var(--baize-line); stroke-width: 1.5; }
@@ -764,6 +779,19 @@ ${THEME_TOKENS_CSS}
      a quoted manuscript line reporting what "look" would say right now. */
   .caption { background: var(--parchment); border-left: 3px solid var(--gilt); padding: .55rem .7rem; font-size: .86rem; font-style: italic; margin: 0 0 .5rem; }
   .caption:empty { display: none; margin: 0; }
+  /* "what would you like to do" — the room's own contextual pills sit
+     top-right of the heading, on the header's own row; more pills than fit
+     wrap onto further lines still pinned to the right (justify-content:
+     flex-end on the inner .pills flex box), so the block grows down and
+     toward the left rather than pushing the heading around. */
+  .command-head { display: flex; align-items: flex-start; justify-content: space-between; gap: .3rem .6rem; margin: 0 0 .5rem; padding-bottom: .3rem; border-bottom: 1px solid var(--line); }
+  .command-head h2 { flex: 0 0 auto; margin: 0; padding: 0; border-bottom: none; }
+  /* nowrap on .command-head itself keeps the pills box on the SAME row as
+     the heading (top-right); .pills' own min-width: 0 lets IT shrink below
+     its natural width so ITS children (not the whole box) are what wraps
+     onto further lines, staying right-anchored rather than dropping the
+     whole pill row under the heading. */
+  .command-head .pills { flex: 1 1 auto; min-width: 0; justify-content: flex-end; margin-bottom: 0; }
   .chatask { display: flex; align-items: center; gap: .5rem; border-top: 1px solid var(--line); padding-top: .5rem; }
   .chatask .prompt { color: var(--taught); font-size: .78rem; font-family: ${MONO_STACK}; }
   .chatask input { flex: 1; font-family: ${MONO_STACK}; font-size: .78rem; background: var(--bg); color: var(--ink); border: 1px solid var(--line); padding: .32rem .55rem; min-width: 0; }
@@ -799,23 +827,34 @@ ${THEME_TOKENS_CSS}
   body.preview .side, body.preview .stage-left > .panel, body.preview .controls-row, body.preview .status { display: none; }
   body.preview main { padding: 0; max-width: none; }
   body.preview .stage { display: block; }
-  body.preview .eyebrow, body.preview h1, body.preview .mode-toggle, body.preview #editStage, body.preview .page-note { display: none; }
+  body.preview .eyebrow, body.preview .mode-toggle, body.preview #editStage, body.preview .page-note { display: none; }
 </style>
 </head>
 <body>
 <main>
-  <div class="eyebrow">tmct &middot; the adventure</div>
   <div class="titlebar">
-    <h1>A room, drawn from exactly what the text already says is there</h1>
+    <div class="eyebrow">tmct &middot; the adventure</div>
     <button id="editModeBtn" type="button" class="mode-toggle" disabled>edit the world</button>
   </div>
   <p class="page-note">${escapeHtml(worldPayload.opening)}</p>
   <div class="stage" id="playStage">
     <div class="stage-left">
+      <div class="controls-row" id="playControls">
+        <button id="resetBtn" type="button" disabled>reset</button>
+        <button id="playBtn" type="button" disabled>&#9654; play</button>
+        <button id="stepBtn" type="button" disabled>step</button>
+        <span class="turn mono" id="turnLabel">turn: 0</span>
+      </div>
+      <div class="goal-line" id="goalLine"></div>
+      <div class="status" id="status">loading the engine&hellip;</div>
       <div class="panel goals">
         <h2>quest</h2>
         <div id="goalList"></div>
       </div>
+      <div class="panel carrying">
+        <h2>satchel</h2>
+        <div class="chips" id="carryList"></div>
+      </div>
       <div class="room-frame" id="roomFrame">
         <div class="room-plaque mono" id="roomName"></div>
         <div class="room-kind-icon" id="roomKindIcon"></div>
@@ -825,39 +864,32 @@ ${THEME_TOKENS_CSS}
           <div class="you-slot" id="youSlot"></div>
         </div>
       </div>
-      <div class="controls-row" id="playControls">
-        <button id="resetBtn" type="button" disabled>reset</button>
-        <button id="playBtn" type="button" disabled>&#9654; play</button>
-        <button id="stepBtn" type="button" disabled>step</button>
-        <span class="turn mono" id="turnLabel">turn: 0</span>
-      </div>
-      <div class="goal-line" id="goalLine"></div>
-      <div class="status" id="status">loading the engine&hellip;</div>
-      <div class="panel carrying">
-        <h2>satchel</h2>
-        <div class="chips" id="carryList"></div>
-      </div>
       <div class="panel command">
-        <h2>speak to the manor</h2>
+        <div class="command-head">
+          <h2>What would you like to do</h2>
+          <div class="pills" id="pills"></div>
+        </div>
         <form class="chatask" id="chatform">
           <span class="prompt mono">tmct&gt;</span>
           <input id="chatq" type="text" placeholder="go north" aria-label="Type a command, or ask a question" disabled>
         </form>
       </div>
+    </div>
+    <aside class="side" aria-label="The adventure's log and chat">
       <div class="panel roommap">
         <h2>the manor, so far</h2>
-        <div class="map-viewport"><div id="mapWrap"></div></div>
+        <div class="map-viewport map-viewport-fixed" id="mapViewport"><div id="mapWrap"></div></div>
       </div>
-    </div>
-    <aside class="side" aria-label="The adventure's log and chat">
       <div class="chat">
         <h2>the manor's own account</h2>
         <div class="chatlog" id="chatlog" aria-live="polite"></div>
-        <div class="pills" id="pills"></div>
         <div class="caption" id="caption"></div>
       </div>
     </aside>
   </div>
+  <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="stage editor-stage" id="editStage" aria-label="The world editor">
     <div class="panel edittext">
@@ -925,6 +957,9 @@ ${engineBundleJs ? `<script>\n${embedScriptText(engineBundleJs)}\n</script>` : `
   const chatqEl = el("chatq");
   const carryListEl = el("carryList");
   const mapWrapEl = el("mapWrap");
+  const mapViewportEl = el("mapViewport");
+  const mapLightboxEl = el("mapLightbox");
+  const mapLightboxInnerEl = el("mapLightboxInner");
   const goalListEl = el("goalList");
   const editModeBtn = el("editModeBtn");
   const editorTextEl = el("editorText");
@@ -1120,6 +1155,25 @@ ${engineBundleJs ? `<script>\n${embedScriptText(engineBundleJs)}\n</script>` : `
   function renderRoomMap(rows, state, visitedRoomIds) {
     mapWrapEl.innerHTML = roomMapSvg(visitedRoomGraph(state, visitedRoomIds), false) || '<span class="empty-note">nowhere yet</span>';
   }
+
+  // ---- the map lightbox — clicking the fixed-square play-mode map redraws
+  // the SAME roomMapSvg output larger, over a dimmed backdrop; clicking the
+  // backdrop (not the board itself) or pressing Escape closes it.
+  function openMapLightbox() {
+    if (!lastSnapshot) return;
+    const svg = roomMapSvg(visitedRoomGraph(lastSnapshot.state, lastSnapshot.visitedRoomIds), false);
+    if (!svg) return;
+    mapLightboxInnerEl.innerHTML = svg;
+    mapLightboxEl.hidden = false;
+  }
+  function closeMapLightbox() {
+    mapLightboxEl.hidden = true;
+    mapLightboxInnerEl.innerHTML = "";
+  }
+  mapViewportEl.addEventListener("click", openMapLightbox);
+  mapLightboxEl.addEventListener("click", (e) => { if (e.target === mapLightboxEl) closeMapLightbox(); });
+  document.addEventListener("keydown", (e) => { if (e.key === "Escape" && !mapLightboxEl.hidden) closeMapLightbox(); });
+
   function renderEditMap(rows, state) {
     editMapWrapEl.innerHTML = roomMapSvg(visitedRoomGraph(state, allRoomIds(rows)), true) || '<span class="empty-note">this world defines no rooms</span>';
   }