docs: enrich Axe 13 Shell AI in roadmap and update architecture

ARCHITECTURE.md

@@ -15,6 +15,7 @@
 - 🚀 Les démarrer, arrêter, redémarrer en avant-plan ou en arrière-plan
 - 🔍 Observer leur état, leurs logs, leurs statistiques d'utilisation
 - 🛠️ Gérer dépendances, alias, groupes, profils, secrets, favoris et annotations
+- ⚡ Exécuter des actions shell via langage naturel avec un agent léger (`am ai`)
 
 Le tout sans toucher au système : chaque agent est installé dans un répertoire utilisateur isolé.
 
@@ -35,6 +36,7 @@ flowchart TB
         APP["App<br/>contexte partagé"]
         CLI_DEF["cli.rs<br/>définition des commandes"]
         CMD["commands/<br/>dispatch"]
+        SHELL_AI["shell_ai.rs<br/>agent shell léger"]
     end
 
     subgraph DATA["💾 Données persistantes"]
@@ -62,7 +64,9 @@ flowchart TB
     CLI --> APP
     REPL --> APP
     TUI --> APP
+    WEB --> APP
     APP --> CLI_DEF
+    APP --> SHELL_AI
     APP --> CONFIG
     APP --> CATALOG
     APP --> STATE
@@ -76,6 +80,7 @@ flowchart TB
     CMD --> DASH
     CMD --> STATS
     CMD --> SESSIONS
+    SHELL_AI --> CMD
 ```
 
 ---
@@ -166,6 +171,7 @@ src/
 ├── playbook.rs          ▶️ Rejeu pas à pas d'une séquence d'historique
 ├── plugins.rs           🔌 Scripts d'extension sur les événements (contrat JSON)
 ├── models.rs            🤖 Inventaire des modèles locaux (ollama, llama.cpp, LM Studio)
+├── shell_ai.rs          ⚡ Agent shell léger : langage naturel → action shell
 ├── sync.rs              🔄 Push git de l'état (journal, sessions, config)
 ├── agent_config.rs      ⚙️ Adaptateurs de configuration post-install (TOML/YAML/JSON/key=value)
 ├── costs.rs             💰 Coûts estimés par agent (tokens in/out, modèles de prix)
@@ -463,6 +469,7 @@ flowchart TB
 | `am registry publish/search/install` | Registre communautaire de catalogues (Gitea, manifeste + checksum sha256 vérifié) |
 | `am serve --token [--port]` | API HTTP + WebSocket authentifiée : stats, run, start, stop, ask — rate limiting par IP, TLS derrière reverse proxy |
 | `am web [--port]` | Dashboard web local en lecture seule (127.0.0.1), contrats `--json` réutilisés |
+| `am ai "<prompt>" [--exec] [--files <path>]` | **Shell AI** : langage naturel → commande/action shell via agent léger (AIChat) ; `--dry-run` par défaut, confirmation avant exécution |
 | `am lab --agents a,b --task <f>` | Benchmark comparatif (durée, exit, coût) sur tâches YAML versionnables |
 | `am sync [--message]` | Sauvegarde git de l'état (journal, sessions, config — secrets exclus) |
 | `am migrate export/import` | Bundle de transfert machine A → B (config + état + historique) |
@@ -711,6 +718,57 @@ flowchart LR
 
 ---
 
+## ⚡ Shell AI
+
+`am ai` (alias `am shell`) est une commande dédiée aux **actions shell via langage naturel**. Elle repose sur un agent léger (par défaut **AIChat**, installé comme n'importe quel autre agent via le catalogue) et réutilise le registre de providers LLM (`providers.rs`) pour choisir le modèle le plus rapide/cheap.
+
+### Flux d'exécution
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant User
+    participant cli as cli.rs
+    participant shell_ai as shell_ai.rs
+    participant catalog as catalog.rs
+    participant providers as providers.rs
+    participant runner as runner.rs
+    participant aichat as aichat (agent)
+
+    User->>cli: am ai "traite les JSON"
+    cli->>shell_ai: parse args (--exec, --files)
+    shell_ai->>catalog: agent "aichat" installé ?
+    catalog-->>shell_ai: Ok / install
+    shell_ai->>providers: provider & modèle par défaut
+    providers-->>shell_ai: config (ollama / cheap cloud)
+    shell_ai->>shell_ai: injecte cwd + fichiers (--files)
+    shell_ai->>runner: exec aichat -f . -e "..."
+    runner->>aichat: lancement processus
+    aichat-->>runner: commande générée / exécutée
+    runner-->>shell_ai: output + exit code
+    shell_ai->>shell_ai: journalise événement shell_ai
+    shell_ai-->>User: résultat ou confirmation
+```
+
+### Sécurité
+
+| Règle | Détail |
+|---|---|
+| `--dry-run` par défaut | Aucune commande modifiante n'est exécutée sans confirmation |
+| Classification risk/certainty | Inspiré d'AI CLI : chaque commande est classée `safe` ou `risky` |
+| Confirmation utilisateur | Les commandes `risky` demandent une validation explicite |
+| Mode local possible | Support d'Ollama via `providers.rs` pour ne pas sortir les données |
+
+### Dépendances
+
+- `src/shell_ai.rs` : parsing du prompt, gestion des flags, appel à l'agent
+- `src/providers.rs` : résolution du provider/modèle
+- `src/runner.rs` : exécution du binaire `aichat`
+- `src/events.rs` : journalisation `shell_ai` dans le journal JSONL
+- `config.yaml` : définition de l'agent `aichat` + alias `ai`
+
+---
+
 ## 📚 Références
 
 - `src/lib.rs:4` : documentation d'architecture du crate

