@polycode-projects/the-mechanical-code-talker 2.10.2 → 2.10.3

package/package.json

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

@@ -5,9 +5,18 @@
 // arrives as data from the memory store's fact/Rule rows. Plugs into
 // planning.mjs's findActionPath as its applyActions.
 
+import { provenanceTagToSource } from "./memory/trust.mjs";
+
 const MEMBER_EDGE_PREDICATES = new Set(["rdfs:subClassOf", "rdf:type"]);
 const SNAPSHOT_RE = /^(.+)@step(\d+)$/;
 
+/** The class-member list a grounding step ranges over. The default "all" is
+ *  every typed member; "taught" restricts to instances a person taught, the
+ *  scope the plan lane uses so a merged corpus never widens a quantified goal
+ *  or the movable set. Falls back to nothing for an unknown scope. */
+const membersInScope = (domain, cls, scope) =>
+  (scope === "taught" ? domain.taughtClassMembers : domain.classMembers)?.[cls] || [];
+
 /** Trim a taught term defensively: some teach frames keep a sentence's
  *  trailing punctuation in the captured object. */
 const normTerm = (value) => String(value ?? "").trim().replace(/[.!?]+$/, "");
@@ -110,18 +119,34 @@ export function compileDomain(factRows, ruleRows) {
 
   // Class membership from typing edges. A member is a subject with a typing
   // edge into the class and no typing edge pointing at itself (a leaf).
-  const edges = (factRows || []).map(normRow).filter((r) => MEMBER_EDGE_PREDICATES.has(r.predicate));
-  const hasIncoming = new Set(edges.map((r) => r.object));
-  const classMembers = {};
-  for (const edge of edges) {
-    if (hasIncoming.has(edge.subject)) continue;
-    (classMembers[edge.object] ??= []).push(edge.subject);
-  }
-  for (const members of Object.values(classMembers)) {
-    members.sort();
-    // de-dup while keeping order
-    for (let i = members.length - 1; i > 0; i -= 1) if (members[i] === members[i - 1]) members.splice(i, 1);
-  }
+  const membersFromEdges = (typingEdges) => {
+    const hasIncoming = new Set(typingEdges.map((r) => r.object));
+    const members = {};
+    for (const edge of typingEdges) {
+      if (hasIncoming.has(edge.subject)) continue;
+      (members[edge.object] ??= []).push(edge.subject);
+    }
+    for (const list of Object.values(members)) {
+      list.sort();
+      // de-dup while keeping order
+      for (let i = list.length - 1; i > 0; i -= 1) if (list[i] === list[i - 1]) list.splice(i, 1);
+    }
+    return members;
+  };
+  const typingRows = (factRows || []).filter((r) => MEMBER_EDGE_PREDICATES.has(normTerm(r.predicate)));
+  const edges = typingRows.map(normRow);
+  const classMembers = membersFromEdges(edges);
+  // The same membership, restricted to instances a person taught (an operator
+  // assert or a teach-lane frame). A planner that quantifies over a class —
+  // "every X" — ranges over the taught individuals only: a merged corpus can
+  // type dozens of unrelated things into that class, and sweeping those into
+  // the goal makes it unsatisfiable and the search fruitless. classMembers
+  // keeps every member for the readers that want them all.
+  const taughtEdges = edges.filter((_, i) => {
+    const kind = provenanceTagToSource(typingRows[i].provenance)?.kind;
+    return kind === "operator" || kind === "teach";
+  });
+  const taughtClassMembers = membersFromEdges(taughtEdges);
 
   // A class-bound word (an effect role or constraint term that is neither
   // "subject" nor "target") is substituted by its class's sole member at
@@ -158,7 +183,7 @@ export function compileDomain(factRows, ruleRows) {
     .filter((r) => !dynamicPredicates.has(r.predicate) && !MEMBER_EDGE_PREDICATES.has(r.predicate))
     .sort(rowSort);
 
-  return { actions, classMembers, dynamicPredicates, ordering };
+  return { actions, classMembers, taughtClassMembers, dynamicPredicates, ordering };
 }
 
 const domainIndividuals = (domain) => {
@@ -312,13 +337,16 @@ function constraintViolated(action, nextState, domain) {
 }
 
 /** Every legal grounded action from `state`, with its successor.
- *  Deterministic: actions, signatures, and members are walked sorted. */
-export function movesFromRules(state, domain, { budget = 5000 } = {}) {
+ *  Deterministic: actions, signatures, and members are walked sorted. `scope`
+ *  ("all" | "taught") picks which class members ground the moves — the plan
+ *  lane passes "taught" so corpus members of a taught class never enter the
+ *  movable set. */
+export function movesFromRules(state, domain, { budget = 5000, scope = "all" } = {}) {
   let groundings = 0;
   for (const action of domain.actions) {
     for (const sig of action.signatures) {
-      groundings += (domain.classMembers[sig.subjectClass] || []).length *
-        (domain.classMembers[sig.targetClass] || []).length;
+      groundings += membersInScope(domain, sig.subjectClass, scope).length *
+        membersInScope(domain, sig.targetClass, scope).length;
     }
   }
   if (groundings > budget) throw new PlanBudgetError(groundings, budget);
@@ -327,8 +355,8 @@ export function movesFromRules(state, domain, { budget = 5000 } = {}) {
   for (const action of domain.actions) {
     const [verb, particle] = action.name.split(/\s+/);
     for (const sig of action.signatures) {
-      for (const subject of domain.classMembers[sig.subjectClass] || []) {
-        for (const target of domain.classMembers[sig.targetClass] || []) {
+      for (const subject of membersInScope(domain, sig.subjectClass, scope)) {
+        for (const target of membersInScope(domain, sig.targetClass, scope)) {
           if (subject === target) continue;
           let ok = true;
           for (const precond of action.preconds) {
@@ -360,7 +388,7 @@ export function movesFromRules(state, domain, { budget = 5000 } = {}) {
  *  state predicate. Satisfaction is a transitive walk along the goal
  *  predicate: a stacked member reaches the goal object through its support
  *  chain, which a direct row lookup cannot see. */
-export function compileGoal(goalSpecs, domain) {
+export function compileGoal(goalSpecs, domain, { scope = "all" } = {}) {
   const specs = (goalSpecs || []).map((g) => ({
     universal: Boolean(g.universal),
     term: normTerm(g.term),
@@ -369,7 +397,7 @@ export function compileGoal(goalSpecs, domain) {
   }));
   const checks = [];
   for (const spec of specs) {
-    const members = spec.universal ? domain.classMembers[spec.term] || [] : [spec.term];
+    const members = spec.universal ? membersInScope(domain, spec.term, scope) : [spec.term];
     if (spec.universal && members.length === 0) {
       throw new Error(`the goal names "${spec.term}" as a class, but it has no known members`);
     }

package/src/services/adventure.mjs

@@ -408,9 +408,21 @@ const BACKGROUND_FACT_PHRASES = {
   "mgx:atLocation": "is found in",
 };
 
+/** True when a fact row is provably owned by a NON-world source (a merged
+ *  corpus, a reference pack, a taught assert) rather than the loaded world. A
+ *  row with no provenance is not "non-world" — a hand-built digest view carries
+ *  none, and the room-look filter keeps those. World facts and their @turn
+ *  snapshots tag as `world:<name>[:turnN]`. */
+function isNonWorldSourced(row) {
+  const prov = String(row.provenance || "").trim();
+  return prov !== "" && !prov.startsWith("world:");
+}
+
 /** The digest's fact view: current placements (folded), exits, typing and
  *  every other surviving fact, with phrase predicates and sentence-cased
- *  subjects so the pipeline's sentence splitter sees real sentences. Pure. */
+ *  subjects so the pipeline's sentence splitter sees real sentences. Room text
+ *  is world-sourced only — a merged corpus's overlap on a room's own vocabulary
+ *  never leaks into the description. Pure. */
 export function worldDigestRows(rows, state) {
   const out = [];
   const seen = new Set();
@@ -440,6 +452,12 @@ export function worldDigestRows(rows, state) {
   }
   for (const row of rows || []) {
     if (SNAPSHOT_RE.test(row.subject)) continue;                 // folded above
+    // Room text comes from the world source only. A merged corpus overlaps a
+    // room's own vocabulary ("library rdfs:subClassOf literary study"), and
+    // without this those rows leak into the room description as stray sentences.
+    // A row with no provenance (a hand-built test view) is kept — the filter
+    // only drops rows a non-world source provably owns.
+    if (isNonWorldSourced(row)) continue;
     if (PLACEMENT_PREDICATES.has(row.predicate)) continue;       // folded above
     if (VIEW_EXCLUDED_PREDICATES.has(row.predicate)) continue;
     const exit = EXIT_PREDICATE_RE.exec(row.predicate);
@@ -909,6 +927,58 @@ async function worldOpennessAnswer(line, { memoryDir }) {
   );
 }
 
+// The in-game orientation asides — "where am I", "what can I do", "what is the
+// quest/goal". Without a world-state answer these fall through to the ordinary
+// lanes and misroute: "where am I" reads "I" as a module name, "what can I do"
+// walls, and "what is the goal" answers from corpus vocabulary about the word
+// "goal". A live world answers each from its own fold first.
+const WORLD_WHERE_AM_I_RE = /^where\s+am\s+i(?:\s+now)?[?.!\s]*$/i;
+const WORLD_OPTIONS_RE = /^(?:what\s+can\s+i\s+do(?:\s+(?:here|now))?|what\s+are\s+my\s+options|what\s+(?:should|do)\s+i\s+do(?:\s+(?:here|now))?|what\s+now)[?.!\s]*$/i;
+const WORLD_QUEST_RE = /^(?:what(?:'s|\s+is)\s+(?:the\s+|my\s+)?(?:quest|goal|objective|mission|aim)|what\s+am\s+i\s+(?:trying\s+to\s+do|(?:supposed|meant)\s+to\s+do)|what\s+do\s+i\s+do\s+here)[?.!\s]*$/i;
+
+/** The in-game orientation asides, answered from the world fold: the player's
+ *  room, the room's real affordances, and the world's objective. Null when the
+ *  line is none of them, so an ordinary question keeps its lane. */
+async function worldContextAnswer(line, { memoryDir }) {
+  const l = String(line).trim();
+  const asksWhere = WORLD_WHERE_AM_I_RE.test(l);
+  const asksOptions = WORLD_OPTIONS_RE.test(l);
+  const asksQuest = WORLD_QUEST_RE.test(l);
+  if (!asksWhere && !asksOptions && !asksQuest) return null;
+  let rows;
+  try { rows = readFactRows(await loadMemory(memoryDir)); } catch { return null; }
+  const state = foldWorldState(rows);
+  const here = state.placements.get("player")?.object ?? null;
+
+  if (asksWhere) {
+    return here
+      ? answer(`you are in the ${here}.`, "ADVENTURE — where-am-I aside: the player's own room from the current world fold", { goal: "check where you are" })
+      : answer("the world has no written player position yet.", "ADVENTURE — where-am-I aside: no player placement", { miss: true, goal: "check where you are" });
+  }
+
+  if (asksOptions) {
+    const actions = here ? roomAffordances(rows, state, here) : [];
+    return answer(
+      actions.length ? `you can: ${actions.join(", ")}.` : `nothing obvious here — say "look" to look around${here ? ` the ${here}` : ""}.`,
+      `ADVENTURE — options aside: the ${here}'s roomAffordances, the same list "look" appends`,
+      { goal: "see what you can do here" },
+    );
+  }
+
+  const objectiveId = rows.find((r) => r.predicate === "mgx:is-objective" && r.object === "true")?.subject ?? null;
+  return objectiveId
+    ? answer(
+        `your goal is to find the ${objectiveId} and pick it up.`,
+        `ADVENTURE — quest aside: the world's objective (${objectiveId}), named without spoiling where it is`,
+        { goal: `find the ${objectiveId}` },
+      )
+    : answer(
+        `this world sets no explicit goal — explore it, and say "look" to see your options.`,
+        "ADVENTURE — quest aside: no objective marker in this world",
+        { goal: "explore the world" },
+      );
+}
+
 async function inventoryAnswer({ memoryDir, graph }) {
   const memory = await loadMemory(memoryDir);
   const rows = readFactRows(memory);
@@ -1033,5 +1103,7 @@ export async function adventureTurn(line, { planHolder, memoryDir, sessionId = "
   if (whereAside) return whereAside;
   const opennessAside = await worldOpennessAnswer(line, { memoryDir });
   if (opennessAside) return opennessAside;
+  const contextAside = await worldContextAnswer(line, { memoryDir });
+  if (contextAside) return contextAside;
   return null; // a mid-game aside — the ordinary lanes answer, world untouched
 }

package/src/services/chat.mjs

@@ -2555,6 +2555,10 @@ const GOAL_CONJUNCT_RE = new RegExp(
 // three only REPORT.
 const PLAN_WHAT_NEXT_RE = /^(?:what(?:'s|\s+is)?|whats)\s+the\s+next\s+move[?.!\s]*$/i;
 const PLAN_MOVE_COUNT_RE = /^how\s+many\s+moves(?:\s+(?:are\s+(?:there|left)|remain(?:ing)?|left|to\s+go|in\s+the\s+plan|total))?[?.!\s]*$/i;
+// "what is the goal" while a goal is held — a read-back off planState, so a
+// mid-plan aside never falls to the child-pack lane and answers from corpus
+// vocabulary about the word "goal".
+const PLAN_GOAL_READBACK_RE = /^(?:what(?:'s|\s+is)\s+(?:the\s+|my\s+)?goal|remind\s+me\s+(?:of\s+|what\s+)?the\s+goal(?:\s+is)?|what\s+am\s+i\s+solving\s+for|what\s+goal(?:'s|\s+is)\s+(?:set|held))[?.!\s]*$/i;
 // "is that really the minimum number of moves?" / "could there be a shorter
 // plan than that?" — a confirmation of the planner's own optimality claim,
 // not a request to count anything (without this it fell to the unrelated
@@ -5798,8 +5802,38 @@ const FACT_PREDICATE_PHRASES = {
   "mgx:similarTo": "is similar to",
   "mgx:relatedTo": "is related to",
   "mgx:symbolOf": "is a symbol of",
+  // A loaded adventure world's placement predicates, so a describe read-back of
+  // a visible prop reads as English ("lamp is in the study") instead of the
+  // mechanical -s fold garbling them ("lamp locateds in study"). The world's
+  // SECRET/mechanics predicates (a hidden object's location, the objective
+  // marker, the lock/open/NPC internals) are kept out of the describe lane
+  // entirely by WORLD_INTERNAL_PREDICATES below, so they never render at all.
+  "mgx:currently-in": "is in",
+  "mgx:located-in": "is in",
+  "mgx:fixed-in": "is fixed in",
+  "mgx:stands-locked-in": "stands locked in",
+  "mgx:works-in": "works in",
 };
 
+/** The world-mechanics predicates the generic describe read-back must never
+ *  surface: a hidden object's location and the objective marker spoil the
+ *  puzzle, and the lock/container/open/NPC-schedule flags are datatype internals
+ *  the adventure's own readers answer in-game. Mirrors adventure.mjs's own
+ *  VIEW_EXCLUDED_PREDICATES — the same discipline the room-look digest uses. */
+const WORLD_INTERNAL_PREDICATES = new Set([
+  "mgx:hidden-in", "mgx:is-objective", "mgx:unlocks-with",
+  "mgx:is-npc", "mgx:acts-on-turn", "mgx:acts-toward",
+  "mgx:is-container", "mgx:is-open",
+]);
+
+/** The world PLACEMENT predicates carry curated phrases above so they render as
+ *  English, but they must stay OUT of the query-marker families derived from
+ *  FACT_PREDICATE_PHRASES — "what is in the study" is a members-of-class query,
+ *  not a reverse placement lookup, and "is in" is far too broad an anchor. */
+const WORLD_PLACEMENT_PREDICATES = new Set([
+  "mgx:currently-in", "mgx:located-in", "mgx:fixed-in", "mgx:stands-locked-in", "mgx:works-in",
+]);
+
 /** The MECHANICAL fallback for a predicate this table has no curated entry
  *  for — specifically generalVerbTeach's minted "mgx:<lemma>" predicates
  *  ("mgx:eat", "mgx:drive", …) — the mechanical INVERSE of singularizeSurface's
@@ -5889,6 +5923,7 @@ function relationRoleWord(predicate) {
 // (no curated second table) — the single-letter "a" is excluded, too short
 // to anchor on without risking eating a genuine multi-word subject.
 const TRAILING_PREDICATE_MARKERS = Object.entries(FACT_PREDICATE_PHRASES)
+  .filter(([predicate]) => !WORLD_PLACEMENT_PREDICATES.has(predicate))
   .map(([predicate, phrase]) => {
     const m = /^(?:is|are)\s+(.+)$/i.exec(phrase);
     return m ? { predicate, marker: m[1].trim().toLowerCase() } : null;
@@ -6654,7 +6689,7 @@ const REVERSE_PREDICATE_EXCLUDE = new Set([
   "mgx:ownedBy", "owl:disjointWith", "mgx:hasProperty", "mgx:receivesAction",
 ]);
 const REVERSE_PREDICATE_MARKERS = Object.entries(FACT_PREDICATE_PHRASES)
-  .filter(([predicate]) => !REVERSE_PREDICATE_EXCLUDE.has(predicate))
+  .filter(([predicate]) => !REVERSE_PREDICATE_EXCLUDE.has(predicate) && !WORLD_PLACEMENT_PREDICATES.has(predicate))
   .map(([predicate, phrase]) => ({
     predicate,
     re: new RegExp(`^what\\s+${escapeRegex(phrase)}\\s+(.+?)[?.!\\s]*$`, "i"),
@@ -6680,7 +6715,7 @@ const FORWARD_YESNO_EXCLUDE = new Set([
   "mgx:ownedBy",
 ]);
 const FORWARD_YESNO_MARKERS = Object.entries(FACT_PREDICATE_PHRASES)
-  .filter(([predicate]) => !FORWARD_YESNO_EXCLUDE.has(predicate))
+  .filter(([predicate]) => !FORWARD_YESNO_EXCLUDE.has(predicate) && !WORLD_PLACEMENT_PREDICATES.has(predicate))
   .map(([predicate, phrase]) => {
     let re;
     if (phrase === "can be") {
@@ -7003,8 +7038,11 @@ async function factAnswerReaders(memoryDir, query, envelope, miss, biasByBundle
     const variants = factTermVariants(normFactTerm, subject);
     // factRows (trust+sourceIds-bearing), not the plain memoryFacts shape — the
     // bias-weighted ranking below needs each hit's sourceIds to resolve which
-    // bundle it came from (memory/bias.mjs's biasForRow).
-    const subjectHits = (await factRows(memoryDir, cache)).filter((f) => variants.has(f.subject));
+    // bundle it came from (memory/bias.mjs's biasForRow). A live world's secret
+    // and mechanics predicates are dropped so "what is the letter" never reads
+    // back where it's hidden or that it's the objective (WORLD_INTERNAL_PREDICATES).
+    const subjectHits = (await factRows(memoryDir, cache))
+      .filter((f) => variants.has(f.subject) && !WORLD_INTERNAL_PREDICATES.has(f.predicate));
     let hits = predicate ? subjectHits.filter((f) => f.predicate === predicate) : subjectHits;
     if (!hits.length) {
       // The subject itself is known, but not under this specific relation —
@@ -7533,6 +7571,12 @@ async function factAnswerReaders(memoryDir, query, envelope, miss, biasByBundle
         hits = rows.filter((f) => overlaps(f.subject) || overlaps(f.object));
       }
     }
+    // A live adventure world's mechanics never leak through the describe lane:
+    // "what is the letter" must not read back where it's hidden or that it's the
+    // objective, and those datatype internals render as garbled non-English
+    // besides. The adventure's own where/openness readers answer the legitimate
+    // in-game questions from the world fold.
+    hits = hits.filter((f) => !WORLD_INTERNAL_PREDICATES.has(f.predicate));
     // A genuinely empty result here is a real miss: "what do you know about
     // the last commit" needs a TEACH-OFFER, not a bare wall — added as a LATE
     // runTurn-level addition, below, alongside the sibling "what is X" offer,
@@ -10684,7 +10728,7 @@ async function planLaneAnswer(query, { memoryDir, planHolder, sessionId = "", ga
   if (wantsLegal) {
     let moves;
     try {
-      moves = movesFromRules(state, domain);
+      moves = movesFromRules(state, domain, { scope: "taught" });
     } catch (err) {
       if (err instanceof PlanBudgetError) {
         return { text: `too many possible moves to enumerate here (${err.message}) — narrow the classes involved.`, via: "plan", deduced: "list the legal moves (budget exceeded)", note: "plan lane — budget decline" };
@@ -10774,7 +10818,7 @@ async function planLaneAnswer(query, { memoryDir, planHolder, sessionId = "", ga
   }
   let isGoal;
   try {
-    isGoal = compileGoal(goals, domain);
+    isGoal = compileGoal(goals, domain, { scope: "taught" });
   } catch (err) {
     return { text: `I can't compile that goal: ${err?.message ?? err}`, via: "plan", deduced: "plan a move sequence (uncompilable goal)", note: "plan lane — goal compile decline" };
   }
@@ -10782,7 +10826,7 @@ async function planLaneAnswer(query, { memoryDir, planHolder, sessionId = "", ga
   const maxDepth = gameConfig?.planning?.maxDepth ?? DEFAULT_GAME_CONFIG.planning.maxDepth;
   let found;
   try {
-    found = findActionPath(state, isGoal, (s) => movesFromRules(s, domain), { maxDepth, stateKey: stateKeyFor });
+    found = findActionPath(state, isGoal, (s) => movesFromRules(s, domain, { scope: "taught" }), { maxDepth, stateKey: stateKeyFor });
   } catch (err) {
     if (err instanceof PlanBudgetError) {
       return { text: `the search space is too large (${err.message}) — narrow the classes involved.`, via: "plan", deduced: "plan a move sequence (budget exceeded)", note: "plan lane — budget decline" };
@@ -10883,7 +10927,7 @@ async function executePlanStep(planHolder, { memoryDir, sessionId = "" }) {
   const factRows = readFactRows(payload);
   const domain = compileDomain(factRows, readRuleRows(payload));
   const finalState = stateFromFacts(factRows, domain);
-  const holds = compileGoal(ps.goals, domain)(finalState);
+  const holds = compileGoal(ps.goals, domain, { scope: "taught" })(finalState);
   planHolder.state = { ...planHolder.state, done: true };
   return {
     text: holds
@@ -10940,6 +10984,18 @@ async function planFollowUpAnswer(query, { memoryDir, planHolder, pendingPager =
     };
   }
 
+  if (PLAN_GOAL_READBACK_RE.test(q)) {
+    if (!ps || !(ps.goalTexts?.length || ps.goals?.length)) return null;
+    const goalText = ps.goalTexts?.length ? ps.goalTexts.join("; ") : "the goal you set";
+    const status = activePlan
+      ? ` A plan is ready — ${ps.actions.length} move${ps.actions.length === 1 ? "" : "s"}; say "next" to step through it.`
+      : ' Say "solve it" when the board is taught.';
+    return {
+      text: `the goal is that ${goalText}.${status}`,
+      deduced: "read back the held goal",
+      note: "PLAN FOLLOW-UP — goal read-back from the held planState",
+    };
+  }
   if (PLAN_WHAT_NEXT_RE.test(q)) {
     if (!activePlan) return null;
     if (ps.done || ps.cursor >= ps.actions.length) {

package/src/services/spider-fly-turn.mjs

@@ -381,6 +381,68 @@ async function runToldFactTurn(match, { planHolder, memoryDir, cache, gameConfig
   });
 }
 
+// ---- in-game orientation asides ---------------------------------------------
+//
+// "where is the spider", "where am I", "what can I do", "what is the goal" —
+// while the board is live these must answer from the board, not fall through to
+// the code-graph lanes, where "where is the spider" reads "spider" as a module
+// name and "what is the goal" answers from corpus vocabulary. There is no
+// player piece here (both agents move on their own), so "where am I" reports
+// the watcher stance and where the pieces stand.
+
+const SF_WHERE_AGENT_RE = /^where(?:'s|\s+is|\s+are)\s+(?:the\s+)?(spider|fly)(?:-\d+)?(?:\s+now)?[?.!\s]*$/i;
+const SF_WHERE_AM_I_RE = /^where\s+am\s+i(?:\s+now)?[?.!\s]*$/i;
+const SF_OPTIONS_RE = /^(?:what\s+can\s+i\s+do(?:\s+(?:here|now))?|what\s+are\s+my\s+options|what\s+(?:should|do)\s+i\s+do(?:\s+(?:here|now))?|what\s+now)[?.!\s]*$/i;
+const SF_GOAL_RE = /^(?:what(?:'s|\s+is)\s+(?:the\s+|my\s+)?(?:goal|objective|point|quest|aim)|what\s+are\s+they\s+(?:doing|trying\s+to\s+do)|what\s+am\s+i\s+(?:trying\s+to\s+do|(?:supposed|meant)\s+to\s+do))[?.!\s]*$/i;
+
+const WATCHER_STANCE = 'you have no piece here — both agents move on their own. Watch, say "tick" to advance, or address one, e.g. "@spider the fly is east".';
+
+const positionsOfKind = (kind, state) =>
+  liveIdsOfKind(kind, state).map((id) => `${id} at ${state.placements.get(id).cell}`);
+
+async function spiderFlyContextAnswer(line, { memoryDir }) {
+  const l = String(line).trim();
+  const whereAgent = l.match(SF_WHERE_AGENT_RE);
+  const asksWhereMe = SF_WHERE_AM_I_RE.test(l);
+  const asksOptions = SF_OPTIONS_RE.test(l);
+  const asksGoal = SF_GOAL_RE.test(l);
+  if (!whereAgent && !asksWhereMe && !asksOptions && !asksGoal) return null;
+  let state;
+  try { state = foldSpiderFlyState(readFactRows(await loadMemory(memoryDir))); } catch { return null; }
+
+  if (whereAgent) {
+    const kind = whereAgent[1].toLowerCase();
+    const positions = positionsOfKind(kind, state);
+    return {
+      text: positions.length ? `${positions.join("; ")}.` : `there's no live ${kind} on the board right now.`,
+      lane: "game-answer",
+      note: `SPIDER-FLY — where-aside: ${kind} positions from the current board fold`,
+      goal: `find the ${kind}`,
+      miss: !positions.length,
+    };
+  }
+
+  if (asksWhereMe) {
+    return { text: WATCHER_STANCE, lane: "game-inform", note: "SPIDER-FLY — where-am-I aside: the watcher stance (no player piece)", goal: "understand your role" };
+  }
+
+  if (asksOptions) {
+    return {
+      text: 'say "tick" to advance a turn, or address an agent — e.g. "@spider the fly is east" or "@spider the fly is at cell-7-3" to plant a belief. Say "stop watching" to end.',
+      lane: "game-inform",
+      note: "SPIDER-FLY — options aside: the live game's own commands",
+      goal: "see what you can do",
+    };
+  }
+
+  return {
+    text: "the spider hunts the fly; the fly tries to stay clear. You watch it play out — plant a belief to nudge one, or say \"tick\" to advance.",
+    lane: "game-inform",
+    note: "SPIDER-FLY — goal aside: the game's predator/prey objective",
+    goal: "understand the game",
+  };
+}
+
 // ---- the lane ------------------------------------------------------------
 
 /**
@@ -468,5 +530,8 @@ export async function spiderFlyTurn(line, { planHolder, memoryDir, env, cache =
     return runTickAndRender({ planHolder, memoryDir, cache, toldFacts: [], gameConfig });
   }
 
+  const contextAside = await spiderFlyContextAnswer(line, { memoryDir });
+  if (contextAside) return contextAside;
+
   return null; // an unaddressed aside — the ordinary lanes answer, board untouched
 }