Connect guided interactions to the tutor

Author: Doppp

CHANGELOG.md

@@ -6,6 +6,10 @@ All notable changes to `explorables` are documented here.
 
 ### Added
 
+- 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.
+
 - 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.
@@ -36,6 +40,9 @@ All notable changes to `explorables` are documented here.
 
 ### Changed
 
+- 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.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.

README.md

@@ -54,13 +54,14 @@ Agent Plugins-compatible clients discover the portable `start-course` skill. Cod
 
 ```bash
 explorables start [path]
+explorables tutor [--url <local-course-url>]
 explorables validate [path]
 explorables test [path]
 explorables build [path]
 explorables new <name>
 ```
 
-`explorables start` uses the strict default address `127.0.0.1:4173` so local resume state remains available. `--port <port>` is supported explicitly, but a different port has separate browser storage.
+`explorables start` uses the strict default address `127.0.0.1:4173` so local resume state remains available. `--port <port>` is supported explicitly, but a different port has separate browser storage. During an active guided session, the host adapter runs `explorables tutor` beside the server. It listens only to the local server's bounded semantic event stream so browser checkpoint actions can prompt the coding-agent tutor; it sends no analytics or remote learner data.
 
 From this source checkout, run the CLI as `pnpm exec explorables` or use the root scripts:
 

apps/site/playwright.config.ts

@@ -1,13 +1,16 @@
-import { defineConfig } from "@playwright/test";
 import path from "node:path";
+import { defineConfig } from "@playwright/test";
+
+const sitePort = process.env.EXPLORABLES_SITE_TEST_PORT ?? "4174";
+const siteUrl = `http://127.0.0.1:${sitePort}`;
 
 export default defineConfig({
   testDir: "./tests",
-  use: { baseURL: "http://127.0.0.1:4174" },
+  use: { baseURL: siteUrl },
   webServer: {
-    command: "pnpm site:dev --host 127.0.0.1 --port 4174",
+    command: `pnpm site:dev --host 127.0.0.1 --port ${sitePort}`,
     cwd: path.resolve(import.meta.dirname, "../.."),
-    url: "http://127.0.0.1:4174",
+    url: siteUrl,
     reuseExistingServer: !process.env.CI,
   },
 });

apps/site/src/main.tsx

