# Manuel utilisateur — Constellae

> **Version couverte : 3.191.0** · Dernière mise à jour : 2026-07-14
>
> **À qui s'adresse ce manuel.** Aux utilisateurs et administrateurs d'une
> organisation Constellae — pas aux développeurs d'applications (voir la
> *Convention développeur* pour cela). Il explique, étape par étape, comment
> utiliser la plateforme et réaliser les connexions un peu techniques :
> brancher un assistant IA (MCP), créer un jeton, gérer les clés des services
> externes et sa clé personnelle.
>
> **Où le retrouver.** En ligne : `/api/public/manual`. Dans l'application :
> bouton « 📖 Manuel utilisateur » (Aide). Via un assistant IA connecté en
> MCP : outil `get_user_manual`.
>
> **Maintenance.** Ce document suit les évolutions de la plateforme. Toute
> nouvelle fonctionnalité visible par l'utilisateur doit y être reflétée.

---

## Sommaire
1. Premiers pas
2. Utiliser les applications
3. Services externes (Services API) — le cœur
4. Ma clé personnelle (pas à pas)
5. Connecter un assistant IA (MCP)
6. Jetons d'API
7. Canaux & webhooks
8. Stocker des données
9. Rôles & qui peut faire quoi
10. Constellation ✦ — orchestrateur no-code
11. Nova Studio ★ — créer ses propres applications
12. Halos 🌟 — enrichir vos Novas (compléments)
13. Dépannage

---

## 1. Premiers pas

- **Se connecter.** Utilisez l'adresse e-mail et le mot de passe fournis par
  votre administrateur. À la première connexion, un mot de passe peut vous être
  demandé de changer.
- **Votre profil.** Menu du compte → *Profil*. Renseignez votre nom, prénom,
  **téléphone**, **photo** et **langue d'interface** (français, anglais,
  espagnol, allemand, italien). Ces informations aident vos collègues à vous
  reconnaître (annuaire, discussions).
- **Sécurité.** Section *Sécurité* : changement de mot de passe et, si activée,
  **double authentification (2FA)**.
- **Notifications 🔔.** La **cloche** en haut à droite regroupe les actions qui vous
  concernent (surtout pour les administrateurs — ex. « canal à activer »). Chaque
  notification propose : **Afficher** (aller à la page concernée), **Épingler**
  (garder en tête), **Masquer**. Vous pouvez aussi recevoir un **rappel e-mail
  hebdomadaire** : *Profil → Rappel e-mail → Résumé hebdomadaire*.

## 2. Utiliser les applications

- **Parcourir.** L'**Cosmos** présente les applications disponibles (à la une,
  par catégorie, les mieux notées). Les applications **officielles** portent un
  badge.
- **Installer.** Ouvrez une application : un écran d'**autorisations** (façon
  smartphone) liste ce à quoi elle accède (stockage, fichiers, IA, canaux…).
  Validez pour l'ajouter à *Mes applications*.
- **Accueil & widgets.** Certaines applications proposent des **widgets** (tuiles)
  à épingler sur votre page d'accueil.
- **Suites.** Une **suite** regroupe plusieurs applications d'un même métier ;
  elle s'ouvre comme une application dédiée et peut s'installer en PWA sur votre
  appareil.

## 3. Services externes (Services API) — le cœur

Certaines applications ont besoin d'un **service externe** (envoi d'e-mails, IA
tierce, cartographie, base Supabase…). La **clé d'accès** à ce service est
saisie **une seule fois** et reste **sur le serveur** : elle n'est **jamais**
transmise à l'application (le « bac à sable »). L'application déclare seulement
un « besoin » ; la plateforme s'en occupe en sécurité.

Ouvrez *Services API*. Pour chaque service, l'**administrateur de l'organisation**
choisit un **mode** (bouton « Configurer ») parmi trois :

| Mode | Ce que ça veut dire | Quand le choisir |
|---|---|---|
| **Clé de la plateforme** | La plateforme fournit la clé et facture l'usage. | Le plus simple, rien à gérer. |
| **Une clé pour toute l'organisation** (BYOK) | Vous fournissez **une** clé, partagée par tous les membres ; vous gérez la facturation en direct. | Un seul compte fournisseur pour toute l'équipe. |
| **Chaque utilisateur fournit sa clé** | **Chaque membre** branche **sa propre** clé (voir §4). | Quand chacun a son propre compte chez le fournisseur. |

### Quand choisir « chaque utilisateur » ? — 3 cas concrets

- **Agence, chacun son Supabase.** Chaque consultant a son propre projet
  Supabase. L'admin règle le service `supabase` en « chaque utilisateur » ;
  chacun met sa clé. → mode **utilisateur**.
- **Service facturé par la plateforme (ex. IA).** On ne veut pas que des clés
  personnelles contournent la facturation : le super-admin **n'autorise pas les
  clés client** ; seul le mode **plateforme** est possible.
- **Plusieurs organisations, exigences différentes.** Une org veut des clés
  personnelles (Notion), une autre les interdit (conformité). Chaque **admin
  d'org** décide pour la sienne.

