feat: integrate Google semantic search and branded desktop launcher

docs/BUILDING.md

@@ -1,46 +1,118 @@
 # Build and release targets
 
-Install stable Rust, Node 22+, and native Tauri development prerequisites.
-On Windows install Visual Studio C++ build tools and WebView2. Linux needs
-WebKitGTK 4.1 development libraries. macOS needs Xcode command-line tools.
-See https://v2.tauri.app/start/prerequisites/ for platform details.
+Use stable Rust, Node 24 LTS, Python 3.11+, Git, CMake, and a native C/C++
+toolchain. Python provisions the pinned Google runtime and model; inference
+runs in a native process. Default Rust tests do not download model assets.
+
+Windows needs Visual Studio C++ build tools, a Windows SDK, and WebView2.
+Linux desktop builds need WebKitGTK 4.1 development libraries; macOS needs
+Xcode command-line tools. Follow the [Tauri prerequisites](https://v2.tauri.app/start/prerequisites/).
+Headless Linux CLI/worker builds do not need WebKitGTK or a display server.
+They still need a C/C++ compiler, linker, CMake, and Rust: SQLite, USearch,
+NumKong, and the Google worker contain native code.
+
+## Windows CPU development
+
+Run from the repository root. Building the worker clones a pinned llama.cpp
+revision and verifies/applies its memory patch. Model provisioning explicitly
+uses the network and verifies both Google assets, approximately 865 MB total.
+The Python CMake package is needed only when CMake is absent from PATH.
 
 ```powershell
+python -m pip install cmake
+python tools/embeddinggemma2/build_runtime.py --backend cpu --jobs 2
+python tools/embeddinggemma2/stage_runtime.py --backend cpu
+python tools/embeddinggemma2/download.py
+$env:SEARCHI_FORCE_CPU = '1'
+$env:SEARCHI_GEMMA_MODEL_DIR = (Resolve-Path .searchi/models/embeddinggemma2).Path
+$env:SEARCHI_GEMMA_WORKER = (Resolve-Path .searchi/runtime/cpu/Release/searchi-gemma-worker.exe).Path
+cargo fmt --all --check
+cargo clippy --workspace --all-targets --locked -- -D warnings
 cargo test --workspace --locked
-cd apps/desktop
+cargo test -p searchi-semantic --test gemma_cpu -- --ignored --nocapture
+cargo test -p searchi-service --test google_cpu -- --ignored --nocapture
+cargo test -p searchi-service --lib google_cpu_preserves -- --ignored --nocapture
+```
+
+The worker is statically linked with the MSVC CRT on Windows. Staging copies
+it and the llama.cpp license into the desktop resources directory. Add
+`--bundle-model` to staging for an offline model bundle after downloading;
+otherwise desktop setup provisions verified models on first launch. Search
+itself performs no network inference or downloads. Media weights are staged
+for future integration; the current worker supports text only.
+
+The desktop is a standalone Cargo workspace and needs separate validation:
+
+```powershell
+cargo test --manifest-path apps/desktop/src-tauri/Cargo.toml --locked
+Set-Location apps/desktop
 npm ci
+npm run format:check
+npm test
 npm run build
-# Windows VM: all rendering and inference tests must use CPU.
-$env:WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS='--disable-gpu'
+$env:WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS = '--disable-gpu'
 npm run tauri -- dev
 ```
 
-The desktop is a standalone Cargo workspace; validate it separately:
+Every Windows VM inference/rendering test must stay CPU only. Production
+supports `--backend auto|metal|vulkan|cuda` builds with CPU fallback; do not
+exercise those acceleration backends in this VM. Their execution and failure
+recovery require validation on the corresponding release hardware.
+
+## Headless Linux Google search
+
+These are the current script and CLI interfaces, not evidence of an executed
+Linux release. On a native Linux build host, run from the repository root:
 
 ```sh
-cargo test --manifest-path apps/desktop/src-tauri/Cargo.toml --locked
+python3 tools/embeddinggemma2/build_runtime.py --backend cpu --jobs 2
+python3 tools/embeddinggemma2/download.py
+export SEARCHI_FORCE_CPU=1
+cargo build --release -p searchi-cli --locked
+./target/release/searchi index --db searchi.sqlite --root /path/to/documents
+./target/release/searchi embed --db searchi.sqlite --model-dir .searchi/models/embeddinggemma2 --embedding-worker .searchi/runtime/cpu/searchi-gemma-worker --cpu-threads 1
+./target/release/searchi search --db searchi.sqlite 'supplier cancellation terms' --model-dir .searchi/models/embeddinggemma2 --embedding-worker .searchi/runtime/cpu/searchi-gemma-worker --cpu-threads 1
 ```
 
-## Cross-compilation
+`searchi setup --model-dir PATH` is an alternative verified model-provisioning
+command. It provisions model assets, not the native worker. Package the worker
+separately and pass its path to headless embedding/search. Each short-lived CLI
+search starts a model process; the desktop retains a prewarmed query worker.
 
-The Rust engine has no GUI dependency. Add the destination Rust target with
-`rustup target add TARGET`, then use `cargo build -p searchi-cli --target TARGET`.
-This requires the target linker, C toolchain and SDK because SQLite is compiled
-from bundled C. Target installation alone is insufficient. Document each
-verified host/target pair before treating it as supported.
+## Cross-compilation and native release matrix
 
-Desktop builds also need the platform webview libraries and packaging tools.
-Use native runners for dependable release builds. macOS signing/notarization
-needs Apple credentials and tooling. Windows installer cross-builds have
-additional Tauri caveats: https://v2.tauri.app/distribute/windows-installer/.
+The shared Rust engine/service has no GUI dependency. Install a destination
+Rust target with `rustup target add TARGET`, then build using
+`cargo build -p searchi-cli --target TARGET --locked`. This also requires the
+target C/C++ toolchain, linker, and SDK for bundled SQLite and the vector index.
+The separate native Google worker must be compiled for the same destination;
+installing a Rust target does not cross-compile it. The current Python runtime
+script configures the host toolchain; it does not expose a CMake cross-toolchain
+file interface. Record each verified host/target pair before claiming support.
+
+| Release host | Intended artifacts | Remaining validation |
+| --- | --- | --- |
+| Windows | Windows CLI, worker, desktop installer | Installer, upgrade, signing, GPU hardware |
+| macOS | Apple Silicon/Intel CLI, worker, desktop bundle | Native builds, architecture parity, Metal, notarization |
+| Linux | CLI, worker, desktop packages | Native builds, distribution ABI, webview, acceleration |
+
+Use native runners for dependable desktop releases. Platform webviews,
+packaging tools, SDKs, and signing impose additional constraints. macOS
+signing/notarization requires Apple tooling and credentials. See the
+[Tauri Windows installer cross-build caveats](https://v2.tauri.app/distribute/windows-installer/).
 
 ## CI and packaging gates
 
-Both Gitea and GitHub workflow files are provided. Gitea needs registered runners
-matching the configured OS labels; this repository does not provision runners.
-No Linux/macOS checks are considered passed until actual job evidence exists.
+GitHub and Gitea workflows define native OS matrices. Gitea requires registered
+runners matching its configured labels. A workflow declaration does not prove
+a platform was tested; Linux/macOS gates remain open until actual job evidence
+exists. Current workflow checks do not certify the separately built Google
+worker or execute downloaded-model tests automatically.
 
-Current bundles are disabled during development. Enable installers only after
-packaging icons, native smoke tests, CPU model distribution and license review,
-upgrade/migration tests, signatures and rollback checks are ready. Do not place
-private signing keys, repository tokens or model credentials in source control.
+Desktop bundles remain disabled during development. Before enabling release
+installers, stage the target worker, retain dependency/model notices, verify
+clean-machine launch and setup, run native Google smoke tests, and complete
+upgrade/migration, signatures, and rollback checks. Optional offline bundles
+need both verified model files. See [semantic bounds and evidence](SEMANTIC.md)
+for current text-only, corpus, and performance limitations. Keep signing keys,
+repository tokens, and model credentials outside source control.