You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
thoughtml guide — the language travels inside the binary. The whole spec is
embedded (include_str!) so a tool you just cargo installed can teach itself, with no
website and no network. Three shapes over one source (crates/thoughtml/llms.txt):
thoughtml guide — a one-screen tour (the 60-second model + a quick reference + a topic menu).
thoughtml guide <topic> — one section, by keyword (relations, kinds, mirror, time, formulas, …) or number.
thoughtml guide --full — the complete, source-derived spec, meant to be piped into an
AI (thoughtml guide --full | pbcopy).
The same file is served on the site at /llms.txt and bundled in the crate and npm
packages, so the CLI, the site, and the AI-ready dump can never disagree.
Changed
llms.txt rewritten and re-verified against parser source. Now carries the exact
compute mechanics (derived-confidence propagation, grounded argument status, decision
expected value), the full diagnostic-code table (TML101–TML501), formulas and units,
imports, and a concept → example index mapping every one of the 20 corpus documents to
the construct it demonstrates. Moved from the repo root into the crate so it publishes with
the package.
Internal
A conformance test (corpus_covers_every_core_construct) asserts every core kind, relation,
and posture has a worked instance in the example corpus — so "the guide teaches the whole
language" is enforced, not assumed. (roadmap-priorities gained an assumption and a considers to close the last two gaps.)
Installable, not just cloneable.thoughtml now ships as prebuilt binaries for
macOS, Linux, and Windows — attached to each GitHub release, built by cargo-dist — and as an npm package: npm install -g thoughtml puts the CLI on your PATH with no Rust toolchain
required. Building from source (cargo install / cargo build) still works.
A subcommand CLI — the toolchain, not just a compiler.thoughtml grows
git-style subcommands; the bare thoughtml <file> [--compute/--html/…] invocation
is unchanged and still the default.
check — validate and report diagnostics without emitting the model. --json gives each diagnostic a stable code (TML1xx vocabulary … TML5xx
lints), line, and a suggested help fix (nearest-spelling for the "unknown
<thing>" family — supprts → supports); --lint adds opinionated checks,
starting with the supports-used-as-a-list detector (TML501) that catches
the enumeration-inflates-confidence smell; --strict fails on any warning. The
machine-readable stream is what an agent or editor self-corrects against.
fmt — rewrite a document in one canonical style (two-space indentation,
a blank line between records, normalized field/body order). It re-parses its own
output and refuses to write if the model would change, so formatting is always
safe; --check (CI) and -w (in place). Comments are not yet preserved.
explain <id> — trace why a node reads the way it does: its derived
confidence and grounded status, the evidence for and against it with each edge's leverage, the stances on it, the conflict it's caught in, and a one-line "why".
Makes the mirror interrogable, not just declarative.
diff <a> <b> — a semantic diff at the belief level, not the text level:
nodes added/removed, confidence and status changes (in→out), supersession,
and the conflicts that appeared or resolved between two documents. Version
control for reasoning. Install with cargo install --path crates/thoughtml.
Concise authoring surface (M1–M2) — less boilerplate, same model. Pure sugar
that desugars to the existing canonical model; every prior .thml still parses.
Typed headers. A built-in kind used as the header word — observation foo, decision bar — is shorthand for focus foo + kind.
Optional time / narrative replay. Time is no longer required to get a good
view. A document with no real time spread reveals and lays out in document
order (each node carries a seq), so authors stop inventing timestamps just
to force an ordering; dated documents are unchanged.
Evidence bundles. A <relation> <target> header lists its sources, one per
line (supports claim + members), each desugaring to an ordinary link.
On the ~1,200-line Netflix case study these cut the file ~40% with an
identical canonical model.
Collections & candidates (M3) — enumerations stop polluting the mirror. Two
non-evidential relations: part-of (a collection member) and candidate-for (a proposed answer to a question). Using supports to list
a claim's parts silently inflated its derived confidence (a SWOT-summary read as
100%-certain just for naming its items); part-of has no evidence polarity, so it
never touches confidence, argument status, or leverage. The engine needed no
change — non-supports/opposes/undercuts relations were already ignored by
evidence propagation. The viewer renders them as a muted, subordinate member
edge.
Memory & time overhaul (Phase A) — valid-time is now the backbone. Five
temporal primitives toward "version control for reasoning":
Time spine. The derived timeline now carries an ordered events array
(at, seq, id, kind, optional agent), sorted by valid-time with a seq tiebreak — the document's reasoning as a sequence of moments, not the
order you happened to type it.
Tree-of-thought. A focus or question can contain other records by
nesting them (indentation); the members are recorded on includes and inherit
the container's provenance/temporal context. A thought-tree, not a flat list.
Lifecycle / fold. A focus gains a first-class status: open / settled / superseded / abandoned. An abandoned branch is kept
with its reason, not deleted, so dead ends stay inspectable.
Keep-everything. Redefining a focus with differing content no longer
silently clobbers the first definition — every alternative is retained on divergent and surfaced as a definition-divergence conflict. Concurrent
authoring is lossless.
As-of replay.--as-of <instant> (valid-time, the default axis) and --as-of-seq <n> (transaction order) project the model to a point in time,
cascading to drop dangling links and stances to a fixpoint. Exposed in the
library as parse_str_as_of / AsOf.
A second conflict type: definition-divergence (warning). The mirror now
flags a focus defined more than once with differing content — see above.
Standalone interactive viewer (thoughtml --html). Bake any document into a
single, self-contained HTML file — the interactive graph (pan/zoom, node detail,
the lenses, the as-of timeline, light/dark) with the canonical model inlined and no wasm and no server. --html implies the full compute stack so every lens
has data. The graph is now an output of the toolchain, alongside JSON.
Changed
The viewer is now a time-driven reasoning view (Track D). The playground's
"Readable" surface is replaced by a Viewer that lays reasoning out along
time — earlier beliefs to the left, later to the right — with vertical position
emerging from a force layout rather than fixed lanes, and a built-in replay
(drag the as-of bar, or press play) that fades beliefs in as of when they were
asserted. "Structural" stays as the node-link view. The same time-driven
renderer (timeview.ts, dependency-free SVG) drives the standalone --html
export, so both render identically.
The renderer is a wasm-free core. The graph/detail/legend projection was
split from the wasm parser (a pure model.ts type seam), so the same renderer
drives both the playground and the standalone viewer — they can't drift. The
viewer ships with system fonts (no inlined web fonts), keeping each exported
file small. A CI freshness guard rebuilds the viewer template and fails if the
committed copy drifts, so cargo build still needs no Node.
Removed
Interactive what-if. The playground's what-if control (mute a node/link and
re-derive the counterfactual live) is gone, along with its wasm bridge
(parse_what_if). It leaned oracle rather than mirror, never worked in the
standalone viewer (it needs a live parser), and left the playground with a third
control the docs already described as a two-lens spine. The underlying override
engine (Overrides / parse_str_with_overrides) stays — it's the derive
pipeline's spine and still powers sensitivity / leverage, which is unchanged.
