Le manuel
d'atelier.

La plupart des outils d'IA sont des faiseurs : ils courent vers une réponse unique, puis vous demandent de la publier. C'est la mauvaise forme pour les minutes les plus dures du travail de fond - cadrer une question ambiguë, choisir entre deux directions plausibles, éprouver un plan avant de s'engager, réconcilier des avis d'experts contradictoires. Ces minutes ne sont pas limitées par le débit ; elles sont limitées par le jugement.

Armance est construite pour ces minutes-là. Elle n'écrit pas votre code, n'envoie pas vos courriers, ne pousse rien nulle part. Elle réunit plusieurs perspectives compétentes, les fait se contredire utilement, et vous remet une note que vous saurez défendre. La décision - et le geste - restent à vous.

La métaphore n'est pas décorative : Armance modélise une maison de conseil miniature, dont vous êtes la direction. Chaque agent permanent y tient un contrat étroit et vérifiable - c'est cette étroitesse qui rend le système lisible, testable, et digne de confiance. Cinq membres du personnel se partagent la maison ; aucun ne se recrute lui-même.

Les cinq invariants

Toute fonctionnalité, présente ou à venir, est jugée contre cinq règles non négociables :

1. Le système de fichiers est la source de vérité. Le dossier .armance/ est le système. Aucune base de données ne porte l'état principal ; le SQLite de la recherche sémantique ne sert qu'au rappel.
2. Markdown est l'interface entre humains et agents. Agents, notes, contextes, conversations - tout est lisible, comparable, versionnable avec les outils que vous avez déjà.
3. Le désaccord est une fonctionnalité. Serge existe parce que le consensus est un bogue. Malik choisit des personas qui s'opposent ; Kim fait délibérer en parallèle.
4. Local d'abord. Une installation sur un portable, sans serveur, doit fonctionner. L'interface web n'est qu'une autre porte sur la même maison.
5. Aucun effet de bord autonome. Armance n'envoie jamais de courrier, n'ouvre jamais de pull-request, ne modifie jamais votre code. Elle écrit dans ses propres dossiers ; vous restez les mains.

Tout, dans Armance, se demande en langage naturel - « Malik, recrute deux historiennes » suffit. Les commandes à barre oblique (/save, /workflow run…) existent, mais ce sont des alias. Voici le chemin exact d'un tour de parole :

Armance est l'hôtesse : c'est elle qui vous accueille à l'ouverture, elle qui pose les questions de cadrage - quel public, quelle contrainte, quel horizon - et elle qui tient la mémoire du projet. Sa règle de conduite est stricte : quand un détail lui manque, elle vous le demande ; elle ne comble jamais un blanc par une invention.

La bibliothèque : indexer ou charger

Vos documents (PDF, DOCX, Markdown, texte) se déposent dans .armance/docs/. Armance en propose alors deux lectures distinctes :

• Indexer — le document est découpé en feuillets, chaque feuillet reçoit une empreinte sémantique (embedding), et l'ensemble rejoint l'index local. Lors des délibérations, seuls les passages réellement pertinents pour la question remontent dans le contexte des agents - c'est la recherche sémantique (RAG). Un modèle de reclassement optionnel peut raffiner ce tri en deux étapes : large rappel vectoriel, puis re-tri fin.
• Charger — le texte intégral du document est injecté tel quel au tour suivant, pour une lecture de bout en bout. Utile quand le document entier compte : un brief, un contrat, un texte que le panel doit avoir lu en totalité.

L'index vit dans .armance/vector/ (une base sqlite-vec accompagnée d'un manifeste listant ce qui est indexé). Retirer un document de l'index est aussi simple que l'y mettre - et rien de tout cela ne quitte votre machine.

Le cache de contexte : la mémoire qui se tisse

Pendant que vous dialoguez, Armance tient un cache de contexte : un fichier (context/cache.md) où elle note, au fil de l'eau, ce qui mérite d'être retenu - une contrainte que vous venez d'énoncer, un choix arrêté, une nuance qui déplace le projet. Quand ce cache devient substantiel (au-delà d'environ 1 500 caractères), elle vous propose de geler.

