Publish verified Ubuntu 24.04 headless preview and user setup guide

docs/LINUX-HEADLESS.md

@@ -0,0 +1,91 @@
+# searchi on a Linux server
+
+Use the headless version to search your local files from a terminal or connect
+an AI agent through read-only MCP. It includes the Google EmbeddingGemma 2
+worker, automatic CPU/GPU selection with CPU fallback, and FFmpeg helpers.
+There is no desktop shell in this package.
+
+## Install and prepare search
+
+This initial x86-64 preview was checked on Ubuntu 24.04 in WSL. It requires
+GLIBC 2.39, GLIBCXX 3.4.32 and CXXABI 1.3.13 or compatible newer runtime
+versions. Older Linux distributions should build from source; this archive is
+not an all-distribution compatibility claim.
+
+Download into a new dedicated directory and verify before extracting:
+
+```sh
+mkdir -p "$HOME/Applications/searchi"
+cd "$HOME/Applications/searchi"
+curl -fLO https://tea.karlcom.de/karl/searchi/releases/download/v0.1.1/searchi-headless_0.1.0_linux-x86_64.tar.xz
+curl -fLO https://tea.karlcom.de/karl/searchi/releases/download/v0.1.1/LINUX-SHA256SUMS.txt
+sha256sum -c LINUX-SHA256SUMS.txt
+tar -xf searchi-headless_0.1.0_linux-x86_64.tar.xz
+./searchi --help
+./searchi setup --model-dir ./models
+```
+
+The package is approximately 103 MB. First model setup downloads approximately
+865 MB and reuses verified cached assets. Keep the runtime libraries and media
+helpers alongside the CLI. To use graphics acceleration, the system needs a
+compatible Vulkan loader and graphics driver; otherwise search uses CPU.
+
+Choose your own folder by replacing `/path/to/your/files` below:
+
+```sh
+./searchi index --db ./searchi.sqlite --root /path/to/your/files
+./searchi embed --db ./searchi.sqlite --model-dir ./models --embedding-worker ./searchi-gemma-worker
+./searchi search --db ./searchi.sqlite 'what you remember' --model-dir ./models --embedding-worker ./searchi-gemma-worker
+```
+
+Indexing names/content and embedding meaning are separate CLI steps. After
+changing files, run both again to refresh their local index. Add `--code-only`
+to search source implementations. For filenames/content without model inference,
+omit both model arguments. `--json --performance` reports basic measurements;
+`--debug-performance` enables detailed traces.
+
+## Connect your local agent
+
+Configure a stdio MCP client to run the absolute path to `searchi`, with these
+arguments using absolute paths:
+
+```text
+mcp --db /absolute/path/searchi.sqlite --model-dir /absolute/path/models --embedding-worker /absolute/path/searchi-gemma-worker
+```
+
+MCP searches the prepared index and reads only its cited excerpts. It does not
+index or mutate files. See [agent integration](AGENT-INTEGRATION.md).
+
+## Recorded package evidence, 2026-10-13
+
+Headless component version 0.1.0 is supplied alongside desktop release 0.1.1.
+All 89 selected engine/CLI and workspace lock/manifest files matched current
+Git archive bytes before a locked offline native release rebuild. Runtime source
+and recipe bytes were also compared; current worker SHA-256:
+`b52d50a1e676bd4bf64124daff1c4ce83d86a8bde01e4eaf09838cbb24a4c28f`.
+CLI SHA-256:
+`0a169112aab66f6b80d3696e6eb06bbd2a8ab8d1a845956353c897ab36691cdb`.
+
+Sixteen packaging tests passed in normal and optimized Python modes, including
+XZ member/checksum/mode equality and reproducibility. Actual extracted archive
+checks verified 29 files, relocated paths containing spaces, automatic media
+helper discovery, three newly encoded Google chunks (two documents plus one
+audio), German semantic document search, Code-scope source citation and strict
+extension filtering. A separate genuine CPU MCP preflight passed with this
+worker. No GPU provider was exercised.
+
+Archive: 103,295,132 bytes, SHA-256
+`940c1f871a8775723fc571018fd2f9f946f48528dac3fdea0888a3d90cacc8a6`.
+Public unauthenticated full-byte archive and checksum downloads matched local
+files. Ignored final report `.searchi/qa/linux-xz-current-runtime-smoke.json`,
+SHA-256 `35d4795469e6c22f778218161a97d160a3148a3a30a55435ef0c7f775601846b`.
+
+An earlier candidate used a historical staged worker and failed query startup
+with `Unknown worker option`. It was never published. The old archive remains
+locally as `searchi-headless-legacy-worker.tar.xz`; captured failure evidence is
+`.searchi/qa/linux-xz-release-diagnostic.json`. The corrected package uses the
+current runtime and passed the same full archive check.
+
+WSL CPU deployment proof does not establish broad distribution compatibility,
+clean-machine installs, real GPU fallback/parity, Linux desktop behavior or
+general media relevance. Those checks remain open.

docs/ROADMAP.md

@@ -11,6 +11,10 @@ release. Keep their evidence and unchecked production gates intact.
 - [x] Publish Windows desktop v0.1.1 with single-instance handling; verify public
   bytes and isolated genuine Google CPU launch. Existing user installation is
   not automatically upgraded. See [release evidence](WINDOWS-0.1.1.md).
+- [x] Publish the Linux x86-64 headless preview with current query-role runtime,
+  verified public bytes and genuine document/code/audio CPU archive checks on
+  Ubuntu 24.04 WSL. See [headless evidence](LINUX-HEADLESS.md); desktop, GPU and
+  broader distribution compatibility remain open.
 
 ## Required product scope (user clarification)