flowdeck/docs/architecture-agents-skills-notion-flowdeck.md

Architecture — Fonctionnalités « Agents & Skills » (modèle Notion) pour Flowdeck

Champ	Valeur
Version	1.0
Date	9 octobre 2026
Auteur	Spark, pour Bruno
Statut	Proposition d'architecture — à valider contre le code réel de Flowdeck
Produit cible	Flowdeck v7.69.8 (monolithe FastAPI / SSR Jinja2 + htmx + Alpine.js, SQLite WAL, API publique v2) — d'après ARCHITECTURE.md fourni par Bruno le 9 octobre 2026
Références fonctionnelles	Notion Agent (agent personnel), Custom Agents (agents autonomes partagés) et Skills (compétences réutilisables) dans Notion, tels que documentés dans le centre d'aide Notion, rubrique Notion AI

Historique des versions

• 1.0 — 9 octobre 2026 : analyse fonctionnelle d'après la documentation publique de Notion (pages Notion Agent, Custom Agents, Create & manage skills, guide Getting started with skills, page Manage your inbox with Notion Agent et hub Notion AI) et proposition d'architecture pour Flowdeck, ancrée sur l'état réel décrit dans ARCHITECTURE.md v7.69.8, §16 (IA : agent, compétences, connecteurs & écriture), §17 (recherche), §19 (automatisations & workers) et §9.3 (gouvernance de l'agent).

Avertissement méthodologique — à lire avant tout

L'architecture interne de Notion est propriétaire et n'est pas publique. Ce document ne prétend donc pas décrire « comment Notion est construit en interne ».

Il contient trois choses distinctes, clairement séparées :

1. Une analyse fonctionnelle (section 3) de ce que font Notion Agent, les Custom Agents et les Skills dans Notion, établie à partir de sa documentation publique officielle, consultée le 9 octobre 2026. C'est le comportement observable du produit, résumé avec mes mots.
2. Un état des lieux Flowdeck (section 4) tiré du document d'architecture v7.69.8 fourni par Bruno : ce qui existe déjà, ce qui existe partiellement, ce qui manque. C'est la différence majeure avec un exercice « page blanche » : Flowdeck possède déjà un moteur d'agent ReAct, des skills, des connecteurs et une gouvernance — le travail est un alignement, pas une création.
3. Une architecture cible originale (sections 5 à 23) pour porter Flowdeck à parité fonctionnelle. Les choix techniques, le modèle de données, les API et les diagrammes sont des propositions de conception qui respectent les invariants de Flowdeck (monolithe, SQLite, SQL brut, zéro bundler, CSP stricte, un seul processus), pas une reproduction de l'existant Notion.

Note de vocabulaire. Bruno a écrit « Nation Agent » dans sa demande ; il s'agit bien de Notion Agent. Dans tout le document : Agent personnel = l'assistant à la demande de chaque utilisateur (équivalent Notion Agent) ; Agent personnalisé / Custom Agent = un agent partagé, configurable, qui tourne aussi en arrière-plan sur déclencheurs ; Skill = une compétence réutilisable. On garde les noms anglais Agent et Skill quand ils désignent les objets produit, comme le document Meetings gardait AI Meeting Notes.

---

Table des matières

1. Résumé exécutif
2. Périmètre, personas et cas d'usage
3. Analyse fonctionnelle : Agents et Skills dans Notion
4. État des lieux Flowdeck v7.69.8 et analyse d'écart
5. Principes directeurs pour Flowdeck
6. Vue d'ensemble du système (C4)
7. Architecture front-end web 7A. Maquettes ASCII — panneau Agent, page Skill, réglages d'un Custom Agent
8. Architecture back-end
9. Flux et séquences clés
10. Modèle de données
11. API et événements
12. Moteur d'exécution de l'Agent
13. Moteur Skills
14. Connecteurs, sources et actions externes
15. Espace de travail fichiers (« computer ») de l'Agent
16. Sécurité, permissions et gouvernance
17. Exigences non fonctionnelles
18. Résilience et gestion des échecs
19. Déploiement et exploitation
20. Plan d'implémentation par phases
21. Décisions d'architecture (ADR — résumé)
22. Risques et mitigations
23. Questions ouvertes pour Flowdeck

• Annexe A — Correspondance Notion → Flowdeck
• Annexe B — Catalogue des outils de l'Agent
• Annexe C — Skills par défaut et presets à livrer
• Annexe D — Glossaire
• Sources

---

1. Résumé exécutif

Notion a transformé son IA en trois objets composables, et c'est cette composition — plus que n'importe quelle fonction isolée — qu'il faut reproduire dans Flowdeck :

Instructions   → ce que l'Agent doit toujours faire (permanent, personnel ou par agent)
Skill          → comment faire UN type de travail (réutilisable, partageable, page)
Agent          → qui fait le travail, avec quels accès, quels outils, quel modèle
  ├─ Agent personnel   : à la demande, dans le chat, avec TES permissions
  └─ Custom Agent      : partagé, autonome, déclencheurs + horaires, accès EXPLICITES

Objet	Question à laquelle il répond	Durée de vie	Portée
Instructions	« Comment dois-tu te comporter avec moi / pour ce travail, en permanence ? »	Toujours actives	Un utilisateur (Agent personnel) ou un Custom Agent
Skill	« Comment fait-on ce type de tâche, chez nous ? »	À la demande ou automatique quand ça correspond	Une tâche, une sélection, une page
Agent personnel	« Fais ce travail ponctuel ou multi-étapes, maintenant, avec mon contexte »	Une conversation	Les permissions de l'utilisateur
Custom Agent	« Fais ce travail récurrent pour l'équipe, même quand personne ne demande »	Déclencheurs / horaires, en arrière-plan	Uniquement les accès qu'on lui accorde explicitement

Où en est Flowdeck. D'après son architecture v7.69.8, Flowdeck a déjà le squelette complet : un moteur ReAct (agent_engine.py, 12 itérations max, journal d'actions annulables), 26 outils + outils MCP dynamiques, des agents personnalisés avec déclencheurs planifiés, des skills (prompts paramétrés + outils autorisés, galerie de 17 presets, format portable), des connecteurs (natifs, Google/Microsoft 365 en OAuth lecture seule, Discord/Telegram/Teams, client MCP complet), une mémoire par conversation, une gouvernance (politiques, approbations, outils destructifs sous confirmation) et un client LLM à 23 fournisseurs + mode offline déterministe.

Ce qui sépare Flowdeck de la parité Notion tient en cinq chantiers, détaillés en section 4 et planifiés en section 20 :

#	Écart structurant	Nature du travail
E1	Le Skill Notion est une page (et une base de skills est une base ordinaire dont chaque page est un skill, avec Description + Files) ; le Skill Flowdeck est un enregistrement agent_skills séparé de l'éditeur	Refonte du modèle Skill : skill = page marquée, base de skills = collection marquée, migration des 17 presets et du format portable (§10, §13)
E2	L'Agent Notion choisit tout seul un skill pertinent grâce à sa Description ; Flowdeck applique un skill choisi par l'utilisateur	Routeur de skills : appariement description ↔ demande, réutilisant l'index sémantique hybride existant (§13.2)
E3	Le Custom Agent Notion a des déclencheurs événementiels (commentaire, ligne ajoutée/modifiée/retirée, note de réunion terminée, message/réaction/mention dans un canal, courriel, calendrier) ; Flowdeck n'a que l'horaire	Brancher agent_triggers sur le bus d'événements des automatisations (fire_event(), §19.1 de l'architecture Flowdeck) — l'infrastructure existe, il manque le câblage (§9.4, §12.6)
E4	L'Agent Notion agit dans les apps connectées en écriture (poster/répondre dans Slack, rédiger/envoyer/archiver dans Gmail, trouver un créneau et réserver dans le calendrier, gérer l'Inbox) et dispose d'un espace fichiers pour ingérer PDF/CSV/XLSX et produire des fichiers téléchargeables ; Flowdeck est en lecture seule sur Google/MS365 et sans outil Inbox/calendrier/Slack	Nouveaux outils + connecteur Slack + passage des connecteurs Google en écriture gardée par approbation (§14, §15)
E5	Notion mesure et plafonne l'usage (allocation d'usage, crédits premium, limites par membre, modèles autorisés par surface, tableaux d'usage) ; Flowdeck configure des modèles mais ne compte rien	Compteur d'usage et crédits : journal de consommation par run, budgets, modèles autorisés séparément pour l'Agent personnel et les Custom Agents (§10.6, §16.5)

Recommandation principale. Ne pas créer un deuxième moteur. Tout le document fait évoluer agent_engine.py, tool_registry.py, context_builder.py, skill_gallery.py et les connecteurs existants, en réutilisant trois actifs que Notion a dû construire et que Flowdeck a déjà : le bus d'événements des automatisations (pour les déclencheurs), le moteur d'indexation sémantique hybride (pour le routage automatique des skills et la recherche d'entreprise) et la sandbox des Workers (pour l'espace fichiers / exécution de code de l'Agent). Le chantier est estimé en 5 phases (§20), dont les deux premières — skill-page et routeur de skills — livrent à elles seules l'essentiel de la valeur visible « façon Notion ».

---

2. Périmètre, personas et cas d'usage

2.1 Dans le périmètre

Agent personnel

• Chat omniprésent (panneau latéral / flottant, onglet Chat de la sidebar, historique cherchable, conversations épinglées).
• Contexte par défaut = page et blocs sélectionnés courants ; ajout de contexte par mentions @, sélecteur de sources (All sources), fichiers téléversés.
• Tâches multi-étapes : chercher, lire, créer/éditer pages et bases (propriétés, relations, vues y compris cartes et formulaires), interroger les bases par propriétés, lire commentaires et historique de versions.
• Résultats structurés dans le chat : tableaux interactifs, fichiers téléchargeables.
• Ingestion de fichiers (PDF, CSV, XLSX, DOCX, PPTX, ZIP) : questions-réponses, transformation en pages ou bases structurées.
• Gestion de l'Inbox (lire, regrouper, marquer, archiver en masse), actions Gmail, actions calendrier (trouver un créneau avec grille comparative, réserver, préparer une réunion), actions Slack (rechercher, lire, poster, répondre, réagir, éditer ses propres messages).
• Personnalisation : nom et apparence, page d'instructions personnelle (plusieurs pages possibles, commutables), mémoire.
• Choix du modèle : Auto ou modèle précis, modèles premium gouvernés par l'admin.

Custom Agents

• Création de trois façons : conversation de génération avec l'IA (brouillon d'instructions/déclencheurs/accès à relire), modèle de la galerie, ou page blanche.
• Réglages en trois onglets : Chat (tester), Activity (journal des runs), Settings (Instructions, Triggers, Tools and access, Modèle, Avancé).
• Déclencheurs combinables et filtrables : horaire récurrent, événements Flowdeck, événements de messagerie connectée, événement calendrier, événement courriel, note de réunion terminée, mention @agent.
• Accès explicites et minimaux : pages, collections, canaux, outils ; accès web commutable ; aucun accès par défaut.
• Délégation entre agents (un agent appelle d'autres agents comme sous-agents, chacun avec ses instructions, son accès et son modèle).
• Partage avec trois niveaux (Accès complet / Peut éditer / Peut voir et interagir), duplication avec règles de reprise, historique de versions de la configuration, intégration (embed) du chat d'un agent dans une page, mentions de l'agent dans pages, propriétés de base et commentaires.
• Insights : statistiques d'usage et export CSV des conversations.

Skills

• Skill = page : créer un skill depuis une page (Use as a skill), convertir une base en base de skills, propriétés Description, Files, Tags.
• Bibliothèque de skills dans Library (onglet Skills + onglet Discover, Enable for me), activation distincte de l'accès.
• Invocation : menu / dans le chat de l'Agent, menu / et menu de bloc et menu de sélection de texte dans l'éditeur, bascule « présent dans le menu de l'éditeur ».
• Usage automatique par l'Agent quand la description correspond ; nom du skill utilisé affiché dans la réponse et dans les sources.
• Usage par les Custom Agents (skill ajouté en Tools and access + consigne d'usage dans les instructions).
• Export vers les agents locaux au format SKILL.md (fichiers de support inclus, badge de désynchronisation quand la page change), import d'un skill externe conforme au même format.
• Création assistée : décrire son savoir-faire à l'Agent, qui rédige le skill.

Transverse

• Modèles : catalogue, Auto, modèles autorisés par surface, activation admin des modèles premium, repli quand un modèle est retiré.
• Mesure : allocation d'usage, crédits, limites par membre/agent, tableaux d'usage, coût par run dans Activity.
• Gouvernance : politiques d'outils existantes étendues, approbations pour les écritures externes, journal d'audit des changements de configuration d'agent.

2.2 Hors périmètre (au moins aux premières phases)

• Application mobile dédiée « Agents » (le panneau reste responsive ; Flowdeck est une PWA).
• SDK public permettant à une application externe de continuer une conversation d'agent en streaming (l'API v2 synchrone existante suffit ; extension possible en Phase 5, §11.4).
• Serveur MCP Flowdeck officiel exposant Flowdeck aux agents externes : déjà un chantier distinct documenté côté Flowdeck (FLOWDECK_MCP_SERVER_GUIDE.md, non implémenté) — ce document ne couvre que le client MCP de l'Agent, déjà livré.
• Génération/édition d'images par l'Agent (fonction Notion AI voisine, hors demande).
• Traduction de pages entières comme fonction d'espace de travail (les skills de traduction couvrent le besoin dans le chat et l'éditeur).
• Tout ce que l'Agent Notion déclare ne pas faire (§3.7) reste, par défaut, hors périmètre Flowdeck aussi — ce sont des garde-fous produit, pas des manques.

2.3 Personas

Persona	Besoin dominant	Fonction critique
Utilisateur quotidien	« Fais-le à ma place, avec mon contexte, sans quitter ma page »	Agent personnel, skills en un /, résultats dans le chat
Auteur de skill	Capitaliser un savoir-faire répété et le rendre exécutable par tous	Skill-page, Description soignée, fichiers d'exemple
Créateur de Custom Agent	Automatiser un travail récurrent d'équipe, de façon sûre	Déclencheurs filtrés, accès minimaux, Activity relisible
Responsable d'équipe	Que les mêmes standards s'appliquent partout	Base de skills partagée, agents partagés, Discover / Enable for me
Admin de workspace	Contrôler modèles, coûts, accès et création d'agents	Modèles autorisés, limites de crédits, audit, qui peut créer des agents
Développeur / intégrateur	Brancher des outils externes et réutiliser les skills hors Flowdeck	Client MCP, API v2 agents/skills, export SKILL.md

2.4 Cas d'usage structurants

• UC-01 — Tâche ponctuelle multi-sources : « À partir de la page Objectifs, des issues Gitea du trimestre et du dernier compte rendu, rédige les OKR du trimestre suivant, avec responsables et lien vers la source de chaque résultat clé. »
• UC-02 — Skill manuel : dans le chat, taper /, choisir Project Brief Writer, pointer des notes brutes, obtenir un brief au format d'équipe.
• UC-03 — Skill automatique : demander « transforme ces notes d'entretien en synthèse » sans nommer de skill ; l'Agent reconnaît la description du skill Synthèse d'entretien, l'applique, et affiche son nom dans les sources.
• UC-04 — Skill dans l'éditeur : sélectionner un texte, choisir un skill dans le menu de sélection (les skills personnels d'abord, puis les skills intégrés : améliorer, corriger, expliquer, reformater) ; ou ouvrir le menu d'un bloc → Skills.
• UC-05 — Custom Agent horaire : chaque lundi 8 h, un agent lit la base Projets, regroupe les tâches par statut et poste le résumé dans le canal d'équipe connecté.
• UC-06 — Custom Agent événementiel : une ligne ajoutée à la base Tickets avec le statut « À trier » déclenche un agent de triage qui classe, assigne et commente par une page de synthèse.
• UC-07 — Délégation : un agent « Rapport hebdomadaire » délègue la collecte à un agent lecteur, la mise en forme à un agent rédacteur (modèle léger), puis assemble et publie.
• UC-08 — Fichiers : téléverser un CSV de retours clients ; l'Agent l'analyse dans son espace fichiers, produit les thèmes et recommandations avec citations, crée la base correspondante et rend un XLSX nettoyé téléchargeable.
• UC-09 — Inbox et calendrier par le chat : « Quoi de neuf dans mon Inbox ? Groupe par projet, archive ce qui est lu. » ; « Trouve un créneau de 30 minutes avec A et B demain après-midi » → suggestions classées + grille, réservation en un clic.
• UC-10 — Skill hors Flowdeck : télécharger un skill vers un agent local (format SKILL.md) ; quand la page du skill évolue, un badge signale qu'il faut re-télécharger.

---

3. Analyse fonctionnelle : Agents et Skills dans Notion

Cette section résume, avec mes mots, le comportement documenté publiquement par Notion (centre d'aide, rubrique Notion AI, consulté le 9 octobre 2026). Elle sert de cahier des charges fonctionnel de référence pour Flowdeck. Les exemples de prompts de la documentation sont reformulés, jamais repris tels quels.

3.1 Les quatre objets et leur articulation

La documentation de Notion distingue explicitement quatre notions que les utilisateurs confondent — et que Flowdeck doit distinguer de la même façon :

Objet	Ce que c'est	Quand il démarre
Instructions	Une consigne permanente qui façonne le comportement de l'Agent (ton, règles, contexte de rôle, pages à consulter d'abord)	Toujours actif
Skill	Une méthode, un standard ou un format réutilisable pour un type de travail	Choisi par l'utilisateur, ou utilisé par l'Agent quand il correspond
Notion Agent	L'assistant personnel à la demande, dans le chat	L'utilisateur demande
Custom Agent	Un coéquipier IA configuré (instructions, accès, outils, déclencheurs propres) et partageable	Un humain, un horaire ou un événement le déclenche ; il peut tourner seul

Leçon d'architecture n° 1 — la règle du double copier-coller. La documentation donne un critère simple pour créer un skill : si la même consigne risque d'être collée deux fois, c'est un candidat skill. Corollaire pour Flowdeck : le skill n'est pas un « gros prompt système », c'est l'unité de capitalisation du savoir-faire — il doit donc vivre là où le savoir-faire vit déjà, c'est-à-dire dans les pages (§3.4).

Leçon d'architecture n° 2 — deux régimes de permissions, pas un. L'Agent personnel hérite des permissions de son utilisateur : il ne voit et ne modifie que ce que l'utilisateur peut voir et modifier. Le Custom Agent, lui, fonctionne en liste blanche : aucun accès par défaut, uniquement les pages, bases et apps explicitement ajoutées dans ses réglages. Mélanger les deux régimes (un agent autonome avec les droits de son créateur) est l'erreur de conception à ne pas importer.

