vibe64 0.1.32 → 0.1.34

package/docs/colleague-usage/learning-code-questions.md

@@ -0,0 +1,55 @@
+# Answering a code question in a lesson
+
+This is part of [Choosing lessons and Learning conversations](learning-mode-ui.md).
+
+
+Some practice lessons ask you to change code, for example "make `notes.mjs`
+refuse an empty title". To answer:
+
+1. Choose **Dashboard**, then **Files** in the session tools. It is
+   the ordinary source editor for this lesson's practice project: the file list,
+   **New file at source root**, **Download file**, **Star file** and a file's
+   **⋮** actions menu (**Star file**, **Download file**, **New file here**,
+   **Copy path**) work as in any project. Files open as code; the **Interface**
+   view is not available in a lesson. **Explain** is shown but disabled; its
+   tooltip says to ask your lesson teacher in Learning. On a phone, use the files
+   button to show or hide the file list.
+2. Open the file the teacher named and edit it. Your changes save automatically
+   a moment after you stop typing; the editor shows when a save has finished.
+3. Choose the graduation-cap option beside **Preview** and **Dashboard** (on a
+   phone, the next-pane button labelled **Learning**) and press **Check my code** in the
+   code-check bar docked at the bottom of its **Courses** view (it stays in view while you scroll).
+   The button is there whenever a practice lesson is open; it checks only an open
+   code question. The lesson's declared check runs on a private copy of
+   the pinned exercise with your saved version of the named files. The result
+   appears in that bar: a green **Check passed** with "Your code passed the check…",
+   an amber **Not yet** with the check's reason (for example "Empty or blank titles are
+   still accepted", or that the check stopped after its time limit because the
+   code never finished), or a red **Could not check** saying what to do first. Fix the code and press **Check my code** again as often
+   as you like; only your latest check counts.
+4. After a passing check, explain to your teacher in Learning, in your own
+   words, what you changed and why. The teacher submits that explanation with the
+   check for grading. A pass is saved only when the check passed **and** the
+   explanation meets the lesson's rubric.
+
+What counts: only edits you saved yourself in the **Dashboard → Files** editor since the
+teacher asked the question. If anything else changed a named file in the
+meantime—the teacher or another assistant, a terminal command, Git, or another
+editor—the check does not run and reports "needs an independent attempt: other
+edits detected in `<file>`". That question cannot pass; ask the teacher for a new
+question and write the change yourself. The teacher is instructed not to edit
+those files or send solution code; it can give hints and point to lines.
+Checking never saves progress by itself, and a check without your explanation
+is not a pass. **Check my code** requires this lesson's Learning conversation
+to be connected in this browser. Every press either checks your code or shows
+why it could not in the line under the button: "This lesson's Learning
+conversation is not open here" (open the lesson conversation, then press again),
+"This lesson's Learning conversation is still loading its saved question" (wait
+until the Learning chat shows its messages, then press again), "There is no open
+lesson question yet" or a report that the question is not a code question (ask
+the teacher for the code question first), or "Earlier presses are still being
+handled" (wait, then press again). An asked, unanswered code question stays open
+when the server restarts or the page reloads, including the next day: open the
+lesson again and press **Check my code**; you do not need a new question, and
+your earlier saves in **Dashboard → Files** still count. Colleague can explain
+these steps but cannot type, save or check code for you.

package/docs/colleague-usage/learning-course-catalogue.md

