vibe64 0.1.32 → 0.1.34

package/docs/colleague-usage/learning-teacher-guide.md

@@ -0,0 +1,52 @@
+# Learning teacher guide
+
+During a practice lesson, the lesson teacher (Main) shows you where things are in
+the real Vibe64 workspace. By default it *points*: it rings the real control you
+should click next, with a short caption such as **Dashboard → Database → ERD**.
+You then click it yourself.
+
+## What you see
+
+- The rest of the screen dims slightly, and a ring with a gentle ripple sits on
+  one real tab, Dashboard section or button. A caption with the whole path points
+  at it; a thin bar on the caption shows the time left.
+- The ring is on the next step from where you are. On **Preview**, a path to the
+  ERD rings the **Dashboard** tab; once you are in **Dashboard → Database**, it
+  rings the **ERD** button.
+- The ring lasts about 8 seconds, or until you click or press a key. It never
+  blocks your click, and it holds still when your device asks for reduced motion.
+
+## Places the teacher can point at
+
+**Preview**, **Dashboard**, **Dashboard → Database → ERD** or **Data**,
+**Dashboard → Files** (and one file in it), **Current changes**, **Git log**,
+**Session info**, **Architecture**, and the graduation-cap (Learning) option beside Preview and Dashboard. A Dashboard section
+the lesson does not show cannot be ringed.
+
+## On a phone
+
+A phone shows the chat or one pane at a time, so the next tab is often hidden.
+The ring then sits on the header's pane switch: the arrow button that shows the
+project panes from the chat, or the next-pane button (for example **Dashboard ›**)
+that steps **Preview → Dashboard → Learning**. The caption still shows the whole
+path. Tap the switch; when the next step becomes visible, the teacher can ring it
+directly.
+
+## When nothing is ringed
+
+If neither a step on the path nor the pane switch is visible, nothing is drawn.
+The teacher is told so and gives you the path in words instead; follow it with the
+visible controls.
+
+## "Show me"
+
+Ask the teacher to "show me" and it opens the place itself (for a file, in the
+lesson's **Dashboard → Files** editor) and rings it there. A view the teacher opens is
+a demonstration, not your step; when a lesson asks you to find a place, click it
+yourself so **Watch me** observes your own navigation.
+
+## What Colleague can do
+
+Colleague can explain these steps. It cannot draw the teacher's ring; it can open
+the lesson project's **Preview** or **Dashboard → Database → ERD** for you when you
+ask, which is also a demonstration.

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

@@ -25,6 +25,34 @@ explain native observation facts/accepted steps from its context query; those fa
 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
@@ -142,97 +170,48 @@ configured before retrying. Unrelated history cannot be assessed; host support i
 
 ### Practising the native workspace controls
 
-For the workspace exercise, keep the same question open while you use the
-controls yourself: open the project selector and choose the lesson's exercise
-(the already selected project also counts), reveal its Main coding conversation
-with the session tab or **Show chat**, then choose **Preview**. A different session
-or temporary review conversation does not count; use its **Main chat** button
-first. Wait for each view to finish opening.
-Colleague can explain these steps, but its own navigation is a demonstration,
-not evidence that you performed them.
-
-Keep one delivered challenge and its question reference across all three steps.
-The Main teacher may explain one substep at a time, but must not prepare a new question
-between project selection, revealing its Main chat and Preview selection:
-that replaces the challenge and resets its observation collection. On a phone,
-receive the task before minimising Colleague; return after the steps and explain
-what you did before assessment. The supported Main practical owner must acknowledge the actual accepted steps
-and coach the next move; ordinary Colleague chat is not a grading path.
-These collecting facts are not a completed observation or pass. Only the final
-native step supplies `trainingPractical` for assessment.
-
-For the return exercise, **Minimize conversation**, use the workspace, then
-restore Colleague with its launcher. On phones, **Show project** / **Show chat**
-toggle workspace / Main, not Colleague. Desktop drawer and phone full-screen retain
-the session, speech, draft and exercise. Restore Colleague's actual body; another
-assistant's voice panel does not count.
-
-Native observation binds your clicked control and settled view to the delivered
-question; it has no pass button. Unsupported observation leaves the practical
-incomplete. If unconfirmed, repeat the step once ready; the workspace action was
-not undone. Reload or question replacement may require repeating an unfinished
-sequence. Separate verified assessment uses the pinned rubric and your explanation.
-
-Observation retries retain the original gesture acknowledgement/step count;
-conflicting details are rejected. Completion is an observation, not a pass.
-After server restart repeat the sequence; workspace actions were not undone.
-Demonstration/substantial help remains teacher-origin, not independent evidence.
-
-Practical assessment requires both your native exercise receipt and accepted
-explanation, never Main's substitute description. Demonstrations and failed
-declared checks cannot earn a pass. Retry reads the saved result; another submission
-cannot reuse the observation. Assessment is not a learner grading button or proof
-of lesson completion.
-
-### Trying the real application
-
-For the application practical, show **App preview**, press the application's
-**Ask the server** button yourself, and read its greeting and request reference.
-If the diagram is showing, switch back to App preview first. On a phone,
-minimise Colleague so the real App is visible. Tell the Main teacher in ordinary words
-what you pressed and what replied; a verified request alone does not replace
-this explanation.
-
-The lesson checks the visible App frame and real server response. Diagrams,
-demonstrations, readiness signals and background responses are insufficient.
-If App was hidden, the question changed or observation was unconfirmed, show the
-same exercise and press again. After server restart, use **Reload preview** before
-pressing. Original App/Preview controls remain; Colleague gets no source or screenshots.
-
-Colleague can read the completed observation's exact identity through its normal
-context query, then evaluate it with your accepted explanation. Missing or stale
-observations require repeating the native task. A check reporting a verified
-interaction is not itself a rubric pass, and demonstrated steps remain labelled
-as demonstrated.
-
-An assessment error does not prove a Helper setup problem. Keep the attempt and question; inspect the actual cause. After admission recovery, give a fresh answer to the current question; old messages stay unchanged.
-
-
-## Preview lesson choices: integration prerequisite
-
-The prepared **Lessons** picker displays the host's installed courses in their
-original order, with readable lesson titles beside the exact lesson codes,
-course/topic releases and lesson hashes. It does
-not install or enable content. Disabled courses, preview courses and draft
-lessons stay labelled and unavailable for a new start. Choose a published lesson
-from an enabled release, then use **Start selected lesson** to request that exact
-lesson. Selection alone never starts anything. A missing title reports **Lesson titles
-are unavailable**; use **Refresh lessons**. This preserves the saved attempt and
-history and does not substitute an invented title or another lesson. The host's original lesson action
+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.
+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
-through the existing lesson operation first; the picker never does that for you.
+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 lessons** rereads;
+**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;

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

@@ -161,9 +161,15 @@ immutable. Check both the exact local lock and actual requested Git publication;
 
 ## Operator installation is separate
 
+Courses published in the official Vibe64 course catalogue are installed and
+updated from Learning's **Courses** pane by any signed-in person (see
+[Installing and updating Learning courses](learning-course-catalogue.md)). The
+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 **Lessons** to
+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
 enabled learner course. Ordinary **Start** still requires a published lesson in
 an enabled release. Local validation/bundling alone admits no trial. Do not change
