brainclaw 1.22.0 → 1.24.0

package/dist/facts.js

@@ -1,8 +1,8 @@
 // Generated by scripts/emit-site-facts.mjs at build time. Do not edit manually.
-// Source: brainclaw v1.22.0 on 2026-08-08T16:03:19.158Z
+// Source: brainclaw v1.24.0 on 2026-08-10T18:03:29.240Z
 export const FACTS = {
-  "version": "1.22.0",
-  "generated_at": "2026-08-08T16:03:19.158Z",
+  "version": "1.24.0",
+  "generated_at": "2026-08-10T18:03:29.240Z",
   "tools": {
     "count": 67,
     "published_count": 65,
@@ -474,7 +474,7 @@ export const FACTS = {
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-08-08T16:03:17.056Z",
+    "generated_at": "2026-08-10T18:03:27.087Z",
     "node_version": "v24.18.0",
     "platform": "linux-x64",
     "repeats": 3,
@@ -483,7 +483,7 @@ export const FACTS = {
         "name": "cold_onboard",
         "volume": "empty",
         "description": "fresh machine → init → first useful context. Baseline for time-to-first-value.",
-        "duration_ms_median": 73,
+        "duration_ms_median": 71,
         "payload_chars_median": 1640,
         "payload_tokens_est_median": 410
       },
@@ -491,7 +491,7 @@ export const FACTS = {
         "name": "warm_work",
         "volume": "medium",
         "description": "bclaw_work consult over a real-shaped store (~200 plans / 500 handoffs / 450 claims).",
-        "duration_ms_median": 128,
+        "duration_ms_median": 107,
         "payload_chars_median": 2626,
         "payload_tokens_est_median": 657
       },
@@ -499,7 +499,7 @@ export const FACTS = {
         "name": "first_edit",
         "volume": "medium",
         "description": "code_find + code_brief on the fresh-agent path (missing index, first touch).",
-        "duration_ms_median": 14,
+        "duration_ms_median": 10,
         "payload_chars_median": 499,
         "payload_tokens_est_median": 125
       }

package/dist/facts.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.22.0",
-  "generated_at": "2026-08-08T16:03:19.158Z",
+  "version": "1.24.0",
+  "generated_at": "2026-08-10T18:03:29.240Z",
   "tools": {
     "count": 67,
     "published_count": 65,
@@ -472,7 +472,7 @@
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-08-08T16:03:17.056Z",
+    "generated_at": "2026-08-10T18:03:27.087Z",
     "node_version": "v24.18.0",
     "platform": "linux-x64",
     "repeats": 3,
@@ -481,7 +481,7 @@
         "name": "cold_onboard",
         "volume": "empty",
         "description": "fresh machine → init → first useful context. Baseline for time-to-first-value.",
-        "duration_ms_median": 73,
+        "duration_ms_median": 71,
         "payload_chars_median": 1640,
         "payload_tokens_est_median": 410
       },
@@ -489,7 +489,7 @@
         "name": "warm_work",
         "volume": "medium",
         "description": "bclaw_work consult over a real-shaped store (~200 plans / 500 handoffs / 450 claims).",
-        "duration_ms_median": 128,
+        "duration_ms_median": 107,
         "payload_chars_median": 2626,
         "payload_tokens_est_median": 657
       },
@@ -497,7 +497,7 @@
         "name": "first_edit",
         "volume": "medium",
         "description": "code_find + code_brief on the fresh-agent path (missing index, first touch).",
-        "duration_ms_median": 14,
+        "duration_ms_median": 10,
         "payload_chars_median": 499,
         "payload_tokens_est_median": 125
       }

package/docs/design/federation-onboarding-usecases.md

@@ -0,0 +1,254 @@
+# Fédération cloud — cartographie des cas d'usage et des parcours
+
+> Objectif fixé par l'opérateur (2026-08-09) : identifier **tous** les cas pour qu'un ou
+> plusieurs humains, sur un ou plusieurs projets, avec un ou plusieurs agents, utilisent la
+> fédération **simplement**. Point de départ : l'onboarding côté cloud, avec l'idée d'un
+> appairage par agent via une URL d'activation.
+>
+> Chaque affirmation « état actuel » de ce document a été **mesurée sur le code ou en
+> production cette session** — les références (dec#, trp#) pointent la mesure.
+
+---
+
+## 1. Le vocabulaire d'abord — quatre identités, pas deux
+
+Tout le reste du document repose sur cette distinction. La confusion entre ces quatre
+notions est la cause directe des deux pièges déjà rencontrés (trp#1610, trp#1625).
+
+| Identité | Ce qu'elle est | Sa preuve | Où elle vit |
+|---|---|---|---|
+| **Compte humain** | La personne — s'inscrit, approuve, administre | session web (email + mot de passe) | cloud (`users`) |
+| **Appareil** | La machine — détient les clés de **déchiffrement** | clé X25519, empreinte comparée à l'appairage | local (`~/.brainclaw/keys/`) + cloud (`enrollments`) |
+| **Agent** | Le logiciel (claude-code, codex…) — **signe** ce qu'il émet | clé Ed25519, attestée à l'appairage | local (registre d'agents) + cloud (`agents`) |
+| **Projet** | Le magasin `.brainclaw/` et sa projection aveugle | — | local (source de vérité) + cloud (projection, dec#154) |
+
+Relations cibles (dec#158/159) : un humain **possède** des appareils ; un appareil
+**héberge** des agents ; un enrôlement lie *(agent, appareil, humain propriétaire, projet)*.
+
+**Écart mesuré aujourd'hui** : l'enrôlement lie agent + appareil mais **pas l'humain**
+(aucun `owner_user_id`), et l'état local ne connaît qu'**un** appairage par workspace, sans
+mémoriser quel agent (trp#1625).
+
+---
+
+## 2. La matrice des situations
+
+Quatre axes : humains (1/N) × machines (1/N) × agents (1/N) × projets (1/N).
+Les combinaisons se ramènent à six situations réellement distinctes :
+
+| # | Situation | État aujourd'hui | Ce qui bloque |
+|---|---|---|---|
+| S1 | 1 humain, 1 machine, 1 agent, 1 projet | ✅ **fonctionne, vérifié en prod** | — |
+| S2 | + agents supplémentaires sur la même machine | ❌ | `connection.json` singleton : le 2ᵉ `connect` **écrase** le 1ᵉʳ (trp#1625) |
+| S3 | + machines supplémentaires (même humain) | ❌ | pas de **remise de clé d'epoch** : la 2ᵉ machine ne peut ni lire ni sceller (dec#159) |
+| S4 | + humains supplémentaires (équipe) | ❌ | pas d'invitation par email (`404` si compte inexistant, zéro envoi d'email), pas de propriétaire d'appareil |
+| S5 | plusieurs projets | 🟡 | 1 workspace = 1 projet : correct par construction ; clés API scopées par projet (vérifié : `403` croisé) ; mais l'URL du cloud n'est pas persistée, à repasser à chaque commande |
+| S6 | agents sans humain au terminal (CI, headless) | ❌ non conçu | la cérémonie exige un humain qui compare des empreintes — cas à traiter explicitement, pas par contournement |
+
+La règle de conception qui découle de dec#158 : **le solo est le cas dégénéré du modèle
+d'équipe**, jamais une branche parallèle. S1 doit rester exactement « S4 où le même humain
+joue tous les rôles et où les approbations s'effondrent en un geste ».
+
+---
+
+## 3. Les parcours, un par un
+
+Convention : 🖥 = côté cloud (navigateur), ⌨ = côté machine (terminal), 👤 = geste humain
+explicite. ✅/🟡/❌ = état mesuré de chaque étape.
+
+### W1 — Solo : premier appairage (S1) — *fonctionne aujourd'hui*
+
+Le cas « j'utilisais déjà brainclaw en local » : le magasin existe, le cloud est vide.
+
+| # | Étape | Où | État |
+|---|---|---|---|
+| 1 | Créer un compte, créer/choisir le projet cloud | 🖥 | ✅ |
+| 2 | « Connect an agent » → créer une invitation (rôle + libellé) → **code affiché une fois** (TTL 15 min, usage unique, seul le SHA-256 est stocké) | 🖥👤 | ✅ |
+| 3 | `brainclaw cloud connect <code> --url <url> --agent <id>` **depuis le bon workspace** — le workspace appairé est affiché avec les empreintes | ⌨ | ✅ (garde trp#1610 livrée) |
+| 4 | Comparer les **deux empreintes** terminal ↔ écran, approuver | 🖥👤 | ✅ |
+| 5 | `brainclaw cloud await --url <url>` → appairage local actif, **genèse de la clé d'epoch 1** (premier appareil seulement) | ⌨ | ✅ (livré ce jour) |
+| 6 | `brainclaw cloud push --url <url>` → plans + mémoire projet scellés, envoyés, stockés | ⌨ | ✅ (vérifié en prod : enveloppe en base, zéro fuite) |
+
+**Frictions restantes de W1** (aucune bloquante) : l'URL doit être répétée à chaque commande
+(l'état ne la persiste pas — mesuré) ; `connect` puis `await` sont deux commandes là où une
+seule suffirait (`connect` pourrait attendre l'approbation en sondant) ; l'agent doit être
+un identifiant opaque `[a-zA-Z0-9_-]{4,64}` et l'erreur ne le dit qu'après coup.
+
+### W2 — Deuxième agent, même machine (S2) — *à construire*
+
+Cible : les agents d'une même machine **partagent la clé X25519 de l'appareil** et signent
+chacun avec leur Ed25519. C'est cohérent avec l'attestation existante (elle lie déjà un
+Ed25519 à un X25519) : chaque agent atteste **la même** clé d'appareil.
+
+| # | Étape | Où | État |
+|---|---|---|---|
+| 1 | Créer une invitation **par agent** (ou une invitation multi-usages ? → non : usage unique conservé, un code par agent) | 🖥👤 | ✅ (mécanique identique à W1) |
+| 2 | `cloud connect <code> --agent <id2>` → détecte l'appairage existant, **réutilise la clé d'appareil**, ajoute un enrôlement à la liste | ⌨ | ❌ `connection.json` doit devenir une **liste d'appairages** `{agent, enrollment_id, role}` autour d'un `device` unique |
+| 3 | Approbation par empreintes — l'empreinte de chiffrement **répète** celle de l'appareil, l'empreinte d'identité change par agent | 🖥👤 | 🟡 l'écran d'approbation existe ; afficher « appareil déjà connu » serait le bon signal |
+| 4 | Chaque agent pousse sous sa propre signature ; l'origine (`origin_agent_id`) les distingue | ⌨ | ✅ le transport le fait déjà |
+
+**Prérequis structurel** : migration de `connection.json` (forme v2 → v3) avec lecture
+tolérante des deux formats — même discipline que la purge cloud (rien d'irréversible sans
+chemin de retour).
+
+### W3 — Deuxième machine, même humain (S3) — *bloqué sur la remise d'epoch*
+
+| # | Étape | Où | État |
+|---|---|---|---|
+| 1 | Invitation + cérémonie sur la machine B (identique à W1 étapes 2–4) | 🖥⌨👤 | ✅ |
+| 2 | La machine B est `active` **mais ne détient aucune clé d'epoch** : elle ne peut ni lire ni sceller | — | ⚠️ c'est l'état actuel : actif et inopérant, sans message |
+| 3 | Une machine détentrice (A) **remet** les epochs autorisés : paquet HPKE scellé vers la X25519 attestée de B, manifeste signé (`epoch_grant`, dec#159) | ⌨ A | ❌ à construire — **le cœur du chantier** |
+| 4 | B vérifie le manifeste, range les clés (`storeEpochPrivateKey` refuse déjà d'écraser une clé différente), relit le passé autorisé | ⌨ B | 🟡 primitives présentes, protocole absent |
+
+**Point de vigilance déjà mesuré** : le premier appairage marque `recovery: true` et le
+quorum de récupération (2 appareils) est **rapporté mais jamais appliqué** — le solo n'est
+pas bloqué, mais la perte de l'unique machine = perte du passé, et rien ne l'affiche.
+
+### W4 — Embarquer un deuxième développeur (S4) — *le parcours demandé, à construire*
+
+Le principe directeur (convergence des deux critiques de l'idéation) : **deux approbations
+de nature différente**. L'admin admet **l'humain** ; l'humain approuve **ses appareils**.
+Un admin ne peut pas comparer les empreintes du terminal d'un tiers — le faire approuver à
+sa place réduirait la cérémonie à un clic de confiance (dec#8).
+
+| # | Étape | Où | État |
+|---|---|---|---|
+| 1 | Admin : « Inviter un membre » → email + rôle | 🖥👤 | ❌ aujourd'hui `404` si le compte n'existe pas |
+| 2 | Le cloud envoie un email avec lien d'acceptation ; si le compte n'existe pas, le lien passe par l'inscription | 🖥 | ❌ **zéro envoi d'email dans le backend** (une skill `cloudflare-email-service` est disponible pour le construire) |
+| 3 | Le membre accepte → `project_members` actif avec son rôle | 🖥👤 | 🟡 la table et les rôles existent, le flux non |
+| 4 | Le membre crée **ses** invitations d'agent (portée : ses propres appareils) et fait W1/W2 sur ses machines | 🖥⌨👤 | ❌ nécessite `owner_user_id` sur `enrollments` + revendication de propriétaire **dans le payload d'attestation signé** (sinon la liaison humain↔appareil ne vaut que la parole du cloud) |
+| 5 | L'**admin voit** les appareils du membre (métadonnées, pas les clés) ; le **membre** les approuve | 🖥 | ❌ l'écran d'approbation ne filtre pas par propriétaire |
+| 6 | Un custodian remet les epochs selon l'**horizon** choisi (tout / à partir de maintenant / borné) | ⌨ | ❌ même chantier que W3-3 + **arbitrage produit** (voir §7) |
+
+### W5 — Révoquer (agent, appareil, ou humain)
+
+| # | Étape | Où | État |
+|---|---|---|---|
+| 1 | Révoquer l'enrôlement (bouton « Revoke ») | 🖥👤 | ✅ existe |
+| 2 | Supprimer / renommer l'agent dans le registre cloud | 🖥 | ❌ **aucun `DELETE /agents/:id`**, le `PATCH` ne change que le statut — c'est le manque constaté par l'opérateur |
+| 3 | Rotation d'epoch N+1, remise aux lecteurs restants | ⌨ | ❌ dépend de W3-3 |
+| 4 | Affichage honnête : « ne lit plus le **futur** ; conserve ce qu'il avait déjà déchiffré » | 🖥 | ✅ le texte existe sur la page connect |
+
+### W6 — Perte de machine / récupération
+
+RFC §5.3 : un porteur restant approuve la nouvelle clé, enveloppe les epochs historiques
+autorisés, révoque l'ancienne. Même mécanique que W3-3 avec un autorisateur différent —
+**toute solution qui inventerait un second canal de transfert de clés créerait un second
+endroit où une clé peut fuir** (conséquence 3 de dec#158).
+État : ❌ (bloqué sur la remise d'epoch) + ⚠️ quorum non appliqué (mesuré).
+
+### W7 — Quotidien : synchroniser
+
+| # | Étape | État |
+|---|---|---|
+| 1 | `cloud push` — scelle, met en file, envoie ; refus des trois filets listés un par un | ✅ vérifié en prod |
+| 2 | **Pull** — tirer les enveloppes des autres, vérifier (`verifyInbound` : roster, signature, AAD, anti-rejeu), matérialiser localement | ❌ **`verifyInbound` n'a aucun appelant de production** — symétrique exact de l'émission avant ce matin ; le « Materialized N signals » des sessions vient du chemin **v1** |
+| 3 | Relais dashboard : changer statut/priorité depuis le web, appliqué localement (`applyCloudCommand`) | 🟡 primitives présentes des deux côtés, câblage du poll absent |
+| 4 | Automatisation : push en fin de session, pull en début (hooks existants) | ❌ manuel aujourd'hui |
+| 5 | Conflits : `409` → recalage signé une fois, sinon visible en `conflict` | ✅ |
+
+### W8 — Multi-projets (S5)
+
+Fonctionne par construction (1 workspace = 1 projet, table d'ids opaques cloisonnée par
+projet cloud — testé). Reste : persister l'URL du cloud par appairage, et le sélecteur de
+projet web existe déjà.
+
+### W9 — Agent headless / CI (S6) — *à concevoir, pas à contourner*
+
+La cérémonie exige un humain au terminal. Pour un runner CI éphémère, trois options à
+trancher **plus tard** (aucune n'est urgente) : appairage du runner par son propriétaire au
+provisioning ; « appareil de service » à rôle réduit (écriture seule, jamais custodian) ;
+ou exclusion assumée (le CI passe par un membre humain). À documenter comme limite tant que
+non conçu.
+
+---
+
+## 4. L'URL d'activation — ce qu'elle change, ce qu'elle ne doit jamais porter
+
+L'idée de l'opérateur est bonne et **peu coûteuse** : l'URL est un véhicule pour le code
+d'invitation existant, pas un nouveau mécanisme.
+
+```
+https://app.brainclaw.dev/a/<code>          ← partageable à l'humain OU collée à l'agent
+brainclaw cloud connect <url|code> --agent x  ← la CLI accepte les deux formes
+```
+
+Ce que ça améliore : une seule chose à copier (aujourd'hui : code + URL + savoir où les
+mettre) ; un agent à qui on colle l'URL peut en extraire le code ET l'adresse du
+déploiement — ce qui règle au passage la non-persistance de l'URL.
+
+**Les invariants qui rendent l'URL sûre** (tous déjà en place pour le code) :
+usage unique, TTL 15 min, seul le SHA-256 stocké, et surtout — **l'URL ne donne aucun droit
+de lecture**. Elle n'ouvre que le droit de *candidater* ; la sécurité reste dans la
+comparaison d'empreintes à l'approbation, et les clés d'epoch ne voyagent **jamais** dans
+une URL.
+
+**Le piège à refuser explicitement** : mettre dans l'URL de quoi éviter l'approbation
+(« lien magique » qui active). Ce serait le modèle moltbook, voir ci-dessous.
+
+## 5. Pourquoi pas l'auto-enregistrement (le modèle moltbook), et ce qu'on en garde
+
+Le modèle « l'agent s'enregistre tout seul dans l'application » échoue sur trois points,
+tous structurels :
+
+1. **Aucune liaison de propriété** — n'importe quel processus connaissant l'URL devient un
+   agent du projet ; l'identité se squatte.
+2. **Le cloud peut fabriquer des agents** — sans approbation humaine par empreintes, un
+   cloud hostile insère son propre « membre fantôme » dans le projet, et le chiffrement de
+   bout en bout devient décoratif (c'est exactement l'attaque que l'attestation
+   X25519-par-Ed25519 ferme, migrations 0022/0025).
+3. **Rien ne lie l'agent à une clé** — un agent enregistré sans attestation ne peut pas
+   recevoir d'epoch de façon vérifiable.
+
+**Ce qu'on en garde** : la simplicité du geste — *un seul artefact à transmettre*. C'est
+précisément l'URL d'activation (§4) : la simplicité de moltbook, la cérémonie en dessous.
+
+---
+
+## 6. Besoins transverses (indépendants des parcours)
+
+| Besoin | Pourquoi | État |
+|---|---|---|
+| Envoi d'email (invitations, notifications d'approbation) | W4 | ❌ — skill `cloudflare-email-service` disponible |
+| CRUD agents cloud (`DELETE`, renommage, purge des agents v1 périmés) | W5, demande opérateur | ❌ |
+| État local multi-appairage (`connection.json` v3 : un `device`, une liste d'agents) | W2, trp#1625 | ❌ |
+| Persistance de l'URL du cloud dans l'état d'appairage | toutes les commandes | ❌ (mesuré) |
+| `connect` qui enchaîne l'attente d'approbation (supprime `await` du chemin nominal) | W1 friction | ❌ |
+| Pull v2 (`verifyInbound` câblé + matérialisation + curseur de feed) | W7 — sans lui, la fédération est **unidirectionnelle** | ❌ |
+| Application du quorum de récupération (aujourd'hui rapporté, jamais bloquant) | W6 | ❌ |
+| Écran « appareils par humain » (l'admin voit, le propriétaire approuve) | W4 | ❌ |
+
+## 7. Les arbitrages qui vous appartiennent (aucun n'est technique)
+
+Repris de dec#159 — à trancher **avant** W3/W4, parce qu'irréversibles par nature :
+
+1. **Horizon par défaut d'un nouveau membre** : rien / depuis l'adhésion / tout.
+   Recommandation technique : minimal (élargir reste toujours possible, reprendre jamais).
+2. **Qui est custodian** des remises de clés : le premier appareil ? tout membre `admin` ?
+   un quorum ? — et l'exigence d'indépendance des appareils de récupération.
+3. **Disponibilité** : accepter qu'un nouveau membre attende qu'un custodian soit en ligne,
+   ou financer une récupération explicitement détentrice de clés (coffre).
+4. **Équivocation du cloud** : aucun témoin / gossip d'équipe / journal de transparence.
+   Le cloud hostile qui montre des rosters différents à deux humains reste indétectable
+   sans canal hors bande — c'est une limite à afficher, pas à taire.
+
+## 8. Ordre de construction proposé
+
+Chaque tranche est livrable et vérifiable seule ; les deux premières ne demandent aucun
+arbitrage :
+
+1. **Fondations sans arbitrage** — état multi-appairage (W2), URL persistée + URL
+   d'activation (§4), `connect` qui attend, CRUD agents (W5-2). *Débloque S2 et la demande
+   opérateur immédiate.*
+2. **Pull v2** (W7-2) — la fédération devient bidirectionnelle ; sans lui, un deuxième
+   appareil n'aurait de toute façon rien à lire.
+3. **Invitation d'humains** (W4-1..3, email inclus) — après l'arbitrage §7-1 au minimum.
+4. **Remise d'epoch** (W3/W4-6/W6) — le gros œuvre, après les arbitrages §7-1/2/3.
+
+---
+
+*Références : dec#154 (cloud = projection), dec#155 (relais sans contexte), dec#156 (v2
+cassante), dec#158 (appairage deux niveaux), dec#159 (synthèse idéation, epoch grants),
+dec#160 (six divergences de contrat, résolues), trp#1610 (connect appaire le cwd),
+trp#1625 (connection.json singleton), critiques `CRITIQUE-codex.md` /
+`CRITIQUE-claude-code.md` (worktrees de l'idéation du 2026-08-09).*

package/docs/design/pairing-v3-brief.md

@@ -0,0 +1,80 @@
+# Idéation — repenser l'appairage de la fédération v2 (dec#158)
+
+**Direction opérateur (2026-08-09) :** un compte cloud doit gérer le solo-dev **et** l'équipe
+sans deux modèles distincts. L'admin du compte invite des utilisateurs **humains** par leur
+email ; chaque humain appaire ensuite **ses propres** agents.
+
+## État mesuré aujourd'hui — vérifié sur le code, ne pas re-supposer
+
+- `handleAddProjectMember` (`src/handlers/projects.ts`) cherche l'utilisateur **par email**
+  mais exige qu'il **existe déjà** : sinon `404 No user found with email`. Aucun flux
+  d'invitation — la personne doit s'inscrire d'abord, puis être ajoutée.
+- **Aucun envoi d'email** dans tout le backend.
+- `enrollments` porte `invited_by_user_id` (qui a invité) mais **aucun lien** vers l'humain
+  **propriétaire** de l'appareil.
+- L'invitation d'agent est créée par quiconque détient `enrollments.invite` sur le projet.
+- Cycle actuel d'un appareil : invite → claim → PoP → attestation X25519 → approbation
+  humaine → active.
+- Le scellement se fait sous une **clé d'epoch de projet**
+  (`buildEnvelope(keyEpoch)`, `epochPublicKey(cloudProjectId, epoch)`), **pas par appareil**.
+  Chaque appareil détient un **jeu** d'epochs (`heldEpochs`, `storeEpochPrivateKey`).
+- **Rien ne projette encore** : `buildEnvelope` a zéro appelant hors sa définition, l'outbox
+  v2 n'est jamais alimentée, 0 enveloppe reçue côté cloud.
+
+## Les trois conséquences à traiter, pas à redécouvrir
+
+1. **Qui approuve un agent doit changer.** L'approbation repose sur la comparaison hors
+   bande de deux empreintes entre l'écran web et le terminal de l'appareil. Un admin ne peut
+   pas vérifier le terminal d'un tiers : lui faire approuver l'agent d'autrui transforme la
+   vérification en clic de confiance et rouvre l'attaque de l'homme du milieu que la
+   cérémonie ferme (dec#8).
+2. **Un nouveau membre ne lit que les epochs qu'on lui remet.** Il ne peut rien lire du passé
+   tant qu'un membre existant ne lui transmet pas les epochs antérieurs, ou ne rescelle pas.
+3. **Chargement de l'historique et invitation d'équipe sont le même problème** : qui remet
+   quelles clés d'epoch à qui, et quand. Les traiter séparément produirait deux mécanismes de
+   transfert de clés — donc deux endroits où une clé peut aller où elle ne devrait pas.
+
+## Ce qui est attendu
+
+Proposez une conception, en la défendant sur les points **durs** plutôt que sur la partie
+facile — le formulaire d'invitation par email est trivial et n'intéresse pas.
+
+**(a) Modèle d'entités.** Où vivent les humains, où vivent les appareils, quel lien entre les
+deux. Un `owner_user_id` sur `enrollments` suffit-il ?
+
+**(b) Qui approuve quoi**, et comment le solo-dev ne subit **pas** la cérémonie d'équipe. Le
+solo doit rester un cas dégénéré du même modèle, pas une branche parallèle.
+
+**(c) La remise des clés d'epoch — le cœur du sujet.** Qui la fait, quand, sous quelle
+autorité, avec quelle preuve ? Un membre existant doit-il être **en ligne** pour qu'un
+nouveau membre rejoigne ? Que se passe-t-il si le seul détenteur d'un epoch quitte l'équipe
+ou perd sa machine ? Une clé d'epoch remise **ne se reprend pas** — comme la révocation ne
+retire pas ce qui a déjà été déchiffré.
+
+**(d) L'horizon d'un nouveau membre** : tout l'historique, rien, ou borné ? Argumentez le
+défaut, et dites ce qui devient **impossible à corriger après coup**.
+
+**(e) La rotation d'epoch sur changement d'appartenance.** Au départ d'un membre, faut-il
+tourner ? Quel est le coût réel, et que protège-t-on exactement sachant que le partant garde
+ce qu'il détient déjà ?
+
+**(f) Ce qui casse si le cloud est hostile.** Il orchestre l'appairage, donc il choisit qui
+voit quelle empreinte et quand. Où sa malveillance reste-t-elle **indétectable** ?
+
+## Contraintes dures
+
+- **dec#154** — le cloud est projection + relais, le local est source de vérité ; chemins
+  locaux, hôtes, sessions, clés et secrets **ne sortent jamais**.
+- **dec#155** — le relais cloud n'a ni session, ni cwd, ni contexte ambiant : seulement un id
+  d'entité et un `base_rev`.
+- **dec#8** — aucune clé collée à la main, aucune variable d'environnement ; l'humain compare
+  des empreintes.
+- Zéro dépendance runtime au-delà de `commander`/`yaml`/`zod` côté core.
+
+## Méthode attendue
+
+Ne convergez pas trop vite. **Nommez les alternatives que vous écartez** et pourquoi. Si une
+partie du sujet demande un arbitrage **produit** plutôt qu'une réponse technique, dites-le
+explicitement au lieu de trancher à la place de l'opérateur. **Signalez toute prémisse de ce
+brief que le code contredit** — plusieurs affirmations ci-dessus ont été mesurées, mais la
+mesure peut avoir manqué un chemin.

package/docs/integrations/mcp.md

@@ -47,7 +47,7 @@ Every tool has one of three tiers in its `annotations.tier` field:
 - **standard** — Day-to-day coordination tools: plans, claims, messaging, sequences, dispatch, review, memory. Returned by default alongside facades.
 - **advanced** — Specialized governance, audit, registry, and power tools.
 
-By default, `tools/list` returns **facade + standard** tools (44 tools). To get all tools including advanced, pass `{ "catalog": "all" }`, `{ "include": "all" }`, or `{ "advanced": true }`. To filter by a single tier, pass `{ "tier": "facade" }`, `{ "tier": "standard" }`, or `{ "tier": "advanced" }`.
+By default, `tools/list` returns **facade + standard** tools (46 tools). To get all tools including advanced, pass `{ "catalog": "all" }`, `{ "include": "all" }`, or `{ "advanced": true }`. To filter by a single tier, pass `{ "tier": "facade" }`, `{ "tier": "standard" }`, or `{ "tier": "advanced" }`.
 
 Published tools remain callable regardless of catalog filtering — the tier only affects discovery via `tools/list`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainclaw",
-  "version": "1.22.0",
+  "version": "1.24.0",
   "description": "Shared project memory for humans and coding agents.",
   "type": "module",
   "repository": {