3.2 L'Agent personnel (Notion Agent)

Surfaces. Un visage d'agent en bas de l'interface ouvre le chat ; le chat existe aussi en mode barre latérale droite ou fenêtre flottante (réglage Switch chat mode), dans un onglet Chat de la barre latérale, et depuis l'Inbox. Au-dessus de la zone de saisie : des actions suggérées dépendantes de la page courante (par exemple extraire les actions d'une page, ou la raccourcir). Les conversations passées sont retrouvables par un historique cherchable, nommées d'après leur sujet ; une conversation peut être épinglée en haut de l'onglet Chat.

Contexte. Par défaut, l'Agent travaille sur la page courante — et, si des blocs sont sélectionnés, sur ces blocs. Trois mécanismes ajoutent du contexte :

1. la mention @ (pages, personnes) dans la zone de saisie ou dans le texte de la demande ;
2. le sélecteur All sources, qui liste les sources consultables, y compris les serveurs MCP connectés ;
3. le trombone 📎, qui téléverse un fichier pour la conversation.

Capacités documentées (regroupées par domaine) :

Domaine	Ce que l'Agent peut faire
Pages	Créer et éditer des pages, en s'appuyant sur des pages de référence mentionnées (guide de style, PRD…)
Bases de données	Créer/éditer des bases, des propriétés (dont relations entre bases), des vues — y compris vues carte et formulaire
Recherche & Q&R	Répondre sur le workspace et les apps connectées (connecteurs), interroger les bases jusque dans les propriétés, lire les commentaires et chercher dans l'historique de versions
Résultats en tableau	Quand le résultat est des données, l'afficher en tableau interactif dans le chat, sans ouvrir la base
Fichiers entrants	Ingérer PDF et CSV (et, dans l'espace de travail fichiers, XLSX, DOCX, PPTX, ZIP) : répondre dessus, ou les transformer en pages/bases structurées
Espace de travail fichiers	Dans un environnement sécurisé : lire les fichiers déposés, calculer (au besoin exécuter du code simple), et produire des fichiers téléchargeables (tableurs, présentations, PDF, documents)
Analyse de données	Comparaisons et synthèses chiffrées avec explications (écarts budgétaires, par exemple)
Inbox	Lire, résumer, regrouper (par type, statut de lecture, projet/page) et archiver les notifications, y compris en masse ; détail en §3.5
Gmail connecté	Chercher, rédiger, envoyer, archiver, jeter, étiqueter, se désabonner ; les écritures demandent une confirmation avant exécution
Calendrier connecté	Trouver un créneau entre participants (suggestions classées + grille horaire interactive, réservation en un clic), préparer une réunion, replanifier, bloquer du temps de tâche ; en cas de calendriers multiples, utiliser le calendrier par défaut ou demander
Slack connecté (compte personnel)	Agir en tant que l'utilisateur : chercher des personnes, lire les canaux accessibles (publics, privés, messages directs), lire les messages récents et fichiers partagés, poster, répondre en fil, éditer ses propres messages, ajouter/retirer des réactions — limité à ce que l'utilisateur voit
Apps via MCP	Connecter un serveur MCP (depuis le chat, depuis All sources → MCP servers → Add MCP server, ou Settings → Connections → Discover), s'authentifier, puis consulter et — selon le serveur — agir dans l'app
Formules	Créer, éditer et évaluer des formules de base de données

Personnalisation. Depuis le chat, rouvrir le visage de l'Agent donne accès à : nom et accessoires de l'avatar, et Add instructions. Les instructions peuvent être une page existante du workspace, un modèle, ou une page créée pour l'occasion — une page privée (nommée, dans la documentation, My Notion AI) qui peut décrire le ton souhaité, ce que l'Agent doit retenir du rôle et des habitudes de l'utilisateur, et les pages/canaux/fichiers à consulter en premier. L'Agent s'y réfère à chaque interaction, peut la mettre à jour sur demande de l'utilisateur, et l'utilisateur peut maintenir plusieurs pages d'instructions et changer de comportement en changeant de page. Point de vigilance documenté : quiconque peut éditer la page d'instructions modifie le comportement de l'Agent — pour partager un exemple, on partage une copie.

Modèles. Le sélecteur de modèle propose Auto (Notion choisit par tâche) ou un modèle nommé (familles Claude, GPT, Gemini, Grok dans la documentation consultée, avec des modèles « premium » selon les plans). Un modèle peut, selon son type, ne regarder que le web et pas le workspace : le choix du modèle modifie donc les sources accessibles, pas seulement la qualité. Les modèles premium consomment des crédits et doivent être activés par un admin du workspace avant d'apparaître (§3.6).

Feedback. Pouce haut/bas sur les réponses ; le pouce bas ouvre un motif. La documentation précise que ce feedback sert à améliorer le produit et n'entraîne pas l'Agent de l'utilisateur.

3.3 Les Custom Agents

Définition. Un Custom Agent est un flux de travail partagé, construit une fois, qui tourne en arrière-plan selon ses déclencheurs, en utilisant documents et bases comme contexte. Exemples types de la documentation : rapports récurrents, tri de retours, maintenance de connaissances.

Création — trois portes, un même objet. Depuis la section Agents de la barre latérale (+) :

1. Créer avec le chat IA : décrire le travail en langage naturel ; l'IA génère un brouillon — instructions, déclencheurs, accès — que l'on relit et ajuste avant d'enregistrer.
2. Créer depuis un modèle : partir d'un modèle de galerie, même relecture.
3. Créer à blanc : champ d'instructions vide, réglages manuels.

La documentation insiste sur la rédaction des instructions : partir du travail et du résultat attendu, puis étapes concrètes, entrées, sorties, exemples.

Déclencheurs — combinables, filtrables. Un même agent peut en cumuler plusieurs, avec filtres (valeur de propriété, vue de base, mot-clé) :

Famille	Déclencheurs documentés
Horaire	Récurrence jour / semaine / mois / année, heure et fuseau précis, aperçu du prochain passage avant enregistrement
Événements Notion	Commentaire ajouté à une page ; page ajoutée à une base ; propriété mise à jour dans une base ; page retirée d'une base ; note de réunion IA terminée
Événements Slack	Message posté dans un canal ; réaction emoji ajoutée ; agent mentionné dans un message — avec inclusion optionnelle des réponses en fil, filtres par mot-clé, et indicateur « en train d'écrire » désactivable par déclencheur
Mention	@mention de l'agent dans les pages, les propriétés de base et les commentaires de Notion

Accès — Tools and access. L'agent ne lit que ce qui lui est accordé : pages et bases précises, ou l'ensemble « partagé avec tout le workspace » pour une couverture large ; réglage par défaut recommandé : rien, ou un petit ensemble. Deux précisions structurantes de la documentation :

• lier une page dans les instructions n'accorde pas l'accès — les liens d'instructions et l'accès outillé sont deux choses distinctes ;
• l'accès web est un interrupteur séparé, à couper pour les flux strictement internes.

Slack pour Custom Agents. Préalable : un admin connecte Slack au workspace (connecteur) ; ensuite, par agent : choisir les canaux lisibles et les seuls canaux où il peut poster, répondre et réagir. Le compte Slack doit porter le même courriel que le compte Notion dans le parcours documenté.

Délégation entre agents. Un agent principal peut confier une partie du travail à d'autres Custom Agents auxquels on lui donne accès dans Tools and access, en décrivant dans ses instructions quoi déléguer et ce que chaque sous-agent doit renvoyer. Chaque sous-agent garde ses instructions, son contexte, son accès et son modèle. Bonnes pratiques documentées : commencer par un ou deux sous-agents, tester chacun seul avant le flux complet, modèle fort pour l'agent qui planifie et assemble, modèles légers pour les sous-tâches ciblées, et surveiller Activity/Insights — chaque délégation consomme des crédits.

Modèles des Custom Agents. Même catalogue que l'Agent personnel, Auto recommandé par défaut ; l'admin peut restreindre les modèles autorisés pour les Custom Agents (Settings → Notion AI → General → Allowed models for Custom Agents) ; si un modèle utilisé est désactivé, l'agent bascule automatiquement sur le modèle par défaut ou Auto. Certains modèles premium exigent une activation admin explicite, motivée dans la documentation par un régime de conservation des données différent chez le fournisseur.

Partage et permissions — modèle simplifié à trois niveaux.

Niveau	Peut
Accès complet	Configurer (instructions, déclencheurs, accès, modèle), voir et gérer les journaux d'activité, exécuter et utiliser l'agent
Peut éditer	Modifier instructions et configuration, consulter l'activité
Peut voir et interagir	Exécuter et discuter avec l'agent, voir les réglages en lecture seule ; ni éditer, ni partager

Partage à des personnes, des groupes ou tout le workspace. Un agent partagé apparaît dans la section Agents de la barre latérale, dans la recherche et partout où les agents sont listés. Nuance documentée : des personnes sans accès à l'agent peuvent quand même le déclencher indirectement (par exemple via un canal Slack accessible), et quiconque a accès à l'agent voit ses sorties, même sans accès au canal privé d'origine.

La page d'un Custom Agent — trois onglets.

1. Chat : conversation dédiée (privée ou partagée) — tester les instructions, lancer des tâches ponctuelles, déboguer en dialoguant.
2. Activity : journal de chaque exécution (déclencheur, actions, erreurs), visible avec l'Accès complet ; c'est l'outil de débogage : ouvrir le run en échec, voir ce qui l'a déclenché, ce que l'agent a « pensé » et fait à chaque étape, puis corriger instructions ou déclencheurs et relancer.
3. Settings : instructions, déclencheurs, accès, modèle — enregistrer et publier, puis vérifier dans Chat et Activity.

Intégration dans une page (embed). Coller le lien d'un Custom Agent dans une page et choisir Embed y installe son chat. L'intégration n'accorde aucun accès nouveau (il faut partager l'agent), et l'agent ne lit pas la page hôte sauf si elle est ajoutée à ses accès. Cas types : agent Q&R sur un hub de projet, agent d'accueil sur la page d'équipe.

Historique de versions et duplication. La configuration d'un agent a un historique de versions (qui, quand, quoi) avec restauration. La duplication crée une copie privée par défaut, nommée avec un suffixe numérique, dont les règles de reprise sont précises :

Repris dans la copie	Non repris
Nom (suffixé), modèle, instructions (nouvelle page copiée)	Connexions d'outils (à reconnecter)
Pages/bases et déclencheurs auxquels le duplicateur a accès (les ressources inaccessibles apparaissent en jetons « sans accès » et sont exclues)	Workers associés (à reconfigurer)
	Historique des runs (la copie repart de zéro)
	Limites de crédits de l'original

Insights. Un onglet Insights expose l'usage ; l'export CSV des conversations (plafonné, 300 conversations par période dans la documentation) est réservé à l'Accès complet, et un admin doit s'ajouter à chaque agent pour exporter à l'échelle du workspace.

Administration. Par défaut, tout le monde dans le workspace peut créer des Custom Agents ; les plans supérieurs permettent à l'admin de restreindre qui peut créer. Les changements de configuration et d'accès des Custom Agents alimentent le journal d'audit de l'espace de travail (sur les plans concernés).

3.4 Les Skills

Définition. Un skill est un ensemble d'instructions réutilisables qui apprend à l'IA une façon de faire un type de travail : objectif, entrées, règles/standards, exemples, sortie attendue. Cas types documentés : reformuler aux standards d'un dirigeant, transformer des notes de réunion en actions ou en courriel de synthèse, convertir un brouillon en modèle précis (FAQ, résumé de PRD, squelette de spécification), uniformiser un format. La documentation oppose le skill « focalisé sur un type de travail » aux instructions générales : un skill trop large est un mauvais skill.

Le skill est une page — c'est le point central. Toute page peut être marquée comme skill (••• → Use as a skill, ou en demandant à l'Agent de le faire) ; les pages-skill portent une bannière distinctive. Conséquences immédiates, toutes documentées :

• organiser et partager un skill = organiser et partager une page (mêmes permissions, même historique de page) ;
• quiconque peut éditer la page peut changer le skill pour tous ses utilisateurs — choisir les éditeurs avec soin, l'historique permet de revenir en arrière ;
• un Custom Agent utilise un skill en recevant accès à sa page dans Tools and access, plus une consigne dans ses instructions disant quand l'utiliser.

La base de skills. Créer un skill le range dans une base de skills privée par défaut. Une base de skills est une base ordinaire transformée (Turn into Skills database, avec correspondance des propriétés existantes vers les rôles attendus) ou créée directement comme base de type Skills ; toute page créée dedans devient automatiquement un skill. Propriétés pré-installées :

Propriété	Rôle
Description	Ce que fait le skill et quand l'utiliser — c'est elle que l'Agent lit pour décider d'un usage automatique
Files	Matériaux de support : exemples, documents de référence, images, données, scripts
Tags	Étiquettes (rôle prévu dans l'assistant de conversion)

On peut ajouter les propriétés de gestion d'équipe (Owner, Status…). Recommandation documentée : commencer par une seule base partagée, n'en ajouter (équipe, privée) que lorsque les accès, les responsables ou le besoin de brouillon privé divergent. Déplacer une page existante (un playbook, un how-to) dans une base de skills la transforme en skill ; la base sert à gérer, la Library sert à trouver.

La Library, onglet Skills. La Library (barre latérale) a un onglet Skills : skills créés, skills disponibles, gestion. Un onglet Discover présente les skills partagés par l'éditeur, l'admin ou les coéquipiers. Deux notions que la documentation sépare soigneusement :

• l'accès décide qui peut ouvrir/éditer le skill (permissions de la page) ;
• l'activation (Enable for me) décide s'il apparaît dans mes menus. Tout skill créé par l'utilisateur est activé pour lui d'office ; un skill partagé doit être activé depuis Discover. Désactiver un skill découvert le retire pour soi seul ; supprimer la page le retire pour tout le monde ; Use as AI skill décoché retransforme la page en page ordinaire, contenu conservé.

Création assistée. Depuis le chat (/ puis +, ou simplement demander à créer un skill), l'Agent guide la rédaction : l'utilisateur décrit le travail comme il le fait d'habitude, avec le contexte qu'il donnerait normalement, et l'Agent met ce savoir-faire en forme de skill. Anatomie d'un bon skill, selon le guide : objectif, entrées, règles (sections habituelles, ton, terminologie, longueur), exemples qui montrent « ce que bon veut dire », sortie attendue — avec des exigences explicites (« cinq puces », « risques et prochaines étapes inclus »), une page courte qui lie les références longues plutôt que de tout contenir, et un responsable nommé pour les skills partagés.

Invocation — quatre surfaces.

Surface	Geste	Conditions documentées
Chat Agent	/ puis choisir, ou /nom-du-skill	Le skill utilisé est nommé dans la réponse ; en chat pleine page, il apparaît aussi dans la barre des sources/connaissances
Menu de sélection de texte	Sélectionner, choisir le skill	Seuls les skills avec l'option Add to text editor menu y figurent ; les skills de l'utilisateur d'abord, puis les intégrés
Menu slash dans une page	/skill à côté d'un contenu	Il faut du contenu sur la ligne : un skill a besoin de matière à traiter
Menu de bloc	Survol → poignée du bloc → Skills → choisir	Types de blocs éligibles énumérés (texte, titres, citation, callout, listes, to-do, toggle, image, blocs synchronisés) ; les blocs vides ou non éligibles n'offrent pas de skills ; le contenu imbriqué d'un bloc est inclus dans le traitement

Usage automatique. Activé par défaut : si la demande correspond à un skill disponible, l'Agent l'utilise sans qu'on le nomme. Conditions et contrôles documentés :

• l'usage automatique exige une Description — donc un skill doit vivre dans une base de skills pour en avoir une ; une page-skill autonome doit d'abord y être ajoutée ;
• l'interrupteur Use automatically (dans l'onglet Skills de la Library ou sur la page du skill) réserve un skill à l'invocation manuelle ;
• la qualité de l'appariement dépend directement de la clarté de la description.

Skills intégrés. Le menu de sélection propose par défaut quatre skills d'édition — améliorer l'écriture, corriger, expliquer, reformater — auxquels les skills créés s'ajoutent en tête et peuvent se substituer ; le guide de démarrage cite en outre des skills par défaut de traduction et de résumé. Ce sont les mêmes fonctions que l'« AI Writing » historique, re-présentées comme skills : conséquence pour Flowdeck au §4.

Skills et agents locaux externes. Un skill peut être téléchargé vers un agent local pris en charge (les agents de code cités dans la documentation : Claude Code, Codex, Cursor, Gemini, Grok…) : depuis la page du skill (••• → Download to local agents, ou la bannière prévue), l'outil écrit un fichier SKILL.md dans le répertoire de skills de chaque agent choisi, accompagné des fichiers de support approuvés au partage (propriété Files). Deux règles de fonctionnement, documentées :

• activation dans Notion et téléchargement local sont deux actions indépendantes ;
• la copie locale ne se synchronise pas : quand la page du skill change, un badge orange sur la page signale qu'il faut re-télécharger pour mettre l'agent local à jour.

Échelle d'équipe (guide d'adoption). Le guide de passage à l'échelle (hub Notion AI) prolonge le même modèle : une base partagée par équipe, des responsables par skill, la Library comme point de découverte, et la gouvernance par les permissions ordinaires des pages et des bases — pas d'outil d'administration séparé pour les skills.

3.5 Fonctions voisines du hub Notion AI qui touchent l'Agent

Le hub Notion AI regroupe des fonctions dont plusieurs sont des dépendances de l'Agent et des Skills ; le document les traite comme telles :

