vibe64 0.1.39 → 0.1.40

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

@@ -1,7 +1,7 @@
-# Author a lesson and publish its source
+# Author a lesson and save its source
 
 Ask Colleague to coordinate a coding agent, review the lesson in the same session,
-and publish its source through the existing Save or pull-request workflow.
+and save its source through the existing Save or pull-request workflow.
 Colleague can operate those controls when requested; it does not edit files or
 run a shell itself. Git publication, pinned course material and installation are
 separate results. The current Getting started course has four step-based lessons
@@ -32,7 +32,7 @@ text needs a new immutable topic/course pin, keeping earlier learners’ version
 
 For example: “In this lesson-authoring project and session, improve the introduction's
 wording, keep its step IDs, checks and App/diagram contracts, validate and bundle it,
-arrange a review, then publish the source as a draft PR. Do not install or enable it.”
+arrange a review, then save the source as a draft PR. Do not install or enable it.”
 This is an example instruction, never authority to execute it without the person's
 actual request. A how-to question makes no edits, assignment or external write.
 
@@ -58,21 +58,21 @@ it does not mean published or installed. A preview can be published as preview
 source when requested. Pedagogical trial, real exercise and animation acceptance
 remain explicit requirements before claiming a reviewed course release.
 
-## Publish through the native repository workflow
+## Save through the native repository workflow
 
 After coding settles, inspect **Changes** and the exact repository/branch
 reported by the session. **Save** captures ALL current work, not selected files.
 A managed Vibe64 Git Save updates its canonical project; a GitHub Save pushes to
 the reviewed repository branch. Colleague can request native Save after an explicit
-Save/publication instruction and passes its unchanged destination review. It
+Save instruction and passes its unchanged destination review. It
 cannot bypass active-agent, stale-source, account or required-PR rules, or discard
-unrelated work to make publication pass. An ambiguous target stays unresolved.
+unrelated work to make Save pass. An ambiguous target stays unresolved.
 On mobile, reveal the project and use its Dashboard section chooser for Changes
 or Pull requests. The same native Save/PR permissions and review apply.
 
 For a required or requested PR workflow, Colleague can use the existing PR creation
 operation with the reviewed destination and requested title/body; draft is the
-default. PR creation saves and publishes the session's work. An already bound PR
+default. PR creation saves and pushes the session's work. An already bound PR
 is returned rather than silently edited. **Pull requests** shows actual remote
 source/base commits, checks and review blockers. Marking a draft ready or merging
 requires the person's corresponding instruction and the original fresh review;
@@ -80,10 +80,10 @@ creating a PR does not authorise merge. Use only a repository-enabled merge meth
 covered by that instruction. Save, PR creation or merge never deploys Vibe64.
 
 After success, report the actual saved destination or returned PR and current
-remote status. A coding agent's “pushed” message is not publication proof. After
+remote status. A coding agent's “pushed” message is not proof that Save pushed. After
 an uncertain result, inspect the original operation/PR before a deliberate retry;
-`published_needs_reconcile` means publication happened and local reconciliation
-still needs recovery. Do not republish automatically. Existing **Update this
+`published_needs_reconcile` means the push happened and local reconciliation
+still needs recovery. Do not push again automatically. Existing **Update this
 session (rebase)** and coding-agent conflict repair apply only when requested.
 
 ## Validate, bundle and pin
@@ -190,7 +190,7 @@ In supported hosted installations, ask Colleague to admit your exact clean
 committed snapshot from the authorized authoring session. Then open Learning with
 **L**; on its **Courses** tab the **Author trial** card shows the snapshot's lesson
 and release, and **Resume author trial** opens it in the ordinary lesson reader, the page's **Lesson** tab. This saved trial has isolated progress; it is not an
-enabled learner course. Ordinary **Start** still requires a published lesson in
+enabled learner course. Ordinary **Start lesson** still requires a published lesson in
 an enabled release. Local validation/bundling alone admits no trial. Do not change
 a draft's status to bypass that guard or report a trial as published progress.
 
