#3968 install: Fresh install and smoke-test coverage tracker

Prerequisites

I searched open issues and this has not already been proposed.
I searched discussions and this is not already being debated there.
This is a concrete, actionable proposal, not a vague "it would be nice if..." request.

Area

Testing / CI

Problem or Motivation

Odysseus needs a clear fresh-install smoke-test contract.

The roadmap calls for fresh-install smoke coverage across Docker, native Linux, macOS, Windows, and WSL, but there is no single tracker that defines what "fresh install works" means for each supported environment.

Current state is fragmented:

Windows has a focused smoke-test issue: #2789.
Default Docker has at least one confirmed clean-install degradation: #3433.
Some older install-related reports contain useful evidence, but are too broad, stale, duplicated, or mixed with provider-specific setup problems.
Current CI has syntax checks and advisory pytest, but does not prove that clean installs can start and reach a usable baseline state across supported environments.

Without a shared smoke contract, contributors can keep fixing individual startup issues without knowing what baseline behavior the project expects.

This makes fresh-install reliability hard to review, hard to reproduce, and hard to improve safely.

Proposed Solution

Use this issue as the parent tracker for fresh-install and smoke-test coverage.

The goal is to define small, repeatable smoke contracts for each supported environment, then add focused child issues and PRs for each slice.

Initial target environments:

Environment	Goal	Status
Docker Compose	Clean clone can start, UI/API become reachable, optional services degrade clearly	Needs child issue / validation
Native Linux	Clean clone can install dependencies and start a usable server	Needs child issue
macOS	Clean clone can install dependencies and start a usable server	Needs child issue
Windows native	Launcher/smoke checks verify prerequisites and app availability	Existing issue: #2789
WSL / Git Bash	Launcher/path behavior is validated separately from native Windows	Needs child issue

Minimum smoke contract:

start from a clean clone or clearly documented clean environment;
install or verify required dependencies for that environment;
start the application or verify an already-running server only when the smoke mode explicitly says so;
confirm a baseline HTTP endpoint is reachable, such as /api/version or another agreed health endpoint;
confirm the UI can become available when applicable;
confirm optional services do not block baseline startup;
confirm degraded optional services are reported clearly instead of failing silently;
record exact commands and expected output.

Initial child / linked issues:

#2789 - Windows-native smoke-test slice.
#3433 - Default Docker FastEmbed cache-path issue that silently degrades vector functionality.

Prior-art / evidence, not direct children yet:

#2140 - contains useful Docker UI-readiness evidence, but currently mixes startup blocking with an unrelated SearXNG port configurability request.
PR #137 - contains useful macOS clean-install observations, but was closed without merge and bundled unrelated documentation, UI, icon, calendar, and provider changes.

Potential future child issues:

Define the canonical smoke contract and accepted smoke modes.
Add Docker Compose clean-clone smoke validation.
Add native Linux clean-clone smoke validation.
Add macOS clean-clone smoke validation.
Refine the Windows smoke script so its scope is explicit.
Add WSL / Git Bash launcher validation.
Add optional-service degraded-startup validation.

Working rules:

One platform or smoke contract per child issue.
One behavior slice per PR.
No broad launcher rewrites.
No provider-specific setup requirements in the baseline smoke contract.
No GPU benchmarking or GPU-specific provider tuning.
No full browser E2E framework until the basic smoke contract is agreed.
No claim of "fresh-install coverage" unless the test actually starts from a clean or clearly documented state.

Success criteria:

Each supported environment has a documented smoke command or manual validation procedure.
Each smoke check states whether it installs, launches, probes, or only validates prerequisites.
Docker clean-start behavior is validated separately from optional provider configuration.
Windows native behavior is validated separately from WSL / Git Bash.
Optional services can fail or be unavailable without blocking the baseline app startup, unless they are explicitly required by that environment.
Future install bugs can be routed under a clear parent instead of becoming scattered one-off reports.

Alternatives Considered

Adding each install-related issue directly to the Stabilization milestone was rejected because it would make the milestone noisy and harder to reason about.

Using #2789 as the parent was rejected because it only covers Windows native smoke checks.

Using #3433 as the parent was rejected because it is a specific Docker/FastEmbed defect, not a cross-platform smoke contract.

Using older Docker/Ollama threads as the parent was rejected because those discussions mix baseline install behavior with optional provider setup, host Ollama behavior, GPU runtime issues, and user-support details.

Prior Art / Related Issues

Directly related:

#2789 - Windows-native smoke-test slice.
#3433 - Default Docker FastEmbed cache-path issue affecting vector functionality.

Prior art / evidence:

#2140 - Docker UI-readiness concern, but mixed with unrelated SearXNG configurability.
PR #137 - macOS clean-install observations, but closed, stale, and too broad.

Explicitly not treated as direct children at this time:

#3817 - duplicate of #3433.
#3218 - ChromaDB architecture / support-mode expectation, not a baseline smoke contract.
#3648 - provider probing / host Ollama feedback.
#3846 - repeated-start performance and ownership behavior.
#1292 - drifted Docker/Ollama/provider-support thread.
#2341 - duplicate Windows python/python3 issue.
#3564 - optional Ollama setup documentation.

Are you willing to implement this?

Yes. I can help organize the tracker, validate existing candidate issues, and contribute small smoke-test slices where appropriate.

Current Next Step

Agree on the minimum smoke contract first.

After that, the first practical slices should be:

refine/validate the Windows smoke-test work in #2789 / PR #2719;
validate the canonical Docker FastEmbed issue #3433 and its competing fixes;
open focused child issues for Docker Compose, native Linux, macOS, and WSL once the smoke contract is clear.