vibe64 0.1.35 → 0.1.37

package/docs/colleague-usage/learning-with-colleague.md

@@ -1,218 +1,197 @@
-# Lessons: Main teaches, Colleague supervises
+# Lessons: Colleague teaches
 
 For authoring and Git publication, read `lesson-authoring`. For pinned content
-and owner recovery, read `teaching-content`.
-
-## Asking Colleague about lessons
-
-Ask Colleague to list available courses or read your saved lesson; these reads
-change no project or progress. A direct start request or accepted offer authorizes
-reservation of that exact lesson and preparation of its declared exercise.
-Resume after interruption to retain the saved attempt. If preparation is
-unsupported, ask the owner to configure it, then retry that attempt.
-The yellow **L** and session panel attach Learning mode; read `learning-mode-ui`
-for controls and retained Working selection. Main teaches the saved lesson.
-Colleague supervises selection, progress and authoring; its catalogue and execution
-refuse question preparation, quiz/practical grading and all five lesson visual
-operations, including old contracts. Missing Main support leaves teaching pending;
-start/resume does not prove its chat opened. An empty catalogue requires owner
-installation/enablement, never substitute content.
-
-Questions and diagrams continue in saved Main with Colleague's drawer closed.
-Opening Colleague grants no missing teacher/grading support. The return practical
-requires its actual drawer controls and your explanation to Main. Colleague can
-explain native observation facts/accepted steps from its context query; those facts
-are not a pass. Missing facts do not prove lost steps: ask Main to check the current
-question before repeating the practical.
-
-Colleague can start and control a watcher for the current learner task through its
-eye-button dialog while you continue using Main. Starting from a delivered question
-captures that exact question, attempt, content pin, project/session and initiating
-browser. For a task without a delivered question, name one bounded criterion. The
-separate Learning watcher is event-first and performs bounded code-only
-reconciliation; Colleague and Main do not check your activity, keep an AI turn
-open or repeatedly call a model. **Pause**, **Resume** and **Stop** remain explicit.
-Leaving the target or losing current authority pauses it, and Resume performs a
-fresh access check. Its allowlisted control/view/progress facts are status context
-only and cannot pass an assessment.
-
-A direct “Watch me while I do this” request lets Colleague start that same watch
-from the currently connected Learning task. A how-to question only explains the
-controls. Ask Colleague to read, pause, resume or stop it, or use the eye dialog;
-both paths update the same watch ID. Status includes the exact goal and target,
-latest observation time, last delivered-help receipt and any saved assessment
-outcome. Stop ends observation only, not Main, the lesson or the application.
-Polling grants no source, Git, publication, provider, account or other mutation
-permission. Unsupported in-app behavior must be reported as unobservable.
-
-After a confirmed relevant step or an explicit observed failure, polling can give
-the same saved Main teacher one bounded application update. Main waits if your
-current turn is still running, then may connect confirmed progress to the current
-criterion or offer one useful hint for the reported failure. The update is not
-shown as words authored by you, cannot answer a pending question, and cannot award
-a pass. Repeated identical evidence is coalesced, and merely being quiet or away
-does not trigger another teacher turn. Pause or Stop discards undelivered help.
-
-A no-exercise lesson stays reserved without a practice project or Workspace setup.
-Its Learning Main is a private teacher conversation; the fresh brief reports
-`lesson.exerciseRequired: false`. Supported Main quizzes assess accepted answers
-against the pinned rubric and save progress. Practicals require native observations;
-missing support leaves them incomplete. Keep practical/diagram readiness guards,
-and do not inspect/resume a nonexistent practice session. An unexpected exercise
-checkpoint requires explicit end/restart with progress retained, never silent repair.
-
-Saved `preparation.phase` is a checkpoint, not live setup status. If it remains
-`preparing`, finish the already-requested lesson with `lesson.resume` on that same
-attempt; rereading `learning.read` cannot advance it. `sessions.inspect` reports
-the reserved session's actual `workspaceSetupStatus`. Resume rechecks that setup
-and saves proven readiness before `question.prepare`. Do not claim still running
-or nothing broken from the checkpoint. Ready is not running App Preview.
-
-Before each start, read `vibe64.training.courses.list` in that supervisor turn
-and `vibe64.training.learning.read` for the current revision/attempt. Choose an
-enabled listed release/lesson; historical catalogue results may be obsolete.
-After refusal, reread both before explaining it. A disabled old release does not
-prove the current course unavailable. Never call rejection successful or reuse
-its request identity for another release.
-
-The catalogue's topic IDs identify pinned lesson content, not ordinary help
-topics. Do not pass them to `usage.guide.read`. After a successful start, read the
-exact returned attempt through `vibe64.training.teaching-brief.read`; that owner
-provides the teaching text, rubrics and diagrams. A missing help topic is not
-evidence that an installed course's content is missing. If the native brief or
-preparation actually fails, report that result and retain its exact saved target.
-Main receives the complete bounded teaching brief, including its rubric and saved
-results. It does not shorten a valid lesson to fit a smaller tool response. A brief
-that exceeds the teaching owner's 128 KiB bound is refused; retain the saved attempt
-and ask the content author to shorten the lesson rather than retrying an unchanged read.
-
-A host-enabled Main lesson diagram uses the existing Preview area's lesson
-**Presentation**. Read `learning-mode-ui` for its actual view choices; **App**
-requires a real prepared exercise. The application and diagram remain mounted
-while switching supported views.
-Hidden supported motion pauses; restoring a diagram does not automatically replay
-it. Diagram state and completion are display facts, not learner assessment evidence.
-A diagram component alone does not establish active teaching or completed
-narration. Require its actual Main/native and player receipts.
-
-
-For explicitly ending a lesson and continuing its retained pin in a fresh exercise, read
-[Lesson history and resume](learning-history.md).
-An explicitly started newer topic can retain passes for a lesson whose code and
-content hash are unchanged. Colleague reads the fresh brief's retained results and
-continues the remaining assessments; changed lesson content requires its own
-assessment. This never transfers another person's results or proves that a new
-practice project is running.
-
-Only the host-registered native assessment operation can save a pass, using the
-pinned rubric, admitted learner message and required observation. Colleague's
-agreement, diagram motion, opened views, provisional words and demonstrations
-are insufficient. Unavailable evaluation/cleanup leaves results unsaved for retry.
-After substantial help or demonstration, require an independent follow-up;
-there is no raw pass-writing control.
-
-Use host-registered **question.prepare** in the current interactive teaching
-turn after reading the exact brief/revision and finishing any diagram/audio cue.
-Record actual help; retries retain the same request ID. After success, the whole
-final reply must equal the returned question text without additions. **Prepared**
-is not delivered or passed: only that exact completed final reply in this chat
-establishes delivery, never progress text. No learner button is added.
-
-Failed preparation/staging retains the attempt and request for read/retry; never
-invent an ID to hide uncertainty. Historical questions without help/issued-revision
-provenance require explicit fresh preparation, not an assumption of no help.
-Later cue/pause checkpoints retain the question; replacement makes queued old
-answers stale. Saving/displaying a question neither accepts an answer nor grants
-evaluation/pass authority.
-
-A teaching cue binds one declared diagram transition to the actual final
-Main explanation, never a tool-progress sentence. Motion follows audible
-speech start; with sound off, **Continue** follows the finished transcript
-explanation. **Play diagram without sound** is an explicit recovery while sound
-has not started. The next cue/question waits for actual display and required audio
-completion. Hiding, stopping or reloading retires the cue; ask for an explicit
-repeat. These facts grant no assessment pass and do not start another assistant
-turn automatically. On phones the presentation opens in Preview with Colleague
-minimised, preserving its voice session and separate typed draft.
-
-
-When the host supplies the question owner, a typed Send captures the question
-actually delivered by the completed Main reply in that lesson chat. A saved lesson
-checkpoint or tool-progress sentence alone does not make a question available.
-Speech keeps the question captured when that utterance began, including while it waits behind a working reply or remains in review.
-Showing a newer question does not move those earlier words to it. A valid native
-admission retains the issued question and its recorded assistance with your
-actual message identity and the native question reply/output identity; this
-alone does not evaluate or pass the answer. A fresh chat does not reattach words
-to a question delivered in its archived history.
-
-You can keep talking or typing if that question was replaced or its pinned
-content is unavailable. The message remains an ordinary, ungraded conversation
-message; it is never assigned to the newer question automatically. An accepted
-message retry keeps its original receipt. Old questions without recorded issuance
-remain ungradable until the Main teacher explicitly prepares a new question.
-Operators apply required state upgrades with writers stopped before activation.
-Upgrades do not invent old question provenance or grade historical words.
-
-Native quiz evaluation uses only the accepted learner message in the current
-interactive Main teaching turn and its actually delivered question. Caller text,
-paraphrases, provisional words and unrelated history cannot substitute. The
-original restricted Helper evaluates the pinned rubric; the progress owner saves
-its feedback. Retrying the same submission reads its result before another
-inference; a new identity cannot bypass a consumed answer.
-
-Stopping the Main teacher or retiring its admitted turn cancels evaluation without a pass.
-Missing support, interruption, stale questions or failed saves remain unsaved
-and recoverable. Keep the attempt/question; practicals require observed evidence.
-A confirmed Helper setup failure needs its existing AI Accounts model routing
-configured before retrying. Unrelated history cannot be assessed; host support is required.
-
-
-### Practising the native workspace controls
-
-For workspace observations, application checks and practical assessment, read
-[Practical Learning exercises](learning-practical-exercises.md).
-
-## Course and lesson choices
-
-The prepared **Courses** pane displays the host's installed courses in their
-original order as cards with "N of M lessons complete" and a progress ring.
-**View course** shows each topic and its lessons in order, with readable lesson
-titles beside the exact lesson codes, course/topic releases and lesson hashes,
-and a **Completed**, **In progress** or **Not started** status read from saved
-progress. Opening a course does not install or enable content; the separate
-**Install a course** catalogue below the cards does, and Colleague may install or
-update an official catalogue course only on the person's direct request or
-accepted offer (see [Installing and updating Learning courses](learning-course-catalogue.md)).
-Disabled courses and draft lessons stay labelled and unavailable for a new start.
-A preview course can be started only by the workspace owner: `courses.list`
-reports `canTryPreviews`, the owner sees **Try preview**, and the server refuses
-anyone else's start (Colleague included, acting for that person) with **This
-preview course can be tried only by the workspace owner until it is released.**
-**Start** or **Try preview** on a card, **Start next lesson** or **Start lesson**
-on the course page requests that exact published lesson from an enabled release; opening a course alone never
-starts anything. A missing title reports **Lesson titles are unavailable**; use
-**Refresh courses**. This preserves the saved attempt and history and does not
-substitute an invented title or another lesson. The host's original lesson action
-must still authorize and admit it; unavailable support or a failed read is not a
-successful start. The owner's **New course** form is described in
-[Choosing lessons and Learning conversations](learning-mode-ui.md).
-
-**Resume saved lesson** requests only the displayed saved attempt. Its retained
-pin can be older than the currently enabled catalogue. This button is available
-only when the host actually supports resume, not merely because progress exists.
-Starting a different lesson requires explicitly ending the active saved attempt
-first: ask Colleague, which uses `lesson.end` and stops that lesson
-conversation's work while keeping its history (see
-[Lesson history and resume](learning-history.md)). The Courses pane has no End
-button and never ends a lesson for you.
-**Saved lesson history** remains read-only and visible independently of new-start
-or resume support. Ended history is not marked completed without an actual
-completion result.
-
-Assessment counts come from saved results, never chat, motion or selection.
-**Saved lesson identity** shows the saved commit/hash. **Refresh courses** rereads;
-loading/errors create or repair no state. Desktop/phone share wrapping, scrollable
-controls. Colleague can explain/offer supported start/resume; only a direct request
-or accepted offer authorizes it. Main teaches with supported Preview controls;
-if unavailable, retain the attempt and ask the owner. See `learning-mode-ui`.
+and owner recovery, read `teaching-content`. For pointing and "show me", read
+`learning-teacher-guide`.
+
+## Two conversations: Develop and Learn
+
+Vibe64 has two modes, switched with **L**: **Develop** (your own projects) and
+**Learn** (your practice projects). Colleague keeps a separate conversation for
+each, and the one you see always follows the mode:
+
+- **Develop** has your one Colleague conversation, with its read-only previous
+  conversations, watches and assignments, exactly as before. It does not teach:
+  ask it about lessons and it tells you to press **L** (it can switch for you
+  when you ask or accept its offer, with `learning-mode.set`).
+- **Learn** gives each lesson attempt its own teacher conversation. Leaving the
+  lesson (pressing **L**, or reading another lesson) and coming back resumes
+  that same conversation. Learn mode with no lesson in progress has one
+  conversation of its own. Restarting a lesson starts a fresh teacher.
+- Switching never interrupts Colleague: a reply it is writing finishes in its
+  own conversation, still on the projects of the mode it started in, which you
+  see again when you switch back. Watched agents
+  keep being followed while you are in Learn; their updates wait in Develop's
+  conversation until you return. **Start fresh** and **Previous conversations**
+  work within the conversation you are in.
+- In Learn, Colleague does not create assignments or watches; in Develop it does
+  not teach, read lessons or your teacher notes.
+
+## Colleague as your teacher
+
+In Learn mode, **Courses** (on the lesson step bar, or in the project menu beside **L**) is the catalogue
+where you choose and start lessons; your current lesson is read on the Learn
+page itself, in its **Lesson** tab beside Colleague (see `learning-environment`).
+You can read lessons yourself without AI. Choose **Teach me** on a lesson step,
+or ask Colleague about your lesson, and Colleague teaches the current step.
+**Teach me** opens Colleague beside the step and sends "Teach me this step.";
+the step stays on screen, so Colleague refers to it rather than repeating it.
+**I'm stuck** (in the lesson step bar, see `lesson-step-bar`, on a *do* line or a step its own check
+decides, and in the step beside **Teach me**, until the step passes) opens Colleague the same way and sends "I'm stuck on this
+step."; Colleague looks at where you are and helps you get unstuck. It never
+passes the step for you:
+
+- It reads your lesson with `lesson.read` (the steps in order with their text,
+  diagram, guide and check kind, plus your saved results) and explains the step
+  in its own words, by text or voice. Reading changes nothing. Long lessons
+  arrive in pages; Colleague reads every page before claiming a step's text is
+  missing.
+- It points at, or with "show me" opens, the real Vibe64 places the step uses,
+  replays the step's diagram, can show your current step in the **Lesson** tab,
+  and can open **Courses** or close it so you see the app. Courses keeps its
+  place while closed.
+- In Learn mode with a lesson in progress, Colleague's header shows a small
+  yellow **Step N/M** button (a check once the step passed). Pressing it shows
+  that step in the page's **Lesson** tab (see `learning-environment`); on a
+  phone Colleague's full-screen chat also minimises so the step is visible, and
+  its avatar button brings Colleague back. It appears on the desktop panel, the
+  phone's full-screen chat and during voice chat. Develop shows no step button.
+- Before asking you to press **Done**, answer a question or press **Check now**,
+  it looks at that step's saved result. A step that already passed is not asked
+  for again: Colleague says it passed and moves on to the next unpassed step.
+- It tells you in plain words what it opened or highlighted, without receipt
+  fields or IDs. If it could not open or point at a step's place (for example the
+  control is hidden), it says so plainly and describes the path in words.
+
+On a phone, Colleague's full-screen chat minimises itself when it opens Courses,
+shows a lesson step or rings a control, so you can see it; reopen Colleague with
+its avatar button. **Teach me** on a phone opens Colleague's full-screen chat
+over the Lesson tab, which stays underneath.
+
+## Colleague never judges
+
+A step passes only through your own action in the lesson:
+
+- **Choice question**: only your own answer counts. Colleague never sees or
+  reveals the correct option, sees only whether your answer passed (not which
+  options you chose), and cannot answer for you; it helps you reason instead.
+- **Self-check**: only your own **Done** records it.
+- **Reading step**: optional; only your own **Mark as done** records it.
+- **Automatic check**: when you say you have done a task, Colleague may run the
+  step's check (`step.check.run`) and tell you its actual result, but that run is
+  a diagnostic and is never saved. The step passes only when you press **Check
+  now**; a response check first needs your own press of the App's control in this
+  lesson's Preview.
+- **Review check**: the step shows its rubric, what your finished work must
+  show. Only your own **Check my work** asks your own AI (your Helper route in
+  **AI Accounts → Model routing**) to review your practice work against it;
+  Colleague never runs a review for you. A review answers **Passed** (final) or
+  **Not yet** with a comment and a hint. While the coding agent is still
+  working it says "Wait until the agent finishes"; with nothing changed yet it
+  says "No changes yet" without asking your AI; pressing again without new
+  work shows the same review. When the review cannot finish (no Helper route,
+  the provider failed, or the reply was unusable) nothing is recorded: fix the
+  cause and press it again.
+- **When you are stuck**: Colleague can read your practice work for the
+  current step (`step.evidence.read`): the files you changed since the lesson
+  started and their diff, the lesson's coding conversation when the step's
+  review uses it, the rubric and your last review. It uses this to help you
+  with the next move; reading it never passes a step.
+
+Colleague's feedback never changes a step's status. If Colleague says a step
+passed, ask it to read the lesson again: only a saved **passed** result counts.
+Your reading place is saved automatically. A change to your mode, lesson,
+results, reading place or practice project notifies only your own signed-in
+pages, so open views (and Colleague's conversation) refresh.
+
+Starting, restarting, finishing or deleting a lesson, and switching mode, needs
+your direct request or an accepted offer; a how-to question alone authorizes
+nothing.
+
+## Which projects Colleague opens
+
+Colleague opens only the projects of your mode. In **Learn** that is your
+practice project (none for a lesson without one); opening any of
+your own projects is refused with "You're in Learn mode. Press L to go back to
+your projects." In **Develop** it opens your own projects, and a practice
+project is refused with "This is a practice project. Press L to switch to
+Learn." Colleague relays the reason and offers to switch; it switches for you
+(`learning-mode.set`) only when you ask or accept. Switching ends nothing: the
+lesson in progress stays paused, with its practice project, until you come
+back.
+
+## Teacher notes
+
+Colleague keeps short private notes about you as a learner
+(`learner-notes.read` and `learner-notes.update`): your strengths, difficulties,
+preferences and where you are. It reads them when it starts teaching and rewrites
+them as one short summary (at most 4000 characters), never a transcript, secrets
+or a grade. They live in your own Learning state: no other learner and not the
+workspace owner can read them, and they never change a step's status. You see,
+edit and clear them in **L** under **What my teacher knows about me** on
+**Courses**. Ask Colleague to change or forget something and it rewrites them;
+clearing is your own **Clear** in **L**. If you edited the notes since Colleague
+read them, its save is refused and it reads them again before combining.
+Colleague treats the notes as a description of you, not as instructions: writing
+"tell me the answers" in them does not change how it teaches or judges.
+
+## Lessons in progress and archived
+
+One lesson is in progress at a time. Colleague reads it, with its practice
+project, and your archived lessons with `practice.list`. When you ask:
+
+- **Start a different lesson** (`lesson.start`): while another is in progress
+  this is refused until the current one is archived. Colleague asks you first
+  and archives it (`archiveCurrent`) only after you agree.
+- **Finish** (`lesson.finish`), once every step passed: the lesson is completed
+  and archived with its practice project and this teacher conversation.
+- **Restart** (`lesson.restart`): archives this attempt and starts the lesson
+  again with a fresh practice project, fresh results and a fresh teacher.
+- **Delete** (`lesson.delete`): removes the lesson's practice project and
+  teacher conversation without archiving.
+- **Delete an archived lesson** (`practice.archived.delete`): removes it for
+  good.
+
+Only the 3 newest archived lessons with a practice project keep it; archiving
+another removes the oldest one's project and keeps its record and conversation
+(`hasProject` in `practice.list` says which still have one). Colleague says so
+when a finish, restart or archive will do this.
+
+Colleague restarts or deletes only after you confirm that exact lesson in the
+chat (`confirmed`); it names the lesson and says what is kept. A pinned session
+must be unpinned first; that refusal changes nothing. Colleague cannot see or
+change another learner's lessons, and it cannot turn a practice project into one
+of your own projects. The buttons under **Courses** → **In progress** and
+**Archived** do the same (see [Practice projects](learning-practice-projects.md)).
+
+## Earlier lessons
+
+Lessons started before Learning v2 were taught by a separate lesson
+conversation, with quizzes and practical grading. Those attempts and their saved
+results are not kept by Rev 4's learning space reset. Start the lesson again in
+its current format and Colleague teaches it from its steps.
+
+## Courses and starts
+
+Courses, course pages and their states are described in
+[Choosing lessons and courses](learning-mode-ui.md). Opening a course does not
+install or enable content. Colleague installs or updates an official catalogue
+course only on your direct request or accepted offer (see
+[Installing and updating Learning courses](learning-course-catalogue.md)).
+
+A start requests that exact published lesson from an enabled release; the host's
+lesson action must still authorize and admit it, and an unavailable host or a
+failed read is not a successful start. A preview course can be started only by
+the workspace owner: anyone else's start (Colleague included, acting for that
+person) is refused with **This preview course can be tried only by the workspace
+owner until it is released.** A missing title reports **Lesson titles are
+unavailable**; use **Refresh courses**. Nothing substitutes an invented title or
+another lesson.
+
+**Open** on the lesson in progress returns to that attempt, whose pin can be
+older than the enabled catalogue. Starting a different lesson first archives the
+lesson in progress, after your confirmation (see
+[Lesson history and resume](learning-history.md)). **Saved lesson history** stays read-only and visible
+independently of start or resume support; ended history is not marked completed
+without an actual completion result. **Saved lesson identity** shows the saved
+commit and hash. Loading and errors create or repair no state.