@@ -0,0 +1,118 @@
+# Installing and updating Learning courses
+
+Learning mode can install courses from the official Vibe64 course catalogue
+straight from the **Courses** pane. Nobody needs a terminal for official
+courses.
+
+## Where it is
+
+1. Turn on Learning with the **L** button at the left of the header.
+2. The **Courses** pane shows your installed course cards first. Below them is
+   the **Course catalogue** section, headed **Install a course**.
+3. The catalogue is grouped by **topic** (for example **Vibe64**). Under each
+   topic, every course shows its title, release (for example `0.1.10`), a
+   **Released** or **Preview** chip, its lesson count and whether it is
+   **Installed**, **Not installed**, **Disabled by the owner** or has a
+   **Conflicting copy installed**. A topic without courses says **No courses in
+   this topic yet.** Courses whose catalogue entry names no topic are listed
+   under **Other courses**.
+
+When no course is installed yet, the installed area says **No courses are
+installed yet. Choose a course in the catalogue below and select Install.**
+
+On a phone the same sections stack in one column and each course's button
+fills the row width. On desktop the button sits at the right of the course.
+
+## Installing a course
+
+Select **Install** on a course that is **Not installed**. While it works, the
+button shows a spinner and the row reports each step: **Reading the official
+catalogue…**, **Downloading and verifying topic 1 of N…**, **Enabling the
+course…**, or **Waiting for another course installation to finish…** when
+another install is running. You can keep reading other parts of the page; other
+course buttons wait until it finishes.
+
+When it succeeds the course card appears among your installed courses and the
+catalogue row shows **Installed** with **View course**. Installing a course does
+not start a lesson.
+
+What the server does: it rereads the official catalogue, downloads each topic of
+that exact course release at the exact Git commit named in the catalogue's lock,
+verifies every file byte for byte against that lock, installs the verified copy
+and enables the course. It runs no course code. If anything does not match, it
+installs nothing new for that topic and enables nothing.
+
+Any signed-in person can install official catalogue courses. The catalogue
+location is fixed by the server, so the page can only install the courses it
+lists. Courses from other sources remain an owner/operator task (see
+[Author a lesson and publish its source](lesson-authoring.md)).
+
+### Preview courses
+
+A **Preview** course can be installed so that it is ready, and the row says
+**Preview course: it can be installed; until it is released, only the workspace
+owner can try its lessons from Courses.** Its installed card keeps the
+**Preview course** chip. The workspace owner (on local Vibe64, you) sees
+**Try preview**, which starts the lesson exactly like **Start**; everyone else
+sees the course with the note **Preview — the workspace owner can try it; it
+becomes startable when released** and no start button. Installing does not change
+this; once the course is released, everyone gets **Start**.
+
+## Updating a course
+
+When the catalogue has a newer release of a course you already have, the
+installed course card shows **Update available: <release>** with an **Update**
+button, and the catalogue row says **You have <old release>. Updating keeps
+your saved lessons and progress.** with the same **Update** button. Both run the
+same installation as **Install**, for the newer release.
+
+After an update:
+
+- The new release is installed and enabled, and new lessons start from it.
+- Older releases of that course are disabled **for new starts only**. They are
+  not deleted. Their old card is hidden from the list, except while you still
+  have a saved lesson in that release: that card stays, labelled **Disabled for
+  new lessons**, and **Resume saved lesson** or **Continue** still opens the
+  exact lesson you started. Lesson history is unchanged.
+- Progress carries over. A lesson whose content did not change keeps its
+  **Completed** status. A lesson whose content changed shows **Not started**
+  (or **In progress**) with the note **Completed in <old release> · updated
+  since**, so you can see you finished the earlier version. Completing the new
+  version records new progress; the earlier record stays.
+
+## Errors and recovery
+
+The message appears on the course row, and the button becomes **Retry install**
+or **Retry update**. Retrying repeats the same request safely; an already
+installed course is not installed twice.
+
+- **The official course catalogue … could not be downloaded** (shown in the
+  catalogue section, with **Retry**): the server cannot reach GitHub. Installed
+  courses keep working. Retry later or ask the operator to check the server's
+  internet access.
+- **Topic … could not be downloaded …**: the same network problem during
+  install. Nothing was enabled; retry.
+- **The official course catalogue is invalid …**: the published catalogue is
+  wrong. Nothing was installed; the catalogue maintainers must correct it.
+- **The owner disabled course … on this server**: shown as **Disabled by the
+  owner**. Only the workspace owner can enable it again.
+- **… already keeps 16 installed course releases, its limit**: every installed
+  or updated release uses one of 16 places and none is deleted automatically. Ask
+  the owner to free space; nothing was changed.
+- **Topic source or installed snapshot conflicts with the approved owner pin** or
+  **Conflicting copy installed**: the server holds different content under the
+  same release. Nothing is replaced automatically; ask the owner to inspect it.
+- **Installing courses from the catalogue is unavailable in this installation**:
+  this host has not enabled catalogue installation. Installed courses still work.
+
+**Refresh courses** at the top rereads installed courses, progress and the
+catalogue.
+
+## What Colleague can do
+
+Colleague can list the catalogue (`available.list`), explain each course's state,
+and offer to install or update a course. It installs or updates only after you
+directly ask for that course or accept its offer, using the same server action
+as the button, and it reports the real result. It cannot install courses from
+other sources, choose a different catalogue, delete releases or re-enable a
+course the owner disabled.

package/docs/colleague-usage/learning-diagrams-and-voice.md

