From a4dbeb368d19f6afc0f6da3819c8e0d6242b0732 Mon Sep 17 00:00:00 2001
From: Christophe Besson <cbesson@gmail.com>
Date: Sun, 9 Aug 2026 21:55:12 +0200
Subject: fix: venv --clear required when copying repo across OS
 (Fedora→Ubuntu)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Root cause: certifi.where() in the Fedora venv points to
/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem which does not
exist on Ubuntu. 'python3 -m venv .venv' without --clear keeps the
Fedora certifi paths. Fix: always use --clear when recreating a venv
on a different OS.

Documented in QUICKSTART.md and CLAUDE.md.
rsync command updated to exclude .venv/ (in QE/server-state, not versioned).

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md          |  7 +++----
 docs/QUICKSTART.md | 19 ++++++++-----------
 2 files changed, 11 insertions(+), 15 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index fc28305..6293bdb 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -38,10 +38,9 @@ pip install -e packages/meshbay-common -e packages/meshbay-hub -e packages/meshb
 pip install httpx blake3 uvicorn pytest pytest-asyncio
 ```
 
-> **Bug pip + Python 3.14** sur Ubuntu et Fedora : `FileNotFoundError` dans certifi.
-> Passer `SSL_CERT_FILE` avant le premier `pip install` :
-> - Ubuntu : `SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt pip install ...`
-> - Fedora  : `SSL_CERT_FILE=/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem pip install ...`
+> **Ne jamais copier `.venv/` entre machines d'OS différents.** Si rsync depuis Fedora vers Ubuntu,
+> exclure `.venv/` et recréer sur la cible avec `python3 -m venv .venv --clear`.
+> Sans `--clear`, `certifi.where()` pointe vers un chemin Fedora inexistant sur Ubuntu → `FileNotFoundError`.
 
 ```bash
 # Lancer les tests
diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md
index b5ca327..2fa5af0 100644
--- a/docs/QUICKSTART.md
+++ b/docs/QUICKSTART.md
@@ -17,21 +17,18 @@ cd ~/meshbay              # le dépôt local (pas encore publié sur GitHub)
 python3 -m venv .venv && source .venv/bin/activate
 ```
 
-> **Bug pip + Python 3.14 (Ubuntu & Fedora)** : pip peut échouer avec
-> `FileNotFoundError` dans `certifi`. Fix : passer la variable `SSL_CERT_FILE`
-> pointant vers les CA système.
+> **Important — ne pas copier `.venv/` entre machines d'OS différents.**
+> Le venv est spécifique à l'OS. Si vous avez cloné/copié le repo depuis une machine Fedora
+> vers Ubuntu (ou inversement), le venv doit être recréé avec `--clear` :
 
 ```bash
-# Sur Ubuntu / meshbay.org
-SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt \
-  pip install -e packages/meshbay-common -e packages/meshbay-node httpx blake3 uvicorn
-
-# Sur Fedora (machine locale)
-SSL_CERT_FILE=/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem \
-  pip install -e packages/meshbay-common -e packages/meshbay-node httpx blake3 uvicorn
+python3 -m venv .venv --clear   # ← --clear force la recréation propre
+source .venv/bin/activate
+pip install -e packages/meshbay-common -e packages/meshbay-node httpx blake3 uvicorn
 ```
 
-Une fois `certifi` correctement installé, les `pip install` suivants n'ont plus besoin de `SSL_CERT_FILE`.
+Sans `--clear`, pip peut échouer avec `FileNotFoundError` dans `certifi` parce qu'il
+cherche les certificats CA à un chemin valide sur l'OS d'origine mais absent sur l'OS cible.
 
 ---
 
-- 
cgit v1.2.3