package/docs/colleague-usage/lesson-authoring.md

@@ -4,7 +4,8 @@ Ask Colleague to coordinate a coding agent, review the lesson in the same sessio
 and publish its source through the existing Save or pull-request workflow.
 Colleague can operate those controls when requested; it does not edit files or
 run a shell itself. Git publication, pinned course material and installation are
-separate results. The current learner offering remains one introductory lesson.
+separate results. The current Getting started course has four step-based lessons
+(V64-START-00 to V64-START-03).
 
 ## Choose the authoring target
 
@@ -15,24 +16,22 @@ connection, repository access and Git author identity remain the person's normal
 account steps. Opening, creating or importing a new GitHub project uses the
 existing hosted UI; Colleague must not invent an import or source-access tool.
 
-For the current introduction, revise the existing V64-START-01 topic rather than
-exposing a second lesson. Preserve its permanent IDs, six assessments, actual App
-button/check correlation and declared SVG/controller protocol unless the person's
-request explicitly changes that content. New lesson content may be authored as
+To improve an existing lesson, revise it in its topic rather than exposing a
+duplicate lesson. Preserve its permanent lesson and step IDs, its declared checks
+(including the actual App button/check correlation) and its SVG/controller
+protocol unless the person's request explicitly changes that content. New lesson content may be authored as
 a draft using the existing template below; a draft is not another learner release.
 
