Articles and Lessons¶
Mention turns each entry in an Audience's table of contents into two artifacts: an Article and a Lesson. They cover the same material and do different jobs. This page explains the division and why it exists.
Two artifacts, two jobs¶
| Article | Lesson | |
|---|---|---|
| Shape | One markdown document | A sequence of 5 to 9 exercises |
| Job | Consult what you already know | Come to know it |
| Written from | Your organization's facts | The Article, plus situations drawn from your sources |
| What it produces | A document to read | Graded attempts, per piece of material |
The short version: the Article is what you consult; the Lesson is what makes you know it.
An Article is the right shape for looking something up — faithful to your sources, and written to answer one kind of question well. It is the wrong shape for learning something for the first time. Nobody learns a procedure by reading eight paragraphs about it, and a member who has read an Article and a member who has not are indistinguishable to everyone, including themselves.
So the Article stays exactly as it was, and a Lesson is composed from it.
Four kinds of Article¶
A document that answers two different questions at once answers neither well. A set of instructions that stops to explain its own history loses the reader mid-task; a description of how something works that starts telling you what to do cannot be scanned for a single fact. So every Article is written as exactly one of four kinds, and Mention picks the kind before it writes a word.
| Kind | The reader is… | It gives them |
|---|---|---|
| Reference | mid-task, and needs one fact | A neutral description of how things are: thresholds, fields, states, who owns what. No instruction, no opinion |
| How-to | trying to finish something they already set out to do | The sequence that gets them there, including where it branches. No teaching, no background |
| Explanation | away from the work, and wants to understand it | Why it is like this: the context, the trade-offs, what was decided and what that ruled out. No steps |
| Tutorial | brand new, and has never done this | A guided first run down a single path, ending with something they can see they did |
The kind is chosen from the material, not from a setting you fill in. When Mention proposes your starting contents it decides which kinds your sources can actually support for each subject; when you write an entry yourself, it reads your brief and settles the kind from that. Either way you steer it the same way — through the prompt. A brief that asks how to do something gets a how-to; one that asks why something is the way it is gets an explanation. The Curriculum tab groups an Audience's entries by the kind each one settled on, so what a body of knowledge is missing is visible at a glance. See Curating Contents.
One subject can produce more than one entry. Refund policy is a reference (the approval thresholds), a how-to (processing a refund above the threshold), and an explanation (why the threshold is 48 hours). Those are three documents because they are three questions, and Mention proposes each one the material supports rather than making them compete for one slot.
How a Lesson is made¶
Once Mention finishes writing an Article, it composes that Article's Lesson automatically. One Article, one Lesson — there is nothing to commission separately and nothing extra for an owner to write.
The Lesson is authored from the Article rather than parsed out of it: Mention reads the finished document and writes exercises against what it says. Two rules govern where the material comes from.
- The Article is the only authority on what is correct. Every answer key and every rubric criterion is justified against it, so a Lesson can never grade you against something the Article does not say.
- Your sources supply the situations. Realistic scenarios and plausible-but-flawed artifacts come from your organization's own material, fictionalized — names and identifying details are replaced, because a Lesson is shown to a whole Audience.
When the Article is rewritten — a changed prompt, shifted source material — its Lesson is composed again from the updated document.
Not every entry affords a Lesson. Some material is genuinely inert — a page of links, a list of names with nothing that turns on them — and Mention says so rather than padding a lesson out; the entry keeps its Article and its Lesson shows as No lesson possible with the reason. That is a verdict, not an error — a Lesson only shows as failed when something actually went wrong composing it. Being a reference rather than a procedure is not what makes an entry inert: a reference is exercised by applying its facts, not by reciting them. See Curating Lessons.
What an exercise is¶
Every exercise has the same three parts: a setup (a situation or a question), the learner's attempt, and then the correction. Nothing is revealed before the learner commits, which means there is nowhere in a Lesson to put an explanation except after an attempt.
Exercises come in six kinds — a warm-up guess before being taught, deciding in a messy scenario, telling near-identical cases apart, critiquing a flawed artifact, reconstructing a procedure from memory, and explaining why a rule exists. They are graded two ways: picking from options, checked against an answer key, or writing prose, judged against a rubric of criteria. Passing a written answer means meeting every required criterion. The warm-up is never graded. See Working Through Lessons for what this feels like from the learner's side.
Roleplay is not a Lesson exercise but the Audience's final exam: one multi-turn conversation drawn across every Lesson once a learner has finished them all, sampling the material they hold most weakly and graded once at the end. A topic that falls down there drops back to the first review rung and falls due immediately. See Tracking Your Progress.
Which of the six a Lesson can use follows from its Article's kind. An exercise has to be answerable from the document it was composed from, and a reference contains no "why" to explain, while an explanation contains no procedure to run. Every kind opens with the warm-up guess. A reference is exercised by deciding against its facts, telling near-identical cases apart, and reconstructing what it lays out. A how-to uses all of those plus critiquing a flawed attempt at the procedure. An explanation is exercised by explaining, critiquing, and discriminating. A tutorial keeps to deciding and reconstructing its single path. This is also why review can bring material back as a different exercise than the one that taught it, but never as one the Article cannot settle.
Learn mode and Read mode¶
Which artifact an entry opens is derived from the member's progress, not chosen by anyone.
| Mode | Condition | What the entry opens |
|---|---|---|
| Learn | The Lesson isn't finished yet | The Lesson, one exercise at a time |
| Read | The Lesson is finished | The Article in full |
Neither mode withholds the Article. It is reference material a member may need before, during, or long after its Lesson, so it stays readable by its own link and read_article always returns the whole document. What the mode decides is which half the entry is asking for.
A Lesson is open book; review is closed book. Every exercise carries the passage of the Article it was composed from, and a learner may open it before answering at no cost — finding the right material and applying it is a competency, and it is the one a first pass practises. Whether the material stuck without the document is what review checks, so a review item carries no such passage.
This applies identically in the web app and through the MCP server. Modes describe what a learner is served. An Audience's owners are not learners in it, so they are not in either mode: they read every article they commissioned from the entry's page in Curriculum, regardless of progress, because they have none.
Mastery attaches to material, not to exercises¶
Every exercise declares the piece of material it exercises — "the 48-hour threshold for legal escalation" — and a learner's mastery is recorded against that, not against the exercise.
This is the choice that makes the rest work:
- It survives a rewrite. Rebuilding a Lesson after its Article changed keeps everyone's progress on the material that didn't change.
- It survives an edit. An owner swapping a recall exercise for a scenario over the same material resets nobody.
- It is the right key for review. What comes back is material you are shaky on, in whatever form suits it that day.
A learner has completed a Lesson when they have passed every piece of material it grades. Completion is taken back in exactly one case: a rewrite whose recomposed Lesson grades material the learner has never been asked about. Everything they already passed stays passed, and the entry asks them for the rest. Coverage that a rewrite removes never costs anyone their completion.
Review, and what "current" means¶
Completion is not the end state. A Lesson finished once and never revisited produces someone who knew something in March.
Mastered material returns on a fixed ladder — 1 day, 3 days, 7 days, 21 days, 60 days. Passing moves the learner up a rung; failing resets them to the first. Because mastery is keyed to material rather than to exercises, a review item can come back as a different kind of exercise than the one that first taught it.
That gives two different statements about a learner and an Audience, and they mean different things:
- Complete — they have finished every Lesson in the Audience.
- Current — they have finished every Lesson and nothing in the Audience is overdue.
Current is the honest number, and it is the first straight answer this product has been able to give to "does my team know this." It also means an Audience that is complete can stop being current. See Monitoring Progress.