chore: version 1.0.1 (post-v1.0.0 — self-update décompresse les archives, prompt REPL avec shell actif)

Le statut avant chaque invite affiche maintenant le shell-gateway courant (ex: ⚙ am v1.0.0 🪟 bash │ ...), mis à jour dynamiquement via 'shell <name>'. Vérifié en réel : bash → pwsh après switch.

.gitea/workflows/release.yml

@@ -0,0 +1,145 @@
+# Gitea Actions : pipeline de release (issue #42).
+#
+# Sur chaque tag v* : construit les binaires de toutes les plateformes,
+# archive + publie la release Gitea avec les artefacts. Les installateurs
+# (install.sh / install.ps1) et 'am self-update' consomment ces artefacts.
+#
+# Labels de runners attendus : ubuntu-latest, windows-latest, macos-latest.
+# Un runner manquant laisse son job en attente ; le job linux couvre la
+# majorite des cas (les artefacts windows/macos peuvent aussi etre produits
+# par les scripts locaux documentes dans RELEASING.md).
+#
+# Prérequis du runner : pouvoir tirer les images docker.io (rust:1.94-alpine,
+# ~300 Mo) et le secret GITEA_TOKEN (jeton avec droit 'write:release')
+# positionné sur le dépôt. La release existante est écrasée
+# (release_overwrite).
+#
+# Note disque (runner avec espace limite) :
+# - il faut ~1 Go libres sur / pour tirer l'image (rust:1.94-alpine) ;
+#   en cas de 'no space left on device' : docker system prune -af --volumes
+#   sur l'HOTE du runner (pas une autre machine !) ;
+# - les builds compilent dans CARGO_TARGET_DIR=/tmp (hors du volume
+#   workspace) avec l'incremental desactive, donc rien ne persiste ;
+# - le job linux utilise cargo-zigbuild : zig (~50 Mo) fournit le linker
+#   croise pour les DEUX cibles musl statiques dans une seule image legere
+#   (rust:1.94-alpine n'embarque pas de compilateur croise aarch64).
+name: release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  linux:
+    runs-on: ubuntu-latest
+    container: rust:1.94-alpine
+    env:
+      CARGO_TARGET_DIR: /tmp/am-target
+      CARGO_INCREMENTAL: "0"
+    steps:
+      # actions/checkout (et son post-step) s'execute via node, absent de
+      # l'image rust:alpine : sans nodejs le job echoue des le checkout.
+      - name: Prepare container (node for checkout action)
+        run: apk add --no-cache nodejs
+
+      - uses: actions/checkout@v4
+
+      - name: Install build tools (zig + cargo-zigbuild)
+        run: |
+          apk add --no-cache build-base zip curl
+          rustup target add x86_64-unknown-linux-musl aarch64-unknown-linux-musl
+          curl -fsSL https://ziglang.org/download/0.14.1/zig-x86_64-linux-0.14.1.tar.xz -o /tmp/zig.tar.xz
+          tar -xf /tmp/zig.tar.xz -C /opt
+          echo "/opt/zig-x86_64-linux-0.14.1" >> "$GITHUB_PATH"
+          cargo install cargo-zigbuild --locked
+
+      - name: Build linux x86_64 + aarch64 (static musl, zig)
+        run: cargo zigbuild --release --locked --target x86_64-unknown-linux-musl --target aarch64-unknown-linux-musl
+
+      - name: Stage archives
+        run: |
+          mkdir -p dist
+          cp "$CARGO_TARGET_DIR/x86_64-unknown-linux-musl/release/am" dist/am-linux-x86_64
+          cp "$CARGO_TARGET_DIR/aarch64-unknown-linux-musl/release/am" dist/am-linux-aarch64
+          cd dist
+          tar -czf am-linux-x86_64.tar.gz am-linux-x86_64
+          tar -czf am-linux-aarch64.tar.gz am-linux-aarch64
+          sha256sum am-linux-*.tar.gz > checksums.txt
+
+      - name: Publish release
+        uses: https://gitea.com/actions/gitea-release-action@v1
+        with:
+          # L'action splitte 'files' sur les retours a la ligne (pas les
+          # espaces) : un bloc YAML plie en une seule ligne et ne trouve
+          # alors aucun fichier -> 'not include valid file', rien n'upload.
+          files: |
+            dist/am-linux-x86_64.tar.gz
+            dist/am-linux-aarch64.tar.gz
+            dist/checksums.txt
+          GITHUB_TOKEN: ${{ secrets.GITEA_TOKEN }}
+          release_overwrite: true
+
+  windows:
+    runs-on: windows-latest
+    env:
+      CARGO_TARGET_DIR: C:/am-target
+      CARGO_INCREMENTAL: "0"
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build windows x86_64
+        run: cargo build --release --locked
+
+      - name: Stage archive
+        run: |
+          New-Item -ItemType Directory -Force dist | Out-Null
+          Compress-Archive -Path C:/am-target/release/am.exe -DestinationPath dist/am-windows-x86_64.zip -Force
+          (Get-FileHash dist/am-windows-x86_64.zip -Algorithm SHA256).Hash.ToLower() | Out-File dist/checksums.txt
+
+      - name: Publish release
+        uses: https://gitea.com/actions/gitea-release-action@v1
+        with:
+          files: |
+            dist/am-windows-x86_64.zip
+            dist/checksums.txt
+          GITHUB_TOKEN: ${{ secrets.GITEA_TOKEN }}
+          release_overwrite: true
+
+  macos:
+    runs-on: macos-latest
+    env:
+      CARGO_TARGET_DIR: /tmp/am-target
+      CARGO_INCREMENTAL: "0"
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build macos x86_64 + aarch64
+        run: |
+          rustup target add x86_64-apple-darwin aarch64-apple-darwin
+          cargo build --release --locked --target x86_64-apple-darwin
+          cargo build --release --locked --target aarch64-apple-darwin
+
+      - name: Stage archives
+        run: |
+          mkdir -p dist
+          cp "$CARGO_TARGET_DIR/x86_64-apple-darwin/release/am" dist/am-macos-x86_64
+          cp "$CARGO_TARGET_DIR/aarch64-apple-darwin/release/am" dist/am-macos-aarch64
+          cd dist
+          tar -czf am-macos-x86_64.tar.gz am-macos-x86_64
+          tar -czf am-macos-aarch64.tar.gz am-macos-aarch64
+          shasum -a 256 am-*.tar.gz > checksums.txt
+
+      - name: Publish release
+        uses: https://gitea.com/actions/gitea-release-action@v1
+        with:
+          files: |
+            dist/am-macos-x86_64.tar.gz
+            dist/am-macos-aarch64.tar.gz
+            dist/checksums.txt
+          GITHUB_TOKEN: ${{ secrets.GITEA_TOKEN }}
+          release_overwrite: true

ARCHITECTURE.md

@@ -0,0 +1,691 @@
+# 🏗️ Document d'architecture — agent-manager (`am`)
+
+> Ce document décrit la conception, le fonctionnement et les fonctionnalités de **agent-manager** (binaire `am`), un CLI Rust multiplateforme pour gérer des agents IA de coding locaux.
+>
+> 📦 Version : `0.6.0` · 🦀 Rust 2021 · ✅ Windows · ✅ Linux · ✅ macOS
+
+---
+
+## 🎯 Vue d'ensemble
+
+`am` est un gestionnaire d'agents IA de coding qui permet de :
+
+- 📋 Découvrir et lister plus de **72 agents** via un catalogue YAML embarqué
+- 📦 Les installer avec **9 méthodes** différentes (npm, pip, uv, cargo, go, bun, curl, binaire, git)
+- 🚀 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
+
+Le tout sans toucher au système : chaque agent est installé dans un répertoire utilisateur isolé.
+
+---
+
+## 🧩 Architecture globale
+
+```mermaid
+flowchart TB
+    subgraph UI["🖥️ Interfaces utilisateur"]
+        CLI["Ligne de commande<br/>clap v4"]
+        REPL["Shell interactif<br/>rustyline"]
+        TUI["Dashboard TUI<br/>ratatui + crossterm"]
+        WEB["Dashboard web<br/>tiny_http (127.0.0.1)"]
+    end
+
+    subgraph CORE["⚙️ Noyau applicatif"]
+        APP["App<br/>contexte partagé"]
+        CLI_DEF["cli.rs<br/>définition des commandes"]
+        CMD["commands/<br/>dispatch"]
+    end
+
+    subgraph DATA["💾 Données persistantes"]
+        CONFIG["Configuration YAML<br/>embarquée + utilisateur"]
+        CATALOG["Catalog<br/>index agents/alias/groupes"]
+        STATE["StateStore<br/>state.json"]
+        EVENTS["Journal JSONL<br/>events-YYYYMM.jsonl"]
+        CACHE["Probe cache<br/>probe-cache.json"]
+    end
+
+    subgraph EXEC["🔧 Exécution"]
+        RUNNER["Runner trait<br/>système / mock"]
+        INSTALLERS["installers/<br/>9 méthodes"]
+        DEPS["deps.rs<br/>vérification dépendances"]
+        PROCESS["process.rs<br/>PID / signaux"]
+    end
+
+    subgraph OBS["👁️ Observation"]
+        PROBE["probe.rs<br/>détection agents externes"]
+        DASH["dashboard.rs<br/>agrégation"]
+        STATS["stats.rs<br/>statistiques"]
+        SESSIONS["sessions.rs<br/>registre sessions"]
+    end
+
+    CLI --> APP
+    REPL --> APP
+    TUI --> APP
+    APP --> CLI_DEF
+    APP --> CONFIG
+    APP --> CATALOG
+    APP --> STATE
+    APP --> EVENTS
+    APP --> CACHE
+    CMD --> RUNNER
+    CMD --> INSTALLERS
+    CMD --> DEPS
+    CMD --> PROCESS
+    CMD --> PROBE
+    CMD --> DASH
+    CMD --> STATS
+    CMD --> SESSIONS
+```
+
+---
+
+## 🚀 Flux d'exécution d'une commande
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant User
+    participant main as main.rs
+    participant lib as lib.rs
+    participant help as help.rs
+    participant cli as cli.rs
+    participant app as app.rs
+    participant cfg as config.rs
+    participant state as state.rs
+    participant cmd as commands/mod.rs
+    participant impl as commands/xxx_cmd.rs
+
+    User->>main: am install jcode
+    main->>lib: main_entry()
+    lib->>lib: spawn thread 8 Mo
+    lib->>help: intercept(-h/--help) ?
+    help-->>lib: None
+    lib->>cli: Cli::parse()
+    cli-->>lib: Cli { command: Install {...} }
+    lib->>app: App::from_cli(cli)
+    app->>cfg: load() config embarquée + user
+    cfg-->>app: Config
+    app->>state: StateStore::new()
+    state-->>app: state.json chargé
+    app-->>lib: App
+    lib->>cmd: commands::execute(&app)
+    cmd->>impl: install_cmd::run(...)
+    impl->>impl: vérifier dépendances, installer
+    impl->>state: persister
+    impl->>app: emit(event install)
+    impl-->>cmd: Ok(0)
+    cmd-->>lib: 0
+    lib-->>main: code sortie
+```
+
+---
+
+## 📁 Structure du code source
+
+```
+src/
+├── main.rs              🚪 Point d'entrée
+├── lib.rs               🧭 main_entry(), doc du crate
+├── cli.rs               📋 Définition clap de toutes les commandes
+├── app.rs               🧰 Contexte App (config, state, paths, logger, theme)
+├── config.rs            ⚙️ Schéma YAML, chargement, fusion, validation
+├── catalog.rs           🔍 Index agents + recherche fuzzy + suggestions
+├── state.rs             💾 Base JSON des installations et annotations
+├── events.rs            📝 Journal d'événements JSONL
+├── runner.rs            🏃 Trait d'exécution système / mock
+├── process.rs           ⚙️ Lancement, arrêt, signaux des processus
+├── deps.rs              ✅ Vérification et auto-installation des dépendances
+├── toolchain.rs         🖥️ Détection OS / gestionnaire de paquets
+├── download.rs          ⬇️ Téléchargement, checksums, extraction
+├── probe.rs             🔎 Détection des agents externes sur le PATH
+├── dashboard.rs         📊 Données agrégées du dashboard
+├── ps.rs                🧮 Table des processus
+├── context.rs           📂 Contexte du projet courant
+├── repl.rs              💬 Shell interactif
+├── shell.rs             🐚 Gestion des shells supportés
+├── help.rs              ❓ Aide Nushell-style
+├── output.rs            🖨️ Logger et rendu
+├── tables.rs            📋 Rendu tabulaire
+├── theme.rs             🎨 Thèmes de couleur (REPL et tableaux)
+├── web.rs               🌐 Serveur HTTP local (127.0.0.1) + API JSON + frontend embarqué
+├── frontend/            📄 index.html — dashboard web (HTML5 + CSS + JS vanilla, include_str!)
+├── history.rs           ⏪ Historique des commandes
+├── sessions.rs          📅 Registre des sessions
+├── projects.rs          🗂️️ Agrégation par projet
+├── hooks.rs             🪝 Hooks de cycle de vie
+├── secrets.rs           🔒 Gestion des secrets (keyring OS)
+├── version.rs           🏷️ Informations de version
+├── commands/            📦 35 modules, un par commande
+└── installers/          📦 9 installateurs spécialisés
+```
+
+---
+
+## ⚙️ Configuration : catalogue YAML extensible
+
+### Hiérarchie de chargement
+
+```mermaid
+flowchart LR
+    EMB["📦 config.yaml<br/>embarqué dans le binaire"] --> MERGE["🔀 Fusion"]
+    USER["👤 ~/.config/agent-manager/config.yaml"] --> MERGE
+    LOCAL["📂 ./agent-manager.yaml"] --> MERGE
+    FLAG["⚡ --config <file>"] --> MERGE
+    MERGE --> EFFECTIVE["✅ Configuration effective"]
+```
+
+Priorité (la plus prioritaire en dernier) :
+
+1. `config.yaml` embarqué (catalogue par défaut, ~72 agents)
+2. `~/.config/agent-manager/config.yaml`
+3. `./agent-manager.yaml` (configuration locale par projet)
+4. `--config <fichier>`
+
+### Schéma de configuration
+
+```yaml
+version: "1.0"
+
+settings:
+  install_dir: null            # ~/.local/share/agent-manager/agents
+  log_dir: null                # ~/.local/state/agent-manager/logs
+  default_shell: null          # shell utilisateur par défaut
+  auto_install_deps: true      # proposer d'installer les dépendances manquantes
+  confirm_before_run: true     # confirmer avant les scripts d'installation
+  stop_timeout_secs: 5         # délai SIGTERM → SIGKILL
+  self_update_repo: Projets/agent-manager
+  self_update_base_url: https://git.dracodev.net/api/v1
+  theme: null
+  hooks:
+    on_install: []
+    on_start: []
+    on_stop: []
+    on_update: []
+
+aliases:
+  cc: claude-code
+  gemini: gemini-cli
+
+groups:
+  dev: [claude-code, aider, codex]
+
+include:
+  - ./extra-agents.yaml
+
+agents:
+  - name: claude-code
+    display_name: "Claude Code"
+    description: "..."
+    category: coding-agent
+    website: https://github.com/anthropics/claude-code
+    install:
+      type: npm
+      package: "@anthropic-ai/claude-code"
+    dependencies:
+      - { name: node, min_version: "18.0.0" }
+    run: claude
+    tags: [anthropic, assistant]
+
+profiles:
+  dev:
+    agent: claude-code
+    env: { API_ENV: dev }
+    args: [--verbose]
+
+projects:
+  mon-projet:
+    root: ~/projets/mon-projet
+    default_agent: claude-code
+    env: { KEY: value }
+```
+
+### Définition d'un agent (`AgentDef`)
+
+| Champ | Description |
+|-------|-------------|
+| `name` | Identifiant unique (slug) |
+| `display_name` | Nom lisible |
+| `description` | Description longue |
+| `category` | Catégorie (coding-agent, assistant, local-first...) |
+| `website` | URL du projet |
+| `install` | Spécification d'installation |
+| `dependencies` | Outils requis (node, python, go...) avec version min |
+| `run` | Commande de lancement |
+| `args` | Arguments par défaut |
+| `env` | Variables d'environnement par défaut |
+| `tags` | Tags pour recherche/filtrage |
+| `installable` | `false` pour les agents SaaS/Desktop |
+| `platforms` | Restriction `linux`/`macos`/`windows` |
+
+### Méthodes d'installation supportées
+
+| Type | Fichier | Principe |
+|------|---------|----------|
+| `npm` | `installers/npm.rs` | `npm install -g --prefix <root>` |
+| `bun` | `installers/npm.rs` | `bun install -g` |
+| `pip` / `uv` | `installers/pipuv.rs` | virtualenv privé dans `install_dir` |
+| `cargo` | `installers/cargo.rs` | `cargo install --root` |
+| `go` | `installers/golang.rs` | `go install` avec `GOBIN` local |
+| `curl` | `installers/script.rs` | Télécharge et exécute un script |
+| `binary` | `installers/binary.rs` | Release GitHub/Gitea → extraction archive |
+| `git` | `installers/git.rs` | Clone + build + `binary_path` |
+
+---
+
+## 💾 Gestion des états
+
+### `state.json` — base d'installation locale
+
+Format JSON version 3, atomique (écriture `.tmp` + `rename`).
+
+```json
+{
+  "version": 3,
+  "installed": {
+    "jcode": {
+      "name": "jcode",
+      "version": "0.76.0",
+      "method": "binary",
+      "directory": ".../agents/jcode",
+      "binaries": ["jcode"],
+      "pid": null,
+      "installed_at": "...",
+      "updated_at": "..."
+    }
+  },
+  "annotations": {
+    "jcode": {
+      "favorite": true,
+      "note": "mon agent préféré",
+      "tags": ["perso"]
+    }
+  }
+}
+```
+
+### Journal d'événements JSONL
+
+- Un fichier par mois : `events-YYYYMM.jsonl`
+- Append-only, horodaté
+- Types d'événements : `start`, `stop`, `run`, `install`, `update`, `uninstall`, `doctor`, `config`, `repl`, `shell`, `annotate`
+- Les secrets ne sont jamais journalisés
+- Source de vérité pour les statistiques, sessions, projets et timeline
+
+### Cache de sondes
+
+`probe-cache.json` évite de re-scanner le PATH à chaque commande pour détecter les agents externes et leurs versions.
+
+---
+
+## 🛡️ Gestion des dépendances
+
+```mermaid
+flowchart LR
+    INSTALL["am install jcode"] --> CHECK["deps::check_dep"]
+    CHECK --> MISSING{Manquant ?}
+    MISSING -->|Oui| DETECT["toolchain::detect OS"]
+    DETECT --> COMMANDS["toolchain::install_commands"]
+    COMMANDS --> PROMPT["Proposer la commande"]
+    PROMPT --> AUTO["Exécuter si --yes"]
+    AUTO --> INSTALL2["installers::run_install"]
+    MISSING -->|Non| INSTALL2
+```
+
+- `deps.rs` vérifie chaque dépendance via `<outil> --version`
+- `toolchain.rs` détecte l'OS et le gestionnaire de paquets :
+  - Windows : `scoop` → `winget`
+  - Linux : `apt` / `dnf` / `pacman` / `apk`
+  - macOS : `brew`
+- Si `auto_install_deps: true`, `am` propose et peut exécuter la commande d'installation
+- Les dépendances de l'agent (modules npm/pip) restent isolées dans le répertoire `install_dir`
+
+---
+
+## ⚡ Gestion des processus
+
+```mermaid
+flowchart TB
+    START["am start <agent>"] --> MODE{Mode ?}
+    MODE -->|Foreground| FG["Attache au terminal<br/>Ctrl-C pour quitter"]
+    MODE -->|Background| BG["spawn_background()"]
+    BG --> LOG["Redirection stdout/stderr<br/>vers log agent"]
+    LOG --> PID["Enregistrement PID<br/>dans state.json"]
+    PID --> EVENT["Émission événement start"]
+
+    STOP["am stop <agent>"] --> SIGTERM["SIGTERM"]
+    SIGTERM --> WAIT{"Processus terminé ?"}
+    WAIT -->|Non| SIGKILL["SIGKILL après timeout"]
+    WAIT -->|Oui| CLEAN["PID effacé"]
+```
+
+- Démarrage avant-plan (`-f`) ou arrière-plan (`-b`, `--background`)
+- Variables d'environnement injectées via `--env KEY=VALUE`
+- Secrets via `--env KEY=@secret` (résolu depuis le trousseau OS)
+- Arrêt gracieux avec timeout configurable (défaut 5 s)
+- Notifications desktop optionnelles (`--notify`)
+
+---
+
+## 📋 Commandes détaillées
+
+### 🔍 Découvrir
+
+| Commande | Description |
+|----------|-------------|
+| `am list` | Agents installés + détectés sur le PATH |
+| `am list --all` | Tout le catalogue avec état |
+| `am search <mot>` | Recherche fuzzy avec suggestions |
+| `am info <agent>` | Fiche détaillée |
+| `am status [agent]` | État, version, PID, logs |
+
+### 📦 Cycle de vie
+
+| Commande | Description |
+|----------|-------------|
+| `am install <agent>` | Installe un agent et ses dépendances |
+| `am install <agent> --method pip` | Choisit la méthode |
+| `am uninstall <agent> [--purge]` | Désinstalle et nettoie |
+| `am update <agent>` / `--all` | Met à jour |
+| `am start [agent]` | Lance en avant-plan |
+| `am start <agent> -b` | Lance en arrière-plan |
+| `am stop <agent>` | Arrêt gracieux |
+| `am restart <agent>` | Redémarrage |
+| `am run <agent> [args...]` | Exécution directe sans gestion de PID |
+
+### 👁️ Observer
+
+| Commande | Description |
+|----------|-------------|
+| `am logs <agent>` | Tail du log agent |
+| `am log [agent]` | Journal des événements `am` |
+| `am timeline` | Vue chronologique unifiée |
+| `am sessions [agent]` | Registre des sessions |
+| `am stats [agent] --period 7d` | Statistiques d'utilisation |
+| `am top --period 30d` | Top 10 agents |
+| `am report --last-week` | Rapport markdown |
+| `am projects [nom]` | Agents par projet |
+| `am dashboard` | Dashboard TUI temps réel |
+| `am watch <agent> --restart` | Supervision et relance automatique |
+
+### 🎯 Personnaliser
+
+| Commande | Description |
+|----------|-------------|
+| `am favorite <agent>` | Marquer comme favori |
+| `am note <agent> <texte>` | Ajouter une note |
+| `am tag <agent> <tag>` | Taguer |
+| `am tags [agent]` | Lister les tags |
+| `am profile list/show <name>` | Profils d'environnement |
+| `am alias add <nom> <cible>` | Créer un alias |
+| `am secret set <nom> --agent <a> --value <v>` | Secret dans le trousseau |
+
+### 🛠️ Système
+
+| Commande | Description |
+|----------|-------------|
+| `am doctor [--fix]` | Diagnostic environnement |
+| `am config show/path/edit/validate/set` | Gestion config |
+| `am completion <shell>` | Script de complétion |
+| `am man [commande]` | Page de manuel |
+| `am open <agent>` | Ouvrir le répertoire d'installation |
+| `am export/import` | Sauvegarde/restauration |
+| `am self-update [--check]` | Mise à jour de `am` |
+| `am self-uninstall` | Désinstallation complète |
+| `am version` | Version et build |
+| `am` (sans commande) | REPL interactif |
+
+---
+
+## 🌐 Options globales
+
+Disponibles avant ou après la sous-commande.
+
+| Option | Effet |
+|--------|-------|
+| `-c, --config <FILE>` | Fichier de configuration alternatif |
+| `-v, --verbose` | Affiche chaque commande exécutée |
+| `-q, --quiet` | Seules les erreurs sont affichées |
+| `-y, --yes` | Oui à toutes les confirmations |
+| `--dry-run` | Simulation sans modification |
+| `--json` | Sortie JSON structurée |
+| `--no-color` | Désactive les couleurs |
+| `--theme <THEME>` | Thème de couleur |
+
+---
+
+## 🎨 Fonctionnalités avancées
+
+### Alias
+
+```yaml
+aliases:
+  cc: claude-code
+  gemini: gemini-cli
+```
+
+`am start cc` démarre `claude-code`.
+
+### Groupes
+
+```yaml
+groups:
+  dev: [claude-code, aider, codex]
+```
+
+`am start group:dev` démarre tous les agents du groupe en arrière-plan.
+
+### Profils d'environnement
+
+```yaml
+profiles:
+  dev:
+    agent: claude-code
+    env: { API_ENV: dev }
+    args: [--verbose]
+```
+
+`am start --profile dev` lance `claude-code` avec les variables et arguments du profil.
+
+### Projets
+
+```yaml
+projects:
+  mon-projet:
+    root: ~/projets/mon-projet
+    default_agent: claude-code
+```
+
+Dans le répertoire du projet, `am start` sans argument lance l'agent par défaut du projet.
+
+### Secrets
+
+Les secrets sont stockés dans le trousseau du système d'exploitation (via `keyring`), jamais en clair dans la config.
+
+```bash
+am secret set OPENAI_API_KEY --agent claude-code --value sk-...
+am start claude-code --env OPENAI_API_KEY=@secret
+```
+
+### Hooks
+
+Commandes exécutées automatiquement aux étapes clés du cycle de vie :
+
+- `on_install`
+- `on_start`
+- `on_stop`
+- `on_update`
+
+Définissables globalement dans `settings.hooks` ou par projet.
+
+### Shell interactif (REPL)
+
+Lancé par `am` sans sous-commande :
+
+- Complétion Tab personnalisée (commandes, agents, alias, groupes, flags, shells, thèmes)
+- Historique des commandes
+- Passerelle système : commandes inconnues exécutées dans le shell actif
+- Commandes internes : `ls`, `dir`, `cd`, `ps`, `where`, `get`, `shell`, `theme`, `exit`, `/help`
+- Bannière ASCII art
+
+---
+
+## 📊 Dashboard TUI
+
+```mermaid
+flowchart LR
+    DASH["am dashboard"] --> OVER["Overview"]
+    DASH --> ACT["Activité"]
+    DASH --> STATS["Statistiques"]
+    DASH --> SESS["Sessions"]
+    DASH --> PROJ["Projets"]
+```
+
+- Navigation : `Tab` / `←` / `→` pour les onglets
+- Défilement : `j` / `k` ou flèches
+- Quitter : `q`
+- Données agrégées depuis `state.json`, le journal d'événements, les sessions et les projets
+
+---
+
+## 🧪 Tests
+
+### Organisation
+
+- **Tests unitaires** : dans chaque module `src/*.rs` sous `#[cfg(test)]`
+- **Tests d'intégration** : dans `tests/`
+
+### Fichiers de tests notables
+
+| Fichier | Couverture |
+|---------|------------|
+| `annotations_test.rs` | Favoris, notes, tags |
+| `config_test.rs` | Chargement/validation/fusion |
+| `dashboard_test.rs` | Dashboard |
+| `doctor_test.rs` | `am doctor` |
+| `dry_run_test.rs` | Mode `--dry-run` |
+| `events_test.rs` | Journal d'événements |
+| `history_test.rs` | Historique |
+| `process_test.rs` | Processus |
+| `profiles_test.rs` | Profils |
+| `projects_test.rs` | Projets |
+| `sessions_test.rs` | Sessions |
+| `stats_test.rs` | Statistiques |
+
+Lancer les tests :
+
+```bash
+cargo test
+```
+
+---
+
+## 📦 Packaging et distribution
+
+```
+dist/                    Binaires précompilés
+├── am-linux-x86_64
+├── am-linux-aarch64
+├── am-windows-x86_64.zip
+├── am_0.4.3_amd64.deb
+└── ...
+
+packaging/              Scripts de packaging
+├── deb/
+├── rpm/
+├── homebrew/
+├── scoop/
+└── winget/
+
+completions/            Scripts de complétion
+├── _am                 zsh
+├── _am.ps1             PowerShell
+├── am.bash             bash
+├── am.elv              elvish
+└── am.fish             fish
+
+man/                    Pages de manuel générées
+```
+
+- `build.rs` enregistre le commit et la branche git pour `am version`
+- `scripts/build-release.ps1` construit les releases multiplateformes
+- `scripts/render-manifests.ps1` génère les manifests de packaging
+
+---
+
+## 🗂️️ Arborescence des données utilisateur
+
+### Windows
+
+```
+%LOCALAPPDATA%\agent-manager\
+├── agents\              installations
+├── logs\                logs agents
+└── state\               state.json, events-*.jsonl, probe-cache.json
+```
+
+### Linux
+
+```
+~/.local/share/agent-manager/   données
+~/.local/state/agent-manager/   logs, state, events, cache
+~/.config/agent-manager/        config.yaml
+```
+
+### macOS
+
+```
+~/Library/Application Support/agent-manager/   données
+~/.local/state/agent-manager/                  logs, state, events, cache
+~/.config/agent-manager/                       config.yaml
+```
+
+Variables d'environnement de débogage/test :
+
+- `AGENT_MANAGER_DATA` : remplace le répertoire de données
+- `AGENT_MANAGER_STATE` : remplace le répertoire d'état
+
+---
+
+## 🔐 Sécurité
+
+- Mode `--dry-run` universel pour simuler sans modifier
+- Checksums `sha256` pour les binaires téléchargés
+- Confirmation avant exécution des scripts d'installation
+- Secrets dans le trousseau OS, jamais dans les logs ni le journal
+- Installation isolée : aucune modification système
+
+---
+
+## 🔁 Résumé du flux de données
+
+```mermaid
+flowchart LR
+    CONFIG["📄 YAML config"] --> CATALOG["📚 Catalog"]
+    CATALOG --> INSTALL["📦 Installateurs"]
+    INSTALL --> STATE["💾 state.json"]
+    STATE --> PROCESS["⚙️ Processus"]
+    PROCESS --> EVENTS["📝 Journal JSONL"]
+    EVENTS --> STATS["📊 Stats / Dashboard"]
+    EVENTS --> SESSIONS["📅 Sessions"]
+    EVENTS --> PROJECTS["🗂️️ Projets"]
+```
+
+---
+
+## 📚 Références
+
+- `src/lib.rs:4` : documentation d'architecture du crate
+- `src/cli.rs:24` : options globales
+- `src/cli.rs:61` : énumération des commandes
+- `src/app.rs:16` : struct `App`
+- `src/config.rs:25` : struct `Config`
+- `src/config.rs:148` : struct `AgentDef`
+- `src/config.rs:241` : enum `InstallType`
+- `src/state.rs:12` : struct `StateFile`
+- `src/events.rs:57` : struct `Event`
+- `README.md` : documentation utilisateur complète
+
+---
+
+*Document généré pour agent-manager v0.4.3* 🚀

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "agent-manager"
-version = "0.2.4"
+version = "1.0.1"
 edition = "2021"
 description = "Manage local AI coding agents: list, install, start, stop, update — with automatic dependency handling and a YAML-driven catalog."
 license = "MIT"
@@ -25,15 +25,27 @@ semver = "1"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 serde_yaml = "0.9"
-rustyline = { version = "14", default-features = false, features = ["with-file-history"] }
+reedline = "0.49"
+nu-ansi-term = "0.50"
 sha2 = "0.10"
 shell-words = "1"
 tar = "0.4"
 tempfile = "3"
+tiny_http = "0.12"
+sha1 = "0.10"
+base64 = "0.22"
+toml = "0.8"
 ureq = { version = "2", default-features = false, features = ["tls"] }
 wait-timeout = "0.2"
+keyring = { version = "3", features = ["windows-native", "linux-native"] }
 which = "7"
 zip = "0.6"
+crossterm = "0.29"
+ratatui = "0.30"
+clap_mangen = "0.3"
+
+[target.'cfg(windows)'.dependencies]
+windows-sys = { version = "0.52", features = ["Win32_Foundation", "Win32_System_Threading", "Win32_System_ProcessStatus", "Win32_System_Diagnostics_ToolHelp", "Win32_System_Console"] }
 
 [profile.release]
 lto = "thin"

EXAMPLES.md

@@ -285,3 +285,99 @@ avec purge.
     $ am uninstall cowsay --purge --yes
     removed 'cowsay' from .../cowsay.yaml (backup: .../cowsay.yaml.bak)
     uninstalled Cowsay (files removed, config purged)
+
+## Favoris, notes et tags personnels (v0.4.1)
+
+    $ am favorite claude-code
+    ⭐ claude-code added to favorites
+
+    $ am note claude-code use sonnet for this repo
+    note saved for 'claude-code'
+
+    $ am tag claude-code python frontend
+    tagged 'claude-code' with python, frontend
+
+    $ am tags
+    ┌───┬────────────┬───────┬─────────────┐
+    │ # │ TAG        │ COUNT │ AGENTS      │
+    ├───┼────────────┼───────┼─────────────┤
+    │ 0 │ #frontend  │ 1     │ claude-code │
+    │ 1 │ #python    │ 1     │ claude-code │
+    └───┴────────────┴───────┴─────────────┘
+
+L'étoile apparaît dans am list, am status et am info ; les tags sont
+filtrables avec am search --tag, et tout survit au redémarrage (état v3) :
+
+    $ am info claude-code | tail
+      tags  anthropic · assistant · source-available · mainstream
+      personal
+      ● favorite ★
+      ● tags #frontend #python
+      ● note use sonnet for this repo
+
+    $ am search --tag python
+    ┌───┬──────────────────────────┬──────────────┬─────────────┬─────────────┐
+    │ # │ NAME                     │ CATEGORY     │ INSTALLABLE │ DESCRIPTION │
+    ├───┼──────────────────────────┼──────────────┼─────────────┼─────────────┤
+    │ 0 │ ★ Claude Code            │ coding-agent │ yes         │ Agent termi… │
+    └───┴──────────────────────────┴──────────────┴─────────────┴─────────────┘
+
+## Profils d'environnement (v0.4.1)
+
+Des profils nommés dans la configuration (env + args + agent par défaut)
+s'appliquent au lancement :
+
+    profiles:
+      dev:
+        agent: claude-code
+        env: {DEBUG: "1", LOG_LEVEL: debug}
+        args: [--model, sonnet]
+      prod:
+        env: {LOG_LEVEL: info}
+
+    $ am profile list
+    PROFILE  AGENT        ENV                    ARGS
+    -------  -----------  ---------------------  ----------------
+    dev      claude-code  DEBUG=1 LOG_LEVEL=…    --model sonnet
+    prod     —            LOG_LEVEL=info         —
+
+    $ am start claude-code --profile dev
+    # lance claude --model sonnet avec DEBUG=1 et LOG_LEVEL=debug
+
+    $ am start --profile dev        # agent par défaut du profil
+    $ am start --profile staging    # -> error: unknown profile 'staging' — …
+    #    available profiles: dev, prod
+
+## Dashboard TUI (v0.4.1)
+
+am dashboard ouvre un tableau de bord temps réel (ratatui/crossterm, aucune
+dépendance runtime) : vue d'ensemble (statuts, PID, uptime, ★), activité
+(journal d'événements), stats par agent, sessions et projets. Tab / ← / →
+changent d'onglet, j/k défilent, q quitte ; rafraîchissement chaque seconde.
+Sur une sortie non interactive (pipe, script), un instantané texte est
+affiché à la place :
+
+    $ am dashboard | head
+    agent-manager dashboard — 2 installed · 1 running · 12 sessions
+
+    overview
+      ★ claude-code       running   2.1.233    pid 4242  (up 3h12m)
+        aider             installed 0.76.0     —
+        codex             external  —          —
+
+    $ am dashboard --json   # l'instantané complet en JSON pour les scripts
+
+## Pages de manuel et complétions dynamiques (v0.4.1)
+
+    $ am man dashboard
+    .TH am-dashboard 1  "dashboard "
+    .SH NAME
+    dashboard - Live TUI dashboard: overview, activity, stats, sessions, projects
+    ...
+
+    $ am man --output man/          # am.1 + une page par commande (44 pages)
+    man pages written to man/ (am.1 + 44 pages)
+
+    $ am completion bash --installed   # Tab complète dynamiquement les
+                                        # agents installés, alias et groupes
+                                        # (interroge 'am _agents --installed')

README.md

@@ -76,9 +76,26 @@ plateforme, il compile automatiquement depuis les sources.
 |----------|------|
 | am list | agents installés (gérés + détectés sur le PATH) |
 | am list --all | tout le catalogue, avec l'état de chacun |
-| am search <mot-clé> | recherche par nom, description, catégorie, tag |
+| am search <mot-clé> | recherche fuzzy : tolère les fautes de frappe, classe par pertinence, propose « vouliez-vous dire » |
+| am suggest <requête> | recommande un agent pour une demande en langage naturel (tags + usage réel) |
 | am info <agent> | fiche détaillée (installation, dépendances, site…) |
 | am status [agent] | état, version, PID, logs |
+| am models | inventaire des modèles locaux (ollama, llama.cpp, LM Studio) |
+| am models --prune | purge des modèles inutilisés (--dry-run : simulation) |
+| am catalog update / add <url> | catalogue distant : rafraîchit l'officiel ou ajoute un catalogue d'équipe |
+| am audit | qui a modifié quoi, quand (checksums config + journal) |
+| am sessions --export <id> | export d'une session (métadonnées + commandes + extrait de log) |
+| am sessions --retention <jours> | purge des sessions terminées au-delà de N jours |
+| am init --template <stack> | génère une config pré-remplie (web, python, rust, cli) |
+| am doctor --watch <s> | vérifications périodiques de l'environnement + alerte en cas de panne |
+| am monitor [--json] | TUI temps réel des processus gérés (CPU/RSS/uptime) + alertes de seuils |
+| am stats --costs | coût estimé par agent (tokens in/out, $) — modèles de prix configurables |
+| am sync [--message <m>] | sauvegarde git de l'état (state.json, journal, historique) — secrets exclus |
+| am migrate export/import | bundle de transfert machine A → B (config + état + historique + backups) |
+| am service install <agent> --autostart | service système (systemd / launchd / tâche Windows) + démarrage auto |
+| am schedule add <cmd...> --at HH:MM | planifie une commande am (ex: update --all) ; list / remove / run |
+| am start group:dev --parallel | orchestration de groupes : ordre, --parallel, attente de santé (healthcheck) |
+| am run <agent> --container | exécute l'agent dans son profil conteneur (docker/podman) |
 
 **Statuts** : 🟢 running · 🔵 installed (géré par am) · 🟡 external (trouvé
 sur le PATH) · ⚪ not-installed · 🔴 not-installable (SaaS/desktop)
@@ -90,27 +107,106 @@ sur le PATH) · ⚪ not-installed · 🔴 not-installable (SaaS/desktop)
 | am install <agent> | installe (dépendances vérifiées et proposées) |
 | am install <agent> --method pip | choisit une méthode d'installation |
 | am update <agent> | met à jour vers la dernière version connue |
-| am uninstall <agent> | désinstalle et nettoie (--purge : logs + config) |
+| am config set settings.default_shell pwsh | modifie la configuration sans éditeur |
+| am alias add cc claude-code | raccourci pour un agent (list / remove aussi) |
+| am init | génère un agent-manager.yaml selon la pile du projet (Node/Rust/Python…) |
+| am uninstall <agent> | désinstalle et nettoie (--purge : logs + config) — gère aussi les agents externes (npm/pip/uv/cargo/bun, sinon suppression des fichiers) |
 | am export / am import | sauvegarde et restaure config + état |
 
+### 📁 Où et comment agent-manager installe et gère les agents
+
+`am` ne touche jamais au système : chaque agent est installé dans un **répertoire utilisateur isolé**, et ses exécutables (ou shims) sont centralisés dans un `bin/` commun que `am` met automatiquement sur le `PATH` au lancement.
+
+| Plateforme | Répertoire de l'agent | Dossier `bin` partagé | Fichier d'état | Configuration utilisateur |
+|---|---|---|---|---|
+| Linux | `~/.local/share/agent-manager/agents/<agent>/` | `~/.local/share/agent-manager/bin/` | `~/.local/state/agent-manager/state.json` | `~/.config/agent-manager/config.yaml` |
+| macOS | `~/Library/Application Support/agent-manager/agents/<agent>/` | `~/Library/Application Support/agent-manager/bin/` | `~/Library/Application Support/agent-manager/state.json` | `~/.config/agent-manager/config.yaml` |
+| Windows | `%LOCALAPPDATA%\agent-manager\agents\<agent>\` | `%LOCALAPPDATA%\agent-manager\bin\` | `%LOCALAPPDATA%\agent-manager\state.json` | `%APPDATA%\agent-manager\config.yaml` |
+
+Les variables d'environnement `AGENT_MANAGER_DATA`, `AGENT_MANAGER_STATE` et `AGENT_MANAGER_CONFIG_DIR` peuvent déplacer ces emplacements. Le répertoire d'installation est aussi configurable via `settings.install_dir` et celui des logs via `settings.log_dir`.
+
+#### Cycle d'installation (`am install <agent>`)
+
+1. **Résolution du catalogue** — `am` fusionne le catalogue embarqué (72 agents) avec `~/.config/agent-manager/config.yaml` et un éventuel `./agent-manager.yaml`. Vos définitions remplacent les entrées par défaut du même nom.
+2. **Vérification des dépendances** — les outils requis (`node`, `python`, `uv`, `cargo`, `go`, `bun`, `git`...) sont détectés sur le `PATH`. S'il en manque, `am` détecte l'OS et propose la commande d'installation (`scoop`, `winget`, `apt`, `dnf`, `pacman`, `brew`...). Avec `--yes` ou `settings.auto_install_deps: true`, il peut l'exécuter à votre place.
+3. **Choix de la méthode** — chaque agent déclare une méthode principale et des alternatives. `--method <nom>` force le choix ; sinon `am` prend la première disponible. Pour `am update`, c'est la méthode utilisée lors de l'installation initiale qui est reconstruite.
+4. **Exécution de l'installateur** — selon le type, les commandes réelles lancées sont :
+
+| Méthode | Ce que `am` exécute localement | Où ça atterrit |
+|---|---|---|
+| `npm` | `npm install -g --prefix <root> <package>` | binaires dans `<root>/bin/`, liens ou copie dans `bin/` |
+| `bun` | `BUN_INSTALL=<root> bun install -g <package>` | binaires dans `<root>/bin/`, shims dans `bin/` |
+| `pip` | `python -m venv <root>/venv` puis `<venv>/bin/pip install --upgrade <package>` | exécutables dans `<root>/venv/bin/` |
+| `uv` | `uv venv --python 3.13 <root>/venv` puis `uv pip install --python <venv>/bin/python <package>` | exécutables dans `<root>/venv/bin/` |
+| `cargo` | `cargo install --root <root> <crate>` | binaires dans `<root>/bin/` |
+| `go` | `GOBIN=<bindir> go install <module>@latest` | binaire directement dans `bin/` |
+| `curl` | télécharge le script, l'affiche en `--verbose`, puis l'exécute avec `sh <script>` dans `<root>/` | le script gère son propre déploiement ; `am` repère les binaires résultants |
+| `binary` | télécharge un asset release (`url` ou `repo`), vérifie le `sha256` si fourni, extrait dans `<root>/dist/`, copie dans `bin/` | binaire unique dans `bin/` |
+| `git` | `git clone --depth 1 <repo> <root>/repo`, exécute les commandes `build`, puis copie `binary_path` dans `bin/` ou crée un shim | `bin/<agent>` ou shim |
+
+5. **Post-installation** — `am` exécute les commandes `post_install` déclarées dans la fiche, avec `<bindir>` en tête du `PATH`.
+6. **Détection de version** — `am` lance `<binaire> --version` (puis `-V`) pour enregistrer la version réelle.
+7. **Enregistrement** — une entrée est écrite dans `state.json` (`name`, `version`, `method`, `install_dir`, `bins`, `run`, `installed_at`, `pid`, etc.).
+
+#### Cycle de gestion (`am start / stop / update / uninstall`)
+
+- **Démarrage** — `am start <agent>` lit `state.json` pour retrouver le binaire et la commande `run` configurée. En arrière-plan (`--background`), le PID est enregistré dans `state.json` et la sortie est redirigée vers `<log_dir>/<agent>.log`.
+- **Arrêt** — `am stop` envoie `SIGTERM`, attend `settings.stop_timeout_secs` (5 s par défaut), puis `SIGKILL` si besoin. Le PID est effacé de `state.json`.
+- **Mise à jour** — `am update <agent>` détermine la dernière version disponible (registre npm/PyPI/cargo/release), crée une sauvegarde (`am update --rollback`), réinstalle avec la même méthode et met à jour `state.json`. Les versions épinglées (`pin_version`) sont respectées.
+- **Désinstallation** — `am uninstall <agent>` arrête le processus, supprime `<root>/`, supprime les binaires de `bin/` et efface l'entrée de `state.json`. `--purge` efface aussi les logs et retire la définition du fichier de config utilisateur.
+
 ### 🚀 Exécuter
 
 | Commande | Rôle |
 |----------|------|
-| am start <agent> | avant-plan (Ctrl-C pour quitter) |
-| am start <agent> --background --env KEY=VALEUR | détaché, PID et log gérés |
+| am start [agent] | avant-plan (Ctrl-C pour quitter) — sans argument, lance l'agent par défaut du projet |
+| am start <agent> --background --env KEY=VALEUR | détaché, PID et log gérés ; --env NOM=@secret injecte un secret du trousseau |
 | am stop <agent> | arrêt gracieux puis forcé (--force : immédiat) |
 | am restart <agent> | arrête puis redémarre |
 | am run <agent> [args…] | exécution directe, sans gestion de processus |
 
+### 📊 Observer & retrouver
+
+| Commande | Rôle |
+|----------|------|
+| am stats [agent] --period 7d/30d/90d | statistiques d'utilisation : lancements, durées, échecs, barres ASCII |
+| am top --period | les 10 agents les plus utilisés |
+| am report --last-week / --last-month | digest markdown (lancements, échecs, changements, sessions) |
+| am log [agent] --kind --since --follow | journal des événements : tout ce que am a fait, en direct avec --follow |
+| am timeline --project --since | vue chronologique unifiée (journal + commandes du REPL) |
+| am projects [nom] | quel agent travaille sur quel projet (agent dominant, sessions, durées) |
+| am sessions [agent] --status --show --resume | registre des sessions + reprise d'une session arrêtée |
+| am history --search --failed --rerun N | historique des commandes (am + shell), filtrable et réexécutable |
+| am history 12..25 --save <f> · am playbook <f> | exporte une plage en playbook YAML et la rejoue pas à pas ({{var}}) |
+| am lab --agents a,b --task <f> [--parallel] [--json] | benchmark : même tâche sur plusieurs agents (durée, exit, coût) — tâches versionnables dans <state>/lab/ |
+| am plugins [--test <nom>] | scripts d'extension sur les événements (on_install/on_start/on_stop/on_update), contrat JSON stdin/stdout, timeout — exemples dans examples/plugins/ |
+| am logs <agent> --follow | tail du log d'un agent, en direct |
+| am dashboard | tableau de bord TUI temps réel : vue d'ensemble, activité, stats, sessions, projets (Tab/←/→ : onglets, j/k : défilement, q : quitter) |
+| am web [--port <p>] | dashboard web local en lecture seule (127.0.0.1) : vue d'ensemble, graphiques, sessions, événements, projets — API JSON /api/* avec les mêmes contrats que les sorties --json |
+
+### 🎯 Personnaliser
+
+| Commande | Rôle |
+|----------|------|
+| am favorite <agent> / am unfavorite | étoile ★ dans am list, am status et am info (persistante) |
+| am note <agent> <texte…> | note libre affichée dans am info (am note <agent> : affiche) |
+| am tag <agent> <mot>… / am untag <agent> <mot> | tags personnels, filtrables avec am search --tag |
+| am tags [agent] | liste les tags personnels et les agents qui les portent |
+| am profile list / show | profils d'environnement (env + args + agent par défaut) |
+| am start <agent> --profile dev | lance un agent avec un profil ; am start --profile dev utilise l'agent du profil |
+| am man [commande] --output man/ | génère les pages de manuel (am.1 + une page par commande) |
+
 ### 🧰 Système
 
 | Commande | Rôle |
 |----------|------|
 | am doctor | vérifie outils, config, chemins — avec commandes d'installation |
 | am doctor --fix | répare ce qui peut l'être, propose d'installer les outils manquants |
-| am config show / edit / add | gère votre configuration |
-| am completion <shell> | script de complétion (bash, zsh, fish, powershell) |
+| am watch <agent> --restart --notify | supervise un agent et le relance en cas de crash |
+| am secret set NOM --agent A --value … / list / unset | secrets dans le trousseau du système (jamais en clair) |
+| am config show / edit / add / set | gère votre configuration (hooks on_start/on_stop/… dans settings.hooks) |
+| am open <agent> | ouvre le répertoire d'installation dans l'explorateur |
+| am completion <shell> [--installed] | script de complétion (bash, zsh, fish, powershell, elvish) ; --installed complète dynamiquement les agents installés, alias et groupes |
 | am self-update | met à jour am lui-même (si configuré) |
 | am self-uninstall | désinstalle am et tout ce qu'il a créé (confirmation) |
 | am | shell interactif : bannière, passerelle système, Tab et historique |
@@ -157,6 +253,7 @@ Disponibles avant **ou après** la sous-commande.
 | -v, --verbose | affiche chaque commande exécutée |
 | -q, --quiet | uniquement les erreurs |
 | --no-color | désactive les couleurs |
+| --lang <fr\|en> | langue des messages : fr (défaut) ou en — AM_LANG/LANG lus sinon |
 | -c, --config <fichier> | configuration alternative |
 
 ---
@@ -166,10 +263,18 @@ Disponibles avant **ou après** la sous-commande.
     am start cc               # alias (cc -> claude-code)
     am start group:dev        # démarre tout un groupe en arrière-plan
     am stop group:dev
+    am start cc --profile dev # profil d'environnement : env + args injectés
+
+    am dashboard              # TUI temps réel : toute l'activité d'un coup d'œil
+    am web                    # dashboard web local (ouvre le navigateur) : http://127.0.0.1:7878/
+    am favorite cc && am tag cc python   # personnalisez votre parc
+    am search --tag python    # retrouvez les agents que vous avez tagués
 
     am                        # shell interactif (bannière style Hermes) :
-    ❯ inst<Tab>               # complétion Tab : commandes, agents, groupes, options
+    ❯ inst<Tab>               # complétion Tab : commandes, agents installés, groupes, options
     ❯ install jcode
+    ❯ dashboard               # le dashboard se lance aussi depuis le REPL
+    ❯ web                     # ... et le dashboard web aussi (am web --port pour changer le port)
     ❯ exit                    # historique persistant (flèches haut/bas)
 
 ### 🐚 Passerelle système
@@ -181,13 +286,29 @@ démarrage et mis en évidence** dans la bannière (config
 `settings.default_shell`, puis `SHELL`/`COMSPEC`, puis détection sur le
 PATH — pwsh, powershell, cmd, bash, zsh, fish, sh, nu, elvish).
 
-    ❯ ls                      # exécuté par le shell actif (cmd, pwsh, bash, ...)
+    ❯ ls                      # liste façon Nushell : tableau encadré (type, taille, date)
+    ❯ dir                     # sur Windows, même affichage que ls
+    ❯ ls src                  # un chemin précis — Tab complète fichiers et dossiers
+    ❯ ps                      # liste des processus (pid, ppid, cpu, mem, threads)
+    ❯ ls | where size > 1mb   # filtre la dernière table  (>, <, >=, <=, ==, !=, =~)
+    ❯ ps | where name =~ am   # =~ cherche dans le texte
+    ❯ ls | get name           # sélectionne une colonne
+    ❯ cd <Tab>                # complétion des dossiers — menu interactif façon Nushell
     ❯ shell                   # affiche le shell courant + les shells disponibles
     ❯ shell bash              # change le shell de la session
-    ❯ !list                   # force l'exécution système (même nom qu'une commande am)
+    ❯ !ls · !list             # force l'exécution système (même nom qu'une commande am)
     ❯ cd ~/projets            # change le répertoire de la session (persistant)
     ❯ /help                   # commandes slash : /help · /version · /exit · /shell <nom>
 
+La complétion Tab est un **menu interactif façon Nushell** : une
+correspondance unique est insérée directement ; plusieurs correspondances
+ouvrent un menu sous la ligne avec le **premier choix en surbrillance**, et
+chaque Tab déplace la surbrillance vers le choix suivant (Shift+Tab vers
+l'arrière). **Entrée** valide le choix, **Échap** ferme le menu, les flèches
+↑/↓ naviguent et continuer à taper filtre la liste en direct. Le menu
+affiche une **description** à côté de chaque candidat (commandes et agents)
+et suit la palette du thème actif.
+
 Pour rendre le choix permanent : `settings.default_shell: pwsh` dans
 `config.yaml` (voir `am config path`).
 
@@ -211,7 +332,11 @@ qu'agent-manager possède :
     # macOS
     rm -rf "$HOME/Library/Application Support/agent-manager" "$HOME/.config/agent-manager"
 
-    # Windows (cmd)
+    # Windows — PowerShell
+    Remove-Item -Recurse -Force $env:LOCALAPPDATA\agent-manager, $env:APPDATA\agent-manager -ErrorAction SilentlyContinue
+
+    # Windows — cmd.exe (à ne PAS coller dans PowerShell : rmdir y est un
+    # alias de Remove-Item et le & final lance un job en arrière-plan)
     rmdir /s /q "%LOCALAPPDATA%\agent-manager" & rmdir /s /q "%APPDATA%\agent-manager"
 
 (Si vous utilisiez `AGENT_MANAGER_DATA`/`AGENT_MANAGER_STATE`/`AGENT_MANAGER_CONFIG_DIR`,
@@ -279,6 +404,21 @@ multi-fichiers pris en charge ; configuration validée au démarrage.
 (Windows) — l'état et les logs dans ~/.local/state/agent-manager (Linux) ou
 %LOCALAPPDATA%\\agent-manager (Windows).
 
+**Où vivent les statistiques, les sessions et l'historique ?** Dans le
+répertoire d'état, au format JSON lisible et 100 % local : events-YYYYMM.jsonl
+(journal de chaque action), sessions.json (registre des sessions),
+history/ (historique structuré du shell), projects.json (agrégats par
+projet). Interrogeables avec am stats, am top, am log, am timeline,
+am projects, am sessions et am history.
+
+**Où vivent les secrets ?** Dans le trousseau de votre système (Windows
+Credential Manager, macOS Keychain, Linux Secret Service) — jamais dans la
+configuration ni dans les logs. Injection avec --env NOM=@secret.
+
+**Puis-je automatiser des actions ?** Oui : hooks on_install/on_start/on_stop/
+on_update dans settings.hooks (globaux) ou dans le profil d'un projet, et
+am watch pour superviser un agent avec redémarrage automatique.
+
 **Comment mettre à jour am ?** Relancez l'installeur one-liner (ou
 am self-update si le dépôt de release est configuré).
 

RELEASING.md

@@ -1,62 +1,110 @@
 # Publier une release
 
-Les installateurs one-liner (`install.sh` et `install.ps1`) téléchargent
-les binaires attachés à la **dernière release** du dépôt Gitea
+Les installateurs one-liner (`install.sh` et `install.ps1`), la commande
+`am self-update` et les paquets (scoop/winget/homebrew) consomment les
+**artefacts attachés à la dernière release** du dépôt Gitea
 (https://git.dracodev.net/Projets/agent-manager). Sans binaire pour la
-plateforme, ils retombent sur `cargo install --git` (plus lent mais toujours
-fonctionnel).
+plateforme, les installateurs retombent sur `cargo install --git`.
+
+La phase 1 (v0.4.1) a ajouté le pipeline CI (issue #42) : sur chaque tag
+`v*`, `.gitea/workflows/release.yml` construit Linux (x86_64 + aarch64
+musl statiques), Windows (x86_64) et macOS (x86_64 + aarch64) et publie la
+release. La procédure locale ci-dessous reste disponible pour produire
+manuellement les mêmes artefacts (ou les plateformes sans runner CI).
 
 ## 1. Bumper la version
 
-Dans Cargo.toml (ex. `0.2.1`), puis mettre à jour Cargo.lock
-(`cargo check`) et compiler :
+Dans Cargo.toml (ex. `0.4.1`), puis `cargo check` pour mettre à jour
+Cargo.lock, et lancer toute la batterie :
 
-    cargo build --release          # binaire Windows (am.exe) sur Windows
+    cargo test --locked          # 240+ tests
+    cargo clippy --all-targets -- -D warnings   # si possible
 
-    # binaire Linux STATIQUE (musl) : compatible toutes distributions,
-    # y compris Debian 12 (glibc 2.36) — ne JAMAIS publier un binaire glibc
-    # compilé sur une base récente.
-    docker run --rm -v "${PWD}:/work" -w /work -e CARGO_TARGET_DIR=/tmp/target-musl \
-      rust:1.94-alpine sh -c "apk add --no-cache build-base && \
-      rustup target add x86_64-unknown-linux-musl && \
-      cargo build --release --locked --target x86_64-unknown-linux-musl && \
-      cp /tmp/target-musl/x86_64-unknown-linux-musl/release/am dist/am-linux-x86_64"
+## 2. Produire les binaires et les archives
 
-## 2. Créer les archives des binaires
+### Windows (x86_64) — natif
 
-Windows (PowerShell) :
+    scripts/build-release.ps1    # target/release/am.exe -> dist/am-windows-x86_64.zip
 
-    Compress-Archive target\release\am.exe am-windows-x86_64.zip
+### Linux — binaire STATIQUE (musl), compatible toutes distributions,
+### y compris Debian 12 (glibc 2.36) — ne JAMAIS publier un binaire glibc
+### compilé sur une base récente.
 
-Linux (l'archive doit contenir un fichier nommé « am ») :
+    # cargo-zigbuild : zig (~50 Mo) fournit le linker croisé pour les DEUX
+    # cibles musl (rust:1.94-alpine n'embarque pas de compilateur croisé
+    # aarch64 : 'aarch64-linux-musl-gcc not found').
+    docker run --rm -v "${PWD}:/work" -w /work -e CARGO_TARGET_DIR=/tmp/am-target \
+      -e CARGO_INCREMENTAL=0 rust:1.94-alpine sh -c "apk add --no-cache build-base zip curl >/dev/null && \
+      rustup target add x86_64-unknown-linux-musl aarch64-unknown-linux-musl && \
+      curl -fsSL https://ziglang.org/download/0.14.1/zig-x86_64-linux-0.14.1.tar.xz -o /tmp/zig.tar.xz && \
+      tar -xf /tmp/zig.tar.xz -C /opt && \
+      export PATH=/opt/zig-x86_64-linux-0.14.1:\$PATH && \
+      cargo install cargo-zigbuild --locked && \
+      cargo zigbuild --release --locked --target x86_64-unknown-linux-musl --target aarch64-unknown-linux-musl && \
+      mkdir -p dist && \
+      cp /tmp/am-target/x86_64-unknown-linux-musl/release/am dist/am-linux-x86_64 && \
+      cp /tmp/am-target/aarch64-unknown-linux-musl/release/am dist/am-linux-aarch64 && \
+      cd dist && tar -czf am-linux-x86_64.tar.gz am-linux-x86_64 && \
+      tar -czf am-linux-aarch64.tar.gz am-linux-aarch64"
 
-    docker run --rm -v "${PWD}:/work" -w /work rust:1.94-alpine sh -c \
-      "cd dist && cp am-linux-x86_64 am && tar -czf am-linux-x86_64.tar.gz am && rm am"
+### macOS (x86_64 + aarch64) — via CI (runner macOS) :
 
-## 3. Créer la release sur Gitea
+    # le job 'macos' du workflow release.yml produit :
+    #   am-macos-x86_64.tar.gz  am-macos-aarch64.tar.gz
+    # (compilation croisée macOS impossible depuis Windows/Linux ; sans
+    # runner macOS, ces archives manquent et l'install.sh compile depuis
+    # les sources sur macOS, ce qui reste fonctionnel.)
 
-Via l'interface web : Releases > New Release, tag v0.2.0, attacher les
-archives ci-dessus.
+Vérifier chaque archive : `am version` doit répondre, et `am doctor` ne
+doit signaler aucune dépendance manquante.
 
-Ou via l'API (jeton Gitea requis) :
+## 3. Rendre les manifests de packaging (issue #42)
+
+Une fois toutes les archives dans `dist/` :
+
+    scripts/render-manifests.ps1 -Version 0.4.3
+
+Ce script rend, avec la version et les sha256 réels :
+
+- `dist/scoop/am.json`          → `scoop install dist/scoop/am.json`
+  (ou à ajouter à un bucket ; checkver/autoupdate inclus)
+- `dist/winget/*.yaml`          → à soumettre à microsoft/winget-pkgs
+  (`winget install BrunoDracodev.AgentManager`)
+- `dist/homebrew/am.rb`         → à servir via un tap, ou à soumettre
+- `dist/rpm/am.spec`            → rpmbuild -bb (avec am-linux-x86_64.tar.gz
+  dans ~/rpmbuild/SOURCES)
+- Paquet deb : `packaging/deb/make-deb.sh 0.4.3` → dist/am_0.4.3_amd64.deb
+
+## 4. Créer la release sur Gitea
+
+Via l'interface web : Releases > New Release, tag v0.4.3, attacher les
+archives. Ou via l'API (jeton Gitea requis) :
 
     curl -X POST -H "Authorization: token <JETON>" \
       -H "Content-Type: application/json" \
-      -d '{"tag_name":"v0.2.0","name":"v0.2.0","body":"notes de version"}' \
+      -d '{"tag_name":"v0.4.3","name":"v0.4.3","body":"notes de version"}' \
       https://git.dracodev.net/api/v1/repos/Projets/agent-manager/releases
 
     curl -X POST -H "Authorization: token <JETON>" \
-      -F "attachment=@am-windows-x86_64.zip" \
+      -F "attachment=@dist/am-windows-x86_64.zip" \
       https://git.dracodev.net/api/v1/repos/Projets/agent-manager/releases/<id>/assets?name=am-windows-x86_64.zip
 
-    curl -X POST -H "Authorization: token <JETON>" \
-      -F "attachment=@am-linux-x86_64.tar.gz" \
-      https://git.dracodev.net/api/v1/repos/Projets/agent-manager/releases/<id>/assets?name=am-linux-x86_64.tar.gz
+    # idem pour am-linux-x86_64.tar.gz, am-linux-aarch64.tar.gz,
+    # am-macos-x86_64.tar.gz, am-macos-aarch64.tar.gz (si CI) et
+    # checksums.txt.
 
-## 4. Tag git
+## 5. Tag git (déclenche aussi le pipeline CI)
 
-    git tag v0.2.0 && git push origin v0.2.0
+    git tag v0.4.3 && git push origin v0.4.3
+
+## Conventions de nommage (attendues par les installateurs et self-update)
 
-Les conventions de nommage attendues par les installateurs :
 - am-windows-x86_64.zip (contient am.exe)
 - am-linux-x86_64.tar.gz (contient am)
+- am-linux-aarch64.tar.gz (contient am)
+- am-macos-x86_64.tar.gz / am-macos-aarch64.tar.gz (contiennent am)
+
+## Vérification finale
+
+    am self-update --check     # doit annoncer la nouvelle version
+    am self-update             # met à jour le binaire courant

ROADMAP.md

@@ -0,0 +1,513 @@
+# 🗺️ ROADMAP agent-manager — vers le « super outil »
+
+> **Version du document : 2.2** · Statut : propositions, non engagées
+> Base : analyse du code **v0.2.7** (Rust, 45+ tests, zéro dépendance runtime)
+>
+> ✅ **Phase 0 livrée en v0.3.0 (2026-08-17)** : issues #2 à #16 clôturées,
+> 157 tests, release publiée sur Gitea. Les découpages des phases 1 à 3 sont
+> en place sur Gitea (issues #25 à #80) : v0.4.0, v0.5.0, v1.0.
+>
+> ✅ **Phase 1 livrée en v0.4.1 (2026-08-17)** : 17/17 issues clôturées
+> (#26–#42), 240+ tests. v0.4.0 a livré 13/17 (#26–#32, #34–#38) ; v0.4.1
+> complète avec le dashboard TUI (#33), les favoris/notes/tags (#39), les
+> profils d'environnement (#40), les complétions dynamiques + man pages
+> (#41) et le packaging officiel + CI (#42). Binaires Windows/Linux publiés
+> sur Gitea — am self-update et les installateurs servent la v0.4.1.
+>
+> ✅ **Phase 2 livrée en v0.6.0 (2026-08-19)** : 28/28 issues clôturées
+> (#47–#75), 250+ tests. am web, i18n, services, schedule, lab, sync,
+> migrate, models, plugins d'événements… Binaires publiés sur Gitea.
+>
+> 🔨 **Phase v0.7.0 en cours (priorité P0)** : providers & configuration
+> automatisée (épique #87) — livrée AVANT la Phase 3 (v1.0), voir section 7 bis.
+
+---
+
+## 📖 Sommaire
+
+1. [Résumé exécutif](#1--résumé-exécutif)
+2. [Légende de lecture](#2--légende-de-lecture)
+3. [Quick wins — valeur immédiate](#3--quick-wins--valeur-immédiate)
+4. [État des lieux](#4--état-des-lieux)
+5. [Vision & principes](#5--vision--principes)
+6. [Socle technique : le modèle de données](#6--socle-technique--le-modèle-de-données)
+7. [Les 12 axes](#7--les-12-axes)
+8. [Jalons versionnés](#8--jalons-versionnés)
+9. [Indicateurs de succès (KPI)](#9--indicateurs-de-succès-kpi)
+10. [Risques & garde-fous](#10--risques--garde-fous)
+11. [Par où commencer](#11--par-où-commencer)
+
+---
+
+## 1. 📌 Résumé exécutif
+
+**am** est aujourd'hui un excellent *gestionnaire* d'agents : 72 agents au
+catalogue, 9 méthodes d'installation, dépendances résolues automatiquement,
+processus pilotés, REPL avec passerelle shell, sauvegarde export/import.
+
+Mais il est **aveugle** : il ne retient ni ce qui a été fait, ni quand, ni
+par quel agent, ni dans quel projet, ni avec quel résultat. Les logs sont du
+texte libre non interrogeable, l'état ne contient que les installations et
+le PID courant, l'historique est un simple fichier plat.
+
+Cette roadmap transforme **am** en **cockpit de votre parc d'agents IA** :
+
+| Rôle | Promesse | Porté par |
+|---|---|---|
+| 📓 Journal de bord | tout est tracé, rien ne se perd | Axe 1 (journal d'événements) |
+| 🔎 Rétroviseur | tout est cherchable en 2 secondes | Axes 2, 3, 4 |
+| 📊 Tableau de bord | tout est mesuré | Axes 1, 5, 9 |
+| 🤖 Copilote | il pilote à votre place | Axes 6, 7 |
+
+**Chiffres clés :** 12 axes · ~55 fonctionnalités · 4 jalons (v0.3.0 → v1.0)
+· ~15 semaines de travail cumulé · 0 dépendance runtime ajoutée.
+
+---
+
+## 2. 📚 Légende de lecture
+
+| Symbole | Signification |
+|---|---|
+| **P0** | Fondations — à démarrer tout de suite (socle des autres axes) |
+| **P1** | Court terme — après la phase 0 |
+| **P2** | Moyen terme |
+| **P3** | Vision — long terme |
+| ⭐ | Reprend une demande explicite de l'utilisateur |
+| **S** | Effort : moins d'1 jour |
+| **M** | Effort : 2 à 4 jours |
+| **L** | Effort : 1 à 2 semaines |
+| **XL** | Effort : plus de 2 semaines |
+| ⬜ / 🔨 / ✅ | Proposé / En cours / Livré (rien n'est commencé aujourd'hui) |
+
+---
+
+## 3. ⚡ Quick wins — valeur immédiate
+
+*Tous en effort S, phase P0, sans dépendance sur le socle. Livrables en
+quelques jours, à caler avant ou pendant la construction du journal.*
+
+| Fonctionnalité | Commande | Apport |
+|---|---|---|
+| Voir les logs d'un agent | am logs claude-code (--follow) | tail des logs déjà écrits par process.rs |
+| Filtres sur la liste | am list --running · --sort name,version,status | repérage instantané |
+| Éditer la config sans éditeur | am config set key value | moins de friction YAML |
+| Alias à la volée | am alias add cc claude-code | sans éditer le fichier |
+| Historique propre | dédup + horodatage de history.txt | base saine pour l'axe 2 |
+| Doctor scriptable | am doctor --json | CI et monitoring |
+| Ouvrir l'installation | am open claude-code | explorer le répertoire de l'agent |
+| Version scriptable | am version --json | introspection des scripts |
+
+---
+
+## 4. 🧭 État des lieux (points d'ancrage dans le code)
+
+| Brique actuelle | Fichier | Limite aujourd'hui |
+|---|---|---|
+| Catalogue 72 agents, alias, groupes | src/catalog.rs, config.yaml | recherche = sous-chaîne stricte, pas de ranking |
+| Installation (9 méthodes), dépendances OS | src/installers/, src/deps.rs, src/toolchain.rs | solide — rien à redire |
+| État local | src/state.rs (state.json v1) | installations + PID courant uniquement, **aucun historique** |
+| Détection externe + cache | src/probe.rs | excellent pattern de cache — à généraliser |
+| Processus | src/process.rs | logs non structurés, pas de sessions, pas de métriques |
+| Journal applicatif | src/output.rs | texte libre horodaté, non interrogeable |
+| REPL + passerelle shell | src/repl.rs (history.txt, session_id()) | historique plat, pas de recherche ni de stats |
+| Backup | src/commands/export_import.rs | manuel, pas de synchronisation |
+
+---
+
+## 5. 🎯 Vision & principes directeurs
+
+**Vision :** le cockpit unique du parc d'agents — journal de bord, rétroviseur,
+tableau de bord et copilote.
+
+**Principes :**
+
+1. **Zéro dépendance runtime** — tout est Rust pur et fichiers locaux
+   (JSONL/JSON), jamais de base de données externe.
+2. **Local par défaut, opt-in pour le distant** — la télémétrie n'existe que
+   si l'utilisateur l'active ; tout le reste est 100 % local.
+3. **Contrats stables** — les sorties --json sont la base des scripts et des
+   futurs UI : champs ajoutés, jamais retirés.
+4. **Performance** — écriture en append (JSONL), lectures par fenêtres
+   temporelles, index dérivés régénérables, caches sur le modèle de probe.rs.
+5. **Livraison continue** — chaque phase produit un binaire utilisable et
+   testé ; la barre des 45+ tests monte à chaque jalon.
+
+---
+
+## 6. 🧱 Socle technique : le modèle de données
+
+*Tout dépend de ceci. À construire en premier, avant les commandes visibles.*
+
+    state_dir/
+      state.json            # v2 : + sessions_count, last_used (migration auto depuis v1)
+      events.jsonl          # NOUVEAU — journal d'événements (source de vérité)
+      events-202608.jsonl   # rotation mensuelle
+      sessions.json         # NOUVEAU — registre des sessions (index dérivé)
+      history/
+        <session>.jsonl     # NOUVEAU — historique structuré du REPL
+      projects.json         # NOUVEAU — agrégats par projet (recalculable)
+      probe-cache.json      # existant — pattern de cache à suivre
+
+| Fichier | Rôle | Alimenté par | Reconstruction |
+|---|---|---|---|
+| events.jsonl | faits bruts (start, stop, run, install…) | process.rs, run_cmd.rs, install_cmd.rs, repl.rs, doctor_cmd.rs | source de vérité, jamais reconstruit |
+| sessions.json | index des sessions | dérivé du journal | doctor --fix (rejoue le journal) |
+| projects.json | agrégats par projet | dérivé du journal | doctor --fix |
+| history/*.jsonl | commandes REPL | repl.rs | non (données primaires) |
+| state.json v3 | installations + résumé + annotations (★, notes, tags) | state.rs | partiellement (compteurs depuis le journal) |
+
+**Règles :** JSONL append-only pour les faits · JSON dérivés régénérables ·
+migration additive (state v1 reste lisible partout) · doctor --fix répare
+tout ce qui peut l'être.
+
+---
+
+## 7. 🗂️ Les 12 axes
+
+### Axe 1 — 📊 Observabilité & statistiques d'utilisation ⭐
+
+🎯 Savoir **quoi** a tourné, **quand**, **combien de temps**, avec **quel
+taux de succès** — et **combien ça coûte**.
+
+| Fonctionnalité | Effort | Phase |
+|---|---|---|
+| Journal d'événements events.jsonl (toutes les actions de am) | M | P0 |
+| am stats + --period 7d/30d/90d + --json (tableaux et barres ASCII) | M | P0 |
+| am top — classement des agents par utilisation | S | P1 |
+| am log — filtres agent/type/date, --follow | S → M | P0 → P1 |
+| am report — rapport hebdo/mensuel en markdown (top agents, échecs, changements) | M | P1 |
+| Suivi des coûts — tokens/€ par session quand l'agent expose son usage (Claude Code --output-format json, Codex…) ✅ #49 | M | P2 |
+| am monitor — TUI temps réel : CPU/mémoire par PID, uptime, alertes ✅ #50 | L | P2 |
+| Télémétrie anonyme **opt-in** (compteurs agrégés uniquement, jamais de chemins) | M | P3 |
+
+    am stats                    # vue globale
+    am stats claude-code --period 30d
+    am top                      # qui tourne le plus
+    am report --last-week       # digest markdown
+
+### Axe 2 — 💾 Historique des commandes ⭐
+
+🎯 Gérer, **rechercher** et **réutiliser** tout ce qui a été tapé.
+
+| Fonctionnalité | Effort | Phase |
+|---|---|---|
+| Historique structuré : history/<session>.jsonl (cmd, kind am/shell, cwd, durée, exit, agent) + migration de history.txt | M | P0 |
+| am history — filtres --kind, --cwd, --search, --failed, --session | M | P0 |
+| Ctrl-R + !! + !install + !42 + ^old^new dans le REPL | M | P1 |
+| am history --rerun 42 (réexécution confirmée) | S | P1 |
+| Playbooks : am history 12..25 --save deploy.yaml puis am playbook deploy.yaml ✅ #51 | L | P2 |
+
+    am history --search "install" --failed
+    am history --rerun 42
+
+### Axe 3 — 🧭 Projets & workspaces ⭐
+
+🎯 Centraliser **quel agent travaille sur quel projet** — automatiquement.
+
+| Fonctionnalité | Effort | Phase |
+|---|---|---|
+| Contexte auto au lancement : racine + branche git, stack détectée (Cargo.toml, package.json…), mis en cache | S | P0 |
+| am projects / am projects api — agents, sessions, durées, dernière activité | M | P1 |
+| Profils de projet dans config : default_agent, env, hooks | M | P1 |
+| am start (sans argument) = agent par défaut du dossier courant ; REPL contextuel | S | P1 |
+| am init — génère un agent-manager.yaml selon la stack détectée | S → M | P0 |
+| Templates : am init --template web | M | P2 |
+
+    am projects
+    am projects api
+    am init            # dans un projet Node → config pré-remplie
+
+### Axe 4 — 🗂️ Sessions centralisées ⭐
+
+🎯 Un registre unique de **toutes les sessions de tous les agents** —
+consultable, reprenable, archivable.
+
+| Fonctionnalité | Effort | Phase |
+|---|---|---|
+| sessions.json + session_id() partagé (repl.rs) ; fin de session avec exit code et durée | M | P0 |
+| Réconciliation au démarrage : sessions interrompues (crash, reboot) marquées et datées | S | P0 |
+| am sessions — filtres agent/projet/statut ; show = résumé + extrait de log | M | P0 |
+| am timeline — vue chronologique unifiée de toute l'activité | M | P1 |
+| am sessions resume <id> — relance avec les mêmes args/env/cwd | M | P1 |
+| am sessions export <id> + rétention configurable (settings.sessions_retention_days) | M | P2 |
+
+    am sessions --status failed
+    am sessions show 20260815_143926_a1b2c3
+    am timeline --project api
+
+### Axe 5 — 🖥️ Tableau de bord
+
+🎯 Voir l'état du parc d'un coup d'œil.
+
+| Fonctionnalité | Effort | Phase |
+|---|---|---|
+| am dashboard — TUI (ratatui/crossterm) : vue d'ensemble, activité en direct, stats, sessions, projets | L | P1 |
+| am web — serveur local + API JSON + page HTML embarquée avec graphiques | XL | P2 |
+
+### Axe 6 — 🤖 Automatisation & orchestration
+
+🎯 Laisser am **superviser et piloter seul** le parc.
+
+| Fonctionnalité | Effort | Phase |
+|---|---|---|
+| Hooks on_install / on_start / on_stop / on_update (agent, projet, global) — via le runner existant | M | P0 |
+| am watch claude-code --restart-on-crash --notify | M | P1 |
+| Services : unités systemd / plists launchd / tâches Windows, am service install claude-code --autostart ✅ #55 | L | P2 |
+| Planification : am schedule add update --all --at 06:30 + check santé (cron / Task Scheduler) ✅ #56 | M | P2 |
+| Orchestration de groupes : ordre, --parallel, attente de santé ✅ #57 | L | P2 |
+| Conteneurs : profil docker/podman par agent (isolation à la demande) ✅ #58 | L | P2 |
+| am doctor --watch — vérifications périodiques avec alertes ✅ #59 | M | P2 |
+
+### Axe 7 — 🧠 Intelligence & catalogue
+
+🎯 Trouver le bon agent, suivre leurs sorties, et comparer.
+
+| Fonctionnalité | Effort | Phase |
+|---|---|---|
+| Recherche fuzzy dans am search (typos, scoring, « vouliez-vous dire ») | M | P1 |
+| am compare a b — tableau côte à côte (méthode, deps, catégorie, activité) | S | P1 |
+| am news — dernières releases des agents installés (API GitHub/Gitea, cache) | M | P1 |
+| Catalogue distant : am catalog update / am catalog add <url> | M | P2 |
+| am suggest "un agent pour du Python" — tags + usage réel | M | P2 |
+| am lab — benchmark : même tâche sur N agents, comparaison durée/résultat/coût | L | P2 |
+| Registre communautaire : publier son catalogue (Gitea) + am registry | L | P3 |
+| am ask "installe claude et lance-le" — langage naturel → commande am (fournisseur LLM configurable, optionnel) | L | P3 |
+
+### Axe 8 — 🔒 Sécurité & gouvernance
+
+🎯 Protéger les secrets, tracer les changements, pouvoir revenir en arrière.
+
+| Fonctionnalité | Effort | Phase |
+|---|---|---|
+| am secret set OPENAI_KEY --agent claude-code (keyring OS) + injection --env automatique | M | P1 |
+| am audit — qui a modifié quoi quand (checksums des configs, événements) | M | P2 |
+| am update --rollback — backup automatique avant chaque mise à jour | M | P2 |
+| Politiques : pin de version, settings.update_policy | S | P2 |
+| Profils sandbox par agent (commandes/répertoires autorisés) | L | P3 |
+
+### Axe 9 — 🌐 Multi-machine & collaboration
+
+🎯 Retrouver son cockpit partout, et le partager.
+
+| Fonctionnalité | Effort | Phase |
+|---|---|---|
+| Synchronisation git automatique : settings.sync_repo, am sync, push à la fermeture du REPL ✅ #66 | L | P2 |
+| Partage de catalogue d'équipe : include par URL | S | P2 |
+| am migrate — assistant de transfert machine A → B ✅ #68 | M | P2 |
+| am serve --token — API HTTP + WebSocket pour piloter à distance | XL | P3 |
+
+### Axe 10 — 🧩 Confort & personnalisation
+
+🎯 Adapter am à sa façon de travailler.
+
+| Fonctionnalité | Effort | Phase |
+|---|---|---|
+| Favoris : am favorite / am unfavorite + ⭐ dans am list | S | P1 |
+| Notes : am note claude-code "utiliser pour …" | S | P1 |
+| Tags personnels : am tag claude-code python | S | P1 |
+| Raccourcis de commandes : settings.shortcuts (i → install, s → start) | S | P1 |
+| Profils d'environnement : am profile dev / prod (env + args + agent par profil) | M | P1 |
+| Thèmes couleurs du REPL | S | P2 |
+
+### Axe 11 — 🎛️ Modèles locaux
+
+🎯 Étendre le cockpit aux modèles : **ollama, llama.cpp, LM Studio**.
+
+| Fonctionnalité | Effort | Phase |
+|---|---|---|
+| am models — inventaire : nom, taille disque, quantisation, dernière utilisation | M | P2 |
+| Lien agent ↔ modèle : am run mon-agent --model llama3.1 | M | P2 |
+| doctor vérifie ollama / llama-server comme n'importe quel outil | S | P2 |
+| am models prune — purge des modèles inutilisés | S | P2 |
+
+### Axe 12 — 🛠️ Écosystème & expérience développeur
+
+🎯 Rendre am disponible partout et contribuable.
+
+| Fonctionnalité | Effort | Phase |
+|---|---|---|
+| Fixtures d'événements rejouables + tests de bout en bout du journal | S | P0 |
+| Packaging officiel : winget, scoop, deb/rpm, Homebrew + CI de release | M | P1 |
+| Complétions dynamiques (agents installés, groupes personnalisés) | S | P1 |
+| Man pages + documentation générée | S | P1 |
+| i18n : messages EN/FR | L | P2 |
+| Plugin scripts (hooks avancés, intégration CI) | M | P2 |
+
+---
+
+## 8. 🚀 Jalons versionnés
+
+| Jalon | Version | Contenu principal | Durée | Critère de sortie |
+|---|---|---|---|---|
+| **J0 — Fondations** | v0.3.0 | events.jsonl, sessions, am stats, am log, am history, am init, quick wins | ≈ 2 sem | 100 % des actions tracées · 100+ tests |
+| **J1 — Cockpit** | v0.4.0 | recherche fuzzy, Ctrl-R, projects, timeline, dashboard TUI, hooks, secret, favoris, packaging | ≈ 3 sem | retrouver n'importe quelle action passée en < 2 s |
+| **J2 — Automatisation** | v0.5.0 | watch, services, schedule, news/compare, catalogue distant, lab, models, sync | ≈ 4 sem | parc auto-supervisé (crash = redémarrage + alerte) |
+| **J3 — Plateforme** | v1.0 | am web, am serve, am ask, registry, télémétrie opt-in, sandbox | ≈ 6 sem | dashboard web complet + API distante |
+
+---
+
+## 9. 📈 Indicateurs de succès (KPI)
+
+| Indicateur | Cible |
+|---|---|
+| Part des actions tracées dans events.jsonl | 100 % dès la v0.3.0 |
+| Temps pour retrouver une commande ou session passée | < 2 s |
+| am list à chaud, journal actif | < 100 ms |
+| Dépendances runtime ajoutées | 0 |
+| Couverture de tests | ≥ 100 tests en v0.3, +25 par jalon |
+| Contrats --json cassés entre versions mineures | 0 |
+
+---
+
+## 10. ⚠️ Risques & garde-fous
+
+1. **ADN « zéro runtime »** : toute dépendance nouvelle est compilée dans le
+   binaire, jamais requise à l'exécution.
+2. **Performance** : le journal grossit — fenêtres temporelles, index dérivés,
+   rotation mensuelle, caches façon probe.rs.
+3. **Vie privée** : local par défaut ; télémétrie opt-in, agrégée, anonyme.
+4. **Contrats --json** : ajout de champs sans retrait (scripts utilisateurs).
+5. **Compatibilité** : migrations additives ; les exports 0.2.x restent
+   importables en 0.3+.
+6. **Complexité UX** : les fonctions avancées restent derrière
+   settings.experimental jusqu'à maturité.
+7. **Périmètre** : rester un orchestrateur — ne pas réimplémenter les
+   fonctionnalités propres aux agents (tokens, MCP, prompts), sauf valeur
+   transversale (stats, sessions, secrets, coûts).
+
+---
+
+## 11. 🏁 Par où commencer
+
+*Le suivi est en place sur Gitea : 4 milestones (v0.3.0 → v1.0), 22 labels
+(P0–P3, axe-1…axe-12, S/M/L/XL, quick-win, epic) et les issues ci-dessous.
+Chaque PR doit référencer son issue avec `closes #N` pour une clôture
+automatique. Ordre de construction proposé pour la phase 0 — chaque étape
+est un PR indépendant et testé :*
+
+1. **[PR 1](https://git.dracodev.net/Projets/agent-manager/issues/2)** — src/events.rs : journal JSONL + rotation + tests.
+2. **[PR 2](https://git.dracodev.net/Projets/agent-manager/issues/3)** — instrumentation start/stop/run (process.rs, run_cmd.rs) — dépend de PR 1.
+3. **[PR 3](https://git.dracodev.net/Projets/agent-manager/issues/4)** — state.json v2 + migration additive — dépend de PR 1.
+4. **[PR 4](https://git.dracodev.net/Projets/agent-manager/issues/5)** — sessions.json + am sessions + réconciliation — dépend de PR 2.
+5. **[PR 5](https://git.dracodev.net/Projets/agent-manager/issues/6)** — am stats + am log (lecture du journal) — dépend de PR 2.
+6. **[PR 6](https://git.dracodev.net/Projets/agent-manager/issues/7)** — historique structuré + am history (migration de history.txt).
+7. **[PR 7](https://git.dracodev.net/Projets/agent-manager/issues/8)** — am init + détection de contexte (git, stack, cache) — dépend de PR 1.
+8. **En parallèle** — les quick wins de la section 3 :
+   [am logs #9](https://git.dracodev.net/Projets/agent-manager/issues/9) ·
+   [am list --sort #10](https://git.dracodev.net/Projets/agent-manager/issues/10) ·
+   [am config set #11](https://git.dracodev.net/Projets/agent-manager/issues/11) ·
+   [am alias add #12](https://git.dracodev.net/Projets/agent-manager/issues/12) ·
+   [dedup history.txt #13](https://git.dracodev.net/Projets/agent-manager/issues/13) ·
+   [am doctor --json #14](https://git.dracodev.net/Projets/agent-manager/issues/14) ·
+   [am version --json #15](https://git.dracodev.net/Projets/agent-manager/issues/15) ·
+   [am open #16](https://git.dracodev.net/Projets/agent-manager/issues/16).
+
+Épique de suivi : [issue #1](https://git.dracodev.net/Projets/agent-manager/issues/1) (Phase 0).
+
+### Phase 1 — Cockpit (v0.4.0) — découpage créé le 2026-08-17
+
+Épique : [issue #25](https://git.dracodev.net/Projets/agent-manager/issues/25) · milestone v0.4.0 · 17 issues.
+
+| # | Issue | Effort |
+|---|---|---|
+| [#26](https://git.dracodev.net/Projets/agent-manager/issues/26) | Recherche fuzzy dans am search | M |
+| [#27](https://git.dracodev.net/Projets/agent-manager/issues/27) | Ctrl-R + réexécution dans le REPL | M |
+| [#28](https://git.dracodev.net/Projets/agent-manager/issues/28) | am history --rerun N | S |
+| [#29](https://git.dracodev.net/Projets/agent-manager/issues/29) | am projects + profils de projet | M |
+| [#30](https://git.dracodev.net/Projets/agent-manager/issues/30) | am start contextuel (dépend de #29) | S |
+| [#31](https://git.dracodev.net/Projets/agent-manager/issues/31) | am timeline (vue chronologique unifiée) | M |
+| [#32](https://git.dracodev.net/Projets/agent-manager/issues/32) | am sessions resume <id> | M |
+| [#33](https://git.dracodev.net/Projets/agent-manager/issues/33) | am dashboard (TUI temps réel) | L |
+| [#34](https://git.dracodev.net/Projets/agent-manager/issues/34) | Hooks on_install/on_start/on_stop/on_update | M |
+| [#35](https://git.dracodev.net/Projets/agent-manager/issues/35) | am watch --restart-on-crash --notify | M |
+| [#36](https://git.dracodev.net/Projets/agent-manager/issues/36) | am secret (keyring OS) + injection --env | M |
+| [#37](https://git.dracodev.net/Projets/agent-manager/issues/37) | am top + am report (rapport hebdo/mensuel) | M |
+| [#38](https://git.dracodev.net/Projets/agent-manager/issues/38) | am log --follow (flux en direct) | S |
+| [#39](https://git.dracodev.net/Projets/agent-manager/issues/39) | Favoris, notes et tags personnels | M |
+| [#40](https://git.dracodev.net/Projets/agent-manager/issues/40) | Profils d'environnement (am profile dev/prod) | M |
+| [#41](https://git.dracodev.net/Projets/agent-manager/issues/41) | Complétions dynamiques + man pages | S |
+| [#42](https://git.dracodev.net/Projets/agent-manager/issues/42) | Packaging officiel (winget/scoop/deb/Homebrew) + CI | M |
+
+Critère de sortie du jalon : retrouver n'importe quelle action passée en
+moins de 2 secondes.
+
+### Phase 2 — Automatisation (v0.5.0) — découpage créé le 2026-08-17
+
+Épique : [issue #47](https://git.dracodev.net/Projets/agent-manager/issues/47) · milestone v0.5.0 · 27 issues.
+
+| # | Issue | Effort |
+|---|---|---|
+| [#49](https://git.dracodev.net/Projets/agent-manager/issues/49) | Suivi des coûts — tokens/€ par session (stats --costs, cost_models) ✅ | M |
+| [#50](https://git.dracodev.net/Projets/agent-manager/issues/50) | am monitor — TUI temps réel (CPU/mémoire par PID, alertes) ✅ | L |
+| [#51](https://git.dracodev.net/Projets/agent-manager/issues/51) | ✅ Playbooks — am history --save + am playbook | L |
+| [#52](https://git.dracodev.net/Projets/agent-manager/issues/52) | ✅ Templates — am init --template web/python/rust/cli (substitution + validation) | M |
+| [#53](https://git.dracodev.net/Projets/agent-manager/issues/53) | ✅ am sessions export + rétention configurable (sessions_retention_days) | M |
+| [#54](https://git.dracodev.net/Projets/agent-manager/issues/54) | ✅ am web — serveur local + API JSON + graphiques (dashboard embarqué, contrats --json, 127.0.0.1) | XL |
+| [#55](https://git.dracodev.net/Projets/agent-manager/issues/55) | Services système — am service install (systemd/launchd/tâches Windows) ✅ | L |
+| [#56](https://git.dracodev.net/Projets/agent-manager/issues/56) | Planification — am schedule (add --at / list / remove / run) ✅ | M |
+| [#57](https://git.dracodev.net/Projets/agent-manager/issues/57) | Orchestration de groupes (ordre, --parallel, attente de santé) ✅ | L |
+| [#58](https://git.dracodev.net/Projets/agent-manager/issues/58) | Conteneurs — profils docker/podman par agent ✅ | L |
+| [#59](https://git.dracodev.net/Projets/agent-manager/issues/59) | am doctor --watch — vérifications périodiques avec alertes ✅ | M |
+| [#60](https://git.dracodev.net/Projets/agent-manager/issues/60) | ✅ Catalogue distant — am catalog update / am catalog add <url> | M |
+| [#61](https://git.dracodev.net/Projets/agent-manager/issues/61) | ✅ am suggest — « un agent pour du Python » (tags + usage réel) | M |
+| [#62](https://git.dracodev.net/Projets/agent-manager/issues/62) | ✅ am lab — benchmark : même tâche sur N agents | L |
+| [#63](https://git.dracodev.net/Projets/agent-manager/issues/63) | ✅ am audit — qui a modifié quoi quand | M |
+| [#64](https://git.dracodev.net/Projets/agent-manager/issues/64) | ✅ am update --rollback — backup automatique avant mise à jour | M |
+| [#65](https://git.dracodev.net/Projets/agent-manager/issues/65) | ✅ Politiques — pin de version, settings.update_policy | S |
+| [#66](https://git.dracodev.net/Projets/agent-manager/issues/66) | ✅ Synchronisation git automatique — am sync (sync_repo, sync_on_exit, secrets exclus) | L |
+| [#67](https://git.dracodev.net/Projets/agent-manager/issues/67) | ✅ Partage de catalogue d'équipe (include par URL) | S |
+| [#68](https://git.dracodev.net/Projets/agent-manager/issues/68) | ✅ am migrate — assistant de transfert machine A → B (bundle .amx + doctor) | M |
+| [#69](https://git.dracodev.net/Projets/agent-manager/issues/69) | ✅ Thèmes couleurs du REPL | S |
+| [#70](https://git.dracodev.net/Projets/agent-manager/issues/70) | ✅ am models — inventaire des modèles locaux (ollama, llama.cpp, LM Studio) | M |
+| [#71](https://git.dracodev.net/Projets/agent-manager/issues/71) | ✅ Lien agent ↔ modèle — am run --model | M |
+| [#72](https://git.dracodev.net/Projets/agent-manager/issues/72) | ✅ doctor vérifie ollama / llama-server comme n'importe quel outil | S |
+| [#73](https://git.dracodev.net/Projets/agent-manager/issues/73) | ✅ am models prune — purge des modèles inutilisés | S |
+| [#74](https://git.dracodev.net/Projets/agent-manager/issues/74) | ✅ i18n — messages EN/FR (--lang, AM_LANG/LANG, catalogue tr/tr_fmt) | L |
+| [#75](https://git.dracodev.net/Projets/agent-manager/issues/75) | ✅ Plugin scripts (hooks avancés, intégration CI) | M |
+
+Critère de sortie du jalon : parc auto-supervisé (crash = redémarrage +
+alerte).
+
+### Phase 3 — Plateforme (v1.0) — découpage créé le 2026-08-17
+
+Épique : [issue #48](https://git.dracodev.net/Projets/agent-manager/issues/48) · milestone v1.0 · 5 issues.
+
+| # | Issue | Effort |
+|---|---|---|
+| [#76](https://git.dracodev.net/Projets/agent-manager/issues/76) | ✅ Télémétrie anonyme opt-in (compteurs agrégés uniquement) | M |
+| [#77](https://git.dracodev.net/Projets/agent-manager/issues/77) | ✅ Registre communautaire — am registry (publication + recherche sur Gitea) | L |
+| [#78](https://git.dracodev.net/Projets/agent-manager/issues/78) | ✅ am ask — langage naturel → commande am (fournisseur LLM optionnel) | L |
+| [#79](https://git.dracodev.net/Projets/agent-manager/issues/79) | ✅ Profils sandbox par agent (commandes/répertoires autorisés) | L |
+| [#80](https://git.dracodev.net/Projets/agent-manager/issues/80) | ✅ am serve --token — API HTTP + WebSocket pour piloter à distance | XL |
+
+Critère de sortie du jalon : dashboard web complet + API distante.
+
+### Phase v0.7.0 — Providers & configuration automatisée (P0, PRIORITAIRE)
+
+Épique : [issue #87](https://git.dracodev.net/Projets/agent-manager/issues/87)
+· milestone v0.7.0 · 5 issues · **priorité P0 : livrée AVANT la Phase 3
+(v1.0, #76–#80 en P3), sauf dépendances**.
+
+Centralise tokens/providers/modèles dans UN registre (settings.providers +
+keyring partagé) et configure automatiquement les agents à l'installation :
+`am install <agent>` branche le provider/modèle par défaut,
+`--provider/--model` pour surcharger, `--no-config` pour le comportement
+actuel, `am run --provider` pour surcharger au lancement (cloud inclus).
+S'appuie sur #36 (secrets), #40 (profils), #71 (modèle), #66 (sync) — livrés.
+
+| # | Issue | Effort | Dépend de |
+|---|---|---|---|
+| [#88](https://git.dracodev.net/Projets/agent-manager/issues/88) | ✅ Registre de providers + commandes `am providers` (settings.providers, default_provider) | M | — |
+| [#89](https://git.dracodev.net/Projets/agent-manager/issues/89) | ✅ Secrets partagés par provider (namespace keyring + résolution `@secret` fallback) | S | #88 |
+| [#90](https://git.dracodev.net/Projets/agent-manager/issues/90) | ✅ AgentDef provider/model + flags `--provider/--model/--no-config` à l'install | M | #88 |
+| [#91](https://git.dracodev.net/Projets/agent-manager/issues/91) | ✅ Configuration post-install : bloc `config:` par agent (env_map + fichiers) | L | #89, #90 |
+| [#92](https://git.dracodev.net/Projets/agent-manager/issues/92) | ✅ `am run/start --provider` : override au lancement (providers cloud inclus) | M | #90 |
+
+Critère de sortie du jalon : un agent installé est opérationnel sans
+configuration manuelle (tokens au keyring, provider/modèle par défaut).
+
+---
+
+*Document généré à partir de l'analyse du code (v0.2.7, commit d886de3).
+La phase 0 est livrée (v0.3.0) ; les découpages des phases 1 (v0.4.0),
+2 (v0.5.0) et 3 (v1.0) sont en place sur Gitea (issues #25 à #80).*

build.rs

@@ -0,0 +1,32 @@
+//! Record build metadata (git commit and branch) at compile time so the
+//! 'am version' command can display it, like Nushell's version table.
+//!
+//! When git is unavailable (e.g. building from a source tarball) the values
+//! are simply empty.
+
+use std::process::Command;
+
+fn git(args: &[&str]) -> String {
+    Command::new("git")
+        .args(args)
+        .output()
+        .ok()
+        .filter(|o| o.status.success())
+        .map(|o| String::from_utf8_lossy(&o.stdout).trim().to_string())
+        .unwrap_or_default()
+}
+
+fn main() {
+    println!("cargo:rerun-if-changed=.git/HEAD");
+    println!("cargo:rerun-if-changed=.git/refs/heads");
+    let commit = git(&["rev-parse", "HEAD"]);
+    let branch = git(&["rev-parse", "--abbrev-ref", "HEAD"]);
+    // A detached HEAD reports the literal branch name "HEAD".
+    let branch = if branch == "HEAD" {
+        String::new()
+    } else {
+        branch
+    };
+    println!("cargo:rustc-env=AM_GIT_COMMIT={commit}");
+    println!("cargo:rustc-env=AM_GIT_BRANCH={branch}");
+}

completions/am.elv

@@ -20,6 +20,7 @@ set edit:completion:arg-completer[am] = {|@words|
         &'am'= {
             cand -c 'Use an alternate configuration file'
             cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
             cand -v 'Verbose output: show every command executed and its details'
             cand --verbose 'Verbose output: show every command executed and its details'
             cand -q 'Quiet mode: only errors are printed'
@@ -33,31 +34,445 @@ set edit:completion:arg-completer[am] = {|@words|
             cand --help 'Print help (see more with ''--help'')'
             cand -V 'Print version'
             cand --version 'Print version'
-            cand list 'List agents: installed ones, or every agent known to the catalog'
+            cand list 'List installed agents (default); use --all for the whole catalog'
+            cand logs 'Tail the log file of an agent (--follow for a live view)'
+            cand open 'Open an agent''s installation directory in the file manager'
+            cand watch 'Supervise an agent and optionally restart it on crash'
+            cand dashboard 'Live TUI dashboard: overview, activity, stats, sessions, projects'
+            cand favorite 'Mark an agent as a favorite (star in list and status)'
+            cand unfavorite 'Remove the favorite star from an agent'
+            cand note 'Attach a free-form note to an agent (shown in ''am info''); ''am note <agent>'' without text prints the current note'
+            cand tag 'Add a personal tag to an agent'
+            cand untag 'Remove a personal tag from an agent'
+            cand tags 'List personal tags (with counts), optionally for one agent'
+            cand profile 'Manage environment profiles (dev, prod, ...)'
+            cand man 'Generate a man page for am (or for one command)'
+            cand _agents 'Internal: list agent names for shell completions (hidden)'
+            cand alias 'Manage command aliases (cc -> claude-code)'
+            cand secret 'Manage secrets in the OS keyring (never in plaintext config)'
             cand start 'Start an agent (foreground by default, or detached with --background)'
             cand stop 'Stop a background agent (SIGTERM, then SIGKILL after the timeout)'
             cand restart 'Restart an agent: stop, then start with the same options'
             cand status 'Show the state of one agent, or of every installed agent'
+            cand sessions 'List the sessions of every agent (and of the interactive shell)'
+            cand stats 'Show usage statistics computed from the event journal'
+            cand top 'Show the most used agents (top 10)'
+            cand report 'Write a markdown activity report'
+            cand projects 'Show which agent works on which project'
+            cand timeline 'One chronological view of every activity (journal + REPL history)'
+            cand log 'Read the event journal: everything am did'
             cand install 'Install an agent and its dependencies'
-            cand uninstall 'Uninstall an agent and clean its files'
+            cand uninstall 'Uninstall an agent (managed or external) and clean its files'
             cand update 'Update an installed agent to the latest available version'
             cand search 'Search the catalog by keyword (name, description, category, tags)'
+            cand history 'Search the command history (am and shell commands)'
             cand info 'Show detailed information about one agent'
+            cand init 'Generate a local agent-manager.yaml for the current directory'
+            cand help 'Display help: the overview, a command, the command list, or a search'
+            cand version 'Display version and build information'
             cand config 'Manage the configuration file'
             cand doctor 'Check the environment: tools, config validity, paths, permissions'
             cand run 'Run the agent command directly with the given arguments (no process management)'
             cand completion 'Generate a shell completion script'
             cand self-update 'Update agent-manager itself from GitHub Releases'
+            cand self-uninstall 'Remove agent-manager and everything it created from this machine'
             cand export 'Export the configuration and installation state (backup)'
             cand import 'Import a previously exported configuration and state'
-            cand help 'Print this message or the help of the given subcommand(s)'
         }
         &'am;list'= {
             cand --category 'Only show agents of this category'
+            cand --sort 'Sort by name, version or status (default: name)'
             cand -c 'Use an alternate configuration file'
             cand --config 'Use an alternate configuration file'
-            cand --installed-only 'Only show agents that are installed (managed or external)'
-            cand --all 'Include hidden agents as well'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
+            cand --all 'Show every agent known to the catalog, not only the installed ones'
+            cand --running 'Only show running agents'
+            cand -v 'Verbose output: show every command executed and its details'
+            cand --verbose 'Verbose output: show every command executed and its details'
+            cand -q 'Quiet mode: only errors are printed'
+            cand --quiet 'Quiet mode: only errors are printed'
+            cand -y 'Answer yes to every confirmation prompt'
+            cand --yes 'Answer yes to every confirmation prompt'
+            cand --dry-run 'Simulate the action without changing anything'
+            cand --json 'Emit machine-readable JSON on stdout (for scripts)'
+            cand --no-color 'Disable ANSI colors'
+            cand -h 'Print help'
+            cand --help 'Print help'
+        }
+        &'am;logs'= {
+            cand --lines 'Number of lines to show (default: 20)'
+            cand -c 'Use an alternate configuration file'
+            cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
+            cand --follow 'Follow the log as it grows'
+            cand -v 'Verbose output: show every command executed and its details'
+            cand --verbose 'Verbose output: show every command executed and its details'
+            cand -q 'Quiet mode: only errors are printed'
+            cand --quiet 'Quiet mode: only errors are printed'
+            cand -y 'Answer yes to every confirmation prompt'
+            cand --yes 'Answer yes to every confirmation prompt'
+            cand --dry-run 'Simulate the action without changing anything'
+            cand --json 'Emit machine-readable JSON on stdout (for scripts)'
+            cand --no-color 'Disable ANSI colors'
+            cand -h 'Print help'
+            cand --help 'Print help'
+        }
+        &'am;open'= {
+            cand -c 'Use an alternate configuration file'
+            cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
+            cand -v 'Verbose output: show every command executed and its details'
+            cand --verbose 'Verbose output: show every command executed and its details'
+            cand -q 'Quiet mode: only errors are printed'
+            cand --quiet 'Quiet mode: only errors are printed'
+            cand -y 'Answer yes to every confirmation prompt'
+            cand --yes 'Answer yes to every confirmation prompt'
+            cand --dry-run 'Simulate the action without changing anything'
+            cand --json 'Emit machine-readable JSON on stdout (for scripts)'
+            cand --no-color 'Disable ANSI colors'
+            cand -h 'Print help'
+            cand --help 'Print help'
+        }
+        &'am;watch'= {
+            cand --interval 'Check interval in seconds (default: 5)'
+            cand -c 'Use an alternate configuration file'
+            cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
+            cand --restart 'Restart the agent automatically when it dies (with backoff)'
+            cand --notify 'Desktop notification on every restart'
+            cand -v 'Verbose output: show every command executed and its details'
+            cand --verbose 'Verbose output: show every command executed and its details'
+            cand -q 'Quiet mode: only errors are printed'
+            cand --quiet 'Quiet mode: only errors are printed'
+            cand -y 'Answer yes to every confirmation prompt'
+            cand --yes 'Answer yes to every confirmation prompt'
+            cand --dry-run 'Simulate the action without changing anything'
+            cand --json 'Emit machine-readable JSON on stdout (for scripts)'
+            cand --no-color 'Disable ANSI colors'
+            cand -h 'Print help'
+            cand --help 'Print help'
+        }
+        &'am;dashboard'= {
+            cand -c 'Use an alternate configuration file'
+            cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
+            cand -v 'Verbose output: show every command executed and its details'
+            cand --verbose 'Verbose output: show every command executed and its details'
+            cand -q 'Quiet mode: only errors are printed'
+            cand --quiet 'Quiet mode: only errors are printed'
+            cand -y 'Answer yes to every confirmation prompt'
+            cand --yes 'Answer yes to every confirmation prompt'
+            cand --dry-run 'Simulate the action without changing anything'
+            cand --json 'Emit machine-readable JSON on stdout (for scripts)'
+            cand --no-color 'Disable ANSI colors'
+            cand -h 'Print help'
+            cand --help 'Print help'
+        }
+        &'am;favorite'= {
+            cand -c 'Use an alternate configuration file'
+            cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
+            cand -v 'Verbose output: show every command executed and its details'
+            cand --verbose 'Verbose output: show every command executed and its details'
+            cand -q 'Quiet mode: only errors are printed'
+            cand --quiet 'Quiet mode: only errors are printed'
+            cand -y 'Answer yes to every confirmation prompt'
+            cand --yes 'Answer yes to every confirmation prompt'
+            cand --dry-run 'Simulate the action without changing anything'
+            cand --json 'Emit machine-readable JSON on stdout (for scripts)'
+            cand --no-color 'Disable ANSI colors'
+            cand -h 'Print help'
+            cand --help 'Print help'
+        }
+        &'am;unfavorite'= {
+            cand -c 'Use an alternate configuration file'
+            cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
+            cand -v 'Verbose output: show every command executed and its details'
+            cand --verbose 'Verbose output: show every command executed and its details'
+            cand -q 'Quiet mode: only errors are printed'
+            cand --quiet 'Quiet mode: only errors are printed'
+            cand -y 'Answer yes to every confirmation prompt'
+            cand --yes 'Answer yes to every confirmation prompt'
+            cand --dry-run 'Simulate the action without changing anything'
+            cand --json 'Emit machine-readable JSON on stdout (for scripts)'
+            cand --no-color 'Disable ANSI colors'
+            cand -h 'Print help'
+            cand --help 'Print help'
+        }
+        &'am;note'= {
+            cand -c 'Use an alternate configuration file'
+            cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
+            cand -v 'Verbose output: show every command executed and its details'
+            cand --verbose 'Verbose output: show every command executed and its details'
+            cand -q 'Quiet mode: only errors are printed'
+            cand --quiet 'Quiet mode: only errors are printed'
+            cand -y 'Answer yes to every confirmation prompt'
+            cand --yes 'Answer yes to every confirmation prompt'
+            cand --dry-run 'Simulate the action without changing anything'
+            cand --json 'Emit machine-readable JSON on stdout (for scripts)'
+            cand --no-color 'Disable ANSI colors'
+            cand -h 'Print help'
+            cand --help 'Print help'
+        }
+        &'am;tag'= {
+            cand -c 'Use an alternate configuration file'
+            cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
+            cand -v 'Verbose output: show every command executed and its details'
+            cand --verbose 'Verbose output: show every command executed and its details'
+            cand -q 'Quiet mode: only errors are printed'
+            cand --quiet 'Quiet mode: only errors are printed'
+            cand -y 'Answer yes to every confirmation prompt'
+            cand --yes 'Answer yes to every confirmation prompt'
+            cand --dry-run 'Simulate the action without changing anything'
+            cand --json 'Emit machine-readable JSON on stdout (for scripts)'
+            cand --no-color 'Disable ANSI colors'
+            cand -h 'Print help'
+            cand --help 'Print help'
+        }
+        &'am;untag'= {
+            cand -c 'Use an alternate configuration file'
+            cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
+            cand -v 'Verbose output: show every command executed and its details'
+            cand --verbose 'Verbose output: show every command executed and its details'
+            cand -q 'Quiet mode: only errors are printed'
+            cand --quiet 'Quiet mode: only errors are printed'
+            cand -y 'Answer yes to every confirmation prompt'
+            cand --yes 'Answer yes to every confirmation prompt'
+            cand --dry-run 'Simulate the action without changing anything'
+            cand --json 'Emit machine-readable JSON on stdout (for scripts)'
+            cand --no-color 'Disable ANSI colors'
+            cand -h 'Print help'
+            cand --help 'Print help'
+        }
+        &'am;tags'= {
+            cand -c 'Use an alternate configuration file'
+            cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
+            cand -v 'Verbose output: show every command executed and its details'
+            cand --verbose 'Verbose output: show every command executed and its details'
+            cand -q 'Quiet mode: only errors are printed'
+            cand --quiet 'Quiet mode: only errors are printed'
+            cand -y 'Answer yes to every confirmation prompt'
+            cand --yes 'Answer yes to every confirmation prompt'
+            cand --dry-run 'Simulate the action without changing anything'
+            cand --json 'Emit machine-readable JSON on stdout (for scripts)'
+            cand --no-color 'Disable ANSI colors'
+            cand -h 'Print help'
+            cand --help 'Print help'
+        }
+        &'am;profile'= {
+            cand -c 'Use an alternate configuration file'
+            cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
+            cand -v 'Verbose output: show every command executed and its details'
+            cand --verbose 'Verbose output: show every command executed and its details'
+            cand -q 'Quiet mode: only errors are printed'
+            cand --quiet 'Quiet mode: only errors are printed'
+            cand -y 'Answer yes to every confirmation prompt'
+            cand --yes 'Answer yes to every confirmation prompt'
+            cand --dry-run 'Simulate the action without changing anything'
+            cand --json 'Emit machine-readable JSON on stdout (for scripts)'
+            cand --no-color 'Disable ANSI colors'
+            cand -h 'Print help'
+            cand --help 'Print help'
+            cand list 'List every defined profile'
+            cand show 'Show one profile in detail (agent, env, args)'
+        }
+        &'am;profile;list'= {
+            cand -c 'Use an alternate configuration file'
+            cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
+            cand -v 'Verbose output: show every command executed and its details'
+            cand --verbose 'Verbose output: show every command executed and its details'
+            cand -q 'Quiet mode: only errors are printed'
+            cand --quiet 'Quiet mode: only errors are printed'
+            cand -y 'Answer yes to every confirmation prompt'
+            cand --yes 'Answer yes to every confirmation prompt'
+            cand --dry-run 'Simulate the action without changing anything'
+            cand --json 'Emit machine-readable JSON on stdout (for scripts)'
+            cand --no-color 'Disable ANSI colors'
+            cand -h 'Print help'
+            cand --help 'Print help'
+        }
+        &'am;profile;show'= {
+            cand -c 'Use an alternate configuration file'
+            cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
+            cand -v 'Verbose output: show every command executed and its details'
+            cand --verbose 'Verbose output: show every command executed and its details'
+            cand -q 'Quiet mode: only errors are printed'
+            cand --quiet 'Quiet mode: only errors are printed'
+            cand -y 'Answer yes to every confirmation prompt'
+            cand --yes 'Answer yes to every confirmation prompt'
+            cand --dry-run 'Simulate the action without changing anything'
+            cand --json 'Emit machine-readable JSON on stdout (for scripts)'
+            cand --no-color 'Disable ANSI colors'
+            cand -h 'Print help'
+            cand --help 'Print help'
+        }
+        &'am;man'= {
+            cand --output 'Write the page(s) to this directory instead of stdout'
+            cand -c 'Use an alternate configuration file'
+            cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
+            cand -v 'Verbose output: show every command executed and its details'
+            cand --verbose 'Verbose output: show every command executed and its details'
+            cand -q 'Quiet mode: only errors are printed'
+            cand --quiet 'Quiet mode: only errors are printed'
+            cand -y 'Answer yes to every confirmation prompt'
+            cand --yes 'Answer yes to every confirmation prompt'
+            cand --dry-run 'Simulate the action without changing anything'
+            cand --json 'Emit machine-readable JSON on stdout (for scripts)'
+            cand --no-color 'Disable ANSI colors'
+            cand -h 'Print help'
+            cand --help 'Print help'
+        }
+        &'am;_agents'= {
+            cand -c 'Use an alternate configuration file'
+            cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
+            cand --installed 'Only installed agents (managed + external), aliases and groups'
+            cand -v 'Verbose output: show every command executed and its details'
+            cand --verbose 'Verbose output: show every command executed and its details'
+            cand -q 'Quiet mode: only errors are printed'
+            cand --quiet 'Quiet mode: only errors are printed'
+            cand -y 'Answer yes to every confirmation prompt'
+            cand --yes 'Answer yes to every confirmation prompt'
+            cand --dry-run 'Simulate the action without changing anything'
+            cand --json 'Emit machine-readable JSON on stdout (for scripts)'
+            cand --no-color 'Disable ANSI colors'
+            cand -h 'Print help'
+            cand --help 'Print help'
+        }
+        &'am;alias'= {
+            cand -c 'Use an alternate configuration file'
+            cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
+            cand -v 'Verbose output: show every command executed and its details'
+            cand --verbose 'Verbose output: show every command executed and its details'
+            cand -q 'Quiet mode: only errors are printed'
+            cand --quiet 'Quiet mode: only errors are printed'
+            cand -y 'Answer yes to every confirmation prompt'
+            cand --yes 'Answer yes to every confirmation prompt'
+            cand --dry-run 'Simulate the action without changing anything'
+            cand --json 'Emit machine-readable JSON on stdout (for scripts)'
+            cand --no-color 'Disable ANSI colors'
+            cand -h 'Print help'
+            cand --help 'Print help'
+            cand add 'Add an alias (am alias add cc claude-code)'
+            cand remove 'Remove an alias'
+            cand list 'List every alias'
+        }
+        &'am;alias;add'= {
+            cand -c 'Use an alternate configuration file'
+            cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
+            cand -v 'Verbose output: show every command executed and its details'
+            cand --verbose 'Verbose output: show every command executed and its details'
+            cand -q 'Quiet mode: only errors are printed'
+            cand --quiet 'Quiet mode: only errors are printed'
+            cand -y 'Answer yes to every confirmation prompt'
+            cand --yes 'Answer yes to every confirmation prompt'
+            cand --dry-run 'Simulate the action without changing anything'
+            cand --json 'Emit machine-readable JSON on stdout (for scripts)'
+            cand --no-color 'Disable ANSI colors'
+            cand -h 'Print help'
+            cand --help 'Print help'
+        }
+        &'am;alias;remove'= {
+            cand -c 'Use an alternate configuration file'
+            cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
+            cand -v 'Verbose output: show every command executed and its details'
+            cand --verbose 'Verbose output: show every command executed and its details'
+            cand -q 'Quiet mode: only errors are printed'
+            cand --quiet 'Quiet mode: only errors are printed'
+            cand -y 'Answer yes to every confirmation prompt'
+            cand --yes 'Answer yes to every confirmation prompt'
+            cand --dry-run 'Simulate the action without changing anything'
+            cand --json 'Emit machine-readable JSON on stdout (for scripts)'
+            cand --no-color 'Disable ANSI colors'
+            cand -h 'Print help'
+            cand --help 'Print help'
+        }
+        &'am;alias;list'= {
+            cand -c 'Use an alternate configuration file'
+            cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
+            cand -v 'Verbose output: show every command executed and its details'
+            cand --verbose 'Verbose output: show every command executed and its details'
+            cand -q 'Quiet mode: only errors are printed'
+            cand --quiet 'Quiet mode: only errors are printed'
+            cand -y 'Answer yes to every confirmation prompt'
+            cand --yes 'Answer yes to every confirmation prompt'
+            cand --dry-run 'Simulate the action without changing anything'
+            cand --json 'Emit machine-readable JSON on stdout (for scripts)'
+            cand --no-color 'Disable ANSI colors'
+            cand -h 'Print help'
+            cand --help 'Print help'
+        }
+        &'am;secret'= {
+            cand -c 'Use an alternate configuration file'
+            cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
+            cand -v 'Verbose output: show every command executed and its details'
+            cand --verbose 'Verbose output: show every command executed and its details'
+            cand -q 'Quiet mode: only errors are printed'
+            cand --quiet 'Quiet mode: only errors are printed'
+            cand -y 'Answer yes to every confirmation prompt'
+            cand --yes 'Answer yes to every confirmation prompt'
+            cand --dry-run 'Simulate the action without changing anything'
+            cand --json 'Emit machine-readable JSON on stdout (for scripts)'
+            cand --no-color 'Disable ANSI colors'
+            cand -h 'Print help'
+            cand --help 'Print help'
+            cand set 'Store a secret for an agent'
+            cand unset 'Remove a secret'
+            cand list 'List stored secret names (values are never shown)'
+        }
+        &'am;secret;set'= {
+            cand --agent 'Agent it belongs to'
+            cand --value 'Secret value (prefer --value over shell history; never logged)'
+            cand -c 'Use an alternate configuration file'
+            cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
+            cand -v 'Verbose output: show every command executed and its details'
+            cand --verbose 'Verbose output: show every command executed and its details'
+            cand -q 'Quiet mode: only errors are printed'
+            cand --quiet 'Quiet mode: only errors are printed'
+            cand -y 'Answer yes to every confirmation prompt'
+            cand --yes 'Answer yes to every confirmation prompt'
+            cand --dry-run 'Simulate the action without changing anything'
+            cand --json 'Emit machine-readable JSON on stdout (for scripts)'
+            cand --no-color 'Disable ANSI colors'
+            cand -h 'Print help'
+            cand --help 'Print help'
+        }
+        &'am;secret;unset'= {
+            cand --agent 'Agent it belongs to'
+            cand -c 'Use an alternate configuration file'
+            cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
+            cand -v 'Verbose output: show every command executed and its details'
+            cand --verbose 'Verbose output: show every command executed and its details'
+            cand -q 'Quiet mode: only errors are printed'
+            cand --quiet 'Quiet mode: only errors are printed'
+            cand -y 'Answer yes to every confirmation prompt'
+            cand --yes 'Answer yes to every confirmation prompt'
+            cand --dry-run 'Simulate the action without changing anything'
+            cand --json 'Emit machine-readable JSON on stdout (for scripts)'
+            cand --no-color 'Disable ANSI colors'
+            cand -h 'Print help'
+            cand --help 'Print help'
+        }
+        &'am;secret;list'= {
+            cand -c 'Use an alternate configuration file'
+            cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
             cand -v 'Verbose output: show every command executed and its details'
             cand --verbose 'Verbose output: show every command executed and its details'
             cand -q 'Quiet mode: only errors are printed'
@@ -73,8 +488,10 @@ set edit:completion:arg-completer[am] = {|@words|
         &'am;start'= {
             cand --args 'Extra arguments passed to the agent (repeatable; quoted strings are split on spaces)'
             cand --env 'Set an environment variable for the agent (repeatable): --env KEY=VALUE'
+            cand --profile 'Apply an environment profile (env + args, defined in the config)'
             cand -c 'Use an alternate configuration file'
             cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
             cand -b 'Run detached in the background; output goes to the agent log file'
             cand --background 'Run detached in the background; output goes to the agent log file'
             cand -f 'Run in the foreground, attached to this terminal (the default)'
@@ -96,6 +513,7 @@ set edit:completion:arg-completer[am] = {|@words|
             cand --timeout 'Grace period in seconds before killing (default: from config, 5s)'
             cand -c 'Use an alternate configuration file'
             cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
             cand --force 'Kill immediately instead of terminating gracefully'
             cand -v 'Verbose output: show every command executed and its details'
             cand --verbose 'Verbose output: show every command executed and its details'
@@ -112,9 +530,11 @@ set edit:completion:arg-completer[am] = {|@words|
         &'am;restart'= {
             cand --args 'Extra arguments passed to the agent (repeatable; quoted strings are split on spaces)'
             cand --env 'Set an environment variable for the agent (repeatable): --env KEY=VALUE'
+            cand --profile 'Apply an environment profile (env + args, defined in the config)'
             cand --timeout 'Grace period in seconds before killing (default: from config, 5s)'
             cand -c 'Use an alternate configuration file'
             cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
             cand -b 'Run detached in the background; output goes to the agent log file'
             cand --background 'Run detached in the background; output goes to the agent log file'
             cand -f 'Run in the foreground, attached to this terminal (the default)'
@@ -136,6 +556,135 @@ set edit:completion:arg-completer[am] = {|@words|
         &'am;status'= {
             cand -c 'Use an alternate configuration file'
             cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
+            cand -v 'Verbose output: show every command executed and its details'
+            cand --verbose 'Verbose output: show every command executed and its details'
+            cand -q 'Quiet mode: only errors are printed'
+            cand --quiet 'Quiet mode: only errors are printed'
+            cand -y 'Answer yes to every confirmation prompt'
+            cand --yes 'Answer yes to every confirmation prompt'
+            cand --dry-run 'Simulate the action without changing anything'
+            cand --json 'Emit machine-readable JSON on stdout (for scripts)'
+            cand --no-color 'Disable ANSI colors'
+            cand -h 'Print help'
+            cand --help 'Print help'
+        }
+        &'am;sessions'= {
+            cand --project 'Only sessions of this project'
+            cand --status 'Only sessions with this status (running, stopped, failed, interrupted)'
+            cand --show 'Show one session in detail (summary + log excerpt)'
+            cand --resume 'Resume a finished session: relaunch the agent with its recorded arguments'
+            cand -c 'Use an alternate configuration file'
+            cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
+            cand -v 'Verbose output: show every command executed and its details'
+            cand --verbose 'Verbose output: show every command executed and its details'
+            cand -q 'Quiet mode: only errors are printed'
+            cand --quiet 'Quiet mode: only errors are printed'
+            cand -y 'Answer yes to every confirmation prompt'
+            cand --yes 'Answer yes to every confirmation prompt'
+            cand --dry-run 'Simulate the action without changing anything'
+            cand --json 'Emit machine-readable JSON on stdout (for scripts)'
+            cand --no-color 'Disable ANSI colors'
+            cand -h 'Print help'
+            cand --help 'Print help'
+        }
+        &'am;stats'= {
+            cand --period 'Only events of the last period (7d, 30d, 90d, all)'
+            cand -c 'Use an alternate configuration file'
+            cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
+            cand -v 'Verbose output: show every command executed and its details'
+            cand --verbose 'Verbose output: show every command executed and its details'
+            cand -q 'Quiet mode: only errors are printed'
+            cand --quiet 'Quiet mode: only errors are printed'
+            cand -y 'Answer yes to every confirmation prompt'
+            cand --yes 'Answer yes to every confirmation prompt'
+            cand --dry-run 'Simulate the action without changing anything'
+            cand --json 'Emit machine-readable JSON on stdout (for scripts)'
+            cand --no-color 'Disable ANSI colors'
+            cand -h 'Print help'
+            cand --help 'Print help'
+        }
+        &'am;top'= {
+            cand --period 'Only events of the last period (7d, 30d, 90d, all)'
+            cand -c 'Use an alternate configuration file'
+            cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
+            cand -v 'Verbose output: show every command executed and its details'
+            cand --verbose 'Verbose output: show every command executed and its details'
+            cand -q 'Quiet mode: only errors are printed'
+            cand --quiet 'Quiet mode: only errors are printed'
+            cand -y 'Answer yes to every confirmation prompt'
+            cand --yes 'Answer yes to every confirmation prompt'
+            cand --dry-run 'Simulate the action without changing anything'
+            cand --json 'Emit machine-readable JSON on stdout (for scripts)'
+            cand --no-color 'Disable ANSI colors'
+            cand -h 'Print help'
+            cand --help 'Print help'
+        }
+        &'am;report'= {
+            cand --output 'Output file (default: report-YYYYMMDD.md in the state directory)'
+            cand -c 'Use an alternate configuration file'
+            cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
+            cand --last-week 'Cover the last 7 days'
+            cand --last-month 'Cover the last 30 days'
+            cand -v 'Verbose output: show every command executed and its details'
+            cand --verbose 'Verbose output: show every command executed and its details'
+            cand -q 'Quiet mode: only errors are printed'
+            cand --quiet 'Quiet mode: only errors are printed'
+            cand -y 'Answer yes to every confirmation prompt'
+            cand --yes 'Answer yes to every confirmation prompt'
+            cand --dry-run 'Simulate the action without changing anything'
+            cand --json 'Emit machine-readable JSON on stdout (for scripts)'
+            cand --no-color 'Disable ANSI colors'
+            cand -h 'Print help'
+            cand --help 'Print help'
+        }
+        &'am;projects'= {
+            cand -c 'Use an alternate configuration file'
+            cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
+            cand -v 'Verbose output: show every command executed and its details'
+            cand --verbose 'Verbose output: show every command executed and its details'
+            cand -q 'Quiet mode: only errors are printed'
+            cand --quiet 'Quiet mode: only errors are printed'
+            cand -y 'Answer yes to every confirmation prompt'
+            cand --yes 'Answer yes to every confirmation prompt'
+            cand --dry-run 'Simulate the action without changing anything'
+            cand --json 'Emit machine-readable JSON on stdout (for scripts)'
+            cand --no-color 'Disable ANSI colors'
+            cand -h 'Print help'
+            cand --help 'Print help'
+        }
+        &'am;timeline'= {
+            cand --project 'Only activity of this project'
+            cand --since 'Only activity at or after this date (YYYY-MM-DD or RFC 3339)'
+            cand --limit 'Maximum number of entries (default: 50)'
+            cand -c 'Use an alternate configuration file'
+            cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
+            cand -v 'Verbose output: show every command executed and its details'
+            cand --verbose 'Verbose output: show every command executed and its details'
+            cand -q 'Quiet mode: only errors are printed'
+            cand --quiet 'Quiet mode: only errors are printed'
+            cand -y 'Answer yes to every confirmation prompt'
+            cand --yes 'Answer yes to every confirmation prompt'
+            cand --dry-run 'Simulate the action without changing anything'
+            cand --json 'Emit machine-readable JSON on stdout (for scripts)'
+            cand --no-color 'Disable ANSI colors'
+            cand -h 'Print help'
+            cand --help 'Print help'
+        }
+        &'am;log'= {
+            cand --kind 'Only these event kinds (comma separated: start,stop,run,install,...)'
+            cand --since 'Only events at or after this date (YYYY-MM-DD or RFC 3339)'
+            cand --limit 'Maximum number of events (default: 50)'
+            cand -c 'Use an alternate configuration file'
+            cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
+            cand --follow 'Follow the journal as new events arrive'
             cand -v 'Verbose output: show every command executed and its details'
             cand --verbose 'Verbose output: show every command executed and its details'
             cand -q 'Quiet mode: only errors are printed'
@@ -152,6 +701,7 @@ set edit:completion:arg-completer[am] = {|@words|
             cand --method 'Select the install method (index, or type: npm, pip, uv, cargo, go, bun, curl, binary, git)'
             cand -c 'Use an alternate configuration file'
             cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
             cand --force 'Reinstall even if already installed'
             cand -v 'Verbose output: show every command executed and its details'
             cand --verbose 'Verbose output: show every command executed and its details'
@@ -168,6 +718,7 @@ set edit:completion:arg-completer[am] = {|@words|
         &'am;uninstall'= {
             cand -c 'Use an alternate configuration file'
             cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
             cand --purge 'Also remove logs and the agent entry from the user config file'
             cand -v 'Verbose output: show every command executed and its details'
             cand --verbose 'Verbose output: show every command executed and its details'
@@ -184,6 +735,7 @@ set edit:completion:arg-completer[am] = {|@words|
         &'am;update'= {
             cand -c 'Use an alternate configuration file'
             cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
             cand --all 'Update every installed managed agent'
             cand -v 'Verbose output: show every command executed and its details'
             cand --verbose 'Verbose output: show every command executed and its details'
@@ -199,8 +751,33 @@ set edit:completion:arg-completer[am] = {|@words|
         }
         &'am;search'= {
             cand --category 'Restrict to this category'
+            cand --tag 'Only agents carrying this personal tag'
             cand -c 'Use an alternate configuration file'
             cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
+            cand -v 'Verbose output: show every command executed and its details'
+            cand --verbose 'Verbose output: show every command executed and its details'
+            cand -q 'Quiet mode: only errors are printed'
+            cand --quiet 'Quiet mode: only errors are printed'
+            cand -y 'Answer yes to every confirmation prompt'
+            cand --yes 'Answer yes to every confirmation prompt'
+            cand --dry-run 'Simulate the action without changing anything'
+            cand --json 'Emit machine-readable JSON on stdout (for scripts)'
+            cand --no-color 'Disable ANSI colors'
+            cand -h 'Print help'
+            cand --help 'Print help'
+        }
+        &'am;history'= {
+            cand --kind 'Only commands of this kind (am or shell)'
+            cand --cwd 'Only commands run in this directory'
+            cand --search 'Full-text search in the command line'
+            cand --session 'Only commands of this session'
+            cand --limit 'Maximum number of entries (default: 100)'
+            cand --rerun 'Re-run the Nth most recent entry (with confirmation)'
+            cand -c 'Use an alternate configuration file'
+            cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
+            cand --failed 'Only failed commands'
             cand -v 'Verbose output: show every command executed and its details'
             cand --verbose 'Verbose output: show every command executed and its details'
             cand -q 'Quiet mode: only errors are printed'
@@ -216,6 +793,57 @@ set edit:completion:arg-completer[am] = {|@words|
         &'am;info'= {
             cand -c 'Use an alternate configuration file'
             cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
+            cand -v 'Verbose output: show every command executed and its details'
+            cand --verbose 'Verbose output: show every command executed and its details'
+            cand -q 'Quiet mode: only errors are printed'
+            cand --quiet 'Quiet mode: only errors are printed'
+            cand -y 'Answer yes to every confirmation prompt'
+            cand --yes 'Answer yes to every confirmation prompt'
+            cand --dry-run 'Simulate the action without changing anything'
+            cand --json 'Emit machine-readable JSON on stdout (for scripts)'
+            cand --no-color 'Disable ANSI colors'
+            cand -h 'Print help'
+            cand --help 'Print help'
+        }
+        &'am;init'= {
+            cand -c 'Use an alternate configuration file'
+            cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
+            cand --force 'Overwrite an existing agent-manager.yaml'
+            cand -v 'Verbose output: show every command executed and its details'
+            cand --verbose 'Verbose output: show every command executed and its details'
+            cand -q 'Quiet mode: only errors are printed'
+            cand --quiet 'Quiet mode: only errors are printed'
+            cand -y 'Answer yes to every confirmation prompt'
+            cand --yes 'Answer yes to every confirmation prompt'
+            cand --dry-run 'Simulate the action without changing anything'
+            cand --json 'Emit machine-readable JSON on stdout (for scripts)'
+            cand --no-color 'Disable ANSI colors'
+            cand -h 'Print help'
+            cand --help 'Print help'
+        }
+        &'am;help'= {
+            cand --find 'Search through all help commands table'
+            cand -c 'Use an alternate configuration file'
+            cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
+            cand -v 'Verbose output: show every command executed and its details'
+            cand --verbose 'Verbose output: show every command executed and its details'
+            cand -q 'Quiet mode: only errors are printed'
+            cand --quiet 'Quiet mode: only errors are printed'
+            cand -y 'Answer yes to every confirmation prompt'
+            cand --yes 'Answer yes to every confirmation prompt'
+            cand --dry-run 'Simulate the action without changing anything'
+            cand --json 'Emit machine-readable JSON on stdout (for scripts)'
+            cand --no-color 'Disable ANSI colors'
+            cand -h 'Print help'
+            cand --help 'Print help'
+        }
+        &'am;version'= {
+            cand -c 'Use an alternate configuration file'
+            cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
             cand -v 'Verbose output: show every command executed and its details'
             cand --verbose 'Verbose output: show every command executed and its details'
             cand -q 'Quiet mode: only errors are printed'
@@ -231,6 +859,7 @@ set edit:completion:arg-completer[am] = {|@words|
         &'am;config'= {
             cand -c 'Use an alternate configuration file'
             cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
             cand -v 'Verbose output: show every command executed and its details'
             cand --verbose 'Verbose output: show every command executed and its details'
             cand -q 'Quiet mode: only errors are printed'
@@ -247,11 +876,12 @@ set edit:completion:arg-completer[am] = {|@words|
             cand edit 'Open the user configuration file in your editor'
             cand validate 'Validate the configuration file(s)'
             cand add 'Add another agent definition file to the user configuration'
-            cand help 'Print this message or the help of the given subcommand(s)'
+            cand set 'Set one configuration key without an editor (config set settings.default_shell pwsh)'
         }
         &'am;config;show'= {
             cand -c 'Use an alternate configuration file'
             cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
             cand -v 'Verbose output: show every command executed and its details'
             cand --verbose 'Verbose output: show every command executed and its details'
             cand -q 'Quiet mode: only errors are printed'
@@ -267,6 +897,7 @@ set edit:completion:arg-completer[am] = {|@words|
         &'am;config;path'= {
             cand -c 'Use an alternate configuration file'
             cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
             cand -v 'Verbose output: show every command executed and its details'
             cand --verbose 'Verbose output: show every command executed and its details'
             cand -q 'Quiet mode: only errors are printed'
@@ -282,6 +913,7 @@ set edit:completion:arg-completer[am] = {|@words|
         &'am;config;edit'= {
             cand -c 'Use an alternate configuration file'
             cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
             cand -v 'Verbose output: show every command executed and its details'
             cand --verbose 'Verbose output: show every command executed and its details'
             cand -q 'Quiet mode: only errors are printed'
@@ -297,6 +929,7 @@ set edit:completion:arg-completer[am] = {|@words|
         &'am;config;validate'= {
             cand -c 'Use an alternate configuration file'
             cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
             cand -v 'Verbose output: show every command executed and its details'
             cand --verbose 'Verbose output: show every command executed and its details'
             cand -q 'Quiet mode: only errors are printed'
@@ -312,6 +945,7 @@ set edit:completion:arg-completer[am] = {|@words|
         &'am;config;add'= {
             cand -c 'Use an alternate configuration file'
             cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
             cand -v 'Verbose output: show every command executed and its details'
             cand --verbose 'Verbose output: show every command executed and its details'
             cand -q 'Quiet mode: only errors are printed'
@@ -324,29 +958,26 @@ set edit:completion:arg-completer[am] = {|@words|
             cand -h 'Print help'
             cand --help 'Print help'
         }
-        &'am;config;help'= {
-            cand show 'Print the effective (merged) configuration as YAML'
-            cand path 'Print the location of the configuration file(s)'
-            cand edit 'Open the user configuration file in your editor'
-            cand validate 'Validate the configuration file(s)'
-            cand add 'Add another agent definition file to the user configuration'
-            cand help 'Print this message or the help of the given subcommand(s)'
-        }
-        &'am;config;help;show'= {
-        }
-        &'am;config;help;path'= {
-        }
-        &'am;config;help;edit'= {
-        }
-        &'am;config;help;validate'= {
-        }
-        &'am;config;help;add'= {
-        }
-        &'am;config;help;help'= {
+        &'am;config;set'= {
+            cand -c 'Use an alternate configuration file'
+            cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
+            cand -v 'Verbose output: show every command executed and its details'
+            cand --verbose 'Verbose output: show every command executed and its details'
+            cand -q 'Quiet mode: only errors are printed'
+            cand --quiet 'Quiet mode: only errors are printed'
+            cand -y 'Answer yes to every confirmation prompt'
+            cand --yes 'Answer yes to every confirmation prompt'
+            cand --dry-run 'Simulate the action without changing anything'
+            cand --json 'Emit machine-readable JSON on stdout (for scripts)'
+            cand --no-color 'Disable ANSI colors'
+            cand -h 'Print help'
+            cand --help 'Print help'
         }
         &'am;doctor'= {
             cand -c 'Use an alternate configuration file'
             cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
             cand --fix 'Attempt to repair problems (create directories, fix the state file)'
             cand -v 'Verbose output: show every command executed and its details'
             cand --verbose 'Verbose output: show every command executed and its details'
@@ -363,6 +994,7 @@ set edit:completion:arg-completer[am] = {|@words|
         &'am;run'= {
             cand -c 'Use an alternate configuration file'
             cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
             cand -v 'Verbose output: show every command executed and its details'
             cand --verbose 'Verbose output: show every command executed and its details'
             cand -q 'Quiet mode: only errors are printed'
@@ -378,6 +1010,8 @@ set edit:completion:arg-completer[am] = {|@words|
         &'am;completion'= {
             cand -c 'Use an alternate configuration file'
             cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
+            cand --installed 'Add dynamic completion of the installed agents, aliases and groups (queried from ''am _agents'' at Tab time)'
             cand -v 'Verbose output: show every command executed and its details'
             cand --verbose 'Verbose output: show every command executed and its details'
             cand -q 'Quiet mode: only errors are printed'
@@ -394,6 +1028,7 @@ set edit:completion:arg-completer[am] = {|@words|
             cand --to 'Download the new binary to this path instead of replacing the current one'
             cand -c 'Use an alternate configuration file'
             cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
             cand --check 'Only check whether a newer version exists'
             cand -v 'Verbose output: show every command executed and its details'
             cand --verbose 'Verbose output: show every command executed and its details'
@@ -407,10 +1042,27 @@ set edit:completion:arg-completer[am] = {|@words|
             cand -h 'Print help'
             cand --help 'Print help'
         }
+        &'am;self-uninstall'= {
+            cand -c 'Use an alternate configuration file'
+            cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
+            cand -v 'Verbose output: show every command executed and its details'
+            cand --verbose 'Verbose output: show every command executed and its details'
+            cand -q 'Quiet mode: only errors are printed'
+            cand --quiet 'Quiet mode: only errors are printed'
+            cand -y 'Answer yes to every confirmation prompt'
+            cand --yes 'Answer yes to every confirmation prompt'
+            cand --dry-run 'Simulate the action without changing anything'
+            cand --json 'Emit machine-readable JSON on stdout (for scripts)'
+            cand --no-color 'Disable ANSI colors'
+            cand -h 'Print help (see more with ''--help'')'
+            cand --help 'Print help (see more with ''--help'')'
+        }
         &'am;export'= {
             cand --output 'Output file (default: am-export.json)'
             cand -c 'Use an alternate configuration file'
             cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
             cand -v 'Verbose output: show every command executed and its details'
             cand --verbose 'Verbose output: show every command executed and its details'
             cand -q 'Quiet mode: only errors are printed'
@@ -426,6 +1078,7 @@ set edit:completion:arg-completer[am] = {|@words|
         &'am;import'= {
             cand -c 'Use an alternate configuration file'
             cand --config 'Use an alternate configuration file'
+            cand --theme 'Color theme for the output (see ''am help theme'' for the list)'
             cand -v 'Verbose output: show every command executed and its details'
             cand --verbose 'Verbose output: show every command executed and its details'
             cand -q 'Quiet mode: only errors are printed'
@@ -438,77 +1091,6 @@ set edit:completion:arg-completer[am] = {|@words|
             cand -h 'Print help'
             cand --help 'Print help'
         }
-        &'am;help'= {
-            cand list 'List agents: installed ones, or every agent known to the catalog'
-            cand start 'Start an agent (foreground by default, or detached with --background)'
-            cand stop 'Stop a background agent (SIGTERM, then SIGKILL after the timeout)'
-            cand restart 'Restart an agent: stop, then start with the same options'
-            cand status 'Show the state of one agent, or of every installed agent'
-            cand install 'Install an agent and its dependencies'
-            cand uninstall 'Uninstall an agent and clean its files'
-            cand update 'Update an installed agent to the latest available version'
-            cand search 'Search the catalog by keyword (name, description, category, tags)'
-            cand info 'Show detailed information about one agent'
-            cand config 'Manage the configuration file'
-            cand doctor 'Check the environment: tools, config validity, paths, permissions'
-            cand run 'Run the agent command directly with the given arguments (no process management)'
-            cand completion 'Generate a shell completion script'
-            cand self-update 'Update agent-manager itself from GitHub Releases'
-            cand export 'Export the configuration and installation state (backup)'
-            cand import 'Import a previously exported configuration and state'
-            cand help 'Print this message or the help of the given subcommand(s)'
-        }
-        &'am;help;list'= {
-        }
-        &'am;help;start'= {
-        }
-        &'am;help;stop'= {
-        }
-        &'am;help;restart'= {
-        }
-        &'am;help;status'= {
-        }
-        &'am;help;install'= {
-        }
-        &'am;help;uninstall'= {
-        }
-        &'am;help;update'= {
-        }
-        &'am;help;search'= {
-        }
-        &'am;help;info'= {
-        }
-        &'am;help;config'= {
-            cand show 'Print the effective (merged) configuration as YAML'
-            cand path 'Print the location of the configuration file(s)'
-            cand edit 'Open the user configuration file in your editor'
-            cand validate 'Validate the configuration file(s)'
-            cand add 'Add another agent definition file to the user configuration'
-        }
-        &'am;help;config;show'= {
-        }
-        &'am;help;config;path'= {
-        }
-        &'am;help;config;edit'= {
-        }
-        &'am;help;config;validate'= {
-        }
-        &'am;help;config;add'= {
-        }
-        &'am;help;doctor'= {
-        }
-        &'am;help;run'= {
-        }
-        &'am;help;completion'= {
-        }
-        &'am;help;self-update'= {
-        }
-        &'am;help;export'= {
-        }
-        &'am;help;import'= {
-        }
-        &'am;help;help'= {
-        }
     ]
     $completions[$command]
 }

completions/am.fish

@@ -1,6 +1,6 @@
 # Print an optspec for argparse to handle cmd's options that are independent of any subcommand.
 function __fish_am_global_optspecs
-    string join \n c/config= v/verbose q/quiet y/yes dry-run json no-color h/help V/version
+    string join \n c/config= v/verbose q/quiet y/yes dry-run json no-color theme= h/help V/version
 end
 
 function __fish_am_needs_command
@@ -25,6 +25,7 @@ function __fish_am_using_subcommand
 end
 
 complete -c am -n "__fish_am_needs_command" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_needs_command" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
 complete -c am -n "__fish_am_needs_command" -s v -l verbose -d 'Verbose output: show every command executed and its details'
 complete -c am -n "__fish_am_needs_command" -s q -l quiet -d 'Quiet mode: only errors are printed'
 complete -c am -n "__fish_am_needs_command" -s y -l yes -d 'Answer yes to every confirmation prompt'
@@ -33,28 +34,56 @@ complete -c am -n "__fish_am_needs_command" -l json -d 'Emit machine-readable JS
 complete -c am -n "__fish_am_needs_command" -l no-color -d 'Disable ANSI colors'
 complete -c am -n "__fish_am_needs_command" -s h -l help -d 'Print help (see more with \'--help\')'
 complete -c am -n "__fish_am_needs_command" -s V -l version -d 'Print version'
-complete -c am -n "__fish_am_needs_command" -f -a "list" -d 'List agents: installed ones, or every agent known to the catalog'
+complete -c am -n "__fish_am_needs_command" -f -a "list" -d 'List installed agents (default); use --all for the whole catalog'
+complete -c am -n "__fish_am_needs_command" -f -a "logs" -d 'Tail the log file of an agent (--follow for a live view)'
+complete -c am -n "__fish_am_needs_command" -f -a "open" -d 'Open an agent\'s installation directory in the file manager'
+complete -c am -n "__fish_am_needs_command" -f -a "watch" -d 'Supervise an agent and optionally restart it on crash'
+complete -c am -n "__fish_am_needs_command" -f -a "dashboard" -d 'Live TUI dashboard: overview, activity, stats, sessions, projects'
+complete -c am -n "__fish_am_needs_command" -f -a "favorite" -d 'Mark an agent as a favorite (star in list and status)'
+complete -c am -n "__fish_am_needs_command" -f -a "unfavorite" -d 'Remove the favorite star from an agent'
+complete -c am -n "__fish_am_needs_command" -f -a "note" -d 'Attach a free-form note to an agent (shown in \'am info\'); \'am note <agent>\' without text prints the current note'
+complete -c am -n "__fish_am_needs_command" -f -a "tag" -d 'Add a personal tag to an agent'
+complete -c am -n "__fish_am_needs_command" -f -a "untag" -d 'Remove a personal tag from an agent'
+complete -c am -n "__fish_am_needs_command" -f -a "tags" -d 'List personal tags (with counts), optionally for one agent'
+complete -c am -n "__fish_am_needs_command" -f -a "profile" -d 'Manage environment profiles (dev, prod, ...)'
+complete -c am -n "__fish_am_needs_command" -f -a "man" -d 'Generate a man page for am (or for one command)'
+complete -c am -n "__fish_am_needs_command" -f -a "_agents" -d 'Internal: list agent names for shell completions (hidden)'
+complete -c am -n "__fish_am_needs_command" -f -a "alias" -d 'Manage command aliases (cc -> claude-code)'
+complete -c am -n "__fish_am_needs_command" -f -a "secret" -d 'Manage secrets in the OS keyring (never in plaintext config)'
 complete -c am -n "__fish_am_needs_command" -f -a "start" -d 'Start an agent (foreground by default, or detached with --background)'
 complete -c am -n "__fish_am_needs_command" -f -a "stop" -d 'Stop a background agent (SIGTERM, then SIGKILL after the timeout)'
 complete -c am -n "__fish_am_needs_command" -f -a "restart" -d 'Restart an agent: stop, then start with the same options'
 complete -c am -n "__fish_am_needs_command" -f -a "status" -d 'Show the state of one agent, or of every installed agent'
+complete -c am -n "__fish_am_needs_command" -f -a "sessions" -d 'List the sessions of every agent (and of the interactive shell)'
+complete -c am -n "__fish_am_needs_command" -f -a "stats" -d 'Show usage statistics computed from the event journal'
+complete -c am -n "__fish_am_needs_command" -f -a "top" -d 'Show the most used agents (top 10)'
+complete -c am -n "__fish_am_needs_command" -f -a "report" -d 'Write a markdown activity report'
+complete -c am -n "__fish_am_needs_command" -f -a "projects" -d 'Show which agent works on which project'
+complete -c am -n "__fish_am_needs_command" -f -a "timeline" -d 'One chronological view of every activity (journal + REPL history)'
+complete -c am -n "__fish_am_needs_command" -f -a "log" -d 'Read the event journal: everything am did'
 complete -c am -n "__fish_am_needs_command" -f -a "install" -d 'Install an agent and its dependencies'
-complete -c am -n "__fish_am_needs_command" -f -a "uninstall" -d 'Uninstall an agent and clean its files'
+complete -c am -n "__fish_am_needs_command" -f -a "uninstall" -d 'Uninstall an agent (managed or external) and clean its files'
 complete -c am -n "__fish_am_needs_command" -f -a "update" -d 'Update an installed agent to the latest available version'
 complete -c am -n "__fish_am_needs_command" -f -a "search" -d 'Search the catalog by keyword (name, description, category, tags)'
+complete -c am -n "__fish_am_needs_command" -f -a "history" -d 'Search the command history (am and shell commands)'
 complete -c am -n "__fish_am_needs_command" -f -a "info" -d 'Show detailed information about one agent'
+complete -c am -n "__fish_am_needs_command" -f -a "init" -d 'Generate a local agent-manager.yaml for the current directory'
+complete -c am -n "__fish_am_needs_command" -f -a "help" -d 'Display help: the overview, a command, the command list, or a search'
+complete -c am -n "__fish_am_needs_command" -f -a "version" -d 'Display version and build information'
 complete -c am -n "__fish_am_needs_command" -f -a "config" -d 'Manage the configuration file'
 complete -c am -n "__fish_am_needs_command" -f -a "doctor" -d 'Check the environment: tools, config validity, paths, permissions'
 complete -c am -n "__fish_am_needs_command" -f -a "run" -d 'Run the agent command directly with the given arguments (no process management)'
 complete -c am -n "__fish_am_needs_command" -f -a "completion" -d 'Generate a shell completion script'
 complete -c am -n "__fish_am_needs_command" -f -a "self-update" -d 'Update agent-manager itself from GitHub Releases'
+complete -c am -n "__fish_am_needs_command" -f -a "self-uninstall" -d 'Remove agent-manager and everything it created from this machine'
 complete -c am -n "__fish_am_needs_command" -f -a "export" -d 'Export the configuration and installation state (backup)'
 complete -c am -n "__fish_am_needs_command" -f -a "import" -d 'Import a previously exported configuration and state'
-complete -c am -n "__fish_am_needs_command" -f -a "help" -d 'Print this message or the help of the given subcommand(s)'
 complete -c am -n "__fish_am_using_subcommand list" -l category -d 'Only show agents of this category' -r
+complete -c am -n "__fish_am_using_subcommand list" -l sort -d 'Sort by name, version or status (default: name)' -r
 complete -c am -n "__fish_am_using_subcommand list" -s c -l config -d 'Use an alternate configuration file' -r -F
-complete -c am -n "__fish_am_using_subcommand list" -l installed-only -d 'Only show agents that are installed (managed or external)'
-complete -c am -n "__fish_am_using_subcommand list" -l all -d 'Include hidden agents as well'
+complete -c am -n "__fish_am_using_subcommand list" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
+complete -c am -n "__fish_am_using_subcommand list" -l all -d 'Show every agent known to the catalog, not only the installed ones'
+complete -c am -n "__fish_am_using_subcommand list" -l running -d 'Only show running agents'
 complete -c am -n "__fish_am_using_subcommand list" -s v -l verbose -d 'Verbose output: show every command executed and its details'
 complete -c am -n "__fish_am_using_subcommand list" -s q -l quiet -d 'Quiet mode: only errors are printed'
 complete -c am -n "__fish_am_using_subcommand list" -s y -l yes -d 'Answer yes to every confirmation prompt'
@@ -62,9 +91,236 @@ complete -c am -n "__fish_am_using_subcommand list" -l dry-run -d 'Simulate the
 complete -c am -n "__fish_am_using_subcommand list" -l json -d 'Emit machine-readable JSON on stdout (for scripts)'
 complete -c am -n "__fish_am_using_subcommand list" -l no-color -d 'Disable ANSI colors'
 complete -c am -n "__fish_am_using_subcommand list" -s h -l help -d 'Print help'
+complete -c am -n "__fish_am_using_subcommand logs" -l lines -d 'Number of lines to show (default: 20)' -r
+complete -c am -n "__fish_am_using_subcommand logs" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand logs" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
+complete -c am -n "__fish_am_using_subcommand logs" -l follow -d 'Follow the log as it grows'
+complete -c am -n "__fish_am_using_subcommand logs" -s v -l verbose -d 'Verbose output: show every command executed and its details'
+complete -c am -n "__fish_am_using_subcommand logs" -s q -l quiet -d 'Quiet mode: only errors are printed'
+complete -c am -n "__fish_am_using_subcommand logs" -s y -l yes -d 'Answer yes to every confirmation prompt'
+complete -c am -n "__fish_am_using_subcommand logs" -l dry-run -d 'Simulate the action without changing anything'
+complete -c am -n "__fish_am_using_subcommand logs" -l json -d 'Emit machine-readable JSON on stdout (for scripts)'
+complete -c am -n "__fish_am_using_subcommand logs" -l no-color -d 'Disable ANSI colors'
+complete -c am -n "__fish_am_using_subcommand logs" -s h -l help -d 'Print help'
+complete -c am -n "__fish_am_using_subcommand open" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand open" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
+complete -c am -n "__fish_am_using_subcommand open" -s v -l verbose -d 'Verbose output: show every command executed and its details'
+complete -c am -n "__fish_am_using_subcommand open" -s q -l quiet -d 'Quiet mode: only errors are printed'
+complete -c am -n "__fish_am_using_subcommand open" -s y -l yes -d 'Answer yes to every confirmation prompt'
+complete -c am -n "__fish_am_using_subcommand open" -l dry-run -d 'Simulate the action without changing anything'
+complete -c am -n "__fish_am_using_subcommand open" -l json -d 'Emit machine-readable JSON on stdout (for scripts)'
+complete -c am -n "__fish_am_using_subcommand open" -l no-color -d 'Disable ANSI colors'
+complete -c am -n "__fish_am_using_subcommand open" -s h -l help -d 'Print help'
+complete -c am -n "__fish_am_using_subcommand watch" -l interval -d 'Check interval in seconds (default: 5)' -r
+complete -c am -n "__fish_am_using_subcommand watch" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand watch" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
+complete -c am -n "__fish_am_using_subcommand watch" -l restart -d 'Restart the agent automatically when it dies (with backoff)'
+complete -c am -n "__fish_am_using_subcommand watch" -l notify -d 'Desktop notification on every restart'
+complete -c am -n "__fish_am_using_subcommand watch" -s v -l verbose -d 'Verbose output: show every command executed and its details'
+complete -c am -n "__fish_am_using_subcommand watch" -s q -l quiet -d 'Quiet mode: only errors are printed'
+complete -c am -n "__fish_am_using_subcommand watch" -s y -l yes -d 'Answer yes to every confirmation prompt'
+complete -c am -n "__fish_am_using_subcommand watch" -l dry-run -d 'Simulate the action without changing anything'
+complete -c am -n "__fish_am_using_subcommand watch" -l json -d 'Emit machine-readable JSON on stdout (for scripts)'
+complete -c am -n "__fish_am_using_subcommand watch" -l no-color -d 'Disable ANSI colors'
+complete -c am -n "__fish_am_using_subcommand watch" -s h -l help -d 'Print help'
+complete -c am -n "__fish_am_using_subcommand dashboard" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand dashboard" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
+complete -c am -n "__fish_am_using_subcommand dashboard" -s v -l verbose -d 'Verbose output: show every command executed and its details'
+complete -c am -n "__fish_am_using_subcommand dashboard" -s q -l quiet -d 'Quiet mode: only errors are printed'
+complete -c am -n "__fish_am_using_subcommand dashboard" -s y -l yes -d 'Answer yes to every confirmation prompt'
+complete -c am -n "__fish_am_using_subcommand dashboard" -l dry-run -d 'Simulate the action without changing anything'
+complete -c am -n "__fish_am_using_subcommand dashboard" -l json -d 'Emit machine-readable JSON on stdout (for scripts)'
+complete -c am -n "__fish_am_using_subcommand dashboard" -l no-color -d 'Disable ANSI colors'
+complete -c am -n "__fish_am_using_subcommand dashboard" -s h -l help -d 'Print help'
+complete -c am -n "__fish_am_using_subcommand favorite" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand favorite" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
+complete -c am -n "__fish_am_using_subcommand favorite" -s v -l verbose -d 'Verbose output: show every command executed and its details'
+complete -c am -n "__fish_am_using_subcommand favorite" -s q -l quiet -d 'Quiet mode: only errors are printed'
+complete -c am -n "__fish_am_using_subcommand favorite" -s y -l yes -d 'Answer yes to every confirmation prompt'
+complete -c am -n "__fish_am_using_subcommand favorite" -l dry-run -d 'Simulate the action without changing anything'
+complete -c am -n "__fish_am_using_subcommand favorite" -l json -d 'Emit machine-readable JSON on stdout (for scripts)'
+complete -c am -n "__fish_am_using_subcommand favorite" -l no-color -d 'Disable ANSI colors'
+complete -c am -n "__fish_am_using_subcommand favorite" -s h -l help -d 'Print help'
+complete -c am -n "__fish_am_using_subcommand unfavorite" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand unfavorite" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
+complete -c am -n "__fish_am_using_subcommand unfavorite" -s v -l verbose -d 'Verbose output: show every command executed and its details'
+complete -c am -n "__fish_am_using_subcommand unfavorite" -s q -l quiet -d 'Quiet mode: only errors are printed'
+complete -c am -n "__fish_am_using_subcommand unfavorite" -s y -l yes -d 'Answer yes to every confirmation prompt'
+complete -c am -n "__fish_am_using_subcommand unfavorite" -l dry-run -d 'Simulate the action without changing anything'
+complete -c am -n "__fish_am_using_subcommand unfavorite" -l json -d 'Emit machine-readable JSON on stdout (for scripts)'
+complete -c am -n "__fish_am_using_subcommand unfavorite" -l no-color -d 'Disable ANSI colors'
+complete -c am -n "__fish_am_using_subcommand unfavorite" -s h -l help -d 'Print help'
+complete -c am -n "__fish_am_using_subcommand note" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand note" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
+complete -c am -n "__fish_am_using_subcommand note" -s v -l verbose -d 'Verbose output: show every command executed and its details'
+complete -c am -n "__fish_am_using_subcommand note" -s q -l quiet -d 'Quiet mode: only errors are printed'
+complete -c am -n "__fish_am_using_subcommand note" -s y -l yes -d 'Answer yes to every confirmation prompt'
+complete -c am -n "__fish_am_using_subcommand note" -l dry-run -d 'Simulate the action without changing anything'
+complete -c am -n "__fish_am_using_subcommand note" -l json -d 'Emit machine-readable JSON on stdout (for scripts)'
+complete -c am -n "__fish_am_using_subcommand note" -l no-color -d 'Disable ANSI colors'
+complete -c am -n "__fish_am_using_subcommand note" -s h -l help -d 'Print help'
+complete -c am -n "__fish_am_using_subcommand tag" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand tag" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
+complete -c am -n "__fish_am_using_subcommand tag" -s v -l verbose -d 'Verbose output: show every command executed and its details'
+complete -c am -n "__fish_am_using_subcommand tag" -s q -l quiet -d 'Quiet mode: only errors are printed'
+complete -c am -n "__fish_am_using_subcommand tag" -s y -l yes -d 'Answer yes to every confirmation prompt'
+complete -c am -n "__fish_am_using_subcommand tag" -l dry-run -d 'Simulate the action without changing anything'
+complete -c am -n "__fish_am_using_subcommand tag" -l json -d 'Emit machine-readable JSON on stdout (for scripts)'
+complete -c am -n "__fish_am_using_subcommand tag" -l no-color -d 'Disable ANSI colors'
+complete -c am -n "__fish_am_using_subcommand tag" -s h -l help -d 'Print help'
+complete -c am -n "__fish_am_using_subcommand untag" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand untag" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
+complete -c am -n "__fish_am_using_subcommand untag" -s v -l verbose -d 'Verbose output: show every command executed and its details'
+complete -c am -n "__fish_am_using_subcommand untag" -s q -l quiet -d 'Quiet mode: only errors are printed'
+complete -c am -n "__fish_am_using_subcommand untag" -s y -l yes -d 'Answer yes to every confirmation prompt'
+complete -c am -n "__fish_am_using_subcommand untag" -l dry-run -d 'Simulate the action without changing anything'
+complete -c am -n "__fish_am_using_subcommand untag" -l json -d 'Emit machine-readable JSON on stdout (for scripts)'
+complete -c am -n "__fish_am_using_subcommand untag" -l no-color -d 'Disable ANSI colors'
+complete -c am -n "__fish_am_using_subcommand untag" -s h -l help -d 'Print help'
+complete -c am -n "__fish_am_using_subcommand tags" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand tags" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
+complete -c am -n "__fish_am_using_subcommand tags" -s v -l verbose -d 'Verbose output: show every command executed and its details'
+complete -c am -n "__fish_am_using_subcommand tags" -s q -l quiet -d 'Quiet mode: only errors are printed'
+complete -c am -n "__fish_am_using_subcommand tags" -s y -l yes -d 'Answer yes to every confirmation prompt'
+complete -c am -n "__fish_am_using_subcommand tags" -l dry-run -d 'Simulate the action without changing anything'
+complete -c am -n "__fish_am_using_subcommand tags" -l json -d 'Emit machine-readable JSON on stdout (for scripts)'
+complete -c am -n "__fish_am_using_subcommand tags" -l no-color -d 'Disable ANSI colors'
+complete -c am -n "__fish_am_using_subcommand tags" -s h -l help -d 'Print help'
+complete -c am -n "__fish_am_using_subcommand profile; and not __fish_seen_subcommand_from list show" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand profile; and not __fish_seen_subcommand_from list show" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
+complete -c am -n "__fish_am_using_subcommand profile; and not __fish_seen_subcommand_from list show" -s v -l verbose -d 'Verbose output: show every command executed and its details'
+complete -c am -n "__fish_am_using_subcommand profile; and not __fish_seen_subcommand_from list show" -s q -l quiet -d 'Quiet mode: only errors are printed'
+complete -c am -n "__fish_am_using_subcommand profile; and not __fish_seen_subcommand_from list show" -s y -l yes -d 'Answer yes to every confirmation prompt'
+complete -c am -n "__fish_am_using_subcommand profile; and not __fish_seen_subcommand_from list show" -l dry-run -d 'Simulate the action without changing anything'
+complete -c am -n "__fish_am_using_subcommand profile; and not __fish_seen_subcommand_from list show" -l json -d 'Emit machine-readable JSON on stdout (for scripts)'
+complete -c am -n "__fish_am_using_subcommand profile; and not __fish_seen_subcommand_from list show" -l no-color -d 'Disable ANSI colors'
+complete -c am -n "__fish_am_using_subcommand profile; and not __fish_seen_subcommand_from list show" -s h -l help -d 'Print help'
+complete -c am -n "__fish_am_using_subcommand profile; and not __fish_seen_subcommand_from list show" -f -a "list" -d 'List every defined profile'
+complete -c am -n "__fish_am_using_subcommand profile; and not __fish_seen_subcommand_from list show" -f -a "show" -d 'Show one profile in detail (agent, env, args)'
+complete -c am -n "__fish_am_using_subcommand profile; and __fish_seen_subcommand_from list" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand profile; and __fish_seen_subcommand_from list" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
+complete -c am -n "__fish_am_using_subcommand profile; and __fish_seen_subcommand_from list" -s v -l verbose -d 'Verbose output: show every command executed and its details'
+complete -c am -n "__fish_am_using_subcommand profile; and __fish_seen_subcommand_from list" -s q -l quiet -d 'Quiet mode: only errors are printed'
+complete -c am -n "__fish_am_using_subcommand profile; and __fish_seen_subcommand_from list" -s y -l yes -d 'Answer yes to every confirmation prompt'
+complete -c am -n "__fish_am_using_subcommand profile; and __fish_seen_subcommand_from list" -l dry-run -d 'Simulate the action without changing anything'
+complete -c am -n "__fish_am_using_subcommand profile; and __fish_seen_subcommand_from list" -l json -d 'Emit machine-readable JSON on stdout (for scripts)'
+complete -c am -n "__fish_am_using_subcommand profile; and __fish_seen_subcommand_from list" -l no-color -d 'Disable ANSI colors'
+complete -c am -n "__fish_am_using_subcommand profile; and __fish_seen_subcommand_from list" -s h -l help -d 'Print help'
+complete -c am -n "__fish_am_using_subcommand profile; and __fish_seen_subcommand_from show" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand profile; and __fish_seen_subcommand_from show" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
+complete -c am -n "__fish_am_using_subcommand profile; and __fish_seen_subcommand_from show" -s v -l verbose -d 'Verbose output: show every command executed and its details'
+complete -c am -n "__fish_am_using_subcommand profile; and __fish_seen_subcommand_from show" -s q -l quiet -d 'Quiet mode: only errors are printed'
+complete -c am -n "__fish_am_using_subcommand profile; and __fish_seen_subcommand_from show" -s y -l yes -d 'Answer yes to every confirmation prompt'
+complete -c am -n "__fish_am_using_subcommand profile; and __fish_seen_subcommand_from show" -l dry-run -d 'Simulate the action without changing anything'
+complete -c am -n "__fish_am_using_subcommand profile; and __fish_seen_subcommand_from show" -l json -d 'Emit machine-readable JSON on stdout (for scripts)'
+complete -c am -n "__fish_am_using_subcommand profile; and __fish_seen_subcommand_from show" -l no-color -d 'Disable ANSI colors'
+complete -c am -n "__fish_am_using_subcommand profile; and __fish_seen_subcommand_from show" -s h -l help -d 'Print help'
+complete -c am -n "__fish_am_using_subcommand man" -l output -d 'Write the page(s) to this directory instead of stdout' -r -F
+complete -c am -n "__fish_am_using_subcommand man" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand man" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
+complete -c am -n "__fish_am_using_subcommand man" -s v -l verbose -d 'Verbose output: show every command executed and its details'
+complete -c am -n "__fish_am_using_subcommand man" -s q -l quiet -d 'Quiet mode: only errors are printed'
+complete -c am -n "__fish_am_using_subcommand man" -s y -l yes -d 'Answer yes to every confirmation prompt'
+complete -c am -n "__fish_am_using_subcommand man" -l dry-run -d 'Simulate the action without changing anything'
+complete -c am -n "__fish_am_using_subcommand man" -l json -d 'Emit machine-readable JSON on stdout (for scripts)'
+complete -c am -n "__fish_am_using_subcommand man" -l no-color -d 'Disable ANSI colors'
+complete -c am -n "__fish_am_using_subcommand man" -s h -l help -d 'Print help'
+complete -c am -n "__fish_am_using_subcommand _agents" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand _agents" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
+complete -c am -n "__fish_am_using_subcommand _agents" -l installed -d 'Only installed agents (managed + external), aliases and groups'
+complete -c am -n "__fish_am_using_subcommand _agents" -s v -l verbose -d 'Verbose output: show every command executed and its details'
+complete -c am -n "__fish_am_using_subcommand _agents" -s q -l quiet -d 'Quiet mode: only errors are printed'
+complete -c am -n "__fish_am_using_subcommand _agents" -s y -l yes -d 'Answer yes to every confirmation prompt'
+complete -c am -n "__fish_am_using_subcommand _agents" -l dry-run -d 'Simulate the action without changing anything'
+complete -c am -n "__fish_am_using_subcommand _agents" -l json -d 'Emit machine-readable JSON on stdout (for scripts)'
+complete -c am -n "__fish_am_using_subcommand _agents" -l no-color -d 'Disable ANSI colors'
+complete -c am -n "__fish_am_using_subcommand _agents" -s h -l help -d 'Print help'
+complete -c am -n "__fish_am_using_subcommand alias; and not __fish_seen_subcommand_from add remove list" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand alias; and not __fish_seen_subcommand_from add remove list" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
+complete -c am -n "__fish_am_using_subcommand alias; and not __fish_seen_subcommand_from add remove list" -s v -l verbose -d 'Verbose output: show every command executed and its details'
+complete -c am -n "__fish_am_using_subcommand alias; and not __fish_seen_subcommand_from add remove list" -s q -l quiet -d 'Quiet mode: only errors are printed'
+complete -c am -n "__fish_am_using_subcommand alias; and not __fish_seen_subcommand_from add remove list" -s y -l yes -d 'Answer yes to every confirmation prompt'
+complete -c am -n "__fish_am_using_subcommand alias; and not __fish_seen_subcommand_from add remove list" -l dry-run -d 'Simulate the action without changing anything'
+complete -c am -n "__fish_am_using_subcommand alias; and not __fish_seen_subcommand_from add remove list" -l json -d 'Emit machine-readable JSON on stdout (for scripts)'
+complete -c am -n "__fish_am_using_subcommand alias; and not __fish_seen_subcommand_from add remove list" -l no-color -d 'Disable ANSI colors'
+complete -c am -n "__fish_am_using_subcommand alias; and not __fish_seen_subcommand_from add remove list" -s h -l help -d 'Print help'
+complete -c am -n "__fish_am_using_subcommand alias; and not __fish_seen_subcommand_from add remove list" -f -a "add" -d 'Add an alias (am alias add cc claude-code)'
+complete -c am -n "__fish_am_using_subcommand alias; and not __fish_seen_subcommand_from add remove list" -f -a "remove" -d 'Remove an alias'
+complete -c am -n "__fish_am_using_subcommand alias; and not __fish_seen_subcommand_from add remove list" -f -a "list" -d 'List every alias'
+complete -c am -n "__fish_am_using_subcommand alias; and __fish_seen_subcommand_from add" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand alias; and __fish_seen_subcommand_from add" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
+complete -c am -n "__fish_am_using_subcommand alias; and __fish_seen_subcommand_from add" -s v -l verbose -d 'Verbose output: show every command executed and its details'
+complete -c am -n "__fish_am_using_subcommand alias; and __fish_seen_subcommand_from add" -s q -l quiet -d 'Quiet mode: only errors are printed'
+complete -c am -n "__fish_am_using_subcommand alias; and __fish_seen_subcommand_from add" -s y -l yes -d 'Answer yes to every confirmation prompt'
+complete -c am -n "__fish_am_using_subcommand alias; and __fish_seen_subcommand_from add" -l dry-run -d 'Simulate the action without changing anything'
+complete -c am -n "__fish_am_using_subcommand alias; and __fish_seen_subcommand_from add" -l json -d 'Emit machine-readable JSON on stdout (for scripts)'
+complete -c am -n "__fish_am_using_subcommand alias; and __fish_seen_subcommand_from add" -l no-color -d 'Disable ANSI colors'
+complete -c am -n "__fish_am_using_subcommand alias; and __fish_seen_subcommand_from add" -s h -l help -d 'Print help'
+complete -c am -n "__fish_am_using_subcommand alias; and __fish_seen_subcommand_from remove" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand alias; and __fish_seen_subcommand_from remove" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
+complete -c am -n "__fish_am_using_subcommand alias; and __fish_seen_subcommand_from remove" -s v -l verbose -d 'Verbose output: show every command executed and its details'
+complete -c am -n "__fish_am_using_subcommand alias; and __fish_seen_subcommand_from remove" -s q -l quiet -d 'Quiet mode: only errors are printed'
+complete -c am -n "__fish_am_using_subcommand alias; and __fish_seen_subcommand_from remove" -s y -l yes -d 'Answer yes to every confirmation prompt'
+complete -c am -n "__fish_am_using_subcommand alias; and __fish_seen_subcommand_from remove" -l dry-run -d 'Simulate the action without changing anything'
+complete -c am -n "__fish_am_using_subcommand alias; and __fish_seen_subcommand_from remove" -l json -d 'Emit machine-readable JSON on stdout (for scripts)'
+complete -c am -n "__fish_am_using_subcommand alias; and __fish_seen_subcommand_from remove" -l no-color -d 'Disable ANSI colors'
+complete -c am -n "__fish_am_using_subcommand alias; and __fish_seen_subcommand_from remove" -s h -l help -d 'Print help'
+complete -c am -n "__fish_am_using_subcommand alias; and __fish_seen_subcommand_from list" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand alias; and __fish_seen_subcommand_from list" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
+complete -c am -n "__fish_am_using_subcommand alias; and __fish_seen_subcommand_from list" -s v -l verbose -d 'Verbose output: show every command executed and its details'
+complete -c am -n "__fish_am_using_subcommand alias; and __fish_seen_subcommand_from list" -s q -l quiet -d 'Quiet mode: only errors are printed'
+complete -c am -n "__fish_am_using_subcommand alias; and __fish_seen_subcommand_from list" -s y -l yes -d 'Answer yes to every confirmation prompt'
+complete -c am -n "__fish_am_using_subcommand alias; and __fish_seen_subcommand_from list" -l dry-run -d 'Simulate the action without changing anything'
+complete -c am -n "__fish_am_using_subcommand alias; and __fish_seen_subcommand_from list" -l json -d 'Emit machine-readable JSON on stdout (for scripts)'
+complete -c am -n "__fish_am_using_subcommand alias; and __fish_seen_subcommand_from list" -l no-color -d 'Disable ANSI colors'
+complete -c am -n "__fish_am_using_subcommand alias; and __fish_seen_subcommand_from list" -s h -l help -d 'Print help'
+complete -c am -n "__fish_am_using_subcommand secret; and not __fish_seen_subcommand_from set unset list" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand secret; and not __fish_seen_subcommand_from set unset list" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
+complete -c am -n "__fish_am_using_subcommand secret; and not __fish_seen_subcommand_from set unset list" -s v -l verbose -d 'Verbose output: show every command executed and its details'
+complete -c am -n "__fish_am_using_subcommand secret; and not __fish_seen_subcommand_from set unset list" -s q -l quiet -d 'Quiet mode: only errors are printed'
+complete -c am -n "__fish_am_using_subcommand secret; and not __fish_seen_subcommand_from set unset list" -s y -l yes -d 'Answer yes to every confirmation prompt'
+complete -c am -n "__fish_am_using_subcommand secret; and not __fish_seen_subcommand_from set unset list" -l dry-run -d 'Simulate the action without changing anything'
+complete -c am -n "__fish_am_using_subcommand secret; and not __fish_seen_subcommand_from set unset list" -l json -d 'Emit machine-readable JSON on stdout (for scripts)'
+complete -c am -n "__fish_am_using_subcommand secret; and not __fish_seen_subcommand_from set unset list" -l no-color -d 'Disable ANSI colors'
+complete -c am -n "__fish_am_using_subcommand secret; and not __fish_seen_subcommand_from set unset list" -s h -l help -d 'Print help'
+complete -c am -n "__fish_am_using_subcommand secret; and not __fish_seen_subcommand_from set unset list" -f -a "set" -d 'Store a secret for an agent'
+complete -c am -n "__fish_am_using_subcommand secret; and not __fish_seen_subcommand_from set unset list" -f -a "unset" -d 'Remove a secret'
+complete -c am -n "__fish_am_using_subcommand secret; and not __fish_seen_subcommand_from set unset list" -f -a "list" -d 'List stored secret names (values are never shown)'
+complete -c am -n "__fish_am_using_subcommand secret; and __fish_seen_subcommand_from set" -l agent -d 'Agent it belongs to' -r
+complete -c am -n "__fish_am_using_subcommand secret; and __fish_seen_subcommand_from set" -l value -d 'Secret value (prefer --value over shell history; never logged)' -r
+complete -c am -n "__fish_am_using_subcommand secret; and __fish_seen_subcommand_from set" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand secret; and __fish_seen_subcommand_from set" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
+complete -c am -n "__fish_am_using_subcommand secret; and __fish_seen_subcommand_from set" -s v -l verbose -d 'Verbose output: show every command executed and its details'
+complete -c am -n "__fish_am_using_subcommand secret; and __fish_seen_subcommand_from set" -s q -l quiet -d 'Quiet mode: only errors are printed'
+complete -c am -n "__fish_am_using_subcommand secret; and __fish_seen_subcommand_from set" -s y -l yes -d 'Answer yes to every confirmation prompt'
+complete -c am -n "__fish_am_using_subcommand secret; and __fish_seen_subcommand_from set" -l dry-run -d 'Simulate the action without changing anything'
+complete -c am -n "__fish_am_using_subcommand secret; and __fish_seen_subcommand_from set" -l json -d 'Emit machine-readable JSON on stdout (for scripts)'
+complete -c am -n "__fish_am_using_subcommand secret; and __fish_seen_subcommand_from set" -l no-color -d 'Disable ANSI colors'
+complete -c am -n "__fish_am_using_subcommand secret; and __fish_seen_subcommand_from set" -s h -l help -d 'Print help'
+complete -c am -n "__fish_am_using_subcommand secret; and __fish_seen_subcommand_from unset" -l agent -d 'Agent it belongs to' -r
+complete -c am -n "__fish_am_using_subcommand secret; and __fish_seen_subcommand_from unset" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand secret; and __fish_seen_subcommand_from unset" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
+complete -c am -n "__fish_am_using_subcommand secret; and __fish_seen_subcommand_from unset" -s v -l verbose -d 'Verbose output: show every command executed and its details'
+complete -c am -n "__fish_am_using_subcommand secret; and __fish_seen_subcommand_from unset" -s q -l quiet -d 'Quiet mode: only errors are printed'
+complete -c am -n "__fish_am_using_subcommand secret; and __fish_seen_subcommand_from unset" -s y -l yes -d 'Answer yes to every confirmation prompt'
+complete -c am -n "__fish_am_using_subcommand secret; and __fish_seen_subcommand_from unset" -l dry-run -d 'Simulate the action without changing anything'
+complete -c am -n "__fish_am_using_subcommand secret; and __fish_seen_subcommand_from unset" -l json -d 'Emit machine-readable JSON on stdout (for scripts)'
+complete -c am -n "__fish_am_using_subcommand secret; and __fish_seen_subcommand_from unset" -l no-color -d 'Disable ANSI colors'
+complete -c am -n "__fish_am_using_subcommand secret; and __fish_seen_subcommand_from unset" -s h -l help -d 'Print help'
+complete -c am -n "__fish_am_using_subcommand secret; and __fish_seen_subcommand_from list" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand secret; and __fish_seen_subcommand_from list" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
+complete -c am -n "__fish_am_using_subcommand secret; and __fish_seen_subcommand_from list" -s v -l verbose -d 'Verbose output: show every command executed and its details'
+complete -c am -n "__fish_am_using_subcommand secret; and __fish_seen_subcommand_from list" -s q -l quiet -d 'Quiet mode: only errors are printed'
+complete -c am -n "__fish_am_using_subcommand secret; and __fish_seen_subcommand_from list" -s y -l yes -d 'Answer yes to every confirmation prompt'
+complete -c am -n "__fish_am_using_subcommand secret; and __fish_seen_subcommand_from list" -l dry-run -d 'Simulate the action without changing anything'
+complete -c am -n "__fish_am_using_subcommand secret; and __fish_seen_subcommand_from list" -l json -d 'Emit machine-readable JSON on stdout (for scripts)'
+complete -c am -n "__fish_am_using_subcommand secret; and __fish_seen_subcommand_from list" -l no-color -d 'Disable ANSI colors'
+complete -c am -n "__fish_am_using_subcommand secret; and __fish_seen_subcommand_from list" -s h -l help -d 'Print help'
 complete -c am -n "__fish_am_using_subcommand start" -l args -d 'Extra arguments passed to the agent (repeatable; quoted strings are split on spaces)' -r
 complete -c am -n "__fish_am_using_subcommand start" -l env -d 'Set an environment variable for the agent (repeatable): --env KEY=VALUE' -r
+complete -c am -n "__fish_am_using_subcommand start" -l profile -d 'Apply an environment profile (env + args, defined in the config)' -r
 complete -c am -n "__fish_am_using_subcommand start" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand start" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
 complete -c am -n "__fish_am_using_subcommand start" -s b -l background -d 'Run detached in the background; output goes to the agent log file'
 complete -c am -n "__fish_am_using_subcommand start" -s f -l foreground -d 'Run in the foreground, attached to this terminal (the default)'
 complete -c am -n "__fish_am_using_subcommand start" -l notify -d 'Send a desktop notification once the agent has started'
@@ -77,6 +333,7 @@ complete -c am -n "__fish_am_using_subcommand start" -l no-color -d 'Disable ANS
 complete -c am -n "__fish_am_using_subcommand start" -s h -l help -d 'Print help'
 complete -c am -n "__fish_am_using_subcommand stop" -l timeout -d 'Grace period in seconds before killing (default: from config, 5s)' -r
 complete -c am -n "__fish_am_using_subcommand stop" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand stop" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
 complete -c am -n "__fish_am_using_subcommand stop" -l force -d 'Kill immediately instead of terminating gracefully'
 complete -c am -n "__fish_am_using_subcommand stop" -s v -l verbose -d 'Verbose output: show every command executed and its details'
 complete -c am -n "__fish_am_using_subcommand stop" -s q -l quiet -d 'Quiet mode: only errors are printed'
@@ -87,8 +344,10 @@ complete -c am -n "__fish_am_using_subcommand stop" -l no-color -d 'Disable ANSI
 complete -c am -n "__fish_am_using_subcommand stop" -s h -l help -d 'Print help'
 complete -c am -n "__fish_am_using_subcommand restart" -l args -d 'Extra arguments passed to the agent (repeatable; quoted strings are split on spaces)' -r
 complete -c am -n "__fish_am_using_subcommand restart" -l env -d 'Set an environment variable for the agent (repeatable): --env KEY=VALUE' -r
+complete -c am -n "__fish_am_using_subcommand restart" -l profile -d 'Apply an environment profile (env + args, defined in the config)' -r
 complete -c am -n "__fish_am_using_subcommand restart" -l timeout -d 'Grace period in seconds before killing (default: from config, 5s)' -r
 complete -c am -n "__fish_am_using_subcommand restart" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand restart" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
 complete -c am -n "__fish_am_using_subcommand restart" -s b -l background -d 'Run detached in the background; output goes to the agent log file'
 complete -c am -n "__fish_am_using_subcommand restart" -s f -l foreground -d 'Run in the foreground, attached to this terminal (the default)'
 complete -c am -n "__fish_am_using_subcommand restart" -l notify -d 'Send a desktop notification once the agent has started'
@@ -101,6 +360,7 @@ complete -c am -n "__fish_am_using_subcommand restart" -l json -d 'Emit machine-
 complete -c am -n "__fish_am_using_subcommand restart" -l no-color -d 'Disable ANSI colors'
 complete -c am -n "__fish_am_using_subcommand restart" -s h -l help -d 'Print help'
 complete -c am -n "__fish_am_using_subcommand status" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand status" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
 complete -c am -n "__fish_am_using_subcommand status" -s v -l verbose -d 'Verbose output: show every command executed and its details'
 complete -c am -n "__fish_am_using_subcommand status" -s q -l quiet -d 'Quiet mode: only errors are printed'
 complete -c am -n "__fish_am_using_subcommand status" -s y -l yes -d 'Answer yes to every confirmation prompt'
@@ -108,8 +368,88 @@ complete -c am -n "__fish_am_using_subcommand status" -l dry-run -d 'Simulate th
 complete -c am -n "__fish_am_using_subcommand status" -l json -d 'Emit machine-readable JSON on stdout (for scripts)'
 complete -c am -n "__fish_am_using_subcommand status" -l no-color -d 'Disable ANSI colors'
 complete -c am -n "__fish_am_using_subcommand status" -s h -l help -d 'Print help'
+complete -c am -n "__fish_am_using_subcommand sessions" -l project -d 'Only sessions of this project' -r
+complete -c am -n "__fish_am_using_subcommand sessions" -l status -d 'Only sessions with this status (running, stopped, failed, interrupted)' -r
+complete -c am -n "__fish_am_using_subcommand sessions" -l show -d 'Show one session in detail (summary + log excerpt)' -r
+complete -c am -n "__fish_am_using_subcommand sessions" -l resume -d 'Resume a finished session: relaunch the agent with its recorded arguments' -r
+complete -c am -n "__fish_am_using_subcommand sessions" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand sessions" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
+complete -c am -n "__fish_am_using_subcommand sessions" -s v -l verbose -d 'Verbose output: show every command executed and its details'
+complete -c am -n "__fish_am_using_subcommand sessions" -s q -l quiet -d 'Quiet mode: only errors are printed'
+complete -c am -n "__fish_am_using_subcommand sessions" -s y -l yes -d 'Answer yes to every confirmation prompt'
+complete -c am -n "__fish_am_using_subcommand sessions" -l dry-run -d 'Simulate the action without changing anything'
+complete -c am -n "__fish_am_using_subcommand sessions" -l json -d 'Emit machine-readable JSON on stdout (for scripts)'
+complete -c am -n "__fish_am_using_subcommand sessions" -l no-color -d 'Disable ANSI colors'
+complete -c am -n "__fish_am_using_subcommand sessions" -s h -l help -d 'Print help'
+complete -c am -n "__fish_am_using_subcommand stats" -l period -d 'Only events of the last period (7d, 30d, 90d, all)' -r
+complete -c am -n "__fish_am_using_subcommand stats" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand stats" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
+complete -c am -n "__fish_am_using_subcommand stats" -s v -l verbose -d 'Verbose output: show every command executed and its details'
+complete -c am -n "__fish_am_using_subcommand stats" -s q -l quiet -d 'Quiet mode: only errors are printed'
+complete -c am -n "__fish_am_using_subcommand stats" -s y -l yes -d 'Answer yes to every confirmation prompt'
+complete -c am -n "__fish_am_using_subcommand stats" -l dry-run -d 'Simulate the action without changing anything'
+complete -c am -n "__fish_am_using_subcommand stats" -l json -d 'Emit machine-readable JSON on stdout (for scripts)'
+complete -c am -n "__fish_am_using_subcommand stats" -l no-color -d 'Disable ANSI colors'
+complete -c am -n "__fish_am_using_subcommand stats" -s h -l help -d 'Print help'
+complete -c am -n "__fish_am_using_subcommand top" -l period -d 'Only events of the last period (7d, 30d, 90d, all)' -r
+complete -c am -n "__fish_am_using_subcommand top" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand top" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
+complete -c am -n "__fish_am_using_subcommand top" -s v -l verbose -d 'Verbose output: show every command executed and its details'
+complete -c am -n "__fish_am_using_subcommand top" -s q -l quiet -d 'Quiet mode: only errors are printed'
+complete -c am -n "__fish_am_using_subcommand top" -s y -l yes -d 'Answer yes to every confirmation prompt'
+complete -c am -n "__fish_am_using_subcommand top" -l dry-run -d 'Simulate the action without changing anything'
+complete -c am -n "__fish_am_using_subcommand top" -l json -d 'Emit machine-readable JSON on stdout (for scripts)'
+complete -c am -n "__fish_am_using_subcommand top" -l no-color -d 'Disable ANSI colors'
+complete -c am -n "__fish_am_using_subcommand top" -s h -l help -d 'Print help'
+complete -c am -n "__fish_am_using_subcommand report" -l output -d 'Output file (default: report-YYYYMMDD.md in the state directory)' -r -F
+complete -c am -n "__fish_am_using_subcommand report" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand report" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
+complete -c am -n "__fish_am_using_subcommand report" -l last-week -d 'Cover the last 7 days'
+complete -c am -n "__fish_am_using_subcommand report" -l last-month -d 'Cover the last 30 days'
+complete -c am -n "__fish_am_using_subcommand report" -s v -l verbose -d 'Verbose output: show every command executed and its details'
+complete -c am -n "__fish_am_using_subcommand report" -s q -l quiet -d 'Quiet mode: only errors are printed'
+complete -c am -n "__fish_am_using_subcommand report" -s y -l yes -d 'Answer yes to every confirmation prompt'
+complete -c am -n "__fish_am_using_subcommand report" -l dry-run -d 'Simulate the action without changing anything'
+complete -c am -n "__fish_am_using_subcommand report" -l json -d 'Emit machine-readable JSON on stdout (for scripts)'
+complete -c am -n "__fish_am_using_subcommand report" -l no-color -d 'Disable ANSI colors'
+complete -c am -n "__fish_am_using_subcommand report" -s h -l help -d 'Print help'
+complete -c am -n "__fish_am_using_subcommand projects" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand projects" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
+complete -c am -n "__fish_am_using_subcommand projects" -s v -l verbose -d 'Verbose output: show every command executed and its details'
+complete -c am -n "__fish_am_using_subcommand projects" -s q -l quiet -d 'Quiet mode: only errors are printed'
+complete -c am -n "__fish_am_using_subcommand projects" -s y -l yes -d 'Answer yes to every confirmation prompt'
+complete -c am -n "__fish_am_using_subcommand projects" -l dry-run -d 'Simulate the action without changing anything'
+complete -c am -n "__fish_am_using_subcommand projects" -l json -d 'Emit machine-readable JSON on stdout (for scripts)'
+complete -c am -n "__fish_am_using_subcommand projects" -l no-color -d 'Disable ANSI colors'
+complete -c am -n "__fish_am_using_subcommand projects" -s h -l help -d 'Print help'
+complete -c am -n "__fish_am_using_subcommand timeline" -l project -d 'Only activity of this project' -r
+complete -c am -n "__fish_am_using_subcommand timeline" -l since -d 'Only activity at or after this date (YYYY-MM-DD or RFC 3339)' -r
+complete -c am -n "__fish_am_using_subcommand timeline" -l limit -d 'Maximum number of entries (default: 50)' -r
+complete -c am -n "__fish_am_using_subcommand timeline" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand timeline" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
+complete -c am -n "__fish_am_using_subcommand timeline" -s v -l verbose -d 'Verbose output: show every command executed and its details'
+complete -c am -n "__fish_am_using_subcommand timeline" -s q -l quiet -d 'Quiet mode: only errors are printed'
+complete -c am -n "__fish_am_using_subcommand timeline" -s y -l yes -d 'Answer yes to every confirmation prompt'
+complete -c am -n "__fish_am_using_subcommand timeline" -l dry-run -d 'Simulate the action without changing anything'
+complete -c am -n "__fish_am_using_subcommand timeline" -l json -d 'Emit machine-readable JSON on stdout (for scripts)'
+complete -c am -n "__fish_am_using_subcommand timeline" -l no-color -d 'Disable ANSI colors'
+complete -c am -n "__fish_am_using_subcommand timeline" -s h -l help -d 'Print help'
+complete -c am -n "__fish_am_using_subcommand log" -l kind -d 'Only these event kinds (comma separated: start,stop,run,install,...)' -r
+complete -c am -n "__fish_am_using_subcommand log" -l since -d 'Only events at or after this date (YYYY-MM-DD or RFC 3339)' -r
+complete -c am -n "__fish_am_using_subcommand log" -l limit -d 'Maximum number of events (default: 50)' -r
+complete -c am -n "__fish_am_using_subcommand log" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand log" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
+complete -c am -n "__fish_am_using_subcommand log" -l follow -d 'Follow the journal as new events arrive'
+complete -c am -n "__fish_am_using_subcommand log" -s v -l verbose -d 'Verbose output: show every command executed and its details'
+complete -c am -n "__fish_am_using_subcommand log" -s q -l quiet -d 'Quiet mode: only errors are printed'
+complete -c am -n "__fish_am_using_subcommand log" -s y -l yes -d 'Answer yes to every confirmation prompt'
+complete -c am -n "__fish_am_using_subcommand log" -l dry-run -d 'Simulate the action without changing anything'
+complete -c am -n "__fish_am_using_subcommand log" -l json -d 'Emit machine-readable JSON on stdout (for scripts)'
+complete -c am -n "__fish_am_using_subcommand log" -l no-color -d 'Disable ANSI colors'
+complete -c am -n "__fish_am_using_subcommand log" -s h -l help -d 'Print help'
 complete -c am -n "__fish_am_using_subcommand install" -l method -d 'Select the install method (index, or type: npm, pip, uv, cargo, go, bun, curl, binary, git)' -r
 complete -c am -n "__fish_am_using_subcommand install" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand install" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
 complete -c am -n "__fish_am_using_subcommand install" -l force -d 'Reinstall even if already installed'
 complete -c am -n "__fish_am_using_subcommand install" -s v -l verbose -d 'Verbose output: show every command executed and its details'
 complete -c am -n "__fish_am_using_subcommand install" -s q -l quiet -d 'Quiet mode: only errors are printed'
@@ -119,6 +459,7 @@ complete -c am -n "__fish_am_using_subcommand install" -l json -d 'Emit machine-
 complete -c am -n "__fish_am_using_subcommand install" -l no-color -d 'Disable ANSI colors'
 complete -c am -n "__fish_am_using_subcommand install" -s h -l help -d 'Print help'
 complete -c am -n "__fish_am_using_subcommand uninstall" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand uninstall" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
 complete -c am -n "__fish_am_using_subcommand uninstall" -l purge -d 'Also remove logs and the agent entry from the user config file'
 complete -c am -n "__fish_am_using_subcommand uninstall" -s v -l verbose -d 'Verbose output: show every command executed and its details'
 complete -c am -n "__fish_am_using_subcommand uninstall" -s q -l quiet -d 'Quiet mode: only errors are printed'
@@ -128,6 +469,7 @@ complete -c am -n "__fish_am_using_subcommand uninstall" -l json -d 'Emit machin
 complete -c am -n "__fish_am_using_subcommand uninstall" -l no-color -d 'Disable ANSI colors'
 complete -c am -n "__fish_am_using_subcommand uninstall" -s h -l help -d 'Print help'
 complete -c am -n "__fish_am_using_subcommand update" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand update" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
 complete -c am -n "__fish_am_using_subcommand update" -l all -d 'Update every installed managed agent'
 complete -c am -n "__fish_am_using_subcommand update" -s v -l verbose -d 'Verbose output: show every command executed and its details'
 complete -c am -n "__fish_am_using_subcommand update" -s q -l quiet -d 'Quiet mode: only errors are printed'
@@ -137,7 +479,9 @@ complete -c am -n "__fish_am_using_subcommand update" -l json -d 'Emit machine-r
 complete -c am -n "__fish_am_using_subcommand update" -l no-color -d 'Disable ANSI colors'
 complete -c am -n "__fish_am_using_subcommand update" -s h -l help -d 'Print help'
 complete -c am -n "__fish_am_using_subcommand search" -l category -d 'Restrict to this category' -r
+complete -c am -n "__fish_am_using_subcommand search" -l tag -d 'Only agents carrying this personal tag' -r
 complete -c am -n "__fish_am_using_subcommand search" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand search" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
 complete -c am -n "__fish_am_using_subcommand search" -s v -l verbose -d 'Verbose output: show every command executed and its details'
 complete -c am -n "__fish_am_using_subcommand search" -s q -l quiet -d 'Quiet mode: only errors are printed'
 complete -c am -n "__fish_am_using_subcommand search" -s y -l yes -d 'Answer yes to every confirmation prompt'
@@ -145,7 +489,24 @@ complete -c am -n "__fish_am_using_subcommand search" -l dry-run -d 'Simulate th
 complete -c am -n "__fish_am_using_subcommand search" -l json -d 'Emit machine-readable JSON on stdout (for scripts)'
 complete -c am -n "__fish_am_using_subcommand search" -l no-color -d 'Disable ANSI colors'
 complete -c am -n "__fish_am_using_subcommand search" -s h -l help -d 'Print help'
+complete -c am -n "__fish_am_using_subcommand history" -l kind -d 'Only commands of this kind (am or shell)' -r
+complete -c am -n "__fish_am_using_subcommand history" -l cwd -d 'Only commands run in this directory' -r
+complete -c am -n "__fish_am_using_subcommand history" -l search -d 'Full-text search in the command line' -r
+complete -c am -n "__fish_am_using_subcommand history" -l session -d 'Only commands of this session' -r
+complete -c am -n "__fish_am_using_subcommand history" -l limit -d 'Maximum number of entries (default: 100)' -r
+complete -c am -n "__fish_am_using_subcommand history" -l rerun -d 'Re-run the Nth most recent entry (with confirmation)' -r
+complete -c am -n "__fish_am_using_subcommand history" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand history" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
+complete -c am -n "__fish_am_using_subcommand history" -l failed -d 'Only failed commands'
+complete -c am -n "__fish_am_using_subcommand history" -s v -l verbose -d 'Verbose output: show every command executed and its details'
+complete -c am -n "__fish_am_using_subcommand history" -s q -l quiet -d 'Quiet mode: only errors are printed'
+complete -c am -n "__fish_am_using_subcommand history" -s y -l yes -d 'Answer yes to every confirmation prompt'
+complete -c am -n "__fish_am_using_subcommand history" -l dry-run -d 'Simulate the action without changing anything'
+complete -c am -n "__fish_am_using_subcommand history" -l json -d 'Emit machine-readable JSON on stdout (for scripts)'
+complete -c am -n "__fish_am_using_subcommand history" -l no-color -d 'Disable ANSI colors'
+complete -c am -n "__fish_am_using_subcommand history" -s h -l help -d 'Print help'
 complete -c am -n "__fish_am_using_subcommand info" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand info" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
 complete -c am -n "__fish_am_using_subcommand info" -s v -l verbose -d 'Verbose output: show every command executed and its details'
 complete -c am -n "__fish_am_using_subcommand info" -s q -l quiet -d 'Quiet mode: only errors are printed'
 complete -c am -n "__fish_am_using_subcommand info" -s y -l yes -d 'Answer yes to every confirmation prompt'
@@ -153,21 +514,52 @@ complete -c am -n "__fish_am_using_subcommand info" -l dry-run -d 'Simulate the
 complete -c am -n "__fish_am_using_subcommand info" -l json -d 'Emit machine-readable JSON on stdout (for scripts)'
 complete -c am -n "__fish_am_using_subcommand info" -l no-color -d 'Disable ANSI colors'
 complete -c am -n "__fish_am_using_subcommand info" -s h -l help -d 'Print help'
-complete -c am -n "__fish_am_using_subcommand config; and not __fish_seen_subcommand_from show path edit validate add help" -s c -l config -d 'Use an alternate configuration file' -r -F
-complete -c am -n "__fish_am_using_subcommand config; and not __fish_seen_subcommand_from show path edit validate add help" -s v -l verbose -d 'Verbose output: show every command executed and its details'
-complete -c am -n "__fish_am_using_subcommand config; and not __fish_seen_subcommand_from show path edit validate add help" -s q -l quiet -d 'Quiet mode: only errors are printed'
-complete -c am -n "__fish_am_using_subcommand config; and not __fish_seen_subcommand_from show path edit validate add help" -s y -l yes -d 'Answer yes to every confirmation prompt'
-complete -c am -n "__fish_am_using_subcommand config; and not __fish_seen_subcommand_from show path edit validate add help" -l dry-run -d 'Simulate the action without changing anything'
-complete -c am -n "__fish_am_using_subcommand config; and not __fish_seen_subcommand_from show path edit validate add help" -l json -d 'Emit machine-readable JSON on stdout (for scripts)'
-complete -c am -n "__fish_am_using_subcommand config; and not __fish_seen_subcommand_from show path edit validate add help" -l no-color -d 'Disable ANSI colors'
-complete -c am -n "__fish_am_using_subcommand config; and not __fish_seen_subcommand_from show path edit validate add help" -s h -l help -d 'Print help'
-complete -c am -n "__fish_am_using_subcommand config; and not __fish_seen_subcommand_from show path edit validate add help" -f -a "show" -d 'Print the effective (merged) configuration as YAML'
-complete -c am -n "__fish_am_using_subcommand config; and not __fish_seen_subcommand_from show path edit validate add help" -f -a "path" -d 'Print the location of the configuration file(s)'
-complete -c am -n "__fish_am_using_subcommand config; and not __fish_seen_subcommand_from show path edit validate add help" -f -a "edit" -d 'Open the user configuration file in your editor'
-complete -c am -n "__fish_am_using_subcommand config; and not __fish_seen_subcommand_from show path edit validate add help" -f -a "validate" -d 'Validate the configuration file(s)'
-complete -c am -n "__fish_am_using_subcommand config; and not __fish_seen_subcommand_from show path edit validate add help" -f -a "add" -d 'Add another agent definition file to the user configuration'
-complete -c am -n "__fish_am_using_subcommand config; and not __fish_seen_subcommand_from show path edit validate add help" -f -a "help" -d 'Print this message or the help of the given subcommand(s)'
+complete -c am -n "__fish_am_using_subcommand init" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand init" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
+complete -c am -n "__fish_am_using_subcommand init" -l force -d 'Overwrite an existing agent-manager.yaml'
+complete -c am -n "__fish_am_using_subcommand init" -s v -l verbose -d 'Verbose output: show every command executed and its details'
+complete -c am -n "__fish_am_using_subcommand init" -s q -l quiet -d 'Quiet mode: only errors are printed'
+complete -c am -n "__fish_am_using_subcommand init" -s y -l yes -d 'Answer yes to every confirmation prompt'
+complete -c am -n "__fish_am_using_subcommand init" -l dry-run -d 'Simulate the action without changing anything'
+complete -c am -n "__fish_am_using_subcommand init" -l json -d 'Emit machine-readable JSON on stdout (for scripts)'
+complete -c am -n "__fish_am_using_subcommand init" -l no-color -d 'Disable ANSI colors'
+complete -c am -n "__fish_am_using_subcommand init" -s h -l help -d 'Print help'
+complete -c am -n "__fish_am_using_subcommand help" -l find -d 'Search through all help commands table' -r
+complete -c am -n "__fish_am_using_subcommand help" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand help" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
+complete -c am -n "__fish_am_using_subcommand help" -s v -l verbose -d 'Verbose output: show every command executed and its details'
+complete -c am -n "__fish_am_using_subcommand help" -s q -l quiet -d 'Quiet mode: only errors are printed'
+complete -c am -n "__fish_am_using_subcommand help" -s y -l yes -d 'Answer yes to every confirmation prompt'
+complete -c am -n "__fish_am_using_subcommand help" -l dry-run -d 'Simulate the action without changing anything'
+complete -c am -n "__fish_am_using_subcommand help" -l json -d 'Emit machine-readable JSON on stdout (for scripts)'
+complete -c am -n "__fish_am_using_subcommand help" -l no-color -d 'Disable ANSI colors'
+complete -c am -n "__fish_am_using_subcommand help" -s h -l help -d 'Print help'
+complete -c am -n "__fish_am_using_subcommand version" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand version" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
+complete -c am -n "__fish_am_using_subcommand version" -s v -l verbose -d 'Verbose output: show every command executed and its details'
+complete -c am -n "__fish_am_using_subcommand version" -s q -l quiet -d 'Quiet mode: only errors are printed'
+complete -c am -n "__fish_am_using_subcommand version" -s y -l yes -d 'Answer yes to every confirmation prompt'
+complete -c am -n "__fish_am_using_subcommand version" -l dry-run -d 'Simulate the action without changing anything'
+complete -c am -n "__fish_am_using_subcommand version" -l json -d 'Emit machine-readable JSON on stdout (for scripts)'
+complete -c am -n "__fish_am_using_subcommand version" -l no-color -d 'Disable ANSI colors'
+complete -c am -n "__fish_am_using_subcommand version" -s h -l help -d 'Print help'
+complete -c am -n "__fish_am_using_subcommand config; and not __fish_seen_subcommand_from show path edit validate add set" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand config; and not __fish_seen_subcommand_from show path edit validate add set" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
+complete -c am -n "__fish_am_using_subcommand config; and not __fish_seen_subcommand_from show path edit validate add set" -s v -l verbose -d 'Verbose output: show every command executed and its details'
+complete -c am -n "__fish_am_using_subcommand config; and not __fish_seen_subcommand_from show path edit validate add set" -s q -l quiet -d 'Quiet mode: only errors are printed'
+complete -c am -n "__fish_am_using_subcommand config; and not __fish_seen_subcommand_from show path edit validate add set" -s y -l yes -d 'Answer yes to every confirmation prompt'
+complete -c am -n "__fish_am_using_subcommand config; and not __fish_seen_subcommand_from show path edit validate add set" -l dry-run -d 'Simulate the action without changing anything'
+complete -c am -n "__fish_am_using_subcommand config; and not __fish_seen_subcommand_from show path edit validate add set" -l json -d 'Emit machine-readable JSON on stdout (for scripts)'
+complete -c am -n "__fish_am_using_subcommand config; and not __fish_seen_subcommand_from show path edit validate add set" -l no-color -d 'Disable ANSI colors'
+complete -c am -n "__fish_am_using_subcommand config; and not __fish_seen_subcommand_from show path edit validate add set" -s h -l help -d 'Print help'
+complete -c am -n "__fish_am_using_subcommand config; and not __fish_seen_subcommand_from show path edit validate add set" -f -a "show" -d 'Print the effective (merged) configuration as YAML'
+complete -c am -n "__fish_am_using_subcommand config; and not __fish_seen_subcommand_from show path edit validate add set" -f -a "path" -d 'Print the location of the configuration file(s)'
+complete -c am -n "__fish_am_using_subcommand config; and not __fish_seen_subcommand_from show path edit validate add set" -f -a "edit" -d 'Open the user configuration file in your editor'
+complete -c am -n "__fish_am_using_subcommand config; and not __fish_seen_subcommand_from show path edit validate add set" -f -a "validate" -d 'Validate the configuration file(s)'
+complete -c am -n "__fish_am_using_subcommand config; and not __fish_seen_subcommand_from show path edit validate add set" -f -a "add" -d 'Add another agent definition file to the user configuration'
+complete -c am -n "__fish_am_using_subcommand config; and not __fish_seen_subcommand_from show path edit validate add set" -f -a "set" -d 'Set one configuration key without an editor (config set settings.default_shell pwsh)'
 complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from show" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from show" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
 complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from show" -s v -l verbose -d 'Verbose output: show every command executed and its details'
 complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from show" -s q -l quiet -d 'Quiet mode: only errors are printed'
 complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from show" -s y -l yes -d 'Answer yes to every confirmation prompt'
@@ -176,6 +568,7 @@ complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand
 complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from show" -l no-color -d 'Disable ANSI colors'
 complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from show" -s h -l help -d 'Print help'
 complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from path" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from path" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
 complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from path" -s v -l verbose -d 'Verbose output: show every command executed and its details'
 complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from path" -s q -l quiet -d 'Quiet mode: only errors are printed'
 complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from path" -s y -l yes -d 'Answer yes to every confirmation prompt'
@@ -184,6 +577,7 @@ complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand
 complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from path" -l no-color -d 'Disable ANSI colors'
 complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from path" -s h -l help -d 'Print help'
 complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from edit" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from edit" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
 complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from edit" -s v -l verbose -d 'Verbose output: show every command executed and its details'
 complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from edit" -s q -l quiet -d 'Quiet mode: only errors are printed'
 complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from edit" -s y -l yes -d 'Answer yes to every confirmation prompt'
@@ -192,6 +586,7 @@ complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand
 complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from edit" -l no-color -d 'Disable ANSI colors'
 complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from edit" -s h -l help -d 'Print help'
 complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from validate" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from validate" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
 complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from validate" -s v -l verbose -d 'Verbose output: show every command executed and its details'
 complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from validate" -s q -l quiet -d 'Quiet mode: only errors are printed'
 complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from validate" -s y -l yes -d 'Answer yes to every confirmation prompt'
@@ -200,6 +595,7 @@ complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand
 complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from validate" -l no-color -d 'Disable ANSI colors'
 complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from validate" -s h -l help -d 'Print help'
 complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from add" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from add" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
 complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from add" -s v -l verbose -d 'Verbose output: show every command executed and its details'
 complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from add" -s q -l quiet -d 'Quiet mode: only errors are printed'
 complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from add" -s y -l yes -d 'Answer yes to every confirmation prompt'
@@ -207,13 +603,17 @@ complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand
 complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from add" -l json -d 'Emit machine-readable JSON on stdout (for scripts)'
 complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from add" -l no-color -d 'Disable ANSI colors'
 complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from add" -s h -l help -d 'Print help'
-complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from help" -f -a "show" -d 'Print the effective (merged) configuration as YAML'
-complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from help" -f -a "path" -d 'Print the location of the configuration file(s)'
-complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from help" -f -a "edit" -d 'Open the user configuration file in your editor'
-complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from help" -f -a "validate" -d 'Validate the configuration file(s)'
-complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from help" -f -a "add" -d 'Add another agent definition file to the user configuration'
-complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from help" -f -a "help" -d 'Print this message or the help of the given subcommand(s)'
+complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from set" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from set" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
+complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from set" -s v -l verbose -d 'Verbose output: show every command executed and its details'
+complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from set" -s q -l quiet -d 'Quiet mode: only errors are printed'
+complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from set" -s y -l yes -d 'Answer yes to every confirmation prompt'
+complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from set" -l dry-run -d 'Simulate the action without changing anything'
+complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from set" -l json -d 'Emit machine-readable JSON on stdout (for scripts)'
+complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from set" -l no-color -d 'Disable ANSI colors'
+complete -c am -n "__fish_am_using_subcommand config; and __fish_seen_subcommand_from set" -s h -l help -d 'Print help'
 complete -c am -n "__fish_am_using_subcommand doctor" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand doctor" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
 complete -c am -n "__fish_am_using_subcommand doctor" -l fix -d 'Attempt to repair problems (create directories, fix the state file)'
 complete -c am -n "__fish_am_using_subcommand doctor" -s v -l verbose -d 'Verbose output: show every command executed and its details'
 complete -c am -n "__fish_am_using_subcommand doctor" -s q -l quiet -d 'Quiet mode: only errors are printed'
@@ -223,6 +623,7 @@ complete -c am -n "__fish_am_using_subcommand doctor" -l json -d 'Emit machine-r
 complete -c am -n "__fish_am_using_subcommand doctor" -l no-color -d 'Disable ANSI colors'
 complete -c am -n "__fish_am_using_subcommand doctor" -s h -l help -d 'Print help'
 complete -c am -n "__fish_am_using_subcommand run" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand run" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
 complete -c am -n "__fish_am_using_subcommand run" -s v -l verbose -d 'Verbose output: show every command executed and its details'
 complete -c am -n "__fish_am_using_subcommand run" -s q -l quiet -d 'Quiet mode: only errors are printed'
 complete -c am -n "__fish_am_using_subcommand run" -s y -l yes -d 'Answer yes to every confirmation prompt'
@@ -231,6 +632,8 @@ complete -c am -n "__fish_am_using_subcommand run" -l json -d 'Emit machine-read
 complete -c am -n "__fish_am_using_subcommand run" -l no-color -d 'Disable ANSI colors'
 complete -c am -n "__fish_am_using_subcommand run" -s h -l help -d 'Print help'
 complete -c am -n "__fish_am_using_subcommand completion" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand completion" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
+complete -c am -n "__fish_am_using_subcommand completion" -l installed -d 'Add dynamic completion of the installed agents, aliases and groups (queried from \'am _agents\' at Tab time)'
 complete -c am -n "__fish_am_using_subcommand completion" -s v -l verbose -d 'Verbose output: show every command executed and its details'
 complete -c am -n "__fish_am_using_subcommand completion" -s q -l quiet -d 'Quiet mode: only errors are printed'
 complete -c am -n "__fish_am_using_subcommand completion" -s y -l yes -d 'Answer yes to every confirmation prompt'
@@ -240,6 +643,7 @@ complete -c am -n "__fish_am_using_subcommand completion" -l no-color -d 'Disabl
 complete -c am -n "__fish_am_using_subcommand completion" -s h -l help -d 'Print help'
 complete -c am -n "__fish_am_using_subcommand self-update" -l to -d 'Download the new binary to this path instead of replacing the current one' -r -F
 complete -c am -n "__fish_am_using_subcommand self-update" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand self-update" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
 complete -c am -n "__fish_am_using_subcommand self-update" -l check -d 'Only check whether a newer version exists'
 complete -c am -n "__fish_am_using_subcommand self-update" -s v -l verbose -d 'Verbose output: show every command executed and its details'
 complete -c am -n "__fish_am_using_subcommand self-update" -s q -l quiet -d 'Quiet mode: only errors are printed'
@@ -248,8 +652,18 @@ complete -c am -n "__fish_am_using_subcommand self-update" -l dry-run -d 'Simula
 complete -c am -n "__fish_am_using_subcommand self-update" -l json -d 'Emit machine-readable JSON on stdout (for scripts)'
 complete -c am -n "__fish_am_using_subcommand self-update" -l no-color -d 'Disable ANSI colors'
 complete -c am -n "__fish_am_using_subcommand self-update" -s h -l help -d 'Print help'
+complete -c am -n "__fish_am_using_subcommand self-uninstall" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand self-uninstall" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
+complete -c am -n "__fish_am_using_subcommand self-uninstall" -s v -l verbose -d 'Verbose output: show every command executed and its details'
+complete -c am -n "__fish_am_using_subcommand self-uninstall" -s q -l quiet -d 'Quiet mode: only errors are printed'
+complete -c am -n "__fish_am_using_subcommand self-uninstall" -s y -l yes -d 'Answer yes to every confirmation prompt'
+complete -c am -n "__fish_am_using_subcommand self-uninstall" -l dry-run -d 'Simulate the action without changing anything'
+complete -c am -n "__fish_am_using_subcommand self-uninstall" -l json -d 'Emit machine-readable JSON on stdout (for scripts)'
+complete -c am -n "__fish_am_using_subcommand self-uninstall" -l no-color -d 'Disable ANSI colors'
+complete -c am -n "__fish_am_using_subcommand self-uninstall" -s h -l help -d 'Print help (see more with \'--help\')'
 complete -c am -n "__fish_am_using_subcommand export" -l output -d 'Output file (default: am-export.json)' -r -F
 complete -c am -n "__fish_am_using_subcommand export" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand export" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
 complete -c am -n "__fish_am_using_subcommand export" -s v -l verbose -d 'Verbose output: show every command executed and its details'
 complete -c am -n "__fish_am_using_subcommand export" -s q -l quiet -d 'Quiet mode: only errors are printed'
 complete -c am -n "__fish_am_using_subcommand export" -s y -l yes -d 'Answer yes to every confirmation prompt'
@@ -258,6 +672,7 @@ complete -c am -n "__fish_am_using_subcommand export" -l json -d 'Emit machine-r
 complete -c am -n "__fish_am_using_subcommand export" -l no-color -d 'Disable ANSI colors'
 complete -c am -n "__fish_am_using_subcommand export" -s h -l help -d 'Print help'
 complete -c am -n "__fish_am_using_subcommand import" -s c -l config -d 'Use an alternate configuration file' -r -F
+complete -c am -n "__fish_am_using_subcommand import" -l theme -d 'Color theme for the output (see \'am help theme\' for the list)' -r
 complete -c am -n "__fish_am_using_subcommand import" -s v -l verbose -d 'Verbose output: show every command executed and its details'
 complete -c am -n "__fish_am_using_subcommand import" -s q -l quiet -d 'Quiet mode: only errors are printed'
 complete -c am -n "__fish_am_using_subcommand import" -s y -l yes -d 'Answer yes to every confirmation prompt'
@@ -265,26 +680,3 @@ complete -c am -n "__fish_am_using_subcommand import" -l dry-run -d 'Simulate th
 complete -c am -n "__fish_am_using_subcommand import" -l json -d 'Emit machine-readable JSON on stdout (for scripts)'
 complete -c am -n "__fish_am_using_subcommand import" -l no-color -d 'Disable ANSI colors'
 complete -c am -n "__fish_am_using_subcommand import" -s h -l help -d 'Print help'
-complete -c am -n "__fish_am_using_subcommand help; and not __fish_seen_subcommand_from list start stop restart status install uninstall update search info config doctor run completion self-update export import help" -f -a "list" -d 'List agents: installed ones, or every agent known to the catalog'
-complete -c am -n "__fish_am_using_subcommand help; and not __fish_seen_subcommand_from list start stop restart status install uninstall update search info config doctor run completion self-update export import help" -f -a "start" -d 'Start an agent (foreground by default, or detached with --background)'
-complete -c am -n "__fish_am_using_subcommand help; and not __fish_seen_subcommand_from list start stop restart status install uninstall update search info config doctor run completion self-update export import help" -f -a "stop" -d 'Stop a background agent (SIGTERM, then SIGKILL after the timeout)'
-complete -c am -n "__fish_am_using_subcommand help; and not __fish_seen_subcommand_from list start stop restart status install uninstall update search info config doctor run completion self-update export import help" -f -a "restart" -d 'Restart an agent: stop, then start with the same options'
-complete -c am -n "__fish_am_using_subcommand help; and not __fish_seen_subcommand_from list start stop restart status install uninstall update search info config doctor run completion self-update export import help" -f -a "status" -d 'Show the state of one agent, or of every installed agent'
-complete -c am -n "__fish_am_using_subcommand help; and not __fish_seen_subcommand_from list start stop restart status install uninstall update search info config doctor run completion self-update export import help" -f -a "install" -d 'Install an agent and its dependencies'
-complete -c am -n "__fish_am_using_subcommand help; and not __fish_seen_subcommand_from list start stop restart status install uninstall update search info config doctor run completion self-update export import help" -f -a "uninstall" -d 'Uninstall an agent and clean its files'
-complete -c am -n "__fish_am_using_subcommand help; and not __fish_seen_subcommand_from list start stop restart status install uninstall update search info config doctor run completion self-update export import help" -f -a "update" -d 'Update an installed agent to the latest available version'
-complete -c am -n "__fish_am_using_subcommand help; and not __fish_seen_subcommand_from list start stop restart status install uninstall update search info config doctor run completion self-update export import help" -f -a "search" -d 'Search the catalog by keyword (name, description, category, tags)'
-complete -c am -n "__fish_am_using_subcommand help; and not __fish_seen_subcommand_from list start stop restart status install uninstall update search info config doctor run completion self-update export import help" -f -a "info" -d 'Show detailed information about one agent'
-complete -c am -n "__fish_am_using_subcommand help; and not __fish_seen_subcommand_from list start stop restart status install uninstall update search info config doctor run completion self-update export import help" -f -a "config" -d 'Manage the configuration file'
-complete -c am -n "__fish_am_using_subcommand help; and not __fish_seen_subcommand_from list start stop restart status install uninstall update search info config doctor run completion self-update export import help" -f -a "doctor" -d 'Check the environment: tools, config validity, paths, permissions'
-complete -c am -n "__fish_am_using_subcommand help; and not __fish_seen_subcommand_from list start stop restart status install uninstall update search info config doctor run completion self-update export import help" -f -a "run" -d 'Run the agent command directly with the given arguments (no process management)'
-complete -c am -n "__fish_am_using_subcommand help; and not __fish_seen_subcommand_from list start stop restart status install uninstall update search info config doctor run completion self-update export import help" -f -a "completion" -d 'Generate a shell completion script'
-complete -c am -n "__fish_am_using_subcommand help; and not __fish_seen_subcommand_from list start stop restart status install uninstall update search info config doctor run completion self-update export import help" -f -a "self-update" -d 'Update agent-manager itself from GitHub Releases'
-complete -c am -n "__fish_am_using_subcommand help; and not __fish_seen_subcommand_from list start stop restart status install uninstall update search info config doctor run completion self-update export import help" -f -a "export" -d 'Export the configuration and installation state (backup)'
-complete -c am -n "__fish_am_using_subcommand help; and not __fish_seen_subcommand_from list start stop restart status install uninstall update search info config doctor run completion self-update export import help" -f -a "import" -d 'Import a previously exported configuration and state'
-complete -c am -n "__fish_am_using_subcommand help; and not __fish_seen_subcommand_from list start stop restart status install uninstall update search info config doctor run completion self-update export import help" -f -a "help" -d 'Print this message or the help of the given subcommand(s)'
-complete -c am -n "__fish_am_using_subcommand help; and __fish_seen_subcommand_from config" -f -a "show" -d 'Print the effective (merged) configuration as YAML'
-complete -c am -n "__fish_am_using_subcommand help; and __fish_seen_subcommand_from config" -f -a "path" -d 'Print the location of the configuration file(s)'
-complete -c am -n "__fish_am_using_subcommand help; and __fish_seen_subcommand_from config" -f -a "edit" -d 'Open the user configuration file in your editor'
-complete -c am -n "__fish_am_using_subcommand help; and __fish_seen_subcommand_from config" -f -a "validate" -d 'Validate the configuration file(s)'
-complete -c am -n "__fish_am_using_subcommand help; and __fish_seen_subcommand_from config" -f -a "add" -d 'Add another agent definition file to the user configuration'

config.yaml

@@ -18,7 +18,85 @@ settings:
   auto_install_deps: true      # offer to install missing dependencies
   confirm_before_run: true     # confirm before running install scripts
   stop_timeout_secs: 5         # SIGTERM grace period before SIGKILL
-  self_update_repo: null       # e.g. "you/agent-manager" for am self-update
+  self_update_repo: Projets/agent-manager   # repo used by am self-update (release assets)
+  self_update_base_url: https://git.dracodev.net/api/v1   # serveur de release (Gitea ici; GitHub: https://api.github.com)
+  models_prune_days: 30       # un modèle est candidat au prune après N jours sans usage (#73)
+  catalog_cache_ttl_secs: 3600  # TTL du cache des catalogues distants (#60 #67)
+  catalog_url: null           # URL officielle du catalogue distant (défaut: config.yaml du repo) (#60)
+  backups_keep: 5             # nombre de backups conservés pour am update --rollback (#64)
+  sessions_retention_days: 90 # purge des sessions terminées au-delà de N jours (#53)
+  # Prix des modèles (USD par million de tokens) pour am stats --costs (#49).
+  # cost_models:              # décommenter pour surcharger
+  #   claude-sonnet-4: { input_per_mtok: 3.0, output_per_mtok: 15.0 }
+  #   deepseek-chat:  { input_per_mtok: 0.27, output_per_mtok: 1.10 }
+  # Seuils d'alerte de am monitor (#50) : 0 désactive le seuil.
+  # monitor_thresholds:
+  #   cpu_pct: 80.0
+  #   mem_mb: 2048
+  # Plugins d'événements (#75) : scripts exécutés sur on_install/on_start/
+  # on_stop/on_update, contrat JSON stdin/stdout, timeout, échec non bloquant.
+  # Le répertoire <state>/plugins/ contient les scripts (+ manifeste .yaml).
+  # plugins:
+  #   timeout_secs: 10          # temps max d'un plugin (défaut 10 s)
+  #   enabled: [notify]         # vide = tous les plugins du répertoire
+  # Sauvegarde git de l'état (#66) : dépôt où am sync pousse state.json,
+  # le journal et l'historique (logs/ et backups/ exclus automatiquement).
+  # sync_repo: https://git.dracodev.net/bruno/am-state.git
+  # sync_on_exit: true          # pousse automatiquement à la fermeture du REPL (opt-in)
+  # Télémétrie anonyme opt-in (#76) : compteurs agrégés uniquement (jamais de
+  # chemins, commandes ni identifiants). Désactivée par défaut — RIEN n'est
+  # collecté ni envoyé tant que enabled n'est pas explicitement true.
+  # telemetry:
+  #   enabled: false
+  #   endpoint: https://exemple.tld/v1/ping   # optionnel : envoi batch périodique
+  # am ask (#78) : langage naturel → commande am. Les règles locales marchent
+  # toujours, hors-ligne, sans dépendance. Le raffinement LLM optionnel passe
+  # par le registre providers (base_url + token du keyring + modèle) — seul
+  # le texte de la requête est envoyé, jamais les données du journal.
+  # ask:
+  #   enabled: true            # false désactive entièrement am ask
+  #   provider: deepseek       # optionnel (défaut: settings.default_provider)
+  #   model: deepseek-chat     # optionnel (défaut: modèle par défaut du provider)
+  # Registre communautaire (#77) : sources de catalogues de confiance +
+  # auteur par défaut pour am registry publish. L'installation d'une source
+  # inconnue exige une confirmation (checksum sha256 vérifié avant tout).
+  # registry:
+  #   sources:
+  #     - https://git.dracodev.net/bruno/am-catalog/raw/branch/main/am-catalog.yaml
+  #   author: bruno
+  # Profil sandbox par agent (#79) : commandes autorisées (binaires), répertoires
+  # de travail et politique réseau. Désactivé par défaut (mode non sandboxé).
+  # Les tentatives refusées sont journalisées (events sandbox) pour l'audit.
+  # Exemple dans un agent :
+  #   sandbox:
+  #     enabled: true
+  #     commands: [python, git]
+  #     dirs: ["~/workspace"]
+  #     network: false
+  # Registre des providers LLM (#88) : nom -> base_url, modèles, modèle par
+  # défaut. Le provider par défaut est utilisé à l'install/au run quand aucun
+  # n'est donné (issue #90). Les tokens ne vont JAMAIS ici — ils vivent dans
+  # le keyring OS sous providers/<nom>/api_key (issue #89, am providers set-token).
+  # Pour retirer un provider du catalogue par défaut : am providers remove <nom>
+  # (écrit "<nom>: null" dans votre config — le null supprime l'entrée au merge).
+  default_provider: anthropic
+  providers:
+    anthropic:
+      base_url: https://api.anthropic.com/v1
+      default_model: claude-sonnet-4-5
+      models: [claude-sonnet-4-5, claude-opus-4-1, claude-haiku-4-5]
+    openai:
+      base_url: https://api.openai.com/v1
+      default_model: gpt-5.2
+      models: [gpt-5.2, gpt-5.1-mini, o4-mini]
+    deepseek:
+      base_url: https://api.deepseek.com
+      default_model: deepseek-chat
+      models: [deepseek-chat, deepseek-reasoner]
+    google:
+      base_url: https://generativelanguage.googleapis.com/v1beta
+      default_model: gemini-2.5-pro
+      models: [gemini-2.5-pro, gemini-2.5-flash]
 
 # --- Command aliases ----------------------------------------------------------
 aliases:
@@ -54,8 +132,28 @@ agents:
     dependencies:
       - { name: node, min_version: "18.0.0", install_hint: "https://nodejs.org" }
     run: claude
+    provider: anthropic
+    config:
+      env_map:
+        api_key: ANTHROPIC_API_KEY
+        model: ANTHROPIC_MODEL
+        base_url: ANTHROPIC_BASE_URL
     tags: [anthropic, assistant, source-available, mainstream]
 
+  - name: deepseek-harness
+    display_name: "DeepSeek Harness"
+    description: "CLI officiel DeepSeek (dsh) : boot de profils, gestion des plugins Cordis, orchestration multi-agents, boucles de buts (goals) et interface web. Installez-le pour piloter vos agents depuis am."
+    category: coding-agent
+    website: https://github.com/deepseek-ai/deepseek-harness
+    install:
+      type: npm
+      package: "@deepseek-ai/dsh"
+    dependencies:
+      - { name: node, min_version: "20.0.0", install_hint: "https://nodejs.org" }
+    run: dsh
+    provider: deepseek
+    tags: [deepseek, harness, multi-agent, plugins, web-ui]
+
   - name: hermes-agent
     display_name: "Hermes Agent"
     description: "Agent Nous Research multi-modèle (300+ providers). Mémoire persistante, création automatique de skills, exécution de code sandboxée, reach multi-plateforme (Telegram/Slack/Discord/WhatsApp)."
@@ -194,6 +292,11 @@ agents:
     dependencies:
       - { name: node, min_version: "18.0.0", install_hint: "https://nodejs.org" }
     run: codex
+    config:
+      env_map:
+        api_key: OPENAI_API_KEY
+        model: OPENAI_MODEL
+        base_url: OPENAI_BASE_URL
     tags: [openai, mainstream]
 
   - name: openhands
@@ -328,14 +431,14 @@ agents:
 
   - name: kimi-cli
     display_name: "Kimi CLI"
-    description: "Agent CLI officiel Moonshot AI, skills, MCP, intégration ACP IDE (Apache-2.0)."
+    description: "Agent CLI officiel Moonshot AI, skills, MCP, intégration ACP IDE (Apache-2.0). Installé via uv (paquet PyPI kimi-cli)."
     category: coding-agent
     website: https://github.com/MoonshotAI/kimi-cli
     install:
-      type: npm
-      package: "@moonshotai/kimi-cli"
+      type: uv
+      package: kimi-cli
     dependencies:
-      - { name: node, min_version: "18.0.0", install_hint: "https://nodejs.org" }
+      - { name: uv, min_version: "0.4.0", install_hint: "https://docs.astral.sh/uv" }
     run: kimi
     tags: [moonshot, skills, mcp]
 
@@ -444,6 +547,15 @@ agents:
       repo: 1ay1/agentty
       binary: agentty
     run: agentty
+    config:
+      provider_default: openai
+      env_map:
+        api_key: AGENTTY_API_KEY
+        model: AGENTTY_MODEL
+        base_url: AGENTTY_BASE_URL
+      files:
+        - path: ~/.config/agentty/config.toml
+          keys: [model, base_url]
     tags: [c++, static, sandbox]
 
   - name: nullclaw
@@ -816,10 +928,9 @@ agents:
     category: assistant
     website: https://github.com/sipeed/picoclaw
     install:
-      type: git
-      repo: "https://github.com/sipeed/picoclaw"
-    dependencies:
-      - { name: go, min_version: "1.21.0", install_hint: "https://go.dev/dl" }
+      type: binary
+      repo: sipeed/picoclaw
+      binary: picoclaw
     run: picoclaw
     tags: [go, tiny]
 

examples/lab/hello.yaml

@@ -0,0 +1,8 @@
+# Tâche de benchmark (issue #62) : les mêmes arguments sont passés à la
+# commande de chaque agent. Copier dans <state_dir>/lab/ ou passer un
+# chemin explicite :
+#   am lab --agents claude-code,aider --task hello.yaml --json
+name: hello
+description: "Répondre à la question la plus simple (sanity check du lab)."
+args: ["--prompt", "Réponds uniquement 'coucou' et rien d'autre."]
+# timeout: 300   # secondes par agent (défaut 600) — --timeout l'emporte

examples/plugins/README.md

@@ -0,0 +1,31 @@
+# Plugin scripts — agent-manager (issue #75)
+#
+# Les plugins sont des points d'extension par script, exécutés sur les
+# événements du cycle de vie des agents (complément des hooks de l'axe 6) :
+#   on_install · on_start · on_stop · on_update
+#
+# Contrat :
+#   - entrée : l'événement JSON sur stdin
+#     {"event":"on_start","kind":"start","ts":"…","agent":"claude-code",
+#      "pid":1234,"cwd":"…","project":"…","args":[…],"env_keys":[…],…}
+#   - sortie : un objet JSON sur stdout
+#     {"ok": true, "message": "…", "data": {…}}
+#     ou {"ok": false, "error": "…"} — signalé en warning, jamais fatal
+#   - une sortie invalide (pas de JSON) est signalée en warning sans casser am
+#   - un plugin qui dépasse son timeout est tué (défaut 10 s)
+#   - les plugins n'ont pas accès aux valeurs des secrets (env_keys seulement)
+#   - AM_PLUGINS_RUNNING=1 est exporté pendant un plugin : un am imbriqué
+#     saute les plugins (anti-récursion)
+#
+# Installation :
+#   cp notify.py notify.yaml ~/.local/state/agent-manager/plugins/   (Linux)
+#   cp notify.py notify.yaml %LOCALAPPDATA%\agent-manager\plugins\   (Windows)
+#
+# Vérification :
+#   am plugins                 # liste les plugins découverts
+#   am plugins --test notify   # exécute le contrat sur un événement de test
+#
+# Configuration (config.yaml) :
+#   plugins:
+#     timeout_secs: 10          # temps max d'un plugin (défaut 10 s)
+#     enabled: [notify]         # vide = tous les plugins du répertoire

examples/plugins/ci-webhook.py

@@ -0,0 +1,38 @@
+#!/usr/bin/env python3
+"""Plugin exemple (issue #75) : poste les événements install/update vers un
+webhook CI. Si la variable d'environnement CI_WEBHOOK_URL n'est pas définie,
+le plugin répond ok sans rien faire (échec non bloquant, jamais fatal).
+
+Exemple : CI_WEBHOOK_URL=https://hooks.example.com/am-ci am update --all
+"""
+
+import json
+import os
+import sys
+import urllib.request
+
+
+def main() -> int:
+    ev = json.load(sys.stdin)
+    url = os.environ.get("CI_WEBHOOK_URL")
+    if not url:
+        print(json.dumps({"ok": True, "message": "CI_WEBHOOK_URL non définie — rien à faire"}))
+        return 0
+    req = urllib.request.Request(
+        url,
+        data=json.dumps(ev).encode(),
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=5) as resp:
+            status = resp.status
+    except Exception as exc:  # échec non bloquant : warning seulement
+        print(json.dumps({"ok": False, "error": f"webhook: {exc}"}))
+        return 0
+    print(json.dumps({"ok": True, "message": f"webhook {status}"}))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

examples/plugins/ci-webhook.yaml

@@ -0,0 +1,4 @@
+# Manifest du plugin ci-webhook (issue #75).
+command: "python ci-webhook.py"   # Linux : "python3 ci-webhook.py"
+events: [on_install, on_update]
+timeout_secs: 10

examples/plugins/notify.py

@@ -0,0 +1,24 @@
+#!/usr/bin/env python3
+"""Plugin exemple (issue #75) : notifie le démarrage / l'arrêt d'un agent.
+
+Contrat : l'événement JSON arrive sur stdin, la réponse JSON part sur stdout.
+Installation : copier notify.py + notify.yaml dans <state_dir>/plugins/ puis
+relancer am. Test : am plugins --test notify
+"""
+
+import json
+import sys
+
+
+def main() -> int:
+    ev = json.load(sys.stdin)
+    agent = ev.get("agent") or "inconnu"
+    event = ev.get("event", "?")
+    pid = ev.get("pid")
+    detail = f" (pid {pid})" if pid else ""
+    print(json.dumps({"ok": True, "message": f"{event} de {agent}{detail}"}))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

examples/plugins/notify.yaml

@@ -0,0 +1,7 @@
+# Manifest du plugin notify (issue #75).
+# command: interpréteur + script (indispensable sur Windows pour .py).
+command: "python notify.py"   # Linux : "python3 notify.py"
+# Événements écoutés (défaut : les 4 événements du cycle de vie).
+events: [on_start, on_stop]
+# Temps maximal d'exécution avant kill (défaut : settings.plugins.timeout_secs, 10).
+timeout_secs: 5

man/am-alias.1

@@ -0,0 +1,26 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-alias 1  "alias " 
+.SH NAME
+alias \- Manage command aliases (cc \-> claude\-code)
+.SH SYNOPSIS
+\fBalias\fR [\fB\-h\fR|\fB\-\-help\fR] <\fIsubcommands\fR>
+.SH DESCRIPTION
+Manage command aliases (cc \-> claude\-code)
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.SH SUBCOMMANDS
+.TP
+alias\-add(1)
+Add an alias (am alias add cc claude\-code)
+.TP
+alias\-remove(1)
+Remove an alias
+.TP
+alias\-list(1)
+List every alias
+.TP
+alias\-help(1)
+Print this message or the help of the given subcommand(s)

man/am-ask.1

@@ -0,0 +1,19 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-ask 1  "ask " 
+.SH NAME
+ask \- Ask a natural\-language request and get the matching am command(s) (issue #78): local rules first, optional LLM refinement, confirmation before execution
+.SH SYNOPSIS
+\fBask\fR [\fB\-\-yes\fR] [\fB\-h\fR|\fB\-\-help\fR] <\fIREQUEST\fR> 
+.SH DESCRIPTION
+Ask a natural\-language request and get the matching am command(s) (issue #78): local rules first, optional LLM refinement, confirmation before execution
+.SH OPTIONS
+.TP
+\fB\-\-yes\fR
+Skip the confirmation prompt
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+<\fIREQUEST\fR>
+The request in natural language

man/am-audit.1

@@ -0,0 +1,13 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-audit 1  "audit " 
+.SH NAME
+audit \- Audit the configuration: who changed what, when (issue #63)
+.SH SYNOPSIS
+\fBaudit\fR [\fB\-h\fR|\fB\-\-help\fR] 
+.SH DESCRIPTION
+Audit the configuration: who changed what, when (issue #63)
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help

man/am-catalog.1

@@ -0,0 +1,26 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-catalog 1  "catalog " 
+.SH NAME
+catalog \- Manage remote catalogs: update the official one, add external ones
+.SH SYNOPSIS
+\fBcatalog\fR [\fB\-h\fR|\fB\-\-help\fR] <\fIsubcommands\fR>
+.SH DESCRIPTION
+Manage remote catalogs: update the official one, add external ones
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.SH SUBCOMMANDS
+.TP
+catalog\-update(1)
+Fetch the official catalog, show the diff and register it as an include
+.TP
+catalog\-add(1)
+Register an external catalog (same YAML format) by URL
+.TP
+catalog\-list(1)
+List the registered remote catalogs
+.TP
+catalog\-help(1)
+Print this message or the help of the given subcommand(s)

man/am-completion.1

@@ -0,0 +1,35 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-completion 1  "completion " 
+.SH NAME
+completion \- Generate a shell completion script
+.SH SYNOPSIS
+\fBcompletion\fR [\fB\-\-installed\fR] [\fB\-h\fR|\fB\-\-help\fR] <\fISHELL\fR> 
+.SH DESCRIPTION
+Generate a shell completion script
+.SH OPTIONS
+.TP
+\fB\-\-installed\fR
+Add dynamic completion of the installed agents, aliases and groups (queried from \*(Aqam _agents\*(Aq at Tab time)
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+<\fISHELL\fR>
+Shell to generate completions for
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+bash
+.IP \(bu 2
+elvish
+.IP \(bu 2
+fish
+.IP \(bu 2
+powershell
+.IP \(bu 2
+zsh
+.RE

man/am-config.1

@@ -0,0 +1,35 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-config 1  "config " 
+.SH NAME
+config \- Manage the configuration file
+.SH SYNOPSIS
+\fBconfig\fR [\fB\-h\fR|\fB\-\-help\fR] <\fIsubcommands\fR>
+.SH DESCRIPTION
+Manage the configuration file
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.SH SUBCOMMANDS
+.TP
+config\-show(1)
+Print the effective (merged) configuration as YAML
+.TP
+config\-path(1)
+Print the location of the configuration file(s)
+.TP
+config\-edit(1)
+Open the user configuration file in your editor
+.TP
+config\-validate(1)
+Validate the configuration file(s)
+.TP
+config\-add(1)
+Add another agent definition file to the user configuration
+.TP
+config\-set(1)
+Set one configuration key without an editor (config set settings.default_shell pwsh)
+.TP
+config\-help(1)
+Print this message or the help of the given subcommand(s)

man/am-dashboard.1

@@ -0,0 +1,13 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-dashboard 1  "dashboard " 
+.SH NAME
+dashboard \- Live TUI dashboard: overview, activity, stats, sessions, projects
+.SH SYNOPSIS
+\fBdashboard\fR [\fB\-h\fR|\fB\-\-help\fR] 
+.SH DESCRIPTION
+Live TUI dashboard: overview, activity, stats, sessions, projects
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help

man/am-doctor.1

@@ -0,0 +1,19 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-doctor 1  "doctor " 
+.SH NAME
+doctor \- Check the environment: tools, config validity, paths, permissions
+.SH SYNOPSIS
+\fBdoctor\fR [\fB\-\-fix\fR] [\fB\-\-watch\fR] [\fB\-h\fR|\fB\-\-help\fR] 
+.SH DESCRIPTION
+Check the environment: tools, config validity, paths, permissions
+.SH OPTIONS
+.TP
+\fB\-\-fix\fR
+Attempt to repair problems (create directories, fix the state file)
+.TP
+\fB\-\-watch\fR \fI<SECONDS>\fR
+Re\-run the checks every N seconds, alerting on failure (issue #59)
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help

man/am-export.1

@@ -0,0 +1,16 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-export 1  "export " 
+.SH NAME
+export \- Export the configuration and installation state (backup)
+.SH SYNOPSIS
+\fBexport\fR [\fB\-\-output\fR] [\fB\-h\fR|\fB\-\-help\fR] 
+.SH DESCRIPTION
+Export the configuration and installation state (backup)
+.SH OPTIONS
+.TP
+\fB\-\-output\fR \fI<FILE>\fR [default: am\-export.json]
+Output file (default: am\-export.json)
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help

man/am-favorite.1

@@ -0,0 +1,16 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-favorite 1  "favorite " 
+.SH NAME
+favorite \- Mark an agent as a favorite (star in list and status)
+.SH SYNOPSIS
+\fBfavorite\fR [\fB\-h\fR|\fB\-\-help\fR] <\fIAGENT\fR> 
+.SH DESCRIPTION
+Mark an agent as a favorite (star in list and status)
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+<\fIAGENT\fR>
+Agent name or alias

man/am-help.1

@@ -0,0 +1,19 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-help 1  "help " 
+.SH NAME
+help \- Display help: the overview, a command, the command list, or a search
+.SH SYNOPSIS
+\fBhelp\fR [\fB\-\-find\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fICOMMAND\fR] 
+.SH DESCRIPTION
+Display help: the overview, a command, the command list, or a search
+.SH OPTIONS
+.TP
+\fB\-\-find\fR \fI<TEXT>\fR
+Search through all help commands table
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+[\fICOMMAND\fR]
+Command name (also accepts an agent name or alias); "commands" lists every command

man/am-history.1

@@ -0,0 +1,40 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-history 1  "history " 
+.SH NAME
+history \- Search the command history (am and shell commands)
+.SH SYNOPSIS
+\fBhistory\fR [\fB\-\-kind\fR] [\fB\-\-cwd\fR] [\fB\-\-search\fR] [\fB\-\-failed\fR] [\fB\-\-session\fR] [\fB\-\-limit\fR] [\fB\-\-rerun\fR] [\fB\-\-save\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fIRANGE\fR] 
+.SH DESCRIPTION
+Search the command history (am and shell commands)
+.SH OPTIONS
+.TP
+\fB\-\-kind\fR \fI<KIND>\fR
+Only commands of this kind (am or shell)
+.TP
+\fB\-\-cwd\fR \fI<DIR>\fR
+Only commands run in this directory
+.TP
+\fB\-\-search\fR \fI<TEXT>\fR
+Full\-text search in the command line
+.TP
+\fB\-\-failed\fR
+Only failed commands
+.TP
+\fB\-\-session\fR \fI<ID>\fR
+Only commands of this session
+.TP
+\fB\-\-limit\fR \fI<N>\fR [default: 100]
+Maximum number of entries (default: 100)
+.TP
+\fB\-\-rerun\fR \fI<N>\fR
+Re\-run the Nth most recent entry (with confirmation)
+.TP
+\fB\-\-save\fR \fI<FILE>\fR
+Export the range as a playbook YAML file (issue #51)
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+[\fIRANGE\fR]
+Range to export as a playbook: "12..25" (1\-based, newest first)

man/am-import.1

@@ -0,0 +1,16 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-import 1  "import " 
+.SH NAME
+import \- Import a previously exported configuration and state
+.SH SYNOPSIS
+\fBimport\fR [\fB\-h\fR|\fB\-\-help\fR] <\fIFILE\fR> 
+.SH DESCRIPTION
+Import a previously exported configuration and state
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+<\fIFILE\fR>
+File exported by the export command

man/am-info.1

@@ -0,0 +1,16 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-info 1  "info " 
+.SH NAME
+info \- Show detailed information about one agent
+.SH SYNOPSIS
+\fBinfo\fR [\fB\-h\fR|\fB\-\-help\fR] <\fIAGENT\fR> 
+.SH DESCRIPTION
+Show detailed information about one agent
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+<\fIAGENT\fR>
+Agent name or alias

man/am-init.1

@@ -0,0 +1,19 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-init 1  "init " 
+.SH NAME
+init \- Generate a local agent\-manager.yaml for the current directory
+.SH SYNOPSIS
+\fBinit\fR [\fB\-\-force\fR] [\fB\-\-template\fR] [\fB\-h\fR|\fB\-\-help\fR] 
+.SH DESCRIPTION
+Generate a local agent\-manager.yaml for the current directory
+.SH OPTIONS
+.TP
+\fB\-\-force\fR
+Overwrite an existing agent\-manager.yaml
+.TP
+\fB\-\-template\fR \fI<TEMPLATE>\fR
+Use a template (web, python, rust, cli) instead of stack detection; "list" shows the available templates
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help

man/am-install.1

@@ -0,0 +1,31 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-install 1  "install " 
+.SH NAME
+install \- Install an agent and its dependencies
+.SH SYNOPSIS
+\fBinstall\fR [\fB\-\-method\fR] [\fB\-\-force\fR] [\fB\-\-provider\fR] [\fB\-\-model\fR] [\fB\-\-no\-config\fR] [\fB\-h\fR|\fB\-\-help\fR] <\fIAGENT\fR> 
+.SH DESCRIPTION
+Install an agent and its dependencies
+.SH OPTIONS
+.TP
+\fB\-\-method\fR \fI<METHOD>\fR
+Select the install method (index, or type: npm, pip, uv, cargo, go, bun, curl, binary, git)
+.TP
+\fB\-\-force\fR
+Reinstall even if already installed
+.TP
+\fB\-\-provider\fR \fI<PROVIDER>\fR
+Provider to configure (default: the agent\*(Aqs provider, else settings.default_provider) (issue #90)
+.TP
+\fB\-\-model\fR \fI<MODEL>\fR
+Model to configure (default: the provider\*(Aqs default model) (issue #90)
+.TP
+\fB\-\-no\-config\fR
+Skip the post\-install provider configuration (issue #91)
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+<\fIAGENT\fR>
+Agent name or alias

man/am-lab.1

@@ -0,0 +1,28 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-lab 1  "lab " 
+.SH NAME
+lab \- Benchmark: run the same task on several agents and compare (issue #62)
+.SH SYNOPSIS
+\fBlab\fR [\fB\-\-agents\fR] [\fB\-\-task\fR] [\fB\-\-parallel\fR] [\fB\-\-timeout\fR] [\fB\-\-list\fR] [\fB\-h\fR|\fB\-\-help\fR] 
+.SH DESCRIPTION
+Benchmark: run the same task on several agents and compare (issue #62)
+.SH OPTIONS
+.TP
+\fB\-\-agents\fR \fI<AGENTS>\fR
+Comma\-separated agent names (or aliases) to benchmark
+.TP
+\fB\-\-task\fR \fI<FILE>\fR
+Task file (a bare name resolves under state_dir/lab/, .yaml appended)
+.TP
+\fB\-\-parallel\fR
+Run every agent concurrently instead of one after another
+.TP
+\fB\-\-timeout\fR \fI<SECS>\fR
+Override the task timeout in seconds
+.TP
+\fB\-\-list\fR
+List the task files of the lab directory
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help

man/am-list.1

@@ -0,0 +1,25 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-list 1  "list " 
+.SH NAME
+list \- List installed agents (default); use \-\-all for the whole catalog
+.SH SYNOPSIS
+\fBlist\fR [\fB\-\-all\fR] [\fB\-\-category\fR] [\fB\-\-running\fR] [\fB\-\-sort\fR] [\fB\-h\fR|\fB\-\-help\fR] 
+.SH DESCRIPTION
+List installed agents (default); use \-\-all for the whole catalog
+.SH OPTIONS
+.TP
+\fB\-\-all\fR
+Show every agent known to the catalog, not only the installed ones
+.TP
+\fB\-\-category\fR \fI<CATEGORY>\fR
+Only show agents of this category
+.TP
+\fB\-\-running\fR
+Only show running agents
+.TP
+\fB\-\-sort\fR \fI<KEY>\fR
+Sort by name, version or status (default: name)
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help

man/am-log.1

@@ -0,0 +1,28 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-log 1  "log " 
+.SH NAME
+log \- Read the event journal: everything am did
+.SH SYNOPSIS
+\fBlog\fR [\fB\-\-kind\fR] [\fB\-\-since\fR] [\fB\-\-limit\fR] [\fB\-\-follow\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fIAGENT\fR] 
+.SH DESCRIPTION
+Read the event journal: everything am did
+.SH OPTIONS
+.TP
+\fB\-\-kind\fR \fI<KINDS>\fR
+Only these event kinds (comma separated: start,stop,run,install,...)
+.TP
+\fB\-\-since\fR \fI<DATE>\fR
+Only events at or after this date (YYYY\-MM\-DD or RFC 3339)
+.TP
+\fB\-\-limit\fR \fI<N>\fR [default: 50]
+Maximum number of events (default: 50)
+.TP
+\fB\-\-follow\fR
+Follow the journal as new events arrive
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+[\fIAGENT\fR]
+Only events of this agent

man/am-logs.1

@@ -0,0 +1,22 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-logs 1  "logs " 
+.SH NAME
+logs \- Tail the log file of an agent (\-\-follow for a live view)
+.SH SYNOPSIS
+\fBlogs\fR [\fB\-\-lines\fR] [\fB\-\-follow\fR] [\fB\-h\fR|\fB\-\-help\fR] <\fIAGENT\fR> 
+.SH DESCRIPTION
+Tail the log file of an agent (\-\-follow for a live view)
+.SH OPTIONS
+.TP
+\fB\-\-lines\fR \fI<N>\fR [default: 20]
+Number of lines to show (default: 20)
+.TP
+\fB\-\-follow\fR
+Follow the log as it grows
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+<\fIAGENT\fR>
+Agent name or alias

man/am-man.1

@@ -0,0 +1,19 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-man 1  "man " 
+.SH NAME
+man \- Generate a man page for am (or for one command)
+.SH SYNOPSIS
+\fBman\fR [\fB\-\-output\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fICOMMAND\fR] 
+.SH DESCRIPTION
+Generate a man page for am (or for one command)
+.SH OPTIONS
+.TP
+\fB\-\-output\fR \fI<DIR>\fR
+Write the page(s) to this directory instead of stdout
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+[\fICOMMAND\fR]
+Command name (omit for the whole CLI)

man/am-migrate.1

@@ -0,0 +1,22 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-migrate 1  "migrate " 
+.SH NAME
+migrate \- Transfer the installation and state to another machine (issue #68)
+.SH SYNOPSIS
+\fBmigrate\fR [\fB\-\-export\fR] [\fB\-\-output\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fIBUNDLE\fR] 
+.SH DESCRIPTION
+Transfer the installation and state to another machine (issue #68)
+.SH OPTIONS
+.TP
+\fB\-\-export\fR
+Export the bundle (default) or import one
+.TP
+\fB\-\-output\fR \fI<FILE>\fR
+Bundle path for export (default agent\-manager\-migrate.amx)
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+[\fIBUNDLE\fR]
+Bundle path to import

man/am-models.1

@@ -0,0 +1,25 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-models 1  "models " 
+.SH NAME
+models \- List local models (ollama, llama.cpp, LM Studio) and prune unused ones
+.SH SYNOPSIS
+\fBmodels\fR [\fB\-\-prune\fR] [\fB\-\-dry\-run\fR] [\fB\-\-yes\fR] [\fB\-\-days\fR] [\fB\-h\fR|\fB\-\-help\fR] 
+.SH DESCRIPTION
+List local models (ollama, llama.cpp, LM Studio) and prune unused ones
+.SH OPTIONS
+.TP
+\fB\-\-prune\fR
+Purge unused models instead of listing them
+.TP
+\fB\-\-dry\-run\fR
+Only list what would be pruned, delete nothing
+.TP
+\fB\-\-yes\fR
+Answer yes to the deletion prompt
+.TP
+\fB\-\-days\fR \fI<DAYS>\fR
+Consider a model unused after N days (default: 30)
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help

man/am-monitor.1

@@ -0,0 +1,19 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-monitor 1  "monitor " 
+.SH NAME
+monitor \- Real\-time monitor of the managed processes (issue #50)
+.SH SYNOPSIS
+\fBmonitor\fR [\fB\-\-interval\fR] [\fB\-\-json\fR] [\fB\-h\fR|\fB\-\-help\fR] 
+.SH DESCRIPTION
+Real\-time monitor of the managed processes (issue #50)
+.SH OPTIONS
+.TP
+\fB\-\-interval\fR \fI<SECONDS>\fR
+Refresh interval in seconds (default 2)
+.TP
+\fB\-\-json\fR
+Print one JSON document per tick instead of the TUI
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help

man/am-note.1

@@ -0,0 +1,19 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-note 1  "note " 
+.SH NAME
+note \- Attach a free\-form note to an agent (shown in \*(Aqam info\*(Aq); \*(Aqam note <agent>\*(Aq without text prints the current note
+.SH SYNOPSIS
+\fBnote\fR [\fB\-h\fR|\fB\-\-help\fR] <\fIAGENT\fR> [\fITEXT...\fR] 
+.SH DESCRIPTION
+Attach a free\-form note to an agent (shown in \*(Aqam info\*(Aq); \*(Aqam note <agent>\*(Aq without text prints the current note
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+<\fIAGENT\fR>
+Agent name or alias
+.TP
+[\fITEXT...\fR]
+Note text (several words are joined); empty prints the note

man/am-open.1

@@ -0,0 +1,16 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-open 1  "open " 
+.SH NAME
+open \- Open an agent\*(Aqs installation directory in the file manager
+.SH SYNOPSIS
+\fBopen\fR [\fB\-h\fR|\fB\-\-help\fR] <\fIAGENT\fR> 
+.SH DESCRIPTION
+Open an agent\*(Aqs installation directory in the file manager
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+<\fIAGENT\fR>
+Agent name or alias

man/am-playbook.1

@@ -0,0 +1,19 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-playbook 1  "playbook " 
+.SH NAME
+playbook \- Replay a saved playbook step by step with confirmation (issue #51)
+.SH SYNOPSIS
+\fBplaybook\fR [\fB\-\-var\fR] [\fB\-h\fR|\fB\-\-help\fR] <\fIFILE\fR> 
+.SH DESCRIPTION
+Replay a saved playbook step by step with confirmation (issue #51)
+.SH OPTIONS
+.TP
+\fB\-\-var\fR \fI<NAME=VALUE>\fR
+Variable values, repeatable: \-\-var name=value
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+<\fIFILE\fR>
+Playbook file (state_dir/playbooks/ when a bare name is given)

man/am-plugins.1

@@ -0,0 +1,16 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-plugins 1  "plugins " 
+.SH NAME
+plugins \- List the event plugins and test one (issue #75)
+.SH SYNOPSIS
+\fBplugins\fR [\fB\-\-test\fR] [\fB\-h\fR|\fB\-\-help\fR] 
+.SH DESCRIPTION
+List the event plugins and test one (issue #75)
+.SH OPTIONS
+.TP
+\fB\-\-test\fR \fI<NAME>\fR
+Run one plugin against a synthetic event and print its response
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help

man/am-profile.1

@@ -0,0 +1,23 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-profile 1  "profile " 
+.SH NAME
+profile \- Manage environment profiles (dev, prod, ...)
+.SH SYNOPSIS
+\fBprofile\fR [\fB\-h\fR|\fB\-\-help\fR] <\fIsubcommands\fR>
+.SH DESCRIPTION
+Manage environment profiles (dev, prod, ...)
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.SH SUBCOMMANDS
+.TP
+profile\-list(1)
+List every defined profile
+.TP
+profile\-show(1)
+Show one profile in detail (agent, env, args)
+.TP
+profile\-help(1)
+Print this message or the help of the given subcommand(s)

man/am-projects.1

@@ -0,0 +1,16 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-projects 1  "projects " 
+.SH NAME
+projects \- Show which agent works on which project
+.SH SYNOPSIS
+\fBprojects\fR [\fB\-h\fR|\fB\-\-help\fR] [\fINAME\fR] 
+.SH DESCRIPTION
+Show which agent works on which project
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+[\fINAME\fR]
+Project name (omit to list every project)

man/am-providers.1

@@ -0,0 +1,38 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-providers 1  "providers " 
+.SH NAME
+providers \- Manage the LLM provider registry: base URLs, models, default provider
+.SH SYNOPSIS
+\fBproviders\fR [\fB\-h\fR|\fB\-\-help\fR] [\fIsubcommands\fR]
+.SH DESCRIPTION
+Manage the LLM provider registry: base URLs, models, default provider
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.SH SUBCOMMANDS
+.TP
+providers\-list(1)
+List the registered providers (the default one is starred)
+.TP
+providers\-show(1)
+Show one provider in detail (base URL, models, default model)
+.TP
+providers\-add(1)
+Register a provider, or update an existing one
+.TP
+providers\-remove(1)
+Remove a provider from the registry
+.TP
+providers\-set\-token(1)
+Store the provider API token in the OS keyring (shared by every agent of this provider through the @secret cascade, issue #89)
+.TP
+providers\-token(1)
+Check whether a provider token exists (the value is never shown)
+.TP
+providers\-default(1)
+Set the default provider
+.TP
+providers\-help(1)
+Print this message or the help of the given subcommand(s)

man/am-registry.1

@@ -0,0 +1,29 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-registry 1  "registry " 
+.SH NAME
+registry \- Community registry (issue #77): publish, search and install agent catalogs hosted on Gitea
+.SH SYNOPSIS
+\fBregistry\fR [\fB\-h\fR|\fB\-\-help\fR] [\fIsubcommands\fR]
+.SH DESCRIPTION
+Community registry (issue #77): publish, search and install agent catalogs hosted on Gitea
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.SH SUBCOMMANDS
+.TP
+registry\-publish(1)
+Prepare a catalog + manifest (source, version, author, sha256) for publication on Gitea
+.TP
+registry\-search(1)
+Search agents across the registered sources (settings.registry.sources)
+.TP
+registry\-install(1)
+Install a catalog from the registry: manifest + checksum validation, then an explicit trust decision for unknown sources
+.TP
+registry\-list(1)
+List the registered sources
+.TP
+registry\-help(1)
+Print this message or the help of the given subcommand(s)

man/am-report.1

@@ -0,0 +1,22 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-report 1  "report " 
+.SH NAME
+report \- Write a markdown activity report
+.SH SYNOPSIS
+\fBreport\fR [\fB\-\-last\-week\fR] [\fB\-\-last\-month\fR] [\fB\-\-output\fR] [\fB\-h\fR|\fB\-\-help\fR] 
+.SH DESCRIPTION
+Write a markdown activity report
+.SH OPTIONS
+.TP
+\fB\-\-last\-week\fR
+Cover the last 7 days
+.TP
+\fB\-\-last\-month\fR
+Cover the last 30 days
+.TP
+\fB\-\-output\fR \fI<FILE>\fR
+Output file (default: report\-YYYYMMDD.md in the state directory)
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help

man/am-restart.1

@@ -0,0 +1,55 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-restart 1  "restart " 
+.SH NAME
+restart \- Restart an agent: stop, then start with the same options
+.SH SYNOPSIS
+\fBrestart\fR [\fB\-b\fR|\fB\-\-background\fR] [\fB\-f\fR|\fB\-\-foreground\fR] [\fB\-\-args\fR] [\fB\-\-env\fR] [\fB\-\-notify\fR] [\fB\-\-profile\fR] [\fB\-\-model\fR] [\fB\-\-provider\fR] [\fB\-\-no\-sandbox\fR] [\fB\-\-parallel\fR] [\fB\-\-container\fR] [\fB\-\-force\fR] [\fB\-\-timeout\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fIAGENT\fR] 
+.SH DESCRIPTION
+Restart an agent: stop, then start with the same options
+.SH OPTIONS
+.TP
+\fB\-b\fR, \fB\-\-background\fR
+Run detached in the background; output goes to the agent log file
+.TP
+\fB\-f\fR, \fB\-\-foreground\fR
+Run in the foreground, attached to this terminal (the default)
+.TP
+\fB\-\-args\fR [\fI<ARGS>...\fR]
+Extra arguments passed to the agent (repeatable; quoted strings are split on spaces)
+.TP
+\fB\-\-env\fR \fI<KEY=VALUE>\fR
+Set an environment variable for the agent (repeatable): \-\-env KEY=VALUE
+.TP
+\fB\-\-notify\fR
+Send a desktop notification once the agent has started
+.TP
+\fB\-\-profile\fR \fI<NAME>\fR
+Apply an environment profile (env + args, defined in the config)
+.TP
+\fB\-\-model\fR \fI<MODEL>\fR
+Local model to use for this run (validated against the local runtimes)
+.TP
+\fB\-\-provider\fR \fI<PROVIDER>\fR
+Provider to use for this run (issue #92): resolved from the registry
+.TP
+\fB\-\-no\-sandbox\fR
+Skip the agent\*(Aqs sandbox profile for this run (issue #79)
+.TP
+\fB\-\-parallel\fR
+Start every member of a group simultaneously (issue #57)
+.TP
+\fB\-\-container\fR
+Run the agent inside a container (issue #58)
+.TP
+\fB\-\-force\fR
+Kill immediately instead of terminating gracefully
+.TP
+\fB\-\-timeout\fR \fI<SECS>\fR
+Grace period in seconds before killing (default: from config, 5s)
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+[\fIAGENT\fR]
+Agent name, alias, or group:<name> (defaults to the project\*(Aqs default agent)

man/am-run.1

@@ -0,0 +1,31 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-run 1  "run " 
+.SH NAME
+run \- Run the agent command directly with the given arguments (no process management)
+.SH SYNOPSIS
+\fBrun\fR [\fB\-\-model\fR] [\fB\-\-provider\fR] [\fB\-\-no\-sandbox\fR] [\fB\-\-container\fR] [\fB\-h\fR|\fB\-\-help\fR] <\fIAGENT\fR> [\fIARGS...\fR] 
+.SH DESCRIPTION
+Run the agent command directly with the given arguments (no process management)
+.SH OPTIONS
+.TP
+\fB\-\-model\fR \fI<MODEL>\fR
+Local model to use for this run (validated against the local runtimes)
+.TP
+\fB\-\-provider\fR \fI<PROVIDER>\fR
+Provider to use for this run (issue #92): registry lookup, base_url + keyring token + model
+.TP
+\fB\-\-no\-sandbox\fR
+Skip the agent\*(Aqs sandbox profile (issue #79)
+.TP
+\fB\-\-container\fR
+Run the agent inside a container (issue #58)
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+<\fIAGENT\fR>
+Agent name or alias
+.TP
+[\fIARGS...\fR]
+Arguments passed through to the agent command

man/am-schedule.1

@@ -0,0 +1,29 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-schedule 1  "schedule " 
+.SH NAME
+schedule \- Schedule am commands (issue #56)
+.SH SYNOPSIS
+\fBschedule\fR [\fB\-h\fR|\fB\-\-help\fR] <\fIsubcommands\fR>
+.SH DESCRIPTION
+Schedule am commands (issue #56)
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.SH SUBCOMMANDS
+.TP
+schedule\-add(1)
+Add a daily schedule (ex: \*(Aqam schedule add update \-\-all\*(Aq)
+.TP
+schedule\-list(1)
+List the schedules
+.TP
+schedule\-remove(1)
+Remove a schedule by id
+.TP
+schedule\-run(1)
+Run a schedule now (invoked by the OS task, issue #56)
+.TP
+schedule\-help(1)
+Print this message or the help of the given subcommand(s)

man/am-search.1

@@ -0,0 +1,22 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-search 1  "search " 
+.SH NAME
+search \- Search the catalog by keyword (name, description, category, tags)
+.SH SYNOPSIS
+\fBsearch\fR [\fB\-\-category\fR] [\fB\-\-tag\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fIKEYWORD\fR] 
+.SH DESCRIPTION
+Search the catalog by keyword (name, description, category, tags)
+.SH OPTIONS
+.TP
+\fB\-\-category\fR \fI<CATEGORY>\fR
+Restrict to this category
+.TP
+\fB\-\-tag\fR \fI<TAG>\fR
+Only agents carrying this personal tag
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+[\fIKEYWORD\fR]
+Keyword to search for (case\-insensitive substring)

man/am-secret.1

@@ -0,0 +1,26 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-secret 1  "secret " 
+.SH NAME
+secret \- Manage secrets in the OS keyring (never in plaintext config)
+.SH SYNOPSIS
+\fBsecret\fR [\fB\-h\fR|\fB\-\-help\fR] <\fIsubcommands\fR>
+.SH DESCRIPTION
+Manage secrets in the OS keyring (never in plaintext config)
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.SH SUBCOMMANDS
+.TP
+secret\-set(1)
+Store a secret for an agent (or a provider, issue #89)
+.TP
+secret\-unset(1)
+Remove a secret
+.TP
+secret\-list(1)
+List stored secret names (values are never shown)
+.TP
+secret\-help(1)
+Print this message or the help of the given subcommand(s)

man/am-self-uninstall.1

@@ -0,0 +1,15 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-self-uninstall 1  "self-uninstall " 
+.SH NAME
+self\-uninstall \- Remove agent\-manager and everything it created from this machine
+.SH SYNOPSIS
+\fBself\-uninstall\fR [\fB\-h\fR|\fB\-\-help\fR] 
+.SH DESCRIPTION
+Remove agent\-manager and everything it created from this machine
+.PP
+Stops every managed background agent, then deletes the data, state and configuration directories, and finally the executable itself. Combine with \-\-yes for a fully automated one\-liner.
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help (see a summary with \*(Aq\-h\*(Aq)

man/am-self-update.1

@@ -0,0 +1,19 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-self-update 1  "self-update " 
+.SH NAME
+self\-update \- Update agent\-manager itself from the latest release
+.SH SYNOPSIS
+\fBself\-update\fR [\fB\-\-check\fR] [\fB\-\-to\fR] [\fB\-h\fR|\fB\-\-help\fR] 
+.SH DESCRIPTION
+Update agent\-manager itself from the latest release
+.SH OPTIONS
+.TP
+\fB\-\-check\fR
+Only check whether a newer version exists
+.TP
+\fB\-\-to\fR \fI<FILE>\fR
+Download the new binary to this path instead of replacing the current one
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help

man/am-serve.1

@@ -0,0 +1,25 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-serve 1  "serve " 
+.SH NAME
+serve \- Authenticated HTTP + WebSocket API to drive am remotely (issue #80)
+.SH SYNOPSIS
+\fBserve\fR [\fB\-\-token\fR] [\fB\-\-host\fR] [\fB\-\-port\fR] [\fB\-\-rate\-limit\fR] [\fB\-h\fR|\fB\-\-help\fR] 
+.SH DESCRIPTION
+Authenticated HTTP + WebSocket API to drive am remotely (issue #80)
+.SH OPTIONS
+.TP
+\fB\-\-token\fR \fI<TOKEN>\fR
+Bearer token required on every request (mandatory)
+.TP
+\fB\-\-host\fR \fI<HOST>\fR
+Listen address (default 127.0.0.1)
+.TP
+\fB\-\-port\fR \fI<PORT>\fR
+Listening port (default 8080)
+.TP
+\fB\-\-rate\-limit\fR \fI<N>\fR
+Per\-IP request budget per minute (default 120)
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help

man/am-service.1

@@ -0,0 +1,26 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-service 1  "service " 
+.SH NAME
+service \- Register an agent as a system service (issue #55)
+.SH SYNOPSIS
+\fBservice\fR [\fB\-h\fR|\fB\-\-help\fR] <\fIsubcommands\fR>
+.SH DESCRIPTION
+Register an agent as a system service (issue #55)
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.SH SUBCOMMANDS
+.TP
+service\-install(1)
+Install the service unit (systemd / launchd / Task Scheduler)
+.TP
+service\-uninstall(1)
+Remove the service unit
+.TP
+service\-status(1)
+Show whether the service is installed
+.TP
+service\-help(1)
+Print this message or the help of the given subcommand(s)

man/am-sessions.1

@@ -0,0 +1,37 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-sessions 1  "sessions " 
+.SH NAME
+sessions \- List the sessions of every agent (and of the interactive shell)
+.SH SYNOPSIS
+\fBsessions\fR [\fB\-\-project\fR] [\fB\-\-status\fR] [\fB\-\-show\fR] [\fB\-\-resume\fR] [\fB\-\-export\fR] [\fB\-\-output\fR] [\fB\-\-retention\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fIAGENT\fR] 
+.SH DESCRIPTION
+List the sessions of every agent (and of the interactive shell)
+.SH OPTIONS
+.TP
+\fB\-\-project\fR \fI<PROJECT>\fR
+Only sessions of this project
+.TP
+\fB\-\-status\fR \fI<STATUS>\fR
+Only sessions with this status (running, stopped, failed, interrupted)
+.TP
+\fB\-\-show\fR \fI<ID>\fR
+Show one session in detail (summary + log excerpt)
+.TP
+\fB\-\-resume\fR \fI<ID>\fR
+Resume a finished session: relaunch the agent with its recorded arguments
+.TP
+\fB\-\-export\fR \fI<ID>\fR
+Export one session (metadata, commands, log excerpt) to a JSON file
+.TP
+\fB\-\-output\fR \fI<FILE>\fR
+Destination of the export (default: ./am\-session\-<ID>.json)
+.TP
+\fB\-\-retention\fR \fI<DAYS>\fR
+Purge sessions finished more than N days ago (settings default 90)
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+[\fIAGENT\fR]
+Only sessions of this agent

man/am-start.1

@@ -0,0 +1,49 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-start 1  "start " 
+.SH NAME
+start \- Start an agent (foreground by default, or detached with \-\-background)
+.SH SYNOPSIS
+\fBstart\fR [\fB\-b\fR|\fB\-\-background\fR] [\fB\-f\fR|\fB\-\-foreground\fR] [\fB\-\-args\fR] [\fB\-\-env\fR] [\fB\-\-notify\fR] [\fB\-\-profile\fR] [\fB\-\-model\fR] [\fB\-\-provider\fR] [\fB\-\-no\-sandbox\fR] [\fB\-\-parallel\fR] [\fB\-\-container\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fIAGENT\fR] 
+.SH DESCRIPTION
+Start an agent (foreground by default, or detached with \-\-background)
+.SH OPTIONS
+.TP
+\fB\-b\fR, \fB\-\-background\fR
+Run detached in the background; output goes to the agent log file
+.TP
+\fB\-f\fR, \fB\-\-foreground\fR
+Run in the foreground, attached to this terminal (the default)
+.TP
+\fB\-\-args\fR [\fI<ARGS>...\fR]
+Extra arguments passed to the agent (repeatable; quoted strings are split on spaces)
+.TP
+\fB\-\-env\fR \fI<KEY=VALUE>\fR
+Set an environment variable for the agent (repeatable): \-\-env KEY=VALUE
+.TP
+\fB\-\-notify\fR
+Send a desktop notification once the agent has started
+.TP
+\fB\-\-profile\fR \fI<NAME>\fR
+Apply an environment profile (env + args, defined in the config)
+.TP
+\fB\-\-model\fR \fI<MODEL>\fR
+Local model to use for this run (validated against the local runtimes)
+.TP
+\fB\-\-provider\fR \fI<PROVIDER>\fR
+Provider to use for this run (issue #92): resolved from the registry
+.TP
+\fB\-\-no\-sandbox\fR
+Skip the agent\*(Aqs sandbox profile for this run (issue #79)
+.TP
+\fB\-\-parallel\fR
+Start every member of a group simultaneously (issue #57)
+.TP
+\fB\-\-container\fR
+Run the agent inside a container (issue #58)
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+[\fIAGENT\fR]
+Agent name, alias, or group:<name> (defaults to the project\*(Aqs default agent)

man/am-stats.1

@@ -0,0 +1,22 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-stats 1  "stats " 
+.SH NAME
+stats \- Show usage statistics computed from the event journal
+.SH SYNOPSIS
+\fBstats\fR [\fB\-\-period\fR] [\fB\-\-costs\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fIAGENT\fR] 
+.SH DESCRIPTION
+Show usage statistics computed from the event journal
+.SH OPTIONS
+.TP
+\fB\-\-period\fR \fI<PERIOD>\fR
+Only events of the last period (7d, 30d, 90d, all)
+.TP
+\fB\-\-costs\fR
+Show token usage and estimated spend per agent (issue #49)
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+[\fIAGENT\fR]
+Agent name or alias (omit for the global view)

man/am-status.1

@@ -0,0 +1,16 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-status 1  "status " 
+.SH NAME
+status \- Show the state of one agent, or of every installed agent
+.SH SYNOPSIS
+\fBstatus\fR [\fB\-h\fR|\fB\-\-help\fR] [\fIAGENT\fR] 
+.SH DESCRIPTION
+Show the state of one agent, or of every installed agent
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+[\fIAGENT\fR]
+Agent name or alias (omit to show all installed agents)

man/am-stop.1

@@ -0,0 +1,22 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-stop 1  "stop " 
+.SH NAME
+stop \- Stop a background agent (SIGTERM, then SIGKILL after the timeout)
+.SH SYNOPSIS
+\fBstop\fR [\fB\-\-force\fR] [\fB\-\-timeout\fR] [\fB\-h\fR|\fB\-\-help\fR] <\fIAGENT\fR> 
+.SH DESCRIPTION
+Stop a background agent (SIGTERM, then SIGKILL after the timeout)
+.SH OPTIONS
+.TP
+\fB\-\-force\fR
+Kill immediately instead of terminating gracefully
+.TP
+\fB\-\-timeout\fR \fI<SECS>\fR
+Grace period in seconds before killing (default: from config, 5s)
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+<\fIAGENT\fR>
+Agent name, alias, or group:<name>

man/am-suggest.1

@@ -0,0 +1,16 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-suggest 1  "suggest " 
+.SH NAME
+suggest \- Suggest agents matching a query, boosted by real usage (issue #61)
+.SH SYNOPSIS
+\fBsuggest\fR [\fB\-h\fR|\fB\-\-help\fR] <\fIQUERY\fR> 
+.SH DESCRIPTION
+Suggest agents matching a query, boosted by real usage (issue #61)
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+<\fIQUERY\fR>
+Free\-form request ("un agent pour du Python")

man/am-sync.1

@@ -0,0 +1,16 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-sync 1  "sync " 
+.SH NAME
+sync \- Push the state into the configured git repository (issue #66)
+.SH SYNOPSIS
+\fBsync\fR [\fB\-\-message\fR] [\fB\-h\fR|\fB\-\-help\fR] 
+.SH DESCRIPTION
+Push the state into the configured git repository (issue #66)
+.SH OPTIONS
+.TP
+\fB\-\-message\fR \fI<MESSAGE>\fR
+Commit message (default: "am sync — state update")
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help

man/am-tag.1

@@ -0,0 +1,19 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-tag 1  "tag " 
+.SH NAME
+tag \- Add a personal tag to an agent
+.SH SYNOPSIS
+\fBtag\fR [\fB\-h\fR|\fB\-\-help\fR] <\fIAGENT\fR> <\fITAG\fR> 
+.SH DESCRIPTION
+Add a personal tag to an agent
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+<\fIAGENT\fR>
+Agent name or alias
+.TP
+<\fITAG\fR>
+One or more tags to add

man/am-tags.1

@@ -0,0 +1,16 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-tags 1  "tags " 
+.SH NAME
+tags \- List personal tags (with counts), optionally for one agent
+.SH SYNOPSIS
+\fBtags\fR [\fB\-h\fR|\fB\-\-help\fR] [\fIAGENT\fR] 
+.SH DESCRIPTION
+List personal tags (with counts), optionally for one agent
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+[\fIAGENT\fR]
+Only show the tags of this agent

man/am-theme.1

@@ -0,0 +1,16 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-theme 1  "theme " 
+.SH NAME
+theme \- Set or show the active color theme (persisted for the next run)
+.SH SYNOPSIS
+\fBtheme\fR [\fB\-h\fR|\fB\-\-help\fR] [\fINAME\fR] 
+.SH DESCRIPTION
+Set or show the active color theme (persisted for the next run)
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+[\fINAME\fR]
+Theme name (omit to list available themes)

man/am-timeline.1

@@ -0,0 +1,25 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-timeline 1  "timeline " 
+.SH NAME
+timeline \- One chronological view of every activity (journal + REPL history)
+.SH SYNOPSIS
+\fBtimeline\fR [\fB\-\-project\fR] [\fB\-\-since\fR] [\fB\-\-limit\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fIAGENT\fR] 
+.SH DESCRIPTION
+One chronological view of every activity (journal + REPL history)
+.SH OPTIONS
+.TP
+\fB\-\-project\fR \fI<PROJECT>\fR
+Only activity of this project
+.TP
+\fB\-\-since\fR \fI<DATE>\fR
+Only activity at or after this date (YYYY\-MM\-DD or RFC 3339)
+.TP
+\fB\-\-limit\fR \fI<N>\fR [default: 50]
+Maximum number of entries (default: 50)
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+[\fIAGENT\fR]
+Only activity of this agent

man/am-tip.1

@@ -0,0 +1,16 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-tip 1  "tip " 
+.SH NAME
+tip \- Cheat sheet: the most useful commands, their key options, your most\-used commands and a rotating tip of the day
+.SH SYNOPSIS
+\fBtip\fR [\fB\-\-random\fR] [\fB\-h\fR|\fB\-\-help\fR] 
+.SH DESCRIPTION
+Cheat sheet: the most useful commands, their key options, your most\-used commands and a rotating tip of the day
+.SH OPTIONS
+.TP
+\fB\-\-random\fR
+Show a single random tip instead of the whole page
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help

man/am-top.1

@@ -0,0 +1,16 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-top 1  "top " 
+.SH NAME
+top \- Show the most used agents (top 10)
+.SH SYNOPSIS
+\fBtop\fR [\fB\-\-period\fR] [\fB\-h\fR|\fB\-\-help\fR] 
+.SH DESCRIPTION
+Show the most used agents (top 10)
+.SH OPTIONS
+.TP
+\fB\-\-period\fR \fI<PERIOD>\fR
+Only events of the last period (7d, 30d, 90d, all)
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help

man/am-unfavorite.1

@@ -0,0 +1,16 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-unfavorite 1  "unfavorite " 
+.SH NAME
+unfavorite \- Remove the favorite star from an agent
+.SH SYNOPSIS
+\fBunfavorite\fR [\fB\-h\fR|\fB\-\-help\fR] <\fIAGENT\fR> 
+.SH DESCRIPTION
+Remove the favorite star from an agent
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+<\fIAGENT\fR>
+Agent name or alias

man/am-uninstall.1

@@ -0,0 +1,19 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-uninstall 1  "uninstall " 
+.SH NAME
+uninstall \- Uninstall an agent (managed or external) and clean its files
+.SH SYNOPSIS
+\fBuninstall\fR [\fB\-\-purge\fR] [\fB\-h\fR|\fB\-\-help\fR] <\fIAGENT\fR> 
+.SH DESCRIPTION
+Uninstall an agent (managed or external) and clean its files
+.SH OPTIONS
+.TP
+\fB\-\-purge\fR
+Also remove logs and the agent entry from the user config file
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+<\fIAGENT\fR>
+Agent name or alias

man/am-untag.1

@@ -0,0 +1,19 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-untag 1  "untag " 
+.SH NAME
+untag \- Remove a personal tag from an agent
+.SH SYNOPSIS
+\fBuntag\fR [\fB\-h\fR|\fB\-\-help\fR] <\fIAGENT\fR> <\fITAG\fR> 
+.SH DESCRIPTION
+Remove a personal tag from an agent
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+<\fIAGENT\fR>
+Agent name or alias
+.TP
+<\fITAG\fR>
+Tag to remove

man/am-update.1

@@ -0,0 +1,22 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-update 1  "update " 
+.SH NAME
+update \- Update an installed agent to the latest available version
+.SH SYNOPSIS
+\fBupdate\fR [\fB\-\-all\fR] [\fB\-\-rollback\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fIAGENT\fR] 
+.SH DESCRIPTION
+Update an installed agent to the latest available version
+.SH OPTIONS
+.TP
+\fB\-\-all\fR
+Update every installed managed agent
+.TP
+\fB\-\-rollback\fR [\fI<ROLLBACK>\fR]
+Roll back to a pre\-update backup instead of updating ("latest" or a backup id; "\-\-rollback list" shows them)
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+[\fIAGENT\fR]
+Agent name or alias (required unless \-\-all)

man/am-version.1

@@ -0,0 +1,13 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-version 1  "version " 
+.SH NAME
+version \- Display version and build information
+.SH SYNOPSIS
+\fBversion\fR [\fB\-h\fR|\fB\-\-help\fR] 
+.SH DESCRIPTION
+Display version and build information
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help

man/am-watch.1

@@ -0,0 +1,25 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-watch 1  "watch " 
+.SH NAME
+watch \- Supervise an agent and optionally restart it on crash
+.SH SYNOPSIS
+\fBwatch\fR [\fB\-\-restart\fR] [\fB\-\-notify\fR] [\fB\-\-interval\fR] [\fB\-h\fR|\fB\-\-help\fR] <\fIAGENT\fR> 
+.SH DESCRIPTION
+Supervise an agent and optionally restart it on crash
+.SH OPTIONS
+.TP
+\fB\-\-restart\fR
+Restart the agent automatically when it dies (with backoff)
+.TP
+\fB\-\-notify\fR
+Desktop notification on every restart
+.TP
+\fB\-\-interval\fR \fI<SECS>\fR [default: 5]
+Check interval in seconds (default: 5)
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+<\fIAGENT\fR>
+Agent name or alias

man/am-web.1

@@ -0,0 +1,19 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am-web 1  "web " 
+.SH NAME
+web \- Local read\-only web dashboard with charts (issue #54)
+.SH SYNOPSIS
+\fBweb\fR [\fB\-\-port\fR] [\fB\-\-no\-open\fR] [\fB\-h\fR|\fB\-\-help\fR] 
+.SH DESCRIPTION
+Local read\-only web dashboard with charts (issue #54)
+.SH OPTIONS
+.TP
+\fB\-\-port\fR \fI<PORT>\fR
+Port to listen on (default 7878)
+.TP
+\fB\-\-no\-open\fR
+Do not open the browser automatically
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help

man/am.1

@@ -0,0 +1,247 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH am 1  "am 1.0.0" 
+.SH NAME
+am \- agent\-manager (am) — manage local AI coding agents
+.SH SYNOPSIS
+\fBam\fR [\fB\-c\fR|\fB\-\-config\fR] [\fB\-v\fR|\fB\-\-verbose\fR] [\fB\-q\fR|\fB\-\-quiet\fR] [\fB\-y\fR|\fB\-\-yes\fR] [\fB\-\-dry\-run\fR] [\fB\-\-json\fR] [\fB\-\-no\-color\fR] [\fB\-\-theme\fR] [\fB\-\-lang\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] [\fIsubcommands\fR]
+.SH DESCRIPTION
+agent\-manager (am) — a CLI to manage local AI coding agents.
+.PP
+Install, uninstall, start, stop, restart and update AI agents from a YAML
+catalog. Handles dependencies (Node, Python, Go, Rust, Bun), binaries from
+GitHub Releases, install scripts, and git repositories. All state lives under
+your user directories; nothing pollutes the system.
+.SH OPTIONS
+.TP
+\fB\-c\fR, \fB\-\-config\fR \fI<FILE>\fR
+Use an alternate configuration file
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+Verbose output: show every command executed and its details
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR
+Quiet mode: only errors are printed
+.TP
+\fB\-y\fR, \fB\-\-yes\fR
+Answer yes to every confirmation prompt
+.TP
+\fB\-\-dry\-run\fR
+Simulate the action without changing anything
+.TP
+\fB\-\-json\fR
+Emit machine\-readable JSON on stdout (for scripts)
+.TP
+\fB\-\-no\-color\fR
+Disable ANSI colors
+.TP
+\fB\-\-theme\fR \fI<THEME>\fR
+Color theme for the output (see \*(Aqam help theme\*(Aq for the list)
+.TP
+\fB\-\-lang\fR \fI<LANG>\fR
+Output language: fr (default) or en (issue #74)
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+fr
+.IP \(bu 2
+en
+.RE
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help (see a summary with \*(Aq\-h\*(Aq)
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+Print version
+.SH SUBCOMMANDS
+.TP
+am\-list(1)
+List installed agents (default); use \-\-all for the whole catalog
+.TP
+am\-logs(1)
+Tail the log file of an agent (\-\-follow for a live view)
+.TP
+am\-open(1)
+Open an agent\*(Aqs installation directory in the file manager
+.TP
+am\-watch(1)
+Supervise an agent and optionally restart it on crash
+.TP
+am\-dashboard(1)
+Live TUI dashboard: overview, activity, stats, sessions, projects
+.TP
+am\-favorite(1)
+Mark an agent as a favorite (star in list and status)
+.TP
+am\-unfavorite(1)
+Remove the favorite star from an agent
+.TP
+am\-note(1)
+Attach a free\-form note to an agent (shown in \*(Aqam info\*(Aq); \*(Aqam note <agent>\*(Aq without text prints the current note
+.TP
+am\-tag(1)
+Add a personal tag to an agent
+.TP
+am\-untag(1)
+Remove a personal tag from an agent
+.TP
+am\-tags(1)
+List personal tags (with counts), optionally for one agent
+.TP
+am\-profile(1)
+Manage environment profiles (dev, prod, ...)
+.TP
+am\-man(1)
+Generate a man page for am (or for one command)
+.TP
+am\-theme(1)
+Set or show the active color theme (persisted for the next run)
+.TP
+am\-alias(1)
+Manage command aliases (cc \-> claude\-code)
+.TP
+am\-secret(1)
+Manage secrets in the OS keyring (never in plaintext config)
+.TP
+am\-audit(1)
+Audit the configuration: who changed what, when (issue #63)
+.TP
+am\-service(1)
+Register an agent as a system service (issue #55)
+.TP
+am\-schedule(1)
+Schedule am commands (issue #56)
+.TP
+am\-models(1)
+List local models (ollama, llama.cpp, LM Studio) and prune unused ones
+.TP
+am\-registry(1)
+Community registry (issue #77): publish, search and install agent catalogs hosted on Gitea
+.TP
+am\-catalog(1)
+Manage remote catalogs: update the official one, add external ones
+.TP
+am\-providers(1)
+Manage the LLM provider registry: base URLs, models, default provider
+.TP
+am\-suggest(1)
+Suggest agents matching a query, boosted by real usage (issue #61)
+.TP
+am\-ask(1)
+Ask a natural\-language request and get the matching am command(s) (issue #78): local rules first, optional LLM refinement, confirmation before execution
+.TP
+am\-start(1)
+Start an agent (foreground by default, or detached with \-\-background)
+.TP
+am\-stop(1)
+Stop a background agent (SIGTERM, then SIGKILL after the timeout)
+.TP
+am\-restart(1)
+Restart an agent: stop, then start with the same options
+.TP
+am\-status(1)
+Show the state of one agent, or of every installed agent
+.TP
+am\-sessions(1)
+List the sessions of every agent (and of the interactive shell)
+.TP
+am\-stats(1)
+Show usage statistics computed from the event journal
+.TP
+am\-monitor(1)
+Real\-time monitor of the managed processes (issue #50)
+.TP
+am\-web(1)
+Local read\-only web dashboard with charts (issue #54)
+.TP
+am\-serve(1)
+Authenticated HTTP + WebSocket API to drive am remotely (issue #80)
+.TP
+am\-sync(1)
+Push the state into the configured git repository (issue #66)
+.TP
+am\-migrate(1)
+Transfer the installation and state to another machine (issue #68)
+.TP
+am\-top(1)
+Show the most used agents (top 10)
+.TP
+am\-report(1)
+Write a markdown activity report
+.TP
+am\-projects(1)
+Show which agent works on which project
+.TP
+am\-timeline(1)
+One chronological view of every activity (journal + REPL history)
+.TP
+am\-log(1)
+Read the event journal: everything am did
+.TP
+am\-install(1)
+Install an agent and its dependencies
+.TP
+am\-uninstall(1)
+Uninstall an agent (managed or external) and clean its files
+.TP
+am\-update(1)
+Update an installed agent to the latest available version
+.TP
+am\-search(1)
+Search the catalog by keyword (name, description, category, tags)
+.TP
+am\-history(1)
+Search the command history (am and shell commands)
+.TP
+am\-playbook(1)
+Replay a saved playbook step by step with confirmation (issue #51)
+.TP
+am\-lab(1)
+Benchmark: run the same task on several agents and compare (issue #62)
+.TP
+am\-plugins(1)
+List the event plugins and test one (issue #75)
+.TP
+am\-info(1)
+Show detailed information about one agent
+.TP
+am\-init(1)
+Generate a local agent\-manager.yaml for the current directory
+.TP
+am\-help(1)
+Display help: the overview, a command, the command list, or a search
+.TP
+am\-version(1)
+Display version and build information
+.TP
+am\-tip(1)
+Cheat sheet: the most useful commands, their key options, your most\-used commands and a rotating tip of the day
+.TP
+am\-config(1)
+Manage the configuration file
+.TP
+am\-doctor(1)
+Check the environment: tools, config validity, paths, permissions
+.TP
+am\-run(1)
+Run the agent command directly with the given arguments (no process management)
+.TP
+am\-completion(1)
+Generate a shell completion script
+.TP
+am\-self\-update(1)
+Update agent\-manager itself from the latest release
+.TP
+am\-self\-uninstall(1)
+Remove agent\-manager and everything it created from this machine
+.TP
+am\-export(1)
+Export the configuration and installation state (backup)
+.TP
+am\-import(1)
+Import a previously exported configuration and state
+.SH VERSION
+v1.0.0

packaging/deb/make-deb.sh

@@ -0,0 +1,33 @@
+#!/bin/sh
+# Builds an am_<version>_amd64.deb from dist/am-linux-x86_64.
+# Usage: packaging/deb/make-deb.sh <version> [arch]
+set -e
+VERSION="$1"
+ARCH="${2:-amd64}"
+ROOT="$(mktemp -d)"
+PKG="am_${VERSION}_${ARCH}"
+
+mkdir -p "$ROOT/$PKG/usr/bin" "$ROOT/$PKG/usr/share/doc/am" "$ROOT/$PKG/DEBIAN"
+cp dist/am-linux-x86_64 "$ROOT/$PKG/usr/bin/am"
+chmod 755 "$ROOT/$PKG/usr/bin/am"
+
+cat > "$ROOT/$PKG/DEBIAN/control" <<EOF
+Package: am
+Version: $VERSION
+Section: utils
+Priority: optional
+Architecture: $ARCH
+Maintainer: bruno <[email protected]>
+Description: Manage local AI coding agents
+ List, install, start, stop and update local AI coding agents with
+ automatic dependency handling and a YAML-driven catalog.
+EOF
+
+cat > "$ROOT/$PKG/usr/share/doc/am/copyright" <<EOF
+Copyright (c) 2026 bruno
+License: MIT
+EOF
+
+dpkg-deb --build --root-owner-group "$ROOT/$PKG" "dist/$PKG.deb"
+rm -rf "$ROOT"
+echo "built dist/$PKG.deb"

packaging/homebrew/am.rb

@@ -0,0 +1,36 @@
+# Homebrew formula - pour un tap local, ou a soumettre a homebrew/core.
+# Rendu : scripts/render-manifests.ps1 (remplace {{VERSION}} et les sha256).
+class Am < Formula
+  desc "Manage local AI coding agents: list, install, start, stop, update"
+  homepage "https://git.dracodev.net/Projets/agent-manager"
+  license "MIT"
+  version "{{VERSION}}"
+
+  on_macos do
+    if Hardware::CPU.arm?
+      url "https://git.dracodev.net/Projets/agent-manager/releases/download/v{{VERSION}}/am-macos-aarch64.tar.gz"
+      sha256 "{{SHA256_MACOS_AARCH64}}"
+    else
+      url "https://git.dracodev.net/Projets/agent-manager/releases/download/v{{VERSION}}/am-macos-x86_64.tar.gz"
+      sha256 "{{SHA256_MACOS_X86_64}}"
+    end
+  end
+
+  on_linux do
+    if Hardware::CPU.arm?
+      url "https://git.dracodev.net/Projets/agent-manager/releases/download/v{{VERSION}}/am-linux-aarch64.tar.gz"
+      sha256 "{{SHA256_LINUX_AARCH64}}"
+    else
+      url "https://git.dracodev.net/Projets/agent-manager/releases/download/v{{VERSION}}/am-linux-x86_64.tar.gz"
+      sha256 "{{SHA256_LINUX_X86_64}}"
+    end
+  end
+
+  def install
+    bin.install "am"
+  end
+
+  test do
+    system bin/"am", "version"
+  end
+end

packaging/rpm/am.spec

@@ -0,0 +1,26 @@
+# RPM spec - build avec: rpmbuild -bb packaging/rpm/am.spec
+# (rendu par scripts/render-manifests.ps1: %%{VERSION} -> version)
+Name:           am
+Version:        {{VERSION}}
+Release:        1%{?dist}
+Summary:        Manage local AI coding agents
+License:        MIT
+URL:            https://git.dracodev.net/Projets/agent-manager
+Source0:        am-linux-x86_64.tar.gz
+
+%description
+am lists, installs, starts, stops and updates local AI coding agents
+(Claude Code, Codex, Aider, ...) with automatic dependency handling and a
+YAML-driven catalog.
+
+%prep
+%setup -c -T
+tar -xzf %{SOURCE0}
+
+%install
+install -Dm755 am %{buildroot}%{_bindir}/am
+
+%files
+%{_bindir}/am
+
+%changelog

packaging/scoop/am.json

@@ -0,0 +1,24 @@
+{
+    "version": "{{VERSION}}",
+    "description": "Manage local AI coding agents: list, install, start, stop, update - with automatic dependency handling and a YAML-driven catalog.",
+    "homepage": "https://git.dracodev.net/Projets/agent-manager",
+    "license": "MIT",
+    "architecture": {
+        "64bit": {
+            "url": "https://git.dracodev.net/Projets/agent-manager/releases/download/v{{VERSION}}/am-windows-x86_64.zip",
+            "hash": "{{SHA256_WINDOWS}}"
+        }
+    },
+    "bin": "am.exe",
+    "checkver": {
+        "url": "https://git.dracodev.net/api/v1/repos/Projets/agent-manager/releases/latest",
+        "regex": "tag_name\":\s*\"v([\d.]+)\""
+    },
+    "autoupdate": {
+        "architecture": {
+            "64bit": {
+                "url": "https://git.dracodev.net/Projets/agent-manager/releases/download/v$version/am-windows-x86_64.zip"
+            }
+        }
+    }
+}

packaging/winget/agent-manager.installer.yaml

@@ -0,0 +1,16 @@
+# Winget manifest (version 1.6) - submit to microsoft/winget-pkgs
+# Rendering: scripts/render-manifests.ps1
+PackageIdentifier: BrunoDracodev.AgentManager
+PackageVersion: {{VERSION}}
+MinimumOSVersion: 10.0.0.0
+InstallerType: zip
+Installers:
+  - Architecture: x64
+    InstallerUrl: https://git.dracodev.net/Projets/agent-manager/releases/download/v{{VERSION}}/am-windows-x86_64.zip
+    InstallerSha256: {{SHA256_WINDOWS}}
+    NestedInstallerType: portable
+    NestedInstallerFiles:
+      - RelativeFilePath: am.exe
+        PortableCommandAlias: am
+ManifestType: installer
+ManifestVersion: 1.6.0

packaging/winget/agent-manager.locale.en-US.yaml

@@ -0,0 +1,18 @@
+# Winget locale manifest - submit to microsoft/winget-pkgs
+PackageIdentifier: BrunoDracodev.AgentManager
+PackageVersion: {{VERSION}}
+PackageLocale: en-US
+Publisher: bruno (dracodev)
+PackageName: agent-manager (am)
+PackageUrl: https://git.dracodev.net/Projets/agent-manager
+License: MIT
+ShortDescription: Manage local AI coding agents - list, install, start, stop, update - with automatic dependency handling.
+Moniker: am
+Tags:
+  - agent
+  - claude
+  - cli
+  - coding
+  - llm
+ManifestType: defaultLocale
+ManifestVersion: 1.6.0

packaging/winget/agent-manager.yaml

@@ -0,0 +1,6 @@
+# Winget version manifest - submit to microsoft/winget-pkgs
+PackageIdentifier: BrunoDracodev.AgentManager
+PackageVersion: {{VERSION}}
+DefaultLocale: en-US
+ManifestType: version
+ManifestVersion: 1.6.0

scripts/build-release.ps1

@@ -0,0 +1,20 @@
+# Builds the release artefacts for the current platform (Windows):
+#   target/release/am.exe -> dist/am-windows-x86_64.zip
+# Also prints the sha256 of every archive (for the packaging manifests).
+param([switch]$NoTest)
+$ErrorActionPreference = "Stop"
+
+cargo build --release --locked
+if (-not $NoTest) { cargo test --release --locked }
+
+New-Item -ItemType Directory -Force dist | Out-Null
+$zip = "dist/am-windows-x86_64.zip"
+Remove-Item $zip -ErrorAction SilentlyContinue
+Compress-Archive -Path target/release/am.exe -DestinationPath $zip
+
+Write-Host ""
+Write-Host "Artefacts:"
+Get-ChildItem dist | ForEach-Object {
+    $hash = (Get-FileHash $_.FullName -Algorithm SHA256).Hash.ToLower()
+    Write-Host ("  {0,-32} {1}  sha256:{2}" -f $_.Name, $_.Length, $hash)
+}

scripts/render-manifests.ps1

@@ -0,0 +1,50 @@
+# Renders the packaging templates (scoop, winget, homebrew, rpm) with the
+# version and the sha256 of every release archive.
+# Usage: scripts/render-manifests.ps1 -Version 0.4.3 [-DistDir dist]
+param(
+    [Parameter(Mandatory = $true)][string]$Version,
+    [string]$DistDir = "dist"
+)
+$ErrorActionPreference = "Stop"
+
+function Get-Sha([string]$file) {
+    $p = Join-Path $DistDir $file
+    if (-not (Test-Path $p)) {
+        Write-Warning "missing $p - placeholder 0000... (build it or wait for the CI runner)"
+        return "0000000000000000000000000000000000000000000000000000000000000000"
+    }
+    (Get-FileHash $p -Algorithm SHA256).Hash.ToLower()
+}
+
+$vars = [ordered]@{
+    "{{VERSION}}"              = $Version
+    "{{SHA256_WINDOWS}}"       = Get-Sha "am-windows-x86_64.zip"
+    "{{SHA256_LINUX_X86_64}}"  = Get-Sha "am-linux-x86_64.tar.gz"
+    "{{SHA256_LINUX_AARCH64}}" = Get-Sha "am-linux-aarch64.tar.gz"
+    "{{SHA256_MACOS_X86_64}}"  = Get-Sha "am-macos-x86_64.tar.gz"
+    "{{SHA256_MACOS_AARCH64}}" = Get-Sha "am-macos-aarch64.tar.gz"
+}
+
+$targets = @(
+    @{ Src = "packaging/scoop/am.json";              Dst = "dist/scoop/am.json" },
+    @{ Src = "packaging/winget/agent-manager.installer.yaml";    Dst = "dist/winget/agent-manager.installer.yaml" },
+    @{ Src = "packaging/winget/agent-manager.locale.en-US.yaml"; Dst = "dist/winget/agent-manager.locale.en-US.yaml" },
+    @{ Src = "packaging/winget/agent-manager.yaml";  Dst = "dist/winget/agent-manager.yaml" },
+    @{ Src = "packaging/homebrew/am.rb";             Dst = "dist/homebrew/am.rb" },
+    @{ Src = "packaging/rpm/am.spec";                Dst = "dist/rpm/am.spec" }
+)
+
+foreach ($t in $targets) {
+    $text = Get-Content $t.Src -Raw
+    foreach ($k in $vars.Keys) { $text = $text.Replace($k, $vars[$k]) }
+    New-Item -ItemType Directory -Force (Split-Path $t.Dst) | Out-Null
+    Set-Content -Path $t.Dst -Value $text -NoNewline -Encoding utf8
+    Write-Host "rendered $($t.Dst)"
+}
+Write-Host ""
+Write-Host "Manifests rendus dans dist/. Puis :"
+Write-Host "  - scoop :    scoop install dist/scoop/am.json (ou ajoutez-le a votre bucket)"
+Write-Host "  - winget :   soumettez dist/winget/*.yaml a microsoft/winget-pkgs"
+Write-Host "  - homebrew : servez dist/homebrew/am.rb via un tap, ou soumettez a homebrew/core"
+Write-Host "  - rpm :      copiez dist/rpm/am.spec + dist/am-linux-x86_64.tar.gz dans ~/rpmbuild/{SPECS,SOURCES} puis rpmbuild -bb"
+Write-Host "  - deb :      packaging/deb/make-deb.sh $Version"

src/agent_config.rs

@@ -0,0 +1,517 @@
+//! Post-install agent configuration (issue #91): the `config:` block of an
+//! agent definition wires the resolved provider/model into the agent —
+//! the environment variables it expects (env_map) and the config files to
+//! write or softly edit (files).
+//!
+//! Pure functions + per-format tests (probe.rs pattern). Security rule: a
+//! token is never written in clear — the api_key slot stays the `@secret`
+//! reference (issue #89), resolved from the OS keyring at start/run time.
+
+use crate::app::App;
+use crate::config::{AgentDef, Config};
+use anyhow::{anyhow, Context, Result};
+use std::collections::BTreeMap;
+use std::path::Path;
+
+/// The four format families covering ~every agent (spec #91).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum FileFormat {
+    Toml,
+    Yaml,
+    Json,
+    KeyValue,
+}
+
+impl FileFormat {
+    pub fn name(self) -> &'static str {
+        match self {
+            FileFormat::Toml => "toml",
+            FileFormat::Yaml => "yaml",
+            FileFormat::Json => "json",
+            FileFormat::KeyValue => "key=value",
+        }
+    }
+}
+
+/// Detect the format family from the file extension.
+pub fn format_of(path: &Path) -> Option<FileFormat> {
+    let ext = path
+        .extension()
+        .and_then(|e| e.to_str())
+        .unwrap_or("")
+        .to_ascii_lowercase();
+    match ext.as_str() {
+        "toml" => Some(FileFormat::Toml),
+        "yaml" | "yml" => Some(FileFormat::Yaml),
+        "json" => Some(FileFormat::Json),
+        "conf" | "ini" | "env" | "properties" | "cfg" => Some(FileFormat::KeyValue),
+        _ => None,
+    }
+}
+
+/// Provider preferred by an agent: `provider:` of the definition, then the
+/// `config.provider_default` of its config block (issue #91).
+pub fn provider_pref(agent: &AgentDef) -> Option<&str> {
+    agent
+        .provider
+        .as_deref()
+        .or(agent.config.as_ref().and_then(|c| c.provider_default.as_deref()))
+}
+
+/// Merge the resolved `config.env_map` of an agent into its default env
+/// (issue #91): api_key -> `@secret` (resolved by resolve_env_secrets),
+/// model/base_url/provider -> values of the resolved provider. Explicit
+/// values already present in agent.env are never overwritten.
+pub fn apply_env_map(env: &mut BTreeMap<String, String>, agent: &AgentDef, config: &Config) {
+    apply_env_map_resolved(env, agent, config, None, None);
+}
+
+/// Same as `apply_env_map` but with the provider and model fixed by the
+/// caller (issue #92: `am run/start --provider/--model`): the flags win
+/// over the agent declaration and the settings default.
+pub fn apply_env_map_resolved(
+    env: &mut BTreeMap<String, String>,
+    agent: &AgentDef,
+    config: &Config,
+    provider_override: Option<&str>,
+    model_override: Option<&str>,
+) {
+    let Some(cfg) = &agent.config else {
+        return;
+    };
+    if cfg.env_map.is_empty() {
+        return;
+    }
+    let Some(pname) = provider_override
+        .filter(|p| !p.is_empty())
+        .or_else(|| provider_pref(agent))
+        .or_else(|| crate::providers::default_name(config))
+    else {
+        return;
+    };
+    let Some(def) = crate::providers::get(config, pname) else {
+        return;
+    };
+    let model = model_override
+        .filter(|m| !m.is_empty())
+        .or(agent.model.as_deref())
+        .or(def.default_model.as_deref());
+    for (slot, var) in &cfg.env_map {
+        let value = match slot.as_str() {
+            "api_key" => "@secret".to_string(),
+            "model" => {
+                let Some(m) = model else { continue };
+                m.to_string()
+            }
+            "base_url" => def.base_url.clone(),
+            "provider" => pname.to_string(),
+            _ => continue, // unknown slots are ignored
+        };
+        env.entry(var.clone()).or_insert(value);
+    }
+}
+
+/// Write the agent configuration files after a successful install
+/// (issue #91). The caller skips this on `--no-config`, on non-configurable
+/// agents, and in dry-run (never reached). Never writes a token in clear:
+/// the api_key slot is written as the `@secret` reference.
+pub fn apply_post_install(
+    app: &App,
+    agent: &AgentDef,
+    resolved: &Option<(String, Option<String>)>,
+) -> Result<()> {
+    let Some(cfg) = &agent.config else {
+        app.log.info(crate::i18n::tr(
+            "agent sans adaptateur de config — voir sa doc",
+        ));
+        return Ok(());
+    };
+    if cfg.files.is_empty() {
+        if cfg.env_map.is_empty() {
+            app.log.info(crate::i18n::tr(
+                "agent sans adaptateur de config — voir sa doc",
+            ));
+        } else {
+            app.log.info(crate::i18n::tr(
+                "config par variables d'env — injectée au démarrage",
+            ));
+        }
+        return Ok(());
+    }
+    let Some((pname, model)) = resolved else {
+        app.log.warn(crate::i18n::tr(
+            "aucun provider résolu — fichiers de config non écrits",
+        ));
+        return Ok(());
+    };
+    let Some(def) = crate::providers::get(&app.config, pname) else {
+        app.log.warn(&crate::tr_fmt!(
+            "provider '{}' introuvable — fichiers de config non écrits",
+            pname
+        ));
+        return Ok(());
+    };
+    for f in &cfg.files {
+        let path = crate::config::expand_path(&f.path);
+        let Some(fmt) = format_of(&path) else {
+            app.log.warn(&crate::tr_fmt!(
+                "format inconnu pour {} — adaptateurs: toml, yaml, json, key=value",
+                path.display()
+            ));
+            continue;
+        };
+        let mut updates: Vec<(String, String)> = Vec::new();
+        for key in &f.keys {
+            let value = match key.as_str() {
+                "api_key" => "@secret".to_string(),
+                "model" => model.clone().unwrap_or_default(),
+                "base_url" => def.base_url.clone(),
+                "provider" => pname.clone(),
+                other => {
+                    app.log.warn(&crate::tr_fmt!(
+                        "clé '{}' inconnue dans config.files de {}",
+                        other,
+                        agent.name
+                    ));
+                    continue;
+                }
+            };
+            updates.push((key.clone(), value));
+        }
+        write_soft(&path, fmt, &updates)?;
+        app.log
+            .success(&crate::tr_fmt!("config écrite: {}", path.display()));
+    }
+    Ok(())
+}
+
+/// Soft edit of a config file: existing unknown keys are preserved, known
+/// keys are updated, missing keys are appended. Creates parent dirs.
+pub fn write_soft(path: &Path, format: FileFormat, updates: &[(String, String)]) -> Result<()> {
+    if let Some(parent) = path.parent() {
+        if !parent.as_os_str().is_empty() {
+            std::fs::create_dir_all(parent)
+                .with_context(|| format!("cannot create {}", parent.display()))?;
+        }
+    }
+    let text = if path.exists() {
+        std::fs::read_to_string(path)
+            .with_context(|| format!("cannot read {}", path.display()))?
+    } else {
+        String::new()
+    };
+    let out = match format {
+        FileFormat::Toml => edit_toml(&text, updates)?,
+        FileFormat::Yaml => edit_yaml(&text, updates)?,
+        FileFormat::Json => edit_json(&text, updates)?,
+        FileFormat::KeyValue => edit_key_value(&text, updates),
+    };
+    std::fs::write(path, out).with_context(|| format!("cannot write {}", path.display()))?;
+    Ok(())
+}
+
+/// TOML soft edit. Note: toml::Value does not retain comments on
+/// serialization — unknown KEYS are preserved, comments are dropped.
+fn edit_toml(text: &str, updates: &[(String, String)]) -> Result<String> {
+    let mut root: toml::Value = if text.trim().is_empty() {
+        toml::Value::Table(Default::default())
+    } else {
+        text.parse::<toml::Value>()
+            .map_err(|e| anyhow!("invalid TOML: {e}"))?
+    };
+    let table = root
+        .as_table_mut()
+        .ok_or_else(|| anyhow!("TOML root is not a table"))?;
+    for (k, v) in updates {
+        table.insert(k.clone(), toml::Value::String(v.clone()));
+    }
+    Ok(root.to_string())
+}
+
+fn edit_yaml(text: &str, updates: &[(String, String)]) -> Result<String> {
+    let mut root: serde_yaml::Value = if text.trim().is_empty() {
+        serde_yaml::Value::Mapping(Default::default())
+    } else {
+        serde_yaml::from_str(text).map_err(|e| anyhow!("invalid YAML: {e}"))?
+    };
+    let map = root
+        .as_mapping_mut()
+        .ok_or_else(|| anyhow!("YAML root is not a mapping"))?;
+    for (k, v) in updates {
+        map.insert(
+            serde_yaml::Value::String(k.clone()),
+            serde_yaml::Value::String(v.clone()),
+        );
+    }
+    serde_yaml::to_string(&root).map_err(|e| anyhow!("cannot serialize YAML: {e}"))
+}
+
+fn edit_json(text: &str, updates: &[(String, String)]) -> Result<String> {
+    let mut root: serde_json::Value = if text.trim().is_empty() {
+        serde_json::Value::Object(Default::default())
+    } else {
+        serde_json::from_str(text).map_err(|e| anyhow!("invalid JSON: {e}"))?
+    };
+    let obj = root
+        .as_object_mut()
+        .ok_or_else(|| anyhow!("JSON root is not an object"))?;
+    for (k, v) in updates {
+        obj.insert(k.clone(), serde_json::Value::String(v.clone()));
+    }
+    serde_json::to_string_pretty(&root).map_err(|e| anyhow!("cannot serialize JSON: {e}"))
+}
+
+fn edit_key_value(text: &str, updates: &[(String, String)]) -> String {
+    let mut lines: Vec<String> = text.lines().map(String::from).collect();
+    let mut seen: BTreeMap<&str, usize> = BTreeMap::new();
+    for (i, line) in lines.iter_mut().enumerate() {
+        let trimmed = line.trim();
+        if trimmed.is_empty()
+            || trimmed.starts_with('#')
+            || trimmed.starts_with(';')
+            || !trimmed.contains('=')
+        {
+            continue;
+        }
+        let key = trimmed.split('=').next().unwrap_or("").trim();
+        // Case-insensitive match (API_KEY vs api_key in .env files); the
+        // existing line keeps its casing.
+        if let Some((k, v)) = updates.iter().find(|(k, _)| k.eq_ignore_ascii_case(key)) {
+            *line = format!("{key}={v}");
+            seen.insert(k, i);
+        }
+    }
+    for (k, v) in updates {
+        if !seen.contains_key(k.as_str()) {
+            lines.push(format!("{k}={v}"));
+        }
+    }
+    let mut out = lines.join("\n");
+    if !out.is_empty() && !out.ends_with('\n') {
+        out.push('\n');
+    }
+    out
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use clap::Parser;
+    use crate::config::{AgentConfig, Config};
+    use std::collections::BTreeMap;
+
+    fn updates() -> Vec<(String, String)> {
+        vec![
+            ("model".to_string(), "gpt-5.2".to_string()),
+            ("base_url".to_string(), "https://api.openai.com/v1".to_string()),
+            ("api_key".to_string(), "@secret".to_string()),
+        ]
+    }
+
+    fn tmp(name: &str, content: &str) -> (tempfile::TempDir, std::path::PathBuf) {
+        let dir = tempfile::tempdir().unwrap();
+        let p = dir.path().join(name);
+        if !content.is_empty() {
+            std::fs::write(&p, content).unwrap();
+        }
+        (dir, p)
+    }
+
+    #[test]
+    fn format_detection_covers_the_four_families() {
+        assert_eq!(format_of(Path::new("a.toml")), Some(FileFormat::Toml));
+        assert_eq!(format_of(Path::new("a.yaml")), Some(FileFormat::Yaml));
+        assert_eq!(format_of(Path::new("a.yml")), Some(FileFormat::Yaml));
+        assert_eq!(format_of(Path::new("a.json")), Some(FileFormat::Json));
+        assert_eq!(format_of(Path::new("a.conf")), Some(FileFormat::KeyValue));
+        assert_eq!(format_of(Path::new("a.env")), Some(FileFormat::KeyValue));
+        assert_eq!(format_of(Path::new("a.ini")), Some(FileFormat::KeyValue));
+        assert_eq!(format_of(Path::new("a.md")), None);
+    }
+
+    #[test]
+    fn toml_round_trip_keeps_unknown_keys() {
+        let (_d, p) = tmp("c.toml", "# existing\nmodel = \"old\"\ntemperature = 0.7\n");
+        write_soft(&p, FileFormat::Toml, &updates()).unwrap();
+        let out = std::fs::read_to_string(&p).unwrap();
+        assert!(out.contains("model = \"gpt-5.2\""), "{out}");
+        assert!(
+            out.contains("base_url = \"https://api.openai.com/v1\""),
+            "{out}"
+        );
+        assert!(out.contains("api_key = \"@secret\""), "{out}");
+        assert!(out.contains("temperature = 0.7"), "unknown key lost: {out}");
+    }
+
+    #[test]
+    fn toml_creates_the_file_when_missing() {
+        let (_d, p) = tmp("new.toml", "");
+        write_soft(&p, FileFormat::Toml, &updates()).unwrap();
+        let out = std::fs::read_to_string(&p).unwrap();
+        assert!(out.contains("model = \"gpt-5.2\""), "{out}");
+        assert!(out.contains("api_key = \"@secret\""), "{out}");
+    }
+
+    #[test]
+    fn yaml_round_trip_keeps_unknown_keys() {
+        let (_d, p) = tmp("c.yaml", "model: old\nverbose: true\n");
+        write_soft(&p, FileFormat::Yaml, &updates()).unwrap();
+        let out = std::fs::read_to_string(&p).unwrap();
+        assert!(out.contains("model: gpt-5.2"), "{out}");
+        assert!(out.contains("base_url: https://api.openai.com/v1"), "{out}");
+        assert!(out.contains("verbose: true"), "unknown key lost: {out}");
+    }
+
+    #[test]
+    fn json_round_trip_keeps_unknown_keys() {
+        let (_d, p) = tmp("c.json", "{\"model\": \"old\", \"verbose\": true}");
+        write_soft(&p, FileFormat::Json, &updates()).unwrap();
+        let out = std::fs::read_to_string(&p).unwrap();
+        assert!(out.contains("\"model\": \"gpt-5.2\""), "{out}");
+        assert!(out.contains("\"api_key\": \"@secret\""), "{out}");
+        assert!(out.contains("\"verbose\": true"), "unknown key lost: {out}");
+    }
+
+    #[test]
+    fn key_value_round_trip_keeps_unknown_lines() {
+        let (_d, p) = tmp(
+            "c.conf",
+            "# header\nMODEL=old\nOTHER=keep\n",
+        );
+        write_soft(&p, FileFormat::KeyValue, &updates()).unwrap();
+        let out = std::fs::read_to_string(&p).unwrap();
+        assert!(out.contains("MODEL=gpt-5.2"), "{out}");
+        assert!(out.contains("OTHER=keep"), "unknown line lost: {out}");
+        assert!(out.contains("# header"), "comment lost: {out}");
+        assert!(out.contains("api_key=@secret"), "{out}");
+        // No duplicate MODEL line.
+        assert_eq!(out.matches("MODEL=").count(), 1, "{out}");
+    }
+
+    #[test]
+    fn key_value_appends_missing_keys() {
+        let (_d, p) = tmp("empty.env", "");
+        write_soft(&p, FileFormat::KeyValue, &updates()).unwrap();
+        let out = std::fs::read_to_string(&p).unwrap();
+        assert!(out.contains("model=gpt-5.2"), "{out}");
+        assert!(out.contains("base_url=https://api.openai.com/v1"), "{out}");
+        assert!(out.contains("api_key=@secret"), "{out}");
+    }
+
+    fn agent_with_config(config: AgentConfig, provider: Option<String>) -> AgentDef {
+        AgentDef {
+            name: "x".to_string(),
+            display_name: None,
+            description: None,
+            category: None,
+            website: None,
+            install: None,
+            dependencies: vec![],
+            run: Some("x".to_string()),
+            args: vec![],
+            env: BTreeMap::new(),
+            version: None,
+            pin_version: None,
+            model_env: None,
+            model_arg: None,
+            provider,
+            model: None,
+            config: Some(config),
+            sandbox: None,
+            tags: vec![],
+            installable: false,
+            note: None,
+            hidden: false,
+            platforms: vec![],
+            healthcheck: None,
+            container: None,
+            cost_model: None,
+        }
+    }
+
+    #[test]
+    fn apply_env_map_wires_the_resolved_provider() {
+        let mut c: Config = serde_yaml::from_str(
+            "version: \"1.0\"\nsettings:\n  default_provider: openai\n  providers:\n    openai:\n      base_url: https://api.openai.com/v1\n      default_model: gpt-5.2\n      models: [gpt-5.2]\n",
+        )
+        .unwrap();
+        let mut env_map = BTreeMap::new();
+        env_map.insert("api_key".to_string(), "MY_KEY".to_string());
+        env_map.insert("model".to_string(), "MY_MODEL".to_string());
+        env_map.insert("base_url".to_string(), "MY_URL".to_string());
+        let agent = agent_with_config(
+            AgentConfig {
+                env_map,
+                files: vec![],
+                provider_default: None,
+            },
+            None,
+        );
+        let mut env = BTreeMap::new();
+        apply_env_map(&mut env, &agent, &c);
+        assert_eq!(env.get("MY_KEY").unwrap(), "@secret");
+        assert_eq!(env.get("MY_MODEL").unwrap(), "gpt-5.2");
+        assert_eq!(env.get("MY_URL").unwrap(), "https://api.openai.com/v1");
+        // Explicit agent.env values win.
+        let mut env2 = BTreeMap::new();
+        env2.insert("MY_MODEL".to_string(), "explicit".to_string());
+        apply_env_map(&mut env2, &agent, &c);
+        assert_eq!(env2.get("MY_MODEL").unwrap(), "explicit");
+        // Unset default provider + no provider_default: no-op.
+        c.settings.default_provider = None;
+        let mut env3 = BTreeMap::new();
+        apply_env_map(&mut env3, &agent, &c);
+        assert!(env3.is_empty());
+    }
+
+    #[test]
+    fn apply_post_install_without_config_block_is_a_noop() {
+        let guard = tempfile::tempdir().unwrap();
+        let dir = guard.path().to_path_buf();
+        std::mem::forget(guard);
+        let cfg = dir.join("config.yaml");
+        std::fs::write(
+            &cfg,
+            "version: \"1.0\"\nsettings:\n  auto_install_deps: false\n  confirm_before_run: false\nagents: []\n",
+        )
+        .unwrap();
+        let cli = crate::cli::Cli::parse_from(["am", "--config", cfg.to_str().unwrap()]);
+        let app = crate::app::App::from_cli(cli).unwrap();
+        let agent = agent_with_config(
+            AgentConfig {
+                env_map: BTreeMap::new(),
+                files: vec![],
+                provider_default: None,
+            },
+            None,
+        );
+        // No config block at all → Ok, nothing written.
+        let mut bare = agent.clone();
+        bare.config = None;
+        assert!(apply_post_install(&app, &bare, &None).is_ok());
+        // Config block but no files → Ok, nothing written.
+        assert!(apply_post_install(&app, &agent, &None).is_ok());
+    }
+
+    #[test]
+    fn provider_pref_prefers_the_declared_provider() {
+        let agent = agent_with_config(
+            AgentConfig {
+                env_map: BTreeMap::new(),
+                files: vec![],
+                provider_default: Some("openai".to_string()),
+            },
+            Some("anthropic".to_string()),
+        );
+        assert_eq!(provider_pref(&agent), Some("anthropic"));
+        let agent2 = agent_with_config(
+            AgentConfig {
+                env_map: BTreeMap::new(),
+                files: vec![],
+                provider_default: Some("openai".to_string()),
+            },
+            None,
+        );
+        assert_eq!(provider_pref(&agent2), Some("openai"));
+    }
+}

src/app.rs

@@ -6,7 +6,9 @@ use crate::cli::Cli;
 use crate::config::{self, Config, Settings};
 use crate::output::Logger;
 use crate::state::StateStore;
-use anyhow::{Context, Result};
+use crate::theme::{self, Theme};
+use anyhow::{anyhow, Context, Result};
+use std::cell::Cell;
 use std::io::{IsTerminal, Write};
 use std::path::PathBuf;
 
@@ -19,6 +21,12 @@ pub struct App {
     pub catalog: Catalog,
     pub state: StateStore,
     pub log: Logger,
+    /// Active output language (issue #74); mirrored in i18n::active() so the
+    /// REPL 'lang' command can switch it at runtime.
+    lang: Cell<crate::i18n::Lang>,
+    /// Active output color theme (switchable at runtime with the REPL
+    /// 'theme <name>' command).
+    theme: Cell<&'static Theme>,
 }
 
 #[derive(Debug, Clone)]
@@ -78,6 +86,9 @@ impl App {
             loaded.config.aliases.clone(),
             loaded.config.groups.clone(),
         );
+        let theme = resolve_theme(cli.theme.as_deref(), loaded.config.settings.theme.as_deref())?;
+        let lang = crate::i18n::resolve(cli.lang);
+        crate::i18n::set_lang(lang);
         Ok(Self {
             cli,
             config: loaded.config,
@@ -86,6 +97,8 @@ impl App {
             catalog,
             state,
             log,
+            lang: Cell::new(lang),
+            theme: Cell::new(theme),
         })
     }
 
@@ -105,6 +118,48 @@ impl App {
         !self.cli.no_color && std::io::stdout().is_terminal()
     }
 
+    pub fn theme(&self) -> &'static Theme {
+        self.theme.get()
+    }
+
+    /// Active output language (issue #74).
+    pub fn lang(&self) -> crate::i18n::Lang {
+        self.lang.get()
+    }
+
+    /// Switch the active language (REPL 'lang' command); the i18n global is
+    /// kept in sync so tr()/tr_fmt! follow immediately.
+    pub fn set_lang(&self, lang: crate::i18n::Lang) {
+        self.lang.set(lang);
+        crate::i18n::set_lang(lang);
+    }
+
+    /// Switch the active theme (used by the REPL 'theme <name>' command).
+    pub fn set_theme(&self, theme: &'static Theme) {
+        self.theme.set(theme);
+    }
+
+    /// Directory of the event journal (the state directory).
+    pub fn events_dir(&self) -> PathBuf {
+        self.paths
+            .state_file
+            .parent()
+            .map(|p| p.to_path_buf())
+            .unwrap_or_else(|| self.paths.state_file.clone())
+    }
+
+    /// Append an event to the journal; failures are never fatal (logged at
+    /// verbose level only). The plugins subscribed to the event kind are
+    /// then fired (issue #75) — non-blocking, never fatal either.
+    pub fn emit(&self, event: &crate::events::Event) {
+        if let Err(e) = crate::events::append(&self.events_dir(), event) {
+            self.log.verbose(&format!("cannot write event journal: {e:#}"));
+        }
+        // Issue #76: aggregated anonymous counters (no-op while disabled).
+        crate::telemetry::maybe_record(self, event);
+        crate::plugins::dispatch(self, event);
+    }
+
     /// Ask the user for confirmation on stderr. Accepts y/yes/o/oui.
     pub fn confirm(&self, question: &str) -> Result<bool> {
         if self.cli.yes {
@@ -119,6 +174,23 @@ impl App {
     }
 }
 
+/// Resolve the output color theme: the --theme flag wins, then the
+/// configuration entry, then the default theme. An unknown --theme value is
+/// an error; an unknown configured value silently falls back to the default.
+fn resolve_theme(flag: Option<&str>, configured: Option<&str>) -> Result<&'static Theme> {
+    if let Some(name) = flag {
+        return theme::find(name).ok_or_else(|| {
+            anyhow!(
+                "unknown theme '{name}' — available: {}",
+                theme::names().join(", ")
+            )
+        });
+    }
+    Ok(configured
+        .and_then(theme::find)
+        .unwrap_or_else(theme::default_theme))
+}
+
 /// Root directory for agent data (overridable with AGENT_MANAGER_DATA,
 /// mostly used by tests).
 pub fn data_dir() -> PathBuf {

src/ask.rs

@@ -0,0 +1,540 @@
+//! am ask — natural language → am commands (issue #78).
+//!
+//! A local rule-based translator (offline, zero dependency, always works),
+//! an optional LLM refinement through the provider registry (settings.ask),
+//! and a translation cache for offline reuse. Every execution is confirmed
+//! before it runs, and no journal data is ever sent to the provider — only
+//! the user's own query.
+
+use crate::app::App;
+use crate::commands::execute_command;
+use crate::config::AskSettings;
+use crate::secrets::SecretStore;
+use anyhow::{anyhow, Result};
+use clap::Parser;
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeMap;
+use std::path::{Path, PathBuf};
+
+/// System prompt of the refinement call: the model must answer with one am
+/// command per line, nothing else.
+const SYSTEM_PROMPT: &str = "You translate a user request into commands of the 'am' CLI \
+(agent-manager). Reply with ONE 'am' command per line — no text, no backticks, no \
+explanation. Known commands: install, uninstall, update, start, stop, restart, run, \
+list, status, ps, logs, history, stats, top, report, doctor, config, providers, \
+secret, suggest, search, info, open, watch, sync, web, monitor, schedule, ask. \
+Examples: «installe claude et lance-le» -> install claude-code\nstart claude-code ; \
+«qui tourne ?» -> ps.";
+
+const CACHE_MAX_ENTRIES: usize = 200;
+
+// ---------------------------------------------------------------------------
+// Rules (offline, bilingual FR/EN)
+// ---------------------------------------------------------------------------
+
+/// Known agent nicknames resolved before scanning the catalog.
+const NICKNAMES: &[(&str, &str)] = &[
+    ("claude", "claude-code"),
+    ("claude code", "claude-code"),
+    ("codex", "codex"),
+    ("agentty", "agentty"),
+    ("dsh", "deepseek-harness"),
+    ("deepseek", "deepseek-harness"),
+    ("opencode", "opencode"),
+    ("aider", "aider"),
+    ("gptme", "gptme"),
+    ("goose", "goose"),
+    ("openclaw", "openclaw"),
+    ("jcode", "jcode"),
+];
+
+fn agent_of(part: &str, app: &App, prev: Option<&str>) -> Option<String> {
+    // Pronouns reuse the previous agent of the sentence.
+    let p = part.trim().to_lowercase();
+    let pronouns = [
+        "-le", "-la", "-les", "-l", "le", "la", "les", "l'", "it", "him", "her", "them", "celui-ci",
+        "celui la", "celui-là", "the agent", "l'agent",
+    ];
+    if pronouns.iter().any(|pr| p.contains(pr)) {
+        if let Some(prev) = prev {
+            return Some(prev.to_string());
+        }
+    }
+    // Nicknames first (claude before scanning for "claude-code").
+    for (nick, target) in NICKNAMES {
+        if p.contains(nick) {
+            return Some(target.to_string());
+        }
+    }
+    // Exact catalog names, longest first so "claude-code" wins over "claude".
+    let mut names: Vec<&str> = app.config.agents.iter().map(|a| a.name.as_str()).collect();
+    names.sort_by_key(|n| std::cmp::Reverse(n.len()));
+    for name in names {
+        if p.contains(name) {
+            return Some(name.to_string());
+        }
+    }
+    None
+}
+
+fn translate_part(part: &str, app: &App, prev: &mut Option<String>) -> Option<String> {
+    let p = part.trim().to_lowercase();
+    let agent = agent_of(part, app, prev.as_deref()).or_else(|| prev.clone());
+    let needs = |cmd: &str| -> Option<String> {
+        let a = agent.clone().or_else(|| agent_of(part, app, prev.as_deref()));
+        match a {
+            Some(a) => Some(format!("{cmd} {a}")),
+            None => Some(format!("{cmd} --all")), // "tout mettre à jour" etc.
+        }
+    };
+    let cmd = if p.contains("desinstalle") || p.contains("désinstalle")
+        || p.contains("uninstall") || p.contains("supprime")
+    {
+        needs("uninstall")
+    } else if p.contains("mets a jour") || p.contains("mets à jour") || p.contains("maj ")
+        || p.contains("mise a jour") || p.contains("update") || p.contains("upgrade")
+    {
+        if agent.is_some() {
+            needs("update")
+        } else {
+            Some("update --all".to_string())
+        }
+    } else if p.contains("installe") || p.contains("install") || p.contains("setup")
+        || p.contains("instal")
+    {
+        needs("install")
+    } else if p.contains("arrete") || p.contains("arrête") || p.contains("stop")
+        || p.contains("kill") || p.contains("tue") || p.contains("eteins") || p.contains("éteins")
+    {
+        needs("stop")
+    } else if p.contains("relance") || p.contains("redemarre") || p.contains("redémarre")
+        || p.contains("restart") || p.contains("reboot")
+    {
+        needs("restart")
+    } else if p.contains("lance") || p.contains("start") || p.contains("demarre")
+        || p.contains("démarre") || p.contains("ouvre") || p.contains("execute") || p.contains("exécute")
+    {
+        match agent {
+            Some(a) => Some(format!("start {a}")),
+            None => Some("start".to_string()),
+        }
+    } else if p.contains("historique") || p.contains("history") {
+        Some("history".to_string())
+    } else if p.contains("statistique") || p.contains("statistique") || p.contains("stats") {
+        Some("stats".to_string())
+    } else if p.contains("qui tourne") || p.contains("processus") || p.contains("ps ") {
+        Some("ps".to_string())
+    } else if p.contains("sante") || p.contains("santé") || p.contains("doctor")
+        || p.contains("diagnostic") || p.contains("checkup") || p.contains("verifie tout")
+    {
+        Some("doctor".to_string())
+    } else if p.contains("provider") || p.contains("fournisseur") {
+        Some("providers list".to_string())
+    } else if p.contains("secret") {
+        Some("secret list".to_string())
+    } else if p.contains("config") {
+        Some("config show".to_string())
+    } else if p.contains("tout") && p.contains("liste") {
+        Some("list --all".to_string())
+    } else if p.contains("liste") || p.contains("list") || p.contains("lister")
+        || p.contains("catalogue") || p.contains("agents")
+    {
+        Some("list".to_string())
+    } else if p.contains("journal") || p.contains("log") {
+        Some("logs".to_string())
+    } else if p.contains("aide") || p.contains("help") {
+        Some("help".to_string())
+    } else {
+        None
+    };
+    if let Some(c) = &cmd {
+        // Keep the agent context for the following pronouns.
+        if let Some(a) = agent_of(part, app, prev.as_deref()) {
+            *prev = Some(a);
+        }
+    }
+    cmd
+}
+
+/// Rule-based translation of a full query into am commands.
+fn rules_translate(query: &str, app: &App) -> Vec<String> {
+    let mut out: Vec<String> = Vec::new();
+    let mut prev: Option<String> = None;
+    // Sentence separators (FR + EN): each chunk becomes one command.
+    for chunk in query.split(|c| matches!(c, ',' | ';' | '.')) {
+        for part in chunk.splitn(2, |c| c == ':' || c == ';') {
+            let part = part.trim();
+            if part.is_empty() {
+                continue;
+            }
+            // Split on conjunctions, keeping the order.
+            let mut pieces: Vec<String> = Vec::new();
+            let mut current = String::new();
+            for word in part.split_whitespace() {
+                if matches!(
+                    word.to_lowercase().as_str(),
+                    "et" | "puis" | "and" | "then" | "ensuite" | "alors" | "&" | "+"
+                ) {
+                    if !current.trim().is_empty() {
+                        pieces.push(current.trim().to_string());
+                    }
+                    current.clear();
+                } else {
+                    current.push_str(word);
+                    current.push(' ');
+                }
+            }
+            if !current.trim().is_empty() {
+                pieces.push(current.trim().to_string());
+            }
+            for piece in pieces {
+                if let Some(cmd) = translate_part(&piece, app, &mut prev) {
+                    if !out.contains(&cmd) {
+                        out.push(cmd);
+                    }
+                }
+            }
+        }
+    }
+    out
+}
+
+// ---------------------------------------------------------------------------
+// Optional LLM refinement (issue #78) — via the provider registry (#88)
+// ---------------------------------------------------------------------------
+
+/// ask is enabled by default (local rules work out of the box, issue #78);
+/// an explicit `ask.enabled: false` turns the whole command off.
+fn ask_enabled(app: &App) -> bool {
+    app.config
+        .settings
+        .ask
+        .as_ref()
+        .map(|a| a.enabled)
+        .unwrap_or(true)
+}
+
+/// The optional LLM refinement settings: (provider, model), both None when
+/// no provider is configured (rules-only mode).
+fn ask_settings(app: &App) -> Option<(Option<&str>, Option<&str>)> {
+    if !ask_enabled(app) {
+        return None;
+    }
+    let a = app.config.settings.ask.as_ref();
+    Some((
+        a.and_then(|x| x.provider.as_deref()).filter(|p| !p.is_empty()),
+        a.and_then(|x| x.model.as_deref()).filter(|m| !m.is_empty()),
+    ))
+}
+
+fn is_known_command(first_word: &str) -> bool {
+    matches!(
+        first_word,
+        "install" | "uninstall" | "update" | "start" | "stop" | "restart" | "run"
+            | "list" | "status" | "ps" | "logs" | "history" | "stats" | "top"
+            | "report" | "doctor" | "config" | "providers" | "secret" | "suggest"
+            | "search" | "info" | "open" | "watch" | "sync" | "web" | "monitor"
+            | "schedule" | "ask" | "lab" | "playbook"
+    )
+}
+
+/// Ask the provider registry to translate the query. Returns None when no
+/// provider is configured (rules-only mode). Only the user's query is sent —
+/// never journal data.
+fn llm_translate(app: &App, query: &str) -> Result<Option<Vec<String>>> {
+    let Some((provider, model)) = ask_settings(app) else {
+        return Ok(None);
+    };
+    let provider_name = provider.or_else(|| crate::providers::default_name(&app.config));
+    let Some(provider_name) = provider_name else {
+        return Ok(None);
+    };
+    let Some(def) = crate::providers::get(&app.config, provider_name) else {
+        return Ok(None);
+    };
+    let model = model.or(def.default_model.as_deref());
+    let Some(model) = model else {
+        return Ok(None);
+    };
+    let token = crate::secrets::store()
+        .get(&crate::secrets::key_for_provider_token(provider_name))
+        .ok()
+        .flatten();
+    let endpoint = format!("{}/chat/completions", def.base_url.trim_end_matches('/'));
+    let body = serde_json::json!({
+        "model": model,
+        "temperature": 0,
+        "max_tokens": 256,
+        "messages": [
+            {"role": "system", "content": SYSTEM_PROMPT},
+            {"role": "user", "content": query},
+        ],
+    });
+    let mut req = ureq::post(&endpoint)
+        .set("Content-Type", "application/json")
+        .timeout(std::time::Duration::from_secs(20));
+    if let Some(t) = &token {
+        req = req.set("Authorization", &format!("Bearer {t}"));
+    }
+    let resp = req
+        .send_string(&body.to_string())
+        .map_err(|e| anyhow!("{e}"))?;
+    let json: serde_json::Value = serde_json::from_reader(resp.into_reader())?;
+    let content = json
+        .pointer("/choices/0/message/content")
+        .and_then(|c| c.as_str())
+        .ok_or_else(|| anyhow!("réponse du fournisseur illisible"))?;
+    let commands: Vec<String> = content
+        .lines()
+        .map(|l| l.trim().trim_start_matches("am ").trim().to_string())
+        .filter(|l| !l.is_empty())
+        .filter(|l| {
+            let first = l.split_whitespace().next().unwrap_or("");
+            is_known_command(first)
+        })
+        .collect();
+    if commands.is_empty() {
+        anyhow::bail!("le fournisseur n'a produit aucune commande valide");
+    }
+    Ok(Some(commands))
+}
+
+// ---------------------------------------------------------------------------
+// Cache (offline reuse, issue #78)
+// ---------------------------------------------------------------------------
+
+#[derive(Debug, Default, Serialize, Deserialize)]
+struct AskCache {
+    entries: BTreeMap<String, Vec<String>>,
+}
+
+fn cache_path(app: &App) -> PathBuf {
+    app.paths
+        .state_file
+        .parent()
+        .unwrap_or(Path::new("."))
+        .join("ask_cache.json")
+}
+
+fn cache_load(app: &App) -> AskCache {
+    std::fs::read_to_string(cache_path(app))
+        .ok()
+        .and_then(|t| serde_json::from_str(&t).ok())
+        .unwrap_or_default()
+}
+
+fn cache_save(app: &App, cache: &AskCache) {
+    if let Ok(json) = serde_json::to_string_pretty(cache) {
+        let _ = std::fs::write(cache_path(app), json);
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/// Translate a natural-language query into am commands (rules first, then
+/// the optional LLM, both cached for offline reuse).
+pub fn translate(app: &App, query: &str) -> Result<Vec<String>> {
+    let key = query.trim().to_lowercase();
+    if key.is_empty() {
+        anyhow::bail!("usage: am ask <demande en langage naturel>");
+    }
+    // 1. Cache hit — works offline, even after a previous LLM translation.
+    let mut cache = cache_load(app);
+    if let Some(hit) = cache.entries.get(&key) {
+        return Ok(hit.clone());
+    }
+    // 2. Local rules (zero dependency).
+    let rules = rules_translate(query, app);
+    if !rules.is_empty() {
+        cache.entries.insert(key.clone(), rules.clone());
+        cache_save(app, &cache);
+        return Ok(rules);
+    }
+    // 3. Optional LLM refinement through the provider registry. Failures
+    // (no token, provider unreachable, malformed answer) degrade to the
+    // rules-only result instead of blocking the command.
+    match llm_translate(app, query) {
+        Ok(Some(llm)) => {
+            cache.entries.insert(key.clone(), llm.clone());
+            cache_save(app, &cache);
+            return Ok(llm);
+        }
+        Ok(None) => {}
+        Err(e) => {
+            app.log
+                .verbose(&format!("ask LLM refinement skipped: {e:#}"));
+        }
+    }
+    Ok(Vec::new())
+}
+
+/// am ask entry point: translate, show, confirm, execute.
+pub fn run(app: &App, query: &str, yes: bool) -> Result<i32> {
+    if !ask_enabled(app) {
+        app.log.error(crate::i18n::tr(
+            "am ask est désactivé — settings.ask.enabled: true pour l'activer",
+        ));
+        return Ok(1);
+    }
+    let commands = translate(app, query)?;
+    if commands.is_empty() {
+        app.log.info(crate::i18n::tr(
+            "je n'ai pas compris — exemples: «installe claude et lance-le», «liste les agents», «arrête codex»",
+        ));
+        return Ok(0);
+    }
+    for c in &commands {
+        println!("  am {c}");
+    }
+    if !yes && !app.confirm(&crate::i18n::tr("exécuter ces commandes ?"))? {
+        app.log.info(crate::i18n::tr("annulé"));
+        return Ok(0);
+    }
+    for c in &commands {
+        let tokens = shell_words::split(c)?;
+        let mut argv = vec!["am".to_string()];
+        argv.extend(tokens);
+        let cli = crate::cli::Cli::parse_from(argv);
+        let Some(cmd) = cli.command else {
+            continue;
+        };
+        let code = execute_command(app, &cmd)?;
+        if code != 0 {
+            return Ok(code);
+        }
+    }
+    Ok(0)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::app::App;
+    use clap::Parser;
+
+    fn test_app(ask_yaml: &str) -> App {
+        let guard = tempfile::tempdir().unwrap();
+        let dir = guard.path().to_path_buf();
+        std::mem::forget(guard);
+        let cfg = dir.join("config.yaml");
+        std::fs::write(
+            &cfg,
+            format!(
+                "version: \"1.0\"\nsettings:\n  auto_install_deps: false\n  confirm_before_run: false\n{ask_yaml}agents: []\n"
+            ),
+        )
+        .unwrap();
+        let cli = crate::cli::Cli::parse_from(["am", "--config", cfg.to_str().unwrap()]);
+        let mut app = crate::app::App::from_cli(cli).unwrap();
+        let mut p = app.paths.clone();
+        p.state_file = dir.join("state.json");
+        app.paths = p;
+        app
+    }
+
+    #[test]
+    fn rules_install_and_launch_claude() {
+        let app = test_app("");
+        let cmds = translate(&app, "installe claude et lance-le").unwrap();
+        assert_eq!(cmds, vec!["install claude-code", "start claude-code"]);
+    }
+
+    #[test]
+    fn rules_cover_common_requests() {
+        let app = test_app("");
+        assert_eq!(translate(&app, "liste les agents").unwrap(), vec!["list"]);
+        assert_eq!(translate(&app, "arrête codex").unwrap(), vec!["stop codex"]);
+        assert_eq!(
+            translate(&app, "mets à jour tout").unwrap(),
+            vec!["update --all"]
+        );
+        assert_eq!(translate(&app, "qui tourne ?").unwrap(), vec!["ps"]);
+        assert_eq!(
+            translate(&app, "installe deepseek-harness").unwrap(),
+            vec!["install deepseek-harness"]
+        );
+    }
+
+    #[test]
+    fn rules_unknown_query_is_empty() {
+        let app = test_app("");
+        assert!(translate(&app, "quelle est la météo demain ?").unwrap().is_empty());
+    }
+
+    #[test]
+    fn cache_reuses_translations_offline() {
+        let app = test_app("");
+        let cmds = translate(&app, "installe claude et lance-le").unwrap();
+        assert_eq!(cmds.len(), 2);
+        // Second pass: served from the cache file (rules are deterministic,
+        // but the cache also carries previous LLM translations offline).
+        let cache = cache_load(&app);
+        assert!(cache.entries.contains_key("installe claude et lance-le"));
+    }
+
+    #[test]
+    fn llm_refinement_uses_the_registry_and_never_sends_journal_data() {
+        let server = tiny_http::Server::http("127.0.0.1:0").unwrap();
+        let port = server.server_addr().to_ip().unwrap().port();
+        let app = test_app(&format!(
+            "  default_provider: openai\n  ask:\n    enabled: true\n    provider: openai\n  providers:\n    openai:\n      base_url: http://127.0.0.1:{port}\n      default_model: gpt-5.2\n"
+        ));
+        // Store a fake token in the keyring namespace of the provider.
+        let store = crate::secrets::store();
+        let key = crate::secrets::key_for_provider_token("openai");
+        store.set(&key, "sk-test-token").unwrap();
+        let handle = std::thread::spawn(move || {
+            let mut req = server
+                .recv_timeout(std::time::Duration::from_secs(10))
+                .expect("server recv failed")
+                .expect("the ask call must reach the provider");
+            assert_eq!(req.url(), "/chat/completions");
+            let mut body = String::new();
+            req.as_reader().read_to_string(&mut body).unwrap();
+            let json: serde_json::Value = serde_json::from_str(&body).unwrap();
+            assert_eq!(json["model"], "gpt-5.2");
+            assert_eq!(json["temperature"], 0);
+            let user_msg = json["messages"]
+                .as_array()
+                .unwrap()
+                .iter()
+                .find(|m| m["role"] == "user")
+                .unwrap()["content"]
+                .as_str()
+                .unwrap()
+                .to_string();
+            let auth = req.headers().iter().find(|h| h.field.equiv("Authorization")).map(|h| h.value.as_str().to_string());
+            let _ = req.respond(tiny_http::Response::from_string(
+                r#"{"choices":[{"message":{"content":"install claude-code\nstart claude-code"}}]}"#,
+            ));
+            (user_msg, auth)
+        });
+        // The rules do NOT cover this query — the LLM refinement is reached.
+        let cmds = translate(&app, "donne-moi un rapport de la semaine").unwrap();
+        assert_eq!(cmds, vec!["install claude-code", "start claude-code"]);
+        let (user_msg, auth) = handle.join().unwrap();
+        // The provider receives the query and the keyring token — nothing else.
+        assert_eq!(user_msg, "donne-moi un rapport de la semaine");
+        assert_eq!(auth.as_deref(), Some("Bearer sk-test-token"));
+        store.remove(&key).unwrap();
+    }
+
+    #[test]
+    fn llm_failure_degrades_to_rules_only() {
+        // No provider configured explicitly: the embedded default (anthropic)
+        // would 401 without a token — translate() must degrade silently to
+        // the rules-only result instead of blocking.
+        let app = test_app("");
+        let cmds = translate(&app, "une requête hors règles").unwrap();
+        assert!(cmds.is_empty());
+    }
+
+    #[test]
+    fn disabled_ask_is_refused() {
+        let app = test_app("  ask:\n    enabled: false\n");
+        // run() reports the refusal with exit code 1 (not an error).
+        assert_eq!(run(&app, "installe claude", true).unwrap(), 1);
+    }
+}

src/automation.rs

@@ -0,0 +1,438 @@
+//! Automation helpers (axe 6): system service units, scheduled tasks,
+//! container commands and health checks. Pure functions here are unit
+//! tested; the thin command layers live in commands/service_cmd.rs,
+//! commands/schedule_cmd.rs, run_cmd.rs and doctor_cmd.rs.
+
+use crate::config::{ContainerSpec, HealthCheck};
+use anyhow::{bail, Result};
+use std::collections::BTreeMap;
+use std::net::TcpStream;
+use std::path::{Path, PathBuf};
+use std::process::Command;
+
+/// Am binary path used inside generated units/tasks (quoted).
+pub fn am_bin_quoted() -> String {
+    let exe = std::env::current_exe()
+        .map(|p| p.to_string_lossy().to_string())
+        .unwrap_or_else(|_| "am".to_string());
+    shell_escape(&exe)
+}
+
+fn shell_escape(s: &str) -> String {
+    if cfg!(windows) {
+        format!("\"{}\"", s.replace('"', "\\\""))
+    } else {
+        format!("'{}'", s.replace('\'', "'\\''"))
+    }
+}
+
+// ---------------------------------------------------------------------------
+// #55: system service units
+// ---------------------------------------------------------------------------
+
+/// systemd user unit for 'am service install <agent> --autostart'.
+pub fn systemd_unit(agent: &str, am_bin: &str) -> String {
+    format!(
+        "# Generated by 'am service install {agent}' — managed by agent-manager\n\
+         [Unit]\n\
+         Description=agent-manager: {agent}\n\
+         After=network-online.target\n\
+         Wants=network-online.target\n\
+         \n\
+         [Service]\n\
+         Type=simple\n\
+         ExecStart={am_bin} start {agent} --background --notify\n\
+         Restart=on-failure\n\
+         RestartSec=10\n\
+         \n\
+         [Install]\n\
+         WantedBy=default.target\n"
+    )
+}
+
+/// launchd plist for macOS.
+pub fn launchd_plist(agent: &str, am_bin: &str) -> String {
+    format!(
+        "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n\
+         <!DOCTYPE plist PUBLIC \"-//Apple//DTD PLIST 1.0//EN\" \"http://www.apple.com/DTDs/PropertyList-1.0.dtd\">\n\
+         <plist version=\"1.0\">\n\
+         <dict>\n\
+         \t<key>Label</key>\n\
+         \t<string>com.agent-manager.{agent}</string>\n\
+         \t<key>ProgramArguments</key>\n\
+         \t<array>\n\
+         \t\t<string>{am_bin}</string>\n\
+         \t\t<string>start</string>\n\
+         \t\t<string>{agent}</string>\n\
+         \t\t<string>--background</string>\n\
+         \t\t<string>--notify</string>\n\
+         \t</array>\n\
+         \t<key>RunAtLoad</key>\n\
+         \t<true/>\n\
+         \t<key>KeepAlive</key>\n\
+         \t<true/>\n\
+         </dict>\n\
+         </plist>\n"
+    )
+}
+
+/// Windows scheduled task XML (on logon, with retry).
+pub fn windows_task_xml(agent: &str, am_bin: &str) -> String {
+    format!(
+        "<?xml version=\"1.0\" encoding=\"UTF-16\"?>\n\
+         <Task version=\"1.2\" xmlns=\"http://schemas.microsoft.com/windows/2004/02/mit/task\">\n\
+         \t<Triggers><LogonTrigger><Enabled>true</Enabled></LogonTrigger></Triggers>\n\
+         \t<Principals><Principal id=\"Author\"><LogonType>InteractiveToken</LogonType>\n\
+         \t<RunLevel>LeastPrivilege</RunLevel></Principal></Principals>\n\
+         \t<Settings><MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>\n\
+         \t<DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>\n\
+         \t<StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>\n\
+         \t<RestartOnFailure><Interval>PT1M</Interval><Count>3</Count></RestartOnFailure>\n\
+         \t</Settings>\n\
+         \t<Actions><Exec>\n\
+         \t<Command>{am_bin}</Command>\n\
+         \t<Arguments>start {agent} --background --notify</Arguments>\n\
+         \t</Exec></Actions>\n\
+         </Task>\n"
+    )
+}
+
+/// Path of the systemd user unit for an agent.
+pub fn systemd_unit_path(agent: &str) -> PathBuf {
+    let base = std::env::var("XDG_CONFIG_HOME")
+        .map(PathBuf::from)
+        .unwrap_or_else(|_| {
+            crate::config::home_dir()
+                .map(|h| h.join(".config"))
+                .unwrap_or_else(|| PathBuf::from(".config"))
+        });
+    base.join("systemd").join("user").join(format!("am-{agent}.service"))
+}
+
+/// Path of the launchd plist for an agent.
+pub fn launchd_path(agent: &str) -> PathBuf {
+    crate::config::home_dir()
+        .map(|h| h.join("Library/LaunchAgents"))
+        .unwrap_or_else(|| PathBuf::from("."))
+        .join(format!("com.agent-manager.{agent}.plist"))
+}
+
+/// Windows task name for an agent.
+pub fn windows_task_name(agent: &str) -> String {
+    format!("am-{agent}")
+}
+
+// ---------------------------------------------------------------------------
+// #56: scheduled tasks
+// ---------------------------------------------------------------------------
+
+/// HH:MM at which a "daily" schedule runs (default 08:00). Parsed leniently.
+pub fn parse_hhmm(at: &str) -> (u8, u8) {
+    let parts: Vec<&str> = at.split(':').collect();
+    let h: u8 = parts.first().and_then(|p| p.parse().ok()).unwrap_or(8);
+    let m: u8 = parts.get(1).and_then(|p| p.parse().ok()).unwrap_or(0);
+    (h.min(23), m.min(59))
+}
+
+/// Crontab line for a daily schedule (Linux/macOS).
+pub fn crontab_line(at: &str, am_bin: &str, schedule_id: &str) -> String {
+    let (h, m) = parse_hhmm(at);
+    format!("{m} {h} * * * {am_bin} schedule-run {schedule_id}")
+}
+
+/// schtasks command registering a daily task (Windows).
+pub fn schtasks_daily(at: &str, am_bin: &str, schedule_id: &str, task_name: &str) -> Command {
+    let (h, m) = parse_hhmm(at);
+    let mut c = Command::new("schtasks");
+    c.args([
+        "/create",
+        "/tn",
+        task_name,
+        "/sc",
+        "daily",
+        "/st",
+        &format!("{h:02}:{m:02}"),
+        "/tr",
+        &format!("\"{am_bin}\" schedule-run {schedule_id}"),
+        "/f",
+    ]);
+    c
+}
+
+/// The command that actually runs a schedule: am schedule-run <id>.
+pub fn schedule_run_command(app: &crate::app::App, entry: &crate::state::ScheduleEntry) -> Result<i32> {
+    // Re-dispatch through the CLI so hooks/events/state stay consistent.
+    let args: Vec<String> = entry
+        .command
+        .iter()
+        .map(|s| s.to_string())
+        .collect();
+    let mut full = vec!["am".to_string()];
+    if let Some(cfg) = &app.config_origin {
+        full.push("--config".to_string());
+        full.push(cfg.to_string_lossy().to_string());
+    }
+    full.extend(args);
+    let status = Command::new(std::env::current_exe()?)
+        .args(&full[1..])
+        .status()?;
+    Ok(status.code().unwrap_or(1))
+}
+
+// ---------------------------------------------------------------------------
+// #57: health checks
+// ---------------------------------------------------------------------------
+
+/// Wait for an agent health check (issue #57). Returns Ok when the check
+/// passes within the timeout, Err otherwise. Never probes when the agent
+/// has no healthcheck configured.
+pub fn wait_health(agent: &str, hc: Option<&HealthCheck>, log: &crate::output::Logger) -> Result<()> {
+    let Some(hc) = hc else {
+        return Ok(());
+    };
+    let timeout = hc.timeout_secs.unwrap_or(30).max(1);
+    let deadline = std::time::Instant::now() + std::time::Duration::from_secs(timeout);
+    let mut attempt = 0;
+    loop {
+        attempt += 1;
+        let ok = healthcheck_once(hc);
+        if ok {
+            return Ok(());
+        }
+        if std::time::Instant::now() >= deadline {
+            bail!(
+                "health check for '{agent}' failed after {timeout}s \
+                 (command: {}, port: {})",
+                hc.command.as_deref().unwrap_or("-"),
+                hc.port.map(|p| p.to_string()).unwrap_or_else(|| "-".to_string())
+            );
+        }
+        if attempt == 1 || attempt % 5 == 0 {
+            log.verbose(&format!(
+                "waiting for '{agent}' health (attempt {attempt})..."
+            ));
+        }
+        std::thread::sleep(std::time::Duration::from_secs(2));
+    }
+}
+
+/// One health check probe: command exit 0, or TCP connect on the port.
+pub fn healthcheck_once(hc: &HealthCheck) -> bool {
+    if let Some(cmd) = &hc.command {
+        let ok = Command::new("sh")
+            .arg("-c")
+            .arg(cmd)
+            .stdout(std::process::Stdio::null())
+            .stderr(std::process::Stdio::null())
+            .status()
+            .map(|s| s.success())
+            .unwrap_or(false);
+        if !ok {
+            return false;
+        }
+    }
+    if let Some(port) = hc.port {
+        if TcpStream::connect(("127.0.0.1", port)).is_err() {
+            return false;
+        }
+    }
+    true
+}
+
+// ---------------------------------------------------------------------------
+// #58: container profiles
+// ---------------------------------------------------------------------------
+
+/// Detect a container runtime: podman preferred, docker fallback.
+pub fn detect_runtime() -> Option<String> {
+    for bin in ["podman", "docker"] {
+        if Command::new(bin)
+            .arg("--version")
+            .stdout(std::process::Stdio::null())
+            .stderr(std::process::Stdio::null())
+            .status()
+            .map(|s| s.success())
+            .unwrap_or(false)
+        {
+            return Some(bin.to_string());
+        }
+    }
+    None
+}
+
+/// Build the container run command for an agent (issue #58): mounts the
+/// state dir and log dir, applies the profile volumes/network/env, runs
+/// the agent's run command in the image.
+pub fn container_command(
+    runtime: &str,
+    agent: &str,
+    spec: &ContainerSpec,
+    state_dir: &Path,
+    log_dir: &Path,
+) -> Result<Vec<String>> {
+    if spec.image.trim().is_empty() {
+        bail!("agent '{agent}': container profile requires an 'image'");
+    }
+    let mut cmd = vec![
+        runtime.to_string(),
+        "run".to_string(),
+        "-d".to_string(),
+        "--name".to_string(),
+        format!("am-{agent}"),
+    ];
+    // State + logs mounts so sessions/history keep working.
+    cmd.push("-v".to_string());
+    cmd.push(format!("{}:/data", state_dir.to_string_lossy()));
+    cmd.push("-v".to_string());
+    cmd.push(format!("{}:/logs", log_dir.to_string_lossy()));
+    for v in &spec.volumes {
+        cmd.push("-v".to_string());
+        cmd.push(v.clone());
+    }
+    match &spec.network {
+        Some(n) => {
+            cmd.push("--network".to_string());
+            cmd.push(n.clone());
+        }
+        None => {
+            cmd.push("--network".to_string());
+            cmd.push(
+                if cfg!(target_os = "linux") {
+                    "host".to_string()
+                } else {
+                    "bridge".to_string()
+                },
+            );
+        }
+    }
+    for (k, v) in &spec.env {
+        cmd.push("-e".to_string());
+        cmd.push(format!("{k}={v}"));
+    }
+    cmd.push(spec.image.clone());
+    Ok(cmd)
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn systemd_unit_is_valid_and_referenced() {
+        let unit = systemd_unit("claude-code", "/usr/local/bin/am");
+        assert!(unit.contains("[Unit]"));
+        assert!(unit.contains("ExecStart=/usr/local/bin/am start claude-code --background --notify"));
+        assert!(unit.contains("Restart=on-failure"));
+        assert!(unit.contains("[Install]"));
+    }
+
+    #[test]
+    fn launchd_plist_is_valid_xml_shape() {
+        let plist = launchd_plist("aider", "/opt/homebrew/bin/am");
+        assert!(plist.contains("com.agent-manager.aider"));
+        assert!(plist.contains("<string>/opt/homebrew/bin/am</string>"));
+        assert!(plist.contains("<key>RunAtLoad</key>"));
+    }
+
+    #[test]
+    fn windows_task_xml_has_action() {
+        let xml = windows_task_xml("codex", "C:\\bin\\am.exe");
+        assert!(xml.contains("LogonTrigger"));
+        assert!(xml.contains("am.exe"));
+        assert!(xml.contains("start codex --background --notify"));
+        assert!(xml.contains("RestartOnFailure"));
+    }
+
+    #[test]
+    fn crontab_line_formats_time_and_id() {
+        let line = crontab_line("22:05", "/usr/bin/am", "sched-1");
+        assert_eq!(line, "5 22 * * * /usr/bin/am schedule-run sched-1");
+        let line = crontab_line("", "/usr/bin/am", "sched-2");
+        assert_eq!(line, "0 8 * * * /usr/bin/am schedule-run sched-2");
+    }
+
+    #[test]
+    fn parse_hhmm_is_lenient() {
+        assert_eq!(parse_hhmm("09:30"), (9, 30));
+        assert_eq!(parse_hhmm("garbage"), (8, 0));
+        assert_eq!(parse_hhmm("25:99"), (23, 59));
+    }
+
+    #[test]
+    fn healthcheck_command_exit_0_is_healthy() {
+        let hc = HealthCheck {
+            command: Some("true".to_string()),
+            port: None,
+            timeout_secs: Some(5),
+        };
+        assert!(healthcheck_once(&hc));
+        let bad = HealthCheck {
+            command: Some("false".to_string()),
+            port: None,
+            timeout_secs: Some(5),
+        };
+        assert!(!healthcheck_once(&bad));
+    }
+
+    #[test]
+    fn healthcheck_without_config_skips() {
+        let app = test_app();
+        assert!(wait_health("x", None, &app.log).is_ok());
+    }
+
+    fn test_app() -> crate::app::App {
+        let dir = tempfile::tempdir().unwrap();
+        let cfg = dir.path().join("config.yaml");
+        std::fs::write(
+            &cfg,
+            concat!(
+                "version: \"1.0\"\n",
+                "settings:\n",
+                "  auto_install_deps: false\n",
+                "  confirm_before_run: false\n",
+                "agents: []\n",
+            ),
+        )
+        .unwrap();
+        use clap::Parser;
+        let cli = crate::cli::Cli::parse_from(["am", "--config", cfg.to_str().unwrap()]);
+        let mut app = crate::app::App::from_cli(cli).unwrap();
+        app.paths.state_file = dir.path().join("state.json");
+        app.state = crate::state::StateStore::new(dir.path().join("state.json"));
+        app
+    }
+
+    #[test]
+    fn container_command_mounts_and_env() {
+        let spec = ContainerSpec {
+            image: "node:20".to_string(),
+            volumes: vec!["/host/work:/work:ro".to_string()],
+            network: None,
+            env: BTreeMap::from([("NODE_ENV".to_string(), "production".to_string())]),
+        };
+        let cmd = container_command(
+            "docker",
+            "my-agent",
+            &spec,
+            Path::new("/state"),
+            Path::new("/logs"),
+        )
+        .unwrap();
+        assert_eq!(cmd[0], "docker");
+        assert!(cmd.contains(&"run".to_string()));
+        assert!(cmd.contains(&"-v".to_string()));
+        assert!(cmd.contains(&"/state:/data".to_string()));
+        assert!(cmd.contains(&"/logs:/logs".to_string()));
+        assert!(cmd.contains(&"--network".to_string()));
+        assert!(cmd.contains(&"-e".to_string()));
+        assert!(cmd.contains(&"NODE_ENV=production".to_string()));
+        assert_eq!(cmd.last().unwrap(), "node:20");
+        // Empty image fails clearly.
+        let bad = ContainerSpec { image: String::new(), ..Default::default() };
+        assert!(container_command("docker", "a", &bad, Path::new("/s"), Path::new("/l")).is_err());
+    }
+}

src/backup.rs

@@ -0,0 +1,426 @@
+//! Pre-update backups (issue #64, axe 8): a snapshot of the install
+//! directory, the state database and the user config is taken before every
+//! real update, kept under <state>/backups/<timestamp>/, and restored by
+//! 'am update --rollback <point>'. Retention is bounded by
+//! settings.backups_keep (default 5).
+
+use crate::app::App;
+use anyhow::{anyhow, bail, Context, Result};
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeMap;
+use std::path::{Path, PathBuf};
+
+/// Default number of backups to keep (settings.backups_keep default).
+pub const DEFAULT_KEEP: u32 = 5;
+
+/// Manifest of one backup point (JSON file inside the backup directory).
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct BackupInfo {
+    /// Backup id = the directory name (RFC 3339 timestamp).
+    pub id: String,
+    /// RFC 3339 creation timestamp.
+    pub created_at: String,
+    /// Reason: "update:<agent>" or "update:--all".
+    pub reason: String,
+    /// Agents whose install directories were snapshotted (empty = all).
+    pub agents: Vec<String>,
+    /// True when the state database was snapshotted.
+    pub state: bool,
+    /// True when the user config file was snapshotted.
+    pub config: bool,
+}
+
+impl BackupInfo {
+    /// Load the manifest of one backup directory.
+    fn load(dir: &Path) -> Option<BackupInfo> {
+        let text = std::fs::read_to_string(dir.join("manifest.json")).ok()?;
+        serde_json::from_str(&text).ok()
+    }
+}
+
+/// Directory holding every backup point. Lives next to the state database
+/// so tests and --config overrides stay fully sandboxed.
+pub fn backups_dir(app: &App) -> PathBuf {
+    app.paths
+        .state_file
+        .parent()
+        .unwrap_or_else(|| std::path::Path::new("."))
+        .join("backups")
+}
+
+/// Take a snapshot before an update. `agents` lists the agents being
+/// updated; an empty list means "the whole install directory".
+pub fn create_backup(app: &App, reason: &str, agents: &[String]) -> Result<BackupInfo> {
+    let now = crate::installers::now_rfc3339();
+    // Directory names must be sortable and filesystem-safe: the RFC 3339
+    // timestamp with colons replaced by dashes.
+    let id = now.replace(':', "-").replace('Z', "").replace('+', "_");
+    let root = backups_dir(app).join(&id);
+    std::fs::create_dir_all(&root)
+        .with_context(|| format!("cannot create backup directory {}", root.display()))?;
+
+    let mut info = BackupInfo {
+        id: id.clone(),
+        created_at: now,
+        reason: reason.to_string(),
+        agents: agents.to_vec(),
+        state: false,
+        config: false,
+    };
+
+    // 1. State database.
+    if let Ok(sf) = app.state.load() {
+        let text = serde_json::to_string_pretty(&sf)?;
+        std::fs::write(root.join("state.json"), text)
+            .with_context(|| "cannot snapshot state.json".to_string())?;
+        info.state = true;
+    }
+
+    // 2. User config file (the active origin when it is a user file).
+    if let Some(origin) = &app.config_origin {
+        if origin.is_file() {
+            std::fs::copy(origin, root.join("config.yaml")).with_context(|| {
+                format!("cannot snapshot user config {}", origin.display())
+            })?;
+            info.config = true;
+        }
+    }
+
+    // 3. Install directories of the updated agents (or everything).
+    let install_root = &app.paths.install_dir;
+    let dest_root = root.join("install");
+    std::fs::create_dir_all(&dest_root)?;
+    if agents.is_empty() {
+        copy_tree(install_root, &dest_root)
+            .with_context(|| format!("cannot snapshot {}", install_root.display()))?;
+    } else {
+        for name in agents {
+            let entry = app.state.get(name).ok().flatten();
+            if let Some(e) = entry {
+                let src = PathBuf::from(&e.install_dir);
+                if src.is_dir() {
+                    let dest = dest_root.join(&e.name);
+                    copy_tree(&src, &dest).with_context(|| {
+                        format!("cannot snapshot {} for {name}", src.display())
+                    })?;
+                }
+            }
+            // Also snapshot the shim binaries (bin/<name>).
+            let shim = app.paths.bin_dir.join(name);
+            if shim.exists() {
+                copy_tree(&shim, &dest_root.join("bin").join(name))?;
+            }
+        }
+    }
+
+    // Write the manifest last: a backup without a manifest is invalid.
+    let manifest = serde_json::to_string_pretty(&info)?;
+    std::fs::write(root.join("manifest.json"), manifest)
+        .with_context(|| "cannot write backup manifest".to_string())?;
+
+    prune(app)?;
+    Ok(info)
+}
+
+/// List every backup point, oldest first.
+pub fn list_backups(app: &App) -> Vec<BackupInfo> {
+    let mut out: Vec<BackupInfo> = Vec::new();
+    if let Ok(entries) = std::fs::read_dir(backups_dir(app)) {
+        for entry in entries.flatten() {
+            let path = entry.path();
+            if path.is_dir() {
+                if let Some(info) = BackupInfo::load(&path) {
+                    out.push(info);
+                }
+            }
+        }
+    }
+    out.sort_by(|a, b| a.id.cmp(&b.id));
+    out
+}
+
+/// Resolve a rollback point: "latest"/empty = most recent backup,
+/// otherwise the backup id (prefix matching allowed).
+pub fn resolve_point(app: &App, point: Option<&str>) -> Result<BackupInfo> {
+    let all = list_backups(app);
+    if all.is_empty() {
+        bail!("no backup found — nothing to roll back to");
+    }
+    match point {
+        None | Some("latest") => all
+            .last()
+            .cloned()
+            .ok_or_else(|| anyhow!("no backup found")),
+        Some(p) => {
+            let exact = all.iter().find(|b| b.id == p);
+            if let Some(b) = exact {
+                return Ok(b.clone());
+            }
+            let prefix: Vec<BackupInfo> = all
+                .iter()
+                .filter(|b| b.id.starts_with(p))
+                .cloned()
+                .collect();
+            match prefix.len() {
+                0 => bail!("backup '{p}' not found — run 'am update --rollback --list'"),
+                1 => Ok(prefix[0].clone()),
+                _ => bail!(
+                    "backup prefix '{p}' is ambiguous ({} matches: {})",
+                    prefix.len(),
+                    prefix
+                        .iter()
+                        .map(|b| b.id.as_str())
+                        .collect::<Vec<_>>()
+                        .join(", ")
+                ),
+            }
+        }
+    }
+}
+
+/// Restore a backup point over the live install: state, user config and
+/// install directories. The agent processes of the restored agents are
+/// stopped first (they would hold the old binaries open).
+pub fn restore_backup(app: &App, point: Option<&str>) -> Result<BackupInfo> {
+    let info = resolve_point(app, point)?;
+    let root = backups_dir(app).join(&info.id);
+    if !root.join("manifest.json").is_file() {
+        bail!("backup {} is corrupted (no manifest)", info.id);
+    }
+
+    // Stop the agents being restored (only managed ones we know).
+    let names: Vec<String> = if info.agents.is_empty() {
+        app.state
+            .all()?
+            .keys()
+            .cloned()
+            .collect()
+    } else {
+        info.agents.clone()
+    };
+    for name in &names {
+        if let Ok(Some(entry)) = app.state.get(name) {
+            if let Some(pid) = entry.pid {
+                if crate::process::is_running(pid) {
+                    app.log
+                        .info(&format!("stopping {name} (pid {pid}) before rollback"));
+                    let _ = crate::commands::run_cmd::stop(app, name, false, None);
+                }
+            }
+        }
+    }
+
+    // 1. Restore the state database.
+    if info.state {
+        let src = root.join("state.json");
+        if src.is_file() {
+            std::fs::copy(&src, app.state.path())
+                .with_context(|| "cannot restore state.json".to_string())?;
+        }
+    }
+
+    // 2. Restore the user config.
+    if info.config {
+        if let Some(origin) = &app.config_origin {
+            if let Some(parent) = origin.parent() {
+                std::fs::create_dir_all(parent)?;
+            }
+            std::fs::copy(root.join("config.yaml"), origin)
+                .with_context(|| format!("cannot restore {}", origin.display()))?;
+        }
+    }
+
+    // 3. Restore the install directories.
+    let src_root = root.join("install");
+    if src_root.is_dir() {
+        if info.agents.is_empty() {
+            if app.paths.install_dir.exists() {
+                std::fs::remove_dir_all(&app.paths.install_dir)
+                    .with_context(|| "cannot clear the install directory".to_string())?;
+            }
+            copy_tree(&src_root, &app.paths.install_dir)?;
+        } else {
+            for name in &info.agents {
+                let src = src_root.join(name);
+                if !src.exists() {
+                    continue;
+                }
+                // Remove the agent's current install dir (known from the
+                // restored state) and copy the snapshot back.
+                if let Ok(Some(entry)) = app.state.get(name) {
+                    let cur = PathBuf::from(&entry.install_dir);
+                    if cur.is_dir() {
+                        let _ = std::fs::remove_dir_all(&cur);
+                    }
+                }
+                let dest = app.paths.install_dir.join(name);
+                copy_tree(&src, &dest)?;
+            }
+            // Restore the shims.
+            let bin_src = src_root.join("bin");
+            if bin_src.is_dir() {
+                copy_tree(&bin_src, &app.paths.bin_dir)?;
+            }
+        }
+    }
+
+    Ok(info)
+}
+
+/// Enforce settings.backups_keep: delete the oldest backups beyond the cap.
+pub fn prune(app: &App) -> Result<()> {
+    let keep = app.config.settings.backups_keep.unwrap_or(DEFAULT_KEEP) as usize;
+    let all = list_backups(app);
+    if all.len() <= keep {
+        return Ok(());
+    }
+    for old in all.iter().take(all.len() - keep) {
+        let dir = backups_dir(app).join(&old.id);
+        if dir.is_dir() {
+            let _ = std::fs::remove_dir_all(&dir);
+        }
+    }
+    Ok(())
+}
+
+/// Recursively copy a directory tree (files and directories only; symlinks
+/// are copied as-is when possible).
+fn copy_tree(src: &Path, dest: &Path) -> Result<()> {
+    if !src.exists() {
+        return Ok(());
+    }
+    let meta = std::fs::metadata(src)?;
+    if meta.is_file() {
+        if let Some(parent) = dest.parent() {
+            std::fs::create_dir_all(parent)?;
+        }
+        std::fs::copy(src, dest)?;
+        return Ok(());
+    }
+    std::fs::create_dir_all(dest)?;
+    let mut entries: Vec<_> = std::fs::read_dir(src)?
+        .flatten()
+        .map(|e| e.path())
+        .collect();
+    entries.sort();
+    for child in entries {
+        let name = child
+            .file_name()
+            .ok_or_else(|| anyhow!("invalid path {}", child.display()))?;
+        copy_tree(&child, &dest.join(name))?;
+    }
+    Ok(())
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::cli::Cli;
+    use crate::state::StateFile;
+    use clap::Parser;
+    use std::io::Write;
+
+    fn test_app(tag: &str) -> App {
+        let dir = std::env::temp_dir().join(format!("am-backup-{tag}-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        std::fs::create_dir_all(&dir).unwrap();
+        let cfg = dir.join("config.yaml");
+        std::fs::write(&cfg, "version: \"1.0\"\nagents: []\n").unwrap();
+        let cli = Cli::parse_from([
+            "am",
+            "--config",
+            cfg.to_str().unwrap(),
+            "--yes",
+            "--no-color",
+        ]);
+        let mut app = App::from_cli(cli).expect("app builds");
+        // Point the state/install dirs into the temp dir so nothing touches
+        // the real user data.
+        let state_file = dir.join("state.json");
+        let install = dir.join("agents");
+        std::fs::create_dir_all(&install).unwrap();
+        app.paths.state_file = state_file.clone();
+        app.paths.install_dir = install.clone();
+        app.paths.bin_dir = install.join("bin");
+        app.state = crate::state::StateStore::new(state_file);
+        app.config_origin = Some(cfg);
+        // Fresh backups dir for this test run.
+        let _ = std::fs::remove_dir_all(backups_dir(&app));
+        app
+    }
+
+    fn write_agent_file(app: &App, name: &str, content: &str) -> PathBuf {
+        let dir = app.paths.install_dir.join(name);
+        std::fs::create_dir_all(&dir).unwrap();
+        let f = dir.join("agent.txt");
+        let mut h = std::fs::File::create(&f).unwrap();
+        h.write_all(content.as_bytes()).unwrap();
+        f
+    }
+
+    #[test]
+    fn backup_create_list_restore_roundtrip() {
+        let app = test_app("roundtrip");
+        write_agent_file(&app, "alpha", "v1");
+        write_agent_file(&app, "beta", "b1");
+        // Simulate a managed entry for alpha.
+        let mut sf = StateFile::default();
+        sf.installed.insert(
+            "alpha".to_string(),
+            crate::state::InstalledEntry {
+                name: "alpha".to_string(),
+                version: Some("1.0.0".to_string()),
+                method: "binary".to_string(),
+                install_dir: app.paths.install_dir.join("alpha").display().to_string(),
+                bins: vec![],
+                run: "alpha".to_string(),
+                installed_at: "2026-01-01T00:00:00Z".to_string(),
+                updated_at: None,
+                pid: None,
+                started_at: None,
+            },
+        );
+        app.state.save(&sf).unwrap();
+
+        let info = create_backup(&app, "update:alpha", &["alpha".to_string()]).unwrap();
+        assert!(info.state && info.config);
+
+        // Corrupt the live install + state.
+        write_agent_file(&app, "alpha", "BROKEN");
+        let mut bad = StateFile::default();
+        bad.sessions_count = 999;
+        app.state.save(&bad).unwrap();
+
+        restore_backup(&app, Some(&info.id)).unwrap();
+        let text = std::fs::read_to_string(app.paths.install_dir.join("alpha/agent.txt")).unwrap();
+        assert_eq!(text, "v1", "install dir restored");
+        let sf = app.state.load().unwrap();
+        assert_eq!(sf.installed.get("alpha").unwrap().version.as_deref(), Some("1.0.0"));
+        assert_eq!(sf.sessions_count, 0, "state restored");
+    }
+
+    #[test]
+    fn resolve_point_prefix_and_latest() {
+        let app = test_app("resolve");
+        create_backup(&app, "update:a", &[]).unwrap();
+        let info = resolve_point(&app, None).unwrap();
+        assert_eq!(info.agents, Vec::<String>::new());
+        let prefix = &info.id[..info.id.len().min(10)];
+        let by_prefix = resolve_point(&app, Some(prefix)).unwrap();
+        assert_eq!(by_prefix.id, info.id);
+    }
+
+    #[test]
+    fn prune_keeps_only_backups_keep() {
+        let mut app = test_app("prune");
+        app.config.settings.backups_keep = Some(1);
+        create_backup(&app, "update:one", &[]).unwrap();
+        create_backup(&app, "update:two", &[]).unwrap();
+        let all = list_backups(&app);
+        assert_eq!(all.len(), 1, "only the newest backup survives");
+    }
+}

src/catalog.rs

@@ -80,35 +80,126 @@ impl Catalog {
     }
 
     /// Case-insensitive search over name, display name, description,
-    /// category, tags and note.
+    /// category, tags and note — typo-tolerant, ranked by relevance.
     pub fn search(&self, keyword: &str, category: Option<&str>) -> Vec<&AgentDef> {
         let kw = keyword.to_lowercase();
-        self.agents
+        let mut scored: Vec<(u32, &AgentDef)> = self
+            .agents
             .iter()
-            .filter(|a| {
-                if a.hidden {
-                    return false;
-                }
-                if let Some(cat) = category {
-                    if a.category.as_deref() != Some(cat) {
-                        return false;
-                    }
-                }
-                let hay = format!(
-                    "{} {} {} {} {} {}",
-                    a.name,
-                    a.title(),
-                    a.description.as_deref().unwrap_or(""),
-                    a.category.as_deref().unwrap_or(""),
-                    a.tags.join(" "),
-                    a.note.as_deref().unwrap_or("")
-                )
-                .to_lowercase();
-                hay.contains(&kw)
+            .filter(|a| !a.hidden)
+            .filter(|a| category.map_or(true, |c| a.category.as_deref() == Some(c)))
+            .filter_map(|a| {
+                let name = a.name.to_lowercase();
+                let title = a.title().to_lowercase();
+                let rest = format!(
+                    "{} {} {}",
+                    a.description.as_deref().unwrap_or("").to_lowercase(),
+                    a.category.as_deref().unwrap_or("").to_lowercase(),
+                    a.tags.join(" ").to_lowercase()
+                );
+                let score = score_keyword(&kw, &name)
+                    .saturating_mul(3)
+                    .saturating_add(score_keyword(&kw, &title).saturating_mul(2))
+                    .saturating_add(score_keyword(&kw, &rest));
+                (score > 0).then_some((score, a))
             })
-            .collect()
+            .collect();
+        scored.sort_by(|(sa, a), (sb, b)| sb.cmp(sa).then(a.name.cmp(&b.name)));
+        scored.into_iter().map(|(_, a)| a).collect()
     }
 
+    /// "Did you mean" candidates for a keyword with no results: closest
+    /// agent names and display names by edit distance.
+    pub fn suggest(&self, keyword: &str) -> Vec<String> {
+        let kw = keyword.to_lowercase();
+        let mut out: Vec<(usize, String)> = Vec::new();
+        for a in self.agents.iter().filter(|a| !a.hidden) {
+            for field in [&a.name, &a.title().to_string()] {
+                let f = field.to_lowercase();
+                if f.is_empty() {
+                    continue;
+                }
+                let d = levenshtein(&kw, &f);
+                if d <= 3 && !out.iter().any(|(_, n)| n == &a.name) {
+                    out.push((d, a.name.clone()));
+                }
+            }
+        }
+        out.sort_by(|(da, na), (db, nb)| da.cmp(db).then(na.cmp(nb)));
+        out.truncate(4);
+        out.into_iter().map(|(_, n)| n).collect()
+    }
+}
+
+/// Score a keyword against one haystack field: 100 for a full hit,
+/// then subsequence and typo bonuses; 0 = no relation at all.
+/// Public so `am suggest` can reuse the exact same ranking (issue #61).
+pub fn score_keyword(keyword: &str, hay: &str) -> u32 {
+    if keyword.is_empty() {
+        return 0;
+    }
+    let tokens: Vec<&str> = keyword.split_whitespace().collect();
+    let mut total = 0u32;
+    for token in &tokens {
+        if token.is_empty() {
+            continue;
+        }
+        let s = score_token(token, hay);
+        if s == 0 {
+            return 0;
+        }
+        total += s;
+    }
+    total
+}
+
+fn score_token(token: &str, hay: &str) -> u32 {
+    if hay.contains(token) {
+        return 100;
+    }
+    if subsequence(token, hay) {
+        return 40;
+    }
+    // Typo tolerance: compare the token with every word of the field.
+    let mut best = usize::MAX;
+    for word in hay.split(|c: char| !c.is_alphanumeric()) {
+        if word.is_empty() {
+            continue;
+        }
+        best = best.min(levenshtein(token, word));
+    }
+    match best {
+        0..=1 => 25,
+        2 => 15,
+        3 => 5,
+        _ => 0,
+    }
+}
+
+/// Do the characters of needle appear in order inside hay?
+fn subsequence(needle: &str, hay: &str) -> bool {
+    let mut it = hay.chars();
+    needle.chars().all(|c| it.any(|h| h == c))
+}
+
+/// Classic Levenshtein distance on characters.
+fn levenshtein(a: &str, b: &str) -> usize {
+    let a: Vec<char> = a.chars().collect();
+    let b: Vec<char> = b.chars().collect();
+    let mut prev: Vec<usize> = (0..=b.len()).collect();
+    let mut cur = vec![0usize; b.len() + 1];
+    for (i, ca) in a.iter().enumerate() {
+        cur[0] = i + 1;
+        for (j, cb) in b.iter().enumerate() {
+            let cost = if ca == cb { 0 } else { 1 };
+            cur[j + 1] = (prev[j] + cost).min(prev[j + 1] + 1).min(cur[j] + 1);
+        }
+        std::mem::swap(&mut prev, &mut cur);
+    }
+    prev[b.len()]
+}
+
+impl Catalog {
     /// Sorted list of all categories present in the catalog.
     pub fn categories(&self) -> Vec<String> {
         let mut cats: Vec<String> = self
@@ -156,4 +247,50 @@ mod tests {
         let cats = cat.categories();
         assert!(cats.contains(&"coding-agent".to_string()));
     }
+
+    #[test]
+    fn fuzzy_search_tolerates_missing_separator() {
+        let cat = catalog();
+        let hits = cat.search("claude cod", None);
+        assert!(
+            hits.iter().any(|a| a.name == "claude-code"),
+            "expected claude-code in {:?}",
+            hits.iter().map(|a| &a.name).collect::<Vec<_>>()
+        );
+    }
+
+    #[test]
+    fn fuzzy_search_tolerates_typos() {
+        let cat = catalog();
+        let hits = cat.search("cludecode", None);
+        assert!(hits.iter().any(|a| a.name == "claude-code"));
+    }
+
+    #[test]
+    fn exact_matches_rank_first() {
+        let cat = catalog();
+        let hits = cat.search("claude", None);
+        assert!(!hits.is_empty());
+        assert_eq!(
+            hits[0].name, "claude-code",
+            "exact name match must rank first: {:?}",
+            hits.iter().map(|a| &a.name).collect::<Vec<_>>()
+        );
+    }
+
+    #[test]
+    fn suggest_proposes_close_names() {
+        let cat = catalog();
+        let sug = cat.suggest("aiderr");
+        assert!(sug.contains(&"aider".to_string()), "suggestions: {sug:?}");
+        assert!(sug.len() <= 4);
+    }
+
+    #[test]
+    fn levenshtein_distance() {
+        assert_eq!(levenshtein("aider", "aider"), 0);
+        assert_eq!(levenshtein("aider", "aiderr"), 1);
+        assert_eq!(levenshtein("abc", "axc"), 1);
+        assert_eq!(levenshtein("abc", "xyz"), 3);
+    }
 }

src/catalog_remote.rs

@@ -0,0 +1,303 @@
+//! Remote catalogs (issues #60 #67, axes 7 & 9): fetching a catalog from
+//! an http(s) URL, validating its format, and caching it on disk the
+//! probe.rs way (keyed by URL + timestamp, TTL-bounded). Used both by
+//! 'am catalog update/add' and by config `include:` entries pointing at
+//! URLs.
+//!
+//! Rules:
+//! * only http, https and file:// URLs are accepted (download::validate_url);
+//! * a cached copy is served while it is fresh; on network failure the
+//!   stale cache is used with a warning (offline support);
+//! * a malformed catalog is an error, never silently skipped.
+
+use crate::config::{self, Config};
+use anyhow::{anyhow, bail, Context, Result};
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeMap;
+use std::path::{Path, PathBuf};
+use std::time::{SystemTime, UNIX_EPOCH};
+
+/// Default time-to-live of a cached remote catalog, in seconds (1 h).
+pub const DEFAULT_TTL_SECS: u64 = 3600;
+
+/// Base URL of the official catalog (the agent-manager repo on Gitea).
+pub const DEFAULT_CATALOG_URL: &str =
+    "https://git.dracodev.net/Projets/agent-manager/raw/branch/main/config.yaml";
+
+/// One cached catalog: the raw text, the URL it came from, and the fetch
+/// time (seconds since the epoch).
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CachedCatalog {
+    pub url: String,
+    pub fetched_at: u64,
+    pub text: String,
+}
+
+#[derive(Debug, Default, Serialize, Deserialize)]
+pub struct CatalogCache {
+    pub entries: BTreeMap<String, CachedCatalog>,
+}
+
+impl CatalogCache {
+    fn load(state_dir: &Path) -> Self {
+        std::fs::read_to_string(state_dir.join("catalog-cache.json"))
+            .ok()
+            .and_then(|t| serde_json::from_str(&t).ok())
+            .unwrap_or_default()
+    }
+
+    fn save(&self, state_dir: &Path) {
+        if let Ok(text) = serde_json::to_string_pretty(self) {
+            let _ = std::fs::write(state_dir.join("catalog-cache.json"), text);
+        }
+    }
+}
+
+/// Fetch the text of a catalog URL, using and refreshing the on-disk cache.
+/// `force` bypasses the TTL (used by 'am catalog update').
+pub fn fetch(app: &crate::app::App, url: &str, force: bool) -> Result<String> {
+    let ttl = app
+        .config
+        .settings
+        .catalog_cache_ttl_secs
+        .unwrap_or(DEFAULT_TTL_SECS);
+    fetch_with_cache(&app.events_dir(), url, force, ttl, Some(&app.log))
+}
+
+/// Fetch a catalog URL during config loading (no App available yet): the
+/// cache lives in the state directory and the TTL is the default one.
+pub fn fetch_for_config(state_dir: &Path, url: &str) -> Result<String> {
+    fetch_with_cache(state_dir, url, false, DEFAULT_TTL_SECS, None)
+}
+
+/// Shared fetch + cache logic.
+fn fetch_with_cache(
+    state_dir: &Path,
+    url: &str,
+    force: bool,
+    ttl: u64,
+    log: Option<&crate::output::Logger>,
+) -> Result<String> {
+    crate::download::validate_url(url)?;
+    let mut cache = CatalogCache::load(state_dir);
+    let now = now_secs();
+
+    // Fresh cache hit: no network.
+    if !force {
+        if let Some(entry) = cache.entries.get(url) {
+            if now.saturating_sub(entry.fetched_at) < ttl {
+                return Ok(entry.text.clone());
+            }
+        }
+    }
+
+    // Try the network; fall back to the stale cache on failure.
+    let fresh = fetch_url_text(url);
+    match fresh {
+        Ok(text) => {
+            cache.entries.insert(
+                url.to_string(),
+                CachedCatalog {
+                    url: url.to_string(),
+                    fetched_at: now,
+                    text: text.clone(),
+                },
+            );
+            cache.save(state_dir);
+            Ok(text)
+        }
+        Err(net_err) => {
+            if let Some(entry) = cache.entries.get(url) {
+                if let Some(log) = log {
+                    log.warn(&format!(
+                        "cannot refresh catalog {url} ({net_err:#}) — using the cached copy from {}",
+                        format_ts(entry.fetched_at)
+                    ));
+                }
+                Ok(entry.text.clone())
+            } else {
+                Err(net_err)
+            }
+        }
+    }
+}
+
+/// Fetch the raw text of an http(s) or file:// URL (no cache).
+fn fetch_url_text(url: &str) -> Result<String> {
+    if let Some(local) = url.strip_prefix("file://") {
+        // Windows: "file:///C:/x" -> "C:/x" (drop the leading slash).
+        let local = if cfg!(windows) && local.starts_with('/') {
+            local.strip_prefix('/').unwrap_or(local)
+        } else {
+            local
+        };
+        let p = PathBuf::from(local);
+        return std::fs::read_to_string(&p)
+            .with_context(|| format!("cannot read catalog file {}", p.display()));
+    }
+    let resp = ureq::get(url)
+        .set("User-Agent", crate::download::USER_AGENT)
+        .timeout(std::time::Duration::from_secs(30))
+        .call()
+        .map_err(|e| match e {
+            ureq::Error::Status(code, r) => anyhow!(
+                "HTTP {code} {} while fetching {url}",
+                r.status_text()
+            ),
+            other => anyhow!("cannot fetch {url}: {other}"),
+        })?;
+    resp.into_string()
+        .with_context(|| format!("reading the catalog body of {url}"))
+}
+
+/// Parse and validate a catalog YAML text; returns the parsed Config.
+pub fn parse_catalog(text: &str) -> Result<Config> {
+    let cfg: Config = serde_yaml::from_str(text)
+        .map_err(|e| anyhow!("the remote catalog is not a valid config: {e}"))?;
+    let problems = config::validate(&cfg);
+    if !problems.is_empty() {
+        bail!(
+            "the remote catalog is invalid:\n  - {}",
+            problems.join("\n  - ")
+        );
+    }
+    Ok(cfg)
+}
+
+/// Diff between the local effective catalog and a remote one: agent names
+/// that are new, removed, or changed (run command differs).
+pub struct CatalogDiff {
+    pub added: Vec<String>,
+    pub removed: Vec<String>,
+    pub changed: Vec<(String, String, String)>, // (name, local run, remote run)
+}
+
+pub fn diff_catalogs(local: &Config, remote: &Config) -> CatalogDiff {
+    let local_names: BTreeMap<&str, &str> = local
+        .agents
+        .iter()
+        .map(|a| (a.name.as_str(), a.run.as_deref().unwrap_or("")))
+        .collect();
+    let remote_names: BTreeMap<&str, &str> = remote
+        .agents
+        .iter()
+        .map(|a| (a.name.as_str(), a.run.as_deref().unwrap_or("")))
+        .collect();
+    let mut added = Vec::new();
+    let mut removed = Vec::new();
+    let mut changed = Vec::new();
+    for (name, run) in &remote_names {
+        match local_names.get(name) {
+            None => added.push((*name).to_string()),
+            Some(local_run) if local_run != run => {
+                changed.push(((*name).to_string(), (*local_run).to_string(), (*run).to_string()));
+            }
+            _ => {}
+        }
+    }
+    for name in local_names.keys() {
+        if !remote_names.contains_key(name) {
+            removed.push((*name).to_string());
+        }
+    }
+    added.sort();
+    removed.sort();
+    changed.sort();
+    CatalogDiff {
+        added,
+        removed,
+        changed,
+    }
+}
+
+/// The official catalog URL: the configured value, or the Gitea default.
+pub fn official_url(app: &crate::app::App) -> String {
+    app.config
+        .settings
+        .catalog_url
+        .clone()
+        .unwrap_or_else(|| DEFAULT_CATALOG_URL.to_string())
+}
+
+fn now_secs() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map(|d| d.as_secs())
+        .unwrap_or(0)
+}
+
+fn format_ts(secs: u64) -> String {
+    let dt = chrono::DateTime::from_timestamp(secs as i64, 0);
+    dt.map(|d| d.format("%Y-%m-%d %H:%M").to_string())
+        .unwrap_or_else(|| "unknown date".to_string())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const VALID: &str = "version: \"1.0\"\nagents:\n  - name: alpha\n    run: alpha\n    install: { type: binary, url: \"https://x/a\" }\n";
+
+    #[test]
+    fn parses_and_validates_a_remote_catalog() {
+        let cfg = parse_catalog(VALID).unwrap();
+        assert_eq!(cfg.agents.len(), 1);
+        assert_eq!(cfg.agents[0].name, "alpha");
+    }
+
+    #[test]
+    fn rejects_malformed_catalogs() {
+        assert!(parse_catalog("not: [valid").is_err());
+        // Missing run on an installable agent is invalid.
+        assert!(parse_catalog(
+            "version: \"1.0\"\nagents:\n  - name: x\n    install: { type: npm, package: y }\n"
+        )
+        .is_err());
+    }
+
+    #[test]
+    fn diff_detects_added_removed_changed() {
+        let local: Config = serde_yaml::from_str(
+            "version: \"1.0\"\nagents:\n  - { name: keep, run: keep, install: { type: binary, url: \"https://x/k\" } }\n  - { name: gone, run: gone, install: { type: binary, url: \"https://x/g\" } }\n  - { name: tweaked, run: old, install: { type: binary, url: \"https://x/t\" } }\n",
+        )
+        .unwrap();
+        let remote: Config = serde_yaml::from_str(
+            "version: \"1.0\"\nagents:\n  - { name: keep, run: keep, install: { type: binary, url: \"https://x/k\" } }\n  - { name: fresh, run: fresh, install: { type: binary, url: \"https://x/f\" } }\n  - { name: tweaked, run: new, install: { type: binary, url: \"https://x/t\" } }\n",
+        )
+        .unwrap();
+        let d = diff_catalogs(&local, &remote);
+        assert_eq!(d.added, vec!["fresh".to_string()]);
+        assert_eq!(d.removed, vec!["gone".to_string()]);
+        assert_eq!(d.changed.len(), 1);
+        assert_eq!(d.changed[0].0, "tweaked");
+        assert_eq!(d.changed[0].1, "old");
+        assert_eq!(d.changed[0].2, "new");
+    }
+
+    #[test]
+    fn file_url_fetch_works_offline() {
+        let dir = tempfile::tempdir().unwrap();
+        let p = dir.path().join("cat.yaml");
+        std::fs::write(&p, VALID).unwrap();
+        let url = format!("file://{}", p.display());
+        let text = fetch_url_text(&url).unwrap();
+        assert!(text.contains("alpha"));
+    }
+
+    #[test]
+    fn cache_roundtrip() {
+        let dir = tempfile::tempdir().unwrap();
+        let mut cache = CatalogCache::default();
+        cache.entries.insert(
+            "https://x".to_string(),
+            CachedCatalog {
+                url: "https://x".to_string(),
+                fetched_at: 42,
+                text: "body".to_string(),
+            },
+        );
+        cache.save(dir.path());
+        let back = CatalogCache::load(dir.path());
+        assert_eq!(back.entries["https://x"].text, "body");
+    }
+}