Modèle mental

Un workspace est l'unité racine de Gilbert : une équipe, un client, une org. Tout ce qui se passe dans Gilbert se rattache à un workspace : intégrations OAuth, agents embed, repos liés, routines, connexions MCP, chat history.

Le workspace apparaît dans :

• Le claim iss de vos JWT SSO (c'est lui, pas un attribut data-* du snippet embed, qui rattache l'iframe à votre workspace)
• Le product_context qui route vos endpoints webhooks (voir Webhooks)
• La table gilbert.workspaces en base, avec FK workspace_id sur toutes les tables scopées

Isolation forte : un workspace ne voit jamais les données d'un autre. Un trigger Postgres crée automatiquement un workspace « personnel » à chaque signup, donc aucun user n'existe sans workspace.

Le product_context est un label preset hérité des premières versions : il indique le contexte produit d'un agent embed (solve-web, solve-learn, solve-holding, etc.) pour appliquer des allowlists de tools par défaut.

Aujourd'hui, c'est le workspace qui scope réellement les agents, les routines et les intégrations. Le product_context reste comme fallback de configuration et label d'identification, mais ce n'est plus le pivot du routing.

Gilbert reconnaît trois identités possibles. Choisir le bon mode conditionne la sécurité et l'UX :

Un dossier regroupe toutes les conversations, fichiers et states associés à un user (ou à un guest token) sur un product_context donné. Il persiste entre sessions.

Identifiant stable : dossier_id. Vous pouvez pré-sélectionner un dossier à l'ouverture de l'iframe via le param ?dossier=… : utile si vous gérez plusieurs contextes parallèles pour un même user.

1. 1. User tape un message dans l'iframe Gilbert
2. 2. Gilbert appelle POST /api/chat avec le JWT (ou le cookie session)
3. 3. Gilbert vérifie l'auth, charge le dossier, stream la réponse en NDJSON (text-delta, tool-call, finish)
4. 4. Si Gilbert appelle un tool métier (ex: create_quote), il dispatche un webhook signé vers votre backend
5. 5. Votre backend vérifie la signature HMAC, agit, répond 2xx
6. 6. Gilbert reçoit l'ack et continue le stream jusqu'à finish

Suite logique : voir API (format stream) et Webhooks (vérification signature, retry).