@polycode-projects/the-mechanical-code-talker 1.10.13 → 1.11.0

package/README.md

@@ -114,6 +114,23 @@ tmct> /exit
 **[Try it live in your browser →](https://polycode-projects.gitlab.io/the-mechanical-code-talker/)**
 is a real, interactive chat demo running client-side. Your browser runs the
 actual query engine against a small example codebase, no server, no install.
+The page leads with the **memory ledger**: every fact as a readable sentence,
+drill by clicking the terms inside them, and an in-page chat whose answers
+focus the ledger.
+
+Two more surfaces, both generated by tmct itself:
+
+```bash
+npx tmct viz --ledger                 # ledger.html — your own memory as the same
+                                      # readable, self-contained explorer
+npx tmct init
+npx tmct import --file .tmct/imports/games/hanoi-3.txt
+npx tmct chat --prompt 'disk-1 rests on disk-2. disk-2 rests on disk-3.
+  disk-3 rests on peg-a. the goal is that every disk rests on peg-c. solve it.' \
+  --render blocks --output plan.html  # an animated replay of the solved plan
+```
+
+More on the game file and the planner under "Teach it a game" below.
 
 ## How it interprets you
 
@@ -127,65 +144,38 @@ Those triples are statements it can store, retrieve, and answer from later.
 Text that doesn't fit the grammar still gets the tolerant strategies. Nothing
 is rejected for being loose, fuzzy, or misspelled.
 
-**Everyday question shapes.** Bare "what is Commit" (no article) now resolves
-like "what is a commit" for tmct's own vocabulary. "What's model.mjs for" and
-"what's model.mjs about" answer like "what does model.mjs do". "Is Base a
-superclass of Widget" is read as the reverse of "is Widget a subclass of
-Base", the same relationship either way round. "Recent commits" and "the last
-commit" resolve to real dated history, not a literal string miss. Polite or
-indirect framing reaches the same capability as a direct request: "I'd like
-you to remember X" teaches like bare "remember X"; "please tell me about X"
-and "search for X" describe and find exactly as their direct forms do.
-
-**Negation and passive.** "Which modules do *not* import X?" computes a bounded
-**set complement** over the graph. An empty result stays a miss rather than a
-fabricated list (a non-enumerable type, like arbitrary *changes*, is refused
-outright). Reversible-passive questions traverse the right direction:
-"what is imported by Y" and "what does Y import" are understood as opposite
-edges, not the same one.
-
-**Finding by description.** "find me the payment class" searches by type and a
-fuzzy match against the entity's own properties, instead of making you name it
-exactly. It checks the type itself and its subclasses first. Only if nothing
-matches there does it widen to a related type, and when it does, it says so
-plainly rather than presenting the looser match as exact.
-
-**Comparing two things.** "compare TaskController and UserController" or "how
-is TaskController different from UserController" lines up both entities'
-shared and differing edges side by side: *"Comparing TaskController and
-UserController (both Class): inherits [seon:hasSuperType]: TaskController (1)
--> Controller; UserController (1) -> Controller"*. Every row is a real edge
-or attribute from the graph, never a hand-written diff.
-
-**Up-refining to a containing module.** A class rarely has its own
-symbol-precise commit or import record. "who touched TaskController" answers
-from its containing module's real history instead of a confident-looking but
-wrong "nothing touched it".
-
-**Following a list.** tmct remembers the last list it gave you. After
-"which modules import src/core/model.mjs", "which of those are tested" or
-"how many of those" resolves "those"/"them" against that list, not a fresh,
-unresolved pronoun.
-
-**Synonyms and everyday phrasing.** tmct matches many of the words people
-actually use for the same idea, from a curated synonym list plus a filtered
-ConceptNet slice. A slightly different word for the same concept still
-resolves. It also follows a few common sentence shapes: clauses starting with
-*because/although/while*, and conditionals ("if X were removed, what
-breaks"). It flags a question whose premise doesn't hold, too: "why does X
-still import Y" when it no longer does.
-
-**Response finishing.** Before an answer is printed it is segmented into typed
-spans: prose versus *protected* entities, paths, numbers, code, provenance, and
-receipts. A small data-driven grammar pass then runs on the prose spans only,
-under a guard that proves the protected spans came through byte-for-byte. Today
-that pass fixes the a/an article defect. Broader voice and agreement rules are
-implemented but parked until they earn their place on the benchmark.
+On top of that base, tmct reads the shapes people actually use, and each one
+resolves to a real graph traversal or declines honestly:
+
+- everyday question forms: "what is Commit", "what's model.mjs for",
+  "recent commits" as real dated history;
+- polite or indirect framing: "I'd like you to remember X" teaches like bare
+  "remember X";
+- negation as a bounded **set complement**: "which modules do *not* import
+  X?", with an empty result staying a miss, never a fabricated list;
+- reversible passives: "what is imported by Y" and "what does Y import" are
+  opposite edges, not the same one;
+- finding by description: "find me the payment class" checks the type and
+  its subclasses first, and says so plainly when it widens;
+- comparison: "compare TaskController and UserController" lines up both
+  entities' real edges side by side, never a hand-written diff;
+- list follow-ups: after "which modules import src/core/model.mjs",
+  "which of those are tested" resolves against that list;
+- curated synonyms plus a filtered ConceptNet slice, clause openers
+  (*because/although/while*), conditionals, and false-premise flags ("why
+  does X still import Y" when it no longer does).
+
+The full catalog with measured coverage lives in `CAPABILITIES_1.7.3.md` and
+the `BENCHMARK_*.md` reports.
+
+**Response finishing.** Before an answer prints, it is segmented into typed
+spans: prose versus *protected* entities, paths, numbers, code, provenance,
+and receipts. A small data-driven grammar pass runs on the prose spans only,
+under a guard that proves the protected spans came through byte-for-byte.
 
 A frozen regression suite plays out full multi-turn dialogues built from these
-phrasings, at every complexity level this project defines. That ranges from a
-single question up to a messy, typo-ridden real user. Tier-by-tier detail is
-in `HANDOVER.md` and `ROADMAP.md`.
+phrasings, from a single question up to a messy, typo-ridden real user.
+Tier-by-tier detail is in `HANDOVER.md` and `ROADMAP.md`.
 
 ## How it guides you
 
@@ -250,13 +240,7 @@ const memory = await loadMemory(dir);
 const graphService = createCompletionsGraphAdapter(graph, memory);
 
 const { text } = await generateCompletion(dir, "Store", { query: "Store", graph, memory, graphService });
-console.log(text);
-```
-
-```
-Attribute: prose_tokens = memory record store [mgx:hasProseTokens]. Attribute:
-doc = In-memory record store. [seon:hasDoc]. Other matches: src/core/store.mjs
-(Module), loadStore (Function), saveStore (Function), testLoadStore (Function).
+console.log(text);   // prints the same text as the chat answer above
 ```
 
 Full pipeline design in `archive/PLAN_COMPLETIONS.md`.
@@ -328,6 +312,45 @@ proof chain, composed answer) for a caller that wants to consume this
 programmatically rather than read the report. `tmct plan --help` has the full
 flag reference.
 
+## Teach it a game, then ask it to plan
+
+The planner above works over a fixed toolset. This one works over rules you
+teach. A game definition is a plain-text file of controlled English — the
+classes, the pieces, the ordering, and the legal moves as taught action
+rules — with `#` comment lines carrying example prompts. `tmct init`
+scaffolds one at `.tmct/imports/games/hanoi-3.txt`, and
+`tmct import --file` teaches it sentence by sentence, reporting every line
+and refusing (exit 1) if any sentence declines.
+
+Then one message states the board and the goal, and "solve it" searches the
+taught rules for the shortest move sequence:
+
+```
+tmct> disk-1 rests on disk-2. disk-2 rests on disk-3. disk-3 rests on peg-a.
+      the goal is that every disk rests on peg-c. solve it.
+plan found — 7 moves (shortest):
+  1. move disk-1 onto peg-c
+  2. move disk-2 onto peg-b
+  3. move disk-1 onto disk-2
+  4. move disk-3 onto peg-c
+  5. move disk-1 onto peg-a
+  6. move disk-2 onto disk-3
+  7. move disk-1 onto disk-2
+
+because — you taught me the "move onto" rule and 3 ordering facts. Say "next" to make move 1, or ask "what moves are legal now".
+
+Goal (inferred): Plan a move sequence from the current state to the goal (7 moves).
+```
+
+"next" executes one move at a time, writing each board state into memory as
+facts; the final step re-reads those facts and confirms the goal from them,
+never assuming success. The search is genuine and domain-general: the test
+suite teaches Towers of Hanoi purely as sentences for 1 to 8 disks and
+asserts the plan is exactly 2^n − 1 moves every time, and a second game
+(`crates.txt`, stacking crates with different rules and a two-goal
+conjunction) solves with zero interpreter changes. `--render blocks` writes
+the plan as a self-contained animated page (see "Two more surfaces" above).
+
 ## How it remembers
 
 tmct's memory has two layers, both fed by every parsed request and response and
@@ -359,38 +382,21 @@ reasoning). Design detail and the full fact-count tables are in `archive/PLAN_SE
 The default memory backend writes an OWL-labelled JSON file under `.tmct/`.
 Two more exist: `memory` keeps taught facts in the process only, nothing
 written to disk; `sqlite` persists them to a local SQLite file instead
-(`.tmct/memory/graph.sqlite`).
-
-Pick one at init time and it sticks. `tmct init --memory-backend sqlite`
-writes the choice into `tmct.toml`, and every later `tmct chat` in that repo
-uses it with no flag needed:
-
-```bash
-tmct init --memory-backend sqlite     # writes [memory] backend = "sqlite" to tmct.toml
-tmct chat                             # picks it up automatically
-tmct chat --memory-backend memory     # override for just this session
-```
-
-Precedence is `--memory-backend` flag > `TMCT_MEMORY_BACKEND` env > tmct.toml's
-`[memory] backend` > the default. A library caller sets the same thing
-directly: `runChat({ memoryBackend: "sqlite" })`.
+(`.tmct/memory/graph.sqlite`). `tmct init --memory-backend sqlite` writes the
+choice into `tmct.toml` and every later `tmct chat` in that repo picks it up.
+Precedence is `--memory-backend` flag > `TMCT_MEMORY_BACKEND` env >
+tmct.toml's `[memory] backend` > the default. A library caller sets the same
+thing directly: `runChat({ memoryBackend: "sqlite" })`.
 
 Teaching isn't limited to the ACE grammar's fixed shapes. Tell tmct an
 arbitrary fact, like "margo really eats ribs", and it mints a fact you can
-later ask about directly: "what does margo eat", or "does margo eat ribs".
-
-New vocabulary compounds as you teach it. "redis is a cache" mints "redis" as
-a class-level concept even though it was never in the built-in lexicon, and a
-later "every cache is a store" does the same for "store," the other way
-round, as long as one side of the sentence is already grounded. tmct never
-mints a fact between two totally ungrounded terms. It declines instead, and
-nudges you to ground one side first. Quantified teaching works too: "some
-functions are risky" stores the quantifier, and a later "how many functions
-are risky" answers "A few."
-
-Once you've taught a few facts, "how many facts are there" counts them back.
-That's the same count phrasing a code graph answers "how many classes are
-there" with, just now reading tmct's own memory.
+ask about directly: "what does margo eat". New vocabulary compounds as you
+teach: "redis is a cache" mints "redis" even though it was never in the
+built-in lexicon, as long as one side of the sentence is already grounded —
+tmct never mints a fact between two totally ungrounded terms; it declines and
+nudges you to ground one side first. Quantified teaching stores the
+quantifier ("some functions are risky" … "how many functions are risky" →
+"A few."), and "how many facts are there" counts the store back.
 
 ### Provenance and trust
 
@@ -410,10 +416,8 @@ provenance** rather than silently picking a winner.
 
 `tmct syllogise [--depth n] [--budget n]` is an offline, bounded, deterministic
 batch that forward-chains the memory's `rdfs:subClassOf` closure into new
-**entailed** facts, pre-deriving what the trusted sources already imply. It runs
-once automatically after seeding and on demand; the entailed facts are
-**low-trust and retractable** (never outranking a stated fact) and this never runs
-on the chat's hot path.
+**entailed** facts. They are low-trust and retractable, never outranking a
+stated fact, and this never runs on the chat's hot path.
 
 ## Install & use
 
@@ -461,6 +465,11 @@ Usage:
                                see src/graph-merge.mjs); wins over --repo/TMCT_GRAPH_FILE/tmct.toml
        [--config <path>]       an alternate tmct.toml location (a file or a directory)
        [--ephemeral]           read the graph but write nothing back (demo/read-only)
+       [--prompt "<text>"]     one-shot: run the prompt's sentences as turns and print
+                               the final answer (teach state first, trigger last)
+       [--render blocks]       with --prompt: when the final turn produced a plan,
+                               write it as a self-contained animated page
+       [--output <path>]       the rendered page's path (default plan.html)
        [--narrate]             start with narrate mode on — a verbose, developer-facing
                                trace of decision points/matched pattern/results/goal per
                                turn, appended under a "--- narrate ---" marker (also
@@ -518,6 +527,9 @@ already set up. Its `--graph` flag works differently from the others: it appends
        [--ontology <name|path>]  DIFFERENT operation from the others: it APPENDS to
        [--lexicon <name|path>]   tmct.toml's graph_files array (multi-graph growth),
        [--graph <path>]        never an extensions-bundle activation.
+       [--file <definition.txt>]  teach a plain-text definition file sentence by
+                               sentence (# lines are comments); any declined
+                               sentence exits non-zero with the sentence named
        [--memory-backend <default|memory|sqlite>]  same knob as `tmct init`
        [--config <path>]
 ```
@@ -544,10 +556,12 @@ inference" above:
 
 ```
   tmct viz [--repo <abs>]      write one self-contained, navigable HTML file rendering the
-       [--focus <id>]         memory graph: pan/zoom, click a node for its label/class/
-       [--term <word>]        timestamps. Seeds from the most recently created individual
-       [--depth <n>]          by default (--focus <id> or --term <word> override it);
-       [--limit <n>]          --output defaults to graph.html in the cwd.
+       [--ledger]             memory graph: pan/zoom, click a node for its label/class/
+       [--focus <id>]         timestamps. Seeds from the most recently created individual
+       [--term <word>]        by default (--focus <id> or --term <word> override it);
+       [--depth <n>]          --output defaults to graph.html in the cwd. With --ledger,
+       [--limit <n>]          a readable fact ledger around one focus term instead
+                              (writes ledger.html; --limit caps the embedded fact rows).
        [--hub-degree <n>]     --depth = max arcs (hops) from the focus node (default 3);
        [--edge-kind <mode>]   --limit = spiral length, total nodes walked (default 300);
        [--output <path>]      --hub-degree = stop expanding THROUGH a node above N

package/ROADMAP.md

@@ -10,7 +10,10 @@ open items, session-scoped), see `HANDOVER.md` instead — this file doesn't dup
 A tolerant, ELIZA/PARRY-style chat surface over a codebase, obsessed with software the way PARRY was
 obsessed with the mafia — deterministic, zero-cost, **no LLM anywhere in the product path**. Guides a
 user toward precision queries rather than guessing; every answer is grounded, restates every genuine
-reading it finds in full, or is an honest miss when nothing grounds it at all.
+reading it finds in full, or is an honest miss when nothing grounds it at all. Its visual surfaces —
+the ledger explorer with its in-browser chat (`tmct viz --ledger`), the animated plan page
+(`chat --prompt … --render blocks`), and the Pages homepage hero — are the same graph read out loud:
+same engine, same provenance, no LLM.
 
 ## Ambition
 
@@ -48,9 +51,19 @@ getting silently traded away by inherited caution:
   and an NPC turn scheduler. Design-only.
 - **`PLAN_SYLLOGIST.md`** — retraction-aware consistency checking under a hard budget and trust
   tiers, the one open piece of the reasoning engine's research horizon. Design-only.
-- **`PLAN_GUESS_NUMBER.md` / `PLAN_HANOI.md`** — closed-loop and open-loop planning domains for the
-  `findActionPath`/`findReachableSet` kernels, both already built and proven but not yet wired to
-  either domain. Design-only.
+- **`PLAN_HANOI.md` follow-ups** — the plan itself shipped (taught game domains, the chat plan
+  lane, `tmct import --file` + the `.tmct/imports/` scaffold, the animated plan page; see its
+  implementation addendum). Remaining: river-crossing's two missing frames plus the multi-effect
+  interpreter extension, and planner-side consumption of the `taught:` capability records the
+  registry bridge now registers.
+- **`PLAN_GUESS_NUMBER.md`** — the closed-loop (observe-and-replan) planning domain for the same
+  kernels. Design-only.
+- **`PLAN_VIZ_LEDGER.md` follow-ups** — phases 1-4 shipped (the ledger explorer, its chat dock,
+  the Pages hero, this README pass). Remaining: whether the ledger becomes the default viz
+  surface; a `goal` field on `factAnswer`'s returns so the dock can carry the chat's goal line
+  (needs operator sign-off — it touches the ask engine); a predicate-cardinality question for
+  `findContradictions` (multi-valued `has`/`can` facts group under the same contract as genuine
+  disagreements); bundle weight if the ledger page outgrows its measured ~533 KB.
 - **`PLAN_CODE.md`** — small JS-function and HTML/CSS-fragment synthesis via a sandboxed headless
   browser (Track 1, program synthesis, already shipped). Blocked on a sandbox dependency decision.
 - **`PLAN_AGENTS.md`** — the governing plan for tmct's broader multi-repo arc (marginalia, seonix,

package/bin/tmct.mjs

@@ -38,6 +38,11 @@ Usage:
                                see src/graph-merge.mjs); wins over --repo/TMCT_GRAPH_FILE/tmct.toml
        [--config <path>]       an alternate tmct.toml location (a file or a directory)
        [--ephemeral]           read the graph but write nothing back (demo/read-only)
+       [--prompt "<text>"]     one-shot: run the prompt's sentences as turns and print
+                               the final answer (teach state first, trigger last)
+       [--render blocks]       with --prompt: when the final turn produced a plan,
+                               write it as a self-contained animated page
+       [--output <path>]       the rendered page's path (default plan.html)
        [--narrate]             start with narrate mode on — a verbose, developer-facing
                                trace of decision points/matched pattern/results/goal per
                                turn, appended under a "--- narrate ---" marker (also
@@ -77,6 +82,9 @@ Usage:
        [--ontology <name|path>]  DIFFERENT operation from the others: it APPENDS to
        [--lexicon <name|path>]   tmct.toml's graph_files array (multi-graph growth),
        [--graph <path>]        never an extensions-bundle activation.
+       [--file <definition.txt>]  teach a plain-text definition file sentence by
+                               sentence (# lines are comments); any declined
+                               sentence exits non-zero with the sentence named
        [--memory-backend <default|memory|sqlite>]  same knob as \`tmct init\`
        [--config <path>]
   tmct extend --validate <dir>  validate a third-party extension pack's declared
@@ -86,10 +94,12 @@ Usage:
        [--depth <n>] [--budget <n>]  chain the memory's rdfs:subClassOf closure, materialising
        [--config <path>]      bounded, low-trust, retractable entailed facts (never on the chat path)
   tmct viz [--repo <abs>]      write one self-contained, navigable HTML file rendering the
-       [--focus <id>]         memory graph: pan/zoom, click a node for its label/class/
-       [--term <word>]        timestamps. Seeds from the most recently created individual
-       [--depth <n>]          by default (--focus <id> or --term <word> override it);
-       [--limit <n>]          --output defaults to graph.html in the cwd.
+       [--ledger]             memory graph: pan/zoom, click a node for its label/class/
+       [--focus <id>]         timestamps. Seeds from the most recently created individual
+       [--term <word>]        by default (--focus <id> or --term <word> override it);
+       [--depth <n>]          --output defaults to graph.html in the cwd. With --ledger,
+       [--limit <n>]          a readable fact ledger around one focus term instead
+                               (writes ledger.html; --limit caps the embedded fact rows).
        [--hub-degree <n>]     --depth = max arcs (hops) from the focus node (default 3);
        [--edge-kind <mode>]   --limit = spiral length, total nodes walked (default 300);
        [--output <path>]      --hub-degree = stop expanding THROUGH a node above N
@@ -596,6 +606,65 @@ async function main() {
     if (graphPaths.length) extra.graphPaths = graphPaths;
     if (configPath) extra.configPath = configPath;
     if (memoryBackend) extra.memoryBackend = memoryBackend;
+    // `--prompt "<text>"` — one-shot mode: each sentence of the prompt runs as
+    // its own turn (state teaches first, the goal/solve trigger last), the
+    // FINAL turn's answer prints to stdout, and the process exits. Piped stdin
+    // stays the interactive fallback.
+    const prompt = strFlag(rest, ["--prompt"]);
+    // `--render <archetype> [--output <path>]` — after a one-shot --prompt whose
+    // final turn produced a plan, write the self-contained animated plan page
+    // (src/plan-viz.mjs). Requires --prompt: interactive chat has no single
+    // final turn to render.
+    let renderArchetype;
+    try {
+      renderArchetype = enumFlag(rest, ["--render"], ["blocks"]);
+    } catch (e) {
+      process.stderr.write(`tmct: ${e?.message || e}\n`);
+      process.exit(2);
+    }
+    if (renderArchetype && !prompt) {
+      process.stderr.write("tmct: --render needs --prompt (a one-shot turn whose plan it renders)\n");
+      process.exit(1);
+    }
+    if (prompt) {
+      const { createSession } = await import("../src/chat.mjs");
+      const { splitSentences } = await import("../src/sentences.mjs");
+      const session = await createSession({ repoPath, ephemeral, narrate, ...extra });
+      let finalAnswer = "";
+      let finalPlan = null;
+      let parts;
+      try { parts = splitSentences(prompt); } catch { parts = null; }
+      const sentences = parts && parts.length ? parts : [prompt];
+      for (const s of sentences) {
+        const t = await session.turn(s);
+        finalAnswer = t?.answer ?? "";
+        finalPlan = t?.plan ?? null;
+      }
+      await session.close();
+      process.stdout.write(finalAnswer + "\n");
+      if (renderArchetype) {
+        if (!finalPlan) {
+          process.stderr.write("the final turn produced no plan — nothing to render\n");
+          process.exitCode = 1;
+          return;
+        }
+        const { renderPlanHtml } = await import("../src/plan-viz.mjs");
+        const { writeFile } = await import("node:fs/promises");
+        const { resolve: resolvePath } = await import("node:path");
+        const outPath = resolvePath(process.cwd(), strFlag(rest, ["--output", "--out"], "plan.html"));
+        const rendersAs = finalPlan.domain?.renderHints ?? {};
+        const sizeOrder = (finalPlan.domain?.ordering ?? [])
+          .filter((row) => /-than$/.test(String(row.predicate || "")))
+          .map((row) => [row.subject, row.object]);
+        const html = renderPlanHtml({
+          plan: finalPlan, rendersAs, sizeOrder,
+          title: finalPlan.goal?.text || "tmct plan",
+        });
+        await writeFile(outPath, html, "utf8");
+        process.stdout.write(`wrote ${outPath} (${finalPlan.actions.length} moves, ${finalPlan.states.length} snapshots)\n`);
+      }
+      return;
+    }
     // The shell gate: a real terminal gets the full-screen Ink TUI; `--plain` or a
     // non-TTY stream (pipes, scripts, the test suite) gets the readline shell. Both
     // drive the same createSession sink — only the drawing differs.
@@ -867,8 +936,9 @@ async function main() {
       process.exit(2);
     }
 
-    if (!corpusVal && !ontologyVal && !lexiconVal && !graphFlags.length && !memoryBackendVal) {
-      process.stderr.write("tmct import: needs at least one of --corpus/--ontology/--lexicon/--graph/--memory-backend\n");
+    const fileVal = strFlag(rest, ["--file"]);
+    if (!corpusVal && !ontologyVal && !lexiconVal && !graphFlags.length && !memoryBackendVal && !fileVal) {
+      process.stderr.write("tmct import: needs at least one of --corpus/--ontology/--lexicon/--graph/--memory-backend/--file\n");
       process.exit(2);
     }
 
@@ -914,6 +984,22 @@ async function main() {
         process.exit(1);
       }
     }
+
+    // `--file <definition.txt>` — teach a plain-text definition file, one
+    // sentence per turn, through the same recognizers the live chat uses.
+    // Any declined sentence exits non-zero: a half-taught game plans wrongly
+    // or not at all with no visible cause otherwise.
+    if (fileVal) {
+      const { importDefinitionFile } = await import("../src/import-file.mjs");
+      try {
+        const result = await importDefinitionFile(repoRoot, fileVal);
+        process.stdout.write(result.report + "\n");
+        if (result.declined.length > 0) process.exit(1);
+      } catch (e) {
+        process.stderr.write(`tmct import: ${e?.message || e}\n`);
+        process.exit(1);
+      }
+    }
     return;
   }
 
@@ -1012,7 +1098,7 @@ async function main() {
     // depth/age falloff. Same repo resolution as `memory`/`syllogise` —
     // resolveRuntimeConfig: --repo > git root > cwd.
     const rest = process.argv.slice(3);
-    const { strFlag, resolveRuntimeConfig } = await import("../src/cli-args.mjs");
+    const { strFlag, boolFlag, resolveRuntimeConfig } = await import("../src/cli-args.mjs");
     const { computeVizGraph, renderVizHtml, readAskBundle, readMemoryAskBundle } = await import("../src/viz.mjs");
     const { writeFile } = await import("node:fs/promises");
     const { resolve } = await import("node:path");
@@ -1021,15 +1107,35 @@ async function main() {
       const v = j !== -1 ? Number(rest[j + 1]) : NaN;
       return Number.isFinite(v) ? v : undefined;
     };
+    const ledger = boolFlag(rest, ["--ledger"]);
     const focus = strFlag(rest, ["--focus"]);
     const term = strFlag(rest, ["--term"]); // PLAN_VIZ_MEMORY.md: seed via normFactTerm-matched Fact(s), alongside --focus
     const depth = numFlag("--depth"); // max arcs (hops) from the focus node
-    const nodeLimit = numFlag("--limit"); // spiral length: total nodes walked
+    const nodeLimit = numFlag("--limit"); // spiral length: total nodes walked (ledger mode: fact-row cap)
     const hubDegree = numFlag("--hub-degree"); // stop expanding THROUGH a node above N connections
     const edgeKindModeRaw = strFlag(rest, ["--edge-kind"]);
     const edgeKindMode = ["meta", "relation", "both"].includes(edgeKindModeRaw) ? edgeKindModeRaw : undefined;
-    const outPath = resolve(process.cwd(), strFlag(rest, ["--output", "--out"], "graph.html"));
+    const outPath = resolve(process.cwd(), strFlag(rest, ["--output", "--out"], ledger ? "ledger.html" : "graph.html"));
     const { repo } = await resolveRuntimeConfig({ argv: rest });
+    if (ledger) {
+      const { computeLedgerData, renderLedgerHtml } = await import("../src/ledger-viz.mjs");
+      const data = await computeLedgerData(repo, {
+        ...(focus ? { focus } : {}),
+        ...(!focus && term ? { term } : {}),
+        ...(nodeLimit != null ? { rowLimit: nodeLimit } : {}),
+      });
+      const memoryAskBundle = await readMemoryAskBundle();
+      await writeFile(outPath, renderLedgerHtml({ ...data, memoryAskBundle }), "utf8");
+      process.stdout.write(
+        `tmct viz --ledger — wrote ${data.meta.shown} fact row(s) around ${data.focus ? `'${data.focus}'` : "no focus"} to ${outPath}\n`,
+      );
+      if (data.meta.truncated) {
+        process.stdout.write(
+          `showing ${data.meta.shown} of ${data.meta.total} rows — narrow with --focus <term> or raise --limit\n`,
+        );
+      }
+      return;
+    }
     const vizGraph = await computeVizGraph(repo, {
       ...(focus ? { focus } : {}),
       ...(!focus && term ? { term } : {}), // --focus takes precedence when both are given

package/data/games/crates.txt

@@ -0,0 +1,24 @@
+# crates — a second taught game, same closed frames as hanoi-3.
+# Lines starting with # are skipped by import.
+# No size order here: stacking is legal onto any clear crate or pallet, so this
+# domain exercises the comparator precondition being optional. Goals can be a
+# conjunction — teach several goal sentences before "solve it".
+#
+# After `tmct import --file crates.txt`, try this in `tmct chat` (or via --prompt):
+#
+#   crate-c rests on crate-a. crate-a rests on pallet-1. crate-b rests on pallet-2.
+#   the goal is that crate-a rests on crate-b. the goal is that crate-b rests on pallet-2.
+#   solve it.
+#
+# (2 moves: clear crate-a, then stack it — the solver may route crate-c to
+# pallet-3 or onto crate-b; both are optimal.)
+a crate is a kind of container.
+a pallet is a kind of place.
+crate-a is a crate. crate-b is a crate. crate-c is a crate.
+pallet-1 is a pallet. pallet-2 is a pallet. pallet-3 is a pallet.
+you can stack a crate onto a pallet.
+you can stack a crate onto a crate.
+to stack a crate onto a target, nothing may rest on the crate.
+to stack a crate onto a target, nothing may rest on the target.
+stacking a crate onto a target makes the crate rest on the target.
+a crate renders as a block. a pallet renders as a slot.

package/data/games/hanoi-3.txt

@@ -0,0 +1,30 @@
+# hanoi-3 — a taught game definition. Lines starting with # are skipped by import.
+# After `tmct import --file hanoi-3.txt`, try this in `tmct chat` (or via --prompt):
+#
+#   disk-1 rests on disk-2. disk-2 rests on disk-3. disk-3 rests on peg-a.
+#   the goal is that every disk rests on peg-c. solve it.
+#
+# Variations, each stretching a different direction:
+#   scale      — first teach: "disk-4 is a disk. disk-3 is smaller than disk-4."
+#                start all four on peg-a, same goal. 15 moves (2^4 - 1).
+#   any start  — disk-1 rests on peg-b. disk-2 rests on peg-c. disk-3 rests on peg-a.
+#                the goal is that every disk rests on peg-c. solve it.
+#   other goal — same start, "the goal is that every disk rests on peg-b. solve it."
+#   partial    — "the goal is that disk-3 rests on peg-c. solve it."
+#                (a one-fact goal; exercises the non-universal goal frame)
+#   legality   — "what moves are legal now?"  (findReachableSet, one ply, no plan)
+#   read-back  — "what rests on disk-2?" / "is disk-1 clear?"  (plain fact questions,
+#                no planning involved)
+a disk is a kind of game piece.
+a peg is a kind of place.
+disk-1 is a disk. disk-2 is a disk. disk-3 is a disk.
+peg-a is a peg. peg-b is a peg. peg-c is a peg.
+disk-1 is smaller than disk-2. disk-1 is smaller than disk-3.
+disk-2 is smaller than disk-3.
+you can move a disk onto a peg.
+you can move a disk onto a disk.
+to move a disk onto a target, nothing may rest on the disk.
+to move a disk onto a target, nothing may rest on the target.
+to move a disk onto a disk, the disk must be smaller than the target.
+moving a disk onto a target makes the disk rest on the target.
+a disk renders as a block. a peg renders as a slot.

package/package.json

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