vibe64 0.1.35 → 0.1.37

package/docs/colleague-usage/learning-practice-projects.md

@@ -1,78 +1,178 @@
-# Practice projects in standalone lessons
-
-Some lessons need a practice application. In Learning → **Courses**, use
-**Start**, **Start next lesson** or **Start lesson** for a new lesson, or
-**Continue**/**Resume saved lesson** for your saved one (see
-[Choosing lessons and Learning conversations](learning-mode-ui.md)). If the installation reports that exercise preparation is
-unavailable, keep the saved attempt and ask the owner to provide preparation
-support before retrying. That refusal means preparation did not start.
-
-Supported preparation uses the exercise bundled with your saved lesson and keeps
-its reserved practice project and session when you resume. Workspace setup may
-continue after the start request finishes. When that setup run succeeds, the
-lesson becomes ready on its own; you do not need to press **Resume saved lesson**
-first. Failed setup needs its existing recovery, then **Resume saved lesson**;
-setup success does not mean Preview is running or a practical has passed.
-Standalone setup uses the installation's actual resources; it does not create a
-hosted development database by default.
-
-The saved lesson and progress remain intact. Keep mismatched or unsafe practice
-storage intact and ask the owner to inspect the reported error. An unrelated
-Working project cannot replace this saved attempt's practice project.
-
-Colleague can explain the error and use supported lesson controls when asked.
-
-In a practice lesson, **Preview** shows the practice app as soon as it
-reports ready, including after the app starts while you are on the **Learning**
-pane. **Stop preview** stops the practice app cleanly and keeps it stopped, even
-after a reload, until you choose **Restart preview**. Switching between
-**Preview**, **Dashboard** and the graduation-cap **Learning** option keeps the same running app without reloading it.
-Standalone exercise conversations in Learning, their Preview and practical
-assessment are still being integrated; prepared source alone does not make that
-complete flow available.
-
-A local installation normally serves only the project you selected. It also
-opens your own active lesson's practice project by its address (for example
-when Colleague navigates there or you open **Account settings** from it): the
-page, **Preview** and **Dashboard** load the same way as on a hosted workspace.
-That address gives viewing and Preview control only; start new coding work from
-the lesson in **Learning**. The lesson's own conversation stays in **Learning**:
-the project's ordinary (Working) session list and settings do not show it. Another person's practice project, or a practice
-address with no saved lesson behind it, still reports "Local editor mode only
-serves the selected project."
-
-## Instructing your teacher-agent
-
-In a lesson with a practice project, the teacher in the lesson's conversation is
-also your Vibe64 agent for that project, as in normal Vibe64. Ask it to make a
-change and it does the work in the practice project. It also teaches you to
-instruct it well: say the goal, where the change belongs, and how you will check
-it. Then check the result yourself in the real interface: **Preview**, and in the
-lesson **Dashboard** the **Files**, **Current changes**, **Git log**,
-**Architecture**, **Env** and **Database** → **ERD** views. These are the ordinary
-Dashboard sections, limited to this practice project and lesson session; see
-[Choosing lessons and Learning conversations](learning-mode-ui.md) for which
-sections a lesson shows.
-
-Work the teacher does for you is a demonstration. It never counts as your
-practical evidence, and the teacher does not do a graded task for you before you
-try it. When a lesson is about instructing the agent, your own explanation or
-instruction is what is assessed.
-
-While a code question is open, the teacher will not edit that question's files,
-even if you ask; any agent edit there voids the attempt and **Check my code**
-then reports that an independent attempt is needed. Make those edits yourself in
-the lesson Dashboard's **Files** tool. The teacher also never deploys, publishes,
-pushes to real remotes, changes Git remotes, or touches other projects or folders
-outside this practice project. Lesson 0 and other lessons without a practice
-project keep a conversation-only teacher that does no project work.
-
-A lesson you started before Learning moved onto the real Vibe64 app picks up
-the current teacher instructions with your next message. Its earlier replies may
-still say **Workspace** or **Code tab**; those are the old names for the header's
-**Preview** | **Dashboard** options and the Dashboard's **Files** section.
-
-Opening supported practice teaching retains the reserved initial conversation,
-source and history. An ownership or lesson-binding error needs owner inspection;
-do not create a replacement or switch it to an unrelated Working project. An
-older prepared conversation is not silently converted by resuming the lesson.
+# Lessons in progress, practice projects and archives
+
+Vibe64 has two modes: **Develop**, for your own projects, and **Learn**, for
+lessons. **L** switches between them (see
+[The Learning environment (L)](learning-environment.md)). This guide covers
+what a lesson keeps while it is in progress, and what happens when you finish,
+restart or delete it.
+
+## One lesson in progress
+
+Starting a lesson (**Courses**, then **Start**) begins one run of it, called an
+attempt. The attempt owns:
+
+- its step results,
+- its teacher conversation with Colleague,
+- its practice project, when the lesson needs a practice application.
+  A lesson without one has no project.
+
+You have at most one lesson in progress. It stays in progress until you finish,
+restart or delete it. Switching to Develop, or opening another page, only
+pauses it: its project, results and conversation are all kept, for as long as
+you like. Press **L** to come back to it.
+
+If you start a different lesson while one is in progress, Vibe64 asks once
+whether to archive the current lesson first. Confirming archives it (see
+below) and starts the new lesson. Cancelling changes nothing and keeps the
+current lesson in progress. Starting the lesson that is already in progress
+just opens it.
+
+## Practice projects
+
+Some lessons need a practice application. Starting such a lesson creates a
+practice project for it. If the installation reports that exercise preparation
+is unavailable, ask the owner to provide preparation support before retrying.
+That refusal means preparation did not start.
+
+Preparation uses the exercise bundled with the lesson. Workspace setup may
+continue after the start request finishes; when it succeeds the lesson becomes
+ready on its own. Failed setup needs its existing recovery; then ask Colleague
+to resume the lesson's preparation. Setup success does not mean Preview is running or a step has
+passed. Standalone setup uses the installation's actual resources; it does not
+create a hosted development database by default.
+
+Practice projects live in your own learning space, apart from your projects.
+In Develop mode they never appear in the project lists, the project switcher or
+Management → **Projects**, and opening one says
+"This is a practice project. Press L to switch to Learn." In Learn mode only
+your practice projects open; opening one of your own projects says
+"You're in Learn mode. Press L to go back to your projects." Only you see your
+practice projects; the workspace owner does not.
+
+This separation is part of Vibe64, not of the computer. Vibe64 keeps the two
+apart in where it stores them, what it lists and what it opens. It is not a
+security boundary: agents and the practice application run on the same machine,
+with the same system access, as your other projects. Treat a practice project
+like any of your projects and do not put secrets in it.
+
+Before an agent turn, Vibe64 writes its agent guidance (the `.agents`,
+`.claude`, `.codex` and `.opencode` folders) into the project. In a practice
+project these folders stay out of **Current changes** and out of what **Save**
+commits, so you see and save only your own changes; every lesson gets this
+without anything in its exercise. In your own projects they appear as changes
+to save, as before.
+
+A practice project is a complete project. Its chat, **Preview**, **Dashboard**
+and sessions work as in any project. The session that lesson preparation
+creates in it is an ordinary session.
+
+## In progress and Archived
+
+In Learn mode, **Courses** (on the lesson step bar, or in the project menu beside **L**) has an **In progress** list and an
+**Archived** list. Until your lessons are read, each list shows **Loading your
+lesson…** or **Loading archived lessons…** instead of staying blank.
+
+**In progress** shows the lesson in progress, if any: its title and its
+practice project's name (or **No practice project**). Without one it says
+**No lesson in progress. Start one from Courses.** The row has three buttons:
+
+- **Open** closes Courses and opens the lesson in the **Lesson** tab of its
+  practice project (or, for a lesson without one, of the page with no project
+  selected).
+- **Restart** turns into **Archive and restart**; press that to archive this
+  attempt and start the same lesson again with a new practice project, a new
+  teacher conversation and no step results.
+- **Delete** turns into **Delete for good**; press that to delete the lesson
+  in progress for good: its practice project (files, sessions and Preview) and
+  its teacher conversation go, with no archive. A lesson you completed before
+  stays completed.
+
+**Archived** lists your archived lessons, newest first, with the lesson title,
+whether it was finished or archived, and the date. Each row has a delete
+icon, then **Delete for good**, which removes that archive for good. You can keep at most 20 archived lessons;
+finishing, restarting or archiving another lesson is refused until you delete
+one. Archived lessons cannot be reopened from Vibe64; use **Start lesson** again to
+redo a lesson.
+
+An archive keeps the attempt's record and step results, its teacher
+conversation and its practice project's source, sessions and state, but leaves
+out dependencies that can be rebuilt, such as `node_modules`. A lesson without
+a practice project keeps only its record and conversation.
+
+To limit disk use, only your 3 newest archived lessons with a practice project
+keep it (they show **with practice project** in the list). When archiving
+another lesson's project would make 4, the oldest of them loses its practice
+project, on its own; it keeps its record, step results and teacher
+conversation. Lessons without a practice project do not count. This never
+touches the lesson in progress, however long it stays paused, or your own
+projects.
+
+## Finishing a lesson
+
+When every required step has passed, the lesson's **Lesson finished** screen,
+in the page's **Lesson** tab, finishes it: the lesson counts as completed for good, and the attempt is
+archived as one bundle (its record, practice project and conversation). The
+screen then offers **Next lesson** and **Back to courses**. **Start lesson** on
+the course page starts a new attempt with a fresh project, teacher and results; the
+course list still shows the lesson as completed.
+
+## When something refuses or stops
+
+If a session in the practice project is pinned, finishing, restarting,
+archiving or deleting refuses with a message that names the session. Nothing
+was changed. Open the session, choose **Unpin session**, and try again. A full
+archive (20 lessons) or too little storage also refuses with nothing changed.
+
+If archiving or deleting stops part-way, the lesson stays in progress (a
+stopped removal shows **Being deleted**). Press the same button again; it
+continues from the step that failed. **Delete** also finishes a stopped archive.
+If it keeps failing, the error says why; ask the person who runs this Vibe64
+to inspect it.
+
+## What Colleague can do
+
+Colleague can list the lesson in progress and the archived lessons, and switch
+between Learn and Develop when you ask. It restarts or finishes a lesson only
+when you ask, and deletes the lesson in progress or an archive only when you
+ask and then confirm that exact deletion; an offer is not a request. Starting a
+different lesson while one is in progress needs your confirmation to archive
+the current one first.
+
+## A practice project open elsewhere
+
+If a practice project that was archived or deleted is still open in another tab
+or window, that page switches by itself (no reload needed) to **This practice
+project is gone** instead of an error. The page's requests answer not found with
+the code `vibe64_practice_project_deleted`. Colleague can explain this.
+
+## How a practice project is named
+
+A practice project keeps its address (`/app/project/training-…`), but Vibe64
+names it after its lesson: in the project header, in **Courses** and by
+Colleague. The name is **Practice:** followed by the lesson title, otherwise the
+lesson code, for example **Practice: V64-START-02**. Hover the header name on a
+computer to see the address too.
+
+On a phone the header name shortens with **…** so it never covers the other
+header buttons. While Preview's controls are showing on a very narrow phone, or
+beside a local project's Git branch and GitHub controls on a phone narrower than
+about 540px, there may be no room for it at all; the name is then hidden rather
+than squeezed. With Preview shown, **Show chat** brings it back; otherwise turn
+the phone sideways or use a wider screen. On phones narrower than about 480px the button that switches
+between **Preview** and **Dashboard** shows that pane's icon instead of the word
+(its name is still **Go to dashboard** or **Go to preview**).
+
+## Working in the practice project
+
+The practice project's session has an ordinary Vibe64 agent, without lesson
+instructions. Ask it to make a change and it works in the practice project, as
+in any project; Colleague teaches you to instruct it well (say the goal, where
+the change belongs and how you will check it). Then check the result yourself in
+**Preview** and the **Dashboard** sections.
+
+Work an agent does for you never counts as your own work. While a code step is
+open, make the edits to its files yourself in
+**Dashboard → Files**: your saves there are recorded for the lesson, and any
+other writer's edit in those files means the step's **Check now** asks for an
+independent attempt (see [Answering a code question in a lesson](learning-code-questions.md)).
+Hosted workspaces record these saves the same way.

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

@@ -1,52 +1,74 @@
 # 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.
+Colleague teaches your lessons and shows you where things are in the real
+Vibe64 app. By default it *points*: it rings the real control you should click
+next, with a short caption such as **Dashboard → Database → ERD** or the
+lesson's own caption. 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.
+  one real tab, Dashboard section or button. A caption 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.
+  rings the **ERD** button. When you are already at the place (for example
+  Preview or **Dashboard → Files** is open), the ring goes around that open
+  pane, with the caption inside its top edge when the pane fills the screen.
 - 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.
+- If Learning is open above the app when Colleague points at an app place,
+  Learning is minimised first (your lesson and step are kept) so you can see it.
 
-## Places the teacher can point at
+## Places Colleague 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.
+**Session info**, **Architecture**, and the **L** (Learning) button. A Dashboard
+section the project 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.
+A phone shows the chat or one pane at a time, so the Preview/Dashboard tabs and
+the Dashboard menu are hidden. Colleague's full-screen chat minimises itself
+first so the ring is visible. Then:
+
+- If the place's pane is already showing (for example Preview, or Files in the
+  Dashboard), the ring goes around that pane.
+- In the Dashboard, a Dashboard section that is not open rings the
+  **Dashboard section** select at the top; choose the section there.
+- When Files, Database, Architecture or Current changes fills the Dashboard
+  and the place is another Dashboard section, the ring goes around that pane's
+  **Back to dashboard** button (in Files or Database it may read **Back to
+  Architecture**). Tap it, then follow the next ring.
+- Only when the place is in the other pane (Preview instead of Dashboard, or
+  the reverse), or the chat is showing, does the ring sit 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 ›**;
+  on phones narrower than about 480px it shows only the Dashboard or Preview
+  icon).
+  Tap it; when the next step becomes visible, Colleague can ring it directly.
+
+The caption always shows the whole path. Reopen Colleague with its avatar
+button.
 
 ## 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.
+Colleague is told so, never claims a highlight, 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.
+Ask Colleague to "show me" and it opens the place itself in your project (for a
+file, in **Dashboard → Files**) and rings it there. For the Learning place it
+opens Learning. A view Colleague opens is a demonstration, not your step: it never
+passes a lesson step. When a lesson asks you to find a place, click it yourself.
 
-## What Colleague can do
+## Opening your lesson
 
-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.
+Colleague can show your current lesson step in the Learn page's **Lesson** tab,
+and open the **Courses** catalogue or close it so you can see the app, without
+ending the lesson. While the lesson is going, the **Step N/M** button in
+Colleague's header shows the current step in the Lesson tab (on a phone,
+Colleague's chat minimises so the step is visible).