[MarcelT87]

Summary

Make repeated beginner installations/upgrades safer when a checkout already contains a stale or broken .venv.

Previously, install.sh reused any existing .venv directory without validating the interpreter or pip inside it. That could turn an otherwise valid host Python setup into a confusing pip/bootstrap failure.

Behaviour

The installer now:

• validates the host Python as before;
• reuses a healthy existing project-local virtual environment;
• detects a recognizable but unusable/unsupported virtual environment and recreates only .venv;
• verifies the recreated environment provides Python 3.11+ and pip;
• refuses to modify:
  • a symbolic link named .venv;
  • a non-directory named .venv;
  • an ordinary directory named .venv that does not contain pyvenv.cfg.

Unknown files are therefore never deleted automatically.

Runtime data such as data/, collected Evidence and contexts is not part of the repair path.

Beginner-flow coverage

CI now verifies that:

• rerunning the installer reuses a healthy virtual environment;
• a recognizable broken virtual environment is recreated automatically;
• existing data/ content survives that repair;
• an unknown .venv directory is rejected and its marker file remains untouched;
• removing that unknown directory and rerunning the normal installer succeeds.

Documentation

The install guide now explains safe reinstall/upgrade behaviour and what happens when .venv is damaged or unexpected.

Scope

Installer and beginner UX only.

No parser, Evidence, profile, bundle, submission or heating-system behaviour changes.