@@ -0,0 +1,97 @@
+# Lesson diagrams and voice
+
+How lesson diagrams (the **Presentation** pane) and spoken teaching behave in a
+Learning conversation; see also
+[Choosing lessons and Learning conversations](learning-mode-ui.md).
+
+The original Preview host remains mounted beneath these choices. A saved practice
+workspace is reopened through its existing exact-session check before its outputs
+appear; a failure stays visible with **Retry workspace**. A declared diagram can
+open from Learning; covered workspace controls do not remain interactive.
+Switching views retains the App and diagram instances, the lesson picker, and
+Dashboard selections within that host. Hidden diagrams pause; returning does
+not replay their motion or count as a completed lesson. If sound is off, use the
+presentation's **Continue** only after its explanation is ready. A supported
+narrated diagram waits for its confirmed final explanation and actual sound and
+motion completion. Hiding or stopping it does not count as completed teaching.
+If its cue receipt was not confirmed, read the current status before continuing;
+do not assume the explanation or motion succeeded.
+When Main opens a lesson diagram, keep that same browser open until its operation
+is confirmed. Main opens it in that lesson's **Presentation** pane; opening the
+Colleague drawer is not required. If the browser did not acknowledge navigation,
+keep the initiating conversation open and check its current status before
+requesting another operation. If Main already finished with that failure, its
+message remains saved; read its result and your saved lesson progress before
+asking it to continue. Do not resend that completed message to recover navigation.
+Stop or a replacement Learning conversation retires its old
+explanation; an old confirmation cannot complete a new one.
+When Main opens a diagram in the practice project, wait for its confirmation;
+you do not need to request the diagram again while the view changes.
+This also applies with read-aloud off; opening voice first is not required.
+Wait for Main to confirm that the diagram is ready before continuing its
+illustrated steps.
+The whole diagram is scaled to fit its frame, centred, with its title above and
+the current step's caption below. **Minimise presentation**, the pill at the
+right of **Courses** | **Presentation** (below them on a phone), folds the
+diagram away; **Restore presentation** brings it back. After a page reload,
+**Presentation** stays unavailable until the teacher opens the diagram again,
+unless the diagram had already run a step or been paused (see below).
+
+Source-less Learning conversations select the graduation-cap option and disable Preview and Dashboard. A supported declared
+diagram can use the same Presentation player only in your exact saved lesson
+conversation; an empty picker or unavailable diagram cannot open it. This does
+not give the lesson repository, Save or Temporary AI/workspace access. A saved
+checkpoint does not mean a presentation is currently open. After a completed
+command or pause, the player saves its semantic state and labels. Reopening the
+same attempt restores its last confirmed state without replaying sound or motion.
+**Retry diagram checkpoint** retains an unconfirmed save identity; after a
+revision conflict, **Save current diagram** captures fresh state. Keep the player
+open until confirmation. Practice lesson diagrams save to that same lesson and
+Main conversation. A changed account, attempt or conversation retires its old
+handle; an error never grants a pass.
+
+To request teaching, open the exact saved Learning Main conversation and ask
+“Teach me this lesson.” Starting or resuming the lesson does not itself send that
+request. Main can use the lesson's declared diagrams in that same browser;
+Colleague remains available for general help and workspace supervision. Text
+teaching does not require voice, and private key entry remains your action.
+
+Lessons speak by default where this installation has a speech service. When the
+lesson conversation has loaded and read-aloud is on, Main's voice opens by itself and reads new replies aloud; earlier history
+is not replayed. The microphone stays off until you press **Talk**. Use the
+read-aloud button beside the avatar to mute replies; text continues in chat.
+If the browser reports **Sound is blocked**, choose **Enable sound**. Ending
+voice keeps it off for that lesson until you open it again or reload the page.
+Working conversations still start voice only when you choose it. Without a speech
+service, lessons stay text-only and quiet; **Continue** paces any diagram.
+
+If sound stops early, for example because the voice service could not be
+reached or you hid a narrated diagram, the diagram does not claim it finished.
+Choose **Continue** to go on without sound, or ask Main to repeat the
+explanation. Turning read-aloud off while it speaks stops the speech and leaves
+the diagram interrupted; turning it on again does not replay it. Your next message
+to Main is read aloud again once the voice service is available; you do not need
+to toggle read-aloud or reload.
+
+For a narrated diagram, keep the initiating browser and exact lesson conversation
+open until its operation is confirmed. Its explanation waits until Main has
+finished that turn. Stopping or interrupting an unfinished explanation prevents
+it from playing later when you ask a new question. With sound off, use
+**Continue** only after the explanation is ready. A visible diagram or saved
+state does not itself mean narration, motion or an assessment succeeded.
+
+Main confirms a diagram explanation from that turn's finished response before
+enabling **Continue**. Keep the same lesson and conversation open while it
+finishes. A stopped explanation or a response from a different turn cannot
+confirm the old diagram; read Main's current result before asking it to continue.
+The response may appear before **Continue** becomes ready; wait for its
+confirmation instead of resending that finished reply.
+
+If an operation is unconfirmed, read its current status before requesting a
+repeat. A reload or changed lesson/account cannot reuse an old cue confirmation.
+Switching the compact screen between chat and Preview retains the same active
+lesson; selecting a different session or account retires its old presentation.
+
+While a lesson’s narrated visual explanation awaits its final response, optional
+thinking and interim speech stay silent too. Your speech preferences remain saved;
+fresh confirmed replies use the same voice controls. This does not hide chat text.

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

