@polycode-projects/the-mechanical-code-talker 1.10.14 → 1.11.5

package/src/codegraph.mjs

@@ -1,4 +1,4 @@
-import { lookupByProseTokens, proseLayerHits } from "./prose.mjs";
+import { lookupByProseTokens, proseLayerHits, splitIdentifierWords } from "./prose.mjs";
 import { cosine } from "./embed.mjs";
 import { CREATED_AT_PROP, UPDATED_AT_PROP, provenanceTagToSource } from "./memory/core.mjs";
 
@@ -204,6 +204,19 @@ function relLabel(g) {
   return g.prop ? `${g.predicate} [${g.prop}]` : g.predicate;
 }
 
+/** A class enum in a rendered heading: a multi-word enum reads as words
+ *  ("GlobalVariable" -> "Global Variable"); a single-word enum stays verbatim,
+ *  keeping the long-standing Module/Function/Entity headings byte-identical.
+ *  Title-cased (unlike ask.mjs's lowercase classDisplayName) because these
+ *  sites use the enum as a heading label, not mid-sentence prose — and ask.mjs
+ *  already imports this module, so reusing its formatter here would be a cycle. */
+function classHeading(cls) {
+  const c = cls || "Entity";
+  const words = splitIdentifierWords(c);
+  if (words.length < 2) return c;
+  return words.map((w) => w[0].toUpperCase() + w.slice(1)).join(" ");
+}
+
 // Show the first `n` items, then a "+K more" tail with the true count.
 function capJoin(items, n, sep = ", ") {
   if (items.length <= n) return items.join(sep);
@@ -216,7 +229,7 @@ const PROV_CAP = 8;
 /** Compact plain-text description of one individual — for an agent consumer. */
 export function renderDescribe(graph, ind, { candidates = [] } = {}) {
   const lines = [];
-  lines.push(`${ind.label} — ${ind.class || "Entity"} (id: ${ind.id})`);
+  lines.push(`${ind.label} — ${classHeading(ind.class)} (id: ${ind.id})`);
 
   const refs = (ind.derived_from || []).filter(isProvRef);
   if (refs.length) lines.push(`attestation: touched by ${refs.length} commit(s)`);
@@ -244,7 +257,7 @@ export function renderDescribe(graph, ind, { candidates = [] } = {}) {
   }
 
   if (candidates.length) {
-    lines.push(`other matches: ${candidates.map((c) => `${c.label} (${c.class})`).join(", ")}`);
+    lines.push(`other matches: ${candidates.map((c) => `${c.label} (${classHeading(c.class)})`).join(", ")}`);
   }
   if (graph.truncated.length) {
     lines.push(truncationNote(graph));
@@ -286,7 +299,7 @@ export function renderCompare(graph, indA, indB) {
   const klass = indA.class || "Entity";
   if ((indB.class || "Entity") !== klass) return null;
 
-  const lines = [`Comparing ${indA.label} and ${indB.label} (both ${klass}):`];
+  const lines = [`Comparing ${indA.label} and ${indB.label} (both ${classHeading(klass)}):`];
   const a = edgesFor(graph, indA.id);
   const b = edgesFor(graph, indB.id);
   const outByPred = pairByPredicate(a.out, b.out);
@@ -1382,7 +1395,7 @@ const CALL_CAP = 30;
 /** A class's methods + attributes (with sites/decorators) in one slice — replaces
  *  reading the class body. Uses the `contains` (seon:containsCodeEntity) relation. */
 export function renderMembers(graph, ind) {
-  const lines = [`${ind.label} — ${ind.class || "Entity"} (id: ${ind.id})`];
+  const lines = [`${ind.label} — ${classHeading(ind.class)} (id: ${ind.id})`];
   const contains = edgesOfKind(graph, "contains").filter((e) => e.subject === ind.id);
   if (!contains.length) {
     lines.push("members: none recorded (empty class, or members not in the extracted graph). Use tmct_describe for its edges.");
@@ -1411,7 +1424,7 @@ const attrVal = (ind, key) => (ind?.attributes || []).find((a) => a.key === key)
  *  (kept OUT of tmct_context's lean bundle; this is the targeted tool for them). */
 export function renderSignature(graph, ind) {
   const site = siteOf(ind);
-  const lines = [`${ind.label} — ${ind.class || "Entity"}${spanTag(site)}`];
+  const lines = [`${ind.label} — ${classHeading(ind.class)}${spanTag(site)}`];
   const params = attrVal(ind, "params");
   const returns = attrVal(ind, "returns");
   if (params || returns || (ind.class || "") === "Method" || (ind.class || "") === "Function") {
@@ -1451,7 +1464,7 @@ export function renderSubclasses(graph, ind) {
     if (!childrenOf.has(e.object)) childrenOf.set(e.object, []);
     childrenOf.get(e.object).push({ id: e.subject, label: e.subjectLabel || e.subject });
   }
-  const lines = [`${ind.label} — ${ind.class || "Entity"} (id: ${ind.id})`];
+  const lines = [`${ind.label} — ${classHeading(ind.class)} (id: ${ind.id})`];
   lines.push(bases.length ? `extends: ${capJoin(bases, SUBCLASS_CAP)}` : "extends: (no internal/recorded base classes)");
   const visited = new Set([ind.id]);
   const levels = [];
@@ -1625,10 +1638,10 @@ export function callHint(graph, ind) {
 export function renderCalls(graph, ind) {
   const calls = edgesOfKind(graph, "callsSymbol").filter((e) => e.subject === ind.id);
   if (!calls.length) {
-    return `${ind.label} — ${ind.class || "Entity"}: no in-repo calls recorded (calls only stdlib/external, or fine-grained call edges are not in the extracted graph).`;
+    return `${ind.label} — ${classHeading(ind.class)}: no in-repo calls recorded (calls only stdlib/external, or fine-grained call edges are not in the extracted graph).`;
   }
   const items = calls.map((e) => calleeRef(graph, e));
-  return `${ind.label} — ${ind.class || "Entity"} calls ${calls.length} in-repo symbol(s):\n  ${capJoin(items, CALL_CAP, "\n  ")}`;
+  return `${ind.label} — ${classHeading(ind.class)} calls ${calls.length} in-repo symbol(s):\n  ${capJoin(items, CALL_CAP, "\n  ")}`;
 }
 
 // ---- commit history with author/date/subject (Commit attributes) ----------------
@@ -1664,11 +1677,11 @@ export function renderFileHistory(graph, ind) {
 function renderSymbolHistory(graph, ind) {
   const commits = edgesOfKind(graph, "touchesSymbol").filter((e) => e.object === ind.id);
   if (!commits.length) {
-    return `${ind.label} — ${ind.class || "Entity"}: no symbol-level commit history recorded (outside the git-log window, or fine-grained history is not in the extracted graph).`;
+    return `${ind.label} — ${classHeading(ind.class)}: no symbol-level commit history recorded (outside the git-log window, or fine-grained history is not in the extracted graph).`;
   }
   const shown = commits.slice(0, HISTORY_CAP).map((e) => `  ${commitLine(graph, e.subject, e.subjectLabel)}`);
   const tail = commits.length > HISTORY_CAP ? `\n  …+${commits.length - HISTORY_CAP} more` : "";
-  return `${ind.label} — ${ind.class || "Entity"}: touched by ${commits.length} commit(s):\n${shown.join("\n")}${tail}`;
+  return `${ind.label} — ${classHeading(ind.class)}: touched by ${commits.length} commit(s):\n${shown.join("\n")}${tail}`;
 }
 
 /** Method history — commits touching a specific method symbol (`touchesSymbol`). */

package/src/domain.mjs

@@ -0,0 +1,350 @@
+// domain.mjs — the generic taught-action interpreter.
+//
+// Pure functions from taught rows to planner inputs: no I/O, and no knowledge
+// of any particular game — every class, individual, predicate, and action
+// arrives as data from the memory store's fact/Rule rows. Plugs into
+// planning.mjs's findActionPath as its applyActions.
+
+const MEMBER_EDGE_PREDICATES = new Set(["rdfs:subClassOf", "rdf:type"]);
+const SNAPSHOT_RE = /^(.+)@step(\d+)$/;
+
+/** 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(/[.!?]+$/, "");
+
+/** Predicates in Rule slots are stored bare (normFactTerm strips prefixes);
+ *  fact rows carry the prefixed form. */
+const attachPrefix = (predicate) => {
+  const p = normTerm(predicate);
+  return p.includes(":") ? p : `mgx:${p}`;
+};
+
+const rowSort = (a, b) =>
+  a.subject.localeCompare(b.subject) ||
+  a.predicate.localeCompare(b.predicate) ||
+  a.object.localeCompare(b.object);
+
+const normRow = (row) => ({
+  subject: normTerm(row.subject),
+  predicate: normTerm(row.predicate),
+  object: normTerm(row.object),
+});
+
+export class PlanBudgetError extends Error {
+  constructor(groundings, budget) {
+    super(`action grounding count ${groundings} exceeds the budget of ${budget}`);
+    this.name = "PlanBudgetError";
+    this.groundings = groundings;
+    this.budget = budget;
+  }
+}
+
+/** Compile fact + Rule rows into a planning domain:
+ *  { actions, classMembers, dynamicPredicates, ordering }. */
+export function compileDomain(factRows, ruleRows) {
+  const byName = new Map();
+  for (const rule of ruleRows || []) {
+    if (!String(rule.kind || "").startsWith("action-")) continue;
+    const name = normTerm(rule.name);
+    if (!byName.has(name)) byName.set(name, { name, signatures: [], preconds: [], effects: [], constraints: [] });
+    const family = byName.get(name);
+    const slots = rule.slots || {};
+    if (rule.kind === "action-signature") {
+      family.signatures.push({
+        subjectClass: normTerm(slots.subjectClass),
+        targetClass: normTerm(slots.targetClass),
+      });
+    } else if (rule.kind === "action-precond") {
+      family.preconds.push({
+        shape: normTerm(slots.shape),
+        predicate: attachPrefix(slots.predicate),
+        role: normTerm(slots.role),
+        scope: normTerm(slots.scope),
+      });
+    } else if (rule.kind === "action-effect") {
+      family.effects.push({
+        predicate: attachPrefix(slots.predicate),
+        subjectRole: normTerm(slots.subjectRole),
+        objectRole: normTerm(slots.objectRole),
+      });
+    } else if (rule.kind === "action-constraint") {
+      family.constraints.push({
+        left: normTerm(slots.left),
+        right: normTerm(slots.right),
+        guard: normTerm(slots.guard),
+      });
+    }
+  }
+  const actions = [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+  for (const action of actions) {
+    action.signatures.sort((a, b) =>
+      a.subjectClass.localeCompare(b.subjectClass) || a.targetClass.localeCompare(b.targetClass));
+    action.preconds.sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
+    action.effects.sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
+    action.constraints.sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
+  }
+
+  // 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);
+  }
+
+  // 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
+  // grounding time. With 0 or 2+ members that substitution would be a silent
+  // guess, so an ill-bound family fails loudly here instead.
+  const requireSoleMember = (word, where) => {
+    const count = (classMembers[word] || []).length;
+    if (count !== 1) {
+      throw new Error(`${where} names "${word}", which must be a class with exactly one member (it has ${count})`);
+    }
+  };
+  for (const action of actions) {
+    for (const effect of action.effects) {
+      for (const role of [effect.subjectRole, effect.objectRole]) {
+        if (role !== "subject" && role !== "target") requireSoleMember(role, `an effect role of "${action.name}"`);
+      }
+    }
+    for (const constraint of action.constraints) {
+      for (const word of [constraint.left, constraint.right, constraint.guard]) {
+        requireSoleMember(word, `a constraint term of "${action.name}"`);
+      }
+    }
+  }
+
+  const dynamicPredicates = new Set();
+  for (const action of actions) for (const effect of action.effects) dynamicPredicates.add(effect.predicate);
+
+  const ordering = (factRows || [])
+    .map(normRow)
+    .filter((r) => !dynamicPredicates.has(r.predicate) && !MEMBER_EDGE_PREDICATES.has(r.predicate))
+    .sort(rowSort);
+
+  return { actions, classMembers, dynamicPredicates, ordering };
+}
+
+const domainIndividuals = (domain) => {
+  const out = new Set();
+  for (const action of domain.actions) {
+    for (const sig of action.signatures) {
+      for (const m of domain.classMembers[sig.subjectClass] || []) out.add(m);
+      for (const m of domain.classMembers[sig.targetClass] || []) out.add(m);
+    }
+  }
+  return out;
+};
+
+/** The current state as canonical sorted rows over the domain's dynamic
+ *  predicates. Prefers the newest @stepN snapshot when one exists, so a
+ *  re-plan after per-step execution never reads the stale step-0 board. */
+export function stateFromFacts(factRows, domain) {
+  const individuals = domainIndividuals(domain);
+  const subjectClasses = new Set();
+  for (const action of domain.actions) for (const sig of action.signatures) subjectClasses.add(sig.subjectClass);
+  const subjects = new Set();
+  for (const cls of subjectClasses) for (const m of domain.classMembers[cls] || []) subjects.add(m);
+
+  const rows = (factRows || []).map(normRow).filter((r) => domain.dynamicPredicates.has(r.predicate));
+  let maxStep = -1;
+  for (const row of rows) {
+    const m = SNAPSHOT_RE.exec(row.subject);
+    if (m && individuals.has(m[1])) maxStep = Math.max(maxStep, Number(m[2]));
+  }
+  const state = [];
+  for (const row of rows) {
+    const m = SNAPSHOT_RE.exec(row.subject);
+    if (maxStep >= 0) {
+      if (!m || Number(m[2]) !== maxStep) continue;
+      const base = m[1];
+      if (subjects.has(base)) state.push({ subject: base, predicate: row.predicate, object: normTerm(row.object.replace(SNAPSHOT_RE, "$1")) });
+    } else if (!m && subjects.has(row.subject)) {
+      state.push(row);
+    }
+  }
+  state.sort(rowSort);
+  return state;
+}
+
+/** 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
+ *  literal NUL byte in this repo. */
+const SEP = String.fromCharCode(0);
+export function stateKeyFor(state) {
+  return state.map((r) => [r.subject, r.predicate, r.object].join(SEP)).join("\n");
+}
+
+const precondApplies = (precond, target, domain) =>
+  precond.scope === "any" || (domain.classMembers[precond.scope] || []).includes(target);
+
+function precondHolds(precond, subject, target, state, domain) {
+  const roleTerm = precond.role === "target" ? target : subject;
+  if (precond.shape === "no-incoming") {
+    return !state.some((r) => r.predicate === precond.predicate && r.object === roleTerm);
+  }
+  if (precond.shape === "comparator") {
+    const left = roleTerm;
+    const right = precond.role === "target" ? subject : target;
+    return domain.ordering.some((r) =>
+      r.subject === left && r.predicate === precond.predicate && r.object === right);
+  }
+  return false;
+}
+
+/** Ground an effect/constraint role word: "subject"/"target" bind the
+ *  grounding pair; any other word is class-bound and binds the class's sole
+ *  member — its companion semantics (compileDomain guarantees exactly one). */
+const roleBinding = (role, subject, target, domain) => {
+  if (role === "subject") return subject;
+  if (role === "target") return target;
+  return (domain.classMembers[role] || [])[0];
+};
+
+const positionIn = (rows, term, predicate) =>
+  rows.find((r) => r.subject === term && r.predicate === predicate)?.object;
+
+function applyEffects(effects, subject, target, state, domain) {
+  let rows = state;
+  let changed = false;
+  for (const effect of effects) {
+    const effSubject = roleBinding(effect.subjectRole, subject, target, domain);
+    const effObject = roleBinding(effect.objectRole, subject, target, domain);
+    const already = rows.some((r) =>
+      r.subject === effSubject && r.predicate === effect.predicate && r.object === effObject);
+    if (already) continue;
+    rows = rows.filter((r) => !(r.subject === effSubject && r.predicate === effect.predicate));
+    rows = [...rows, { subject: effSubject, predicate: effect.predicate, object: effObject }];
+    changed = true;
+  }
+  if (!changed) return null;
+  return [...rows].sort(rowSort);
+}
+
+/** True when `state` still permits every companion (class-bound effect
+ *  subject) to move WITH the grounded subject. Co-location is a derived
+ *  precondition, not a taught one: the taught effect says the companion ends
+ *  up at the target, and applying that from a state where the companion
+ *  stands elsewhere would teleport it instead of carrying it. Trivially true
+ *  when the subject is its own companion. */
+function companionsCoLocated(action, subject, target, state, domain) {
+  for (const effect of action.effects) {
+    if (effect.subjectRole === "subject" || effect.subjectRole === "target") continue;
+    const companion = roleBinding(effect.subjectRole, subject, target, domain);
+    if (companion === subject) continue;
+    const subjectAt = positionIn(state, subject, effect.predicate);
+    if (!subjectAt || positionIn(state, companion, effect.predicate) !== subjectAt) return false;
+  }
+  return true;
+}
+
+/** True when a successor state breaks one of the action's constraints: the
+ *  left and right members sharing a position under one of the action's
+ *  effect predicates while the guard member stands elsewhere. */
+function constraintViolated(action, nextState, domain) {
+  if (!action.constraints.length) return false;
+  const predicates = [...new Set(action.effects.map((e) => e.predicate))];
+  for (const constraint of action.constraints) {
+    const left = (domain.classMembers[constraint.left] || [])[0];
+    const right = (domain.classMembers[constraint.right] || [])[0];
+    const guard = (domain.classMembers[constraint.guard] || [])[0];
+    for (const predicate of predicates) {
+      const leftAt = positionIn(nextState, left, predicate);
+      if (!leftAt || positionIn(nextState, right, predicate) !== leftAt) continue;
+      if (positionIn(nextState, guard, predicate) !== leftAt) return true;
+    }
+  }
+  return false;
+}
+
+/** Every legal grounded action from `state`, with its successor.
+ *  Deterministic: actions, signatures, and members are walked sorted. */
+export function movesFromRules(state, domain, { budget = 5000 } = {}) {
+  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;
+    }
+  }
+  if (groundings > budget) throw new PlanBudgetError(groundings, budget);
+
+  const out = [];
+  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] || []) {
+          if (subject === target) continue;
+          let ok = true;
+          for (const precond of action.preconds) {
+            if (!precondApplies(precond, target, domain)) continue;
+            if (!precondHolds(precond, subject, target, state, domain)) { ok = false; break; }
+          }
+          if (!ok) continue;
+          if (!companionsCoLocated(action, subject, target, state, domain)) continue;
+          const nextState = applyEffects(action.effects, subject, target, state, domain);
+          if (!nextState) continue;
+          if (constraintViolated(action, nextState, domain)) continue;
+          out.push({
+            action: {
+              name: action.name,
+              subject,
+              target,
+              label: [verb, subject, particle, target].filter(Boolean).join(" "),
+            },
+            nextState,
+          });
+        }
+      }
+    }
+  }
+  return out;
+}
+
+/** Compile goal specs ({universal, term, predicate, object}) into a pure
+ *  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) {
+  const specs = (goalSpecs || []).map((g) => ({
+    universal: Boolean(g.universal),
+    term: normTerm(g.term),
+    predicate: attachPrefix(g.predicate),
+    object: normTerm(g.object),
+  }));
+  const checks = [];
+  for (const spec of specs) {
+    const members = spec.universal ? domain.classMembers[spec.term] || [] : [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`);
+    }
+    for (const member of members) checks.push({ member, predicate: spec.predicate, object: spec.object });
+  }
+  return function isGoal(state) {
+    for (const check of checks) {
+      let current = check.member;
+      let reached = false;
+      const seen = new Set();
+      for (let hop = 0; hop <= state.length; hop += 1) {
+        if (seen.has(current)) break;
+        seen.add(current);
+        const row = state.find((r) => r.subject === current && r.predicate === check.predicate);
+        if (!row) break;
+        if (row.object === check.object) { reached = true; break; }
+        current = row.object;
+      }
+      if (!reached) return false;
+    }
+    return true;
+  };
+}

package/src/import-file.mjs

@@ -0,0 +1,86 @@
+// import-file.mjs — `tmct import --file <definition.txt>`: teach a plain-text
+// definition file, one sentence at a time, through the SAME recognizers the
+// live chat uses (runTurn) — no separate parser, no guessing.
+//
+// The report is loud on purpose: a definition file that half-teaches produces
+// a planner that finds wrong plans or no plans with no visible cause, so every
+// sentence's outcome is printed and any decline makes the caller exit non-zero.
+//
+// `#` lines are comments (skipped, counted, never "declined") — a definition
+// file carries its own example prompts this way.
+
+import { readFile } from "node:fs/promises";
+import { basename, resolve } from "node:path";
+
+import { runTurn, uuidv7 } from "./chat.mjs";
+import { loadMemory, readFactRows, appendFact, openMemoryBackend } from "./memory/core.mjs";
+import { loadConfig } from "./config.mjs";
+import { splitSentences } from "./sentences.mjs";
+
+/**
+ * Teach every sentence of `filePath` into `repoRoot`'s memory store.
+ *
+ * @returns {Promise<{
+ *   sentences: number, taught: string[], declined: {sentence: string, reason: string}[],
+ *   comments: number, report: string
+ * }>}
+ */
+export async function importDefinitionFile(repoRoot, filePath, { env = process.env } = {}) {
+  const root = resolve(repoRoot);
+  const abs = resolve(root, filePath);
+  const sourceTag = `import:${basename(abs)}`;
+  const text = await readFile(abs, "utf8");
+
+  const lines = text.split("\n");
+  const commentLines = lines.filter((l) => l.trim().startsWith("#"));
+  const body = lines.filter((l) => !l.trim().startsWith("#")).join("\n");
+  const sentences = splitSentences(body).map((s) => s.trim()).filter(Boolean);
+
+  const { loadTomlConfig } = await import("./toml-config.mjs");
+  const raw = await loadTomlConfig(root).catch(() => null);
+  const backend = String(raw?.memory?.backend || "default").trim().toLowerCase();
+  const { dir: memoryDir, close } = await openMemoryBackend(root, backend);
+  const config = loadConfig(env, root);
+
+  const taught = [];
+  const declined = [];
+  const reportLines = [`${basename(abs)} — ${sentences.length} sentence(s), ${commentLines.length} comment line(s) skipped`, ""];
+
+  try {
+    for (const sentence of sentences) {
+      const before = readFactRows(await loadMemory(memoryDir));
+      const beforeById = new Map(before.map((r) => [r.id, r.provenance]));
+      const { record } = await runTurn(sentence, { config, memoryDir, sessionId: uuidv7() });
+      const ok = record?.via === "assert" && !record?.miss;
+      if (!ok) {
+        const reason = String(record?.answer || "").split("\n")[0] || "not a recognized declarative shape";
+        declined.push({ sentence, reason });
+        reportLines.push(`  DECLINED — ${sentence} — ${reason}`);
+        continue;
+      }
+      taught.push(sentence);
+      reportLines.push(`  taught — ${sentence}`);
+      // Layer the additive audit tag onto the fact rows this sentence touched
+      // (appendFact unions provenance by id — re-import is idempotent). Rule
+      // teaches touch no fact rows; the Rule's own provenance already names
+      // the teach source.
+      const after = readFactRows(await loadMemory(memoryDir));
+      const touched = after.filter((r) => beforeById.get(r.id) !== r.provenance);
+      for (const row of touched) {
+        await appendFact(memoryDir, {
+          subject: row.subject, predicate: row.predicate, object: row.object,
+          provenance: sourceTag, quantifier: row.quantifier || "",
+        });
+      }
+    }
+  } finally {
+    await close();
+  }
+
+  reportLines.push("");
+  reportLines.push(
+    `${taught.length} taught, ${declined.length} declined, ${commentLines.length} comment line(s) skipped`
+    + (declined.length ? " — a half-taught game plans wrongly or not at all; fix the declined sentence(s) and re-import" : ""),
+  );
+  return { sentences: sentences.length, taught, declined, comments: commentLines.length, report: reportLines.join("\n") };
+}

package/src/init.mjs

@@ -13,7 +13,7 @@
 // write the same `.tmct/memory/corpus-seed.json`, so whichever runs first wins. Re-declared
 // here rather than imported, to keep init off chat.mjs's heavy module graph.
 
-import { mkdir, readFile, writeFile, stat } from "node:fs/promises";
+import { copyFile, mkdir, readFile, readdir, writeFile, stat } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { stringify as stringifyToml } from "smol-toml";
@@ -197,6 +197,51 @@ export async function initRepo(dir, { force = false, seed, env = process.env, pe
     }
   }
 
+  // ---- 1b. Importable starters (.tmct/imports) — game definition files a
+  // fresh repo can discover by listing a directory, plus a README naming the
+  // corpus bundle ids `tmct import` accepts. Game files are copied (import
+  // --file consumes them directly); corpus bundles are listed by id, not
+  // copied — the wordnet-scale ones are far too large to scaffold into every
+  // repo, and `tmct import --corpus <id>` resolves ids without a local copy.
+  {
+    const importsDir = join(paths.tmct, "imports");
+    const gamesDir = join(importsDir, "games");
+    const shippedGames = join(dirname(fileURLToPath(import.meta.url)), "..", "data", "games");
+    if (!(await exists(gamesDir))) {
+      await mkdir(gamesDir, { recursive: true });
+      created.push(gamesDir);
+    }
+    try {
+      for (const f of await readdir(shippedGames)) {
+        if (!f.endsWith(".txt")) continue;
+        const dest = join(gamesDir, f);
+        if (!(await exists(dest))) {
+          await copyFile(join(shippedGames, f), dest);
+          created.push(dest);
+        }
+      }
+    } catch { /* no shipped games directory — scaffold stays empty */ }
+    const readmePath = join(importsDir, "README.txt");
+    if (!(await exists(readmePath))) {
+      await writeFile(readmePath, [
+        "Importable starters for this repo.",
+        "",
+        "Game definitions (plain controlled-English sentences; # lines are comments):",
+        "  tmct import --file .tmct/imports/games/hanoi-3.txt",
+        "",
+        "Corpus bundles (activate by id — no local copy needed):",
+        "  tmct import --corpus human | human-medium | human-large",
+        "  tmct import --corpus seon | conceptnet | aws | python | java | general",
+        "  tmct import --corpus wordnet-xl | wordnet-full | namenet   (large: tens of thousands of facts)",
+        "",
+        "Ontology / lexicon resources are file paths declared as extension entries:",
+        "  tmct import --ontology <path> | --lexicon <path>",
+        "",
+      ].join("\n"));
+      created.push(readmePath);
+    }
+  }
+
   // ---- 2. The externalised config (preserve an existing file unless force) ----
   let config = defaultConfig();
   // Persona overrides apply only to a fresh write.

package/src/interpret/normalize.mjs

@@ -8,6 +8,7 @@
 import {
   CONTRACTIONS, MISSPELLINGS, WRONG_WORDS, G_DROP, FILLER_WORDS,
   NEGATION_FRAMES, COMMIT_CONTENT_FRAMES, VERB_TO_KIND, ENTITY_TO_TYPE,
+  TRAILING_SCOPE_FILLER,
 } from "../ask-vocab.mjs";
 
 export function escapeRegex(s) {
@@ -146,6 +147,21 @@ const EXPLAIN_WRAPPER_RE = /^explain\s+(?:to\s+me\s+|please\s+)*(.+?)\??$/i;
 /** "tell me <Q>" (bare, no "about") -> "<Q>"; "tell me about X" is a
  *  different, untouched territory (chat.mjs's vagueTouchTermOf). */
 const TELL_ME_WRAPPER_RE = /^tell\s+me\s+(.+?)\??$/i;
+/** "do you know <Q>" -> "<Q>", gated on an interrogative remainder — so
+ *  "do you know anything about movies" (small-talk, no embedded question)
+ *  passes through untouched. */
+const KNOW_WRAPPER_RE = /^do\s+you\s+know\s+(.+?)\??$/i;
+/** "i'd like to know <Q>" / "i want to know <Q>" -> "<Q>", same
+ *  interrogative-remainder gate as KNOW_WRAPPER_RE. */
+const WANT_KNOW_WRAPPER_RE = /^i(?:'d|\s+would)?\s+(?:like|want|need)\s+to\s+know\s+(.+?)\??$/i;
+/** EMBEDDED-QUESTION DE-INVERSION: the wrappers above unwrap "could you
+ *  tell me what a dog is" down to the embedded clause "what a dog is",
+ *  which keeps declarative word order — nothing downstream parses it. Fold
+ *  it back to the direct question the meta lane already owns. Deliberately
+ *  closed to a short (≤3-word) subject so an ordinary relative clause
+ *  ("what the parser does with X …") is never re-inverted. */
+const EMBEDDED_WHATIS_RE = /^what\s+((?:an?\s+|the\s+)?[\w'-]+(?:\s+[\w'-]+){0,2})\s+(is|are)\??$/i;
+const EMBEDDED_MEANS_RE = /^what\s+((?:an?\s+|the\s+)?[\w'-]+(?:\s+[\w'-]+){0,2})\s+means\??$/i;
 /** show/give-me presentation bridge: a kind-listing remainder is left
  *  untouched, a relation/interrogative remainder unwraps to itself, anything
  *  else bridges to "describe <thing>". */
@@ -194,6 +210,14 @@ export function applyPreambleFrames(text) {
     if (m && INTERROGATIVE_LEAD_RE.test(m[1].trim())) q = m[1].trim();
     m = q.match(TELL_ME_WRAPPER_RE);
     if (m && INTERROGATIVE_LEAD_RE.test(m[1].trim())) q = m[1].trim();
+    m = q.match(KNOW_WRAPPER_RE);
+    if (m && INTERROGATIVE_LEAD_RE.test(m[1].trim())) q = m[1].trim();
+    m = q.match(WANT_KNOW_WRAPPER_RE);
+    if (m && INTERROGATIVE_LEAD_RE.test(m[1].trim())) q = m[1].trim();
+    m = q.match(EMBEDDED_WHATIS_RE);
+    if (m) q = `what ${m[2].toLowerCase()} ${m[1].trim()}`;
+    m = q.match(EMBEDDED_MEANS_RE);
+    if (m) q = `what does ${m[1].trim()} mean`;
     m = q.match(SHOW_GIVE_ME_RE);
     if (m) {
       const rest = m[1].trim();
@@ -387,6 +411,28 @@ export const PHRASING_FRAMES = Object.freeze([
   //   a bare "is").
   { re: /^were\s+is\s+(?:the\s+)?(.+?)\s+(defined|declared|located|implemented)\??$/i, to: (m) => `where is ${m[1]} ${m[2]}` },
 
+  // DESCRIBE PARAPHRASES ("what is the purpose of X", "what does X do in
+  // this codebase") → the meta/whatis shape ("what is a <term>"), which
+  // already answers a unique code entity via metaFallbackEntityAnswer. The
+  // term slot refuses an a/an article or a pronoun lead so the vocabulary
+  // phrasings ("what is the purpose of a horse", "what does it do here")
+  // pass through untouched to their own memory-facts and context readers,
+  // which read the raw text and must keep their turn. A leading "the" is
+  // entity-term noise (mirrors resolveObject's own article strip). The
+  // sibling "what is X for" paraphrase is deliberately NOT a frame: chat's
+  // module-overview lane owns that phrasing and gates on an ask() miss, so
+  // it lives as ask()'s own miss-gated fallback (WHATIS_FOR_FALLBACK_RE)
+  // instead, adopted only when the meta reading actually answers.
+  { re: /^what\s+is\s+the\s+purpose\s+of\s+(?:the\s+)?(?!(?:an?|it|this|that|these|those)\s)(.+?)\??$/i, to: (m) => `what is a ${m[1]}` },
+  // Scoped form only: bare "what does X do" stays unrewritten — the chat
+  // surface's module-grain overview lane owns it and only gets its turn when
+  // ask() misses, so claiming it here would swap that richer answer for the
+  // one-line meta fallback.
+  {
+    re: new RegExp(`^what\\s+does\\s+(?:the\\s+)?(?!(?:an?|it|this|that|these|those)\\s)(.+?)\\s+do\\s+(?:${TRAILING_SCOPE_FILLER.map(escapeRegex).join("|")})\\??$`, "i"),
+    to: (m) => `what is a ${m[1]}`,
+  },
+
   // PREDICATIVE QUALIFIER ("which modules are untested") → the ATTRIBUTIVE form
   // ("untested modules") the grammar already answers. The QUALIFIER must sit
   // immediately after are/is, so "…are NOT tested" keeps its own set-complement handler.