Atomic Learning Graph — a plain-English edition of a real textbook: one idea per page, a receipt on every sentence, and no AI while you read (the build proves it against the shipped bytes).
- Who it's for: learners who want AI's help but don't trust unverifiable output — and want a durable course they keep, not a chatbot thread they lose.
- What to click: the live demo — it runs offline in your browser.
- What makes it different: Codex (GPT-5.6) wrote this repo under adversarial gates it couldn't talk past, then runs as the atomizer inside the product. One model, two jobs.
- Built: entirely during OpenAI Build Week 2026.
A plain-English edition of a real textbook — one idea per page, a receipt on every sentence, and no AI while you read.
Every lesson step has a receipt. Every claim has a gate. Give it an open textbook chapter. It produces an offline learning path where every lesson step can be challenged against the exact source passage it cites.
Humans specify the educational intent; a model does the expensive translation work; deterministic evidence makes every boundary visible. We don't ask what kind of learner you are — we give every learner several grounded routes to the same idea, and we show you the receipts.
The live demo is the reader for one compiled course. Build your own from open text with the local builder →
Open the live demo → — runs entirely in your browser; nothing is generated while you read.
Watch the 60-second explainer → — a plain-language tour of what it does and why. Prefer the full version? Here's the longer walkthrough.
The whole project, in five steps:
- Pick something to learn. Choose a goal concept.
- Follow the prerequisite path. A deterministic order, derived from the graph, teaches one idea per page.
- Challenge any sentence against its source. Every lesson step is anchored to a real, highlighted passage.
- Inspect how the course was generated and verified. Human-specified structure, model-generated prose, deterministically-verified grounding, advisory-reviewed quality, and the limits we do not prove — each boundary is labelled, not hidden.
- Build your own. Paste your own open text and key into the builder; it compiles a course you can then read offline.
Pick something you want to understand. We work backwards through a prerequisite graph to the ideas
it rests on, and teach them one page at a time, in order. Every page is a plain-English translation
of a passage from Dive into Deep Learning (Zhang, Lipton, Li & Smola), pinned to commit
b2e2ae3. Every
page shows you the exact sentence it came from, highlighted.
The translation was made once, before publication, and checked against the source. Nothing is generated while you read. No key, no network, no model call. That is enforced against the shipped browser bytes, not left as a promise.
- Run the offline reader
- Understand the pipeline
- Inspect what is verified
- Use an export in your tool
- See the build record
- Check maintenance and contribute
- Read the project map
- Read the limits
- Read the licenses
- Inspect compilation mechanics
The committed reader needs Node.js 22.18 or newer and pnpm 10.33.0 (the exact
engines and packageManager contract). It needs no API key and makes no model
or network request while a learner reads.
git clone https://github.com/beauboorman/atomic-learning-graph.git
cd atomic-learning-graph
corepack enable
pnpm install
pnpm build
pnpm previewOpen the local URL Vite prints, then stop the preview server with Ctrl+C when
you are done. Use pnpm preview instead of opening dist/index.html directly: a file:// origin
cannot load the built module.
The local BYOK builder requires Node.js 22.18 or newer, text you are allowed to embed, and your
own provider key. From the checkout, run pnpm alg for the guided terminal UI, or follow the
complete builder guide for the local browser flow. Building makes billed provider calls;
the produced one-file reader is offline after a successful build.
- Specify. A human fixes the course goal, concept inventory, prerequisite edges, and permitted source corpus before a model is called.
- Compile. The model proposes grounded explanations, citations, and optional analogies inside that fixed structure.
- Verify. Deterministic checks reject bad licenses, structure, provenance, paths, and shipped browser bytes; advisory reports stay advisory.
- Ship. The committed graph and its projections power a static reader and exports. Reading is a pure local walk over those bytes, not a request-time model session.
The compilation-mechanics appendix records the detailed boundary conditions. The next section states the claims the repository actually checks.
- Atomic steps: one idea per page, never two.
- Prerequisite scaffolding: a deterministic order, derived from the graph, not guessed.
- Optional analogies: the same idea through cooking, sports, music, video games, cars, gardening.
- Optional depth: every step, or just the spine.
Multiple representations, analogical transfer, cognitive-load management, interest-based motivation. These are not learning styles. That idea has been tested and it does not hold up — see Pashler et al. (2008), Learning Styles: Concepts and Evidence; Coffield et al. (2004), Should We Be Using Learning Styles?; and Kirschner (2017), Stop Propagating the Learning Styles Myth.
Every claim on this page is a property of the committed artifact, not a description of intent.
| Claim | Where it is enforced |
|---|---|
| Nothing is generated at read time | After pnpm build, pnpm verify:bundle scans emitted JavaScript, HTML and CSS for network clients, the model vendor and remote assets. src/ui/gate9.test.ts keeps a faster source-level tripwire, but the hard claim rests on the bytes shipped to the learner. The app runs offline. |
| Every lesson step is anchored to a real sentence | All 52 steps carry a quotedText that must be a substantial content-bearing span (at least 8 lexical words, including 4 non-stopwords) and occur verbatim in exactly one resolved source. src/graph/invariants.ts refuses to write a graph where it doesn't. |
| The path is derived, not guessed | src/graph/path.ts is a pure prerequisite-ancestor walk with a stable tie-break, over 9 committed prerequisite edges. Same goal in, same route out, every time. |
| We caught a model failure our citation gates don't check — and designed the gate that will | data/graph.json is written only by pnpm atomize. Its sha256 is pinned in data/graph.run.json, and src/atomization/graph-run.test.ts recomputes it — so an UNDISCLOSED hand-edit turns the suite red. There is exactly one disclosed human correction on record: a human caught that the model's self-attention worked example demonstrated uniform averaging (which is average pooling, not attention). The deterministic citation gates verify that the prose's quotedText bytes occur verbatim in the source; they do not check that the prose's arithmetic demonstrates the concept it claims to — so this error was invisible to them. It is not, however, uncatchable by a machine: ROADMAP.md §15 specifies the deterministic gate that closes exactly this gap — the model emits token values and a weight matrix, code computes the example, and a structural check rejects any uniform weight row — turning this one-time human catch into a machine invariant. The correction touched lesson prose and its analogies only; every quotedText citation, every source byte, every concept id, and every structural invariant is unchanged. It is documented in PROVENANCE-PATCHES.md and under humanPatches in data/graph.run.json, and the project's position is that a human-in-the-loop catch — disclosed on the record and being systematized into a gate — is the honest answer to a gap in automated coverage, not a contradiction of the machine-emitted claim but the strongest possible evidence the discipline behind it is real. |
| The sources are what we say they are | Four pinned CC-BY-SA-4.0 source sections (spanning three chapters), license-checked before ingestion, with revision pins and license evidence recorded in data/oer/sources.json. |
The course structure is hand-specified, not discovered. We decided in advance which ten concepts the
course must contain, which source each one cites, which nine prerequisite edges connect them, and that
self-attention is the goal. The model then fills that fixed structure with grounded content — titles,
summaries, tags, lesson steps, analogies, and the chosen source quotes — and the build refuses to ship
if its output does not match the specified structure exactly. The model proposes; deterministic code
disposes.
How that structuring actually works (mechanics)
The inventory prompt requests the exact ten-concept set; the grounded response is projected onto that
fixed ID set. The relationship prompt receives the exact nine-edge set; code replaces any returned
relations with those edges. pnpm verify:anchors checks that five named corpus passages remain
verbatim in the extracted sources. Those passages are not inserted into the graph as constants: the
model proposes each concept quote, and code only normalizes whitespace before matching the proposal to
the stored source bytes. If a required quote fails grounding, a concept-specific regex narrows the
stored-source excerpt for a separate model repair. The build refuses to write an artifact whose IDs,
source assignments, edges, route, or goal differ from the specified structure.
The model still proposes the grounded content inside those ten slots: titles, summaries, tags, all ten concept-level quote selections, all lesson steps, and all analogies. The graph and citations then face deterministic gates; analogies remain optional illustrations.
The shipped artifact: 10 concepts, 9 prerequisite edges, 52 cited lesson steps (40 core, 12 deep) and 312 optional analogies across 6 passions, plus the complete text of the four pinned sources, embedded so the receipt can be verified in the browser with no request.
The lessons are a translation, not a summary, and translation is the product here.
We render each idea in the plainest English that keeps the meaning whole, following the principle translators call dynamic equivalence: meaning-for-meaning, not word-for-word. We anchor every sentence to the passage beside it. The highlighted words are the authors' own.
The lineage is visible rather than hidden. The translation was made in a single build-time run by a language model, bounded at every step by deterministic checks it cannot talk its way past:
- The pipeline license-checks every corpus source before ingestion. It uses an exact-match SPDX allowlist and fails closed.
- The model fills the pinned concepts with grounded content, returns relations that code projects onto the pinned edge set, translates each converged concept into cited lesson steps, and pre-builds the optional analogies as clearly labelled illustrations.
- Bounded validate → repair → re-validate loops check graph structure, goal reachability, quote-primary provenance, lesson citations, and the readability floor.
- On convergence,
pnpm atomizewrites the sorted graph and a run log recording each call's token usage and cost. It never writes a failing graph. - The browser receives only that committed artifact and calls the pure
getPath()function locally.
The map is human-specified; model output fills it with grounded lessons and citations, and is not trusted until the deterministic checks pass.
Each negative test names the cheating implementation it kills. A () => [] stub, a hard-coded
golden path, a substring shortcut, and a first-match source lookup each have a test built to catch
them. That adversarial suite fenced Codex with executable constraints it could not talk past.
A safety property, and it is not circular. No fabricated citation passes the gates: five tamper scenarios — empty-graph stub, hard-coded golden path, substring-faked citation, first-match source lookup, hand-edited graph.json — are all rejected (5 / 5), and every lesson step's cited source excerpt is checked byte-for-byte against the real source — the plain-English lesson is a faithful translation of that excerpt, shown beside it so you can judge the translation; analogies are illustrative, not sourced. Unlike a live-AI tutor whose grader is validated on a gold set its own model family authored, this proof rests on deterministic checks against a real CC-BY-SA source — there is no model judging itself at read time.
One model, gpt-5.6-sol, did two jobs here.
As Codex, the coding agent, it wrote this repository in a phase-gated RED→GREEN run. The committed
docs/kickoff-prompt.md is the collaboration record: it fixed the
acceptance gates, resumed Codex phase by phase, and forbade weakening tests or hand-writing the
graph.
The same model is the build-time atomizer inside the product. Working inside the pinned ten-concept structure, it produces candidate lessons, citations, and analogies for deterministic validation. That role never runs when a learner reads; the browser receives only committed artifacts.
So gpt-5.6-sol both built the machine and is the intelligence the machine calls at build time, and
in both roles the same discipline holds: it proposes, and gates that it cannot talk past decide what
ships.
The thesis is the compiler and its receipts. Everything below is supporting evidence that the guarantees travel — not the headline.
-
A build receipt. The compile records a machine-checkable receipt in
data/graph.run.json: the source corpus and pin, the model, token usage, cost, and the graph's sha256 (bbcf8b33…) thatsrc/atomization/graph-run.test.tsrecomputes. It distinguishes the human-specified structure from the model-generated prose, and records that the browser makes zero model calls. -
Six learning-content exports, attribution-clean. The one graph emits six learning-content exports: an
llms.txtmanifest, an org-roam graph, a native Tinderbox document, an Obsidian vault, an Anki deck, and a grounded practice exam — the most education-shaped artifact: every answer in its key carries the verbatim source passage that grounds it. The six carry CC-BY-SA attribution, a deed link, and a modification notice. Listed separately because they are not learning content: a portable, rebuildable OPML outline — the deterministic interchange artifact that drives the Tinderbox import — and a machine-checkable course receipt recording the work, authors, license, revision, and graph hash.pnpm verify:llms,verify:orgroam,verify:tinderbox,verify:obsidian,verify:anki,verify:exam,verify:receiptgate them against the committed graph. The Obsidian vault opens with a prerequisite-ordered Start Here note and carries the full cited lesson in every concept note; org-roam leads with the same learning path. The native Tinderbox document opens directly with styled concept/source/edge prototypes, a mapped learning path, and native prerequisite links; the deterministic OPML remains the only gated, rebuildable Tinderbox artifact: Tinderbox imports it in one shot, promotes graph metadata to inspectable user attributes, applies the presentation, and materializes prerequisite links while preserving every canonical relation as a typed edge record. The committed.tbxis a hand-finished convenience for opening the course without an import step; it is not regenerated by the gate, so the OPML is the supported interchange and the.tbxis a presentation convenience.These are deliberately opinionated, presentation-ready projections, not neutral dumps or new authorities. Each emitter applies the best practices we could verify in that format's documentation and community conventions: navigable entry points, native metadata, useful ordering, readable labels, attribution where a learner encounters the content, and styling when the format supports it. Those choices can be changed in the emitter;
data/graph.jsonremains the only authority for course content and relationships. The implementation follows the native guidance for Anki text imports, Obsidian links, org-roam, Tinderbox OPML attribute mapping, and the llms.txt proposal, rather than forcing every platform into one lowest-common-denominator shape.A separate, optional export showcase presents a plain-language mini-course about the product in each supported application. It doubles as human onboarding and a presentation fixture: people can learn how Atomic Learning works in their preferred tool, while maintainers can inspect that tool's links, hierarchy, metadata, and styling. Normal course exports do not include this product tutorial, so repeat exports stay clean.
No coding is required. Download the file or folder for your app, then follow the matching row:
For import prerequisites, exact file paths, and the distinction between a gated export and an application-specific import experience, see the exports guide. The table is the short version.
| Format | What it is | How to open and use it |
|---|---|---|
| Obsidian vault | A linked set of course notes with lessons and source receipts. | GitHub does not let you download a single folder directly, so either clone the repository (git clone) or use Code → Download ZIP on GitHub, then unpack it. In Obsidian, choose Open folder as vault, select the exports/obsidian folder, then open Start Here and follow the learning path. |
| org-roam | The same linked course as one Emacs Org file. | Put the .org file in your org-roam folder, open it in Emacs, run M-x org-roam-db-sync once, then begin at Learning Path. |
| Tinderbox | A visual course map with styled concept cards, sources, and prerequisite links. | The supported artifact is the gated OPML file: in Tinderbox, choose File → Import…, select the OPML, and the map, prototypes, colors, positions, and links apply in one shot. A committed atomic-learning-graph.tbx is also included as a hand-finished convenience that opens directly in Tinderbox 11.8 without an import step; it is not gated or rebuilt by the pipeline. |
| Anki deck | Ready-to-study question-and-answer cards with a source receipt on every answer. | In Anki, choose File → Import, select the .tsv file, keep the Basic note type, import it, then choose Study Now. The file sets its own deck and tag. |
| Practice exam | A printable self-check with questions, passage matching, answer keys, and grounded recall checks. | Open the Markdown file in any Markdown reader or on GitHub. Answer Parts A and B before scrolling to the answer key; print it if you prefer paper. |
llms.txt |
A plain-text course index made for AI assistants; llms-full.txt contains the complete lessons and receipts. |
Attach or paste llms.txt into an assistant for the overview. Add llms-full.txt when you want it to use the full course, and ask it to follow prerequisite order and show the source receipts. |
Retention is a handoff, not a rebuild. This project compiles the inspectable artifact; long-term spaced review rides on Anki's proven scheduler via the gated Anki export. We do not reimplement a forgetting-curve engine — we hand clean, cited cards to one that is already trusted.
- A single-file offline reader.
pnpm build:singleemits onedist-single/index.htmlyou can double-click: no server, no network.pnpm verify:singlegates it. - Bring your own text and key.
builder/compiles a course from any pasted open text with your own OpenAI, Anthropic, or compatible key. The key lives in memory only, never written to disk. Building makes paid model calls at compile time; once the build converges, the downloaded reader runs offline with the same guarantees as the demo reader — no key, no network, no model call. - Cost is stated, not hidden. The demo graph cost $0.4594 to compile (~$0.046 per concept,
40,655 tokens).
src/cost/estimator.tsis a pure, no-network estimator surfaced in both the reader and the builder.
The quick start above runs the committed reader. No API key is needed to test or build its committed graph and UI.
pnpm gate is the acceptance bar. A passing pnpm test is not: it skips corpus verification, the
gap through which a false license notice nearly shipped. The gate brings the repository's checks
together and states what it does not prove on every run. Green is bounded evidence, not a claim
that the model's interpretation is correct or that every product quality is solved.
pnpm gate
pnpm typecheck
pnpm test
pnpm verify:corpuspnpm verify:corpus is hermetic by default: it validates the committed manifest, source hashes,
extraction transform, and derived notices without a network request. To additionally prove the pins
still match the real upstream source and license bytes, run VERIFY_UPSTREAM=1 pnpm verify:corpus.
pnpm estimate:cost -- path/to/source.txtestimates atomization cost locally without a model call.pnpm renderregenerates paid alternate renderings; it requires an API key and makes two model calls per concept.pnpm demo:tamperruns the five in-memory tamper scenarios against the production gates.pnpm emit:llmsrebuildsllms.txtandllms-full.txtfrom the committed graph and renderings.pnpm emit:orgroamrebuilds the org-roam graph from the committed graph.pnpm emit:tinderboxrebuilds the presentation-ready Tinderbox OPML from the committed graph. One import applies the hierarchy, inspectable metadata, prototypes, colors, badges, dimensions, and prerequisite-layer map positions; no separate styling pass is required. The native.tbxcounterpart opens directly in Tinderbox 11.8.pnpm emit:obsidianrebuilds the Obsidian vault from the committed graph.pnpm emit:ankirebuilds the Anki TSV deck from the committed graph.pnpm emit:examrebuilds the grounded practice exam from the committed graph.pnpm emit:receiptrebuilds the machine-checkable course receipt from committed build facts.pnpm emit:showcaserebuilds the separate, optional product tutorial in Markdown, Obsidian, org-roam, Tinderbox, Anki, and llms.txt formats underexports/showcase/. It is for GitHub visitors and presentation QA; normal course exports never include it.pnpm verify:showcasegates the exact showcase bytes.
Atomization is a separate build-time operation and requires OPENAI_API_KEY. Output is always
explicit; a run cannot silently replace the committed demo graph:
pnpm atomize --out-dir .artifacts/d2lThe syntactic atomicity advisory remains the default. An explicit opt-in adds the build-time GPT-5.6
semantic judge to atomicity-report.json; it costs one additional model call per concept and cannot
change convergence or the command's exit code:
pnpm atomize --out-dir .artifacts/d2l-judged --atomicity-judgeAn existing graph.json, graph.run.json, or atomicity-report.json makes the run fail closed.
Replacing the committed demo artifacts therefore requires an unmistakable, deliberate command:
pnpm atomize --out-dir data --overwrite-existing
pnpm testThe second checked corpus proves that the pipeline is not tied to machine-learning prose. Its toy run uses one pinned CC-BY-4.0 OpenStax Physics section and writes no artifact:
pnpm atomize:toy -- --manifest data/corpora/openstax-physics/sources.jsondata/graph.json remains a committed build artifact and must never be hand-edited. See ADR
001. Display-layer editorial choices (such as
sentence-case lesson titles) live in src/ui/titles.ts, deliberately outside the pinned artifact.
The honest answer is machine-checkable rather than promised. pnpm gate is the maintenance status:
on any machine, with no API key, it re-verifies the committed artifact, corpus, build, and shipped
bundle — typecheck, the full test suite (including every adversarial/negative test) against the
committed data/graph.json, license and provenance integrity of the corpus, every export's
graph-derived bytes, the production build, and the post-build network/model-client scan of the
bytes a learner actually downloads. A checkout that has rotted goes red on one of those stages; a
green gate means those bounded guarantees hold today, not that they held when this paragraph was
written, and not that every product quality outside that set is solved. The build receipt in
data/graph.run.json records what was last compiled, by which model, at
what cost.
For changes, start with CONTRIBUTING.md. It explains the non-negotiable artifact boundaries and the local checks expected before a contribution is proposed.
For orientation: data/ holds the pinned corpus and committed artifacts; src/ holds the compiler,
graph rules, and static reader; scripts/ emits and checks projections; builder/ is the separate
BYOK course builder; and exports/ holds the generated learner-facing projections. The
exports guide explains how those projections travel into other tools.
Key modules and enforcement boundaries
data/oer/: pinned upstream Markdown, deterministically extracted source text, and the fail-closed source manifest.data/corpora/openstax-physics/: a separate one-source CC-BY-4.0 corpus proving manifest-relative ingestion.src/atomization/manifest.ts: exact-match SPDX allowlist and manifest validation.src/atomization/atomize.ts: three-phase inventory, relationship, and cited-translation build.src/atomization/translate.ts: strict lesson schema, anchored excerpts, quote repair, and floors.src/atomization/analogy.ts: optional build-time analogies for the fixed interest set.src/graph/invariants.ts: the six hard deterministic proof invariants.src/graph/atomicity-report.ts: an advisory-only concept atomicity reporter; never a gate.src/graph/atomicity-scorer-llm.ts: opt-in build-time GPT-5.6 semantic atomicity judge; fail-open and injected with the existing Responses client.src/graph/path.ts: deterministic prerequisite-ancestor walk with a stable tie-break.src/graph/load.ts: fail-closed loader for the committed graph.scripts/emit-tinderbox.ts: deterministic, one-shot styled Tinderbox OPML with concepts, sources, typed edge records, prototypes, and graph-derived map positions;atomic-learning-graph.tbxis the styled native document for direct use in Tinderbox 11.8.src/ui/: static React interface over the embedded graph, with local-only interactions.scripts/verify-bundle.ts: post-build scan of emitted JavaScript, HTML and CSS; the shipped-bytes enforcement boundary for the no-network browser claim.
Relations live only in LearningGraph.edges[]. Provenance is quote-primary: normalized quotedText
must clear the shared strength floor and occur in exactly one resolved source, while offsets remain
non-load-bearing hints.
Open educational resources are abundant but rarely tell a learner what must be understood first. The graph is a persistent, inspectable substrate. Once built, path routing is reproducible and auditable from the graph's content alone. Because the routing is a pure function over committed data, the same goal always yields the same route, on any machine, with the network unplugged.
In the reader, the graph surfaces as the evidence map — an optional view in which every concept ties back to a cited source passage. The lesson is the message; the map is the validation layer you summon when you want to check one. Opening it never changes your course.
Honest limits, stated up front:
- Readability is advisory, not solved.
READABILITY_HARD_FLOORis US grade 16 and only throws above that; grade 10 is an advisory that warns without blocking. The committeddata/atomicity-report.jsonrecords the real result: 5 of 10 concepts carry a low-confidence advisory, and the default goal (self-attention) is estimated at grade 10.96 (the worst issoftmax-orderingat 11.91). The floor is a build gate against runaway prose, not a promise of grade-8 English. Tightening it is a re-translation, not a config change. - The graph is small and the domain is narrow. 10 concepts across four source sections (three chapters). The pitch is the
substrate and the provenance, not coverage. The demo course is the math substrate under one LLM
mechanism (
self-attention), not an LLM survey. - This artifact is a prerequisite tree, not evidence of a relationship mesh. The graph type
supports
prereq,method, andrelated, but the pinned product run deliberately projects onto 9prereqedges and zero other links. No concept has more than one incoming prerequisite. A broader corpus and an explicit--no-spinerun are the next relationship-mesh experiment, not a promised outcome or new graph architecture. - Two alternate formats ship; infinite generation does not. The bundle embeds 20 validated
alternate renderings (
why-it-existsandhow-it-worksfor each of 10 concepts) with 64 cited steps. Their citations and run-log hash are gated. On-demand renderings remain in ROADMAP.md; the learned atomicity judge is opt-in advisory evidence, not a gate.
Code: MIT. Demo content and D2L source text: CC-BY-SA-4.0. OpenStax proof corpus: CC-BY-4.0.
The source code (src/, scripts/ and the build configuration) is licensed
MIT. Creative Commons recommends against CC licenses for software, and CC-BY-SA's
share-alike term requires adaptations of the licensed text to carry the same license, so the
boundary is drawn between the engine and the text it renders.
The lessons are adaptations of CC-BY-SA-4.0 material from Dive into Deep Learning by Aston Zhang, Zachary C. Lipton, Mu Li and Alexander J. Smola, translated into plain English at build time and modified from the originals. As adaptations of ShareAlike material, the lessons are themselves licensed CC-BY-SA-4.0.
Redistributed D2L text under data/oer/, and the same text embedded in data/graph.json, remains
under CC-BY-SA-4.0. The separate OpenStax source under data/corpora/openstax-physics/ remains
CC-BY-4.0; its adjacent README and manifest record attribution, modifications, license evidence,
revision, and hashes. The original project lessons and prose are licensed
CC-BY-SA-4.0.
For the D2L demo corpus, see NOTICE, DATA-LICENSE and ATTRIBUTIONS.md for per-source attribution, revision pins, license evidence, and modification notices.