-For the revised Learning flow, Main teaches the lesson and Colleague stays the
-general supervisor. Keep the introduction’s original Colleague leave/restore task:
-the learner uses that real drawer and returns to its retained task while the Main
-lesson stays saved. Hiding Main does not replace that practical. Review genuine
-workspace, application and diagram evidence before calling the candidate ready;
-content validation does not supply missing teaching controls. Changed teaching
+Colleague teaches every lesson from its steps in the Learning environment.
+Review genuine workspace,
+application and diagram evidence before calling the candidate ready; content
+validation does not supply missing teaching controls. Changed teaching
 text needs a new immutable topic/course pin, keeping earlier learners’ versions.
 
 ## Delegate and review
 
 For example: “In this lesson-authoring project and session, improve the introduction's
-wording, keep its six assessments and App/diagram contracts, validate and bundle it,
+wording, keep its step IDs, checks and App/diagram contracts, validate and bundle it,
 arrange a review, then publish the source as a draft PR. Do not install or enable it.”
 This is an example instruction, never authority to execute it without the person's
 actual request. A how-to question makes no edits, assignment or external write.
@@ -94,8 +93,28 @@ Vibe64 command. These authoring commands do not by themselves expose a learner c
 install a topic or start a lesson. Do not offer to start a course merely because
 its files validate.
 