@@ -198,7 +198,7 @@ Internal snapshot acquisition also retains the authoring session's normal
 source protections: AI work, pending review or cleanup, and Workspace setup
 must finish before its committed content can be captured. A closing, renewing
 or unavailable source is refused. The saved trial control captures no source,
-automatically stops no work and does not publish the source.
+automatically stops no work and does not save or push the source.
 
 A workspace operator can now provision approved local lesson content through the
 terminal commands documented in [Local operator provisioning](../training-content.md#local-operator-provisioning).

package/docs/colleague-usage/lesson-step-bar.md

@@ -1,21 +1,21 @@
 # The lesson step bar
 
 The yellow lesson step bar above the project page plays the current lesson
-step: its position, beats, **Step** and **Courses**. The rest of
+step: its position, beats, **Lesson** and **Courses**. The rest of
 Learn mode is in [The Learning environment](learning-environment.md).
 
 In Learn mode, while your lesson is loaded, a yellow bar above the project page
 names the lesson and shows **Step N of M** with the step's title and status.
 **Previous step** and **Next step** (arrow buttons) move through the steps.
-**Step** (the ≡ button) opens the whole current step right under the bar, in
-place, with everything the Lesson tab offers for it: its text, diagram and
-**Play**, **Done**, **Mark as done**, its question or **Check now**, **Show me**,
-**Teach me** and **Previous step**/**Next step**. It covers the top of the page
-(at most about two thirds of the screen, scrolling inside); **Step** again or
-Escape closes it, and **Show me** closes it so the place it shows is in view.
-This tab remembers whether it is open. To read the step in the page's
-**Lesson** tab, select that tab (see [The Lesson tab](learning-environment.md#the-lesson-tab));
-the bar has no separate Open button. **Courses**, at its right end (a book icon
+**Lesson** (a school-cap icon), on a lesson with a practice project, shows the
+lesson in the project pane at its current step, with everything for it: its
+text, diagram and **Play**, **Done**, **Mark as done**, its question or **Check
+now**, **Show me**, **Teach me**, **I'm stuck** and **Previous step**/**Next
+step** (see [The Lesson pane](learning-environment.md#the-lesson-pane)). It
+stays pressed while the lesson shows, and the header's **Preview** or **Dash**
+leaves it. On a lesson without a practice project the lesson is already the
+whole page, so the bar has no **Lesson** button.
+**Courses**, at its right end (a book icon
 on a phone), opens the Courses overlay to choose another lesson. The bar is
 always shown in full; it cannot be collapsed or hidden. On a phone the lesson
 name is hidden.
@@ -50,8 +50,8 @@ current one), then the beat's line:
   it opens the place (or the file), reveals and focuses the coding chat, opens
   Courses or Colleague (without asking it anything), reloads the Preview, or
   sends the line's quoted prompt as your next message in the practice
-  project's Main chat. That message shows a **Sent by the lesson** chip under
-  it. On a **Save** line it only points at **Save**: saving stays yours. On a
+  project's Main chat (for a team member, on the team AI, with no owner
+  approval). That message shows a **Sent by the lesson** chip under it. On a **Save** line it only points at **Save**: saving stays yours. On a
   line about waiting for the agent, pressing the App's button, minimising
   Colleague or pressing **L** there is no Do it for me (for **L** it shows
   where the button is). If it cannot be done here (for example the chat cannot take a
@@ -66,21 +66,21 @@ current one), then the beat's line:
   step at either end.
 - After the last beat the bar shows the step's own control: **Done**, **Mark as
   done**, **Check my work** (an automatic check, or a review; a check that does
-  not pass says why under the line) or **Answer in Step** for a question, which opens the
-  step under the bar. When the step has passed it shows **Next step**. **I'm stuck**
+  not pass says why under the line) or **Answer in Lesson** for a question, which shows the
+  step in the Lesson pane. When the step has passed it shows **Next step**. **I'm stuck**
   (on a *do* line, and after the last beat of a step that **Check my work**
-  decides, until the step passes; also in **Step** beside **Teach me**) opens
+  decides, until the step passes; also in the Lesson pane beside **Teach me**) opens
   Colleague and asks it for help with this step (see `learning-with-colleague`).
   On a phone a *do* line keeps only **Do it for me** on the bar; **I'm stuck**
