feat: brain-engine + brain-ui + docs — template full stack standalone
- brain-engine: server, embed, search, RAG, MCP, start.sh (standalone) - brain-ui: source React complète, build.sh, DocsView avec tier colors - docs: 14 pages guides humains (getting-started, architecture, sessions, workflows, agents, vues tier) - brain-compose.yml v0.9.0: tier featured ajouté, sessions/agents par tier, coach_level, API key schema - DISTRIBUTION_CHECKLIST v1.2: brain-engine + brain-ui + docs dans la checklist
This commit is contained in:
224
docs/sessions.md
Normal file
224
docs/sessions.md
Normal file
@@ -0,0 +1,224 @@
|
||||
# Guide des sessions — Brain
|
||||
|
||||
> Ce guide explique comment fonctionnent les sessions du brain.
|
||||
> Pour la reference technique complete : `wiki/session-matrix.md`
|
||||
|
||||
---
|
||||
|
||||
## C'est quoi une session ?
|
||||
|
||||
Une session est une conversation avec le brain, du premier message au dernier commit. Chaque session a un **type** qui determine quels agents sont charges, quels fichiers sont accessibles, et ce que le brain peut ecrire.
|
||||
|
||||
Le cycle de vie est simple : **boot → work → close**.
|
||||
|
||||
- **Boot** : le brain detecte le type de session, charge le contexte minimum necessaire
|
||||
- **Work** : tu travailles, les agents pertinents sont disponibles
|
||||
- **Close** : les scribes capturent les metriques, mettent a jour les todos, et ferment le claim BSI
|
||||
|
||||
**Le brain demarre toujours en session.** Si tu ne declares pas de type, tu es automatiquement en session `navigate` — la plus legere. C'est le lobby : tu peux regarder autour, poser des questions, et quand tu veux travailler, tu escalades vers le bon type.
|
||||
|
||||
---
|
||||
|
||||
## Isolation et escalade
|
||||
|
||||
Chaque type de session a un perimetre strict. Le brain ne deborde jamais :
|
||||
|
||||
- En **navigate** : lecture seule, orientation — pas de code, pas de modification brain
|
||||
- En **work** : code projet — pas de modification du brain (kernel, agents)
|
||||
- En **brain** : modification du brain — pas de code projet
|
||||
- En **edit-brain** : modification kernel — gate humain obligatoire
|
||||
|
||||
Si tu demandes quelque chose qui depasse le scope de ta session, le brain te propose d'escalader :
|
||||
|
||||
```
|
||||
"Cette action depasse le scope navigate — brain boot mode work/superoauth pour continuer."
|
||||
```
|
||||
|
||||
Tu confirmes, le brain ferme la session legere et ouvre la bonne. Deux claims dans l'historique, tout est trace.
|
||||
|
||||
---
|
||||
|
||||
## Les types de sessions
|
||||
|
||||
**Coder & produire**
|
||||
|
||||
- `work` — Developpement projet → `brain boot mode work/<projet>`
|
||||
- `debug` — Investigation bug → `brain boot mode debug/<projet>`
|
||||
- `deploy` — Ship en prod, config VPS → `brain boot mode deploy/<projet>`
|
||||
- `infra` — Maintenance VPS, monitoring → `brain boot mode infra`
|
||||
- `urgence` — Production down, hotfix → `brain boot mode urgence`
|
||||
|
||||
**Construire le brain**
|
||||
|
||||
- `brain` — Travailler sur les agents, todos, focus → `brain boot mode brain`
|
||||
- `edit-brain` — Modifier le kernel (gate humain) → `brain boot sudo`
|
||||
- `kernel` — Lire le kernel sans le modifier → `brain boot mode kernel`
|
||||
- `pilote` — Session longue, copilotage actif → `brain boot mode pilote`
|
||||
|
||||
**Explorer & reflechir**
|
||||
|
||||
- `brainstorm` — Explorer, challenger, structurer → `brain boot mode brainstorm/<sujet>`
|
||||
- `navigate` — Vue d'ensemble legere → `brain boot navigate`
|
||||
- `coach` — Progression, reflexion strategique → `brain boot mode coach`
|
||||
- `capital` — Bilan, objectifs, CV → `brain boot mode capital`
|
||||
- `audit` — Analyse lecture seule, rapport → `brain boot mode audit/<projet>`
|
||||
- `handoff` — Reprendre une session precedente → `brain boot mode handoff/<id>`
|
||||
|
||||
---
|
||||
|
||||
## Comment ca se lance — les 4 couches
|
||||
|
||||
Le brain ne charge pas tout d'un coup. Il utilise 4 couches, comme des pelures d'oignon :
|
||||
|
||||
```
|
||||
L0 — Toujours charge (~5%)
|
||||
KERNEL.md, PATHS.md, brain-compose.local.yml
|
||||
→ L'identite du brain. Non negociable.
|
||||
|
||||
L1 — Selon le type de session (~10-18%)
|
||||
Les agents et fichiers specifiques a CE type de session.
|
||||
→ work charge debug + coach, deploy charge vps + ci-cd, etc.
|
||||
|
||||
L2 — Selon le projet (~5-15%)
|
||||
Si tu declares un projet dans ta commande, ses fichiers sont charges.
|
||||
→ projets/<nom>.md + todo/<nom>.md
|
||||
|
||||
L3 — Sur demande (0% au boot)
|
||||
Tout le reste. Charge en cours de session si tu en as besoin.
|
||||
→ "Charge l'agent testing" → L3 → disponible
|
||||
```
|
||||
|
||||
**Resultat** : ~20-30% du contexte utilise au boot, au lieu de 80%. La session demarre vite.
|
||||
|
||||
---
|
||||
|
||||
## Ce que chaque session peut / ne peut pas faire
|
||||
|
||||
**Sessions projet** — ecrivent dans le code, pas dans le brain :
|
||||
- `work` · `debug` · `deploy` · `infra` · `urgence` — ecriture projet uniquement
|
||||
|
||||
**Sessions brain** — ecrivent dans le brain, pas dans le code :
|
||||
- `brain` — agents, profil (gate humain sur le kernel)
|
||||
- `edit-brain` — **ecriture kernel autorisee** (gate humain obligatoire)
|
||||
- `kernel` — lecture seule, aucune ecriture
|
||||
|
||||
**Sessions mixtes** :
|
||||
- `pilote` — ecriture projet + brain (gates architecturaux sur les forks irreversibles)
|
||||
|
||||
**Sessions legeres** — ecriture limitee ou aucune :
|
||||
- `brainstorm` — todo seulement
|
||||
- `navigate` — aucune ecriture
|
||||
- `coach` — progression seulement
|
||||
- `capital` — profil seulement
|
||||
- `audit` — rapport seul
|
||||
- `handoff` — herite du handoff
|
||||
|
||||
---
|
||||
|
||||
## Ce qui se passe quand tu fermes une session
|
||||
|
||||
Quand tu dis `fin`, `on wrappe` ou `c'est bon`, le brain lance une sequence de fermeture automatique :
|
||||
|
||||
```
|
||||
1. Metriques → metabolism-scribe capture tokens, duree, commits, health_score
|
||||
2. Todos → todo-scribe ferme les ✅ et capture les nouveaux ⬜
|
||||
3. Wiki → wiki-scribe ajoute les nouveaux termes si besoin
|
||||
4. Brain update → scribe met a jour focus, projets, agents si changement
|
||||
5. Coach → rapport de session (sauf en navigate, deploy, infra, urgence, audit)
|
||||
6. BSI close → le claim est ferme, la session est tracee
|
||||
```
|
||||
|
||||
**Pas toutes les etapes a chaque fois.** Le brain adapte selon le type de session :
|
||||
- **navigate** : juste metriques + BSI close (session legere)
|
||||
- **work** : metriques + todos + scribe + coach + BSI close (session complete)
|
||||
- **brainstorm** : metriques + todos emerges + BSI close (pas de commit attendu)
|
||||
- **pilote** : tout — metriques + todos + wiki + scribe + coach + BSI close
|
||||
|
||||
Le coach ne fait pas de rapport en session silencieuse (navigate, deploy, infra, urgence, audit) — il n'intervient que si risque critique.
|
||||
|
||||
---
|
||||
|
||||
## Le metabolisme — ce qu'on mesure
|
||||
|
||||
A la fin de chaque session, le `metabolism-scribe` capture des metriques :
|
||||
|
||||
- **tokens_used** : combien de tokens consommes
|
||||
- **context_peak** : pic d'utilisation du contexte (%)
|
||||
- **duration_min** : duree de la session
|
||||
- **commits** : nombre de commits produits
|
||||
- **todos_closed** : todos coches pendant la session
|
||||
- **health_score** : score calcule — se lit en tendance sur 7 jours
|
||||
|
||||
Le score n'est pas un jugement. Il detecte les patterns :
|
||||
- Score bas + context haut = session qui consomme sans produire
|
||||
- Score bas sur un brainstorm = normal (pas de livrable attendu)
|
||||
- Ratio use-brain/build-brain < 0.5 sur 7j = trop de travail sur le brain, pas assez de production
|
||||
|
||||
### Les 3 profils de scoring
|
||||
|
||||
Toutes les sessions ne se mesurent pas pareil :
|
||||
|
||||
| Profil | Sessions | Ce qui compte |
|
||||
|--------|----------|--------------|
|
||||
| **Productif** | work, deploy, debug, infra, urgence | Todos fermes, commits |
|
||||
| **Constructif** | brain, edit-brain, kernel, pilote | Fichiers kernel touches, ADRs |
|
||||
| **Exploratoire** | brainstorm, navigate, coach, capital, handoff, audit | Insights captures, duree |
|
||||
|
||||
---
|
||||
|
||||
## Les tiers
|
||||
|
||||
Le brain a un systeme de tiers qui controle l'acces aux agents et aux sessions :
|
||||
|
||||
> 🟢 **free** — 6 sessions (work, debug, brainstorm, brain, navigate, handoff). Pas de cle API. Le brain fonctionne quand meme.
|
||||
|
||||
> 🔵 **featured** — +2 sessions (coach, capital). Progression personnelle, RAG, coaching complet.
|
||||
|
||||
> 🟠 **pro** — +4 sessions (audit, deploy, infra, urgence). Tous les agents metier : code-review, security, vps, ci-cd, monitoring.
|
||||
|
||||
> 🟣 **full** — +3 sessions (kernel, edit-brain, pilote). Tous les agents, acces kernel complet, owner du brain.
|
||||
|
||||
→ Detail complet : voir **Agents & Tiers** dans la sidebar.
|
||||
|
||||
---
|
||||
|
||||
## FAQ
|
||||
|
||||
### Comment creer un nouveau type de session ?
|
||||
|
||||
1. Creer `contexts/session-<type>.yml` avec le format L0/L1/L2/L3
|
||||
2. Declarer le tier_required et le context_target
|
||||
3. Ajouter le type dans `brain-compose.yml` > `feature_sets` > le bon tier
|
||||
4. Ajouter le handoff_default dans `manifest.yml`
|
||||
5. Ajouter la zone access dans `KERNEL.md`
|
||||
6. Mettre a jour `wiki/session-matrix.md`
|
||||
|
||||
### Comment escalader depuis navigate ?
|
||||
|
||||
Dis simplement `brain boot mode <type>` (ex: `brain boot mode work/superoauth`). Le brain ferme navigate et ouvre la session demandee. Tu peux aussi decrire ce que tu veux faire — le brain detectera le debordement et proposera le bon type.
|
||||
|
||||
### Pourquoi ma session est en mode conserve ?
|
||||
|
||||
Le mode conserve se declenche quand :
|
||||
- Le contexte depasse 70% ET le health_score est < 1.0
|
||||
- Le contexte a la fermeture depasse 60%
|
||||
- C'est une session urgence (conserve automatique)
|
||||
|
||||
En mode conserve, le brain cible < 40% de contexte et ne charge que l'essentiel.
|
||||
|
||||
### C'est quoi un handoff ?
|
||||
|
||||
Un handoff est un fichier qui capture l'etat d'une session pour qu'une autre puisse reprendre. Niveaux :
|
||||
- **NO** : pas de handoff — la prochaine session repart de zero (cold start)
|
||||
- **SEMI** : Layer 0 + position
|
||||
- **SEMI+** : SEMI + focus + projet
|
||||
- **FULL** : tout le contexte de reprise
|
||||
|
||||
---
|
||||
|
||||
## Liens
|
||||
|
||||
- **Reference technique** : `wiki/session-matrix.md` — matrice complete avec tous les champs
|
||||
- **Cycle de vie** : `wiki/session-lifecycle.md` — boot → work → close en detail
|
||||
- **Context loading** : `wiki/context-loading.md` — architecture BHP L0-L3
|
||||
- **Metabolisme** : `profil/metabolism-spec.md` — formules et seuils
|
||||
Reference in New Issue
Block a user