vibe64 0.1.38 → 0.1.40

package/docs/colleague-usage/running-vibe64-on-your-computer.md

@@ -12,22 +12,67 @@ run `PORT=3001 npx vibe64 --no-open` and open `http://127.0.0.1:3001` yourself.
 
 Nothing needs configuring. Vibe64 runs as you, with your own tools and folders.
 
+Setting up a computer for the first time? Follow the step-by-step guide for
+yours: [Linux](set-up-linux.md) (Ubuntu, Debian, Fedora, Arch),
+[macOS](set-up-macos.md) or [Windows](set-up-windows.md) (through WSL). Each
+covers Node.js, Git, an AI tool, project languages, build tools and database
+servers, and the **Other ways** links on tool rows open the matching section.
+
 ## Tools Vibe64 uses
 
 Vibe64 runs the tools already installed on your computer: the ones your
 terminal finds on its `PATH`, plus Homebrew's `/opt/homebrew/bin` on macOS.
 That includes Node.js, npm, Git and any language tools your projects need.
-Install or upgrade them the way you normally would; Vibe64 uses the new version
+Your own installs come first: `~/.local/bin`, mise's shims folder
+(`~/.local/share/mise/shims`) and the Claude Code, opencode, rustup and Bun
+folders are searched before the system folders, so `mise use -g python@3.13`
+beats an older system Python even before your shell profile is reloaded. On
+Debian and Ubuntu the newest `/usr/lib/postgresql/<version>/bin` is added, and on
+macOS Homebrew's PostgreSQL and MariaDB folders, so their programs are found.
+Install or upgrade tools the way you normally would; Vibe64 uses the new version
 the next time it runs a command.
 
+Vibe64 needs Node.js (the version it declares), Git and one AI tool. Everything
+else depends on the project: a tool row appears only where a step needs it, for
+example after **Preparing workspace** fails (see
+[Project language tools](project-language-tools.md)).
+
+On native Windows, `npx vibe64` stops and explains that Vibe64 runs on Windows
+inside WSL2 (Ubuntu), with a link to [Set up Windows](set-up-windows.md). With
+the wrong Node.js version it stops and shows the mise command that installs the
+right one, with a link to the guide's Node.js step: mise must also be added to
+your shell before a new terminal finds the new Node.js.
+
 - **AI agents.** Claude Code, Codex and opencode are used through their own
   commands, so each must be installed on this computer before you can use it.
-  See [AI accounts](ai-accounts-and-routing.md) for what to install and how to
+  See [AI accounts](ai-accounts.md) for what to install and how to
   check again.
 - **npm global installs** go wherever your own npm configuration puts them.
 - **Playwright** uses its own browser cache. If **Health** reports that
   Playwright or its Chromium is missing, install Playwright, then run
-  `playwright install chromium`.
+  `playwright install chromium`. The coding agent's Preview browser checks use
+  the project's own Playwright when it has one, otherwise the `playwright`
+  command installed on this computer (for example `npm install -g playwright`).
+  A Django, Rails or Spring Boot project therefore needs no Node.js packages
+  for these checks.
+
+## Git
+
+Vibe64 keeps each project's history with Git (2.28 or newer).
+
+- **Git missing or too old.** The repository button at the top of a project
+  says **Git needed** (or **Update Git**). Open it for the install command for
+  this computer, with a copy button; after installing, press **Check again**.
+- **A folder without Git.** The button says **No Git yet**. Open it and choose
+  **Start version control here** to start Git in that folder. Vibe64 never does
+  this by itself, and nothing is uploaded.
+- **Your name on commits.** Commits use the name and email from your own Git
+  settings. If Git has none, they are saved with a stand-in name ending in
+  “via Vibe64”, and **Health** and the Save result show the two
+  `git config --global` lines to set yours.
+- **Signed commits.** If your Git signs every commit (`commit.gpgsign`) and the
+  key needs a passphrase, Vibe64 can't type it. Make one signed commit in a
+  terminal to unlock the key, then try again. Vibe64 doesn't change the setting.
 
 ## Where Vibe64 keeps things
 
@@ -56,6 +101,9 @@ itself. To keep using the old location instead, start Vibe64 with
 
 ## Colleague
 
-Colleague can explain where Vibe64 keeps things and which tools it uses, and can
-open **Health** to check them. Installing tools, moving folders and restarting
-Vibe64 happen in your own terminal; Colleague cannot run them for you.
+Colleague can explain where Vibe64 keeps things, which tools it uses and every
+step of the setup guides. It can run **Health**, check whether a named tool runs
+now, check a project's database server and save non-secret connection values
+in **Env** when you ask. Installing tools, editing shell files, moving folders
+and restarting Vibe64 happen in your own terminal; Colleague cannot run them for
+you and never uses `sudo`.

package/docs/colleague-usage/sessions.md

@@ -1,9 +1,10 @@
 # Create and switch sessions
 
 Use **New session** (+), or **Create session** when there are no open sessions,