-  is then in **Step**.
+  is then in the Lesson pane.
   A step never moves on by itself.
-- **Show me** on such a step (in the bar's step or the Lesson tab) plays its
+- **Show me** on such a step (in the Lesson pane) plays its
   beats again from the first one.
 
 **Check my work on a reviewed step.** Some steps are checked by a review of
-your work: the bar's line (and the step under **Step**) shows what the review
-looks for. **Check my work** uses your own AI (the Lesson review route in AI
-Accounts → Model routing) to look at the changes in your practice project
+your work: the bar's line (and the step in the Lesson pane) shows what the review
+looks for. **Check my work** uses your own AI (the **Explain & check** model in
+AI Accounts → Models) to look at the changes in your practice project
 (and, when the step says so, your coding chat); the line says **Checking your
 work with your AI…** for up to about a minute, without a Cancel. **Passed ✓**
 with the reviewer's comment passes the step for good. **Not yet:** says what
@@ -93,6 +93,6 @@ runs a review or passes a step for you.
 
 This tab remembers the beat and the pause; another tab or device starts the
 step at its first beat. On a phone the bar has two lines: the position and arrows above,
-the beat's line and its one button below; **Step** and **Courses** show only
-their icons, and the open step fills the width. A step without beats shows its title
+the beat's line and its one button below; **Courses** shows only its icon
+and **Lesson** its icon and name. A step without beats shows its title
 and status as before, and **Show me** when it can point at a place.

package/docs/colleague-usage/main-chat-approvals.md

@@ -0,0 +1,150 @@
+# Main chat messages that wait for the owner's approval
+
+A project's Main chat always runs on the workspace owner's AI. When a team
+member writes in Main chat, the message does not reach the assistant straight
+away: it waits in **Messages for approval** until the owner approves, edits or
+declines it. The owner's own messages are sent as usual and never wait.
+
+Temporary chats, Colleague and the other assistants a member uses run on that
+member's own team setup; only Main chat waits for approval.
+
+A team member's own lesson is the exception. A practice project is private to
+its learner, so its Main chat runs on the team setup and the member's messages
+(and the lesson's **Do it for me** prompts) are sent straight away, with no
+approval. The composer then reads "Message your lesson's AI — *model* (team
+AI)". See **Lessons** in [Team AI access](team-ai-access.md). The owner's own
+lessons are unchanged. Messages sent by
+another session (project messages) are not person requests and never wait.
+
+## Send a message as a team member
+
+1. Open the project's coding session. Main chat shows the hint
+   "Main chat runs on {owner}'s AI. {owner} approves each message." and the
+   placeholder "Message main chat — {owner} approves before it's sent".
+2. Type the message and choose **Send for approval**. The button keeps that
+   label while the assistant is working; members have no separate Steer button.
+3. A card appears directly above the composer: **You** with the time, the line
+   "Waiting for {owner} to approve", the message and a **Waiting** chip.
+
+Messages for approval are text only: the member composer has no attachment
+button. A request that carries attachments is refused with "Messages for
+approval are text only. Remove the attachments and send again."
+
+You can have up to 5 messages waiting in one session. A sixth is refused with
+"You have 5 messages waiting. Wait for {owner} to review them, or withdraw one."
+
+If the assistant was working when you sent the message, the card adds: "Sent
+while the assistant was working. It joins the current turn if it's still running
+when {owner} approves." Otherwise the approved message starts a new request.
+
+### Change or withdraw a waiting message
+
+- **Edit** replaces the text with a box. Change it and choose **Save**, or
+  **Cancel** to keep the original. An empty text is refused with "Write a
+  message, or withdraw it."
+- **Withdraw** removes the message from the queue. It stays as the one-line row
+  "Withdrawn by you".
+
+Only the sender can edit or withdraw, and only while the message is waiting.
+If the owner has already decided, the change fails with "This message was
+already sent." (or declined or withdrawn); if it is being sent, with "This
+message is being sent."
+
+### What you see after the owner decides
+
+While the chat is open you get a snackbar: "{owner} approved and sent your
+message" or "{owner} declined your message". The card becomes a one-line row:
+
+- **Sent by {owner} · time**, with "· Edited by {owner}" when the owner changed
+  the text first, and **Show in chat**, which scrolls the conversation to the
+  delivered message.
+- **Declined by {owner} · time**, with the owner's note quoted underneath when
+  they wrote one.
+
+Under each row is the start of the message on one line. On a declined or
+withdrawn row, select it to show the whole text, to copy, rework and send it
+again.
+
+The delivered message appears in Main chat as an ordinary user message with the
+line "{sender} · approved by {owner}" under its text. The assistant's reply is
+visible to everyone with access to the project.
+
+Decided rows stay for 24 hours; at most three show at once and the rest are
+behind **Show earlier (n)**.
+
+## Review messages as the owner
+
+New messages announce themselves in several places:
+
+- In any open tab where you have that project's Main chat open, a snackbar
+  "{sender} sent a message for your approval in {project}" with **Review**,
+  which selects the session and scrolls to the waiting messages.
+- A **{n} waiting** chip in the Main chat header; choose it to reveal the queue.
+- The browser tab title starts with "({n}) " while any messages wait.
+- Project lists that support it show a **{n} waiting** badge on the project.
+
+Each waiting card shows "{sender} wants to send · time", the message and these
+actions:
+
+- **Approve & send** sends the message unchanged.
+- **Edit then send** opens a box with the message. Change it and choose **Send**,
+  or **Cancel**. The sender sees "Edited by {owner}" on the Sent row.
+- **Decline** opens "Add a note for {sender} (optional)", up to 500 characters.
+  Choose **Decline** to confirm, or **Cancel**.
+
+While your approval is being delivered the chip reads **Sending…** and the
+buttons are disabled. The owner cannot edit or withdraw a member's message other than by
+approving it with edited text.
+
+### How an approved message is delivered
+
+Approving sends the message exactly as if you had sent it yourself, on your AI:
+
+- No turn running: it starts a new request (in Auto, the Router classifies it).
+- A turn is running that accepts guidance (including Auto working or an active
+  goal): it joins that turn as guidance.
+- A turn is running that cannot take guidance, a delivery is uncertain, or
+  recovery is in progress: the send fails, the message goes back to **Waiting**
+  and the card shows "Couldn't send: {error} Try again." Choose
+  **Approve & send** again when the turn finishes.
+
+If a page reload interrupts a send, the card may stay on **Sending…** with
+**Send again**. Sending again reuses the same delivery, so the message is never
+delivered twice. Its text can't be edited while it is sending; an edited text
+is always a new delivery.
+
+If the sender edited the message after you opened it, your action fails with
+"{sender} changed this message. Review it again." Read the new text and decide
+again.
+
+## Other team members
+
+Members who did not send a message see the same cards, headed "{sender}", with
+"Waiting for {owner} to approve" and no actions.
+
+## Phone
+
+On a phone the queue collapses to a bar above the composer, "{n} messages
+waiting for approval" (or "Messages for approval" when only decided rows
+remain). Tap it to open the **Messages for approval** sheet with the same cards;
+buttons stack full width and Edit or Decline open inside the sheet. Close the
+sheet with its close button or by tapping outside it.
+
+## What Colleague can do
+
+Colleague can explain all of this. When a team member asks Colleague to send a
+message to Main chat, it goes through the same queue and waits for the owner;
+Colleague must say so rather than claim it was delivered. In the member's own
+lesson there is no queue: the message is sent to the lesson's team AI. Approving, editing,
+declining and withdrawing are human-only: Colleague cannot do them, so it should
+point the person to the buttons above.
+
+## Errors
+
+| Message | Meaning |
+|---|---|
+| Only the workspace owner can approve messages. | A member tried to approve or decline. |
+| Only {sender} can change this message. | Someone else tried to edit or withdraw it. |
+| {sender} changed this message. Review it again. | The text changed since you looked. |
+| This message was already sent. / declined. / withdrawn. | It has been decided. |
+| This message is being sent. | Delivery is in progress; wait for it. |

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