-Use a topic repository whose name begins with `learn-`. Keep the teaching document,
-assessment rubrics, SVG descriptors and runnable exercise in that repository.
+Use a topic repository whose name begins with `learn-`. Keep the lesson
+descriptors, step texts, SVG descriptors, checks and runnable exercise in that
+repository. An exercise needs no `.gitignore` for Vibe64's agent guidance
+folders (`.agents`, `.claude`, `.codex`, `.opencode`): practice projects keep
+them out of the learner's changes by themselves. New lessons use lesson format v2 (`schemaVersion: 2`): optional
+notes and 1–32 ordered steps. Each step has a Markdown body a learner can read
+without AI, an optional diagram to play, and either an optional guide that
+points at a real Vibe64 place or a short `beats` block at the end of its text
+that the lesson step bar plays (show a place, wait for the learner to do
+something, offer the step's check; see "Beats" in `docs/training-content.md`),
+and one check: `auto` (a declared check against the
+learner's own exercise work), `choice` (multiple choice with an answer kept on
+the server), `review` (the learner presses **Check my work** and their own AI
+reviews their practice work against the author's rubric; it needs the
+exercise, and `evidence` may add the lesson's coding conversation to the
+changes), `self` (the learner presses **Done**) or `none` (reading only, never
+required; the learner may still press **Mark as done**). Check verdicts come
+from the declared check and are final; a review may pass a required step.
+Prefer an `auto` check where a deterministic check can decide, and write the
+rubric as what the finished work shows. Colleague never passes a step and
+never runs a review. Older v1 lessons (teaching document plus
+assessments) still validate for history but cannot be started.
 The installed `docs/templates/learn-topic/` directory supplies a copyable whole
 topic. The author copies it to a new directory, follows its README to choose
 permanent identifiers and replace placeholder content, then validates it. Its
@@ -113,7 +132,7 @@ These commands use that session's existing filesystem and Git access. Keep the
 inputs and outputs within the authorised authoring assignment. They do not grant
 Colleague source access or permit a coding agent to install or enable courses.
 Success lists ordered lesson hashes and distinguishes published lessons from drafts.
-A failure means the author must correct the reported schema, reference, rubric or
+A failure means the author must correct the reported schema, step, check, reference or
 path problem; it does not change their project or learning history.
 
 To produce local release material, the author runs
@@ -168,9 +187,9 @@ operator steps below remain for content outside that catalogue, for an author's
 own snapshots, and for disabling a release.
 
 In supported hosted installations, ask Colleague to admit your exact clean
-committed snapshot from the authorized authoring session. Then turn on Learning
-mode in that project view and use **Resume author trial** under **Courses** to
-open its same Main teacher. This saved trial has isolated progress; it is not an
+committed snapshot from the authorized authoring session. Then open Learning with
+**L**; on its **Courses** tab the **Author trial** card shows the snapshot's lesson
+and release, and **Resume author trial** opens it in the ordinary lesson reader, the page's **Lesson** tab. This saved trial has isolated progress; it is not an
 enabled learner course. Ordinary **Start** still requires a published lesson in
 an enabled release. Local validation/bundling alone admits no trial. Do not change
 a draft's status to bypass that guard or report a trial as published progress.
@@ -199,13 +218,11 @@ then reads the fresh installed catalogue before changing enablement. Colleague c
 list the resulting enabled course through its normal learning query after the
 operator completes this step; absence is not permission to fabricate a substitute.
 Existing attempts keep their saved pins. Source publication alone does not prove
-installation, learner delivery, assessment completion or pilot acceptance.
+installation, learner delivery, step completion or pilot acceptance.
 
-Question delivery keeps its exact lesson attempt attached to your answer. An
-unfinished question or one retained from an earlier fresh conversation does not
-become a new assessment. Switching the displayed Preview is not permission to
-move an answer or a diagram checkpoint into another lesson's progress. The
-saved trial control uses the original snapshot admission and explicit refresh
+Each step result stays attached to its exact lesson attempt. Switching the
+displayed Preview or project is not permission to move an answer or a check
+result into another lesson's progress. The saved trial control uses the original snapshot admission and explicit refresh
 operations described above. Edited source requires a deliberately ended old trial
 and a newly admitted committed snapshot; Resume keeps the existing pin.