@@ -1,14 +1,20 @@
 # Lesson history and resume
 
-Ask Colleague to resume the exact saved lesson after an interruption. Ending or
-restarting learning requires your request; it retains earlier progress and does
+After an interruption, choose **Resume saved lesson** (or **Continue** on its
+course) in Learning → **Courses**, or ask Colleague to resume the exact saved
+lesson; see [Choosing lessons and Learning conversations](learning-mode-ui.md).
+Ending or restarting learning requires your request to Colleague; it retains earlier progress and does
 not delete the practice project. These rules apply to desktop and phone.
 
 Explicit lesson retirement preserves the original pinned quiz and practical
-results. It does not stop, archive or delete the exercise. When the person
-requests disposal, use the existing authorised project/session Stop, close,
-archive and deletion workflow; do not claim disposal from an ended learning
-record. Leaving or hiding Colleague does not end the lesson.
+results. Once the end is saved, the lesson's teacher conversation stops: its
+running assistant work and session processes are stopped the same way session
+Stop does, because an ended lesson has no teaching instructions. The
+conversation stays readable in history, and the practice project and session
+are not archived or deleted. When the person requests disposal, use the existing
+authorised project/session close, archive and deletion workflow; do not claim
+disposal from an ended learning record. Leaving or hiding Colleague does not end
+the lesson.
 
 An admitted fresh start after retirement keeps the earlier evidence with its
 original identity. A lesson that declares an exercise uses a new exercise
@@ -32,9 +38,11 @@ content requires exact owner restoration, even when no lesson is active.
 
 When the installation supplies its lesson host, the shared `lesson.end` operation
 can retire the person's exact learning attempt after a direct request or accepted
-offer. State clearly that it retains the exercise and all history; the reason
-`discard` records a learning decision, not project disposal. Use existing separate
-Stop, close, archive or delete operations only when requested and authorised.
+offer. State clearly that it stops the lesson conversation's work but retains
+the exercise and all history; the reason `discard` records a learning decision,
+not project disposal. Use existing separate close, archive or delete operations
+only when requested and authorised. If the end reports that its stop was not
+confirmed, the end itself is saved; retry the same end request to finish the stop.
 An unavailable retirement host is not a successful end. The same tool is used on
 desktop and mobile; this addition creates no new layout control.
 

package/docs/colleague-usage/learning-lesson-watch.md