@@ -49,7 +49,11 @@ 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.
 On a computer without managed browser runtimes, the agent runs the project's own
-Playwright (`npx playwright test`). If that browser is missing, the agent reports
+Playwright (`npx playwright test`). Interactive Preview checks (screenshot, eval)
+use the project's own Playwright, or else the `playwright` command installed on
+this computer, so a project in another language needs no Playwright package. If
+neither exists, the agent asks you to install Playwright on the computer rather
+than adding it to a non-Node.js project. If that browser is missing, the agent reports
 it and asks you before running `npx playwright install chromium`; installing it
 is your decision.
 

package/docs/colleague-usage/project-language-tools.md

@@ -20,7 +20,16 @@ onboarding does not offer PostgreSQL variants yet (for example
 `django-postgresql`); it offers the MySQL or SQLite variant instead.
 
 If **Preparing workspace** fails, expand its output, correct the reported cause
-and choose **Retry**. If Preview cannot start, use **Show run output**. On mobile,
+and choose **Retry**. On your own computer, the panel also lists the tools that
+step uses: each one that runs shows its version and where it was found; one that
+is missing or didn't start shows one sentence, the install command for this
+computer with a copy button, **Check again** and **Other ways**. Language
+runtimes install with mise (`mise use -g ruby@3.4`, `mise use -g python@3.13`,
+`mise use -g java@temurin-25`), which needs no administrator password; build
+tools and libraries for native packages (`cpp`) use `sudo apt install …` on
+Debian/Ubuntu or `brew install …` on macOS. **Other ways** opens the setup
+guide for this computer ([Linux](set-up-linux.md), including Fedora and Arch,
+or [macOS](set-up-macos.md)), which also explains adding mise to your shell. Coming back to the tab checks again. If Preview cannot start, use **Show run output**. On mobile,
 open **Show project** first. A missing runtime needs installation by the host
 administrator; changing the declaration to `shell` does not supply the missing
 tool. Standalone users install/configure the missing tool in their own environment