> **Qui autorise quoi ?** Le **super-admin de la plateforme** décide seulement si
> un service **accepte des clés fournies par le client** (barrière de sécurité et
> de facturation). Dès que c'est autorisé, c'est l'**admin de votre organisation**
> qui choisit le mode — y compris « chaque utilisateur ».

## 4. Ma clé personnelle (pas à pas)

Quand l'admin a réglé un service en **« chaque utilisateur fournit sa clé »**, ce
service apparaît dans *Services API → **Mes clés personnelles***.

1. Ouvrez *Services API*. Repérez le panneau **« 🔑 Mes clés personnelles »**.
2. En face du service voulu, cliquez **« Configurer »**.
3. Collez **votre** clé (obtenue chez le fournisseur : Supabase, Notion, OpenAI…),
   puis **Enregistrer**.
4. C'est fait : quand **vous** utilisez une application qui a besoin de ce service,
   c'est **votre** clé qui est employée.

**Sécurité — l'essentiel.** Votre clé est **chiffrée** et conservée **sur le
serveur**. Elle n'est **jamais** réaffichée, **jamais** transmise au bac à sable
de l'application, et **invisible** des autres membres — y compris des
administrateurs. Pour la remplacer : « Remplacer ». Pour la retirer : « Supprimer »
(effet immédiat).

## 5. Connecter un assistant IA (MCP)

Le **connecteur MCP** permet à un assistant IA (Claude) d'accéder, en votre nom et
dans votre périmètre, à la documentation à jour et aux outils de votre
organisation. C'est utile surtout pour **développer des applications**.

### Étape 0 — Créer un jeton
*Services API → « Jetons d'API »* → **« ＋ Nouveau jeton »**. Nommez-le, choisissez
sa portée (lecture / écriture), validez. **Copiez le jeton `art_…`** : il ne
s'affiche **qu'une seule fois**.

### Claude Code (CLI) — le plus simple
```
claude mcp add --transport http constellae https://VOTRE-DOMAINE/api/mcp \
  --header "Authorization: Bearer art_VOTRE_JETON"
claude mcp list      # doit afficher « connected »
```
`--scope user` pour tous vos projets ; `--scope project` pour le versionner dans
`.mcp.json`.

### Claude Desktop
Éditez `claude_desktop_config.json` :
```
{
  "mcpServers": {
    "constellae": {
      "type": "http",
      "url": "https://VOTRE-DOMAINE/api/mcp",
      "headers": { "Authorization": "Bearer art_VOTRE_JETON" }
    }
  }
}
```
Puis redémarrez Claude Desktop. (L'interface « Connecteurs » native ne gère que
l'OAuth : passez par ce fichier pour un jeton.)

### claude.ai (web)
claude.ai utilise **OAuth** (et non un jeton) — c'est **pris en charge et activé
par défaut** (un super-admin peut le désactiver dans les réglages plateforme).
Sur claude.ai, cliquez « Ajouter un connecteur personnalisé » et remplissez :

| Champ | Quoi mettre |
|---|---|
| **Nom** | Ce que vous voulez, ex. `Constellae` |
| **URL du serveur MCP distant** | `https://VOTRE-DOMAINE/api/mcp` |
| Paramètres avancés → **ID client OAuth** | *(laisser vide)* |
| Paramètres avancés → **Secret client OAuth** | *(laisser vide)* |

Puis **« Ajouter »**. claude.ai vous redirige vers Constellae : **connectez-vous**
puis cliquez **« Autoriser »**. Le connecteur passe en « Connecté ».

*Si claude.ai réclame malgré tout un ID/Secret :* votre super-admin peut en
générer un (*réglages plateforme → « Client OAuth pour claude.ai »*) — collez-y
l'URL de redirection affichée par claude.ai, puis reportez l'ID et le secret dans
les « Paramètres avancés ». Sinon, laissez ces champs vides.

### Ce que l'assistant voit — et ne voit pas
Une fois connecté, l'assistant accède **uniquement** à :
- la **documentation à jour** (Convention, ce manuel, catégories, registre des
  canaux, version) ;
- le **stockage PARTAGÉ** de votre organisation et les **canaux**.

Il **ne voit PAS** les **données privées** des applications. Exemple : si
l'application *Annuaire* enregistre ses clients en stockage **privé** (le défaut),
l'assistant **ne peut pas** les lister. Pour qu'une IA d'organisation y accède,
l'application doit écrire ces données dans un **canal partagé** (ou en stockage
partagé). Le jeton MCP est **au niveau de l'organisation** et ne porte pas
d'identité individuelle : il ne lit jamais les données privées d'un membre.

> **Connexion OAuth (claude.ai) = liée à VOTRE compte.** Contrairement au jeton
> `art_` d'organisation, la connexion OAuth authentifie l'utilisateur qui a
> cliqué « Autoriser ». L'assistant agit donc **en votre nom**, ce qui débloque
> les actions ci-dessous.