@@ -125,7 +125,7 @@ function App() {
 
         <section className="section course-feature" id="course">
           <div>
-            <p className="kicker">Course 001 · thirteen foundation lessons</p>
+            <p className="kicker">Course 001 · sixteen foundation lessons</p>
             <h2>
               AI from
               <br />

docs/PRD.md

@@ -765,9 +765,10 @@ teaching:
 ```
 
 `tutor-led` makes the coding-agent conversation the live teaching surface. The browser defaults to
-the active checkpoint, explorable, evidence, and exercise, while complete lesson prose remains
-available through an accessible reference-notes disclosure. Omitting the profile preserves the
-ordinary browser-led rendering used by existing and standalone courses.
+the prerequisite bridge and foundational definitions followed by the active checkpoint,
+explorable, evidence, and exercise; worked explanations and recaps may remain in an accessible
+reference-notes disclosure. Omitting the profile preserves the ordinary browser-led rendering used
+by existing and standalone courses.
 
 The runtime exposes read-only `data-explorables-*` and `data-tutor-*` attributes for the visible
 lesson, Guided position, active checkpoint, checkpoint phase, mode, and persistence status. These
@@ -1019,6 +1020,8 @@ They allow:
 
 They are not sent to a remote analytics service.
 
+The trusted parent runtime may promote a small allowlist of semantic lesson and checkpoint events to the loopback course server so an actively listening coding-agent tutor can react. This local bridge must be bounded, versioned, process-memory-only, unavailable from static builds, and free of raw control telemetry. It must not call private host APIs or treat interaction as proof of understanding.
+
 Recommended event conventions:
 
 ```text
@@ -1544,11 +1547,15 @@ When asked to start the course, Codex should:
 1. Read `COURSE.md`.
 2. Verify dependencies.
 3. Run `pnpm course`.
-4. Open the local URL in the built-in browser.
-5. Inspect the visible lesson and checkpoint state and introduce that checkpoint in conversation.
-6. Teach the minimum prerequisite concepts, ask for a prediction, then direct the learner to use
+4. Run `pnpm tutor` in a second terminal and keep the tutoring turn open while waiting for its
+   semantic events during the active session.
+5. Open the local URL in the built-in browser.
+6. Inspect the visible lesson and checkpoint state and introduce that checkpoint in conversation.
+7. React to semantic browser checkpoint events without inferring understanding from a click.
+8. Teach the minimum prerequisite concepts, ask for a prediction, then direct the learner to use
    the browser activity and report its evidence.
-7. Move into exercise files only when referenced by the current lesson.
+9. Move into exercise files only when referenced by the current lesson, and stop the listener when
+   the session ends.
 
 Codex may activate the portable `start-course` skill or use `AGENTS.md` directly. Both paths must produce the same course behavior.
 
@@ -1567,10 +1574,13 @@ When asked to start the course, Claude Code Desktop should:
 
 1. Read `CLAUDE.md` and `COURSE.md`.
 2. Start the preview using `.claude/launch.json` or `pnpm course`.
-3. Open the local course in the Browser or Preview pane.
-4. Keep the preview beside the conversation where practical.
-5. Use file and terminal panes for exercises.
-6. Apply the same tutoring restrictions as Codex.
+3. Start the local tutor-event listener in a second terminal and keep the tutoring turn open while
+   waiting for its events during the active session.
+4. Open the local course in the Browser or Preview pane.
+5. Keep the preview beside the conversation where practical.
+6. React to semantic browser checkpoint events without inferring understanding from a click.
+7. Use file and terminal panes for exercises.
+8. Apply the same tutoring restrictions as Codex.
 
 Claude may activate the same portable `skills/start-course/SKILL.md` when its Agent Plugins integration supports it; `.claude/launch.json` remains a thin preview adapter.
 
@@ -1587,6 +1597,12 @@ No remote progress record is needed.
 
 The host must also honor the course-session language in section 6.4. Pausing flushes local browser progress before the host stops the local process. Reviewing does not roll progress back. Restarting from a checkpoint and resetting the course require explicit confirmation. Host conversation history may supplement the runtime state but is never the authoritative progress record.
 
+During active tutoring, the host runs `explorables tutor` against the loopback course URL and keeps
+the tutoring turn open while the learner works in the browser. A semantic browser event is new
+learner input: the host may acknowledge the action, address an explicitly saved response, direct
+the learner to the next current checkpoint, and resume waiting. The listener stops with the
+tutoring session. It does not make a static course page or an inactive host conversation autonomous.
+
 ## 16.5 Adapter principle
 
 Host-specific files must remain thin wrappers.

docs/architecture.md

@@ -97,9 +97,11 @@ Every locally persistent course also writes a smaller, versioned session record
 
 The visible session panel is the host-neutral continuity surface. The lesson root also exposes read-only `data-explorables-*` attributes for course/version, visible lesson, Guided position, checkpoint, mode, and persistence status. Neither surface can complete a checkpoint. Review navigation leaves the Guided position intact; a confirmed restart uses the reducer to delete the selected checkpoint and all later progress. The local server uses a strict port so it cannot silently move state to a different browser origin.
 
+While a local tutor is active, the trusted parent runtime publishes bounded semantic navigation and checkpoint events to an in-memory Server-Sent Events bridge on the same loopback server. `explorables tutor` consumes that stream in the host terminal. It excludes raw control events, applies size and shape validation, retains at most fifty process-local events for reconnection, and does not exist in a static build. The bridge does not alter browser progress, sandbox permissions, or the rule that interaction alone is not proof of understanding.
+
 ## Agent Plugin packaging and hosts
 
-Each distributable course root is an Agent Plugins v1 package. Root `plugin.json` declares portable identity and `skills/start-course/SKILL.md` is the single portable component. The skill locates the course root, reads `AGENTS.md` and `COURSE.md`, starts `pnpm course`, and then follows the active lesson. No MCP server is needed because the existing CLI and local files supply the workflow without another process or permission surface.
+Each distributable course root is an Agent Plugins v1 package. Root `plugin.json` declares portable identity and `skills/start-course/SKILL.md` is the single portable component. The skill locates the course root, reads `AGENTS.md` and `COURSE.md`, starts `pnpm course`, keeps `pnpm tutor` listening and the tutoring turn open while the learner uses the browser, and then follows the active lesson. No MCP server is needed because the existing CLI, local event stream, and course files supply the workflow without another permission surface.
 
 `AGENTS.md` remains the canonical host-neutral tutoring policy. Codex can read it directly or activate the portable skill. Claude Code Desktop retains a thin `CLAUDE.md` adapter and the officially supported `.claude/launch.json` preview configuration. Both open localhost, inspect the same active-state attributes, teach from the same Markdown, and run the same tests. No runtime package calls private host APIs.
 

docs/course-authoring.md

@@ -356,7 +356,7 @@ Keep tasks focused and deterministic. Include an edge case or intentional failur
 
 Put launch and tutoring policy in `AGENTS.md`. It must prohibit solving central starter files before an attempt and revealing protected paths. `CLAUDE.md` should contain `@AGENTS.md` plus only Preview-specific guidance. `.claude/launch.json` uses schema version `0.0.1`, runs `pnpm course`, and names the preview port. Do not put lesson content in host adapters.
 
-Keep `plugin.json` at the course root and target the canonical Agent Plugins v1 schema. Its `name` and `version` must match `COURSE.md`. Put portable startup instructions in `skills/start-course/SKILL.md`; its `name` must match the `start-course` directory, and it should read `../../AGENTS.md` rather than copy the tutoring policy. MCP is optional in Agent Plugins v1 and is not needed for an explorables course.
+Keep `plugin.json` at the course root and target the canonical Agent Plugins v1 schema. Its `name` and `version` must match `COURSE.md`. Put portable startup instructions in `skills/start-course/SKILL.md`; its `name` must match the `start-course` directory, and it should read `../../AGENTS.md` rather than copy the tutoring policy. During active tutoring the skill runs `pnpm tutor` in a second terminal, keeps the tutoring turn open, and reacts to its semantic browser events; raw explorable controls are deliberately excluded. MCP is optional in Agent Plugins v1 and is not needed for an explorables course.
 
 ## 8. Validate and publish
 

docs/decisions/0012-local-tutor-event-stream.md

@@ -0,0 +1,25 @@
+# ADR 0012: bounded local tutor event stream
+
+Status: accepted Date: 21 August 2026
+
+## Context
+
+Guided browser interactions update authoritative course progress, but the adjacent coding-agent tutor does not automatically observe a click. Read-only DOM attributes let a host inspect state during a turn; they do not notify an actively tutoring host when a learner completes a checkpoint, saves a prediction, restarts, skips, or navigates.
+
+Embedding a second model-backed chatbot would split the conversation, require credentials or a hosted service, and violate the product boundary. Calling private Codex or Claude APIs would make the course format provider-specific and fragile. Treating every raw explorable event as tutor input would also produce high-volume control noise.
+
+## Decision
+
+The local development server exposes an in-memory Server-Sent Events endpoint on the existing loopback origin. The main runtime publishes only bounded, versioned semantic events: lesson opened, checkpoint completed or restarted, lesson skipped, and mode changed. A submitted checkpoint response may be included because the learner explicitly intended it for course tutoring. Raw mouse, keyboard, slider, and render events are not forwarded.
+
+The `explorables tutor` command listens to that stream. Portable start-course skills and canonical tutor policies keep the listener running in a second terminal while the host is actively tutoring and treat each event as new learner input. The host responds according to the current checkpoint policy and never treats a click as proof of understanding.
+
+The bridge is loopback-only, process-memory-only, bounded, and absent from static builds. It writes no activity file, database, analytics record, or remote request. It does not call a private host API and cannot create a new host turn after the tutor has stopped listening.
+
+## Consequences
+
+- Browser checkpoints can prompt an immediate response from an actively listening Codex or Claude tutoring turn.
+- The same CLI and event contract work across hosts; adapters remain thin.
+- The tutor listener must remain active for automatic reactions. A static site or stopped listener preserves browser learning but cannot wake a host conversation.
+- Sandboxed explorable permissions and CSP do not change. Only the trusted parent runtime may publish to the same-origin bridge.
+- Event payload validation, byte limits, an in-memory replay buffer, and tests bound the local surface.

docs/implementation-plan.md

@@ -248,3 +248,20 @@ state why training is a separate activity before entering gradient descent.
 
 Exit check: the full check/build/course/browser/site matrix passes; the pull request is merged only
 after required CI is green.
+
+## Milestone 15 — reciprocal tutor interaction and visible foundations
+
+Deliverables:
+
+- Add a bounded, versioned, process-memory-only loopback event stream for semantic lesson and
+  checkpoint actions, plus a CLI listener that host adapters keep open during active tutoring.
+- Publish learner checkpoint submissions, explorable checkpoint completion, navigation, restart,
+  skip, and mode changes without exposing raw control telemetry or weakening iframe isolation.
+- Keep the prerequisite bridge and foundational definitions visible in tutor-led lessons while
+  leaving worked explanations and recaps available as optional reference notes.
+- Cover the bridge, runtime publication, beginner content visibility, and learner/explorable event
+  sources with unit, browser, accessibility, build, and validation checks.
+
+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.

docs/implementation-status.md

@@ -1,6 +1,6 @@
 # Implementation status
 
-Updated: 20 August 2026
+Updated: 21 August 2026
 
 ## Completed
 
@@ -59,6 +59,8 @@ Updated: 20 August 2026
 - Integrated all five frontier-family views into the learner-facing Atlas alongside the exact tiny Transformer and GPT-2 baseline. A shared guided prompt asks learners to identify the changed information path, inspect its evidence label, and recognize which numerical comparisons the incomplete source freeze does not support.
 - Added a published-only GPT lineage: report-derived GPT-1 and GPT-3 configurations complement the GPT-2 code baseline, while GPT-4 presents the technical report's explicit architecture-withholding boundary as an undisclosed interior. Later product names are not used to infer topology.
 - Completed Model Atlas hardening and documentation: the PRD, architecture, authoring guide, course roadmap, changelog, security model, actual catalogue bundle budget, responsive browser interaction, semantic fallback, and full repository checks now cover the feature. Redundant inline runtime source maps were removed after measurement showed they dominated compressed iframe size; compile diagnostics retain source locations.
+- Added a bounded in-memory loopback tutor event stream and `explorables tutor` listener. First-party and scaffolded tutor adapters now keep that listener active so lesson navigation and checkpoint completion, restart, skip, and mode changes can prompt the adjacent coding-agent tutor without private host APIs, raw interaction telemetry, accounts, or a second chatbot.
+- Made the tutor-led lesson setup and foundational definitions visible beside the conversation instead of hiding them inside collapsed reference notes. The existing three-lesson beginner runway defines AI, machine learning, models, data, parameters, training, inference, generative AI, language models, LLMs, and model-versus-product boundaries before gradient descent.
 
 ## Current work
 
@@ -90,6 +92,7 @@ learner-study evidence also remain.
 ## Latest verification
 
 ```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)
 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)