Merge pull request #20 from Doppp/codex/ai-101-terminology-v2

Teach AI terminology before the first prediction

Author: Doppp

AGENTS.md

@@ -41,8 +41,14 @@ When acting as a learner's tutor:
 - Treat lesson Markdown as the canonical subject record. Teach from it conversationally and direct
   the learner to the browser's reference notes for durable definitions, worked examples, and recap.
 - Check only the prerequisite vocabulary needed for the active checkpoint. Explain a missing term
-  briefly, then return to the lesson; do not make chat the only source of a core concept.
-- Ask the learner to predict in chat before revealing outcomes.
+  with a definition, example, and nearby non-example, then return to the lesson; do not make chat
+  the only source of a core concept.
+- Treat `prepare` and `check` phases as prerequisites for prediction. Ask one concrete recognition
+  question, and do not advance while the learner cannot interpret the checkpoint's words.
+- Ask the learner to predict in chat only after the prerequisite vocabulary is usable.
+- Distinguish model inference, repeated generation, and product-level reasoning. Treat generated
+  step-by-step text as output to verify, not a guaranteed private computation trace or proof of
+  correctness.
 - Direct them to manipulate the explorable.
 - Inspect `data-explorables-*` and `data-tutor-*` browser state when available so the conversation
   stays aligned with the active lesson and checkpoint.

CHANGELOG.md

@@ -9,7 +9,15 @@ All notable changes to `explorables` are documented here.
 - A bounded loopback tutor event stream and `explorables tutor` listener so lesson navigation and
   checkpoint actions in the browser can prompt the adjacent coding-agent tutor during an active
   session without analytics, accounts, raw control telemetry, or private host APIs.
-
+- A six-lesson AI 101 runway that teaches course vocabulary, software inputs and outputs, rules and
+  learned models, classification and generation, language models and products, training and
+  inference, and inference, generation, and reasoning before mathematical machinery.
+- A course-local learner glossary with stable beginner definitions and later refinements.
+- Optional `prepare` and `check` checkpoint phases for terminology orientation and concrete
+  recognition before prediction.
+- A visible tutor-led prerequisite surface backed by canonical lesson Markdown, plus two accessible
+  sandboxed activities for software-component and reasoning-path boundaries.
+- ADR 0013 and an expanded consented learner-study protocol for the zero-ML-vocabulary audience.
 - Opt-in `teaching.mode: tutor-led` presentation: the coding-agent conversation leads the live
   lesson while the browser defaults to checkpoint, explorable, evidence, exercise, and collapsed
   reference notes. Stable `data-tutor-*` state keeps host inspection provider-neutral.
@@ -42,7 +50,12 @@ All notable changes to `explorables` are documented here.
 
 - Tutor-led lessons now keep prerequisite bridges and foundational definitions in the main lesson
   flow; only worked explanations and recaps remain in the optional reference-notes disclosure.
-
+- `AI from First Principles` is versioned as `0.7.0-ai-101.1`, now contains nineteen lessons, and
+  starts with terminology rather than an unsupported classification question. Its new progress
+  namespace leaves prior browser-local progress untouched.
+- Tutor policies now require a definition, example, non-example, and recognition check for missing
+  prerequisite vocabulary. They distinguish inference, generation, reasoning, and product
+  orchestration without treating generated explanations as private computation traces.
 - `AI from First Principles` is versioned as `0.6.0-tutor-led.1`, now contains sixteen lessons, and
   uses Codex/Claude conversation as the primary teaching surface. Its browser-progress namespace is
   intentionally fresh; earlier local progress remains untouched under its prior course version.

apps/dev-preview/src/styles.css

@@ -1037,6 +1037,23 @@ pre {
   background: var(--blue);
 }
 
