Updates

docs/CI.md

@@ -68,10 +68,39 @@ DRY_RUN=1 bash scripts/gitea-rolling-release.sh
 | Forge plugin | `@qvac/sdk/electron-forge` + `@electron-forge/plugin-base` |
 | Config | `qvac.config.json` — LLM plugin only |
 | Asar | Forced **off** when QVAC packaging is enabled (Bare needs real paths) |
+| Bare runtime | `bare-runtime` + `bare-runtime-<host>` must be **inside** the app `node_modules` |
 | Skip | `PEARDATA_SKIP_QVAC=1` → tools-only client |
 | Auto tools-only | `win32-arm64` (no `@qvac/llm-llamacpp` prebuild) — still ships client |
 | Docs | [QVAC.md](./QVAC.md) · [Electron tutorial](https://docs.qvac.tether.io/tutorials/electron) |
 
+### Cross-host Bare runtime (issue #1492)
+
+CI runs on **Linux** but packages **darwin/win32** clients. `npm ci` skips optional
+`bare-runtime-darwin-*` / `bare-runtime-win32-*` packages (os/cpu filters). Without them
+the packaged app falls back to:
+
+```text
+Ready (tools-only: Could not load the Bare runtime binary for darwin-arm64 …
+```
+
+Release workflows and `make.cjs` install platform binaries via
+`scripts/ensure-qvac-bare-runtimes.cjs`, which **`npm pack` + extracts** each
+`bare-runtime-<host>` into `node_modules` (plain `npm install --force` is not
+enough — npm's os/cpu filters drop foreign packages and can prune siblings).
+
+```bash
+# after npm ci on the Linux runner
+node scripts/ensure-qvac-bare-runtimes.cjs --all
+
+# or only hosts you will package
+node scripts/ensure-qvac-bare-runtimes.cjs --hosts darwin-arm64,darwin-x64,linux-x64,win32-x64
+```
+
+`forge.config.cjs` also:
+1. Runs the ensure script in `prePackage` for the target host
+2. Copies `bare-runtime` + `bare-runtime-<host>` into the app if packager omitted them
+3. **Fails the package** if the Bare binary is still missing when QVAC is enabled
+
 Client package default timeout is **20 minutes** when QVAC is enabled (`PEARDATA_CLIENT_TIMEOUT_MS`).
 
 ## Key scripts
@@ -84,6 +113,7 @@ Client package default timeout is **20 minutes** when QVAC is enabled (`PEARDATA
 | `scripts/bare-standalone.cjs` | Pack Bare `peardata-server` |
 | `scripts/build-client-bundle.cjs` | esbuild GUI → `electron/app.bundle.cjs` |
 | `scripts/build-qvac-worker.cjs` | Local `bundleSdk` for QVAC Bare worker |
+| `scripts/ensure-qvac-bare-runtimes.cjs` | Force-install `bare-runtime-<host>` for cross-host QVAC clients |
 | `scripts/predownload-electron.cjs` | Pre-fetch Electron zips for CI |
 | `scripts/sign-macos-app.cjs` | Darwin client codesign |
 | `scripts/gitea-rolling-release.sh` | Build + stage + Gitea upload |

docs/QVAC.md

@@ -78,17 +78,25 @@ Produces a **tools-only** client (no LLM natives). QVAC tab still works via RPC
 
 QVAC spawns a **Bare** worker via `bare-runtime` + a platform package such as `bare-runtime-darwin-arm64`.
 
-These ship as **production dependencies** and are **not** stripped by forge for the package target host. If you see:
+These are listed under **optionalDependencies** (os/cpu-filtered). On a Linux CI runner
+`npm ci` will **not** install the darwin/win32 packages, so packaging must force-install them
+first (see `scripts/ensure-qvac-bare-runtimes.cjs` and [CI.md](./CI.md)).
+
+Forge keeps `bare-runtime` + `bare-runtime-<targetHost>` in the app and **fails the build**
+if the binary is missing when QVAC packaging is enabled.
+
+If you still see:
 
 ```text
 Could not load the Bare runtime binary for darwin-arm64
 … bare-runtime-darwin-arm64 … missing
 ```
 
-reinstall deps and rebuild the client:
+on a local or CI client:
 
 ```bash
 npm ci
+npm run ensure:qvac-bare-runtimes   # force-install all QVAC host binaries
 npm run make:client:darwin-arm64
 ```