@@ -31,6 +40,11 @@ interpreter installed does not prove that the project consumes the selected
 library: the project's declared verification must demonstrate that. Normal
 release inputs and unrelated sessions keep their own source selection.
 
+When a runtime is missing, the coding agent stops and says which one, pointing
+to the tool row's command. It never runs `sudo` and never installs a runtime into
+the project folder (for example with `mise use` without `-g`).
+
 Colleague can explain preparation errors and offer its supported status/retry
-actions. These instructions do not give it shell access or permission to install
+actions. On your own computer it can also check whether a named tool runs now,
+for example after you ran an install command. These instructions do not give it shell access or permission to install
 host software. The coding agent can repair project commands after being asked.

package/docs/colleague-usage/project-settings.md

@@ -19,7 +19,7 @@ Gradle, NuGet (.NET) or custom; it is independent of the relationship.
 Custom requires a Preparation script path relative to this project, with its
 runtime declared in Stack. Every other type disables and clears the script; the
 project's own declared Verify command, not Vibe64, treats that source.
-Use **Save connected projects** for the list; ordinary project Save publishes
+Use **Save connected projects** for the list; ordinary project Save pushes
 that source edit. See **Configure connected projects** for access and recovery.
 
 Hosted repository settings can also specify whether GitHub Save permits direct

package/docs/colleague-usage/project-setup.md

@@ -34,8 +34,9 @@ which should be the default. Supply an email, login or user ID, not a password.
 The agent should reuse answers you already gave and wait for your choices.
 Choosing a name such as “admin” does not grant that account administrator rights.
 
-The coding agent can implement the application's Preview identity adapter after
-you accept that work. It can also save the named accounts you give or confirm
+An application with login accounts gets a Preview identity adapter by
+default: when it is missing, the coding agent sets it up as part of the work
+rather than asking first. It can also save the named accounts you give or confirm
 (for example `admin` and `user` with their emails) and then verify each in Preview;
 it never creates accounts or changes roles for this. To configure them yourself,
 open **Dashboard > App access** and use **Managed app access > Add identity**. Enter **Name**, **App identifier**