+.checkpoint-prerequisites {
+  margin-block: var(--space-4);
+  padding: clamp(1rem, 2.5vw, 1.5rem);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-lg);
+  background: var(--surface-raised);
+}
+
+.checkpoint-prerequisites > .eyebrow,
+.checkpoint-prerequisites > h2 {
+  margin-top: 0;
+}
+
+.checkpoint-prerequisites .lesson-fragment > h1:first-child {
+  display: none;
+}
+
 .tutor-handoff .eyebrow,
 .tutor-handoff h2,
 .tutor-handoff p:last-child {

docs/PRD.md

@@ -805,6 +805,19 @@ For a lesson that introduces a foundational concept, the Markdown must also prov
 - at least one deliberate failure and the invariant it violates; and
 - a concise recap or self-check that asks the learner to explain rather than merely recognise.
 
+For a declared zero-domain-knowledge audience, prerequisite terminology is itself an instructional
+objective. Define each required term in plain language, give a concrete example and a nearby
+non-example, and ask a recognition question before asking for a prediction. Tutor-led presentation
+must keep this prerequisite material visible on the activity surface; it must not require the
+learner to discover essential definitions inside collapsed reference notes. Courses may use
+optional `prepare` and `check` checkpoint phases before `predict` without adding a Markdown
+directive or a second progress store.
+
+AI courses must distinguish training, inference, generation, and reasoning. “Reasoning” describes
+problem-solving behaviour that may span model inference, repeated calls, product orchestration,
+and tools. Generated step-by-step prose is output to verify, not guaranteed evidence of private
+model computation or correctness.
+
 This contract does not imply a minimum word count or rigid heading vocabulary. Automated validation
 continues to check structure, paths, fallbacks, and executable contracts; editorial review and
 learner playtesting determine whether the explanation is sufficient for the declared audience.
@@ -2793,7 +2806,8 @@ See how it works. Build it yourself.
 - [ ] The reference course begins with a plain-language learning-loop orientation before gradient
   descent or other mathematical machinery.
 - [ ] Before the learning loop, a beginner can distinguish AI, machine learning, generative AI, an
-  LLM, and a chatbot product, then trace one autoregressive next-token step.
+  LLM, and a chatbot product; separate training, inference, generation, and reasoning; then trace
+  one autoregressive next-token step without relying on undefined AI terminology.
 - [ ] At least five target learners complete two lessons.
 - [ ] Setup failures and authoring friction are documented.
 - [ ] Feedback informs the v1 format before the full course is produced.

docs/course-authoring.md

@@ -192,6 +192,17 @@ Before the prediction, give the learner:
 - plain-language definitions for every new term or symbol needed to make the prediction; and
 - a small, concrete setup whose values can be inspected by hand.
 
+For a zero-domain-knowledge audience, use `prepare` and `check` checkpoints before `predict` when
+the learner must acquire terminology first. `prepare` establishes the definition, example, and
+non-example; `check` asks a concrete recognition question. These phases use ordinary lesson
+Markdown and the existing checkpoint schema, not a custom directive. A prediction must test
+reasoning from the supplied setup rather than prior familiarity with the vocabulary.
+
+When authoring AI material, distinguish model inference, repeated generation, and reasoning that
+may span product orchestration or tools. Generated step-by-step prose is an output that can be
+checked; do not describe it as a guaranteed faithful transcript of private model computation or as
+evidence that the answer is correct.
+
 After the interaction, include:
 
 - an explanation that connects the observed values to the formal mechanism;

docs/course-roadmap.md

@@ -121,13 +121,13 @@ These are separate course packages with separate `COURSE.md` files. They share t
 Status: complete.
 
 - Deliver the v0.1 runtime and authoring format.
-- Complete the sixteen-lesson foundation course and tiny Transformer.
+- Complete the nineteen-lesson foundation course, including its six-lesson AI 101 runway, and tiny Transformer.
 - Verify deterministic training, generation, caching, evaluation, sandboxing, accessibility, and clean builds.
 
 ### Milestone 1 — guided course delivery
 
 - Add reusable opt-in checkpoints, ordered navigation, explicit skip/Explore controls, local resume state, and tutor focus rules.
-- Apply the complete guided loop to all sixteen foundation lessons.
+- Apply the complete guided loop to all nineteen foundation lessons.
 - Preserve unrestricted navigation for existing courses that do not opt in.
 
 ### Milestone 2 — course-family and source freeze

docs/decisions/0013-ai-101-prerequisite-checkpoints.md

@@ -0,0 +1,34 @@
+# ADR 0013: Make prerequisite vocabulary visible before prediction
+
+## Status
+
+Accepted
+
+## Context
+
+The first tutor-led beginner checkpoint asked learners to classify AI products before confirming
+that words such as classifier, label, learned model, generative, LLM, product, and boundary were
+usable. Canonical lesson Markdown contained definitions, but tutor-led presentation collapsed that
+prerequisite prose and foregrounded the prediction. A programming-literate learner with no ML
+vocabulary could therefore be blocked at the first step despite matching the declared audience.
+
+## Decision
+
+Add optional `prepare` and `check` checkpoint phases. In tutor-led courses, render the canonical
+lesson introduction—including vocabulary, examples, non-examples, and worked setup—on the activity
+surface before the active checkpoint. `prepare` records vocabulary orientation; `check` records a
+concrete recognition task; prediction follows only after those prerequisites are complete.
+
+Keep definitions in ordinary Markdown and add no custom directive, second progress store, account,
+grading system, or private host bridge. Teach inference, generation, and reasoning as distinct
+terms. Generated reasoning prose is observable output to verify, not guaranteed access to private
+model computation or proof of correctness.
+
+## Consequences
+
+- Tutor-led pages carry more prerequisite prose in the activity surface, but learners no longer
+  need to discover essential definitions inside collapsed notes.
+- Existing courses and checkpoints remain valid because both phases are optional.
+- Discovery-cycle validation continues to require predict, experiment, apply, and reflect in order;
+  prepare and check may precede them.
+- Instructional sufficiency still requires editorial review and consented learner playtesting.

docs/implementation-plan.md

@@ -265,3 +265,26 @@ Deliverables:
 Exit check: completing learner and explorable checkpoints emits semantic events the adjacent tutor
 can react to; the first lesson visibly defines its core vocabulary before the prediction control;
 and the full repository verification matrix passes.
+
+## Milestone 16 — AI 101 terminology and supported reasoning
+
+Deliverables:
+
+- Publish a course-local terminology register with stable beginner definitions, refinements,
+  prerequisites, examples, non-examples, and misconception boundaries.
+- Replace the compressed opening with a short beginner runway covering software inputs and
+  outputs, rules and learned models, classification and generation, language models and products,
+  training and inference, and inference, generation, and reasoning.
+- Require recognition checks before predictions in foundational lessons and make prerequisite
+  vocabulary visible in the tutor-led activity surface rather than only in collapsed notes.
+- Teach reasoning as observable problem-solving behaviour that may span model inference, product
+  orchestration, and tools; do not present generated explanations as faithful private computation
+  or as proof of correctness.
+- Update the host-neutral tutor policy, authoring guidance, validator coverage, browser tests,
+  learner-study protocol, PRD, implementation status, and changelog.
+
+Exit check: a programming-literate learner with no AI vocabulary can progress through the runway
+without external definitions, distinguish classification from generation, distinguish a model from
+its product, separate training, inference, and generation, and give a cautious explanation of
+reasoning. Automated checks verify instructional order and accessibility; the existing five-learner
+study remains required external evidence before the curriculum claim is considered validated.

docs/implementation-status.md

@@ -4,6 +4,10 @@ Updated: 21 August 2026
 
 ## Completed
 
+- Added the `0.7.0-ai-101.1` terminology correction: a course-local glossary, six-lesson beginner
+  runway, visible prerequisite surface, `prepare` and `check` phases, software-pipeline and
+  reasoning-path explorables, host-neutral tutor policy, authoring guidance, ADR 0013, and focused
+  schema/browser coverage. External learner validation remains explicitly pending.
 - Read the complete PRD and build assignment.
 - Verified authenticated SSH GitHub access as `Doppp`.
 - Verified `Doppp/explorables` is public and defaults to `master`.
@@ -66,7 +70,7 @@ Updated: 21 August 2026
 
 The v0.1 runtime MVP remains verified. Course-session continuity now provides a framework-owned resume surface, lesson-level local state for persistent courses, Guided checkpoint resume and confirmed rollback, page-exit flushing, storage-failure messaging, host-neutral state attributes, shared lifecycle language, and a stable strict development origin. Model Atlas implementation, local hardening, clean-checkout verification, and pull-request CI are complete.
 
-`AI from First Principles` `0.6.0-tutor-led.1`, Guided Course Mode, Agent Plugins v1 packaging, the
+`AI from First Principles` `0.7.0-ai-101.1`, Guided Course Mode, Agent Plugins v1 packaging, the
 general local course library, course overview, and contextual discovery flow are implemented. The
 library presents the shared frontier core and DeepSeek, Kimi, Qwen, MiniMax, and GLM
 specializations as planned rather than runnable. Its DeepSeek and GLM cards reflect the V4 and 5.2
@@ -93,6 +97,7 @@ learner-study evidence also remain.
 
 ```text
 21 Aug reciprocal tutor + visible foundations pass (format/lint/typecheck, 38 suites/113 tests, collection and minimal validation, all builds, 20 course suites/61 model tests, 14 starter/reference exercise pairs, 18 browser tests including learner/explorable tutor events, visible definitions, responsive layout, and axe, plus 2 site tests and live loopback-listener verification)
+27 Aug AI 101 terminology runway       pass (clean pnpm 11 worktree after latest-master reconciliation: format/lint/typecheck, 38 suites/113 tests, collection/minimal validation, all builds, 20 course suites/61 model tests, all 14 starter/reference exercise pairs, 18 browser tests on an isolated port including prerequisite progression/tutor events/19-lesson progress/theme/narrow layout/axe, and 2 site tests)
 20 Aug tutor-led LLM runway           pass (clean pnpm 11 worktree: format/lint/typecheck, 36 suites/109 tests, collection and minimal validation, all builds, 20 course suites/61 model tests, 14 starter/reference exercise pairs, 17 browser tests including tutor state/reference notes/ordered-list containment/320px/axe, and 2 site tests)
 20 Aug course orientation              pass (clean Node 24/pnpm 11 worktree: format/lint/typecheck, 34 suites/105 tests, collection and minimal validation, all builds, 18 course suites/57 tests, 14 starter/reference pairs, 16 browser tests including overview/contextual order/320px/axe, and 2 site tests)
 20 Aug compact library hero          pass (16 browser tests; 320×700, 720×800, 900×700, 1100×760, and 1427×900 geometry; light/dark in-app Codex visual QA; scoped format/lint, typecheck, 33 suites/102 tests, validation, and all builds)

docs/research/beginner-llm-curriculum.md

@@ -41,15 +41,22 @@ decisions remain governed by `docs/PRD.md`.
 
 ## Resulting sequence
 
-1. Generative AI and language models
-2. The next-token loop
-3. How machines learn: training versus inference
-4. Gradient descent and backpropagation
-5. Vectors, losses, and optimisation
-6. Tokenisation and numerical representations
-7. Attention and Transformer blocks
-8. Next-token training, inference, caching, and sampling
-9. Evaluation and leakage
+1. Course vocabulary and recognition-before-prediction
+2. Software inputs, outputs, components, rules, and learned models
+3. Classification, generation, language models, and products
+4. The next-token loop
+5. How machines learn: training versus inference
+6. Inference, generation, reasoning, and product orchestration
+7. Gradient descent and backpropagation
+8. Vectors, losses, and optimisation
+9. Tokenisation and numerical representations
+10. Attention and Transformer blocks
+11. Next-token training, inference, caching, and sampling
+12. Evaluation and leakage
+
+The added terminology runway follows learner feedback that the earlier first checkpoint still
+assumed the meanings of classifier, label, learned model, product boundary, inference, and
+reasoning. The correction treats those terms as course content, not as a diagnostic prerequisite.
 
 The sequence is intentionally spiral-shaped: the learner first sees the complete next-token loop,
 then revisits each component with more mathematical and implementation detail.