fix: venv --clear required when copying repo across OS (Fedora→Ubuntu)

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>

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.
 
 ---