diff --git a/brain-ui/public/docs/brain-engine-guide.md b/brain-ui/public/docs/brain-engine-guide.md new file mode 120000 index 0000000..6b67b2e --- /dev/null +++ b/brain-ui/public/docs/brain-engine-guide.md @@ -0,0 +1 @@ +../../../docs/brain-engine-guide.md \ No newline at end of file diff --git a/brain-ui/public/docs/satellites.md b/brain-ui/public/docs/satellites.md new file mode 120000 index 0000000..1d22c00 --- /dev/null +++ b/brain-ui/public/docs/satellites.md @@ -0,0 +1 @@ +../../../docs/satellites.md \ No newline at end of file diff --git a/brain-ui/src/components/DocsView.tsx b/brain-ui/src/components/DocsView.tsx index 936b7cb..e4b14e0 100644 --- a/brain-ui/src/components/DocsView.tsx +++ b/brain-ui/src/components/DocsView.tsx @@ -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' }, diff --git a/docs/README.md b/docs/README.md index 79a7af9..4af1fa8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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 | diff --git a/docs/brain-engine-guide.md b/docs/brain-engine-guide.md new file mode 100644 index 0000000..27f2ab3 --- /dev/null +++ b/docs/brain-engine-guide.md @@ -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 +``` + +--- + +## 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 | diff --git a/docs/satellites.md b/docs/satellites.md new file mode 100644 index 0000000..b2750f2 --- /dev/null +++ b/docs/satellites.md @@ -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 + .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 + / ← 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 +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 ~/Dev/Brain/todo +git clone ~/Dev/Brain/toolkit +git clone ~/Dev/Brain/progression +git clone ~/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.