From 431fb5626d1fb692425a180e5cdf14ad89adb2bc Mon Sep 17 00:00:00 2001
From: Bruno Charest <bruno.charest@gmail.com>
Date: Tue, 15 Sep 2026 20:59:06 -0400
Subject: [PATCH] docs(ai): inventaire reel des 28 outils du registre (risques,
 libelles UI, outils web) + sections prevues

---
 docs/AI_ARCHITECTURE_GUIDE.md | 99 +++++++++++++++++++++--------------
 1 file changed, 59 insertions(+), 40 deletions(-)

diff --git a/docs/AI_ARCHITECTURE_GUIDE.md b/docs/AI_ARCHITECTURE_GUIDE.md
index 3930370..1c05e37 100644
--- a/docs/AI_ARCHITECTURE_GUIDE.md
+++ b/docs/AI_ARCHITECTURE_GUIDE.md
@@ -181,67 +181,86 @@ boucle (max N itérations):
 
 ## 4. Catalogue des outils
 
-Légende : **R** = lecture (auto), **M** = mutation (confirmation), **N** = navigation (in-app uniquement).
+> **Inventaire au registre** — 28 outils enregistrés (`backend/tools/service.py`,
+> `backend/tools/web.py`), vérifiable par
+> `docker exec obsigate-test python -c "from backend.tools import api; from backend.tools.registry import _REGISTRY; print(len(_REGISTRY))"`.
+> Les tables ci-dessous reflètent le code, pas l'intention : ce qui n'est pas
+> listé n'est pas exposé au modèle.
+
+Légende : **R** = lecture (appel automatique), **M** = mutation (confirmation
+two-step obligatoire), **D** = dangereux (confirmation **+** réglage par vault
+`aiDestructiveTools`). « Étape (UI) » = libellé affiché dans la section
+« N étapes » de l'assistant (`backend/tools/labels.py` → clés `ai.step.*` FR/EN).
 
 ### Vaults & navigation
 
-| Outil | Type | Paramètres | Endpoint source |
+| Outil | Type | Paramètres | Étape (UI) |
 |---|---|---|---|
-| `list_vaults` | R | — | `GET /api/vaults` (`main.py:1267`) |
-| `list_directory` | R | `vault`, `path` | `GET /api/browse/{vault}` (`main.py:1503`) |
-| `list_all_files` | R | `vault` | `GET /api/vault/{vault}/files` (`main.py:3883`) |
-| `open_file` | N | `vault`, `path` | événement front `obsigate:open-file` |
-| `reveal_in_tree` | N | `vault`, `path` | UI sidebar |
+| `list_vaults` | R | — | Liste des vaults consultée |
+| `list_directory` | R | `vault`, `path` | Répertoire exploré : {chemin} |
+| `list_all_files` | R | `vault`, `dir`, `limit`, `recursive` | Fichiers listés |
 
 ### Lecture de contenu
 
-| Outil | Type | Paramètres | Endpoint source |
+| Outil | Type | Paramètres | Étape (UI) |
 |---|---|---|---|
-| `read_file` | R | `vault`, `path` | `GET /api/file/{vault}` (`main.py:2722`) |
-| `read_file_raw` | R | `vault`, `path` | `GET /api/file/{vault}/raw` (`main.py:1589`) |
-| `get_backlinks` | R | `vault`, `path` | `GET /api/file/{vault}/backlinks` (`main.py:2683`) |
-| `list_backups` | R | `vault`, `path` | `GET /api/file/{vault}/backups` (`main.py:2476`) |
-| `diff_backup` | R | `vault`, `path` | `GET /api/file/{vault}/diff` (`main.py:2513`) |
-| `get_graph` | R | `vault` | `GET /api/graph/{vault}` (`main.py:3390`) |
+| `read_file` | R | `vault`, `path` | Fichier lu : {chemin} |
+| `read_file_raw` | R | `vault`, `path` | Fichier lu : {chemin} |
+| `get_backlinks` | R | `vault`, `path` | Backlinks analysés |
+| `list_backups` | R | `vault`, `path` | Sauvegardes consultées |
+| `diff_backup` | R | `vault`, `path`, `version`, `compare_with` | Comparaison de sauvegarde : {chemin} |
+| `get_graph` | R | `vault`, `path`, `depth`, `scope`, `tag` | Graphe du vault consulté |
 
 ### Recherche
 
-| Outil | Type | Paramètres | Endpoint source |
+| Outil | Type | Paramètres | Étape (UI) |
 |---|---|---|---|