@@ -55,15 +56,24 @@ work. Public applications and non-web projects do not need preview accounts.
 ## New project
 
 1. Open the project and create or select its coding session. At **What would you
-   like to build with?**, review the available starter cards. The installed JSKIT
-   starters include **JSKIT · Public app** (no accounts or database) and
-   **JSKIT · Accounts and database** (sign-up, login and MySQL persistence).
-   Available starters depend on the installation; do not assume an absent card exists.
+   like to build with?**, review the available starter cards, grouped by
+   technology. The official catalogue lists JSKIT first: **JSKIT · Basic app**
+   (no accounts or database), **JSKIT · Database app** (MySQL, no accounts) and
+   **JSKIT · Accounts app** (sign-up, login and MySQL). Then one **Basic app**
+   each for Django, Rails, Spring Boot, Express and Next.js: a small notes form
+   saved to SQLite (MySQL/MariaDB for Spring Boot), with ready tests. Only the
+   Rails starter has sign-in, with a seeded development account
+   (`developer@example.com` / `developer`); for the others, ask the agent to add
+   accounts. Available starters depend on the installation; do not assume an
+   absent card exists.
 2. Choose **Use this starter →** on the intended card only when it matches the
    product you want. Preparation adds it to this session; use the session's
    **Save** control to keep the work in the project. A failed application reports
    its error and preserves existing work.
-3. Alternatively, choose **Start through conversation** to open Temporary AI for
+3. You can also describe the app directly in the session's main chat. In an
+   empty folder that was never set up, the coding agent first initializes Genesis,
+   then proposes a Blueprint and the matching Stack components for your answer.
+4. Alternatively, choose **Start through conversation** to open Temporary AI for
    project creation. Discuss what you want, who uses it and its first useful
    outcome before choosing technology. If no starters are configured, this
    conversation route is still offered when a coding assistant is available.

package/docs/colleague-usage/publishing.md