### Mettre à jour une application depuis Claude (super-admin & développeurs)
Si vous êtes **super-admin** ou possédez un **profil développeur**, la connexion
OAuth expose deux outils supplémentaires (portée **écriture** requise) :
- **`list_my_artifacts`** — liste **vos** applications, en deux ensembles
  **distincts** : `appstore` (fiches du catalogue dont **vous** êtes le
  développeur) et `personal` (vos Novas personnels).
- **`update_artifact`** — pousse une **nouvelle version** à partir du code
  source complet. Paramètres : `type` (`appstore` ou `personal`), `id`, `code`,
  et en option `versionLabel` (ex. `1.2.0`) et `note`.

Règles de sécurité :
- Vous ne mettez à jour que **vos propres** applications.
- **Cosmos** : un **super-admin** publie **directement** (aucune validation) ;
  un **développeur** voit sa mise à jour passer **« en attente de validation
  d'un administrateur de la plateforme »**.
- Un super-admin **ne peut pas** mettre à jour une application d'Cosmos qu'il
  n'a **pas** développée — **sauf** si le propriétaire a activé **« Déléguer la
  gestion »** sur sa fiche (dans *Mes dépôts*).
- **Novas personnels** : mis à jour par leur **seul propriétaire** (aucune
  délégation possible).

