vibe64 0.1.39 → 0.1.41

package/docs/colleague-usage/set-up-macos.md

@@ -0,0 +1,199 @@
+# Set up a Mac for Vibe64
+
+A step-by-step setup for running Vibe64 on your own Mac. Do the steps up to
+**An AI tool** once. The project steps only matter when a project needs them, and
+Vibe64 tells you when: a row with the exact command appears where the work
+needs the tool.
+
+Paste each command into **Terminal** (in Applications → Utilities) and press
+Enter. A command that asks for your Mac password shows nothing while you type;
+press Enter when done.
+
+## Basic tools
+
+Apple's command line tools give you Git, a compiler and Make:
+
+```sh
+xcode-select --install
+```
+
+A window opens; choose **Install** and wait for it to finish. Check:
+`git --version` prints a version. Until they are installed, `git`, `python3`
+and `cc` on a Mac only open that install window, so Vibe64 shows this one row
+first and checks nothing else that depends on it.
+
+## Homebrew
+
+[Homebrew](https://brew.sh/) installs the programs that need more than your
+home folder, such as database servers. Its first install asks for your Mac
+password, so use an administrator account:
+
+```sh
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+```
+
+When it finishes, make it available in every terminal:
+
+```sh
+echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
+```
+
+That is the folder on Apple silicon Macs; Homebrew prints the right line for
+your Mac at the end of its install, so you can copy it from there. After this
+first install, `brew install …` needs no password. Homebrew supports macOS 15
+(Sequoia) and newer.
+
+## Node.js and mise
+
+Vibe64 needs **Node.js 26**. Install it with [mise](https://mise.jdx.dev/),
+which installs languages into your home folder without a password:
+
+```sh
+curl -fsSL https://mise.run | sh
+echo 'eval "$(~/.local/bin/mise activate zsh)"' >> ~/.zshrc
+echo 'eval "$(~/.local/bin/mise activate zsh --shims)"' >> ~/.zprofile
+~/.local/bin/mise use -g node@26
+```
+
+These lines are for zsh, the Mac's standard shell. If you use bash, write
+`activate bash` into `~/.bashrc` and `activate bash --shims` into
+`~/.bash_profile` instead.
+
+Close Terminal and open it again. Check: `node --version` prints `v26…`. Always
+keep the `-g`: without it, mise writes a `mise.toml` file into whatever folder
+you are in.
+
+## Start Vibe64
+
+In the folder you want to work on, run `npx vibe64`. See
+[Running Vibe64 on your computer](running-vibe64-on-your-computer.md) for the
+options and where Vibe64 keeps its data.
+
+## Git
+
+Tell Git who you are, once, so your commits carry your name:
+
+```sh
+git config --global user.name "Your Name"
+git config --global user.email "you@example.com"
+```
+
+Without them Vibe64 still saves your work, using a stand-in name ending in
+“via Vibe64”, and **Health** reminds you. To work with GitHub, connect it in
+**Account settings → GitHub**; signing in fills in your name and email only
+when Git has none.
+
+## An AI tool
+
+Vibe64 works through one AI tool on this computer. One is enough; each installs
+into your home folder:
+
+| AI | Command |
+|---|---|
+| Claude Code | `curl -fsSL https://claude.ai/install.sh \| bash` |
+| Codex (ChatGPT and OpenAI keys) | `curl -fsSL https://chatgpt.com/codex/install.sh \| sh` |
+| opencode (providers connected through OpenCode) | `curl -fsSL https://opencode.ai/install \| bash` |
+
+Then choose **Set up your AI** in Vibe64 and sign in. See
+[AI accounts](ai-accounts.md).
+
+## Project languages
+
+Only when a project needs one. When **Preparing workspace** fails because a
+language is missing, the panel shows its row with the command for this Mac.
+These install with mise, without a password:
+
+| Language | Command |
+|---|---|
+| Python | `mise use -g python@3.13` |
+| Ruby | `mise use -g ruby@3.4` |
+| Java | `mise use -g java@temurin-25` |
+| Go | `mise use -g go` |
+| Rust | `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \| sh` |
+| PHP and Composer | `/bin/bash -c "$(curl -fsSL https://php.new/install/mac)"` |
+
+After installing, choose **Check again** on the row; no restart is needed.
+
+The Mac's own Ruby and Python are old, and `/usr/bin/java` only says that no
+Java is installed. Vibe64 looks in mise's folders before the system ones, so
+the versions you install with mise win; each row shows the version and folder it
+found. `brew install ruby` or `brew install python` also work, if you prefer
+Homebrew.
+
+## Build tools
+
+Some packages compile native code (Rails gems such as `psych` and `mysql2`,
+Python's `mysqlclient`), so they need Apple's command line tools (step one)
+and a few libraries. The row is called **Build tools**:
+
+```sh
+brew install pkg-config libyaml openssl@3 gmp
+```
+
+For MySQL drivers, also run `brew install mariadb`: the drivers build against
+it. Don't install `mysql-client` for this; its newer versions can't sign in to
+MariaDB users. Vibe64 adds Homebrew's PostgreSQL folder to the PATH of the commands it
+runs, so PostgreSQL drivers find what they need in the server you install
+below.
+
+## Databases
+
+Only when a project uses MySQL or PostgreSQL. SQLite needs nothing. You run the
+database server yourself; one you already have is fine. Vibe64 never starts it
+for you.
+
+**Install and start it**, once:
+
+| Database | Command |
+|---|---|
+| MySQL-compatible (MariaDB) | `brew install mariadb && brew services start mariadb` |
+| PostgreSQL | `brew install postgresql@18 && brew services start postgresql@18` |
+
+`brew services` starts the server now and every time you log in. To stop it:
+`brew services stop mariadb` (or `postgresql@18`).
+
+**Give the project its own login.** In the failed step's **database server**
+panel, choose **Suggest a user and password**, open **Create a login and
+database**, copy the command and paste it into Terminal. Then choose **Save
+and check**. When the panel says connected, choose **Retry**. See
+[Workspace preparation](workspace-preparation.md).
+
+If you already run Oracle MySQL, keep it: put its host, port, user and password
+in the panel or in **Env**. Don't install Homebrew's MariaDB next to it; the two
+conflict.
+
+## Extras
+
+Nice to have; nothing depends on them.
+
+| Tool | Command |
+|---|---|
+| GitHub CLI | `brew install gh` |
+| ripgrep (faster search) | `brew install ripgrep` |
+| Browser for automated checks | `npx playwright install chromium` |
+
+## Check your setup
+
+Open **Dashboard → Health**. The top line says **Vibe64 has what it needs.**
+when Node.js, Git and an AI tool all run. Each missing tool shows its command
+with a copy button and **Check again**. A tool counts only when it actually
+starts, so a broken install shows as **didn't start**, not as ready.
+
+If a tool works in Terminal but Vibe64 can't find it, it is probably installed
+somewhere only your interactive shell knows. Check the `mise` and Homebrew
+lines above, then start Vibe64 again from a new Terminal window.
+
+## Ask Colleague
+
+Colleague can walk you through any step here and explain what a row or message
+means. It can also do the safe parts for you, when you ask:
+
+- check whether a tool runs now (“is Ruby installed?”), or run all of
+  **Health**;
+- check the project's database server with the current values, and save the
+  host, port, database name and user name you tell it into **Env**;
+- retry the session's **Preparing workspace**, and open **Health** or **Env**.
+
+You run the install commands yourself, in Terminal: Colleague never uses
+`sudo`, never edits your shell files and never installs anything. Never type a
+password into chat; enter it in the panel's password field or in **Env**.

package/docs/colleague-usage/set-up-windows.md

@@ -0,0 +1,76 @@
+# Set up Windows for Vibe64 (WSL)
+
+Vibe64 runs on Windows inside **WSL**, Windows' built-in Linux, with Ubuntu.
+It doesn't run in PowerShell or Command Prompt: there, `npx vibe64` stops and
+points here. Once Ubuntu is set up, everything else is the same as on Linux.
+
+You need Windows 11, or Windows 10 version 2004 or newer.
+
+## Install WSL and Ubuntu
+
+1. Right-click **Start**, choose **Terminal (Admin)** or **Windows PowerShell
+   (Admin)**, and run:
+
+   ```powershell
+   wsl --install
+   ```
+
+2. Restart Windows when it asks.
+3. Open **Ubuntu** from the Start menu. The first start takes a minute, then
+   asks for a **username and password**. They are for Ubuntu only and don't
+   have to match your Windows ones. Remember the password: Ubuntu asks for it
+   whenever a command starts with `sudo`. Nothing shows while you type it.
+
+If `wsl --install` only prints help text, WSL is already there: run
+`wsl --install -d Ubuntu` instead. Microsoft's
+[install page](https://learn.microsoft.com/en-us/windows/wsl/install) has the
+details.
+
+## Set up Ubuntu
+
+From now on, type every command in the **Ubuntu** window, not in PowerShell.
+Follow [Set up Linux](set-up-linux.md) from the start, using the lines for
+**Ubuntu, Debian, WSL**: the basic tools, Node.js with mise, Git, an AI tool,
+and later whatever your projects need. Install the AI tools inside Ubuntu too;
+copies installed on the Windows side don't work from Ubuntu.
+
+Two checks after the Node.js step, in a new Ubuntu window:
+
+- `which node npx` must print paths that start with `/home/`. A path starting
+  with `/mnt/c/` is the Windows Node.js leaking in; it doesn't work with
+  Vibe64. Make sure the mise lines are in `~/.bashrc` and `~/.profile`, then
+  open a new Ubuntu window.
+- `node --version` prints `v26…`.
+
+## Keep projects inside Ubuntu
+
+Put your projects in your Ubuntu home folder (for example `~/Vibe64`, where
+Vibe64 creates new ones), not under `/mnt/c/`:
+
+- **Clone inside Ubuntu.** A project cloned with Git for Windows has Windows
+  line endings, and its scripts then fail with errors like
+  `/usr/bin/env: 'ruby\r': No such file or directory`.
+- **Speed.** Files under `/mnt/c/` are much slower for Linux programs.
+
+To see a project's files in Windows, run `explorer.exe .` in its folder.
+
+## Start Vibe64
+
+In the Ubuntu window, go to your project folder and run `npx vibe64`. Open the
+address it shows in your normal Windows browser: WSL passes `localhost` through
+to Windows. See [Running Vibe64 on your computer](running-vibe64-on-your-computer.md).
+
+## Databases
+
+Install and start them inside Ubuntu, with the Ubuntu lines in
+[Set up Linux](set-up-linux.md#databases). A database server installed on the
+Windows side also works: put its address in the project's **Env** (from inside
+WSL, Windows is not always reachable at `localhost`, so this is the harder
+route).
+
+## Ask Colleague
+
+Colleague can explain each step and check what is installed inside Ubuntu (it
+runs **Health** and checks single tools when you ask). Installing WSL, Ubuntu
+and the tools happens in your own terminal; Colleague never runs commands with
+`sudo` or in PowerShell. Never type a password into chat.

package/docs/colleague-usage/starter-apps.md

@@ -1,16 +1,33 @@
 # Choose a starter with ready tests
 
-In an empty project's onboarding, choose the JSKIT starter that matches the app:
+In an empty project's onboarding, starters are grouped by technology. Choose
+the JSKIT starter that matches the app:
 
 - **Basic app**: responsive shell, server/client/browser tests, no database or login.
-- **Database app**: the same shell plus MySQL migrations and isolated database
+- **App with no users, but a database**: the same shell plus MySQL migrations and isolated database
   tests, without accounts.
-- **Accounts app**: sign-up, login, private pages and persisted profiles, plus
+- **App with users**: sign-up, login, private pages and persisted profiles, plus
   account-persistence and browser tests.
 
+For another framework, each of Django, Rails, Spring Boot, Express and Next.js
+offers one **Basic app**: a home page whose notes form saves to SQLite
+(MySQL/MariaDB for Spring Boot), with unit and HTTP tests and the starter's own
+`docs/colleague-usage/starting-app.md`. Only Rails has sign-in, with the seeded
+development account `developer@example.com` / `developer`; for the others, ask
+the coding agent to add accounts. These starters do not declare **Browser test
+app**.
+
+When the installation does not supply their database itself, Preview stops at
+**Set up your project's environment** and names the missing value: `DB_NAME`
+for Django and Next.js, `DB_DATABASE` for Rails and Express, the `DB_*` server
+values for Spring Boot. Choose **Open Env**, enter an absolute SQLite file path
+outside the project (or the MySQL/MariaDB details) and **Save**; preparation
+then continues and the app starts.
+
 The same choices appear on desktop and mobile. Applying a starter imports its
-source. Finish **Prepare workspace** to install dependencies and provision its
-declared resources and migrations; a failed preparation offers **Retry**.
+source and starts **Prepare workspace** at once: it installs dependencies,
+provisions the declared resources (an installation that supplies the database
+does so here) and runs migrations; a failed preparation offers **Retry**.
 The coding agent can then follow the first feature request using the existing
 test commands documented in the starter's `docs/colleague-usage/testing.md`.
 
@@ -25,6 +42,6 @@ managed projects use the provided browser rather than installing another one.
 Colleague can explain the choices and offer coding-agent help. A how-to question
 alone does not authorize starter import, resource preparation or fixture reset.
 Applying to an existing application is unavailable; it does not replace authored
-source. These are three complete starters; optional packs are not part of this flow.
+source. These are complete starters; optional packs are not part of this flow.
 OpenCode's generated, ignored plugin-install files alone do not make a blank
 project an existing application. Custom OpenCode files still prevent import.

package/docs/colleague-usage/teaching-content.md

@@ -3,7 +3,7 @@
 This topic explains verified lesson content, private progress and owner recovery.
 For host-registered learner controls and assessment, read **Learn with Colleague**
 (`learning-with-colleague`). For authoring and Git publication, read **Author a
-lesson and publish its source** (`lesson-authoring`). The underlying facilities
+lesson and save its source** (`lesson-authoring`). The underlying facilities
 below do not by themselves add learner controls or grant Colleague source access;
 available operations depend on the host registrations described in those topics.
 
@@ -49,7 +49,7 @@ The application also has a server-side verified-snapshot installation facility.
 For official catalogue courses it is reached through **Install** and **Update**
 in Learning's **Courses** pane, or Colleague's `course.install` on a direct
 request (see [Installing and updating Learning courses](learning-course-catalogue.md)).
-For other content, the local operator commands in **Author a lesson and publish its source**
+For other content, the local operator commands in **Author a lesson and save its source**
 invoke the original installation owner.
 An admitted owner operation must select the canonical local source and exact
 course pin. Colleague can explain this boundary and offer to help contact the

package/docs/colleague-usage/team-ai-access.md

@@ -0,0 +1,108 @@
+# Team AI access: when team members can open projects
+
+A workspace can have one owner and other people (team members). Team members
+never use the owner's AI directly: main chat runs on the owner's setup (a team
+member's messages wait for approval), and everything else a team member does
+with AI (their Colleague, Fix it with AI, Explain & check and the quick
+helpers) runs on the **team setup**, the second setup in AI setup. A team
+member's own lesson is the one place where main chat runs on the team setup
+too; see **Lessons** below. The team setup may use only **Workspace-use** models,
+never a personal plan such as the owner's Claude or ChatGPT subscription (see
+[Personal-use AI subscriptions](ai-personal-use.md)).
+
+So that a team member is never dropped into a project whose AI cannot work for
+them, Vibe64 checks one thing when they open a project: **does the team setup
+have at least one Workspace-use model?** Until it does, team members cannot
+open any project in the workspace.
+
+## Who is checked
+
+- **Team members** are checked every time they open a project, including
+  practice (Learning) projects.
+- **The workspace owner is never checked.** The owner can always open every
+  project, whatever the team setup holds.
+- On Vibe64 running on your own computer there is only you, the owner, so the
+  check never applies.
+- Work that runs without a person (an AI turn already running, scheduled
+  checks) is not checked.
+
+## What counts as ready
+
+The team setup is ready when at least one of its roles (Colleague, Fix it with
+AI, Explain & check, Quick helper) uses a model whose connection is Workspace
+use and currently connected, for example DeepSeek through an API key. A role set
+to **Same as** another role counts as the model of the role it follows. A role
+that is off, a role that follows an empty role, a personal plan, or a
+disconnected connection does not count.
+
+The fastest way to get there is the team card in AI setup: **Let your team use
+this workspace: add a DeepSeek key (runs inside Claude Code)**. One key fills
+the team setup with the recommended DeepSeek models.
+
+## What a team member sees
+
+Opening a project before the team setup is ready shows **Team AI isn't set up
+yet** instead of the project:
+
+- "*Owner* needs to set up AI for team members before you can open projects
+  here." (*Owner* is the owner's name, or "The workspace owner" when the
+  workspace has no name for them.)
+- A highlighted line to pass on: **Ask *owner* to set up AI for team members.**
+- **Check again** re-reads the project once the owner says it is done. It opens
+  the project as soon as the team setup is ready.
+- **Back to projects** returns to the project list, where the workspace has one.
+
+The screen is the same on a phone, with the buttons full width and stacked.
+Nothing about the project changes while a team member waits, and their Account
+and AI Accounts pages stay open to them.
+
+## What the owner sees
+
+While the workspace has team members and the team setup is not ready, the
+owner's project list (where the workspace has one) shows **Team members can't
+open projects yet — Set up AI for team members so they can work here.** with
+**Set up team AI**, which opens AI setup at the team setup. The prompt disappears once the team setup has a
+Workspace-use model, or when the workspace has no team members.
+
+Project rows in the list can also show **N waiting**: messages team members
+sent to main chat that wait for the owner's approval.
+
+## Inside a project
+
+Once a team member is in, their AI work uses the team setup, and their messages
+to main chat wait for the owner's approval before they are sent (see
+[Main chat messages that wait for the owner's approval](main-chat-approvals.md)). If the owner
+later removes the last Workspace-use model, the team member's next project
+open shows the waiting screen again.
+
+## Lessons
+
+A lesson's practice project is private to its learner, so a team member's
+lesson does not wait for the owner. In their own practice project, a team
+member's main chat runs on the team setup and their messages go straight to it:
+
+- **Senior** and **Junior** use the team **Colleague** model, and Auto's Router
+  uses the team **Quick helper** model. **Custom** in **Chat mode** lists only
+  Workspace-use models, so the member may choose any of them for the lesson.
+- The composer says which AI it is: the placeholder "Message your lesson's AI —
+  *model* (team AI)" and, in **Chat mode**, "This lesson runs on the team AI:
+  *model*. Only you see this chat."
+- **Do it for me** (which sends a line's prompt to the lesson's main chat),
+  Check my work reviews and the lesson's Colleague use the same team setup.
+- A personal plan, such as the owner's Claude or ChatGPT subscription, is never
+  used, even when the team setup has no Colleague model. Then main chat says
+  "The workspace owner hasn't chosen a Colleague model for team members yet."
+  and the owner adds one in AI setup.
+- The owner's own lessons run on the owner's setup as before. Main chat in
+  every ordinary project still waits for the owner's approval.
+
+## What Colleague can do
+
+Colleague can explain this screen and the team setup. It cannot change the team
+setup for a team member: only the owner edits AI setup. A team member's Colleague
+itself needs the team setup, so Colleague can answer only once the team setup is
+ready; until then, ask the owner directly.
+
+Related topics: [AI model setups](ai-model-setups.md),
+[Personal-use AI subscriptions](ai-personal-use.md),
+[AI onboarding](ai-onboarding.md) and [Colleague](colleague.md).

package/docs/colleague-usage/temporary-chats.md

@@ -9,9 +9,11 @@ first chat. If another temporary or host conversation was selected, it stays
 selected with its draft intact. Dismissing the dialog has the same effect; no
 chat is created and no message is sent. This applies on desktop and narrow screens.
 
-Ordinary temporary chats offer **Custom**, **Senior** and **Junior**. Choose
-**Custom** to open the **Orchestrator**, **Model** and **Thinking** fields. Select
-an available connection and model, then **Apply**. The next message uses that
+Ordinary temporary chats offer **Fix it with AI**, **Custom**, **Senior** and
+**Junior**; a team member's offer **Fix it with AI** and **Custom**. **Fix it with
+AI** uses the model AI setup chose for fixes, which may run in a different tool
+from Main chat. Choose **Custom** to open the **Orchestrator**, **Model** and
+**Thinking** fields. Select an available connection and model, then **Apply**. The next message uses that
 choice and the existing conversation history. Main chat's selection is unchanged.
 
 ## Rename a temporary chat
@@ -70,10 +72,10 @@ message; uncertain delivery is checked before any resend.
 
 ## Hand a merge repair to another model
 
-**Fix it with AI** for an Update conflict opens a temporary repair using Senior
-and sends the repair instructions once. Its reply appears in that temporary
-chat; Main chat's history is unchanged.
-Merge repair always retains the Senior role. To hand it to Codex:
+**Fix it with AI** for an Update conflict opens a temporary repair on the Fix it
+with AI model and sends the repair instructions once. Its reply appears in that
+temporary chat; Main chat's history is unchanged.
+Merge repair stays in Fix it with AI mode or on a model you choose. To hand it to Codex:
 
 1. If it is still working, press **Stop** and wait for it to stop.
 2. Open its **Chat mode** icon and choose **Choose model**.

package/docs/colleague-usage/workspace-preparation.md

@@ -7,7 +7,7 @@ steps come from the project's setup contract.
 
 Select **Prepare workspace**. The notice shows progress while those steps run.
 Use **Expand** to inspect output, or **Dismiss** to hide an inactive notice.
-Preparation does not publish the project.
+Preparation does not save or push the project.
 
 To rerun preparation after success, select **Prepare workspace** (the wrench)
 in the session header. On narrow screens, open **Session actions** (three dots)
@@ -99,6 +99,55 @@ Colleague can explain this recovery; installing a local tool and restarting the
 local editor require the person to use their terminal.
 
 
+## A tool the step needs
+
+When a step fails because a program it runs isn't installed, the failed step
+says so in one sentence ("Vibe64 couldn't find bundle on this computer, so this
+step couldn't run.") and **This step needs a tool that isn't working** lists the
+missing runtime with its install command, **Check again** and **Other ways**.
+A long failure (a stack trace) shows as three lines; **Expand** shows all of it.
+The database server panel below waits until no tool is missing, so there is one
+thing to fix at a time.
+
+## A database server you run
+
+When the project's Stack declares a MySQL/MariaDB or PostgreSQL database and
+this computer supplies none itself, the person runs that server: one they
+already have, or one they install. After a preparation step fails, a
+**database server** panel appears under the failed step. It says whether
+Vibe64 could sign in, in one sentence: nothing answering at the host and port,
+a wrong user or password, a user that can only sign in from the computer's
+administrator account (such as `root` on a fresh MariaDB, or `postgres`), a
+missing database, or no access to it.
+
+The panel's fields are the project's Env values under the exact names the
+Stack declares (for example `DB_HOST`, `DB_PORT`, `DB_NAME` or `DB_DATABASE`,
+`DB_USER` or `DB_USERNAME`, `DB_PASSWORD`). **Save and check** saves them in
+Env and signs in for real with the drivers Vibe64 bundles; **Check again**
+repeats the sign-in. A saved password is never shown or sent back; an empty
+password field keeps it. Env values always win over the Stack's defaults, and a
+variable exported in the shell that started Vibe64 does not count.
+
+**Install or start** shows the command for this computer (Debian, Ubuntu and
+WSL, or macOS with Homebrew); its link opens the Databases step of the setup
+guide, which also has the Fedora and Arch lines ([Linux](set-up-linux.md#databases),
+[macOS](set-up-macos.md#databases)). **Create a login and
+database** shows one command that creates a project user, its database and,
+for PostgreSQL, the right to create test databases. **Suggest a user and
+password** fills in a project user and a strong password first; the command
+shows the password as dots but copies the real one. The person runs these
+commands in their own terminal; Vibe64 never starts a database server or runs
+them. While nothing answers, the panel leads with **Install or start** and
+folds the settings into one line, "Looking for it at host:port · database ·
+user", with **Change** to edit them. When the panel says connected, choose
+**Finish preparing** on it (or **Retry** on the failed step).
+
+Colleague can explain the panel and each message. When asked, it can check the
+server again with the current values and save the non-secret ones the person
+gives (host, port, database name, user name) in Env. It must not ask for,
+repeat or save a password, and it never runs `sudo` or creates databases
+itself; the password goes in the panel's password field.
+
 ## Resource recovery after a daemon restart
 
 When the host supports database preservation checks, reopening a previously

package/docs/templates/learn-topic/README.md

@@ -1,6 +1,6 @@
 # Copyable teaching topic template
 
-This is a complete directory template for an **incomplete draft topic**. It has one draft lesson in lesson format v2 (schemaVersion `2`): optional notes and three steps — a reading step (`none`), a multiple-choice step (`choice`) and a learner-ticked step (`self`) — with no exercise, automatic check or visual. Do not teach it or mark it published before human review. Check verdicts are final and come from each step's declared check (a lesson with an exercise may also use a `review` check, the learner's own AI judging their work against a rubric); Colleague never passes a step.
+This is a complete directory template for an **incomplete draft topic**. It has one draft lesson in lesson format v3 (schemaVersion `3`, stage `studio`: taught outside any project, since it has no exercise): optional notes and three steps — a reading step (`none`), a multiple-choice step (`choice`) and a learner-ticked step (`self`) — with no exercise, automatic check or visual. Do not teach it or mark it published before human review. Check verdicts are final and come from each step's declared check (a lesson with an exercise may also use a `review` check, the learner's own AI judging their work against a rubric); Colleague never passes a step.
 
 ## Copy and adapt
 
@@ -11,7 +11,7 @@ This is a complete directory template for an **incomplete draft topic**. It has
    ```
 
    Work in the copy. No dependency install or new application framework is needed for these content files.
-2. In the copied `package.json`, replace `name` with your `learn-` repository name, `vibe64Training.topicId` with a permanent topic ID, `domainId` with the intended domain ID, and `title` with the topic title. Keep version `0.1.0`, the topic manifest's schemaVersion `1` and status `preview` while drafting (lessons declare their own schemaVersion `2`). IDs start with a letter, contain only letters, digits or hyphens, and have at most 64 characters.
+2. In the copied `package.json`, replace `name` with your `learn-` repository name, `vibe64Training.topicId` with a permanent topic ID, `domainId` with the intended domain ID, and `title` with the topic title. Keep version `0.1.0`, the topic manifest's schemaVersion `1` and status `preview` while drafting (lessons declare their own schemaVersion `3` and `stage`). IDs start with a letter, contain only letters, digits or hyphens, and have at most 64 characters.
 3. Replace `TOPIC-01` with your permanent first lesson code: rename its directory and update the root manifest's `lessons[0].code` and `descriptor`, the lesson descriptor's `code`, the notes title and outline row. Keep the root entry `draft` and `required:true`.
 4. Write the outline's learner, prerequisites, final ability and lesson outcomes. Replace `notes.md` and each `steps/*.md` body with real text a learner can follow without AI. Edit `steps` in `lesson.json`: each step has a unique `id`, `title`, `body`, `check` and `required`. Use `choice` (`question`, 2–8 `options`, `answer` as 0-based option indexes), `self` (learner ticks **Done**), `none` (reading only, never required) or `auto` (a declared check; needs an exercise). At least one step must be required. Optional `guide` points at a real Vibe64 place and optional `visual` plays declared commands. Instead of a guide, a step body may end with a fenced `beats` block that the lesson step bar plays one line at a time (for example `show lesson-bar: This bar walks you through each step.`); see "Beats" in `docs/training-content.md`.
 5. To add lessons, copy the lesson directory to a new permanent code, update its code, title and steps, and append a `draft` entry with the correct descriptor path to the root manifest and outline. Declare earlier lesson prerequisites as `{ "code": "YOUR-01" }` and topic prerequisites as `{ "topicId": "another-topic" }`. Referenced lessons must exist, precede their dependants and have no cycles. A published lesson cannot require a draft lesson.
@@ -28,7 +28,7 @@ This is a complete directory template for an **incomplete draft topic**. It has
    ```
 
    Validation and bundling do not execute content, publish Git, install a topic or make drafts teachable. In a public Vibe64 development checkout, `node bin/run.js training ...` accepts the same arguments; run it from that checkout with the copied topic's absolute path.
-7. Add an exercise, an `auto` step or a visual only when you have a real source and a working check. Follow the installed `docs/training-content.md` reference (section **Lesson format v2: steps**) for exercise/check/visual descriptors, exact relative paths and declared auxiliary `assets`. Never point a step body, notes, visual or exercise at `lesson.json`: it holds the choice answers and is refused. Do not add fake readiness or capabilities to make a draft appear runnable.
+7. Add an exercise (then set the lesson's `stage` to `project`), an `auto` step or a visual only when you have a real source and a working check. Follow the installed `docs/training-content.md` reference (sections **Lesson format v3: stage and facts** and **Lesson format v2: steps**) for exercise/check/visual descriptors, exact relative paths and declared auxiliary `assets`. Never point a step body, notes, visual or exercise at `lesson.json`: it holds the choice answers and is refused. Do not add fake readiness or capabilities to make a draft appear runnable.
 8. Trial and review the lesson with a human learner, including mistakes, assistance, recovery and relevant desktop/mobile controls. Only then change its root entry to `published`. Keep the topic `preview` until every required lesson is reviewed and published. A `released` topic cannot contain required draft lessons.
 
 Before generating a course lock, add the real source repository as root `repository.url` in the format `https://github.com/<owner>/learn-<topic>.git`, commit the intended topic and leave it clean. Use the installed publishing guide for `vibe64 training publish-manifest`; local lock generation does not create or publish a remote repository. A course chooses this whole topic, not a subset of its lessons.

package/docs/templates/learn-topic/training/lessons/TOPIC-01/lesson.json

@@ -1,7 +1,8 @@
 {
-  "schemaVersion": 2,
+  "schemaVersion": 3,
   "code": "TOPIC-01",
   "title": "Replace with the learner task",
+  "stage": "studio",
   "notes": "notes.md",
   "prerequisites": [],
   "estimatedMinutes": 15,