# AGENTS.md

## But du depot

Ce projet construit un framework de post-installation pour Debian 13, lance via :

```bash
curl -fsSL https://gitea.maison43.duckdns.org/gilles/postinstall-debian/raw/branch/main/install.sh | bash
```

L'objectif est de proposer une base modulaire, testable et evolutive pour installer et configurer un systeme Debian apres installation.

## Regles de travail
- ecrire les commentaires et les explication en francais
- Toujours privilegier une architecture modulaire.
- Chaque outil doit vivre dans son propre module.
- Ne pas melanger logique framework, logique UI et logique d'installation d'un outil.
- Eviter les actions destructives ou silencieuses sur le systeme.
- Garder le code compatible avec Debian 13 et un shell Bash standard.
- Favoriser du code lisible, structure et compose de fonctions courtes.

## Structure cible

Le depot doit converger vers cette structure :

```text
install.sh
README.md
consigne.md
tools.md
CHANGELOG.md
AGENTS.md

assets/
config/
core/
docs/
hardware/
lib/
menus/
modules/
profiles/
tests/
```

## Responsabilites par zone

- `install.sh` : point d'entree compatible `curl | bash`.
- `core/` : bootstrap, runtime, registre des modules, dispatch.
- `lib/` : fonctions reutilisables UI, logs, validations, paquets, systeme, reseau.
- `menus/` : menus interactifs.
- `modules/` : outils installables, un dossier par outil.
- `profiles/` : groupes de modules predefinis.
- `hardware/` : selections liees au materiel.
- `assets/` : themes, polices, wallpapers, icones et ressources visuelles.
- `tests/` : tests framework et tests de modules.
- `docs/` : documentation de conception et d'usage.

## Contrat d'un module

Chaque module doit idealement contenir :

```text
modules/<categorie>/<outil>/
module.sh
config.sh
metadata.conf
tests.sh
```

Fonctions attendues quand elles sont pertinentes :

- `module_<outil>_metadata`
- `module_<outil>_check`
- `module_<outil>_install`
- `module_<outil>_configure`
- `module_<outil>_test`

## Standards Bash

- Utiliser `set -u` et une gestion d'erreurs explicite lorsque l'architecture sera en place.
- Citer correctement les variables.
- Preferer `command -v` pour verifier les dependances.
- Centraliser les logs, messages UI et validations dans `lib/`.
- Garder les effets de bord dans des fonctions nommees clairement.
- Prevoir ShellCheck des que les scripts existent.

## Experience utilisateur

Le framework doit fournir :

- une interface console claire
- des messages colores et coherents
- des etapes visibles
- des confirmations quand une action est sensible
- un resume final des operations

Fonctions UI a prevoir :

- `ui_header`
- `ui_section`
- `ui_info`
- `ui_success`
- `ui_warn`
- `ui_error`
- `ui_menu`
- `ui_confirm`
- `ui_pause`

## Securite

- Verifier la distribution et les privileges avant toute installation.
- Verifier le reseau si une action distante est necessaire.
- Ne pas modifier silencieusement des fichiers critiques.
- Preferer des changements explicites, journalises et reversibles quand possible.

## Methode pour ajouter un outil

Avant implementation, passer par :

1. Brainstorming de l'outil.
2. Decision d'architecture.
3. Implementation du module.
4. Integration menu, profil ou materiel si necessaire.
5. Tests.
6. Documentation.

Les informations minimales d'un outil dans `tools.md` sont :

- nom
- description
- categorie
- questions
- methode d'installation
- tests
- statut

## Priorite immediate

Avant d'ajouter des outils, construire l'ossature du framework :

- point d'entree `install.sh`
- dossiers standards
- bibliotheques de base
- mecanisme de chargement
- premiers menus
- documentation de demarrage