-| `search_fulltext` | R | `q`, `vault`, `tag`, `limit` | `GET /api/search` (`main.py:3097`) |
-| `search_advanced` | R | `q`, `vault`, filtres, `regex`… | `GET /api/search/advanced` (`main.py:3195`) |
-| `search_paths` | R | `q`, `vault` | `GET /api/tree-search` (`main.py:3151`) |
-| `list_tags` | R | `vault` | `GET /api/tags` (`main.py:3137`) |
-| `suggest_tags` | R | `q` | `GET /api/tags/suggest` (`main.py:3352`) |
-| `list_recent` | R | `vault` | `GET /api/recent` (`main.py:1301`) |
+| `search_fulltext` | R | `q`, `vault`, `tag`, `limit` | Recherche dans le vault : {q} |
+| `search_advanced` | R | `q`, `vault`, `tag`, `limit`, `offset`, `sort`, `case_sensitive`, `whole_word`, `regex`, `include_paths`, `exclude_paths`, `created`, `modified`, `size` | Recherche dans le vault : {q} |
+| `search_paths` | R | `q`, `vault` | Chemins recherchés : {q} |
+| `list_tags` | R | `vault` | Tags consultés |
+| `suggest_tags` | R | `q`, `vault`, `limit` | Tags suggérés pour {q} |
+| `list_recent` | R | `vault`, `limit`, `mode` | Fichiers récents consultés |
 
-### Création / modification
+### Web (in-app uniquement, jamais exposé en MCP)
 
-| Outil | Type | Paramètres | Endpoint source |
+| Outil | Type | Paramètres | Étape (UI) |
 |---|---|---|---|
-| `create_file` | M | `vault`, `path`, `content` | `POST /api/file/{vault}` (`main.py:2134`) |
-| `create_directory` | M | `vault`, `path` | `POST /api/directory/{vault}` (`main.py:1921`) |
-| `edit_file` | M | `vault`, `path`, `content` | `PUT /api/file/{vault}/save` (`main.py:1796`) |
-| `append_to_file` | M | `vault`, `path`, `content` | dérivé de save |
-| `rename_file` | M | `vault`, `path`, `new_name` | `PATCH /api/file/{vault}` (`main.py:2207`) |
-| `rename_directory` | M | `vault`, `path`, `new_name` | `PATCH /api/directory/{vault}` (`main.py:1995`) |
-| `move_path` | M | `vault`, `src`, `dst` | `POST /api/move/{vault}` (`main.py:2289`) |
-| `replace_in_files` | M ⚠️ | `vault`, `find`, `replace`, filtres | `POST /api/search/replace` (`main.py:3241`) |
+| `web_search` | R | `query`, `max_results`, `category`, `language`, `page` | Recherche sur le web : {query} |
+| `fetch_url` | R | `url` | Page web consultée : {url} |
 
-### Suppression (confirmation renforcée)
+`web_search` interroge l'instance SearXNG auto-hébergée
+(`OBSIGATE_SEARXNG_URL`, `search.dracodev.net` par défaut — aucune clé API) ;
+`fetch_url` extrait le texte d'une page publique après garde SSRF (URL et
+redirections reverrouillées hop par hop, plafond de taille).
 
-| Outil | Type | Paramètres | Endpoint source |
+### Création / modification (confirmation)
+
+| Outil | Type | Paramètres | Étape (UI) |
 |---|---|---|---|
-| `delete_file` | M ⚠️ | `vault`, `path` | `DELETE /api/file/{vault}` (`main.py:1851`) |
-| `delete_directory` | M ⚠️ | `vault`, `path`, `recursive` | `DELETE /api/directory/{vault}` (`main.py:2068`) |
-| `restore_backup` | M | `vault`, `path` | `POST /api/file/{vault}/restore` (`main.py:2601`) |
+| `create_file` | M | `vault`, `path`, `content` | Fichier proposé : {chemin} |
+| `create_directory` | M | `vault`, `path` | Dossier proposé : {chemin} |
+| `edit_file` | M | `vault`, `path`, `content` | Fichier modifié : {chemin} |
+| `append_to_file` | M | `vault`, `path`, `content` | Fichier complété : {chemin} |
+| `restore_backup` | M | `vault`, `path`, `version` | Sauvegarde restaurée : {chemin} |
 
-### Partage (optionnel, admin)
+### Suppression & opérations destructives (confirmation + toggle par vault)
 
-| Outil | Type | Paramètres | Endpoint source |
+| Outil | Type | Paramètres | Étape (UI) |
 |---|---|---|---|
-| `create_share` | M | `vault`, `path`, options | `POST /api/share/{vault}` (`main.py:4719`) |
-| `list_shares` | R | — | — |
+| `rename_file` | D | `vault`, `path`, `new_name` | Fichier renommé : {chemin} |
+| `rename_directory` | D | `vault`, `path`, `new_name` | Dossier renommé : {chemin} |
+| `move_path` | D | `vault`, `source_path`, `destination_dir` | Élément déplacé : {chemin} |
+| `replace_in_files` | D | `find`, `replace`, `vault`, `case_sensitive`, `whole_word`, `regex`, `include_paths`, `exclude_paths`, `replace_all`, `dry_run` | Remplacements : {motif} |
+| `delete_file` | D | `vault`, `path` | Fichier supprimé : {chemin} |
+| `delete_directory` | D | `vault`, `path`, `recursive` | Dossier supprimé : {chemin} |
+
+### Prévu, non implémenté
+
+Navigation front (`open_file`, `reveal_in_tree` — réalisés côté UI par les liens
+cliquables de l'assistant, pas comme outils du registry), partage
+(`create_share`, `list_shares`) et sources connectées (Gitea, Drive, courriel… :
+voir [#92](./features/ai-tools-roadmap.md)).
 
 ---