@@ -0,0 +1,95 @@
+# Watching a lesson step by step
+
+Colleague and the lesson teacher (Main) can show you places in a lesson, and
+Colleague can watch the steps you take; see also
+[Choosing lessons and Learning conversations](learning-mode-ui.md).
+
+You can ask Colleague to enter or leave Learning, show **Courses**, show the
+active lesson, or reveal the exact lesson project's normal **Preview** or
+**Dashboard → Database → ERD**. Main can reveal those same workspace views only
+for its bound active lesson, and can return to that lesson's Learning pane or
+open a visual declared by its pinned content.
+
+Main usually points you to these places instead of opening them; see
+**Learning teacher guide** (`learning-teacher-guide`). Both use the same initiating
+browser and wait for its actual settled mode, pane, session and attempt before
+reporting success. For a declared visual, confirmation follows the visual opening;
+the earlier Courses view is not its success receipt. This also applies when a
+saved lesson finishes loading after the chat first appears. If the lesson or
+visual changes while opening, the request is not confirmed; return to the intended
+saved lesson before requesting its visual again. On a phone, the request changes
+the same stacked panes; it
+does not open another app or conversation. Showing **Courses** does not start a
+lesson, leaving Learning does not end one, and any agent-opened view is a
+demonstration rather than evidence that you performed an assessed step.
+
+Use Colleague's eye button to manage polling for the lesson task currently open
+in this browser. If Main has delivered a lesson question, **Start polling** uses
+that exact question and pinned lesson, including its current practice project;
+you do not need to enter the project again. Otherwise, enter one bounded task in
+**Task to watch**, then start it. This also works for a lesson without a practice
+project, such as Lesson 0; its target then shows as a source-less lesson. The compact details dialog shows the task as
+**active**, **paused**, or **unavailable**, its exact target, and its latest
+structured observation and time, last delivered help, and any saved assessment
+outcome. Observations include switching between the practice project's
+**Preview**/**Dashboard** and the graduation-cap **Learning** option, and between project panes such
+as **Preview**, **Dashboard → Database** and **Dashboard → Files**;
+a view opened by Main or Colleague is recorded as their demonstration, not your step.
+The watch also notices when something you do inside the practice app fails: if
+you click or submit in the visible **Preview** (for example **Add note**) and the
+app's data-changing request then fails, the watch records **app-request** with
+only its method, a path the lesson declared (otherwise `other`), the HTTP status
+and a failure code (`http-4xx`, `http-5xx` or `network`). Main may then offer one
+hint; at most one such hint is offered every 30 seconds, and the same failure
+gets only one. Successful app requests, requests the app makes by itself, and
+anything while Preview is hidden (including behind the phone Colleague overlay)
+are not reported. This is the app's own claim, so it never grades or completes. Expand **Task criteria** below the watch controls to read the full
+criteria; long criteria stay collapsed so **Pause**, **Resume** and **Stop** remain
+easy to reach. You can instead tell Colleague “Watch me while I do this”; that direct
+request starts the same watch and the eye dialog shows the same state. Asking how
+polling works only gets an explanation. Ask Colleague to list, pause, resume or
+stop a watch when you do not want to use the buttons. **Pause** retains the cursor,
+**Resume** rechecks the current learner, lesson and browser before continuing,
+and **Stop** removes only the watch—it does not stop the app, Main or the lesson.
+Returning to another project, lesson or account pauses the old watch;
+after a server restart, return to the same Learning task and choose **Resume**.
+If you leave the task while **Start polling**, **Resume**, or an observed step
+is being checked, that request reports the changed task instead of activating
+the departed watch or queuing help for it. Return to the intended task before
+starting or resuming; repeat a step only after its watch is active.
+Polling follows the exact saved attempt, including an authorized author trial; it does not substitute the ordinary course progress for that task.
+If the lesson can no longer be read or access is lost, polling becomes
+**unavailable** and discards help that has not been delivered. After resolving
+the problem, **Resume** watches fresh steps; it does not replay that discarded help.
+Closing the initiating tab or losing its live connection pauses that tab's watch
+and discards pending help. Watches in other tabs keep their own state. Reconnecting
+registers your current view but leaves the watch paused: return to the intended
+task and choose **Resume**. Minimizing Colleague keeps the same connected task.
+Replacing or closing the watched Main conversation also pauses its old watch,
+even when the project and lesson remain selected. Switching only between that
+task's project panes and its Learning tab keeps polling active.
+After an application update, reload the page before starting or resuming polling.
+Start and Resume require the initiating browser's live connection. If it has not
+connected yet, wait for it to reconnect and then choose the control again; saved
+focus alone cannot start a detached watcher.
+The saved assessment outcome supports the watched outcome only when it is a pass
+for that task's referenced assessment. A pass from another assessment does not
+complete your task. A task you describe in your own words has no automatic
+assessment match; polling and help do not grade it.
+You do not need to keep the dialog open.
+When a watched step reaches the lesson teacher, Main's chat shows a short status
+line such as “Watching: you are in Preview.” followed by the teacher's
+reply. The teacher still receives the full observation; its internal prompt is
+not shown as a chat message. A failed step shows “Watching: that step did not
+finish.”; choosing the graduation-cap **Learning** option shows “Watching: you are in the Learning pane.”
+
+Polling reports only named Vibe64 controls, the settled project-or-Learning view,
+saved lesson progress and the reduced failed app request described above. It
+never sends typed text, form values, request or response bodies, headers, query
+strings, arbitrary page content, screenshots, secrets or another project. Navigation performed by Colleague is
+reported as a demonstration, not as something you did and not as assessment
+evidence. Polling does not grade a question or mark a lesson complete.
+Only a saved assessment outcome supports completion; a recent observation or a
+delivered-help receipt does not. Colleague cannot observe arbitrary activity
+inside the supervised application unless that interaction is one of the named
+Vibe64 controls or the declared exercise-response bridge.