### Développer une Nova avec un LLM externe (paquet `.nova`)
Avec une connexion **OAuth**, l'assistant peut **transférer une Nova** entre le
**Nova Studio** et un LLM externe, en **conservant l'historique de conversation
et les visuels**. Deux outils :
- **`nova_export`** — renvoie **directement** (aucun fichier à manipuler) : le
  `code` (`.tsx`), la `conversation` (liste `{role, content}`), les `images`
  (liste `{id, name, mime, kind, dataBase64}`) et un **résumé fonctionnel**
  (`summary` : à quoi sert la Nova, ses fonctionnalités, données et capacités
  utilisées). Argument : `id` (l'identifiant d'un **brouillon** Nova Studio ou
  d'une **Nova personnelle** de `list_my_artifacts`). Le paquet `.nova` complet
  (`base64`) et `filename` restent fournis pour une reprise à l'identique.
- **`nova_import`** *(portée écriture)* — crée une Nova dans **votre** Nova Studio,
  en conservant l'historique et les images. Deux façons de faire :
  1. `code` — la **source** `.tsx/.jsx/.html`, avec en option `name`,
     `mode` (`guided`/`free`), `conversation` (échanges `{role:"user"|"assistant",
     content}`) et `images` (liste `{mime, dataBase64, name?, kind?, id?}` — les
     images renvoyées par `nova_export` se réutilisent telles quelles) ;
  2. `base64` — un **paquet `.nova`** complet (reprise à l'identique).
  La réponse renvoie `draftId` et un **résumé fonctionnel** de ce qui a été
  importé. La Nova apparaît alors dans **Nova Studio**, prête à tester et publier.

> **Cas d'usage.** « Reprends cette Nova, améliore-la, puis réimporte-la » : demandez
> à l'assistant `nova_export` — il reçoit **directement** le code, la conversation
> et les images —, faites-le travailler, puis `nova_import` (mêmes champs) pour tout
> retrouver dans le Studio. **Aucun fichier `.nova` à télécharger/téléverser.**
> À l'inverse, une Nova conçue avec un LLM externe s'importe de la même façon.

### Travailler sur « Mon Disque » depuis Claude
Avec une connexion **OAuth**, **tout utilisateur** peut faire agir l'assistant
sur son disque interne « Mon Disque » — pour lister, lire, analyser, résumer,
synthétiser et **modifier** des fichiers. Quatre outils :
- **`drive_list`** — liste le contenu. Sans argument : les racines `/Perso`
  (votre espace privé), `/Partagé` (dossiers partagés avec vous) et `/Entreprise`
  (si vous êtes administrateur). Ex. `path="/Perso/notes"`.
- **`drive_read`** — lit un fichier **texte** (pour l'analyser / le résumer).
- **`drive_write`** *(portée écriture)* — crée ou remplace un fichier texte, ex.
  `path="/Perso/notes/resume.md"`.
- **`drive_search`** — recherche par nom.

Règles : l'assistant agit **en votre nom**. Vous accédez à **votre** Perso ; aux
dossiers **Partagés** uniquement là où vous avez le droit (lecture pour lire,
écriture pour modifier) ; l'espace **Entreprise** reste réservé aux
administrateurs. **La suppression n'est pas proposée** pour l'instant. Un simple
jeton d'organisation (sans identité) **n'a pas** accès à ces outils.

### Interdire les assistants IA externes (conformité)
Un **administrateur d'organisation** peut, dans *Mon organisation*, décocher
**« Autoriser les connexions d'assistants IA externes (MCP / claude.ai) »**.
Les nouvelles connexions sont alors refusées et **les jetons déjà émis cessent
immédiatement d'être valables**. Utile si votre politique interdit toute IA
externe.

## 6. Jetons d'API

Un **jeton** connecte **vos** logiciels (ou un assistant via MCP) aux données de
votre organisation, de façon cloisonnée.
- **Créer / révoquer** : *Services API → Jetons d'API*. Un jeton = une
  organisation, une portée, révocable à tout moment. Il s'affiche **une seule
  fois**.
- **Documentation interactive** : bouton « 📖 Documentation API » (Swagger) pour
  tester les appels REST.
- **Exemple REST** :
  ```
  curl -H "Authorization: Bearer VOTRE_JETON" https://VOTRE-DOMAINE/api/ext/channels
  ```

### Appeler un agent IA depuis vos logiciels (API externe)

Vos agents (officiels **et** ceux de votre organisation) peuvent être appelés
depuis l'extérieur, avec la même sécurité que le reste de l'API.

1. **Exposer l'agent** : dans sa fiche (Agents IA → *Modifier*), cochez
   **« Exposer via l'API externe »**. Non coché = accessible uniquement dans l'app.
2. **Créer un jeton** : *Services API → Jetons d'API → Nouveau jeton*, en cochant
   le droit **« Agents IA »**. Copiez la valeur `art_…` (affichée **une seule fois**).
3. **Récupérer l'URL** : sur la carte de l'agent, cliquez **🔗 API** → l'URL et un
   exemple `curl` s'affichent (bouton « Copier »).
4. **Appeler** :
   ```
   curl -X POST https://VOTRE-DOMAINE/api/v1/agents/vega/messages \
     -H "Authorization: Bearer art_VOTRE_JETON" \
     -H "Content-Type: application/json" \
     -d '{"message": "Résume-moi la règle des congés payés"}'
   ```
   Réponse : `{ "agent": "@vega", "reply": "…", "activity": [ … ] }`.

**Bon à savoir** : appelez l'agent par son `/slug` **ou** un de ses alias. Champs
facultatifs : `history` (messages précédents) et `boost` (0–2, effort de réflexion).
Chaque appel est **indépendant** (sans état). Les actions d'**écriture** sont
refusées via l'API. Limite : **60 requêtes/minute** par jeton. Tout reste
**cloisonné** à l'organisation du jeton.

## 7. Canaux & webhooks

- **Canaux** : espaces d'échange partagés entre membres d'une organisation
  (données + fichiers), avec rôles Lecteur/Éditeur gérés par l'admin. Les
  applications s'en servent pour collaborer en temps réel.
- **Une application affiche « Accès refusé — vous n'êtes pas membre de ce
  canal » ?** Le canal partagé de l'application n'a pas encore été créé (cas
  fréquent quand l'application a été installée par un simple utilisateur, pas par
  un admin). **Côté administrateur** : une notification 🔔 « Canal à activer »
  apparaît (cloche en haut à droite) → **Afficher** → dans *Canaux*, encadré
  « ⚠️ Canaux attendus par vos applications » → **« Créer + ouvrir à tous »**.
  L'accès est alors débloqué.
  Astuce : pour éviter ce cas, faites **installer les applications à canal par un
  administrateur ou un manager** (les canaux sont alors créés et ouverts
  automatiquement).
- **Webhooks** : un service externe peut **envoyer** des messages/cartes dans un
  canal (approbations, notifications…). La configuration se fait avec votre
  administrateur.

## 8. Stocker des données

Vous n'avez rien à installer : les applications stockent leurs données pour vous
automatiquement (par utilisateur, ou partagé dans un canal selon l'application).
Les développeurs disposent pour cela de `window.storage` (clé/valeur) et, pour des
besoins avancés, d'une **base SQLite portable** (`window.db`) — tout reste dans
votre espace, sans accès à la base du site.

**Données communes à toute l'organisation.** Certaines applications ont besoin de
données partagées par tous les membres : une **base commune à l'org** (`window.db`
en mode partagé, avec protection contre les écrasements concurrents) ou un **espace
de service propre à l'application** (`window.vault`) que l'application gère seule et
que **vous ne voyez pas** dans « Mon Disque » — c'est volontaire : cela protège ces
données techniques contre les erreurs de manipulation et les fuites. Tout reste
strictement **cloisonné à votre organisation**.

**Réglages d'une application (org + perso).** Une application peut proposer deux
niveaux de configuration : des **réglages pour toute l'organisation** (ex. un SIRET,
une devise) et vos **préférences personnelles** (ex. thème, affichage). Vos
préférences ne concernent que vous ; les réglages « organisation » ne sont
modifiables que par un **administrateur** (voir §9).

## 9. Rôles & qui peut faire quoi

| Action | Membre | Admin d'org | Super-admin |
|---|---|---|---|
| Poser **sa** clé personnelle | ✅ (si le service est en mode « utilisateur ») | ✅ | ✅ |
| Créer un **jeton** / connecter le MCP | selon réglage | ✅ | ✅ |
| Choisir le **mode** d'un service (plateforme / org / utilisateur) | — | ✅ | ✅ |
| Modifier les **réglages « organisation »** d'une application | — (sauf admin délégué) | ✅ | ✅ |
| **Nommer un administrateur délégué** d'une application | — | ✅ | ✅ |
| Déclarer un **service** (URL) et autoriser les clés client | — | — | ✅ |

> **Administrateur délégué d'une application.** Un administrateur d'organisation
> peut confier à un membre les **droits d'administration d'une application précise**
> (bouton « Partager » de l'application → section « Administrateurs de la Nova »).
> Ce membre pourra alors régler la **configuration « organisation »** de cette
> application, **sans** être administrateur de toute l'organisation. La délégation
> vaut pour **cette application seulement** et reste révocable à tout moment.

> **Agents « basés sur » un agent de plateforme (admins d'org).** Dans le
> constructeur d'agents, un administrateur peut choisir un **agent de plateforme
> comme socle** : le nouvel agent d'organisation **hérite de son expertise**
> (savoir-faire, outils, connecteurs) et l'on y **ajoute** ses propres
> instructions, sa base de connaissances, ses connecteurs et ses sources. Un
> **nom** et un **avatar différents** sont obligatoires. Les instructions
> internes du socle restent **confidentielles** (jamais affichées à l'admin).

## 10. Constellation ✦ — orchestrateur no-code

**Constellation** est le module qui **relie tout l'écosystème** : vos
**Novas**, vos **agents IA** (plateforme, organisation, personnels) et vos
**services externes** (connecteurs), sous forme de **flux d'étapes** que vous
composez visuellement, à la souris, **sans écrire une ligne de code** (dans
l'esprit de n8n / Make).

**Installation.** Le module **✦ Constellation** s'installe depuis l'**Cosmos**
(comme l'application « Agents IA ») : ouvrez le Cosmos, section **Constellation**,
« Installer le module » (réservé aux administrateurs). Une fois installé, le
bouton **✦ Constellation** apparaît dans le menu, sous « Agents IA ».

**Afficher un agent dans le chat.** Sur une étape **Agent IA**, l'option
« Afficher la conversation dans le chat » fait apparaître l'échange (question +
réponse) dans l'application « Agents IA », lors d'une exécution manuelle.

### Composer un flux

1. **« + Nouveau flux »**, donnez-lui un nom.
2. Dans la **palette** (à gauche), **glissez une étape** sur le canevas (ou
   cliquez-la pour l'ajouter). Déplacez ensuite les étapes en les faisant glisser.
3. **Reliez** les étapes : tirez un trait depuis la **pastille de sortie** (à
   droite d'une étape) vers la **pastille d'entrée** (à gauche) de la suivante.
   Le résultat passe alors **automatiquement** d'une étape à l'autre — vous n'avez
   **rien à taper**. Pour **supprimer un lien**, cliquez dessus.
4. Cliquez une étape pour la **configurer** dans le panneau de droite.
5. **💾 Enregistrer**. Un flux est **personnel** ; un administrateur peut cocher
   **« Modèle d'org »** pour le partager comme modèle d'organisation.
6. **⬇️ Exporter / ⬆️ Importer** : sauvegardez un flux dans un **fichier JSON**
   (pour l'archiver ou le partager) et **réimportez-le** (il arrive comme un
   nouveau brouillon, à vérifier puis enregistrer). Exemple prêt à importer :
   `examples/workflow-demo-validation-chat.json` (validation d'une dépense).

**Demander une validation dans le chat (boutons).** Sur l'étape **✋ Demander une
validation**, cochez **« Poser la question dans le chat »**, choisissez un **canal**
(dont vous êtes membre), écrivez la **question** et les **boutons** (un par ligne,
couleur optionnelle : `Refuser | danger`). À l'exécution, une **carte à boutons**
apparaît dans le canal ; le **clic d'un membre reprend le flux** avec le choix. Il
faut qu'un **chat affichant les cartes interactives** soit installé et publie sur ce
canal. Ajoutez ensuite une étape **Condition (Si…)** sur `{{prev}}` pour aiguiller
selon la réponse (le résultat = l'identifiant du bouton, ex. `approuver`).

**Demander une validation par e-mail (liens sécurisés).** Sur la même étape,
cochez **« Par e-mail (liens sécurisés) »** — seul, ou **en plus** du chat.
Chaque **destinataire** (voir ci-dessous) reçoit un e-mail avec la question, les
réponses possibles et un **lien personnel** : il clique, une page affiche les
boutons, il répond — **même sans être connecté**, et le flux reprend. Le lien est
**signé** (impossible à falsifier) et **à usage unique** ; l'ouverture du lien
n'a aucun effet tant que la personne n'a pas **cliqué** sur un bouton (les
antivirus de messagerie qui « pré-ouvrent » les liens ne peuvent donc pas valider
à sa place). L'e-mail exige **au moins un destinataire désigné** (on ne peut pas
écrire « à tout le canal ») et que l'**envoi d'e-mails** soit configuré sur la
plateforme. Le mode *successif* fonctionne aussi par e-mail : le valideur suivant
reçoit son lien dès que le précédent a approuvé.

**Destinataires & plusieurs valideurs.** Sous « Qui peut valider ? », laissez vide
pour autoriser **tout membre** du canal (chat uniquement), ou **désignez une ou
plusieurs personnes** (pas forcément celle qui lance le flux ; **obligatoire pour
l'e-mail**). Avec des destinataires, choisissez le
**mode** : *« Un seul valideur suffit »* (la première réponse décide) ou *« Tous
doivent valider (successivement) »* — chaque personne valide **à son tour**, reçoit
une **notification** (et/ou un **e-mail**) quand c'est le sien, et le flux ne
continue que lorsque **tous** ont approuvé (le **premier bouton** = « approuver » ;
tout autre bouton arrête la chaîne, ex. « Refuser »).

### Les types d'étapes

- **▶ Déclencheur** — le point de départ manuel. La donnée saisie au lancement
  est disponible partout via le jeton `{{input}}`.
- **⏰ Programmé** — lance le flux **automatiquement** à intervalle régulier
  (toutes les N minutes) ou **chaque jour à une heure** donnée.
- **🌐 Webhook** — lance le flux quand une **requête HTTP (POST)** arrive sur une
  **URL secrète** propre au flux ; le corps de la requête devient `{{input}}`.
- **🤖 Agent IA** — fait travailler un de vos agents (plateforme / org / perso)
  avec une instruction ; sa réponse devient la sortie de l'étape.
- **🔌 Appeler un service (API / webhook)** — envoie ou lit des données auprès
  d'un **service externe** enregistré (c'est ainsi qu'un flux **écrit vers un
  webhook** ou une API) ; seuls les services autorisés pour votre organisation
  sont proposés.
- **🔔 Afficher une notification** — affiche le résultat à l'écran (pop-up). Une
  façon simple de **voir** ce qu'a produit une étape.
- **▦ Nova** — passe la main à un de vos Novas. Comme une Nova
  s'exécute dans son **bac à sable** (le navigateur), vous l'ouvrez à
  l'exécution, réalisez l'action, puis **reportez son résultat** pour continuer.
- **✋ Validation** — met le flux **en pause** : rien ne continue tant que vous
  n'avez pas **Approuvé** (ou **Refusé**).
- **⚙ Transformer** — met en forme une donnée sans code (gabarit de texte).
- **⑃ Condition** — teste une valeur et propose **deux sorties**, **Vrai** (verte)
  et **Faux** (rouge). Opérateurs : *contient, égal, différent, commence par,
  finit par, dans la liste, correspond à (regex), entre (min,max), est un nombre,
  >, <, vide, non vide*. Vous pouvez **cumuler plusieurs critères** combinés par
  **ET** (tous) ou **OU** (au moins un).
- **⑂ Aiguillage** — plusieurs **cas** → **plusieurs sorties** (une par cas + une
  sortie « Sinon »). Idéal après une validation : un cas *Approuver*, un cas
  *Refuser*, chacun relié à sa suite. La valeur testée est comparée sans tenir
  compte de la casse (souvent `{{prev}}`).
- **🔁 Boucle** — **pour chaque** élément d'une liste (un tableau, ou une valeur
  multi-lignes), exécute un traitement (un gabarit **ou** un agent) ; l'élément
  courant est disponible via `{{item}}`. Les résultats sont concaténés
  (limité à 20 éléments).
- **🔄 Répéter tant que…** — répète un traitement **tant que** des critères
  restent vrais (mêmes opérateurs et combinaison ET/OU que la Condition).
  À chaque tour, `{{prev}}` (= `{{item}}`) vaut le résultat du tour précédent, et
  le traitement (gabarit **ou** agent) produit le résultat suivant. Boucle
  **bornée** : elle s'arrête dès que la condition devient fausse, après le
  **nombre de tours maximum** que vous fixez (1 à 20), ou par sécurité de temps.
  La sortie de l'étape = le **dernier** résultat.

**Le résultat circule tout seul.** Reliez deux étapes et la sortie de la
première alimente **automatiquement** la seconde — rien à écrire. Dans la
configuration, un bandeau vert rappelle « ➡️ Reçoit automatiquement le résultat
de : … ». Laissez le champ **vide** pour transmettre ce résultat tel quel.

**Combiner plusieurs sources (avancé).** Pour composer un texte à partir de
plusieurs étapes, utilisez les **boutons « Insérer une donnée »** sous le champ :
*Entrée du flux*, *Sortie précédente*, ou une étape amont **par son nom**. Aucune
syntaxe à mémoriser.

**Une sortie peut déclencher une action.** La sortie d'une étape peut être
envoyée vers :

- un **Agent IA** — pour la traiter (y compris **Voilà**, l'assistant général) ;
- **Appeler un service (API / webhook)** — écrire vers une API ou un webhook ;
- **Ouvrir une Nova** — passer la main à une Nova ;
- **Notifier** — au choix : **toast** (bulle), **pop-up** (fenêtre) ou **centre de
  notifications** ;
- **Envoyer un e-mail** — à un destinataire, avec objet et message ;
- **Déclencher un workflow** — lancer un autre flux (chaînage), ou **↻ ce même
  flux** pour **reboucler** (ex. sur la branche « Refusé » d'une validation, on
  relance le flux depuis le début), avec un **nombre maximum de relances** pour
  éviter toute boucle infinie.

> **Déclencher un flux depuis une Nova.** Une Nova peut aussi **démarrer**
> un flux automatiquement (ex. « un document est déposé dans un dossier → envoyer
> un e-mail avec la pièce jointe ») : cela passe par l'**étape Webhook** du flux
> et le mécanisme décrit dans la Convention développeur (champ `constellation`).

### Exécuter et suivre

- **▶ Tester** lance le flux. L'exécution se déroule **étape par étape**, et son
  **avancement s'affiche en direct** (étape en cours, réussie, en erreur, en
  attente). L'**état est conservé côté serveur** : vous pouvez **fermer l'onglet
  et reprendre** plus tard.
- Cloisonnement : un flux n'exécute **que** des agents, connecteurs et Novas
  **accessibles à votre organisation**.

### Automatiser (sans onglet ouvert)

Deux étapes permettent de **déclencher un flux automatiquement** :

- **⏰ Programmé** : ajoutez le nœud, choisissez l'intervalle (minutes) ou l'heure
  quotidienne, puis **enregistrez**. Le flux se lancera tout seul.
- **🌐 Webhook** : ajoutez le nœud, **enregistrez** pour obtenir une **URL secrète**,
  puis faites appeler cette URL (POST) par votre outil externe. Le corps de la
  requête est disponible via `{{input}}`.

Vous n'avez **rien à installer** : ces déclenchements s'exécutent **côté serveur,
automatiquement, dès que l'application est utilisée** (le webhook, lui, part
immédiatement à l'appel HTTP). Pour qu'un flux **programmé** parte à l'heure dite
**même si personne n'ouvre l'application**, un administrateur peut ajouter une
**tâche planifiée** (facultatif — voir le manuel technique / `cron/README.md`).

### Déclencher un flux à distance par URL (clés sécurisées)

Pour lancer un flux depuis **n'importe quel outil externe** (Zapier, Make, un cron,
un bouton, un autre logiciel), ouvrez le flux et cliquez sur **🔗 Déclencheurs**
(barre du haut du constructeur). Vous pouvez y **créer une clé** :

1. Donnez-lui un **nom** (ex. « Zapier — nouveau client »).
2. À la création, l'application affiche **une seule fois** l'**URL** et la **clé
   secrète** — copiez-les tout de suite (le secret ne sera plus jamais réaffiché).
3. Dans votre outil, faites un appel **POST** sur l'URL, avec l'en-tête
   `Authorization: Bearer <votre clé secrète>`. Le **corps** de la requête devient
   l'**entrée** du flux (`{{input}}`). Un **exemple `curl`** prêt à copier est fourni.

**Sécurité (pour éviter tout déclenchement malveillant)** : la clé ne déclenche
**que ce flux** ; le secret n'est stocké que **haché** (jamais en clair) ; vous
pouvez **renouveler** le secret ou **révoquer** la clé à tout moment (effet
immédiat) ; le débit est **limité** et chaque appel est **journalisé** (nombre
d'appels, dernière utilisation). Seul un **administrateur** ou le **créateur du
flux** peut gérer ces clés.

Pour les intégrations les plus sensibles, cochez **« Exiger une signature HMAC »** :
chaque appel doit alors être **signé** (horodatage + signature + numéro unique
anti-rejeu) — impossible de rejouer ou d'altérer une requête. L'exemple `curl`
montre comment calculer la signature.

En mode automatique : une étape **Validation** met le flux en pause jusqu'à ce que
quelqu'un l'approuve depuis l'interface, et une étape **Nova** est ignorée
(une Nova a besoin d'un navigateur).

> **Bon à savoir.** Une Nova ne peut pas s'exécuter tout seul en arrière-plan
> (il a besoin de son bac à sable) : l'étape « Nova » vous fait donc
> intervenir. Les autres étapes (agent, connecteur, condition, boucle,
> transformation, validation) s'enchaînent automatiquement.

## 11. Nova Studio ★ — créer ses propres applications

Le **Nova Studio** est une **Super Nova** (grand module natif) qui permet de créer
une Nova (application) **en langage naturel**, sans coder. Il vise surtout les
utilisateurs non-développeurs — les développeurs, eux, préfèrent souvent un assistant
externe (Claude Code + MCP, cf. §5).

**Installation.** Ouvrez le **Cosmos** : la carte **★ Nova Studio** (badge « Super
Nova ») s'installe en un clic, comme les autres Super Novas (Agents, Constellation).
Une fois installé, il apparaît dans le menu.

**Créer une Nova.** À l'ouverture, trois entrées :
- **Mode guidé** — accompagné pas à pas (recommandé pour débuter).
- **Mode libre** — vous décrivez directement votre Nova dans le chat.
- **Mon atelier** — vos Novas créées, leur historique et leurs versions.

Dans le studio, la **conversation** est à gauche, l'**aperçu en direct** à droite. Vous
décrivez votre application, l'IA l'écrit, vous la voyez aussitôt, puis vous l'affinez
en discutant (« ajoute un bouton export », « change les couleurs »…). Boutons **Aperçu /
Code** et **mobile / bureau**. La case **Qualité max** utilise le modèle le plus
performant (plus lent).

**Vos visuels d'abord.** Le Nova Studio **ne génère pas d'images**. Déposez vos logos et
icônes dans l'encart « Vos visuels » : l'IA les réutilisera (elle n'en invente aucune).

**Enregistrer & versions.** **Enregistrer dans Ma Galaxie** crée (ou met à jour) votre
Nova ; chaque enregistrement crée une **version**. Dans **Mon atelier**, le bouton
**Versions** liste l'historique et permet de **restaurer** une version antérieure.

**Publier sur le Cosmos.** Si vous êtes développeur, un bouton **Publier sur le Cosmos**
propose la Nova au magasin : elle passe par la validation habituelle (analyse de sécurité
incluse) avant publication. La Nova reste dans votre Galaxie.

**Convention à jour.** Les règles de fabrication d'une Nova (la « Convention ») évoluent
parfois. Si une Nova a été construite sous une version plus ancienne, un **bandeau** vous
le signale et propose de la **mettre à jour** en un clic ; les générations suivantes
tiennent déjà compte des nouvelles règles.

## 12. Halos 🌟 — enrichir vos Novas (compléments)

Un **Halo** est un **complément** qui enrichit une Nova : un thème, un jeu de données,
un gabarit, ou le déverrouillage d'une fonction premium.

**Où ?** Dans le **Cosmos**, rayon **« 🌟 Halos »**. Chaque Halo indique son type et son prix
(pour l'instant, les exemples sont **gratuits**). Une Nova qui sait exploiter des Halos les
affiche aussi directement sur **sa fiche** (section **« Compléments »**) : vous pouvez les
acquérir depuis la fiche, au moment de découvrir la Nova.

**Acquérir.** Un **administrateur** clique **« Acquérir »** : le Halo devient disponible pour
**toute l'organisation** (licence par organisation). Le bouton passe à **« ✓ Acquis »** ; un
bouton **« Retirer »** permet de revenir en arrière.

**Comment une Nova l'utilise.** Une Nova prévue pour un Halo s'y adapte automatiquement :
elle **déverrouille** une fonction si l'organisation possède le Halo, ou **charge** son contenu
(par exemple une palette de couleurs). Sans le Halo, la Nova reste utilisable (fonction
verrouillée, apparence par défaut).

**Tester.** Deux Halos gratuits d'exemple sont fournis (« Démo — Fonctionnalité Premium » et
« Thème — Aurora ») avec une Nova de démonstration (`examples/halo-demo.tsx`). Acquérez-les
dans le Cosmos, ouvrez la Nova de démo et cliquez « Actualiser » : la fonction se déverrouille
et le thème s'applique. (Pas à pas : `examples/README-TEST-HALOS.md`.)

**Contenu injecté dans les modules.** Certains Halos ajoutent du **contenu** directement dans
les modules natifs, une fois acquis :
- **Constellation** — des **modèles de flux** prêts à l'emploi apparaissent en haut de la liste
  (« 🌟 Modèles ») ; « Utiliser » ouvre un nouveau flux pré-câblé.
- **Nova Studio** — des **modèles de départ** (« 🌟 Démarrer d'un modèle ») sur l'écran
  d'accueil, et des **packs d'icônes** dans l'encart « Vos visuels » (cliquez une icône pour
  l'ajouter à votre Nova).

> Cloisonnement : les droits sont **par organisation** ; une autre organisation ne voit jamais
> vos Halos, et le contenu d'un Halo n'est accessible qu'aux organisations détentrices.

## 13. Dépannage

- **« Vous devez configurer votre clé personnelle… »** : le service est en mode
  « chaque utilisateur » mais vous n'avez pas encore posé votre clé → *Services API
  → Mes clés personnelles* (§4).
- **Je ne vois pas « Mes clés personnelles »** pour un service : l'admin de votre
  organisation ne l'a pas (encore) réglé en mode « chaque utilisateur ».
- **Mon assistant IA ne se connecte pas au MCP** : vérifiez l'URL
  `https://VOTRE-DOMAINE/api/mcp` et l'en-tête `Authorization: Bearer art_…`.
  Ouvrir l'URL dans un navigateur renvoie volontairement une erreur « 405 » :
  c'est normal (le MCP fonctionne en POST, pas en GET).
- **Ma clé ne marche pas** : en mode « ma clé » (org ou perso), une clé invalide
  ou épuisée fait échouer les appels ; la facturation est gérée directement avec
  le fournisseur. Vérifiez/renouvelez la clé chez celui-ci, puis remplacez-la.
- **claude.ai (web) me demande un « ID / Secret client OAuth »** : c'est normal —
  claude.ai web n'accepte que l'OAuth, or notre MCP utilise un **jeton**. Il n'y a
  pas de champ pour le jeton : la connexion ne marchera pas ici. **Utilisez Claude
  Code ou Claude Desktop.**
- **L'assistant ne voit pas les données de mon application** : le MCP ne lit que
  le stockage **partagé** et les **canaux** de l'organisation, pas les données
  privées d'une application. Demandez au développeur de l'application d'écrire les
  données à exposer dans un **canal partagé** (voir §5).