brain-template/docs/getting-started.md

Demarrer avec le brain — le vrai tuto

Du fork au premier brain boot. 10 minutes.

---

Etape 1 — Forker et cloner

Sur Gitea / GitHub : clique "Fork" sur le repo brain-template.

Sur ta machine :

git clone <URL_DE_TON_FORK> ~/Dev/Brain
cd ~/Dev/Brain

Exemple : git clone https://git.example.com/mon-user/brain-template.git ~/Dev/Brain

---

Etape 2 — Installer les prerequis

Le brain a besoin de :

• Python 3.10+ — pour brain-engine (API, search, embeddings)
• Node.js 18+ et npm — pour brain-ui (dashboard web)
• Claude Code — pour les sessions

# Ubuntu / Pop!_OS / Debian
sudo apt install -y python3 python3-pip python3-venv nodejs npm

# Claude Code
npm install -g @anthropic-ai/claude-code

Optionnel mais recommande :

# Ollama — active la recherche semantique dans le brain
curl -fsSL https://ollama.com/install.sh | sh
ollama pull nomic-embed-text

---

Etape 3 — Lancer le setup

cd ~/Dev/Brain
bash setup.sh

Le script fait tout automatiquement :

1. Cree brain-compose.local.yml — ta config machine (chemins auto-detectes)
2. Cree les dossiers satellites — todo/, progression/, toolkit/, reviews/, workspace/ (pourquoi ?)
3. Copie profil/collaboration.md — regles de travail
4. Build le dashboard — brain-ui/ (npm install + vite build)
5. Init brain-engine — cree l'environnement Python + brain.db

Tu n'as rien a repondre — tout est automatique.

A la fin tu vois :

===========================================
  ✅ Brain installe !
===========================================

---

Etape 4 — Configurer Claude Code

Claude Code a besoin de savoir ou est ton brain :

cp profil/CLAUDE.md.example ~/.claude/CLAUDE.md

Edite ~/.claude/CLAUDE.md — remplace les 2 placeholders :

brain_root: /home/<ton-user>/Dev/Brain
brain_name: prod

C'est le seul fichier a editer a la main. Tout le reste est automatique.

---

Etape 5 — Lancer brain-engine

Brain-engine c'est le serveur local qui fait tourner l'API, le dashboard, et la recherche semantique.

Demarrer

bash brain-engine/start.sh

Brain-engine demarre en arriere-plan. Tu vois :

✅ brain-engine demarre (PID 12345)
   Logs    : tail -f brain-engine/brain-engine.log
   Arreter : bash brain-engine/stop.sh

Verifier

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

bash brain-engine/stop.sh

Mode debug (optionnel)

Si tu veux voir les logs en direct dans le terminal :

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.

---

Etape 6 — Premier brain boot

Ouvre un nouveau terminal (brain-engine tourne dans l'autre) :

claude

Claude Code s'ouvre. Tape :

brain boot

Tu n'as pas besoin d'etre dans le dossier brain. brain boot fonctionne depuis n'importe quel repertoire — les chemins dans ~/.claude/CLAUDE.md sont absolus.

Ce que tu dois voir

Bonjour. Voici l'etat du systeme — <date>.
Instance : prod@<ta-machine>  [free]  kernel v0.9.0
Mode actif : prod

Projets actifs
  Aucun focus defini — fresh fork.

Prochain todo prioritaire
  (aucun todo enregistre)

Quelle session aujourd'hui ?

C'est normal que ce soit vide — c'est un brain neuf. Il n'a pas encore de projets, de todos, ni de focus.

Ce que tu peux repondre

• brain boot mode work/<ton-projet> — si tu veux coder sur un projet
• brain boot mode brainstorm/<sujet> — si tu veux explorer une idee
• brain boot mode brain — si tu veux travailler sur le brain lui-meme
• Ou simplement decrire ce que tu veux faire — le brain detecte le type de session

---

Etape 7 — Fermer une session

Quand tu as fini, tape :

on wrappe

Le brain ferme proprement : metriques capturees, todos mis a jour, claim BSI ferme.

Ne ferme pas Claude Code avec Ctrl+C avant que le wrap soit termine.

---

Resume — les 4 commandes

# 1. Setup (une seule fois)
bash setup.sh

# 2. Config Claude Code (une seule fois)
cp profil/CLAUDE.md.example ~/.claude/CLAUDE.md
# Editer brain_root et brain_name

# 3. Lancer le dashboard (optionnel, a chaque session)
bash brain-engine/start.sh

# 4. Lancer Claude Code (a chaque session, depuis n'importe ou)
claude
# Puis : brain boot

---

FAQ

Brain-engine tourne encore en fond, comment l'arreter ?

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 ?

Non. MYSECRETS c'est pour les projets qui ont des secrets (tokens API, mots de passe). Si tu n'en as pas besoin, ignore le message. Le brain fonctionne sans.

Je vois des fichiers "non trackes" au boot — c'est normal ?

Oui. focus.md, workspace/, brain-ui/package-lock.json sont crees localement par setup.sh et le build. Tu peux les commiter ou les ignorer.

Comment mettre a jour le kernel depuis l'upstream ?

git remote add upstream <URL_DU_TEMPLATE_ORIGINAL>
git fetch upstream
git merge upstream/main

Ou est la documentation complete ?

• Dashboard : http://localhost:7700/ui/ → onglet Docs
• Ou directement dans docs/ du repo