vibe64 0.1.39 → 0.1.41

package/docs/colleague-usage/publishing.md

@@ -0,0 +1,187 @@
+# 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 and says how many came back ("Restored 1 key."). When a key is
+  newer than your last kit, the panel reads "Your recovery kit is out of date",
+  says when it was last saved, and offers **Save 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.

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**.