Geler (/save, ou simplement accepter sa proposition), c'est compiler le cache et le brief précédent en une nouvelle version du brief de projet - le contexte L0. Chaque gel crée un fichier daté et numéroté (context/L0/v<N>_<date>_<titre>.md) ; rien n'est écrasé, l'historique de votre pensée reste consultable version par version. Et si vous quittez brusquement (Ctrl+C deux fois), Armance propose un gel rapide du tampon en cours, sans appel au modèle - pour ne rien perdre.

Trois couches de contexte

La mémoire du projet est étagée, pour que chaque agent reçoive juste ce qu'il lui faut :

L0

Le brief de projet - partagé par toute la maison. C'est le sol commun : objectif, contraintes, décisions actées.

L1

Le contexte de rôle - ce qu'un profil donné doit savoir en plus (le juriste ne lit pas les mêmes annexes que la designeuse).

L2

Le contexte de thème - un dossier transverse (un marché, une œuvre, un précédent) mobilisable par étape d'atelier.

Toutes ces couches sont des fichiers Markdown versionnés dans .armance/context/, tenus par un manifeste. Lors d'un atelier, chaque spécialiste reçoit L0, plus le L1 de son rôle, plus le L2 de son étape, plus les passages pertinents de la bibliothèque - et rien d'autre. C'est ainsi que la maison reste économe : on ne fait pas relire tout le dossier à tout le monde à chaque tour.

Quand le brief est posé, Malik lit et propose des rôles : de quels regards ce projet a-t-il besoin - une urbaniste, un économiste rural, une historienne de l'art ? Puis, pour chaque rôle, il fait une chose que les autres outils ne font pas : il recrute des personas qui s'opposent le long d'un axe signifiant pour le rôle. Positiviste contre révisionniste chez les historiennes ; croissance contre image de marque chez les marketeurs ; livrer-vite contre rigoriste chez les ingénieures. Le frottement n'est pas un accident - il est calibré.

Des personas incarnées

Chaque spécialiste reçoit une fiche d'environ deux cents mots : une trajectoire, une manière de parler, des convictions - et des refus. Les prénoms sont puisés dans un vivier international ; deux personas trop semblables sur le même axe sont détectées et régénérées. Ce soin n'est pas cosmétique : une persona riche et située produit des arguments plus francs, plus divergents, plus utiles qu'un « expert » générique.

Le choix des modèles

Avant d'embaucher, Malik présente son plan : pour chaque agent, le fournisseur et le modèle qui l'animeront. Vous pouvez ajuster chaque ligne. Par défaut, il respecte votre réglage de budget - en mode free-first, il privilégie les modèles effectivement gratuits (les modèles :free d'OpenRouter, l'abonnement Claude). Les modèles disponibles sont découverts en direct auprès de chaque fournisseur - prix, fenêtre de contexte, capacité de raisonnement - jamais tirés d'un catalogue figé. Et la maison veille à la diversité des familles : faire critiquer un texte par le modèle qui l'a écrit, c'est demander à un auteur de se relire avec complaisance (voir chapitre VII).

L'embauche est un fichier

Quand vous validez, Malik émet [EXECUTE:/recruit] et chaque spécialiste devient un fichier : .armance/agents/<Prénom>.md, avec un en-tête YAML (rôle, fournisseur, modèle) et son prompt de persona en corps. Vous pouvez l'ouvrir, le corriger, le versionner. Congédier un agent ne détruit rien : sa fiche part aux archives (.archive/), d'où elle peut revenir. Les cinq membres du personnel, eux, sont permanents - system-*.md - et ne se recrutent jamais eux-mêmes.

Kim ne donne jamais d'avis sur le fond. Elle conçoit et conduit les ateliers - les workflows : qui parle, dans quel ordre, en parallèle ou en série, et où la délibération doit s'arrêter pour vous attendre. Sa méthode de conception tient en quatre temps, toujours les mêmes :