-to open **Start an AI session**. It lists **Claude Code** first, then **Codex**,
-then **OpenCode**, and preselects the first available one. Choose an available
-orchestrator, review any branch choice, then select **Create session** (or
+to open **Start an AI session**. It shows **Runs on your main AI:** and the main
+AI's model; every session runs on that AI setup, with no per-session tool
+choice. Select **Change** to open AI setup instead. Review any branch choice,
+then select **Create session** (or
 **Create branch & session**). While **Creating session…** is shown, the dialog
 shows a progress bar and explains that it is copying the project source. It stays open: clicking outside,
 pressing Escape, Close and Cancel cannot dismiss it. On success it closes and
@@ -25,9 +26,10 @@ followed by the project's setup steps. The assistant can start when preparation
 finishes; see [Prepare a session after updating its source](workspace-preparation.md)
 for failures and retry.
 
-Creation through an action without an explicit AI choice uses the first available
-workflow from the same picker. An explicit choice is preserved even when it is
-unavailable: fix its account or Model routing settings before retrying. Colleague
+Creation through an action without an explicit AI choice uses the main AI. An
+explicit model choice makes the new chat Custom and is preserved even when it is
+unavailable: fix its account or AI setup before retrying. A team member's new
+session still records the owner's main AI; main chat runs on the owner's AI. Colleague
 can read the available choices and explain recovery; it must not claim a failed
 request left no saved lesson without checking that lesson's current state.
 
@@ -144,8 +146,9 @@ permissions and confirmation still apply.
 
 ## Chat availability
 
-The chat checks which modes you can use and shows the effective assistant,
-shared-backup label or an actionable connection message. These lightweight
+The chat checks which modes you can use and shows the effective assistant or an
+actionable connection message. Modes that run on the owner's AI are not listed
+for team members. These lightweight
 checks do not start a model or download its repeated execution plan. Opening
 **Chat mode** still shows the available choices; access is checked again when
 work is sent. Colleague can explain an unavailable mode, but cannot grant access.
@@ -237,10 +240,15 @@ not require an AI connection. Archive or renewal already in progress still block
 You can still browse and work in other session tabs; the server-selected source
 link stays on the pinned session. Cross-project requests addressed to the
 server-selected session also keep that destination. Pinning does not Save,
-publish, freeze file contents, or deploy.
+push, freeze file contents, or deploy.
 
 The pinned session cannot be archived or renewed, and the project cannot close
 or be closed by idle cleanup. Closing your browser does not remove the pin.
+Idle cleanup otherwise closes an open project, with its Preview, terminals and
+assistant processes, 30 to 35 minutes after its last recorded activity (opening
+it, session changes and assistant work). Leaving the project or closing the
+browser does not close it sooner; close the project yourself to free its
+memory at once. A running assistant turn or active goal keeps it open.
 The pin survives server restarts. To change it, return to the pinned session and
 choose **Unpin session**; tab selection then controls the source link again.
 Other sessions show a disabled pin with **Unpin the project's pinned session first**.
@@ -248,7 +256,7 @@ Desktop and mobile use the same pin button beside Save. Learning sessions have
 no source pin. Separate project pins do not affect each other.
 
 Colleague can explain the pin or, on your explicit request, pin/unpin a named
-session through its session action. Source cleanliness and publication checks
+session through its session action. Source cleanliness and saved-work checks
 for host updates still apply to the pinned source.
 
 ## Answer clarification questions

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

@@ -0,0 +1,254 @@
+# Set up Linux for Vibe64
+
+A step-by-step setup for running Vibe64 on your own Linux computer: Ubuntu and
+Debian (also inside WSL on Windows), Fedora and Arch. 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.
+
+Commands that start with `sudo` ask for your computer password. Nothing shows
+while you type it; press Enter when done. Everything else installs into your
+home folder and needs no password.
+
+## Basic tools
+
+Vibe64 needs `curl` and `git`. Most desktops already have them.
+
+| System | Command |
+|---|---|
+| Ubuntu, Debian, WSL | `sudo apt install curl git` |
+| Fedora | `sudo dnf install curl git` |
+| Arch | `sudo pacman -S curl git` |
+
+Check: `git --version` prints a version (2.28 or newer).
+
+## Node.js and mise
+
+Vibe64 needs **Node.js 26**. Distribution packages are older, so install it
+with [mise](https://mise.jdx.dev/), which installs languages into your home
+folder without a password. Install mise:
+
+```sh
+curl -fsSL https://mise.run | sh
+```
+
+Then add it to your shell, so every terminal (and every program Vibe64 starts)
+finds the tools it installs. For **bash** on Ubuntu, Debian and WSL:
+
+```sh
+echo 'eval "$(~/.local/bin/mise activate bash)"' >> ~/.bashrc
+echo 'eval "$(~/.local/bin/mise activate bash --shims)"' >> ~/.profile
+```
+
+On **Fedora and Arch**, use `~/.bash_profile` instead of `~/.profile` in the
+second line (those systems read `~/.bash_profile` first). If your shell is
+**zsh**, use `activate zsh` and the files `~/.zshrc` and `~/.zprofile`. Other
+shells: see mise's [shell setup](https://mise.jdx.dev/dev-tools/shims.html).
+
+Now install Node.js and close the terminal:
+
+```sh
+~/.local/bin/mise use -g node@26
+```
+
+Open a new terminal. 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
+computer. 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/linux)"` |
+
+After installing, choose **Check again** on the row; no restart is needed.
+
+**Using your system's packages instead.** This works too, but needs a
+password and gives older versions.
+
+- Python on Ubuntu, Debian, WSL:
+  `sudo apt install python3 python3-venv python3-pip` (without
+  `python3-venv`, creating a virtual environment fails with “ensurepip is not
+  available”). Fedora: `sudo dnf install python3 python3-pip`. Arch:
+  `sudo pacman -S python python-pip`.
+- PHP on Ubuntu, Debian, WSL:
+  `sudo apt install php-cli php-mysql php-pgsql php-sqlite3 php-xml php-mbstring php-curl php-zip php-intl unzip composer`.
+  Fedora:
+  `sudo dnf install php-cli php-mysqlnd php-pgsql php-pdo php-xml php-mbstring php-intl php-pecl-zip composer`.
+  On Arch, use the php.new line above: Arch's own PHP needs extensions turned on
+  by hand.
+- Ruby from the system is not recommended: installing gems then needs a password.
+
+## Build tools
+
+Some packages compile native code (Rails gems such as `psych`, `pg` and
+`mysql2`, Python's `mysqlclient`), so they need a compiler and a few
+libraries. The row is called **Build tools**.
+
+Ubuntu, Debian, WSL:
+
+```sh
+sudo apt install build-essential pkg-config libyaml-dev libssl-dev zlib1g-dev libpq-dev default-libmysqlclient-dev libgmp-dev
+```
+
+Fedora:
+
+```sh
+sudo dnf install gcc gcc-c++ make pkgconf-pkg-config libyaml-devel openssl-devel zlib-ng-compat-devel gmp-devel libpq-devel mariadb-connector-c-devel
+```
+
+Arch:
+
+```sh
+sudo pacman -S --needed base-devel libyaml openssl zlib gmp postgresql-libs mariadb-libs
+```
+
+## 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. For MySQL projects, use MariaDB, the
+MySQL-compatible server Linux systems ship.
+
+| | MariaDB (for MySQL projects) | PostgreSQL |
+|---|---|---|
+| Ubuntu, Debian, WSL | `sudo apt install mariadb-server` | `sudo apt install postgresql` |
+
+Fedora, MariaDB:
+
+```sh
+sudo dnf install mariadb-server
+sudo systemctl enable --now mariadb
+```
+
+Fedora, PostgreSQL:
+
+```sh
+sudo dnf install postgresql-server
+sudo env PGSETUP_INITDB_OPTIONS="--auth-host=scram-sha-256" postgresql-setup --initdb
+sudo systemctl enable --now postgresql
+```
+
+Arch, MariaDB:
+
+```sh
+sudo pacman -S mariadb
+sudo mariadb-install-db --user=mysql --basedir=/usr --datadir=/var/lib/mysql
+sudo systemctl enable --now mariadb
+```
+
+Arch, PostgreSQL:
+
+```sh
+sudo pacman -S postgresql
+sudo -iu postgres initdb -D /var/lib/postgres/data --auth-local=peer --auth-host=scram-sha-256
+sudo systemctl enable --now postgresql
+```
+
+On Ubuntu and Debian the server starts by itself. If it is stopped later, start
+it with `sudo service mariadb start` or `sudo service postgresql start`.
+
+On Fedora, the PostgreSQL line above lets projects sign in with a password. A
+server set up earlier without it refuses password sign-ins; the panel then says
+the server “doesn't accept password sign-ins”. To fix it, change `ident` to
+`scram-sha-256` on the `127.0.0.1` and `::1` lines of
+`/var/lib/pgsql/data/pg_hba.conf`, then run `sudo systemctl reload postgresql`.
+
+**Give the project its own login.** The administrator accounts (`root` for
+MariaDB, `postgres` for PostgreSQL) only sign in from the computer's own
+administrator account, so projects need a login of their own. 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 a 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 MariaDB next to it; the two replace
+each other's packages.
+
+## Extras
+
+Nice to have; nothing depends on them.
+
+| Tool | Ubuntu, Debian, WSL | Fedora | Arch |
+|---|---|---|---|
+| GitHub CLI | `mise use -g gh` | `mise use -g gh` | `sudo pacman -S github-cli` |
+| ripgrep (faster search) | `sudo apt install ripgrep` | `sudo dnf install ripgrep` | `sudo pacman -S ripgrep` |
+| Browser for automated checks | `npx playwright install --with-deps chromium` | `npx playwright install chromium` | `npx playwright install chromium` |
+
+Playwright installs the libraries its browser needs only on Ubuntu and Debian;
+on Fedora and Arch, if the browser doesn't start, install the libraries it
+names. Don't install the GitHub CLI with snap. GitHub's own
+[install page](https://github.com/cli/cli/blob/trunk/docs/install_linux.md)
+lists the official package repositories.
+
+## 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 your terminal but Vibe64 can't find it, it is probably
+installed somewhere only your interactive shell knows. Check the `mise` lines
+above, then start Vibe64 again from a new terminal.
+
+## 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 your own 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-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.