feat: brain-engine start/stop/status — lifecycle visible pour les forks

- start.sh: background par défaut, PID tracké, --foreground pour debug
- stop.sh: arrêt propre avec grace period 5s + force kill
- status.sh: running/stopped, vérification port, exit code scriptable
- getting-started: docs mis à jour (plus de nohup/kill manuels)
- .gitignore: .brain-engine.pid

.gitignore

@@ -11,6 +11,7 @@ brain-engine/.venv/
 brain-engine/__pycache__/
 brain-engine/*.log
 brain-engine/viz_cache.json
+.brain-engine.pid
 
 # Brain-ui build + deps
 brain-ui/node_modules/

brain-engine/start.sh

@@ -61,14 +61,46 @@ else
     echo "   Le serveur démarre quand même (BSI, docs, endpoints basiques)."
 fi
 
-# 5. Lancer le serveur
+# 5. Vérifier si déjà en cours
+PIDFILE="$BRAIN_ROOT/.brain-engine.pid"
+if [ -f "$PIDFILE" ] && kill -0 "$(cat "$PIDFILE")" 2>/dev/null; then
+    echo ""
+    echo "⚠️  brain-engine tourne déjà (PID $(cat "$PIDFILE"))"
+    echo "   Arrêter : bash brain-engine/stop.sh"
+    echo "   Statut  : bash brain-engine/status.sh"
+    exit 0
+fi
+
+# 6. Lancer le serveur
 PORT="${BRAIN_PORT:-7700}"
+LOGFILE="$BRAIN_ROOT/brain-engine/brain-engine.log"
 echo ""
 echo "=== Lancement brain-engine sur port $PORT ==="
 echo "  Health    : http://localhost:$PORT/health"
-echo "  Search : http://localhost:$PORT/search?q=comment+ca+marche"
+echo "  Dashboard : http://localhost:$PORT/ui/"
 echo "  Agents    : http://localhost:$PORT/agents"
 echo ""
 
 cd "$BRAIN_ROOT"
+
+if [ "${1:-}" = "--foreground" ]; then
+    # Mode foreground (debug) — Ctrl+C pour arrêter
+    echo "Mode foreground — Ctrl+C pour arrêter"
     python3 "$SCRIPT_DIR/server.py"
+else
+    # Mode background (défaut) — PID tracké, log rotatif
+    python3 "$SCRIPT_DIR/server.py" > "$LOGFILE" 2>&1 &
+    ENGINE_PID=$!
+    echo "$ENGINE_PID" > "$PIDFILE"
+    sleep 1
+
+    if kill -0 "$ENGINE_PID" 2>/dev/null; then
+        echo "✅ brain-engine démarré (PID $ENGINE_PID)"
+        echo "   Logs    : tail -f brain-engine/brain-engine.log"
+        echo "   Arrêter : bash brain-engine/stop.sh"
+    else
+        echo "❌ brain-engine n'a pas démarré — voir brain-engine/brain-engine.log"
+        rm -f "$PIDFILE"
+        exit 1
+    fi
+fi

brain-engine/status.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+# brain-engine/status.sh — Statut rapide
+# Usage : bash brain-engine/status.sh
+# Exit 0 si running, 1 si stopped — utilisable dans des scripts/briefings
+
+BRAIN_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+PIDFILE="$BRAIN_ROOT/.brain-engine.pid"
+PORT="${BRAIN_PORT:-7700}"
+
+if [ ! -f "$PIDFILE" ]; then
+    echo "brain-engine: stopped"
+    exit 1
+fi
+
+PID=$(cat "$PIDFILE")
+
+if kill -0 "$PID" 2>/dev/null; then
+    # Vérifier que le port répond
+    if curl -s --max-time 2 "http://localhost:$PORT/health" > /dev/null 2>&1; then
+        echo "brain-engine: running (PID $PID, port $PORT)"
+    else
+        echo "brain-engine: starting (PID $PID, port $PORT pas encore prêt)"
+    fi
+    exit 0
+else
+    rm -f "$PIDFILE"
+    echo "brain-engine: stopped (PID $PID stale — nettoyé)"
+    exit 1
+fi

brain-engine/stop.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+# brain-engine/stop.sh — Arrêt propre
+# Usage : bash brain-engine/stop.sh
+
+BRAIN_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+PIDFILE="$BRAIN_ROOT/.brain-engine.pid"
+
+if [ ! -f "$PIDFILE" ]; then
+    echo "brain-engine n'est pas démarré (pas de PID tracké)"
+    exit 0
+fi
+
+PID=$(cat "$PIDFILE")
+
+if kill -0 "$PID" 2>/dev/null; then
+    kill "$PID"
+    # Attendre l'arrêt propre (max 5s)
+    for i in $(seq 1 10); do
+        kill -0 "$PID" 2>/dev/null || break
+        sleep 0.5
+    done
+
+    if kill -0 "$PID" 2>/dev/null; then
+        echo "⚠️  brain-engine ne répond pas — force kill"
+        kill -9 "$PID" 2>/dev/null
+    fi
+
+    rm -f "$PIDFILE"
+    echo "✅ brain-engine arrêté (PID $PID)"
+else
+    rm -f "$PIDFILE"
+    echo "brain-engine n'était plus actif (PID $PID stale — nettoyé)"
+fi

docs/getting-started.md

@@ -98,48 +98,45 @@ Brain-engine c'est le serveur local qui fait tourner l'API, le dashboard, et la
 ### Demarrer
 
 ```bash
-cd ~/Dev/Brain
 bash brain-engine/start.sh
 ```
 
-Tu vois :
+Brain-engine demarre en arriere-plan. Tu vois :
 
 ```
-=== Lancement brain-engine sur port 7700 ===
+✅ brain-engine demarre (PID 12345)
-  Health : http://localhost:7700/health
+   Logs    : tail -f brain-engine/brain-engine.log
-  Dashboard : http://localhost:7700/ui/
+   Arreter : bash brain-engine/stop.sh
 ```
 
-> **Le terminal reste occupe** — brain-engine tourne au premier plan. Ouvre un autre terminal pour la suite.
-
 ### Verifier
 
-Ouvre ton navigateur : `http://localhost:7700/ui/`
+```bash
+bash brain-engine/status.sh
+```
+
+Ou ouvre ton navigateur : `http://localhost:7700/ui/`
 Tu vois le dashboard avec l'onglet Docs — c'est cette documentation.
 
 ### Arreter
 
-Reviens dans le terminal ou brain-engine tourne et fais `Ctrl+C`. C'est tout.
+```bash
+bash brain-engine/stop.sh
+```
+
+### Mode debug (optionnel)
+
+Si tu veux voir les logs en direct dans le terminal :
+
+```bash
+bash brain-engine/start.sh --foreground
+```
+
+`Ctrl+C` pour arreter.
 
 > Brain-engine n'est pas obligatoire pour utiliser le brain avec Claude Code.
 > C'est un bonus (dashboard, search, API). Tu peux faire `brain boot` sans.
 
-### Lancer en arriere-plan (optionnel)
-
-Si tu ne veux pas bloquer un terminal :
-
-```bash
-cd ~/Dev/Brain
-nohup bash brain-engine/start.sh > /tmp/brain-engine.log 2>&1 &
-echo $! > /tmp/brain-engine.pid
-```
-
-Pour l'arreter :
-
-```bash
-kill $(cat /tmp/brain-engine.pid)
-```
-
 ---
 
 ## Etape 6 — Premier brain boot
@@ -223,8 +220,11 @@ claude
 
 ### Brain-engine tourne encore en fond, comment l'arreter ?
 
-Si tu l'as lance au premier plan : `Ctrl+C` dans son terminal.
+```bash
-Si tu l'as lance en arriere-plan : `kill $(cat /tmp/brain-engine.pid)`
+bash brain-engine/stop.sh
+```
+
+Pour verifier s'il tourne : `bash brain-engine/status.sh`
 En dernier recours : `pkill -f 'python3.*server.py'`
 
 ### Je vois "MYSECRETS absent" — c'est grave ?