ROADMAP.md

@@ -350,14 +350,89 @@ consultable, reprenable, archivable.
 
 ### Axe 13 — ⚡ Shell AI & Action ⭐
 
-🎯 Transformer une commande en langage naturel en une action shell exécutée par un agent léger, rapide et contextuel.
+🎯 Transformer une commande en langage naturel en une action shell exécutée par un agent léger, rapide et contextuel, sans démarrer un gros coding agent.
 
-| Fonctionnalité | Effort | Phase |
+**Contexte :** `am` gère aujourd'hui ~72 agents IA, principalement des *coding agents*, des assistants et des outils SaaS. Aucun n'est un **shell assistant pur** — léger, rapide, conçu pour transformer une phrase en commande ou action sur le système de fichiers local (ex. *"traite les fichiers JSON du dossier courant pour extraire les clés uniques"*).
+
+---
+
+#### 13.1 Agents shell AI découverts (non présents dans le catalogue)
+
+| Outil | Repo | Langage | Force | Maturité |
+|---|---|---|---|---|
+| **AIChat** | `sigoden/aichat` | Rust | Shell assistant natif, RAG, agents, fichiers/répertoires, 20+ providers | **10.4k stars**, très actif |
+| **ShellGPT** | `TheR1D/shell_gpt` | Python | Génère/exécute commandes shell, code, docs | Très connu, mature |
+| **Fabric** | `danielmiessler/fabric` | Go | Patterns AI (summarize, extract wisdom), CLI | Très populaire, orienté contenu/texte |
+| **Shell AI** | `nishant9083/shell-ai` | TypeScript | Agent ReAct local via Ollama, MCP, filesystem tools | Plus récent, prometteur mais jeune |
+| **AI CLI** | `kriserickson/ai-cli` | Rust | Natural language → commandes shell avec safety policy (`risk` / `certainty`) | Petit, simple, moins connu |
+
+---
+
+#### 13.2 Recommandation : AIChat (`sigoden/aichat`)
+
+**Choix privilégié pour la fonction Shell AI.**
+
+| Avantage | Détails |
+|---|---|
+| **Léger & rapide** | Rust, binaire unique, cold start rapide, idéal pour RPi 4 |
+| **Shell Assistant natif** | Génère et exécute des commandes shell à partir du langage naturel |
+| **Multi-provider** | OpenAI, Claude, Gemini, DeepSeek, Groq, Ollama, OpenRouter… |
+| **Passage de contexte** | `aichat -f .` injecte le dossier ou les fichiers dans le prompt |
+| **Mode exécution** | `aichat -e "..."` exécute directement, mode conversationnel sinon |
+| **Facilité d'intégration** | Release binaire GitHub, installable via `binary` dans le catalogue |
+
+Exemples d'usage ciblés :
+
+```bash
+# Lister et traiter les fichiers JSON du dossier courant
+aichat -f . -e "liste tous les fichiers JSON et extrait les clés uniques"
+
+# Résumer un dossier de fichiers
+aichat -f . "résume les données de ces fichiers JSON"
+```
+
+---
+
+#### 13.3 Fonctionnalités prévues
+
+| Fonctionnalité | Description | Effort | Phase |
+|---|---|---|---|
+| **Catalogue : ajouter AIChat** | Définition `AgentDef` + alias `ai` → `aichat` | S | P1 |
+| **Commande `am ai <prompt>`** | Lancer AIChat avec le dossier courant comme contexte | S | P3 |
+| **Flag `--exec` / `-e`** | Active le mode exécution directe (`aichat -e`) | S | P3 |
+| **Flag `--files <path>`** | Passer fichiers/dossiers spécifiques en contexte | S | P3 |
+| **Sécurité : `--dry-run` par défaut** | Simuler avant exécution ; confirmation si modification | M | P3 |
+| **Provider configurable** | Réutiliser le registre `providers.rs` (cheap model par défaut) | M | P3 |
+| **Alias intégrés** | `am shell`, `am do` comme synonymes | S | P3 |
+| **Extensions sœurs** | `am summarize`, `am explain`, `am fix` (voir ci-dessous) | M | P3 |
+
+---
+
+#### 13.4 Risques & garde-fous
+
+| Risque | Mitigation |
+|---|---|
+| Exécution automatique de commandes dangereuses | `--dry-run` par défaut, confirmation obligatoire avant toute commande `risky` |
+| Coût API récurrent | Modèle cheap par défaut (`gpt-4.1-mini`, `gemini-flash`) ou Ollama local |
+| Fuite de données sensibles | Support du mode local Ollama, pas d'envoi hors du provider configuré |
+| Installation lente sur RPi | Utiliser l'installateur `binary` GitHub Releases plutôt que `cargo` |
+
+---
+
+#### 13.5 Idées sœurs (à intégrer ou lier à d'autres axes)
+
+| Commande | Description | Axe lié |
 |---|---|---|