Deux modes opératoires

Chaque atelier se lance dans l'un de deux modes, et cette distinction gouverne tout ce que vous pouvez attendre du résultat :

Des exécutions versionnées

Chaque exécution crée son propre dossier - .armance/exports/<atelier>/run-<horodatage>/ - contenant la sortie brute de chaque étape, la synthèse, la trace de délibération et un manifeste (statut, jetons et durée par étape). Rien n'est jamais écrasé : un index recense toutes les exécutions passées, et vous pouvez en faire comparer deux par Mona pour voir ce qui a changé entre deux versions de votre pensée.

Quand le panel a délibéré, Mona lit l'ensemble - c'est la seule de la maison à voir le contenu de bout en bout. Elle aligne les convergences, nomme les frictions, verbalise les non-dits, et rédige la note que vous emporterez. Mais sa vraie singularité est ailleurs : elle vous rend le processus, pas seulement le résultat.

Le registre des arguments

Chaque exécution produit, à côté de la synthèse, un registre des arguments : ceux que le panel a retenus et ceux qu'il a rejetés - avec, pour chacun, qui l'a proposé, qui l'a rejeté, pourquoi, et la source sur laquelle il s'appuyait. L'interface web le rend en deux colonnes ; les arguments rejetés restent visibles, barrés, avec leur motif de rejet. Une synthèse dont on peut inspecter les déchets est une synthèse qu'on peut croire.

S'y ajoute la trace lisible de la délibération : quels arguments ont tenu, lesquels ont été abandonnés, lesquels ont été adoptés d'un pair, quelles objections Serge a levées et comment elles ont été traitées. Le tout en fichiers ordinaires (arguments.json, sources.json, trace.md) dans le dossier de l'exécution.

Les livrables

La note finale s'exporte d'une commande - Markdown, DOCX, PPTX, et PDF si l'option est installée - vers .armance/exports/. Mona peut aussi verser une de ses notes à la bibliothèque, où elle redevient un document comme un autre : indexable, opposable, réutilisable dans le projet suivant. Ainsi la maison apprend d'elle-même - par fichiers, jamais par magie.

Serge entre quand la synthèse est écrite - jamais avant. Son mandat est étroit et sans appel : chercher la faille honnête. L'hypothèse non examinée, l'argument tabou, l'angle mort que la synthèse a lissé. Sa critique suit un format fixe en quatre blocs - ce qui tient, ce qui casse, les contre-exemples, ce qu'il faudrait vérifier - pour que sa sévérité soit exploitable, pas seulement spectaculaire.

Une autre famille de modèles - par construction

C'est la contrainte dure du personnage : Serge tourne sur une famille de modèles délibérément différente de celle qui a produit la synthèse. Un modèle qui relit sa propre prose retrouve ses propres plis - mêmes angles morts, mêmes complaisances. Avant chaque atelier, la maison vérifie cette diversité et vous avertit si votre configuration ne peut pas la garantir (un seul fournisseur configuré, par exemple). L'avertissement ne bloque jamais : l'atelier reste votre choix.

L'auto-invocation sur consensus

Un filet de sécurité veille après chaque exécution : si le panel a convergé trop docilement - pas de vraie contradiction, pas d'objection substantielle - Serge est convoqué d'office, même si l'atelier ne le prévoyait pas. Ses objections sont consignées au registre, et la synthèse doit y répondre. Une idée qui survit à Serge est une idée que vous pouvez signer.

Il n'y a pas de nuage Armance, pas de compte, pas de base de données cachée. Un projet Armance est un dossier .armance/ à la racine de votre projet - et ce dossier est le système. Le voici, annoté :