Fonction (hub)	Lien avec ce document
Enterprise Search / Q&A	Le socle de recherche inter-sources (workspace + connecteurs) que l'Agent utilise pour répondre ; chez Flowdeck, c'est la recherche hybride + Ask AI (§17 de l'architecture Flowdeck)
AI Connectors	Les connexions d'apps (Slack, Gmail, Calendar…) qui alimentent l'Agent en sources et en actions ; chez Flowdeck, le système de connecteurs du Menu ＋ (§16.4 Flowdeck)
Notion MCP (serveur)	Exposer Notion à des agents externes ; et, en miroir, connecter des serveurs MCP à l'Agent (§3.2) — Flowdeck a le client, le serveur est un chantier séparé déjà documenté
Instructions pour l'Agent	La page d'instructions personnelle du §3.2 fait l'objet d'une page d'aide dédiée du hub
Gestion de l'Inbox par l'Agent	Page d'aide dédiée : l'Agent lit/regroupe/archive les notifications — mais ne peut ni approuver/refuser les demandes d'accès et d'approbation intégrées, ni créer de notifications, ni changer les réglages de notification ; l'Inbox reste la source de vérité
Navigateur web pour l'Agent	L'accès web de l'Agent est une capacité administrable séparément (interrupteur par agent chez les Custom Agents, §3.3)
Modèles et dépenses	Page d'aide dédiée à la gestion des modèles d'IA et des limites de dépense par membre (§3.6)
AI Meeting Notes	La fin d'une note de réunion est un déclencheur de Custom Agent ; le reste de la fonction est couvert par le document Meetings de Flowdeck
Workers	Des exécutions de code planifiées/partagées que les Custom Agents peuvent utiliser ; la duplication d'un agent ne les reprend pas (§3.3). Flowdeck a déjà ses Workers sandboxés (§19.2 Flowdeck)

3.6 Modèles, allocation d'usage et crédits

Trois mécanismes distincts coexistent dans la documentation — Flowdeck doit les reproduire comme trois compteurs distincts, sous peine de confusion :

1. L'allocation d'usage incluse : les plans payants incluent un volume d'usage pour certaines fonctions d'IA (dont l'Agent) ; quand elle est épuisée, ces fonctions se mettent en pause jusqu'à son renouvellement (la documentation évoque un rafraîchissement dans une fenêtre de quelques heures, et renvoie aux réglages pour l'état courant).
2. Les crédits premium : les modèles premium et les Custom Agents consomment des crédits achetés par le workspace ; un admin active chaque modèle premium et peut fixer une limite de dépense par membre ; à limite atteinte, les modèles inclus au plan restent utilisables.
3. Les modèles autorisés par surface : l'admin décide quels modèles sont disponibles pour l'Agent personnel et, séparément, pour les Custom Agents ; un modèle retiré disparaît (grisé) des menus, et un agent qui l'utilisait bascule sur le défaut/Auto.

Leçon d'architecture n° 3 — le coût est une donnée du run, pas une surprise de facture. Chaque exécution affiche son contexte d'usage (modèle, activité, insights), et les concepteurs d'agents sont invités à comparer modèle, qualité et crédits entre runs. Flowdeck doit donc journaliser la consommation au niveau du run dès la Phase 4 (§10.6), même avant d'activer un quelconque plafonnement.

3.7 Ce que l'Agent ne fait pas — limites documentées

La page de l'Agent énumère explicitement ses incapacités. Ce sont des décisions produit (souvent des garde-fous), et ce document les adopte comme non-objectifs par défaut pour Flowdeck (§2.2) :

• répondre à partir de contenus embarqués non-PDF (par exemple la transcription d'une vidéo embarquée) ;
• créer des automatisations de base, des modèles de base, des mises en page de page de base, ni des propriétés avancées (formules, rollups, boutons) — alors même qu'il peut créer/éditer des propriétés simples et des vues, et manipuler des formules existantes ;
• créer ou éditer des commentaires, en ligne ou en tête de page ;
• partager des pages ou changer leurs niveaux de permission ;
• démarrer des AI Meeting Notes ;
• créer des rappels ;
• gérer les réglages de niveau workspace (rôles des membres, facturation, sécurité) ;
• éditer/annuler un événement de calendrier dont l'utilisateur n'est pas l'organisateur ;
• (mobile) planifier/annuler des événements et connecter de nouveaux serveurs MCP — réservés au web/desktop.

Leçon d'architecture n° 4 — l'absence d'outil est la politique. Chacune de ces limites correspond, côté implémentation, à un outil qui n'existe pas dans le registre de l'Agent (pas de share_page, pas de create_reminder…). C'est exactement le modèle Flowdeck actuel (26 outils énumérés, aucun outil de partage) : la parité se joue donc en gardant le registre fermé et explicite, pas en ajoutant des interdits au prompt.

3.8 Synthèse : les invariants fonctionnels à reproduire

#	Invariant Notion	Section cible Flowdeck
I1	4 objets distincts : Instructions / Skill / Agent personnel / Custom Agent	§5, §10
I2	Agent personnel = permissions de l'utilisateur ; Custom Agent = liste blanche explicite, rien par défaut	§16.1
I3	Le skill est une page ; la base de skills est une base ; Description pilote l'automatique	§10.3, §13
I4	Accès ≠ activation (Enable for me, Discover)	§10.4, §13.5
I5	Le skill utilisé est nommé dans la réponse et listé dans les sources	§12.4, §13.3
I6	Instructions = une page, éditable, commutable, dont l'édition vaut changement de comportement	§10.2, §12.3
I7	Déclencheurs combinables et filtrés, dont les événements du workspace et des canaux	§12.6
I8	Délégation agent → agent, chacun avec accès/modèle propres	§12.7
I9	Écritures externes = confirmation préalable (Gmail) ; actions Slack « en tant que l'utilisateur » bornées à sa visibilité	§14
I10	Trois onglets par agent : Chat / Activity / Settings ; runs débogables étape par étape	§7, §12.8
I11	Configuration versionnée et restaurable ; duplication privée avec reprise partielle et explicite	§10.5, §11
I12	Modèles : Auto par défaut, premium activés par l'admin, autorisés par surface, repli automatique	§12.2, §16.5
I13	Usage mesuré par run ; allocation, crédits et limites par membre sont trois compteurs distincts	§10.6, §16.5
I14	Les limites de l'Agent sont des outils absents du registre, pas des consignes au modèle	§12.5, Annexe B

---

4. État des lieux Flowdeck v7.69.8 et analyse d'écart

Source unique de cette section : ARCHITECTURE.md v7.69.8 fourni par Bruno (§16 en premier lieu, puis §9.3, §13, §15, §17, §18, §19, §21). Quand un point n'y figure pas, il est marqué « non décrit » plutôt que supposé absent du code.

4.1 Ce que Flowdeck a déjà — et qui correspond directement au modèle Notion

Capacité Notion	Équivalent Flowdeck v7.69.8	État
Moteur d'agent conversationnel multi-étapes	Moteur ReAct (agent_engine.py) : boucle objectif → contexte → raisonnement ↔ action, plafond d'itérations, budget tokens, timeout ; le LLM n'émet que des intentions d'outils	✅ Présent
Panneau de chat	Panneau agent (/api/agent/*, agent_panel.html) : conversations, CRUD d'agents personnalisés, mentions @/＋, feedback 👍/👎, flux SSE (reasoning, action, notice, final, error)	✅ Présent
Agents personnalisés	Table agents : instructions système, scope_json d'outils autorisés, approval_mode, modèle ; déclencheurs planifiés (agent_triggers, scheduler 60 s) ; trigger externe synchrone par l'API v2	🟡 Partiel — voir §4.2
Outils	ToolRegistry, 26 outils statiques (lecture/écriture pages, collections, propriétés, relations, vues, templates, Gitea, web, GitHub, connecteurs) + outils MCP dynamiques fusionnés à chaque run depuis le cache des connecteurs	✅ Présent
Annulation / réversibilité	Chaque action est journalisée dans agent_actions avec snapshot d'annulation ; rollback unitaire par API	✅ Présent — plus fort que le minimum Notion
Contexte filtré par permissions	context_builder.py : snapshot Markdown filtré par permissions, mentions résolues (@document:, @collection:, @page:, @folder:), guide in-app	✅ Présent
Mémoire	agent_memory.py : résumé par conversation réinjecté (plafonné), interrupteur memory_enabled	✅ Présent
Skills	skill_gallery.py, table agent_skills : prompts paramétrés + liste d'outils autorisés ; CRUD/apply/édition ; galerie de 17 presets ; format portable flowdeck-skill v1 (export/import JSON) ; routes cookie et /api/v2/skills/* ; menu Skills dans le Menu ＋ de l'assistant, dans le menu contextuel de bloc et dans la toolbar de sélection de l'éditeur (§13.3 de l'architecture : « Skills › »)	🟡 Partiel — modèle différent, voir §4.2
AI Writing (ancêtre des skills intégrés)	ai_writing.py : 6 actions headless (écrire, résumer, traduire, continuer, autocomplétion, propriétés) consommées par l'éditeur	✅ Présent — à re-présenter comme skills intégrés
Connecteurs	Catalogue natifs (gitea, github, web, google, ms365) + connecteurs personnels (custom, discord, telegram, mcp) ; client MCP complet (JSON-RPC, tools/list, tools/call, cache en base) ; OAuth Google/MS365 lecture seule (Drive/Gmail/Calendar ; Graph Files/Mail/Calendars), refresh automatique, secrets Fernet	🟡 Partiel — lecture seule, pas de Slack
Recherche d'entreprise	Recherche hybride FTS5 + sémantique (RRF), Ask AI avec citations, filtrage ACL avant prompt (§17 Flowdeck) ; palette avec onglet « Réponses IA »	✅ Présent
Gouvernance de l'agent	agent_policies (liste blanche d'outils, max_steps ≤ 50, require_approval), agent_approvals (l'écriture suspend l'action + webhook), gate éditeur+ pour les outils d'écriture, admin/owner + HTTP 428 pour les outils destructifs	✅ Présent
Automatisations événementielles	Moteur d'automations : triggers event/cron/button, fire_event() alimenté par page.*, collection.*, form.submitted, meeting.summarized… ; action agent_trigger qui lance un agent dans sa propre conversation journalisée	✅ Présent — c'est le bus qui manque aux déclencheurs d'agents
Workers (code sandboxé)	Workers Python : cron, partage, fork ; sandbox AST, pas de réseau ni de filesystem, timeout 30 s, budget journalier	✅ Présent — réutilisable pour l'espace fichiers (§15)
Fournisseurs LLM	Client unifié 23 fournisseurs + offline déterministe, précédence de config en 4 niveaux, clés par utilisateur	✅ Présent
Calendrier & réunions	Sync calendrier bidirectionnelle Google/CalDAV ; AI Meeting Notes complètes avec événement meeting.summarized	✅ Présent
Notifications	Service de notifications complet (mentions, commentaires, assignations…), préférences, Inbox de la sidebar	✅ Présent — mais aucun outil agent dessus
Library	Page Library à onglets (Recents, Meeting Notes, Favorites, Shared, Private, Published…)	🟡 Partiel — pas d'onglet Skills
Import de fichiers	Pipeline d'import unifié (PDF, DOCX, CSV/XLSX, ICS, URL…) avec jobs suivis et déduplication	✅ Présent — réutilisable pour l'ingestion agent

4.2 Les écarts, un par un

E1 — Le modèle de Skill. Flowdeck : un skill est un enregistrement dédié (agent_skills), avec un prompt et des outils autorisés. Notion : un skill est une page, éventuellement ligne d'une base de skills (collection ordinaire marquée), avec Description et Files comme propriétés, le partage et l'historique des pages, et la possibilité de marquer n'importe quelle page comme skill. Écart de modèle de données et d'expérience : impossible, dans le modèle actuel, de transformer un playbook existant en skill, de le co-éditer comme un document, ou de le ranger dans une base d'équipe avec Owner/Status. → §10.3, §13.1. C'est l'écart n° 1 : tous les autres usages de skills en découlent.

E2 — L'usage automatique des skills. Flowdeck : le skill est choisi et appliqué par l'utilisateur (galerie, menus). Non décrit : un appariement automatique description ↔ demande, un interrupteur Use automatically, la nomination du skill dans la réponse et sa présence dans les sources. → §13.2, §13.3.

E3 — Accès ≠ activation pour les skills. Non décrits : onglet Discover, Enable for me, activation automatique des skills créés, désactivation pour soi seul. La galerie actuelle mélange découverte, installation et activation. → §13.5.

E4 — L'export SKILL.md vers les agents locaux. Le format portable flowdeck-skill v1 est un JSON rejouable dans Flowdeck. Notion exporte le format SKILL.md lu par les agents locaux externes, fichiers de support inclus, avec badge de désynchronisation. → §13.6 (le format v1 reste, en interne ; v2 = double sérialisation).

E5 — Les déclencheurs des Custom Agents. Flowdeck : agent_triggers = horaire seulement (le scheduler existe). Notion : horaire + événements du workspace + événements de messagerie + mention. Flowdeck possède pourtant le bus (fire_event() des automatisations, qui sait déjà lancer un agent via l'action agent_trigger) : il manque la subscription directe d'un agent à un événement, avec filtres, sans passer par une automation intermédiaire visible. → §12.6.

E6 — L'accès explicite par agent (Tools and access). Flowdeck : scope_json borne les outils, et l'agent personnalisé agit dans le régime de son appelant (déclencheur externe ou propriétaire). Non décrit : une liste blanche de ressources (pages/collections/canaux précis, « tout ce qui est partagé au workspace », rien) évaluée à chaque lecture d'outil pour les runs autonomes, distincte des ACL de l'utilisateur qui lance un run manuel. → §16.1 (les deux régimes coexistent selon le type de run, §12.1).

E7 — Délégation entre agents. Non décrit : un outil « appeler un autre agent » avec passage de contexte, plafond de profondeur, et comptabilité propre. → §12.7.

E8 — Actions externes en écriture. Manquent : connecteur Slack (absent du catalogue natifs décrit) ; outils Inbox (lire/regrouper/archiver les notifications) ; outils calendrier agent (chercher un créneau multi-participants, grilles de suggestions, réserver) — la sync calendrier existe, pas l'action d'agent ; passage de Gmail de la lecture seule à rédiger/envoyer/archiver/étiqueter avec confirmation (le régime d'approbation agent_approvals fournit déjà le mécanisme de confirmation). Discord/Telegram/Teams existent comme connecteurs personnels : leurs actions d'envoi doivent être exposées comme outils au même titre. → §14.

E9 — Espace fichiers / « computer ». Non décrit pour l'agent : ingestion d'un fichier dans la conversation (le trombone), analyse tabulée, exécution de code simple sur les données, et production de fichiers téléchargeables (XLSX, PDF, DOCX, PPTX) joints à la réponse. Les briques existent (importers, Workers sandboxés, export PDF/XLSX) mais ne sont pas assemblées en outil d'agent. → §15.

E10 — Résultats structurés dans le chat. Non décrit : tableau interactif de résultats dans la conversation (l'agent affiche aujourd'hui du texte et des actions). Les vues de collections Flowdeck fournissent le composant d'affichage à réutiliser en lecture dans le panneau. → §7.2.

E11 — Instructions comme page. Flowdeck : agents.instructions (texte système) et mémoire par conversation. Non décrit : pour l'Agent personnel, une page d'instructions par utilisateur (créée/choisie/commutable, privée par défaut), résolue à chaque run ; pour les Custom Agents, des instructions adossées à une page versionnée (l'historique de configuration demandé par Notion suppose une source versionnable — les page_versions Flowdeck la fournissent si les instructions vivent dans une page). → §10.2, §12.3.

E12 — Partage, onglets et cycle de vie des Custom Agents. Partiels ou non décrits : les trois niveaux de partage d'agent (la gouvernance actuelle parle de politiques de workspace, pas de grants par agent) ; la page agent en trois onglets Chat / Activity / Settings (le panneau existe, la page dédiée non) ; Insights et export CSV ; l'embed du chat d'un agent dans une page (nouveau type de bloc) ; la mention @agent dans pages/propriétés/commentaires ; la duplication avec règles de reprise ; l'historique de versions de configuration avec restauration. → §7.3, §10.5, §11.

E13 — Modèles gouvernés et usage mesuré. Flowdeck configure les modèles (23 fournisseurs, clés par utilisateur, précédence) mais ne décrit ni sélecteur Auto explicite par run avec routage par tâche, ni modèles autorisés par surface, ni activation admin des premium, ni aucun compteur : pas d'allocation d'usage, pas de crédits, pas de limite par membre, pas de coût par run dans l'activité. → §10.6, §12.2, §16.5.

E14 — Création d'agent assistée par l'IA. Non décrit : le mode « décrire le travail → brouillon d'instructions/déclencheurs/accès à relire » (un méta-run de l'Agent personnel avec un skill système de génération d'agent). La galerie de modèles d'agents, elle, peut s'appuyer sur le mécanisme de presets déjà utilisé pour les skills. → §7.3, §20 Phase 3.

4.3 Ce que Flowdeck a et que Notion ne met pas en avant — à conserver

• Le rollback par action (undo_snapshot_json) : la réversibilité chez Notion est surtout configurationnelle (historique de versions) ; Flowdeck peut annuler une action exécutée. À étendre aux runs autonomes et à afficher dans Activity.
• Le mode LLM offline déterministe : les runs, le routeur de skills et les tests doivent fonctionner sans fournisseur externe — c'est un atout de testabilité qu'aucune phase ne doit casser (§17).
• Les Workers sandboxés et les automatisations à steps : plutôt que d'inventer un « moteur de workflows d'agents », les Custom Agents restent des consommateurs du bus d'événements et, pour le code, des Workers.
• La gouvernance existante (agent_policies, agent_approvals, 428 sur le destructif) est déjà au niveau du modèle Notion (confirmation sur les écritures sensibles) : on l'étend, on ne la remplace pas.

---

5. Principes directeurs pour Flowdeck

#	Principe	Conséquence concrète
P1	Un seul moteur, quatre objets	Instructions, Skill, Agent personnel et Custom Agent sont des données et des régimes d'exécution du même agent_engine.py ; aucun second moteur « Custom »
P2	Le skill est une page, la base de skills est une collection	On réutilise éditeur, ACL, historique, recherche, Library ; agent_skills devient la table d'indexation/exécution, pas la source de vérité du contenu
P3	Deux régimes de permissions, choisis par le type de run	Run interactif = droits de l'utilisateur ; run autonome = intersection (droits du propriétaire de l'agent) ∩ (liste blanche de l'agent) ∩ (politique du workspace) — §16.1
P4	Le registre d'outils est la politique	Ce qui n'a pas d'outil n'existe pas pour l'agent ; tout nouvel outil naît avec sa classe (lecture / écriture / destructif / externe) et son régime d'approbation
P5	Tout run est relisible et compté	Étapes, outils, sources, skills utilisés, modèle, tokens et coût sont journalisés par run, affichés dans Activity, exportables
P6	Aucune écriture externe silencieuse	Envoyer, poster, archiver en masse, réserver : confirmation préalable (ou politique d'approbation pré-accordée par agent, révocable)
P7	Respecter les invariants du monolithe	SQLite + JSON documentaire, schedulers asyncio existants, SSE déjà en place, fragments htmx + Alpine CSP, aucun bundler, aucune file externe
P8	Offline d'abord pour les tests	Chaque nouvelle capacité (routage de skill, déclencheur, délégation) a un comportement déterministe en mode LLM offline

---

6. Vue d'ensemble du système (C4)

6.1 Contexte

graph TD
    U[Utilisateur Flowdeck] -->|chat, éditeur, Library| FD[Flowdeck - Agents & Skills]
    ADMIN[Admin workspace] -->|modèles, crédits, politiques| FD
    FD -->|chat-completions, protocole compatible| LLM[23 fournisseurs LLM + offline]
    FD -->|OAuth lecture puis écriture gardée| GMS[Google / Microsoft 365]
    FD -->|API| SLACK[Slack - nouveau connecteur]
    FD -->|API existantes| MSG[Discord / Telegram / Teams]
    FD -->|client MCP JSON-RPC| MCP[Serveurs MCP externes]
    FD -->|issues, sync| FORGE[Gitea / GitHub]
    LOCAL[Agents locaux: Claude Code, Codex, Cursor...] -->|lit SKILL.md téléchargé| FD
    FD -->|webhooks agent.*| OUT[Systèmes externes abonnés]

6.2 Conteneurs (dans le monolithe — aucun nouveau déployable)

graph TD
    subgraph Flowdeck - processus uvicorn unique
        PANEL[Panneau Agent + page Agent<br/>SSR Jinja2 / htmx / Alpine]
        EDIT[Éditeur de blocs<br/>menus Skills]
        LIB[Library<br/>onglets Skills / Discover]
        ENG[AgentEngine ReAct<br/>évolution de l'existant]
        CTX[Context Builder v2<br/>sources, instructions-page, mémoire]
        ROUTER[Skill Router<br/>appariement description]
        SKILLRUN[Skill Runner<br/>exécution chat / éditeur / agent]
        REG[Tool Registry<br/>26 outils + nouveaux + MCP dynamiques]
        TRIG[Trigger Dispatcher<br/>branche agent_triggers sur fire_event]
        DELEG[Délégation<br/>agent vers agent]
        FILES[File Workspace<br/>ingestion + production, sandbox Workers]
        METER[Usage Meter<br/>allocation, crédits, limites]
        POL[Policies + Approvals<br/>existant étendu]
        SCHED[Schedulers existants<br/>agent_scheduler 60 s]
    end
    PANEL --> ENG
    EDIT --> SKILLRUN
    LIB --> SKILLRUN
    ENG --> CTX
    ENG --> ROUTER
    ROUTER --> SKILLRUN
    ENG --> REG
    ENG --> DELEG
    ENG --> FILES
    TRIG --> ENG
    SCHED --> TRIG
    REG --> POL
    ENG --> METER
    REG --> DB[(SQLite WAL<br/>tables §10)]

6.3 Règle de placement

Tout ce qui précède vit dans le processus existant : les nouveaux services rejoignent app/services/ (skill_router.py, skill_runner.py, agent_triggers_dispatch.py, agent_files.py, usage_meter.py), les nouvelles routes rejoignent app/routers/agent.py et app/routers/api_v2_agent.py, et aucun scheduler nouveau n'est créé : les déclencheurs horaires restent sur agent_scheduler, les déclencheurs événementiels sont synchrones avec fire_event().

---

7. Architecture front-end web

Contraintes héritées de l'architecture Flowdeck : SSR Jinja2, fragments htmx, Alpine en build CSP (aucun eval), JavaScript vendorisé sans bundler, navigation partielle maison. Tout composant ci-dessous est un fragment + un module static/js/ dans les conventions existantes (agent_panel_*.js, library.js, page_editor_scripts.js).

7.1 Le panneau de l'Agent personnel

Le panneau actuel (agent_panel.html) évolue, sans changer de place dans le shell :

Composant	Évolution
agent-chat-header	Ajoute : sélecteur de mode d'affichage (barre latérale / flottant, persisté par utilisateur), bouton épingler la conversation, titre de conversation généré automatiquement d'après le premier échange (même mécanisme de titrage que les notes de réunion : un titre de travail, modifiable)
agent-suggested-actions	Rangée d'actions suggérées dépendantes de la page courante et des blocs sélectionnés (extraire les actions, raccourcir, traduire la sélection…) ; chaque suggestion est un amorçage de prompt, pas un run caché
agent-composer	Zone de saisie avec : @ (pages, personnes, agents, dossiers — réutilise les jetons du Context Builder), / (menu des skills, §7.4), 📎 (téléversement pour la conversation, §15), sélecteur All sources (cases : workspace, chaque connecteur, chaque serveur MCP — l'état est persisté par conversation)
agent-model-picker	Sélecteur de modèle : Auto en tête, puis les modèles autorisés pour l'Agent personnel ; les modèles premium portent leur badge de coût ; un modèle web-seulement est signalé comme tel (« ce modèle ne verra pas ton workspace »)
agent-run-stream	Le flux SSE existant gagne l'affichage des étapes nommées (comprendre, chercher, lire telle source, appliquer tel skill, appeler tel outil) — même exigence de transparence que les étapes Thinking des Meeting Notes
agent-result-table	Nouveau : quand un outil renvoie des lignes structurées, le panneau rend un tableau interactif en lecture (tri, ouvrir la ligne source) en réutilisant le rendu des vues de collection en mode embarqué ; le tableau est un artefact de conversation, pas une collection
agent-file-cards	Nouveau : fichiers produits par le run (§15) rendus en cartes téléchargeables dans le message ; fichiers déposés rendus en pièces jointes de conversation
agent-sources-panel	Panneau latéral des sources d'un run : pages lues, résultats de recherche, connecteurs interrogés, skills utilisés (nom + lien vers la page du skill) — invariant I5
chat-history	Liste des conversations dans l'onglet Chat de la sidebar : épinglées en tête, recherche par titre et contenu, nommage automatique

7.2 L'éditeur : les skills au point d'usage

Les points d'entrée existent déjà partiellement (menu contextuel de bloc → Skills ›, toolbar de sélection → Skills) ; on les complète et on les unifie :

1. Menu de sélection de texte : section Skills — skills activés de l'utilisateur ayant editor_menu = 1 d'abord, puis les quatre skills intégrés (améliorer, corriger, expliquer, reformater) ; entrée Manage Skills qui ouvre la Library filtrée.
2. Menu slash : /skill et /<nom> à côté d'un contenu ; la ligne vide n'offre pas de skills (un skill a besoin de matière) — le menu filtre sur les types de blocs éligibles (§13.4).
3. Menu de bloc (poignée) → Skills : appliqué au bloc et à son contenu imbriqué.
4. Résultat : les skills de transformation proposent un aperçu diff (accepter / refuser / réessayer) plutôt qu'un remplacement silencieux ; les skills de génération insèrent leur sortie sous le bloc source. Le run est journalisé comme un run d'agent ordinaire, source = editor.

7.3 La page d'un Custom Agent

Nouvelle page SSR /agents/{id} (section Agents de la sidebar, déjà présente), en trois onglets — invariant I10 :

Onglet	Contenu
Chat	Le panneau de conversation de cet agent, réutilisant les composants du §7.1, avec l'identité de l'agent (et non celle de l'Agent personnel)
Activity	Table des runs : déclencheur (icône + libellé), statut, durée, modèle, étapes dépliables (raisonnement résumé, outils, sources, skills), erreurs en clair, coût en crédits, boutons Re-run (avec la même entrée) et, par action, Undo quand un snapshot existe. Filtres : statut, déclencheur, période
Settings	Formulaire en sections : Instructions (éditeur de page embarqué — les instructions sont une page, §10.2), Triggers (liste de cartes typées avec filtres, aperçu du prochain horaire), Tools and access (ressources accordées par type, interrupteur web, connecteurs et canaux, skills accordés, agents délégables), Model (sélecteur gouverné), Advanced (politique d'approbation, plafond d'itérations, budget de crédits par run et par mois)
(transverse)	Barre de partage (trois niveaux, §16.2), menu ••• : Duplicate, Embed in a page (copie le lien avec marqueur d'intégration), Version history (liste + restauration), Insights

Création (/agents/new) : trois cartes — Créer avec l'IA (un champ « décris le travail », puis un écran de relecture du brouillon généré : instructions, déclencheurs proposés, accès proposés — rien n'est activé sans validation), Depuis un modèle (galerie), Page blanche.

Embed : nouveau type de bloc agent_embed dans l'éditeur — colle du lien d'un agent, il rend le chat de cet agent dans la page ; le bloc affiche un état explicite « tu n'as pas accès à cet agent » pour les lecteurs non partagés, et ne donne au modèle aucune lecture implicite de la page hôte.

7.4 La Library : onglets Skills et Discover

La Library (§15.2 de l'architecture Flowdeck) gagne un onglet Skills à deux sous-vues :

• Skills : table des skills activés ou créés par l'utilisateur — colonnes Nom (lien page), Base, Description (tronquée), Use automatically (interrupteur), Menu éditeur (interrupteur), Propriétaire, Dernière utilisation ; actions : New skill, ouvrir, désactiver pour soi.
• Discover : skills partagés accessibles mais non activés (par l'équipe, l'admin, les presets) — bouton Enable for me par ligne, confirmation immédiate.
• Recherche et filtres : par nom/description, base, propriétaire, étiquettes (la propriété Tags des bases de skills).

7.5 La page d'un skill et la base de skills

• Page skill : la page ordinaire + une bannière de skill en tête (nom, base, état activé pour moi, interrupteurs Use automatically / Add to text editor menu, bouton Download for local agents, badge orange « copie locale périmée » quand l'utilisateur a téléchargé puis que la page a changé). Aucun nouvel éditeur : on écrit un skill comme on écrit une page.
• Base de skills : une collection ordinaire dont le gabarit affiche un badge « Skills » ; la conversion d'une collection existante passe par un dialogue de correspondance Description / Files / Tags (créer ou mapper), avec case « activer les pages existantes comme skills pour moi ». La création directe propose Database → Skills dans les gabarits de bases.
• Marquer une page : entrée ••• → Use as a skill (case) sur toute page ; décocher la rend à l'état de page ordinaire.

7.6 Réglages d'administration (Settings → Notion AI → équivalent Flowdeck)

Dans la page de réglages existante, une section IA & Agents : modèles autorisés (deux listes : Agent personnel / Custom Agents), activation des modèles premium, modèle par défaut, limites de crédits par membre et par agent, allocation d'usage et état courant, qui peut créer des Custom Agents (tout le monde / admins / liste), accès web par défaut des agents, tableau d'usage (par membre, par agent, par modèle ; export CSV).

---

7A. Maquettes ASCII — panneau Agent, page Skill, réglages d'un Custom Agent

Section dans l'esprit de la section 3B du document Meetings : un développeur doit pouvoir implémenter la disposition à partir de ces seuls dessins. Les captures Notion n'ayant pas été fournies pour ces écrans, ces maquettes sont des propositions Flowdeck fidèles aux descriptions fonctionnelles de la section 3 — contrairement au document Meetings, elles ne reproduisent pas des captures réelles.

7A.1 Panneau de l'Agent personnel (mode barre latérale)

┌─ Agent ──────────────────────────────────────────────── [📌] [⤢ mode] [✕] ┐
│  (•‿•) Flow  ·  Modèle: [ Auto                       ▾ ]                   │
│ ───────────────────────────────────────────────────────────────────────── │
│  Actions suggérées pour cette page :                                      │
│  [ Extraire les actions ] [ Raccourcir ] [ Traduire la sélection ]        │
│                                                                           │
│  Vous : /Synthèse d'entretien — utilise @Notes appel client               │
│                                                                           │
│  Flow : ✓ Lecture de la page « Notes appel client »                       │
│         ✓ Skill appliqué : Synthèse d'entretien          [voir sources]  │
│         ✓ Recherche dans la base CRM                                      │
│         ┌─ Résultat ────────────────────────────────────────────────┐     │
│         │ (tableau interactif : thèmes · sentiment · citations)     │     │
│         └───────────────────────────────────────────────────────────┘     │
│         📎 synthese-entretien.xlsx   [Télécharger]                        │
│                                            [👍] [👎] [↩ Annuler le run]  │
│ ───────────────────────────────────────────────────────────────────────── │
│  Sources : [ Toutes les sources ▾ ]   (workspace, Gitea, Gmail, MCP…)     │
│  ┌───────────────────────────────────────────────────────────┐ [📎] [↑]  │
│  │ Demande…  (@ page/personne/agent, / skill)                │           │
│  └───────────────────────────────────────────────────────────┘           │
└───────────────────────────────────────────────────────────────────────────┘

Zones : ① en-tête (identité, modèle, épinglage, mode d'affichage) · ② suggestions contextuelles · ③ fil du run (étapes cochées, skill nommé, sources ouvrables) · ④ artefacts (tableau, fichiers) · ⑤ réactions et annulation · ⑥ compositeur (sources, mentions, skills, pièce jointe).

7A.2 Page d'un skill

╭─ Bannière Skill ─────────────────────────────────────────────────────────╮
│ ✦ Skill · Base : Skills Équipe   Activé pour moi : [ oui ]               │
│   Utilisation automatique : (•)   Menu de l'éditeur : (•)                │
│   [ Télécharger pour les agents locaux ]   ⚠ copie locale périmée        │
├──────────────────────────────────────────────────────────────────────────┤
│  Synthèse d'entretien                                                    │
│  Description : Transforme des notes d'entretien client en synthèse       │
│  structurée (thèmes, verbatims, risques, prochaines étapes). À utiliser   │
│  quand l'utilisateur fournit des notes d'appel ou d'interview.           │
│  Files : [exemple-synthese.pdf] [grille-themes.xlsx]                     │
│ ──────────────────────────────────────────────────────────────────────── │
│  Objectif …  Entrées …  Règles …  Exemples …  Sortie attendue …           │
│  (corps de page ordinaire, éditable, versionné, partageable)             │
╰──────────────────────────────────────────────────────────────────────────╯

7A.3 Page d'un Custom Agent — onglet Settings

┌─ Agent : Triage Tickets ───── [Partager] [•••] ──────────────────────────┐
│  ( Chat ) ( Activity ) ( Settings )                                      │
│ ─────────────────────────────────────────────────────────────────────────│
│  Instructions   [ page embarquée : « Triage Tickets — Instructions » ]    │
│  Triggers       [ + Ajouter ]                                            │
│    • Horaire — tous les jours 9 h 00 (Europe/Paris) · prochain : demain  │
│    • Flowdeck — ligne ajoutée à « Tickets » si Statut = « À trier »      │
│    • Discord — mention de l'agent dans #support                          │
│  Tools and access                                                        │
│    Pages/bases : [ Tickets (éditer) ] [ Guide de triage (lire) ]         │
│    Skills      : [ Classification de ticket ]                            │
│    Délégation  : [ Agent Réponse type ]                                  │
│    Web         : ( ) désactivé                                           │
│  Modèle         [ Auto ▾ ]    Budget : 200 crédits/mois · par run : 20   │
│  Approbation    Écritures externes : [ demander à chaque fois ▾ ]        │
└──────────────────────────────────────────────────────────────────────────┘

---

8. Architecture back-end

8.1 Services (nouveaux et évolués)

Service	Statut	Responsabilité
app/services/agent_engine.py	Évolue	Boucle ReAct : reçoit un contexte de run typé (§12.1), résout modèle (§12.2), instructions (§12.3), skills (§13.3) ; émet les événements SSE enrichis ; écrit le journal de run complet (§10.5)
app/services/context_builder.py	Évolue → v2	Ajoute : page courante + blocs sélectionnés (déjà en partie), sélecteur All sources, page(s) d'instructions, skills résolus, pièces jointes de conversation
app/services/skill_router.py	Nouveau	Appariement demande ↔ skills activés : recherche hybride sur les descriptions indexées, seuil, départage, repli offline déterministe (§13.2)
app/services/skill_runner.py	Nouveau	Charge un skill (page + fichiers), construit le prompt d'exécution, exécute selon la surface (chat / éditeur / agent), rend la sortie structurée, journalise skill_runs
app/services/skill_gallery.py	Évolue	La galerie devient des presets de pages : installer un preset = créer la page-skill (dans la base privée de l'utilisateur) plutôt qu'un enregistrement autonome ; migration §20
app/services/agent_triggers_dispatch.py	Nouveau	S'abonne à fire_event() et au scheduler : fait correspondre événements et agent_triggers (filtres), crée les runs autonomes, gère déduplication et fenêtres anti-boucle
app/services/agent_delegation.py	Nouveau	Exécute l'outil delegate_to_agent : run enfant avec son propre contexte de permissions, plafond de profondeur, agrégation des coûts
app/services/agent_files.py	Nouveau	Espace fichiers par conversation/run : ingestion, analyse via les importers, exécution de code dans la sandbox Workers, production de fichiers (§15)
app/services/usage_meter.py	Nouveau	Comptabilise tokens et coût par run, applique allocation/crédits/limites, expose les tableaux d'usage (§10.6)
app/services/connectors.py + oauth_connectors.py	Évoluent	Ajout du connecteur Slack ; passage Google/MS365 en écriture gardée (scopes supplémentaires, confirmation) ; exposition uniforme des actions comme outils (§14)
app/services/agent_policies.py	Évolue	Politiques par surface (modèles autorisés), politique d'approbation des écritures externes par agent, restriction de création d'agents

8.2 Routeurs

Routeur	Évolution
app/routers/agent.py (/api/agent/*)	Nouvelles routes : sources de conversation, épinglage, skills du menu /, runs d'éditeur, fichiers de conversation, page agent (SSR), duplication, versions, insights
app/routers/api_v2_agent.py (/api/v2/agents/*)	Parité Bearer : déclencher un Custom Agent, lire l'activité ; POST /api/v2/agents/{id}/duplicate
app/routers/api_v2/ skills (/api/v2/skills/*)	La ressource skill devient adossée à la page : lecture du SKILL.md sérialisé, téléchargement du bundle, import conforme
app/routers/library.py	Onglet Skills + Discover (activation)
app/routers/admin.py / réglages	Section IA & Agents du §7.6, tableaux d'usage

8.3 Contraintes de mise en œuvre héritées

• Accès SQLite hors event loop pour les chemins chauds (audit A21) : les runs d'agents sont déjà le chemin le plus long — tout nouvel appel synchrone (lecture de page de skill, indexation de description) passe par les mêmes helpers que l'existant.
• Les runs autonomes tournent dans le processus unique : le dispatcher d'événements doit être borné (file par agent, concurrence plafonnée, timeout par run déjà prévu au moteur) — §17, §18.
• Aucun secret nouveau en clair : tokens de connecteurs chiffrés Fernet comme l'existant.

---

9. Flux et séquences clés

9.1 Run de chat avec choix automatique d'un skill (UC-03)

sequenceDiagram
    participant U as Utilisateur
    participant P as Panneau Agent
    participant E as AgentEngine
    participant R as Skill Router
    participant C as Context Builder v2
    participant T as Tool Registry
    participant M as Usage Meter
    U->>P: demande (texte, @mentions, sources)
    P->>E: POST /api/agent/conversations/{id}/run (SSE)
    E->>C: contexte (page courante, blocs sélectionnés, instructions-page, mémoire)
    E->>R: apparier la demande aux skills activés (descriptions)
    R-->>E: skill retenu + score (ou aucun)
    Note over E: le skill chargé devient une consigne de run,<br/>son nom sera affiché dans la réponse (I5)
    loop ReAct (≤ plafond politique)
        E->>T: intention d'outil
        T->>T: check_tool (politique) + assert_can (régime du run)
        T-->>E: résultat (+ snapshot d'annulation si écriture)
    end
    E->>M: comptabiliser tokens / crédits du run
    E-->>P: événements SSE: step, skill_used, action, final
    P-->>U: réponse + sources (skill nommé) + artefacts

9.2 Skill lancé depuis l'éditeur (UC-04)

Sélection / bloc → menu Skills → POST /api/agent/skills/{id}/run-editor
  → Skill Runner charge la page du skill + ses fichiers
  → le contenu éligible (sélection, ou bloc + imbriqués) devient l'entrée datée du run
  → sortie : transformation → aperçu diff (accepter / refuser / réessayer)
             génération    → blocs insérés sous la source
  → journal : agent_runs (surface=editor) + skill_runs (invocation=manual)

9.3 Custom Agent déclenché par un événement (UC-06)

sequenceDiagram
    participant S as Service métier (collections)
    participant B as Bus fire_event()
    participant D as Trigger Dispatcher
    participant E as AgentEngine
    participant A as Approbations
    S->>B: collection.row_added (ligne, base, valeurs)
    B->>D: événement + payload
    D->>D: matcher agent_triggers (type, ressource, filtres) ; dédupliquer
    D->>E: créer run autonome (agent, conversation journalisée dédiée)
    Note over E: régime de permissions = liste blanche de l'agent (§16.1)
    E->>E: boucle ReAct bornée (itérations, budget crédits)
    alt écriture externe couverte par la politique
        E->>A: demande d'approbation (run suspendu, webhook émis)
        A-->>E: approuvé / rejeté
    end
    E-->>D: run terminé (statut, coût, actions) → Activity + webhook agent.run.*

9.4 Délégation entre agents (UC-07)

Run parent → outil delegate_to_agent(agent_id, tâche, contexte)
  → contrôles : agent cible dans la liste de délégation du parent,
    profondeur < 3, budget restant suffisant, cible active
  → run enfant : instructions, accès et modèle PROPRES à la cible,
    conversation fille rattachée (parent_run_id), coût compté au parent ET à la cible
  → le résultat structuré de l'enfant revient comme résultat d'outil du parent
  → échec de l'enfant = résultat d'outil « échec + motif », jamais d'exception silencieuse :
    le parent décide (réessayer, contourner, abandonner) dans sa boucle

9.5 Téléchargement d'un skill vers un agent local (UC-10)

Page du skill → Download for local agents → choix des cibles
  → sérialisation SKILL.md (frontmatter : name, description ; corps : la page en Markdown)
    + fichiers de la propriété Files marqués partageables
  → écriture dans le répertoire de skills de chaque agent local choisi
    (via l'extension / un utilitaire compagnon — voir question ouverte Q4, §23)
  → skill_local_downloads : (user, skill, cible, empreinte de version de la page)
  → toute modification ultérieure de la page rend l'empreinte caduque → badge orange

9.6 Ingestion d'un fichier et production d'un livrable (UC-08)

📎 dans le chat → upload vers l'espace fichiers de la conversation (quotas §15)
  → outil read_uploaded_file : extraction par les importers Flowdeck (PDF, CSV, XLSX…)
  → outil run_code_on_data (sandbox Workers) pour calculer/transformer
  → outil create_collection_from_file si l'utilisateur demande une base structurée
  → outil produce_file (xlsx/pdf/docx/pptx) → carte téléchargeable dans le message
  → tous les artefacts sont rattachés au run (agent_run_files) et comptés (stockage, coût)

---

10. Modèle de données

Conventions Flowdeck respectées : SQLite, SQL brut sans ORM, structures riches en colonnes *_json, migrations versionnées (@register, une migration = une transaction) — la version courante est 38, les migrations proposées commencent donc à 39. Aucune table existante n'est renommée ; les évolutions sont additives, avec deux exceptions assumées et documentées (§10.3 : le rôle d'agent_skills change ; §10.2 : agents.instructions devient un cache).

10.1 Vue d'ensemble des changements

Migration	Objet	Changement
39	agents	kind (personal réservé / custom), instruction_page_id, web_access, credit_limit_monthly, delegation_depth_max
39	agent_personal_settings	Nouvelle : personnalisation de l'Agent personnel par utilisateur
39	agent_permissions	Nouvelle : grants par agent (3 niveaux), user XOR groupe comme les ACL existantes
39	agent_versions	Nouvelle : snapshots de configuration restaurables
40	agent_runs	Nouvelle : le run comme objet de première classe (Activity, coûts, déclencheurs) ; agent_actions.run_id ajouté
40	agent_triggers	Extension événementielle : trigger_kind, event_name, resource_type/id, filter_json
41	agent_skills	Refonte : adossée à une page (page_id), description, fichiers, caractère intégré
41	collections	is_skills_db + correspondance des propriétés de skill dans schema_json
41	user_skill_enablements, skill_runs, skill_local_downloads	Nouvelles : activation par utilisateur, journal d'usage, copies locales
42	workspace_ai_settings, ai_usage_ledger	Nouvelles : gouvernance des modèles et comptabilité d'usage
42	agent_conversations	pinned, title_auto, sources_json, files_enabled
43	agent_run_files	Nouvelle : artefacts de l'espace fichiers (entrants et produits)

10.2 Agents : personnalisation, instructions-page, partage, versions

-- Migration 39
ALTER TABLE agents ADD COLUMN kind TEXT NOT NULL DEFAULT 'custom';
    -- 'custom' pour tous les agents existants ; l'Agent personnel n'est PAS une ligne
    -- d'agents : c'est le moteur + les réglages personnels ci-dessous (un par utilisateur).
ALTER TABLE agents ADD COLUMN instruction_page_id INTEGER REFERENCES pages(id);
    -- Page source des instructions du Custom Agent. agents.instructions (existant)
    -- devient le CACHE texte rendu depuis cette page à chaque sauvegarde de la page ;
    -- si instruction_page_id est NULL, le texte libre existant fait foi (compat ascendante).
ALTER TABLE agents ADD COLUMN web_access INTEGER NOT NULL DEFAULT 0;
ALTER TABLE agents ADD COLUMN credit_limit_monthly INTEGER;   -- NULL = pas de limite propre
ALTER TABLE agents ADD COLUMN delegation_json TEXT DEFAULT '[]';
    -- IDs des agents que celui-ci peut appeler (Tools and access → Délégation)

CREATE TABLE agent_personal_settings (
    user_id              INTEGER PRIMARY KEY REFERENCES users(id),
    display_name         TEXT,                    -- nom donné à SON Agent personnel
    avatar_json          TEXT DEFAULT '{}',       -- accessoires / apparence
    instruction_page_ids TEXT DEFAULT '[]',       -- pages d'instructions maintenues
    active_instruction_page_id INTEGER REFERENCES pages(id),
    chat_mode            TEXT DEFAULT 'sidebar',  -- 'sidebar' | 'floating'
    default_model        TEXT                     -- NULL = Auto
);

CREATE TABLE agent_permissions (                  -- même patron que page_permissions
    id         INTEGER PRIMARY KEY,
    agent_id   INTEGER NOT NULL REFERENCES agents(id) ON DELETE CASCADE,
    user_id    INTEGER REFERENCES users(id),
    group_id   INTEGER REFERENCES user_groups(id),
    level      TEXT NOT NULL CHECK (level IN ('full','edit','interact')),
    created_by INTEGER REFERENCES users(id),
    created_at TEXT NOT NULL,
    CHECK ((user_id IS NULL) <> (group_id IS NULL))
);

CREATE TABLE agent_versions (
    id         INTEGER PRIMARY KEY,
    agent_id   INTEGER NOT NULL REFERENCES agents(id) ON DELETE CASCADE,
    snapshot_json TEXT NOT NULL,   -- instructions (texte), triggers, accès, modèle, politiques
    created_by INTEGER REFERENCES users(id),
    created_at TEXT NOT NULL,
    note       TEXT
);
-- Écrit à chaque sauvegarde des Settings ; la restauration réécrit la configuration
-- et journalise dans permission_audit_log / api_audit_log comme l'existant.

Règle de résolution des instructions (détaillée au §12.3) : page active > page liée de l'agent > texte libre > défaut système. Pour l'Agent personnel, la page par défaut (« Mon Flowdeck AI ») est créée à la première personnalisation : une page privée ordinaire, donc éditable, versionnée et cherchable comme les autres.

10.3 Skills : la page devient la source de vérité

-- Migration 41
ALTER TABLE collections ADD COLUMN is_skills_db INTEGER NOT NULL DEFAULT 0;
    -- La correspondance Description/Files/Tags vit dans collections.schema_json :
    --   {"skill_properties": {"description": "Description",
    --                          "files": "Files", "tags": "Tags"}}

CREATE TABLE agent_skills_v2 (   -- remplace agent_skills par recréation + copie (§20, Phase 1)
    id            INTEGER PRIMARY KEY,
    page_id       INTEGER NOT NULL UNIQUE REFERENCES pages(id) ON DELETE CASCADE,
    collection_id INTEGER REFERENCES collections(id),
        -- NOT NULL quand le skill est une ligne d'une base de skills (sa page-ombre),
        -- NULL pour une page autonome marquée « Use as a skill »
    name_cached   TEXT NOT NULL,        -- titre de la page, recopié à la sauvegarde
    description   TEXT DEFAULT '',      -- propriété Description (base) ou bloc méta (page autonome)
    files_json    TEXT DEFAULT '[]',    -- fichiers de support : {name, path, mime, shareable}
    tools_json    TEXT DEFAULT '[]',    -- héritage du modèle actuel : outils autorisés (peut restreindre)
    is_builtin    INTEGER NOT NULL DEFAULT 0,   -- améliorer / corriger / expliquer / reformater…
    auto_use_default    INTEGER NOT NULL DEFAULT 1,  -- interrupteur « Use automatically » du skill
    editor_menu_default INTEGER NOT NULL DEFAULT 0,  -- interrupteur « Add to text editor menu »
    owner_id      INTEGER REFERENCES users(id),
    status        TEXT DEFAULT 'ready', -- 'ready' | 'draft'
    source        TEXT DEFAULT 'page',  -- 'page' | 'legacy' | 'import'
    created_at    TEXT NOT NULL,
    updated_at    TEXT NOT NULL
);

Décisions de modélisation à noter :

1. Pas de drapeau is_skill sur pages : être un skill = avoir une ligne agent_skills. Une seule source de vérité ; marquer/démarquer une page = insérer/supprimer cette ligne, le contenu de la page ne bouge jamais.
2. Skill de base vs skill autonome : dans une base de skills, le skill est la page-ombre de la ligne (pages.collection_row_id), exactement comme les lignes de base ordinaires depuis la v6.5 de Flowdeck ; Description et Files sont alors de vraies propriétés de la ligne, relues dans property_values_json. Pour une page autonome, description et files_json vivent dans la ligne agent_skills et sont édités depuis la bannière du skill (§7.5).
3. Les presets actuels migrent : chaque preset de la galerie devient une page créée dans la base de skills privée de l'utilisateur lors de l'installation ; les skills agent_skills existants sans page reçoivent une page générée depuis leur prompt (migration de contenu, source='legacy'), afin qu'aucun skill ne survive hors du modèle page.
4. Indexation : description + titre sont indexés dans semantic_embeddings avec resource_type='skill' (le moteur d'indexation incrémental existant s'en charge) — c'est l'index que lit le Skill Router (§13.2).
5. Les fichiers d'un skill référencent le stockage d'uploads existant ; shareable décide de leur inclusion dans le bundle SKILL.md (§13.6).

10.4 Activation, usage et copies locales des skills

-- Migration 41 (suite)
CREATE TABLE user_skill_enablements (
    user_id     INTEGER NOT NULL REFERENCES users(id),
    skill_id    INTEGER NOT NULL REFERENCES agent_skills(id) ON DELETE CASCADE,
    enabled     INTEGER NOT NULL DEFAULT 1,   -- Enable for me
    auto_use    INTEGER,                      -- NULL = suit le réglage du skill ; 0/1 = choix perso
    editor_menu INTEGER,                      -- NULL = suit le réglage du skill
    created_at  TEXT NOT NULL,
    PRIMARY KEY (user_id, skill_id)
);
-- Réglages « du skill » (défauts) : colonnes auto_use_default / editor_menu_default
-- sur agent_skills, éditables par le propriétaire depuis la bannière / la Library.

CREATE TABLE skill_runs (
    id         INTEGER PRIMARY KEY,
    skill_id   INTEGER NOT NULL REFERENCES agent_skills(id),
    run_id     INTEGER NOT NULL REFERENCES agent_runs(id),
    surface    TEXT NOT NULL,      -- 'chat' | 'editor' | 'agent' | 'api'
    invocation TEXT NOT NULL,      -- 'manual' | 'auto' | 'delegated'
    created_at TEXT NOT NULL
);

CREATE TABLE skill_local_downloads (
    user_id       INTEGER NOT NULL REFERENCES users(id),
    skill_id      INTEGER NOT NULL REFERENCES agent_skills(id) ON DELETE CASCADE,
    target        TEXT NOT NULL,        -- 'claude-code' | 'codex' | 'cursor' | 'gemini' | 'grok' | 'file'
    page_version  TEXT NOT NULL,        -- empreinte (updated_at + hash du contenu) au téléchargement
    downloaded_at TEXT NOT NULL,
    PRIMARY KEY (user_id, skill_id, target)
);
-- Badge « copie périmée » = page_version <> empreinte courante de la page.

10.5 Le run comme objet : agent_runs, déclencheurs étendus

Aujourd'hui, un run est implicite (conversation + agent_actions). Activity, les coûts et les déclencheurs événementiels exigent un objet explicite :

-- Migration 40
CREATE TABLE agent_runs (
    id             INTEGER PRIMARY KEY,
    agent_id       INTEGER REFERENCES agents(id),   -- NULL = Agent personnel
    user_id        INTEGER REFERENCES users(id),    -- acteur humain (runs interactifs)
    conversation_id INTEGER REFERENCES agent_conversations(id),
    parent_run_id  INTEGER REFERENCES agent_runs(id),  -- délégation (§9.4)
    surface        TEXT NOT NULL,   -- 'chat'|'editor'|'trigger'|'schedule'|'api'|'mention'|'embed'
    trigger_id     INTEGER REFERENCES agent_triggers(id),
    trigger_payload_json TEXT DEFAULT '{}',  -- événement déclencheur (ligne, canal, message…)
    status         TEXT NOT NULL DEFAULT 'running',
        -- 'running'|'waiting_approval'|'done'|'failed'|'cancelled'|'budget_exceeded'
    provider       TEXT, model TEXT,     -- modèle RÉELLEMENT utilisé (après routage Auto)
    tokens_in      INTEGER DEFAULT 0, tokens_out INTEGER DEFAULT 0,
    credits        REAL DEFAULT 0,       -- coût calculé par usage_meter (§10.6)
    skills_json    TEXT DEFAULT '[]',    -- skills appliqués pendant le run (I5)
    error          TEXT,
    started_at     TEXT NOT NULL, finished_at TEXT
);
ALTER TABLE agent_actions ADD COLUMN run_id INTEGER REFERENCES agent_runs(id);

ALTER TABLE agent_triggers ADD COLUMN trigger_kind TEXT NOT NULL DEFAULT 'schedule';
    -- 'schedule' (existant) | 'event' | 'mention'
ALTER TABLE agent_triggers ADD COLUMN event_name TEXT;
    -- 'collection.row_added' | 'collection.property_updated' | 'collection.row_removed'
    -- | 'page.comment_added' | 'meeting.summarized'
    -- | 'message.posted' | 'message.reaction' | 'message.mention' (connecteurs)
    -- | 'calendar.event_*' | 'mail.received'
ALTER TABLE agent_triggers ADD COLUMN resource_type TEXT;  -- 'collection'|'page'|'channel'|'calendar'
ALTER TABLE agent_triggers ADD COLUMN resource_id   TEXT;
ALTER TABLE agent_triggers ADD COLUMN filter_json   TEXT DEFAULT '{}';
    -- {property, operator, value} | {view_id} | {keywords: []} | {include_thread_replies: bool}
ALTER TABLE agent_triggers ADD COLUMN show_typing   INTEGER DEFAULT 1;  -- canaux de messagerie

Les déclencheurs horaires existants migrent sans perte (trigger_kind='schedule', configuration actuelle conservée dans la colonne existante de planification).

10.6 Modèles gouvernés et comptabilité d'usage

-- Migration 42
CREATE TABLE workspace_ai_settings (
    workspace_id   INTEGER PRIMARY KEY REFERENCES workspaces(id),
    allowed_models_personal_json TEXT DEFAULT '[]',  -- [] = tous les modèles configurés
    allowed_models_custom_json   TEXT DEFAULT '[]',
    premium_models_json          TEXT DEFAULT '[]',  -- modèles derrière crédits, activés par l'admin
    default_model  TEXT,
    member_credit_limit  INTEGER,     -- crédits / membre / mois ; NULL = illimité
    allowance_json TEXT DEFAULT '{}', -- paramètres de l'allocation incluse (fenêtre, volume)
    who_can_create_agents TEXT DEFAULT 'everyone',  -- 'everyone'|'admins'
    updated_by INTEGER REFERENCES users(id), updated_at TEXT
);

CREATE TABLE ai_usage_ledger (
    id          INTEGER PRIMARY KEY,
    workspace_id INTEGER NOT NULL,
    run_id      INTEGER REFERENCES agent_runs(id),
    user_id     INTEGER REFERENCES users(id),   -- bénéficiaire (interactif) ou propriétaire (autonome)
    agent_id    INTEGER REFERENCES agents(id),
    provider    TEXT, model TEXT,
    tokens_in   INTEGER DEFAULT 0, tokens_out INTEGER DEFAULT 0,
    credits     REAL NOT NULL DEFAULT 0,       -- 0 pour les modèles inclus à l'allocation
    bucket      TEXT NOT NULL DEFAULT 'allowance',  -- 'allowance' | 'premium'
    created_at  TEXT NOT NULL
);
-- Allocation et limites se CALCULENT depuis ce journal (fenêtres glissantes),
-- aucun compteur dénormalisé à maintenir. Index sur (workspace_id, created_at)
-- et (user_id, created_at), (agent_id, created_at).

Tarification : une table de prix par modèle (crédits par millier de tokens, entrée/sortie) vit dans llm_config étendue ou un fichier de configuration versionné — décision §21, ADR-09 : commencer par une correspondance modèle → taux dans les réglages du workspace, le mode offline comptant 0.

10.7 Espace fichiers des runs

-- Migration 43
CREATE TABLE agent_run_files (
    id          INTEGER PRIMARY KEY,
    run_id      INTEGER REFERENCES agent_runs(id),
    conversation_id INTEGER REFERENCES agent_conversations(id),
    direction   TEXT NOT NULL,        -- 'input' (déposé) | 'output' (produit)
    name        TEXT NOT NULL, mime TEXT, size INTEGER,
    storage_path TEXT NOT NULL,       -- sous data/uploads/agent-files/<conversation>/…
    created_at  TEXT NOT NULL,
    expires_at  TEXT                  -- rétention (§16.4) ; NULL pour les livrables conservés
);

10.8 Relations mises à jour

graph TD
    USERS[users] --> PS[agent_personal_settings]
    PAGES[pages] -->|instruction_page_id| AG[agents]
    AG --> PERM[agent_permissions]
    AG --> VER[agent_versions]
    AG --> TRIG[agent_triggers étendus]
    AG --> RUNS[agent_runs]
    RUNS -->|parent_run_id| RUNS
    RUNS --> ACT[agent_actions + run_id]
    RUNS --> LEDGER[ai_usage_ledger]
    RUNS --> RF[agent_run_files]
    PAGES -->|page_id| SK[agent_skills refonte]
    COLS[collections is_skills_db] --> SK
    SK --> ENAB[user_skill_enablements]
    SK --> SR[skill_runs]
    SK --> DL[skill_local_downloads]
    WS[workspaces] --> WAI[workspace_ai_settings]

---

11. API et événements

Conventions conservées : routes internes cookie-auth sous /api/agent/* (CSRF complet), API publique Bearer sous /api/v2/* (RFC 7807, Idempotency-Key, rate limit par jeton, audit). Le run synchrone v2 existant (SSE tamponné → JSON unique) ne change pas de contrat ; il gagne les champs run_id, skills_used et usage.

11.1 Agent personnel et conversations

Route	État	Rôle
GET/PUT /api/agent/personal-settings	Nouveau	Nom/avatar de mon Agent, pages d'instructions, page active, mode d'affichage, modèle par défaut
POST /api/agent/personal-settings/instructions-page	Nouveau	Créer (ou dupliquer depuis un modèle) ma page d'instructions privée
PATCH /api/agent/conversations/{id}	Nouveau	Épingler/désépingler, renommer (le titre auto reste éditable)
PUT /api/agent/conversations/{id}/sources	Nouveau	État du sélecteur All sources pour la conversation
POST /api/agent/conversations/{id}/files	Nouveau	Téléverser un fichier dans la conversation (§15)
GET /api/agent/conversations/{id}/files/{fid}/download	Nouveau	Télécharger un fichier produit par un run

11.2 Custom Agents

Route	État	Rôle
GET /agents/{id} (SSR)	Nouveau	Page agent : Chat / Activity / Settings
POST /api/agent/agents/generate	Nouveau	Création assistée : description → brouillon {instructions, triggers, accès proposés} (rien d'enregistré)
PUT /api/agent/agents/{id}/settings	Nouveau	Sauvegarde unifiée des Settings → écrit agent_versions + audit ; déclenche agent.updated (webhook)
POST /api/agent/agents/{id}/duplicate	Nouveau	Duplication avec les règles de reprise du §3.3 (ressources filtrées par les accès du duplicateur, connexions et limites exclues, copie privée)
GET /api/agent/agents/{id}/versions · POST …/versions/{vid}/restore	Nouveau	Historique de configuration et restauration
GET /api/agent/agents/{id}/activity	Nouveau	Runs paginés et filtrés (statut, déclencheur, période) pour l'onglet Activity
POST /api/agent/agents/{id}/runs/{run_id}/rerun	Nouveau	Relancer un run avec la même entrée (débogage)
GET /api/agent/agents/{id}/insights · …/insights/export.csv	Nouveau	Statistiques d'usage ; export CSV des conversations (plafond de lignes documenté côté UI)
POST /api/v2/agents/{id}/trigger	Existant	Inchangé ; renvoie désormais aussi run_id

11.3 Skills

Route	État	Rôle
POST /api/agent/pages/{id}/skill · DELETE …	Nouveau	Marquer / démarquer une page comme skill
POST /api/agent/skills/from-page	Nouveau	Créer un skill en déplaçant une page dans une base de skills
GET /api/agent/skills/menu	Nouveau	Skills des menus (/ du chat, éditeur) pour l'utilisateur : activés, éditeur d'abord, intégrés ensuite
PUT /api/agent/skills/{id}/enablement	Nouveau	Enable for me, auto_use, editor_menu (par utilisateur)
POST /api/agent/skills/{id}/run-chat	Nouveau	Invocation manuelle dans une conversation (le run standard porte skill_id)
POST /api/agent/skills/{id}/run-editor	Nouveau	Run sur sélection/bloc, réponse diff ou insertion (§9.2)
GET /api/agent/skills/{id}/download	Nouveau	Bundle SKILL.md + fichiers partageables (par cible d'agent local)
POST /api/agent/skills/import	Nouveau	Importer un SKILL.md externe conforme → crée une page-skill
PUT /db/{id}/skills-db	Nouveau	Convertir une collection en base de skills (correspondance des propriétés)
GET /api/v2/skills · GET /api/v2/skills/{id}	Évolue	La représentation v2 expose page_id, description et la sérialisation SKILL.md (Accept: text/markdown) en plus du format flowdeck-skill v1

11.4 Événements et webhooks

• SSE de run (existant, étendu) : step (étape nommée : contexte, routage de skill, outil), skill_used {skill_id, name, invocation}, approval_required {approval_id}, file_produced {file_id, name}, puis les événements actuels (reasoning, action, notice, final, error).
• Webhooks sortants (catalogue existant, étendu) : agent.run.started|finished|failed gagnent run_id, trigger, credits ; nouveaux agent.run.approval_requested (déjà émis par la gouvernance — on le rattache au run), agent.created|updated|duplicated, skill.created|updated|enabled, agent.credits.threshold (seuils 50/80/100 % d'une limite).
• Bus interne : les déclencheurs d'agents consomment les événements de fire_event() ; aucun événement nouveau n'est inventé quand un équivalent existe (meeting.summarized, form.submitted, page.*, collection.*).

---

12. Moteur d'exécution de l'Agent

12.1 Le contexte de run typé

L'évolution centrale du moteur : chaque exécution est créée avec un contexte explicite, journalisé dans agent_runs :

@dataclass
class RunContext:
    surface: str            # chat | editor | trigger | schedule | api | mention | embed
    actor_user_id: int|None # humain à l'origine (None si purement événementiel)
    agent_id: int|None      # None = Agent personnel
    permission_regime: str  # 'user' (interactif) | 'allowlist' (autonome) — §16.1
    instruction_sources: list[PageRef]   # pages d'instructions résolues (§12.3)
    skills_forced: list[int]             # skills nommés par l'utilisateur (/nom, menu)
    sources: SourcesSelection            # All sources : workspace, connecteurs, MCP
    model_request: str                   # 'auto' ou identifiant de modèle
    budget: Budget                       # itérations, tokens, crédits (§12.2, §16.5)

La boucle ReAct existante ne change pas d'algorithme ; elle reçoit ce contexte, et chaque appel d'outil passe par la chaîne déjà en place — AgentPolicies.check_tool() puis PermissionManager.assert_can() — étendue du contrôle de ressource (§16.1) quand le régime est allowlist.

12.2 Routage de modèle : Auto, premium, replis

1. Demande : le modèle du run vient, par précédence, du choix explicite dans le chat, du réglage de l'agent, du défaut personnel, du défaut du workspace — même esprit que la précédence de configuration LLM existante.
2. Auto : un routeur léger choisit dans les modèles autorisés pour la surface selon la tâche (classification déterministe des demandes simples en mode offline ; sinon heuristiques : tâche longue/multi-étapes/recherche → modèle fort autorisé ; tâche courte → modèle rapide). Le modèle réellement utilisé est écrit dans agent_runs.model et affiché.
3. Premium : un modèle premium non activé par l'admin n'apparaît nulle part ; son usage puise dans les crédits (§10.6) et respecte la limite par membre ; à limite atteinte, le run continue sur les modèles inclus (avec notice SSE), jamais d'échec sec.
4. Repli : modèle retiré en cours de vie d'un agent → bascule automatique sur défaut/Auto à la prochaine exécution (comportement documenté chez Notion, §3.3) ; fournisseur en erreur → le run échoue proprement avec le motif dans Activity (pas de changement de modèle silencieux en plein run).

12.3 Résolution des instructions

Ordre d'assemblage du prompt système d'un run, chaque couche étant traçable dans le journal :

1. Consignes système du produit (invariants, registre d'outils, sécurité) — non éditables
2. Instructions de l'agent
     · Agent personnel : page d'instructions ACTIVE de l'utilisateur (rendu Markdown de la page)
     · Custom Agent     : page d'instructions liée (cache agents.instructions régénéré à la sauvegarde)
3. Mémoire (agent_memory existante, si activée)
4. Skills résolus pour ce run (§13.3) — consignes de tâche, pas de comportement général
5. Contexte de travail (Context Builder v2 : page courante, mentions, sources choisies)

Règles : une page d'instructions non lisible par le régime du run est ignorée avec un notice (jamais d'erreur bloquante) ; la modification d'une page d'instructions prend effet au run suivant (pas de cache inter-runs autre que le cache texte des Custom Agents, invalidé par la sauvegarde de la page) ; l'agent peut, à la demande explicite de l'utilisateur, proposer une modification de sa propre page d'instructions — présentée en diff et appliquée par l'éditeur ordinaire, jamais écrite en silence.

12.4 Transparence du run

Chaque run produit, en plus de la réponse : la liste des sources réellement lues (pages, lignes, connecteurs, serveurs MCP), les skills appliqués (invariant I5), les actions d'écriture avec leur lien d'annulation, et le coût. C'est ce même journal qui alimente Activity, Insights, l'export CSV et les webhooks : une seule vérité d'exécution, quatre présentations.

12.5 Le registre d'outils : règles d'extension

Le registre actuel (26 outils + MCP dynamiques) s'étend sous quatre règles, qui concrétisent l'invariant I14 :

1. Classes : tout outil déclare READ, WRITE, DESTRUCTIVE ou EXTERNAL_WRITE (nouvelle classe : écriture hors Flowdeck — poster, envoyer, archiver chez un tiers). La gouvernance actuelle sait déjà traiter les trois premières ; EXTERNAL_WRITE hérite du régime d'approbation (§16.3).
2. Pas d'outil = pas de capacité : les limites du §3.7 se traduisent par des absences maintenues — pas d'outil de partage/permission de page, pas d'outil de réglage workspace, pas d'outil de création de rappel, pas d'outil de commentaire (ni création ni édition), pas d'outil de création d'automation de base ni de propriété avancée (formule/rollup/bouton), pas de démarrage de note de réunion par l'agent. Ces absences sont listées en Annexe B et couvertes par des tests de non-régression du registre.
3. Création vs édition asymétrique, comme Notion : l'agent peut créer/éditer propriétés simples, relations et vues (cartes, formulaires inclus) et créer/éditer/évaluer des formules existantes ou nouvelles en texte, sans pouvoir créer les types de propriétés avancés énumérés ci-dessus — la frontière exacte est portée par une liste blanche de types dans l'outil de création de propriété.
4. Snapshots : tout outil d'écriture continue de produire un undo_snapshot_json ; les outils EXTERNAL_WRITE produisent, quand le tiers le permet, une action inverse (supprimer le message posté, archiver le brouillon…) sinon la mention explicite « non annulable » dans le journal.

Le catalogue complet, outil par outil, est en Annexe B.

12.6 Déclencheurs : le dispatcher

agent_triggers_dispatch.py a deux entrées et une seule file de sortie :

• Temps : le scheduler existant (60 s) évalue les déclencheurs schedule arrivés à échéance (comportement actuel, inchangé) et calcule le prochain passage affiché dans les Settings.
• Événements : un abonné unique sur fire_event() reçoit chaque événement du bus des automatisations ; il sélectionne les agent_triggers de type event dont event_name, ressource et filter_json correspondent (filtres évalués avec le même vocabulaire d'opérateurs que les conditions d'automations : eq, neq, contains, changed, appartenance à une vue…).
• Mentions : les mentions d'agents ([[fdagent:ID]], même famille de jetons que [[fdpage:ID]]) dans pages, propriétés et commentaires émettent un événement agent.mentioned sur le même bus.

Garde-fous du dispatcher (détail §18) : déduplication par (trigger, empreinte d'événement), fenêtre anti-boucle (un agent ne peut pas se redéclencher par ses propres écritures : les événements portent l'acteur, et un run autonome marque ses écritures actor=agent:<id> exclues de ses propres déclencheurs par défaut), plafond de runs autonomes par agent et par heure, concurrence bornée (file par workspace), et interrupteur d'arrêt par agent (désactiver un déclencheur ou suspendre l'agent stoppe les nouveaux runs sans toucher aux runs en cours).

12.7 Délégation entre agents

• Outil système delegate_to_agent (classe READ du point de vue des données, mais consommateur de budget) : visible uniquement pour les agents dont delegation_json est non vide.
• Le run enfant est un vrai run (parent_run_id), avec le régime allowlist de l'enfant — déléguer ne transmet ni les accès du parent, ni ceux de l'utilisateur. Le contexte transmis est explicite : la tâche rédigée par le parent + les artefacts qu'il attache ; pas d'accès implicite à la conversation du parent.
• Plafonds : profondeur 3 par défaut (réglable par agent, jamais au-delà de 5), budget de crédits partagé prélevé sur l'enveloppe du run parent, timeout propre à l'enfant.
• Évaluation : chaque enfant doit être testable seul (sa propre page, son propre onglet Chat) — la délégation ne crée pas d'agents « cachés ».

12.8 Débogage et rejouabilité

Activity + rerun + versions donnent la boucle de débogage documentée chez Notion : ouvrir le run en échec → lire déclencheur, étapes, erreur → corriger instructions/déclencheurs/accès → relancer la même entrée. Un run relancé est un nouveau run lié (trigger_payload_json.rerun_of), l'original reste intact.

---

13. Moteur Skills

13.1 Cycle de vie d'un skill

stateDiagram-v2
    [*] --> PageOrdinaire
    PageOrdinaire --> Skill: marquer « Use as a skill »<br/>ou création dans une base de skills
    Skill --> Skill: édition de la page (versionnée comme toute page)
    Skill --> ActivePourMoi: Enable for me (créateur : automatique)
    ActivePourMoi --> Skill: désactiver pour soi (Library)
    Skill --> PageOrdinaire: décocher « Use as a skill »
    Skill --> Corbeille: supprimer la page (pour tout le monde)

Création assistée : depuis le chat (/ → +, ou « crée un skill qui… »), un run dédié de l'Agent personnel conduit un court dialogue (travail visé, entrées, règles, exemples, sortie) puis crée la page dans la base de skills privée de l'utilisateur, avec la Description rédigée pour le routeur (§13.2) — l'utilisateur relit et ajuste la page comme n'importe quel document.

13.2 Le routeur de skills (usage automatique)

Entrée : la demande normalisée du run + les skills activés pour l'utilisateur (ou, pour un Custom Agent, les skills de ses accès) dont auto_use effectif est vrai et la description non vide.

1. Candidats : recherche hybride existante (FTS5 + cosinus sur semantic_embeddings,
   resource_type='skill') sur titre + description → top 8
2. Score : similarité combinée (RRF, k=60 — mêmes constantes que la recherche hybride)
3. Décision déterministe hors LLM quand c'est possible :
     · score ≥ seuil haut        → le meilleur candidat est appliqué
     · seuil bas ≤ score < haut  → le LLM du run tranche parmi les candidats
                                   (leurs descriptions sont jointes au contexte)
     · score < seuil bas         → aucun skill
4. Mode offline : étape 3 réduite à ses branches déterministes (testable sans fournisseur)
5. Plusieurs skills : au plus 2 skills automatiques par run (le premier en consigne
   principale, le second en consigne secondaire) ; les skills FORCÉS par l'utilisateur
   (/nom, menu) ne sont jamais écartés par le routeur

Les seuils sont des réglages de workspace (défauts documentés dans le code), et chaque décision (retenu / écarté / scores) est écrite dans le journal du run : un mauvais appariement doit être débogable depuis Activity, pas seulement constatable.

13.3 Exécution d'un skill

Le Skill Runner construit la consigne de run à partir de la page :

[Page du skill rendue en Markdown — blocs texte éligibles, contenu imbriqué inclus]
+ [Fichiers de support : extraits indexés des fichiers shareable, dans la limite du budget]
+ [Entrée du run : sélection / bloc / demande / payload du déclencheur]
+ [Contrainte d'outils : intersection (outils du skill s'il en déclare) ∩ (politique) ∩ (régime)]

• En chat : la consigne s'insère à la couche 4 du prompt (§12.3) ; la réponse nomme le skill (I5).
• Dans l'éditeur : le résultat est une transformation ou une insertion (§7.2) ; les skills intégrés historiques d'AI Writing sont réimplémentés comme appels au même runner (leurs prompts deviennent les pages des skills intégrés, livrées en seed, is_builtin=1, non supprimables mais désactivables).
• Par un Custom Agent : le skill doit figurer dans les accès de l'agent ; ses instructions disent quand l'utiliser ; le run autonome peut aussi le recevoir du routeur, limité aux skills accordés.

13.4 Éligibilité des contenus (éditeur)

Reprise de la liste documentée : texte, titres H1–H3, citation, callout, listes (à puces, numérotées, to-do), toggle, image, bloc synchronisé — le contenu imbriqué est inclus ; les blocs vides et les autres types n'offrent pas le menu Skills. Dans Flowdeck, cette éligibilité est une propriété du registre des types de blocs (§13.2 de l'architecture Flowdeck), déclarée par type : skill_eligible: bool.

13.5 Découverte, activation, gouvernance d'équipe

• Discover = skills dont l'utilisateur a l'accès en lecture (via la page ou la base) mais pas d'user_skill_enablements actif ; Enable for me crée la ligne.
• Partage = partage de la page ou de la base (mécanismes existants, aucun nouveau droit) ; un skill partagé en édition est mutable par ses éditeurs pour tous — l'UI de la bannière le rappelle, et l'historique de page sert de filet (restauration de version de page = restauration du skill).
• Qualité d'équipe : propriétés libres de la base (Owner, Status, Tags) ; la Library trie par usage réel (skill_runs) pour faire émerger les skills qui servent.

13.6 Export SKILL.md et import

Sérialisation (format v2, externe) — le format que lisent les agents locaux :

---
name: synthese-entretien
description: Transforme des notes d'entretien client en synthèse structurée…
---

<corps de la page du skill, en Markdown>

Le bundle de téléchargement contient ce fichier + les fichiers de support shareable=1 dans un sous-dossier de références. Le format flowdeck-skill v1 (JSON, existant) reste le format d'échange entre instances Flowdeck (il transporte les outils autorisés et les réglages, que SKILL.md ignore) ; l'import accepte les deux : un SKILL.md externe devient une page-skill dans la base privée de l'importateur, ses fichiers joints deviennent la propriété Files.

Cibles locales : l'écriture dans les répertoires de skills des agents locaux (poste de l'utilisateur) ne peut pas être faite par le serveur web seul ; deux voies, tranchées en question ouverte Q4 (§23) : (a) téléchargement du bundle + instructions d'installation (simple, fidèle au geste « télécharger ») ; (b) utilitaire compagnon / extension navigateur qui écrit aux emplacements choisis. La Phase 4 livre (a) ; le suivi de version (skill_local_downloads) et le badge fonctionnent dans les deux cas, puisque l'empreinte est calculée côté serveur.

13.7 Sécurité propre aux skills

Une page de skill est du texte d'instruction fourni par des humains : c'est une surface d'injection de prompt de premier ordre. Traitements (§16.4 pour le détail) : un skill ne peut ni élargir les outils du run (intersection seulement), ni modifier les consignes système ; les fichiers de support sont traités comme des données, jamais comme des instructions système ; l'usage automatique est limité aux skills activés par l'utilisateur ou accordés à l'agent.

---

14. Connecteurs, sources et actions externes

Socle existant (architecture Flowdeck §16.4) : catalogue de connecteurs natifs, connecteurs personnels, OAuth Google/MS365 en lecture seule, client MCP complet, fetch gardé SSRF, secrets chiffrés Fernet. Cette section ne refait pas ce socle ; elle ajoute les actions et un connecteur.

14.1 Le contrat d'un connecteur « agent-ready »

Pour alimenter à la fois le sélecteur All sources et le registre d'outils, chaque connecteur déclare :

ConnectorCapability:
    sources:  [{id, label, kind}]            # ce qu'All sources peut cocher
    read_tools:  [tool...]                    # recherche / lecture (classe READ)
    write_tools: [tool...]                    # écritures (classe EXTERNAL_WRITE, §16.3)
    triggers:    [event...]                   # événements émis vers le bus (déclencheurs)
    identity: 'user' | 'agent_grants'         # agit en tant que l'utilisateur,
                                              # ou dans les seuls canaux accordés à l'agent

14.2 Slack — nouveau connecteur natif

Absent du catalogue décrit en v7.69.8, c'est le seul connecteur à créer de zéro, en suivant le patron des natifs existants :

• Connexion workspace par un admin (préalable aux déclencheurs d'agents), puis connexion de compte par utilisateur pour l'Agent personnel (même courriel que le compte Flowdeck dans le parcours de référence).
• Agent personnel (identité user) : chercher des personnes ; lire les canaux et fils accessibles à l'utilisateur (publics, privés, messages directs) ; lire les fichiers partagés ; poster, répondre en fil, éditer ses propres messages, ajouter/retirer des réactions. Borne dure : l'outil reçoit le jeton de l'utilisateur et ne voit que sa visibilité — aucun mode « admin Slack » pour l'agent.
• Custom Agents (identité agent_grants) : lecture/écriture limitées aux canaux énumérés dans Tools and access ; déclencheurs message.posted (filtres mots-clés, inclusion des fils), message.reaction, message.mention (mention de l'agent) ; indicateur « en train de travailler » par déclencheur (show_typing).
• Les messages postés par un Custom Agent sont signés comme venant de l'agent (compte d'app), ceux de l'Agent personnel comme venant de l'utilisateur — la distinction est visible dans le journal du run et dans l'app tierce.

14.3 Google / Microsoft 365 : de la lecture seule à l'écriture gardée

Les connecteurs OAuth existants gagnent des scopes d'écriture optionnels, demandés séparément (un second consentement, révocable indépendamment de la lecture) :

Domaine	Lectures (existantes)	Écritures ajoutées (classe EXTERNAL_WRITE)
Gmail	recherche, lecture	rédiger un brouillon, envoyer (confirmation systématique par défaut), archiver, corbeille, étiqueter/désétiqueter, se désabonner d'un expéditeur
Calendrier	lecture, free/busy (déjà utilisé par la sync)	trouver un créneau : outil dédié qui croise les disponibilités des participants et rend des suggestions classées + la matière de la grille interactive du panneau (§7.1) ; créer un événement (organisateur = l'utilisateur), préparer une réunion (contexte assemblé : événement, participants, pages liées, note de réunion) ; déplacer/annuler uniquement les événements dont l'utilisateur est organisateur
Drive / Files	lecture	déposer un fichier produit par un run (§15) dans un dossier choisi

Pour les Custom Agents, l'accès calendrier/courriel passe par les ressources accordées (agenda nommée, libellés nommés) et les déclencheurs calendar.event_* / mail.received (filtres expéditeur/mot-clé).

14.4 Inbox Flowdeck — outils nouveaux sur un service existant

Le service de notifications (§19.4 Flowdeck) reçoit quatre outils d'agent (registre, Annexe B) : lire/résumer les notifications, les regrouper (type, statut, projet/page), marquer lu/non-lu, archiver/désarchiver (y compris en masse — écriture interne, confirmée si le lot dépasse un seuil). Deux bornes reprises de la documentation Notion : l'agent ne peut pas décider les demandes d'approbation/d'accès intégrées aux notifications (il les signale), et ne peut ni créer de notifications ni modifier les préférences de notification. L'Inbox reste la source de vérité ; le chat n'en est qu'une vue d'action.

14.5 Messagerie déjà connectée (Discord, Telegram, Teams)

Les connecteurs personnels existants sont promus au même contrat (§14.1) : leurs canaux deviennent des sources cochables, des cibles d'outils d'envoi (EXTERNAL_WRITE) et des sources de déclencheurs (message, réaction, mention) pour les Custom Agents — c'est par eux, autant que par Slack, que les déclencheurs « messagerie » de Notion sont reproduits dans un parc Flowdeck qui n'aurait pas Slack.

14.6 MCP : consommer, et la question du serveur

• Client MCP (existant) : les serveurs connectés apparaissent dans All sources sous une rubrique dédiée ; l'ajout peut se lancer depuis le chat (« connecte… »), depuis le sélecteur de sources, ou depuis les réglages de connexions — trois portes, un même flux d'authentification. Les outils MCP conservent leur fusion dynamique au registre et leur préfixe mcp_<serveur>_<outil> ; leur classe par défaut est READ, un outil MCP ne devient écrivant que si le serveur le déclare et la politique l'autorise.
• Serveur MCP Flowdeck : hors périmètre de ce document (chantier déjà documenté côté Flowdeck) ; on note seulement la symétrie utile : le jour où il existe, l'API v2 skills (§11.3) lui donne ses outils de skills sans travail supplémentaire.

14.7 Accès web

Interrupteur par agent (Custom Agents) et par conversation (Agent personnel) : éteint par défaut pour les Custom Agents, il conditionne les outils web_search / fetch_url existants. Un modèle « web-seulement » (§3.2) est représenté honnêtement dans l'interface : choisir ce modèle décoche les sources workspace/connecteurs pour le run, plutôt que de laisser croire à une lecture qui n'aura pas lieu.

---

15. Espace de travail fichiers (« computer ») de l'Agent

Objectif documenté chez Notion : dépasser le texte — ingérer des fichiers réels, calculer dessus, et rendre des fichiers. Flowdeck assemble trois briques existantes : les importers (§21 Flowdeck), la sandbox des Workers (§19.2 Flowdeck), les exports (§21.2 Flowdeck).

15.1 Cycle de vie

Dépôt (📎, glisser-déposer dans le panneau)
  → agent_run_files (direction=input) sous data/uploads/agent-files/<conversation_id>/
  → extraction à la demande par read_uploaded_file :
      PDF/DOCX/PPTX → texte structuré (importers) ; CSV/XLSX → profil tabulaire
      (colonnes, types devinés, aperçu de lignes) ; ZIP → inventaire + extraction unitaire
  → travail : le LLM manipule des RÉSUMÉS et des aperçus, jamais le binaire ;
      les calculs lourds passent par run_code_on_data
  → production par produce_file : XLSX (openpyxl), PDF (WeasyPrint/xhtm2pdf),
      DOCX (python-docx), PPTX (génération simple par gabarit) —
      mêmes bibliothèques que l'import/export, aucun ajout de dépendance
  → agent_run_files (direction=output) + carte téléchargeable dans le message

15.2 La sandbox comme « computer »

run_code_on_data réutilise le moteur d'exécution des Workers : lint AST (imports interdits), builtins restreints, pas de réseau, timeout 30 s, budget. Différences assumées avec les Workers partagés : le système de fichiers de la conversation est monté en lecture (fichiers déposés) et un répertoire de sortie en écriture (fichiers produits) — c'est le seul écart au « pas de filesystem » des Workers, borné à agent_run_files de la conversation, avec quotas (taille par fichier, total par conversation, durée de rétention configurable, purge par un scheduler existant — on ajoute le nettoyage au trash_purge_scheduler plutôt qu'un nouveau scheduler).

15.3 Transformation fichier → structure

create_collection_from_file : un CSV/XLSX ingéré peut devenir une vraie collection (inférence de types de propriétés par les importers tabulaires, déduplication du pipeline d'import), et un document peut devenir une page structurée. Ce ne sont pas des outils nouveaux au sens fort : ce sont les entrées du pipeline d'import, appelées avec le fichier de la conversation comme source et le run comme contexte d'audit.

15.4 Garde-fous fichiers

Types acceptés = liste blanche alignée sur les importers ; archives ZIP : pas d'extraction récursive, plafond de taille décompressée (anti-bombe) ; fichiers produits : jamais exécutables ; tout fichier déposé est traité comme donnée (son contenu ne devient jamais une consigne système — §16.4).

---

16. Sécurité, permissions et gouvernance

16.1 Les deux régimes de permissions — spécification

	Run interactif (Agent personnel, Chat d'un Custom Agent lancé à la main)	Run autonome (déclencheur, horaire, mention, API)
Identité d'exécution	L'utilisateur qui lance	Le Custom Agent
Lecture autorisée si…	assert_can(user, ressource) (existant)	ressource ∈ accès de l'agent et assert_can(propriétaire de l'agent, ressource) et politique du workspace
Écriture autorisée si…	Idem, + gates existants (éditeur+, destructif = admin/owner + 428)	Idem, + outil ∈ scope_json de l'agent + approbation selon la politique de l'agent
Sources externes	Jeton/connecteurs de l'utilisateur	Canaux et ressources accordés à l'agent uniquement
Memoria / instructions	Celles de l'utilisateur	Celles de l'agent (page liée)

Le contrôle « ressource ∈ accès de l'agent » est un nouveau filtre du Context Builder et du Tool Registry pour le régime allowlist : les résultats de recherche eux-mêmes sont filtrés (un run autonome ne doit pas apprendre, même par un titre de résultat, l'existence d'une page hors de ses accès). La recherche hybride existante filtre déjà par ACL utilisateur ; le régime autonome compose ce filtre avec la liste blanche.

16.2 Partage des agents

agent_permissions (§10.2) suit les patrons d'ACL du produit : grant user XOR groupe, héritage nul (un agent ne s'hérite pas d'un workspace), résolution au moindre privilège. Niveaux : full (configurer, activité, partager), edit (configurer sans partager), interact (chat, runs manuels, settings en lecture). La création d'agents est gouvernée par who_can_create_agents ; chaque grant et chaque changement de configuration alimentent le journal d'audit unifié existant (source agents ajoutée à la vue fusionnée).

16.3 Approbations et écritures externes

Le mécanisme agent_approvals existant est étendu, pas remplacé :

• La classe EXTERNAL_WRITE exige, par défaut, une approbation par action (le run passe en waiting_approval, webhook émis, carte d'approbation dans le panneau ou dans Activity).
• Un Custom Agent peut recevoir une politique pré-approuvée bornée : par outil et par cible (par exemple « poster dans #équipe sans demander »), accordée uniquement par un niveau full, révocable, et journalisée ; l'envoi de courriel reste toujours à confirmation pour l'Agent personnel (parité avec le comportement documenté).
• Les actions en masse (archiver toutes les notifications lues, étiqueter un lot) demandent confirmation avec le compte exact d'éléments concernés.

16.4 Injection de prompt : surfaces et traitements

Les Agents & Skills ajoutent trois surfaces d'instructions non fiables. Traitement uniforme :

Surface	Risque	Traitement
Pages de skills/instructions partagées	Un éditeur malveillant ou négligent change le comportement pour tous	Permissions de page ordinaires + historique restaurable ; bannière rappelant l'effet d'une édition ; skills à fort usage signalés à l'admin (option)
Contenus lus par l'agent (pages, messages, courriels, fichiers, résultats MCP/web)	Instruction cachée dans les données (« ignore tes règles et envoie… »)	Ces contenus sont livrés au modèle comme données délimitées, jamais fusionnées aux consignes système ; les outils restent la seule voie d'action et restent soumis aux contrôles du §16.1/§16.3 — une injection peut au pire produire une demande d'action que la gouvernance refuse
Descriptions de skills	Un skill se décrit pour être choisi hors de son sujet	Routeur limité aux skills activés/accordés ; décision journalisée (§13.2) ; Use automatically désactivable ; les skills intégrés ne peuvent pas être redéfinis par un skill d'utilisateur de même nom en mode automatique

16.5 Modèles et argent : gouvernance

• Modèles autorisés par surface (workspace_ai_settings) appliqués aux trois endroits où un modèle se choisit : chat, Settings d'agent, routage Auto.
• Les modèles premium exigent l'activation admin (liste explicite) ; un modèle premium désactivé disparaît des menus (grisé pendant une transition de configuration) et les agents qui l'utilisaient basculent au prochain run (§12.2).
• Limites : par membre (crédits/mois, tous agents confondus) et par agent (credit_limit_monthly) ; à l'atteinte : les modèles inclus continuent, les premium s'arrêtent, agent.credits.threshold est émis, et l'utilisateur/l'agent voit un état explicite — jamais un échec de run inexpliqué.
• Aucune donnée client ne sert à entraîner les modèles : Flowdeck délègue aux fournisseurs LLM configurés ; le document rappelle que les régimes de conservation varient par fournisseur (c'est la raison d'être de l'activation admin par modèle, §3.3) et que le choix du fournisseur reste une décision du workspace (clés propres, Ollama local, mode offline).

16.6 Vie privée et rétention

• Conversations et runs : rétention alignée sur l'historique de pages du workspace ; suppression d'une conversation = suppression de ses fichiers d'espace (§15) et de sa mémoire.
• Fichiers déposés : expiration configurable (défaut proposé : 30 jours) sauf livrables explicitement conservés par l'utilisateur ; le journal de run garde les métadonnées (nom, taille), pas le contenu.
• Les journaux d'activité d'un Custom Agent sont visibles au niveau full uniquement ; Insights agrège sans exposer le contenu des conversations des autres.

---

17. Exigences non fonctionnelles

Exigence	Cible proposée (à valider)
Latence du chat	Premier événement SSE (step) < 500 ms après l'envoi ; le streaming existant fait le reste
Routage de skill	< 300 ms en mode déterministe (index local), sans appel LLM supplémentaire dans la branche haute confiance
Runs autonomes	File bornée par workspace ; un déclencheur ne perd jamais un événement silencieusement : tout événement apparié produit un run (exécuté, refusé ou budget_exceeded) visible dans Activity
Concurrence	Plafond de runs simultanés par workspace (réglage, défaut modeste adapté au mono-processus) ; les runs interactifs ont priorité sur les runs autonomes
Coûts	Aucun run sans écriture au journal d'usage ; agrégats d'usage calculables en < 1 s sur 12 mois (index du §10.6)
Mode offline	Routage de skills, déclencheurs, délégation (avec réponses du mock planner) et espace fichiers fonctionnels sans fournisseur — couverture de tests équivalente aux fonctions en ligne
Accessibilité / i18n	Panneau et Library au niveau du reste du produit ; libellés en français (le produit est lang: fr) avec noms d'objets conservés en anglais (Agent, Skill)
Observabilité	Compteurs de runs par statut/surface, distribution des coûts, taux d'appariement de skills — dans les Insights d'administration, sans service externe

18. Résilience et gestion des échecs

Échec	Comportement attendu
Fournisseur LLM en panne pendant un run interactif	Le run se termine en failed avec le motif ; la conversation et les actions déjà appliquées restent (chacune annulable) ; bouton Réessayer
Fournisseur en panne pendant un run autonome	Run failed dans Activity + webhook ; pas de rejeu automatique pour les déclencheurs événementiels (l'événement est passé), rejeu possible à la main ; les horaires, eux, repartent au passage suivant
Boucle d'agent (auto-déclenchement, délégation circulaire)	Marque d'acteur sur les écritures d'agent, profondeur de délégation plafonnée, plafond horaire par agent ; au plafond : suspension des déclencheurs de l'agent + notification au propriétaire
Skill introuvable / page supprimée en plein usage	Le run continue sans le skill, avec notice explicite ; un skill dont la page est à la corbeille disparaît des menus dès la suppression (la ligne agent_skills suit la page)
Approbation qui n'arrive jamais	Run waiting_approval expiré après un délai configurable (défaut proposé : 72 h) → cancelled, aucune action exécutée
Budget crédits épuisé au milieu d'un run multi-étapes	Arrêt propre à la prochaine frontière d'outil, réponse partielle signalée comme partielle, jamais d'écriture externe « déjà partie » présentée comme non faite
Événement en double (webhook réémis, scheduler rejoué)	Déduplication par empreinte d'événement au dispatcher (§12.6) ; Idempotency-Key côté API inchangée
Fichier déposé illisible / trop gros	Rejet au dépôt avec motif (type, taille) ; un fichier illisible après coup produit un résultat d'outil d'échec, pas un plantage du run
Base de skills convertie puis « déconvertie »	Les pages redeviennent ordinaires ; les lignes agent_skills correspondantes sont supprimées, les activations utilisateurs nettoyées en cascade, l'historique skill_runs conservé

19. Déploiement et exploitation

• Aucun changement d'infrastructure : même conteneur, même processus, mêmes volumes. Nouveaux répertoires de données : data/uploads/agent-files/ (dans le volume existant, couvert par la sauvegarde existante — avec la réserve que les fichiers éphémères y gonflent les snapshots : la purge par expiration du §15.2 borne ce volume).
• Variables d'environnement nouvelles (toutes optionnelles, défauts sûrs) : AGENT_FILE_MAX_MB, AGENT_FILE_RETENTION_DAYS, AGENT_MAX_CONCURRENT_RUNS, AGENT_AUTONOMOUS_HOURLY_CAP, SKILL_ROUTER_AUTO_THRESHOLD. Les clés des nouveaux connecteurs suivent le régime existant (OAuth + Fernet, jamais en variable d'environnement pour les jetons utilisateurs).
• Migrations 39 à 43 : additives sauf la recréation d'agent_skills (migration 41) qui suit le patron « créer la nouvelle table, copier, générer les pages manquantes, basculer » dans une transaction, avec un script de vérification post-migration (comptage skills avant/après).
• Exploitation : l'état des agents (runs en cours, files, budgets) rejoint la page d'administration existante ; aucun nouveau scheduler, aucun nouveau port.

20. Plan d'implémentation par phases

Chaque phase est livrable seule, testée en mode LLM offline comme en ligne, et laisse le produit dans un état cohérent. Les numéros de version Flowdeck sont des propositions d'étiquetage, pas des engagements.

Phase 1 — Le Skill devient une page (E1, E3, E4 modèle)

• Migrations 41 (skills) + correspondance des propriétés ; conversion de collection en base de skills ; marquer/démarquer une page ; bannière de skill ; migration des skills existants et des 17 presets en pages.
• Library : onglet Skills (liste + réglages du skill) et Discover + Enable for me (user_skill_enablements).
• Skills intégrés : les 6 actions AI Writing exposées comme skills intégrés du menu de sélection ; unification des trois points d'entrée éditeur existants sur le Skill Runner.
• Export/import SKILL.md (bundle téléchargeable) en plus du format v1.
• Critère de sortie : UC-02 et UC-04 fonctionnent entièrement sur des pages ; un playbook existant devient un skill sans copier-coller.

Phase 2 — L'Agent choisit, l'Agent personnel se personnalise (E2, E11)

• Migration 39 (réglages personnels, instructions-page, accès web) ; page « Mon Flowdeck AI » ; sélecteur de modèle avec Auto (§12.2 sans crédits) ; All sources persisté par conversation ; épinglage et titrage auto des conversations ; panneau des sources d'un run (skill nommé, I5).
• Skill Router (§13.2) : indexation des descriptions, décision déterministe + arbitrage LLM, journal de décision.
• Migration 40 limitée à agent_runs (sans déclencheurs événementiels) : tout run devient un objet journalisé avec modèle réel et skills utilisés.
• Critère de sortie : UC-01 et UC-03 ; un run se relit entièrement (sources, skill, coût en tokens) depuis son journal.

Phase 3 — Les Custom Agents deviennent autonomes (E5, E6, E7, E12, E14)

• Page agent en trois onglets ; partage à trois niveaux (agent_permissions) ; versions de configuration ; duplication ; embed dans les pages ; mentions [[fdagent:]].
• Déclencheurs événementiels : extension d'agent_triggers (migration 40 complète) + dispatcher sur fire_event() ; filtres ; garde-fous anti-boucle ; Activity et rerun.
• Création assistée par l'IA (méta-run de génération) ; galerie de modèles de Custom Agents.
• Délégation entre agents (§12.7).
• Critère de sortie : UC-05, UC-06, UC-07 ; un agent événementiel tourne une semaine en autonomie avec un journal propre.

Phase 4 — Agir dehors, travailler sur fichiers, compter (E8, E9, E10, E13)

• Connecteur Slack (§14.2) ; écritures gardées Google/MS365 (§14.3) ; outils Inbox (§14.4) ; promotion des connecteurs de messagerie existants au contrat agent-ready (§14.5).
• Espace fichiers (migration 43) : dépôt dans le chat, run_code_on_data sur la sandbox Workers, produce_file, tableau interactif de résultats dans le chat.
• Comptabilité : workspace_ai_settings + ai_usage_ledger (migration 42), modèles autorisés par surface, activation premium, limites membre/agent, tableaux d'usage et seuils d'alerte.
• Critère de sortie : UC-08, UC-09, UC-10 ; aucun run sans ligne au journal d'usage ; aucune écriture externe sans approbation ou politique explicite.

Phase 5 — Durcissement et extensions (optionnelle)

• Insights avancés et export CSV à l'échelle ; optimisation du routeur (apprentissage sur les décisions corrigées) ; Skills API publique enrichie (publication d'une base de skills vers des agents externes) ; préparation du terrain pour le serveur MCP Flowdeck (chantier séparé) et pour un SDK d'agents si le besoin se confirme.
• Critère de sortie : revues de sécurité (injection de prompt, §16.4) et de coûts passées sur les données réelles des Phases 1 à 4.

21. Décisions d'architecture (ADR — résumé)

ADR	Décision	Alternative écartée
ADR-01	Le skill est une page ; agent_skills devient l'index d'exécution adossé à la page	Garder des skills-enregistrements et ajouter un éditeur dédié (double tout : ACL, historique, recherche)
ADR-02	Deux régimes de permissions (user / allowlist) portés par le type de run, pas par deux moteurs	Un régime « droits du créateur » pour les agents autonomes (faille classique d'escalade)
ADR-03	Les déclencheurs d'agents consomment le bus fire_event() des automatisations	Un second système d'événements propre aux agents
ADR-04	Le routage automatique de skill est hybride et d'abord déterministe (index existant, seuils), l'arbitrage LLM n'intervient qu'en zone grise	Un appel LLM systématique par demande (coût, latence, non-testabilité offline)
ADR-05	Les instructions vivent dans des pages ; le texte libre d'agents.instructions devient un cache	Instructions en base dans un champ texte (pas d'historique, pas de co-édition)
ADR-06	Le run est un objet persisté (agent_runs) auquel actions, fichiers, coûts et approbations se rattachent	Continuer avec des runs implicites (conversation + actions)
ADR-07	L'espace fichiers réutilise la sandbox des Workers avec un montage borné à la conversation	Une sandbox neuve pour l'agent (double surface de sécurité à auditer)
ADR-08	SKILL.md pour l'extérieur, flowdeck-skill v1 conservé pour l'échange Flowdeck ↔ Flowdeck	Un seul format : le JSON v1 n'est lu par aucun agent local ; SKILL.md perd les réglages Flowdeck
ADR-09	Crédits = journal calculé (ai_usage_ledger), prix par modèle en réglages de workspace	Compteurs dénormalisés à incrémenter (dérive garantie entre compteur et réalité)
ADR-10	Les limites produit de l'Agent sont des outils absents, listés en Annexe B et testés	Des interdictions rédigées dans le prompt système
ADR-11	Slack est ajouté comme connecteur natif, sur le patron des natifs existants	Laisser Slack aux connecteurs personnels/MCP (les déclencheurs d'agent exigent la connexion workspace administrée)

22. Risques et mitigations

Risque	Mitigation
Migration des skills existants vers des pages : perte ou déformation de prompts en production	Migration 41 transactionnelle + pages générées conservant le prompt d'origine à l'identique (source='legacy') ; vérification par comptage et échantillon avant bascule
Appariement automatique de skills trop agressif (mauvais skill appliqué en silence)	Seuils conservateurs au départ, skill toujours nommé dans la réponse (l'erreur est visible), Use automatically désactivable par skill et par utilisateur, journal de décision débogable
Coûts LLM des runs autonomes mal configurés (déclencheur trop large)	Filtres obligatoires proposés par l'assistant de création, plafonds horaires, budgets par agent dès la Phase 3 (compteur tokens) avant même les crédits de la Phase 4, Activity relue en un clic
Un agent autonome écrit là où il ne devait pas	Régime allowlist (§16.1) filtrant jusqu'aux résultats de recherche ; approbations par défaut sur EXTERNAL_WRITE ; annulation par action conservée
Injection de prompt via un skill partagé ou un contenu lu	§16.4 : intersection d'outils seulement, données délimitées, gouvernance inchangée quelle que soit la consigne lue
Le mono-processus sature sous les runs autonomes	Files bornées, priorité à l'interactif, concurrence plafonnée ; si la limite devient réelle, c'est le signe documenté (§26 de l'architecture Flowdeck) que le multi-worker devra être traité — pas avant
Dérive des copies locales de skills	Empreinte de version + badge ; la page reste la seule source de vérité, la copie est un cache par construction
Confusion des utilisateurs entre les quatre objets	La distinction est portée par l'interface (quatre lieux distincts : réglages personnels, Library Skills, page Agent, panneau de chat) et par la règle du double copier-coller (§3.1) rappelée dans l'aide in-app

23. Questions ouvertes pour Flowdeck

• Q1 — Tarification des crédits. Flowdeck étant auto-hébergé, les « crédits » sont-ils une monnaie interne de gouvernance (quotas) ou doivent-ils refléter un coût fournisseur réel refacturé ? La Phase 4 fonctionne dans les deux cas (le journal est le même) ; seuls les taux par modèle changent.
• Q2 — Modèle par défaut du workspace. Auto doit-il router vers les modèles des clés de l'utilisateur ou de la configuration globale, quand les deux existent ? La précédence LLM actuelle donne quatre niveaux ; le routeur doit en élire un explicitement.
• Q3 — Skills intégrés et AI Writing. Les 6 actions d'ai_writing.py restent-elles un service headless distinct sous le Skill Runner, ou leurs prompts deviennent-ils littéralement les pages des skills intégrés (éditables par l'admin) ? La Phase 1 propose la seconde voie pour les quatre skills d'édition, et garde le service pour l'autocomplétion inline (latence).
• Q4 — Écriture chez les agents locaux. Téléchargement seul, ou utilitaire compagnon (extension / petit binaire) qui écrit les SKILL.md aux bons endroits et détecte les postes à mettre à jour ? (§13.6)
• Q5 — Slack ou messagerie existante d'abord ? Si l'équipe Flowdeck vit sur Discord/Telegram, la promotion de ces connecteurs (§14.5) peut précéder le connecteur Slack (§14.2) sans changer le modèle — l'ordre de la Phase 4 est réversible.
• Q6 — Rétention des runs. Quelle durée de conservation pour agent_runs et les journaux d'activité, et l'export CSV suffit-il aux besoins d'audit, ou faut-il brancher les runs sur l'export d'audit unifié existant ?

---

Annexe A — Correspondance Notion → Flowdeck

Notion	Flowdeck (cible)	État au départ
Notion Agent (personnel)	Agent personnel : moteur ReAct + agent_personal_settings	🟡 moteur présent, personnalisation à construire
Page d'instructions « My Notion AI »	Page privée « Mon Flowdeck AI », page ordinaire	❌ à construire
Custom Agent	agents avec kind='custom', page /agents/{id}	🟡 agents présents, page et cycle de vie à construire
Tools and access	Accès explicites par agent + régime allowlist	🟡 scope_json (outils) présent, ressources à ajouter
Triggers (horaire)	agent_triggers + scheduler 60 s	✅
Triggers (événements Notion/Slack)	agent_triggers événementiels sur fire_event() + connecteurs	❌ à câbler
Délégation entre Custom Agents	Outil delegate_to_agent, parent_run_id	❌
Embed d'un agent dans une page	Bloc agent_embed	❌
Mention @agent	Jeton [[fdagent:ID]]	❌
Activity / Insights	agent_runs + onglets Activity/Insights, export CSV	❌ (actions journalisées, runs implicites)
Skill = page	Page + ligne agent_skills d'indexation	🟡 skills présents, modèle à refondre
Skills database	Collection is_skills_db + propriétés Description/Files/Tags	❌
Library → Skills / Discover	Onglets Library + user_skill_enablements	❌
Enable for me / Use automatically	Colonnes d'activation par utilisateur et par skill	❌
Skills intégrés (améliorer, corriger…)	Skills is_builtin adossés à AI Writing	🟡 fonctions présentes, forme à aligner
Download for local agents	Bundle SKILL.md + skill_local_downloads (badge)	🟡 format v1 JSON seulement
All sources	sources_json de conversation + Context Builder v2	🟡 mentions présentes, sélecteur à construire
Modèles : Auto / premium / autorisés	Routeur Auto + workspace_ai_settings	🟡 catalogue présent, gouvernance à construire
Allocation d'usage / crédits Notion	ai_usage_ledger (bucket allowance / premium)	❌
AI Connectors (Slack, Gmail, Calendar)	Connecteurs Flowdeck + Slack à créer, écritures gardées	🟡 lecture seule, sans Slack
Serveurs MCP connectés à l'Agent	Client MCP Flowdeck	✅
Enterprise Search	Recherche hybride + Ask AI	✅
Inbox gérée par l'Agent	Outils notifications sur le service existant	❌ outils seulement
Workers	Workers sandboxés Flowdeck	✅
AI Meeting Notes (déclencheur)	Événement meeting.summarized existant	✅

Annexe B — Catalogue des outils de l'Agent

Outils existants repris de l'architecture v7.69.8 (§16.3) ; classes : L = lecture, É = écriture, D = destructif, X = écriture externe.

Outil	Classe	État
search_workspace, read_collection, read_page, read_workspaces, read_document	L	✅ existants
create_collection, create_view, create_page, create_document, add_property (types simples + relations seulement), add_relation, add_sub_item, add_dependency, update_page, write_blocks, apply_template	É	✅ existants (création de propriété à borner, §12.5)
delete_*	D	✅ existants (régime 428 conservé)
read_gitea_issues, sync_gitea, create_gitea_issue	L / É	✅ existants
web_search, fetch_url	L	✅ existants (soumis à l'interrupteur web, §14.7)
search_code (GitHub), connector_fetch	L	✅ existants
Outils MCP dynamiques mcp_<serveur>_<outil>	L par défaut	✅ existants
query_collection (filtres par propriétés, tris, agrégats — sortie tabulaire pour le tableau de chat)	L	🔶 à formaliser depuis read_collection
read_comments, read_page_history (recherche dans les versions)	L	❌ nouveaux
create_or_edit_formula, evaluate_formula	É	❌ nouveaux
apply_skill (chargement d'un skill accordé en consigne de run)	L	❌ nouveau (moteur §13.3)
delegate_to_agent	L (budget)	❌ nouveau (§12.7)
inbox_read, inbox_group, inbox_mark, inbox_archive	L / É	❌ nouveaux (§14.4)
mail_search, mail_read	L	🔶 via connecteur (lecture existante)
mail_draft, mail_send, mail_archive, mail_label, mail_trash	X	❌ nouveaux (§14.3)
calendar_find_time, calendar_create_event, calendar_prep, calendar_move (organisateur seulement)	L / X	❌ nouveaux (§14.3)
slack_search_people, slack_read, slack_post, slack_reply, slack_edit_own, slack_react	L / X	❌ nouveaux (§14.2)
channel_post, channel_read (Discord/Telegram/Teams via connecteurs personnels)	L / X	❌ nouveaux (§14.5)
read_uploaded_file, run_code_on_data, produce_file, create_collection_from_file	L / É	❌ nouveaux (§15)
Outils volontairement absents (parité §3.7)	—	share_page, changement de permissions, réglages workspace, création de rappel, création/édition de commentaire, création d'automation de base, création de propriété avancée (formule/rollup/bouton comme types), démarrage de note de réunion

Annexe C — Skills par défaut et presets à livrer

Skills intégrés (is_builtin=1, seed, désactivables) — parité avec les menus documentés : Améliorer l'écriture · Corriger (proofread) · Expliquer · Reformater · Traduire · Résumer. Les quatre premiers reprennent les actions d'AI Writing ; traduire et résumer existent aussi dans le service — la Phase 1 les expose sous la même forme.

Presets de la galerie actuelle (17, à migrer en pages) : les presets existants (rapport hebdomadaire, compte rendu de réunion, base CRM, OKR, revue de sprint, veille technologique, triage d'incident, briefing quotidien…) deviennent des pages de la base de skills privée à l'installation ; chacun reçoit, pendant la migration, une Description relue pour le routeur (une description écrite pour un humain ne suffit pas toujours à un appariement automatique).

Modèles de Custom Agents à livrer avec la Phase 3 (galerie d'agents, miroir des cas documentés) : Rapport hebdomadaire · Triage de tickets/feedback · Brief quotidien · Q&R d'équipe sur une base de connaissances · Synthèse de canal de messagerie · Suivi de notes de réunion (déclencheur meeting.summarized).

Annexe D — Glossaire

Terme	Sens dans ce document
Agent personnel	L'assistant à la demande de chaque utilisateur ; régime de permissions = l'utilisateur
Custom Agent	Agent partagé et configurable, interactif et autonome ; régime = liste blanche
Skill	Page d'instructions réutilisables pour un type de travail ; peut être forcé ou automatique
Instructions	Consignes permanentes (personnelles ou d'un agent), portées par une page
Run	Une exécution complète et journalisée de l'Agent (agent_runs)
Régime allowlist	Mode d'exécution autonome : accès = intersection des accès de l'agent, des droits de son propriétaire et des politiques
Crédits	Unité de compte interne de l'usage des modèles premium, calculée depuis ai_usage_ledger
Espace fichiers	Zone par conversation où l'Agent lit des fichiers déposés et écrit des fichiers produits
Tools and access	Section des réglages d'un Custom Agent listant ses ressources, outils, skills et délégations

Sources

Documentation publique de Notion, consultée le 9 octobre 2026 (les contenus sont résumés avec mes mots dans la section 3 ; aucun passage substantiel n'est reproduit) :

• Get started with Notion Agent — https://www.notion.com/help/notion-agent
• Custom Agents in Notion — https://www.notion.com/help/custom-agents
• Create & manage skills — https://www.notion.com/help/create-and-manage-skills
• Getting started with skills in Notion (guide) — https://www.notion.com/help/guides/getting-started-with-skills-in-notion
• Manage your inbox with Notion Agent — https://www.notion.com/help/manage-your-inbox-with-notion-agent
• Hub Notion AI (index des pages d'aide et guides, dont instructions de l'Agent, connecteurs, MCP, modèles et crédits, passage à l'échelle des skills) — https://www.notion.com/help/category/notion-ai/all

Documents Flowdeck de référence :

• ARCHITECTURE.md v7.69.8 (fourni par Bruno, 9 octobre 2026) — en particulier §9.3, §13, §15, §16, §17, §18, §19, §21.
• Architecture — Fonctionnalité « Meetings » (modèle Notion) pour Flowdeck, v1.2, 9 octobre 2026 — document compagnon, même méthode.

---

Fin du document — version 1.0, 9 octobre 2026.