Concept map

A lesson's concepts and their prerequisite links, with where you stand on each. The map answers three questions during a lesson: where do I come from, where am I, what comes next. Exported, it becomes a page you can explore: open a concept to see the questions you went through, who assessed each answer, and what the teaching of that concept rests on.

The map states what happened in the session. It does not certify that a concept is learned, and it does not check whether a source is right.

What a state means

State Meaning
acquired Your latest assessed answer on the concept is right, or the session credited it as a prerequisite
to review Your latest assessed answer on the concept is wrong
current The scene on screen belongs to this concept
seen, not yet assessed You went through scenes of the concept, and no key or judge assessed an answer
upcoming Not reached yet

States come from session facts: the scenes served, the answers assessed, the prerequisites credited. The state field of get_workflow_graph reads estimated mastery instead and serves another purpose.

In the conversation

The lesson shows the map at a few moments, not on every question: when it opens, at a detour through a prerequisite and on the way back, on a scene that draws on several concepts, and at the end. When a new concept opens, one line says where you are. Ask for the map at any time: your assistant calls get_workflow_graph and shows concept_map. A harness that draws diagrams can render concept_map.mermaid.

In the lesson panel

In the lesson panel and in the Claude Code pane, « Concept map » opens the map as a list under the scene. Nothing is submitted and the scene stays where it is. Each concept says its state in words and what it needs first. « Evidence and scope » shows what the state establishes, what it does not, and the answers behind it: the day, who assessed the answer, the result and the hints taken. Where a concept can be checked, a button states your claim (« I know it » or « I am not sure »): the lesson then asks one or two check questions and says what they showed. A question whose answer you have already been shown is not asked again: when only such questions are left on a concept, it cannot be checked again in this lesson. A concept the session has not shown yet cannot be contested until it is reached. Your claim alone changes nothing. « Close the map » puts the list away. The panel does not draw the graph; the exported page below does.

Export an interactive page

Ask your assistant to export the map. It calls export_concept_map, which writes a record under your library (<STUDIUM_HOME>/library/_exports/concept-maps/) and returns its path and SHA-256. Then, from the repository root:

.venv/bin/python tools/concept_map_report.py export RECORD.json reports/concept-map --expect-sha256 SHA256
.venv/bin/python tools/concept_map_report.py verify reports/concept-map

Open reports/concept-map/index.html. The page needs no network and no server. Your assistant's procedure for all of this is the studium-concept-map skill (Skills).

On the page What it does
A concept of the graph Opens its panel: prerequisites, your steps, sources, trace nodes
A step of the session path Opens the concept of that step and highlights the step
Viewpoint: Learner Colours concepts by state; shows your steps and the path travelled
Viewpoint: Teacher Shows the structure, what each concept rests on and, when attached, the class figures
Concepts shown Dims the concepts of a state

The record holds no learner identifier and none of your words: results, not answers. For each answer it also keeps the day, the hints you took before it and whether you then rated your own recall, and, for each concept you contested (« I know it », « I am not sure »), what the check questions showed. It stays on your machine until you share the folder. forget_session does not delete exports; it names the folder so you can delete it yourself.

The exported concept-map page of a French chemistry lesson: on the left, the concepts as boxes linked from prerequisite to dependent concept, one acquired, one current, the rest still to come, with the travelled path drawn solid; on the right, the selected concept with what it requires, what it leads to, and each step the learner took on it, with the result and who assessed it.

The concept map exported after a session (synthetic learner): where each concept stands, and the answers behind it.

What a concept rests on

For each scene of a concept, the panel gives the kind of key (written by the author, a production compared with a reference, grounded by a run, or not graded), the sources cited and where each comes from: a web page, a publication, a supplied document, or a conversation with an AI assistant. A passage is quoted only once you have left the scene that cites it, because a passage can state the key of its question. The header says who drafted the lesson and whether a teacher validated this exact version (a lesson changed since its approval says so).

For a lesson drafted from a conversation, read learn with your assistant: what an assistant asserted there was not checked.

The teacher viewpoint and class figures

A teacher who wants the figures of a class on the map exports the class report with the teacher tool class_report, saves its JSON, and passes it (the JSON written by tools/class_report.py also works, run with --bundle path/to/lesson.json so its rows are named by concept):

.venv/bin/python tools/concept_map_report.py export RECORD.json reports/class-map --class-report class-report.json

Each concept then shows its success rate (over the graded answers, whose number is given when it is lower than the answers' own), hint reliance, calibration gap and mean time, and the concepts to reteach first are marked. Figures under the learner floor of class_report are not shown, and no individual figure exists in that report. The page still holds the session path of the record it was built from: for a page without any learner's path, export the record from a session just started.

Provenance files

File Standard Content
sources/concept-map-record.json Studium record The record the server wrote, copied unchanged
astra.yaml ASTRA 0.0.14 The record as a declared artifact, the choices made (state rule, passages quoted, class figures) and technical findings
trace/exploration_tree.yaml ARA 0.1.0 The session path: one node per step, one pivot per detour
course_provenance.myst.md MySTRA The same provenance as a readable page, with the map
report.json, checks.json Studium The summary and its limits; the digest of every file and the ASTRA validator's result

Your results stay in the declared record; they are never written as custom ASTRA fields. To read the package in the Observatory, point its course root at the parent folder, as for a learner report.

Verification recomputes the summary, the ASTRA document, the trace and both pages from the record, runs the installed astra-tools validator and checks every digest. The manifest is unsigned: it detects stale or changed files, and someone who can rewrite the whole folder can rewrite its digests too.

Limits

  • Whether a map helps learning has not been measured.
  • A lesson resumed after a server restart keeps its latest steps and their results (the saved history is bounded); who assessed each earlier answer and how the session routed are recorded only for the steps played since the restart.
  • Mermaid rendering in each harness was not checked by eye; the list form is always present.

View the source of this page on GitHub