.armance/
  docs/               vos documents (PDF, DOCX, MD, TXT)
  vector/             index sémantique local (sqlite-vec) + manifeste
  agents/
    system-*.md         le personnel permanent (Armance, Malik, Kim, Mona, Serge)
    <Prénom>.md         les spécialistes recrutés par Malik
  workflows/          les ateliers conçus avec Kim (YAML, un graphe par fichier)
  context/            la mémoire étagée : cache.md + L0 / L1 / L2 versionnés
  reports/            notes d'agents versionnées
  sessions/<id>/      état, grand livre des jetons, conversation.md
  exports/<atelier>/  une exécution = un dossier run-<horodatage>, jamais écrasé
  config.yaml         réglages non secrets (fournisseurs, modèle, langue, budget)
  .env                clés d'API - jamais versionné

Markdown est la source de vérité ; le seul SQLite de la maison sert au rappel vectoriel, et il se reconstruit à volonté depuis vos documents. Conséquences pratiques : vous pouvez sauvegarder un projet en copiant un dossier, le versionner avec git, lire chaque décision dans un éditeur de texte, et quitter Armance sans rien perdre - les fichiers restent.

Les fournisseurs de modèles

La maison parle à quatre fournisseurs, au choix (et en mélange) : OpenRouter (le départ le plus simple - son palier gratuit fait tourner Armance de bout en bout), Claude via un abonnement Pro/Max (aucune clé d'API requise), Gemini, et tout point d'accès compatible OpenAI - y compris un Ollama local, auquel cas plus rien ne quitte votre machine, pas même les appels aux modèles. Les catalogues sont découverts en direct auprès de chaque fournisseur : prix, fenêtres de contexte, capacités. Le garde-fou budgétaire (budget_effort, plafond en euros par session) s'applique à tous.

Les sessions

Chaque séance de travail vit dans sessions/<id>/ : l'état courant, la conversation en Markdown, et le grand livre - jetons, coût, empreinte, agent par agent. À la relance, Armance retrouve la séance précédente et propose de la reprendre. Deux portes ouvrent sur la même maison : le terminal (armance run) et le navigateur (armance web - un seul processus local qui sert l'API et l'interface). Les fichiers écrits sont les mêmes des deux côtés.

Quatre couches, une règle

Le logiciel lui-même est étagé en quatre couches - client (terminal, web), transport (messages), service (orchestration, agents, ateliers), cœur (modèles purs, sans entrées-sorties) - et une règle d'architecture unique : chaque couche n'importe que celles d'en dessous, ce qu'un outil de vérification fait respecter à chaque contribution. C'est ce qui permet d'ajouter une porte (le web) sans toucher aux murs. Le tout est publié sous licence AGPL-3.0 : quiconque exploite une version modifiée d'Armance en service réseau doit en publier les modifications.

Une délibération consomme de l'électricité, émet du carbone, évapore de l'eau - même quand le calcul se passe sur un serveur que vous ne verrez jamais. Armance affiche ce coût en direct, à côté des jetons et des euros, dans le terminal comme dans le navigateur :

Comment le calcul fonctionne

L'estimation repose sur EcoLogits, le modèle ouvert de l'association GenAI Impact - une analyse de cycle de vie au sens de la norme ISO 14044. Le calcul se fait entièrement hors ligne, sur votre machine : mesurer l'empreinte ne crée aucun trafic supplémentaire. Pour chaque réponse :

1. La phase d'usage. L'énergie GPU est déduite du nombre de jetons générés et de la latence observée, selon l'architecture supposée du modèle, puis multipliée par le PUE du centre de données - le coefficient qui couvre le refroidissement et les pertes autour des serveurs.
2. La phase de fabrication. Fabriquer les serveurs et les puces a coûté avant le premier calcul. Cet impact « embarqué » est amorti sur la durée de vie du matériel, et la part de votre requête s'y ajoute.
3. La conversion. L'énergie devient des grammes de CO₂e via l'intensité carbone du réseau électrique de la zone d'hébergement, et des millilitres d'eau via le WUE (water usage effectiveness) de l'installation.

Quand le modèle exact n'est pas public (paramètres inconnus, architecture supposée), Armance affiche une fourchette honnête, marquée d'un ~ - jamais un faux chiffre précis. Une note « Méthode », à un clic, dit d'où vient chaque nombre.

À l'échelle humaine, et dans la durée

Des grammes de CO₂e ne parlent à personne. Armance les traduit en équivalents sourcés à la Base Carbone de l'ADEME - charges de téléphone, kilomètres en voiture - jamais bricolés. Et chaque échange est journalisé avec son empreinte : des vues récapitulent le coût par jour, par mois, par séance, par agent - pour voir où va réellement l'énergie de votre pensée.

La sobriété comme réglage

Le réglage budget_effort: optimised classe les modèles candidats par carbone croissant : à qualité comparable, la maison préfère le plus sobre. La sobriété devient un paramètre par défaut, pas un vœu pieux.

Deux prérequis, pas davantage : Python ≥ 3.11, et la clé d'un fournisseur de modèles - OpenRouter est le départ le plus simple, son palier gratuit fait tourner Armance de bout en bout sans dépense. Ensuite, une commande :

pip install armance          l'installation de référence (PyPI)
pipx install armance         variante isolée - identique à l'usage
uv tool install armance      idem, pour qui a uv

L'installation de base contient tout : le terminal (TUI), l'interface web, la recherche sémantique, les quatre fournisseurs, les exports Markdown, DOCX et PPTX, et la mesure d'empreinte. La seule option est l'export PDF (pip install 'armance[pdf]'), car il dépend de bibliothèques natives que pip ne sait pas installer ; sans elles, Armance saute le PDF avec un message clair - elle ne plante jamais.

Le site propose aussi un script d'amorçage (curl -fsSL https://armance.io/install.sh | sh sous Linux et macOS, un équivalent PowerShell sous Windows). Il ne fait rien d'occulte : il vérifie Python, installe pipx au besoin, installe Armance depuis PyPI, et pose un raccourci d'application - le tout dans votre compte utilisateur, sans droits administrateur.

Le premier projet

mkdir mon-projet && cd mon-projet
armance init                 dialogue guidé - voir ci-dessous
armance run                  ouvre le terminal (TUI)
armance web                  ou la même maison, dans le navigateur

armance init pose ses questions une à une : les fournisseurs à activer (multi-choix), leurs clés d'API (rangées dans .armance/.env, jamais versionnées), le modèle par défaut, l'effort budgétaire, la langue de la maison (détectée depuis votre système, tous les agents la parleront), le modèle d'empreintes sémantiques pour la bibliothèque (passable, configurable plus tard), et la zone électrique pour l'estimation carbone (par exemple FRA). Déposez ensuite vos documents dans .armance/docs/, et la maison vous attend.

Deux commandes de bon voisinage : armance doctor ausculte l'installation (configuration, joignabilité des fournisseurs, index sémantique, chaîne d'exports, grand livre) et dit ce qui manque ; armance web sert l'API et l'interface dans un seul processus local (http://127.0.0.1:8000), passe en arrière-plan, et s'arrête d'un armance stop - depuis n'importe quel dossier. Il n'y a qu'un serveur pour tous vos projets : le navigateur ouvre un lanceur, et vous choisissez le projet.

Toute la configuration tient en deux fichiers créés par armance init : .armance/config.yaml pour les réglages non secrets, .armance/.env pour les clés d'API. Les deux s'éditent à la main ; un changement prend effet à la prochaine session. Une variable posée dans votre shell l'emporte sur la valeur du .env.

config.yaml

.env

Trois niveaux de réglage

Le même paramètre se règle à trois altitudes, de la plus durable à la plus volatile : le fichier (config.yaml - vaut pour le projet), la fiche d'agent (l'en-tête YAML de agents/<Nom>.md - un fournisseur et un modèle propres à cet agent, c'est ainsi que Serge tourne sur une autre famille), et la séance (/model et /effort changent le modèle et l'effort de raisonnement sans rien écrire). En cas de conflit, le plus proche du moment gagne.

Tout se demande d'abord en langage naturel - « Malik, recrute deux historiennes », « indexe le rapport », « exporte en DOCX ». Les commandes ci-dessous sont les alias exacts de ces gestes, pour qui préfère la précision du clavier :

Les recettes