@@ -0,0 +1,185 @@
+# Publish your project as an app or package (Publish)
+
+**Dashboard → Publish** is where a project becomes something people install: an
+app on your own phone, or a package on a registry. On a phone, open Dashboard,
+then choose **Publish** from the **Dashboard section** menu.
+
+The page has four parts:
+
+- **Releases use your saved work**: the saved commit and branch a release
+  would use, whether it is pushed, whether the project's checks passed on it,
+  and each package from Packaging with its current version.
+- **Targets**: one card per place a release goes, followed by an **Add
+  target** tile. With no targets yet, the page offers the destinations, those
+  this project can use first: **Install on my phone**, **GitHub Releases**,
+  **npm** and **PyPI**. One that cannot be used yet says why (for example
+  "Needs a Python package in Packaging" or "Needs this project's repository
+  on GitHub"). Each shows what it needs, how long the first and later releases
+  take, and what it costs.
+- **History**: every release and dry run with each step, each target's outcome
+  and its proof, and **Full log**. A running release updates live; you can
+  leave the page and it carries on.
+- **Accounts & keys** (top right) and **Release** (top right).
+
+If the project has no `## Packaging` section yet, the page says **Tell Vibe64
+what to build** instead of showing targets. Ask Colleague or a coding
+conversation, for example "Set up packaging so I can install this app on my
+phone", review the change and Save it.
+
+### Publishing keys and accounts
+
+**Accounts & keys** keeps every sign-in and install key Vibe64 uses for
+publishing in one file in your home folder, encrypted under a passphrase of at
+least 12 characters (an `age` file any age tool can open). Create it once;
+afterwards **Unlock** it for 15 minutes when you add accounts or publish, and
+**Lock** it any time. Vibe64 cannot recover a forgotten passphrase.
+
+- **Add account**: npm (an access token and the registry address), PyPI (an
+  API token and the upload address) or GitHub (**Use my GitHub CLI sign-in**,
+  or paste a token). Tokens go straight into the keys file; the page and
+  Colleague only ever see the account's name and address.
+- **Replace token** (the key icon on an account) keeps the account's name and
+  address, so targets using it keep working with the new token.
+- **Recovery kit**: **Save kit** (or **Manage**) downloads every key as one file under a second
+  passphrase; keep both off this computer. **Restore** brings them back on a
+  new computer. The panel says when a key is newer than your last kit.
+
+### Add a target
+
+**Add target** (or a destination tile) asks where the release goes, then which
+package (only packages that destination can publish are offered) and which
+account. **What it needs** marks what this project and your keys already have.
+npm also takes an optional tag such as `next`; empty means `latest`. When the
+dialog asks for an account, **Add account** opens Accounts & keys and, when you
+press Done, comes back to the same target. A card's **⋮** menu switches the
+target to another account of the same kind or removes it. Targets are kept by
+Vibe64 for this project on this computer, not in the project's files.
+
+### Release
+
+1. **Release → Version**: each package offers its saved version **as saved**
+   while no release has published it, then the next patch, minor and major.
+   Releasing as saved needs no session. A new version needs one: **Write
+   1.4.3** puts the version bump and a `CHANGELOG.md` entry (drafted from the
+   saved commits in **What's new**) into the session as an ordinary change;
+   review it and **Save** it. Without a session the dialog says so and offers
+   **Release as saved** while the saved version is still unpublished.
+2. **Review & publish**: choose targets, unlock your keys if asked, and read
+   **Before publishing**: saved and pushed work, Packaging, tags still free,
+   checks passed, every sign-in valid, install key and recovery kit, Android
+   requirements. What needs attention comes first; the rest folds into **All
+   N checks passed**. A red line stops the release and the footer says so; an
+   amber one (a changed toolchain) needs **I understand**. Failed checks name
+   the check, **Show output** shows the end of its output and **Run again**
+   reruns it; a refused sign-in offers **Fix sign-in**; saved work that is
+   not on the remote yet offers **Push to origin** (fast-forward only, never
+   forced; it is the person's button, not a Colleague tool). **What happens** lists
+   the steps in order: build each package once, tag the saved commit, publish
+   to each target (with its account and address), under a short plan id such
+   as `Plan 3f9c`.
+3. **Dry run** builds once and asks each destination what would happen;
+   nothing is tagged or uploaded. It appears in History as a dry run.
+4. **Publish…** opens the confirmation: exactly which package goes where at
+   which version, the saved commit and tag. **Publish** there (with your
+   passphrase if the keys locked meanwhile) builds each package once, then
+   tags the saved commit and pushes the tag, then sends the same files to
+   every target and reads each back. A failed build therefore leaves no tag
+   behind. If the saved work, targets, the account a target signs in with, or
+   tools changed since you reviewed, it refuses and shows the new plan. Builds use the saved commit without the
+   project's Genesis and agent folders (`genesis/`, `.genesis/`, `.agents/`,
+   `.claude/`, `.codex/`, `.opencode/`), so packages never ship them. Builds
+   and **Run checks** run the project's own code the way Vibe64 runs any other
+   project command, with a throwaway home folder and none of your sign-ins.
+
+While a release runs each of its target cards shows **Publishing 1.4.3…**;
+afterwards a card shows the version people get, **Live · published …** and a
+**Verified** checksum read back from the destination: npm's integrity value,
+or for PyPI and GitHub Releases each file's own sha256 (the value pip and the
+release page show). The Publish page's
+**Checks** line runs the checks on the saved commit at any time and, when they
+fail, shows which check failed with **Show output**.
+
+When a build or upload fails, the target card says **Last release failed**
+with the reason; pressing it opens that release in History with the tool's
+own error output (credentials removed) and **Full log**. A release where some
+targets failed shows **Partly published**; fix the cause and **Finish this
+release** retries only the unfinished targets of the same plan (published
+targets are not sent again). If the fix changed the saved work, the button
+reads **Release the new saved work** and starts a new release instead; if the
+plan itself changed (for example a check or setting), **Finish this release**
+opens a new release with a note saying why. Long tool output keeps its start
+and end. Checks that fail without blocking show in amber. Errors appear as a
+short message at the bottom of the page.
+
+### Colleague and publishing
+
+Colleague can read the Publish state, suggest and write a version bump into
+the session, read the plan and preflight, start a dry run, read history and
+logs, and **ask** to publish. Asking only shows a banner, **Your Colleague asked
+to publish plan …**, with **Review** and **Dismiss**; **Review** opens the same
+confirmation. Only your **Publish** press publishes. Colleague never sees a
+token, key, passphrase or file path, and cannot add accounts, unlock keys,
+accept a licence or confirm.
+
+How publishing works underneath:
+
+Package registries Vibe64 releases to:
+
+- **npm**: an `npm` package is packed once with `npm pack`; a dry run shows the
+  exact files and what changed since the version people install today. Proof
+  is the registry's own integrity value. Undo means moving `latest` back to an
+  earlier version (npm versions cannot be replaced).
+- **PyPI** (or TestPyPI): a `python-dist` package's sdist and wheel pass
+  `twine check` first. Versions use PyPI's spelling, so `1.5.0-rc.1` is
+  published as `1.5.0rc1`. Undo means yanking the release on pypi.org, which
+  Vibe64 links to; a file name can never be reused.
+- **GitHub Releases**: the built files are attached to the release of the tag
+  Vibe64 put on your saved commit, as draft, prerelease or latest. Undo means
+  making an earlier release latest again.
+- Re-running a release that already reached a registry is safe: the same
+  version with the same files counts as done. The same version with different
+  files is refused; choose a new version instead.
+- A project that already versions with Changesets, release-please,
+  setuptools-scm or similar keeps that tool; its Packaging says
+  `Version from: external` and Vibe64 only reads the version.
+
+**Install on my phone** (Android, no store account):
+
+- The app's web client is a `web-bundle` package and the phone app a
+  `capacitor` package with an id such as `com.example.notes` (permanent once
+  people install it), a name, a 1024×1024 PNG icon with no transparency, and
+  one `Permission` line with a plain reason per capability (camera,
+  microphone, location, notifications, photos, contacts, calendar, bluetooth,
+  vibration). Native plugins are ordinary dependencies of the client at the
+  exact versions in its `package-lock.json`, on Capacitor 8; Vibe64 builds
+  with exactly those and stops if the lockfile disagrees.
+- The build needs Java 21 and the Android SDK (platform 36). Vibe64 shows the
+  Android SDK licence; only after **you** accept it does it download the SDK
+  into a folder in your home directory. It never accepts the licence for you.
+  The first build downloads about 2 GB in all and needs about 2 GB of free
+  memory; later builds take a minute or two.
+- The card lists three one-time tasks in order. **Android build tools → Set
+  up** shows Google's licence in full; **Accept and download** records your
+  acceptance and downloads Java and the SDK into your user cache folder.
+  **Install key → Create** makes the app's **install key** in your publishing
+  keys. **Recovery kit → Save kit** downloads a kit that includes it. Preflight
+  stops a phone release until all three are done.
+- Phones install an update only when it is signed with the same install key: a
+  lost key (and no recovery kit) means everyone must uninstall and reinstall.
+  On the command line, `vibe64-publish keygen app --out <folder>` creates a key
+  as two private files.
+- Every build gets a build number one higher than the last; it is never stored
+  in the project. After a release the card shows **Install on phone**: a QR
+  code your phone scans on the same Wi-Fi. Opened on an Android phone itself,
+  it offers **Download** directly, with **Show a QR code for another phone**. This computer shares only that one
+  APK, at an unguessable address, for 10 minutes or until you close the
+  dialog. **Download APK** saves it here instead; History offers both for
+  earlier releases.
+- Phones that installed this APK must uninstall it before installing the same
+  app from Google Play later (a different signing line). Since 30 September
+  2026, phones in Brazil, Indonesia, Singapore and Thailand install apps only
+  from developers verified by Google; this goes worldwide in 2027. Preflight
+  says so before a release.
+
+Colleague can open **Publish** for you and explain these steps. It cannot
+publish, confirm a release or see any credential.