docs: satellites guide + brain-engine guide + sidebar mise a jour
This commit is contained in:
1
brain-ui/public/docs/brain-engine-guide.md
Symbolic link
1
brain-ui/public/docs/brain-engine-guide.md
Symbolic link
@@ -0,0 +1 @@
|
||||
../../../docs/brain-engine-guide.md
|
||||
1
brain-ui/public/docs/satellites.md
Symbolic link
1
brain-ui/public/docs/satellites.md
Symbolic link
@@ -0,0 +1 @@
|
||||
../../../docs/satellites.md
|
||||
@@ -12,6 +12,8 @@ const DOCS: DocFile[] = [
|
||||
{ name: 'getting-started', label: 'Demarrer', path: import.meta.env.BASE_URL + 'docs/getting-started.md', group: 'Guides' },
|
||||
{ name: 'architecture', label: 'Architecture', path: import.meta.env.BASE_URL + 'docs/architecture.md', group: 'Guides' },
|
||||
{ name: 'sessions', label: 'Sessions', path: import.meta.env.BASE_URL + 'docs/sessions.md', group: 'Guides' },
|
||||
{ name: 'satellites', label: 'Satellites', path: import.meta.env.BASE_URL + 'docs/satellites.md', group: 'Guides' },
|
||||
{ name: 'brain-engine-guide', label: 'Brain-engine', path: import.meta.env.BASE_URL + 'docs/brain-engine-guide.md', group: 'Guides' },
|
||||
{ name: 'workflows', label: 'Workflows', path: import.meta.env.BASE_URL + 'docs/workflows.md', group: 'Guides' },
|
||||
{ name: 'agents', label: 'Vue d\'ensemble', path: import.meta.env.BASE_URL + 'docs/agents.md', group: 'Agents' },
|
||||
{ name: 'agents-code', label: 'Code & Qualite', path: import.meta.env.BASE_URL + 'docs/agents-code.md', group: 'Agents' },
|
||||
|
||||
@@ -12,6 +12,8 @@
|
||||
| [getting-started.md](getting-started.md) | **Commence ici** — les 5 premieres minutes apres un fork |
|
||||
| [architecture.md](architecture.md) | Comment les pieces s'assemblent — version humaine |
|
||||
| [sessions.md](sessions.md) | Types de sessions, permissions, metabolisme, close sequences |
|
||||
| [satellites.md](satellites.md) | Les repos satellites — todo, toolkit, progression, reviews |
|
||||
| [brain-engine-guide.md](brain-engine-guide.md) | Demarrer, arreter, diagnostiquer brain-engine |
|
||||
| [workflows.md](workflows.md) | Recettes d'agents — quels agents combiner pour quoi |
|
||||
| **Agents** | |
|
||||
| [agents.md](agents.md) | Vue d'ensemble — comparatif tiers, navigation |
|
||||
|
||||
179
docs/brain-engine-guide.md
Normal file
179
docs/brain-engine-guide.md
Normal file
@@ -0,0 +1,179 @@
|
||||
# Brain-engine — guide pratique
|
||||
|
||||
> Demarrer, arreter, diagnostiquer. Les commandes du quotidien.
|
||||
|
||||
---
|
||||
|
||||
## C'est quoi brain-engine ?
|
||||
|
||||
Brain-engine c'est le serveur local de ton brain. Il fait 3 choses :
|
||||
|
||||
1. **Dashboard web** — tes docs, tes workflows, la visualisation 3D de ton corpus
|
||||
2. **API locale** — les agents et scripts du brain l'utilisent pour chercher du contexte
|
||||
3. **Recherche semantique** — tu poses une question, il trouve les fichiers pertinents
|
||||
|
||||
> Brain-engine n'est **pas obligatoire** pour utiliser le brain avec Claude Code.
|
||||
> C'est un bonus. `brain boot` fonctionne sans.
|
||||
|
||||
---
|
||||
|
||||
## Demarrer
|
||||
|
||||
```bash
|
||||
cd ~/Dev/Brain
|
||||
bash brain-engine/start.sh
|
||||
```
|
||||
|
||||
Le script :
|
||||
1. Cree l'environnement Python (une seule fois)
|
||||
2. Installe les dependances (une seule fois)
|
||||
3. Init brain.db si absent
|
||||
4. Indexe le corpus si Ollama est disponible
|
||||
5. Lance le serveur sur le port 7700
|
||||
|
||||
**Le terminal reste occupe.** Ouvre un autre terminal pour Claude Code.
|
||||
|
||||
---
|
||||
|
||||
## Verifier que ca tourne
|
||||
|
||||
```bash
|
||||
# Health check
|
||||
curl http://localhost:7700/health
|
||||
|
||||
# Dashboard
|
||||
# Ouvre dans ton navigateur :
|
||||
http://localhost:7700/ui/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Arreter
|
||||
|
||||
### Premier plan (cas normal)
|
||||
|
||||
Tu as lance `bash brain-engine/start.sh` dans un terminal → **Ctrl+C** dans ce terminal.
|
||||
|
||||
### Arriere-plan
|
||||
|
||||
Si tu l'as lance avec `nohup` :
|
||||
|
||||
```bash
|
||||
kill $(cat /tmp/brain-engine.pid)
|
||||
```
|
||||
|
||||
### Dernier recours
|
||||
|
||||
```bash
|
||||
pkill -f 'python3.*server.py'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Lancer en arriere-plan
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
Verifier les logs :
|
||||
|
||||
```bash
|
||||
tail -f /tmp/brain-engine.log
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Recherche semantique
|
||||
|
||||
La recherche necessite **Ollama** + le modele `nomic-embed-text`.
|
||||
|
||||
### Installer Ollama
|
||||
|
||||
```bash
|
||||
curl -fsSL https://ollama.com/install.sh | sh
|
||||
ollama pull nomic-embed-text
|
||||
```
|
||||
|
||||
### Indexer le corpus
|
||||
|
||||
```bash
|
||||
cd ~/Dev/Brain
|
||||
brain-engine/.venv/bin/python3 brain-engine/embed.py
|
||||
```
|
||||
|
||||
Apres l'indexation, la recherche fonctionne :
|
||||
|
||||
```bash
|
||||
curl "http://localhost:7700/search?q=comment+fonctionnent+les+sessions"
|
||||
```
|
||||
|
||||
### Re-indexer apres des modifications
|
||||
|
||||
```bash
|
||||
brain-engine/.venv/bin/python3 brain-engine/embed.py
|
||||
```
|
||||
|
||||
> L'indexation est incrementale — seuls les fichiers modifies sont re-indexes.
|
||||
|
||||
---
|
||||
|
||||
## Connexion MCP (Claude Code)
|
||||
|
||||
Brain-engine expose un serveur MCP pour que Claude Code puisse chercher dans ton brain :
|
||||
|
||||
```bash
|
||||
# Lancer le MCP server (port 7701)
|
||||
brain-engine/.venv/bin/python3 brain-engine/mcp_server.py
|
||||
|
||||
# Ajouter dans Claude Code
|
||||
claude mcp add brain --transport http http://localhost:7701/mcp/
|
||||
```
|
||||
|
||||
Puis en session Claude Code :
|
||||
|
||||
```
|
||||
use brain_search to find context about <sujet>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Diagnostiquer
|
||||
|
||||
### Le serveur ne demarre pas
|
||||
|
||||
```bash
|
||||
# Verifier que le port n'est pas deja utilise
|
||||
lsof -i :7700
|
||||
|
||||
# Verifier les logs
|
||||
cat /tmp/brain-engine.log
|
||||
```
|
||||
|
||||
### "no such table: embeddings"
|
||||
|
||||
Normal si Ollama n'est pas installe. La recherche ne fonctionne pas mais le dashboard et l'API oui.
|
||||
|
||||
### Le dashboard affiche une page blanche
|
||||
|
||||
```bash
|
||||
# Verifier que brain-ui est build
|
||||
ls ~/Dev/Brain/brain-ui/dist/index.html
|
||||
|
||||
# Si absent, rebuild :
|
||||
bash brain-ui/build.sh
|
||||
# Puis relancer brain-engine
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Ports
|
||||
|
||||
| Service | Port | Usage |
|
||||
|---------|------|-------|
|
||||
| brain-engine | 7700 | API + dashboard |
|
||||
| MCP server | 7701 | Connexion Claude Code |
|
||||
150
docs/satellites.md
Normal file
150
docs/satellites.md
Normal file
@@ -0,0 +1,150 @@
|
||||
# Les satellites — tes repos dans le brain
|
||||
|
||||
> Pourquoi le brain a des sous-dossiers qui sont des repos Git separés.
|
||||
|
||||
---
|
||||
|
||||
## C'est quoi un satellite ?
|
||||
|
||||
Le brain a un **kernel** (le repo principal) et des **satellites** (des repos Git independants qui vivent dans des sous-dossiers).
|
||||
|
||||
```
|
||||
~/Dev/Brain/ ← kernel (repo principal)
|
||||
agents/ ← dans le kernel
|
||||
profil/ ← dans le kernel
|
||||
todo/ ← SATELLITE (son propre repo Git)
|
||||
toolkit/ ← SATELLITE (son propre repo Git)
|
||||
progression/ ← SATELLITE (son propre repo Git)
|
||||
reviews/ ← SATELLITE (son propre repo Git)
|
||||
```
|
||||
|
||||
Chaque satellite a sa propre histoire Git, ses propres commits, ses propres branches. Le kernel les ignore (`.gitignore`).
|
||||
|
||||
---
|
||||
|
||||
## Pourquoi ne pas tout mettre dans un seul repo ?
|
||||
|
||||
**Isolation.** Tes todos n'ont pas besoin d'etre dans le meme historique que tes agents. Ta progression est privee — elle ne doit pas etre dans le template distribue. Ton toolkit peut etre partage independamment.
|
||||
|
||||
**Permissions.** Le kernel est protege (confirmation humaine). Les satellites sont libres — les scribes ecrivent dedans sans gate.
|
||||
|
||||
**Distribution.** Quand tu forkes le brain-template, tu recois le kernel propre. Tes satellites sont a toi — tu les crées.
|
||||
|
||||
---
|
||||
|
||||
## Les 4 satellites
|
||||
|
||||
### todo/ — tes intentions
|
||||
|
||||
Ce que tu veux faire, ce qui reste a faire, ce qui est planifie.
|
||||
|
||||
```
|
||||
todo/
|
||||
README.md ← index des fichiers actifs
|
||||
brain.md ← todos du brain lui-meme
|
||||
<projet>.md ← todos par projet
|
||||
```
|
||||
|
||||
Ecrit par : `todo-scribe` en fin de session.
|
||||
|
||||
### toolkit/ — tes patterns valides
|
||||
|
||||
Les patterns, templates, et snippets que tu as valides en prod. Reutilisables d'une session a l'autre.
|
||||
|
||||
```
|
||||
toolkit/
|
||||
_template.md ← template de pattern
|
||||
docker/ ← patterns Docker
|
||||
apache/ ← templates vhost
|
||||
github-actions/ ← pipelines CI/CD
|
||||
```
|
||||
|
||||
Ecrit par : `toolkit-scribe` quand un pattern est valide.
|
||||
|
||||
### progression/ — ton parcours
|
||||
|
||||
Ta progression, tes skills, ton metabolisme de sessions. Le coach ecrit ici.
|
||||
|
||||
```
|
||||
progression/
|
||||
README.md ← niveau actuel + objectifs
|
||||
metabolism/ ← metriques de chaque session
|
||||
skills/ ← competences par domaine
|
||||
journal/ ← observations de session
|
||||
```
|
||||
|
||||
Ecrit par : `metabolism-scribe`, `coach-scribe`.
|
||||
|
||||
### reviews/ — tes audits d'agents
|
||||
|
||||
Les audits faits par `agent-review` — comment chaque agent performe en conditions reelles.
|
||||
|
||||
```
|
||||
reviews/
|
||||
_template.md ← template de review
|
||||
<Projet>/ ← reviews par projet
|
||||
```
|
||||
|
||||
Ecrit par : `agent-review`.
|
||||
|
||||
---
|
||||
|
||||
## Comment les creer
|
||||
|
||||
### Option 1 — Dossiers locaux (le plus simple)
|
||||
|
||||
Le `setup.sh` cree les dossiers automatiquement au premier lancement. Ils fonctionnent comme des dossiers normaux. Pas de repo Git separe.
|
||||
|
||||
C'est suffisant pour commencer. Tu peux les versionner plus tard.
|
||||
|
||||
### Option 2 — Repos Git separes (recommande a terme)
|
||||
|
||||
Si tu veux versionner chaque satellite independamment :
|
||||
|
||||
```bash
|
||||
# Creer un repo pour todo/
|
||||
cd ~/Dev/Brain/todo
|
||||
git init
|
||||
git add .
|
||||
git commit -m "init: todo satellite"
|
||||
# Optionnel : push vers ton Gitea/GitHub
|
||||
git remote add origin <URL_DU_REPO>
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
Repete pour chaque satellite (toolkit/, progression/, reviews/).
|
||||
|
||||
> Le `.gitignore` du kernel ignore deja ces dossiers — pas de conflit.
|
||||
|
||||
### Option 3 — Cloner des satellites existants
|
||||
|
||||
Si tu reprends un brain existant ou tu veux partir d'un satellite pre-rempli :
|
||||
|
||||
```bash
|
||||
git clone <URL> ~/Dev/Brain/todo
|
||||
git clone <URL> ~/Dev/Brain/toolkit
|
||||
git clone <URL> ~/Dev/Brain/progression
|
||||
git clone <URL> ~/Dev/Brain/reviews
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Ce qui se passe si un satellite est absent
|
||||
|
||||
**Rien ne casse.** Le brain fonctionne sans satellites. Le briefing signale ce qui manque :
|
||||
|
||||
```
|
||||
⚠️ Alertes
|
||||
- progression/ satellite non clone
|
||||
- todo/ satellite non clone
|
||||
```
|
||||
|
||||
C'est informatif, pas bloquant. Les scribes ne peuvent juste pas ecrire dans des dossiers qui n'existent pas.
|
||||
|
||||
---
|
||||
|
||||
## Regle d'or
|
||||
|
||||
> Le kernel ne depend jamais des satellites. Les satellites dependent du kernel.
|
||||
> Un satellite peut etre supprime et recree sans impact sur le brain.
|
||||
> Le kernel, lui, est sacre.
|
||||
Reference in New Issue
Block a user