-| Intégration d'un agent shell léger (`am ai <prompt>`) | M | P3 |
+| `am summarize <fichier/dossier>` | Résume un fichier ou un dossier via AIChat/Fabric | Axe 13 |
-|   ↳ Candidat principal : **AIChat (Rust)** | | |
+| `am explain <commande>` | Explique une commande shell avant exécution | Axe 13 |
-| Passage de contexte (fichiers/dossiers) via flags | S | P3 |
+| `am commit` | Génère un message de commit depuis `git diff` | Axe 13 / Axe 3 |
-| Mode exécution directe (`-e`) vs. conversationnel | S | P3 |
+| `am review` | Review rapide d'un diff ou d'une PR | Axe 7 |
+| `am translate <fichier> --to en` | Traduit un fichier markdown/doc | Axe 13 |
+| `am ask-code "..."` | Pose une question sur le codebase sans lancer un gros agent | Axe 7 |
+| `am doc <dossier>` | Génère un README/doc à partir du code | Axe 13 / Axe 7 |
+| `am fix` | Corrige une commande shell qui a échoué | Axe 13 |
+| `am note` | Extrait des action items d'un texte/réunion | Axe 10 |
+| `am search-web "..."` | Recherche web rapide et réponse synthétisée | Axe 7 |
 
 
 ---