@@ -181,9 +187,9 @@ terminal commands documented in [Local operator provisioning](../training-conten
 fresh catalogue revision; `enable-course` and `disable-course` change only the
 exact selected release against that revision. Creating a course lock does not
 install or enable it, and installation does not make it available to learners.
-Disabling blocks new starts while retaining existing attempts' pins. This is an
-OS-operator task on the selected installation, with no learner/mobile control or
-Colleague source/shell access. Colleague can explain the steps and offer to help
+Disabling blocks new starts while retaining existing attempts' pins. For content outside
+the official catalogue this is an OS-operator task on the selected installation,
+with no learner/mobile control or Colleague source/shell access. Colleague can explain the steps and offer to help
 formulate the operator request; it cannot run operator installation, enablement or deployment on
 that person's behalf. Requested Git source publication uses the native workflow above. Invalid content or an unconfirmed save requires owner
 inspection, not automatic replacement or blind retry.
@@ -202,3 +208,5 @@ move an answer or a diagram checkpoint 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.
+
+Pinned source admission verifies committed file bytes in bounded Git batches, including binary assets and filenames containing line breaks. It retains the clean-source and repeated commit checks; a source change still requires committing and retrying the same authorized operation. This does not publish or change a course pin.

package/docs/colleague-usage/lesson-practical-assessment.md

@@ -41,7 +41,9 @@ another inference or repeat an unknown App effect to manufacture success.
 
 A server restart or retired connection can lose unfinished native-step collection;
 it does not undo your workspace action. Explain that clearly and repeat the
-practical only when collection is genuinely unavailable. Previously confirmed
+practical only when collection is genuinely unavailable. The delivered question
+itself is saved and stays open: missing collected facts after a restart mean
+"press or repeat again", never "issue the question again". Previously confirmed
 passes remain in the original saved progress. A new question needs its own real
 steps; an older observation cannot be reused for it. Closing a view or minimizing
 a drawer is not permission to replace the saved lesson or silently send a message.

package/docs/colleague-usage/managed-app-access.md

@@ -14,6 +14,12 @@ Adding a name here does not create an application account.
 4. Use Preview's available identity controls for the browser exchange. Merely
    saving identity configuration does not sign that browser in.
 
+After switching identity, open the intended application page in Preview and check
+the rendered account and access. An application can leave its login page visible
+after the exchange succeeds; the selected identity name alone is not proof of
+access. If a protected page still returns to login, ask the coding agent to inspect
+the exchange and subsequent application requests without exposing cookie values.
+
 The configuration is part of the selected session's source. Use the ordinary
 Save workflow when it should become saved project work. Source Save, application
 account creation and browser sign-in have distinct effects. If the application

package/docs/colleague-usage/message-delivery-recovery.md

@@ -0,0 +1,56 @@
+# Recovering an unconfirmed message
+
+When a message says **Delivery is uncertain**, choose **Retry** to check its
+original receipt. Do not copy and send the same message again: it may already
+have reached the assistant. Keep the original text and attachments while its
+receipt is checked.
+
+A historical Claude pre-write rejection can leave that receipt uncertain even
+though the native send was refused. An operator can apply the numbered stopped
+workspace repair after proving the original rejection and checking native history.
+The repair sends nothing and preserves the conversation. Once it is applied,
+the failed message's **Retry** action can submit the retained request normally.
+The same controls apply on desktop and mobile.
+When **Retry** starts another attempt, its bubble immediately shows **Pending**
+and hides the previous failure controls while it is sending. If that attempt
+fails or its receipt becomes uncertain, the corresponding recovery controls
+return with its current delivery state.
+
+A message that fails before it reaches the assistant shows its error at once
+and is marked **failed**, not uncertain, for example when the assistant's memory
+is too full. Fix the cause and choose **Retry**; nothing was sent.
+
+The assistant is shown as working (the animated indicator and the **Assistant
+working** dot on a temporary chat tab) only while its turn is actually
+running. Sending, choosing a recipient, connecting and an unconfirmed delivery
+have their own labels and never show the assistant as working. **Stop** stays
+available while a request is being routed or sent.
+
+Accepted messages appear in timestamp order with the conversation, even while
+their saved history is loading. Pending, failed and uncertain messages retain
+their queue position and recovery controls. Loading older history replaces the
+matching local copy rather than showing the same message twice.
+
+Colleague can explain these steps and offer supported message actions. Server
+maintenance requires an operator; Colleague must not invent a receipt, clear
+unknown delivery or claim a failed request was delivered.
+
+## When a turn finishes while you send
+
+Sending a new instruction while Claude works uses its targeted **Send now**
+control when supported by the installed Claude version. Background agents and
+background tasks continue; foreground work may be interrupted to read your
+instruction. This also applies to **Set goal** and **Resume goal** during active
+work. **Stop** keeps its cancellation behavior. Older Claude versions retain
+their previous interruption behavior. These controls work on desktop and mobile.
+
+If you send a steering message just as Claude or Codex finishes, the queue can
+submit those same words and attachments as the next ordinary request. This happens
+only when the server confirms the steer was rejected before admission. It retains
+the same message identity and tries ordinary Send once. A timeout or uncertain
+receipt is still checked rather than resent. If ordinary Send fails, **Retry**
+keeps the request as Send instead of targeting the finished turn again.
+
+This recovery applies to project chats and temporary conversations such as
+**Fix it with AI**. A completed turn allows the one ordinary-send retry; stopped,
+failed or unverified turns do not silently restart through this recovery.

package/docs/colleague-usage/plans.md

@@ -22,7 +22,8 @@ Senior confirms creation or updates after the plan helper has saved the result.
 Both direct Senior and Junior receive the plan format and command instructions.
 Both roles must read the full Plan, including its technical details, and Progress
 before implementing or reviewing. Collapsing details in the viewer does not hide
-them from the agent. Junior can update Progress; Senior owns agreed Plan scope changes. Creating,
+them from the agent. Junior updates Progress and ticks existing checklist items
+as each is implemented and verified; Senior owns agreed Plan scope changes. Creating,
 reopening, archiving and completing a plan still require Senior. An unsuccessful
 save must be reported, and a chat outline alone is not a saved plan.
 
@@ -50,10 +51,11 @@ The icon remains available after completion and when only archived plans remain.
 When there is no current plan, the icon opens **History** directly.
 There is no icon when the session has neither a current plan nor history.
 
-The scope checklist remains stable during execution; it is not a live progress gauge.
-Recorded marks in historical plans remain visible. Junior records implementation
-and verification in Progress. Senior reads both documents, verifies every agreed
-acceptance requirement against the work and evidence, and explicitly completes the artifact.
+Checklist wording stays stable while completion ticks update during development.
+Partial or unverified items stay unchecked; an item is unticked if review finds
+missing evidence or a regression. Junior records supporting evidence and blockers
+in Progress. Senior checks the ticks against that evidence and explicitly completes
+the artifact only after verifying every agreed acceptance requirement.
 A finished turn or a fully ticked checklist alone does not complete a plan.
 Updates appear while the viewer is open.
 
@@ -66,6 +68,10 @@ that exact Plan and Progress pair into History. Chat shows **Completed plan
 archived** with **View plan history**, which opens this session's existing viewer.
 The plan icon remains available and opens History when there is no current plan.
 
+Senior can update checklist ticks and Progress during review without preventing
+completion. The agreed plan wording must still match the reviewed scope, and
+completion uses the latest saved Plan and Progress together.
+
 A finished implementation or an agent's handoff explanation is not completion.
 Interrupted reviews, unfinished plans and unrelated requests do not archive a
 plan. A different plan created while reviewing is not archived by the old review.
@@ -113,7 +119,8 @@ in Main chat to reopen the desired archive, identifying its title and date.
 Creating a new plan starts fresh Progress; it does not inherit the previous artifact's evidence. Reopening an archive retains that archive's exact Progress, including when it replaces another current plan.
 If this replaces a current plan, Senior identifies which paired artifact will be archived
 and confirms your choice unless you already authorized replacement. To implement
-an active plan, explicitly request it in chat; the viewer has no Implement button.
+an active plan, explicitly request it in chat or select **Implement plan** in the
+waiting Auto Planning notice. The viewer itself has no Implement button.
 
 ## Loading, errors and Colleague assistance
 
@@ -146,7 +153,7 @@ sent through an already-authorized chat operation when available.
 ## Auto roles and workflow
 
 For Senior/Junior routing, implementation, review, Deslop, scope deferral and
-Stop or Resume workflow recovery, read [Choose Auto roles and follow the
+Stop or stage-specific Continue recovery, read [Choose Auto roles and follow the
 workflow](auto-workflow.md). Plan and Progress remain one paired artifact.
 
 

package/docs/colleague-usage/preview-browser-checks.md

@@ -0,0 +1,61 @@
+# Browser checks from chat
+
+Ask the coding agent in chat to test the running application in a browser and
+specify the flow to check. The agent uses the session's managed browser tools;
+you do not need to provide an execution ID or change application code to enable
+them. Application login may still require your credentials or interaction.
+The managed browser keeps its page and login between the coding agent’s tool
+commands. Stopping Preview, closing the session, resetting the managed browser
+or losing its editor connection can require login again. If it repeatedly loses
+login during ordinary checks, ask the coding agent to inspect browser lifecycle
+errors; shortening waits is not a recovery for a stopped browser.
+If a check reports **Launch preview token is missing or invalid**, use the
+current Preview link and the session's managed browser, not a copied link from
+an earlier launch. Managed browser code can navigate to `preview.url` using
+its existing authenticated context; that URL does not expose the access token.
+A persistent token error needs browser-access investigation, not a pool restart.
+
+The coding agent runs managed test suites and live Preview browser checks one
+after the other. A suite owns Preview until its cleanup and restoration finish;
+the agent can read status and logs while waiting, then confirms there is no
+active test run and the restored Preview is ready before live inspection. This
+also applies after cancelling a suite. If restoration fails, ask the coding
+agent to recover that existing run before another check. **Test Preview**
+identifies the test environment while it is selected. Colleague can explain the
+sequence and offer coding-agent assistance through the existing chat controls.
+While a suite runs in the background, the coding agent waits on its existing
+execution and checks logs when output or state changes, rather than repeatedly
+reading unchanged logs between short waits.
+Where its command tool supports `yield_time_ms`, an empty progress wait uses
+`30000`; shorter waits are for interactive input or a specific immediate check.
+
+Ask the coding agent to run browser-owning Node integration tests through
+`vibe64-helper playwright npm-run` as well. The project can declare these as
+`test:playwright:<name>` npm scripts. They use the host's browser task budget,
+which counts all Node and Chromium threads. Colleague can explain this route
+and offer coding-agent assistance; it cannot change host resource limits.
+Managed suites and their setup include the Git runtime for repository fixtures.
+Other tool dependencies still need their own declared runtime support. A fixture
+setup failure does not count as a failed application assertion or a passing check.
+
+The coding agent can read `vibe64-helper playwright --help` before a project has
+browser tests or a matching test runtime. Help starts neither Preview nor a browser.
+An actual suite still requires the project's installed Playwright version and a
+matching managed runtime. A version error is a test-runtime blocker; interactive
+checks can use the existing managed Preview browser. Report the exact required
+version to the platform operator instead of installing a separate browser.
+
+Before a suite, the coding agent can run `vibe64-helper playwright readiness`.
+It distinguishes absent tests, uninstalled dependencies, an unsupported exact
+runtime and a supported installed dependency without starting Preview or a
+browser. `ready` confirms dependency/runtime availability, not passing tests or
+application readiness. `status` separately reports an active test run. Colleague
+can explain these outcomes and delegate investigation to the coding chat; it
+does not receive shell access through this guide.
+
+If the agent reports “Browser testing requires a live assistant execution owner,”
+the browser test did not start. This is an assistant runtime problem. After the
+host runtime has been fixed and restarted, send a new chat message asking the
+agent to retry the check. Colleague can explain this recovery and inspect Preview
+state through its existing actions; it does not receive shell or browser-test
+access from this guide.

package/docs/colleague-usage/preview-lesson-presentation.md

@@ -0,0 +1,56 @@
+# Lesson presentation in Preview
+
+This continues [Previewing a web application](preview.md); for diagrams and voice in lessons see also [Lesson diagrams and voice](learning-diagrams-and-voice.md).
+
+When a host opens a declared lesson diagram, Preview offers **App preview** and
+**Colleague presentation**. App preview returns to the running application;
+Colleague presentation shows the same retained diagram. Switching changes neither
+the application process nor its frame. **Minimise presentation** returns to the
+application while retaining the diagram; **Restore presentation** brings it back.
+On phones, return to the workspace from Colleague to use these same Preview choices.
+
+The host reads your pinned diagram for your signed-in lesson attempt even while
+its exercise project is selected. You need not leave the project to load it. If
+loading fails, use **Reload presentation** for the same attempt; do not start a
+new lesson or treat the failure as an assessment result.
+
+Hiding a diagram pauses its motion when its declared controller supports pause.
+Showing it does not replay a transition automatically. A diagram failure offers
+**Reload diagram**; a failed resource read offers **Reload presentation**, which
+reads the same attempt and declared visual again. Neither recovery grades an
+assessment or changes the lesson version. Missing or changed pinned content needs
+the owner's normal recovery. Colleague's visual commands become available only
+when the host supplies authenticated resource delivery and browser acknowledgement;
+this Preview composition alone does not activate those tools or synchronise speech.
+
+With the authenticated host connected, you can ask Colleague to show a declared
+lesson visual or demonstrate its next step. It uses your saved prepared exercise
+and waits for the diagram to be ready or the transition to finish. Ask it to read
+the displayed diagram state if you are unsure. If the browser disconnects or the
+exercise view changes, reopen the same lesson and retry deliberately; a missing
+acknowledgement is not proof the transition failed, so keep the original command
+identity on a retry. These commands do not mark learner work correct or prove
+spoken narration finished.
+
+## Diagram explanations and sound
+
+A host-enabled teaching cue first shows the declared diagram, then uses one final
+Colleague explanation. Its motion starts when that explanation actually becomes
+audible. Tool progress is not narration. With spoken replies off, read the final
+explanation and press **Continue** to watch. If sound has not started, **Play diagram
+without sound** is an explicit alternative; sound failure also offers Continue.
+Neither option pretends that audio played.
+
+Hiding Preview, changing the exercise, reloading its diagram or stopping the
+explanation retires the current cue. Supported motion pauses and its semantic
+state remains readable; showing Preview alone does not replay it. Deliberately
+hiding the diagram interrupts sound only while this cue's exact explanation is
+still audible. The normal voice stop also clears queued speech for that same
+voice binding; it does not pause audio for later resumption. Minimising Colleague
+alone keeps voice playing, and a newer answer or another conversation is never
+stopped by this diagram control. Ask Colleague to repeat the explanation explicitly
+when needed. Colleague waits for the actual
+diagram and required audio completion receipt before another teaching cue or
+question. An unconfirmed receipt needs its current status checked, not an inferred
+pass or automatic replay. On phones, opening a teaching presentation minimises
+Colleague's frame while retaining the conversation, microphone and typed draft.

package/docs/colleague-usage/preview-starting-application.md

@@ -0,0 +1,92 @@
+# Choose a starting application
+
+This continues [Previewing a web application](preview.md).
+
+In an empty project's **Preview**, choose **Use this starter** on the desired
+Basic, Database, or Accounts app. On mobile, open **Show project** first. Import
+adds source to this session; review it and use **Save** to keep it in the project.
+Setup and running the app are separate operations.
+
+A missing Stack contract reported during import can belong to the downloaded
+starter even when your project's Stack is empty. Validation rejects that starter
+before copying it. Migrating the empty destination does not fix the starter.
+After the starter or importer is repaired, retry **Use this starter**. If the
+result is uncertain, recheck the project before retrying; existing application
+source must not be overwritten.
+
+Colleague can inspect onboarding, explain the available choices and offer to
+apply one. After you choose a starter and accept its offer or directly request
+it, Colleague can use the existing onboarding action and recheck the result.
+A successful import does not mean dependencies are prepared or Preview is running.
+
+For recurring **Preview could not load an application resource** errors, enable
+Preview diagnostics in the affected Studio browser before reproducing: add
+`vibe64_preview_debug=1` to the page URL, or set
+`localStorage.setItem("vibe64:preview-debug", "1")` in that browser's developer
+console. The option applies to that browser, on desktop or mobile; Colleague can
+explain it but cannot change browser developer settings for the person.
+
+While enabled, failed script/style/module URLs, frame readiness and automatic
+retry events are sent through the session's authenticated Preview action to the
+workspace's private operational log (`vibe64.preview.browser_diagnostic`). An
+operator can inspect that log after the page reloads or the person leaves. Each
+record identifies the project, session, frame attempt, retry count and browser
+observation time. The authenticated route selects the project and session; the
+browser sends only diagnostic fields in the request body. URLs keep only origin/path: credentials, query values and
+fragments are removed. Console text, request/response bodies and headers are not
+uploaded. Each iframe reports at most 50 failed resources; the daemon accepts
+at most 120 records per minute. Excess diagnostics
+are omitted without changing Preview. These records can identify a failing
+module, but browser resource errors do not themselves provide its HTTP status.
+A log outage does not trigger another Preview retry.
+
+Remove the URL option and run
+`localStorage.removeItem("vibe64:preview-debug")` to stop recording. Existing
+private log retention remains the operator's responsibility. The ordinary
+Preview diagnostics attachment remains a separate, explicitly requested snapshot
+of the current iframe's console/network history.
+
+For a **Chat updates could not reconnect** investigation, the operator can enable
+existing `JSKIT_REALTIME_DEBUG=1` on the workspace daemon (or `realtime.debug` in
+its runtime configuration), then restart the daemon at a safe maintenance boundary
+to apply it. Vibe64 passes this flag to the shared chat runtime; setting it in a
+project's Preview environment does not enable chat diagnostics. Subscription
+diagnostics then record the pending
+server stage at the 10-second acknowledgement budget and the stage/reason when
+that observer is released. With this option enabled, each preceding stage and
+its elapsed time are also retained in warning-level logs, so an operator can
+distinguish slow admission from slow snapshot reading. With the environment flag
+enabled, `vibe64.conversation.browser_timing` also separates Main's session loading,
+native conversation opening and fresh authorization, including failed boundaries.
+Repeated subscription authorization is recorded only when denied or taking at
+least 100 milliseconds, to avoid a diagnostic log entry for every healthy token.
+The same diagnostic record family separates slow conversation access checks into
+fresh user lookup, saved learning-attempt validation, practice scope, project
+access and project-context resolution. It records the elapsed phases even when
+access fails; repeated checks keep their existing authorization behavior.
+These access timings also apply to standalone Learning conversations.
+Concurrent Learning readers share verification of the same pinned course files
+while that verification is running. Completed results are not cached: later
+reads still reject missing or changed installed files, with the same reinstall
+guidance. Each reader retains its own result and fresh access checks.
+These records identify the session and operation, without chat text, request
+details, account credentials or error contents. This does
+not change the deadline, start a model, resend a message or retry a subscription;
+use **Reload chat** after correcting the cause.
+
+Leaving a chat or releasing its failed connection stops further subscription
+setup once the current step finishes. A released connection does not start a
+new history read; an existing read may finish without updating the replacement
+view. This only releases browser observation: agent work continues. **Reload
+chat** still checks current access before restoring history and live updates.
+
+With the same option, saved learning-attempt timings separately report normal or
+preview scope selection, saved exercise validation and practice-context capture.
+These are nested durations within saved-attempt time; do not add them to that
+parent duration. Failed stages retain their timing without exposing their error
+contents, and no completed authorization result is cached.
+
+Opening a saved Learning practice conversation still checks its pinned teaching
+content on each admission. That check does not load a second exercise-file payload
+for workspace preparation. Missing or changed teaching content still requires the
+owner to restore the exact verified snapshot; reloading chat does not bypass it.