Documentation

Ce parcours couvre trois choses : lire la documentation de cadrage de votre projet, tenir sa documentation utilisateur (celle que lisent vos utilisateurs), et traduire l'interface et les descriptions des outils. Vous y venez pour retrouver un document, vérifier que la documentation suit le produit, ou ajouter une langue.

Ce que vous demandez à l'agent

💬 Vous demandez à l’agent

« Quels documents de cadrage a ce projet ? »

→ L’agent appelleeffortless_docs_list

💬 Vous demandez à l’agent

« Cherche dans la documentation tout ce qui parle de la livraison. »

→ L’agent appelleeffortless_docs_search

• query = livraison

💬 Vous demandez à l’agent

« Lis-moi le document blueprints/012-Epic-Export/cadrage.md en entier. »

→ L’agent appelleeffortless_doc_read

• rel_path = blueprints/012-Epic-Export/cadrage.md

💬 Vous demandez à l’agent

« Notre documentation utilisateur couvre-t-elle tout ? Y a-t-il des pages vieillies ? »

→ L’agent appelleeffortless_user_doc_coverage

💬 Vous demandez à l’agent

« Vérifie l'inventaire de la documentation utilisateur. »

→ L’agent appelleeffortless_user_doc_inventory

💬 Vous demandez à l’agent

« Le build de la documentation est fait dans dist/docs : écris son manifeste. »

→ L’agent appelleeffortless_user_doc_manifest

• output_dir = dist/docs

💬 Vous demandez à l’agent

« Installe la nouvelle copie hors ligne de la documentation : la candidate est dans dist/docs, la préproduction dans dist/staging, la copie courante dans app/docs. »

→ L’agent appelleeffortless_user_doc_sync

• source_dir = dist/docs
• staging_dir = dist/staging
• current_dir = app/docs

💬 Vous demandez à l’agent

« Quelles clés de l'interface ne sont pas encore traduites en espagnol ? Traduis-les. »

→ L’agent appelleeffortless_i18n_status

• surface = front
• lang = es

💬 Vous demandez à l’agent

« Montre-moi le catalogue anglais des descriptions d'outils. »

→ L’agent appelleeffortless_i18n_export

• surface = mcp
• lang = en

Ce que fait l'agent

Lire et chercher la documentation de cadrage

1. effortless_project_docs_list liste les documents de cadrage du projet : les fichiers à la racine de blueprints/ dont l'en-tête porte type: cadrage-projet.
2. effortless_docs_list liste tous les documents Markdown de blueprints/, sous-dossiers compris, avec leur titre.
3. effortless_docs_search avec query cherche dans ces documents, sans tenir compte de la casse ni des accents. Les résultats sont classés par nombre d'occurrences, chacun avec un extrait.
4. effortless_doc_read avec rel_path (relatif à la racine du projet) lit un document. Il refuse tout chemin hors de blueprints/.

Ces quatre verbes ne font que lire.

Tenir la documentation utilisateur

La documentation utilisateur est déclarée dans un fichier userdoc.json à la racine d'une stack. Les quatre verbes prennent stack_id ; sans lui, l'agent vise la seule stack qui déclare une documentation utilisateur.

1. effortless_user_doc_inventory lit et valide l'inventaire déclaré, et résout chaque source une fois.
2. effortless_user_doc_coverage fait le diagnostic : trous (une source que personne ne documente), pages vieillies (la source a bougé depuis la génération), pages orphelines (la source a disparu). regime vaut observation (par défaut : les constats sont rendus sans bloquer) ou publication (les constats bloquent).
3. effortless_user_doc_manifest avec output_dir (relatif à la stack, sans défaut) clôt un build déjà produit : il interroge la paire de versions par la commande déclarée et écrit le manifeste en dernier. S'il ne peut pas le produire, il retire toute la sortie.
4. effortless_user_doc_sync avec source_dir, staging_dir et current_dir installe une copie hors ligne : la candidate est écrite en préproduction, son manifeste est relu, et la version de format est demandée à la coque. Une copie d'un autre format est refusée et la copie en place est conservée.

Traduire l'interface et les descriptions des outils

Deux surfaces se traduisent : front (l'interface) et mcp (les descriptions des outils). Le français est la source ; il ne s'écrit jamais.

1. effortless_i18n_status avec surface et lang rend le delta : les clés absentes (avec leur texte français) et les clés traduites par machine qu'aucun humain n'a relues.
2. L'agent traduit lui-même ce delta, puis appelle effortless_i18n_apply avec entries (des clés plates vers le texte). Les traductions vont dans ~/.effortless/locales/<surface>/<lang>.json et sont marquées « machine ». Avec reviewed: true, elles sont marquées relues par un humain, et ne sont plus écrasées par une traduction machine.
3. effortless_i18n_export rend le catalogue complet (livré et vos ajouts) d'une surface et d'une langue, pour inspection ou sauvegarde.

Ce que vous obtenez

• Des documents retrouvés et lus sans que vous ouvriez le dossier blueprints/. Ils se lisent aussi dans l'écran Connaissance (lentilles de cadrage et champ de recherche).
• Un diagnostic de couverture avec un code de sortie : conforme, trou, vieillie, orpheline, ou l'un des refus (inventaire invalide, mesure impossible, page altérée).
• Un manifeste de build et une copie hors ligne installée, quand vous les demandez.
• Des fichiers de traduction dans votre dossier personnel, sans toucher au code livré.

Quand l'agent est refusé

Situation	Ce que dit le refus	Ce qu'il faut faire
Chemin hors de blueprints/, absolu ou remontant	« Chemin hors périmètre. »	Donner un chemin relatif sous blueprints/, tel que rendu par effortless_docs_list.
Aucune stack ne déclare de documentation utilisateur	userDoc:usage (« aucune stack ne porte de userdoc.json »)	Déclarer la documentation utilisateur d'une stack.
Plusieurs stacks la déclarent	userDoc:usage (les stacks sont nommées)	Passer stack_id.
stack_id inconnu	userDoc:usage	Lister les stacks avec effortless_stack_list (voir Code et stacks).
Inventaire invalide (code 5)	userDoc:inventoryInvalid	Corriger l'inventaire, effortless_user_doc_coverage nomme ce qui manque.
Mesure impossible (code 6)	userDoc:unmeasurable	Une commande déclarée a échoué : la lire dans le message et la corriger.
Page altérée (code 7)	userDoc:pageAltered	Régénérer la page dérivée plutôt que la modifier à la main.
Couverture bloquante en régime publication	userDoc:coverageBlocking	Combler la couverture décrite dans le rapport, ou repasser en observation.
Copie à installer d'un autre format que celui de la coque	un refus userDoc:* ; la copie en place est conservée	Reconstruire la documentation avec la bonne version de format.
Surface de traduction invalide	« surface invalide … (attendu : front, mcp) »	Passer front ou mcp.
Écriture en français	« Le français est la source : écriture interdite. »	Traduire vers une autre langue (en, es, ru…).