Air Desktop — index général

Carte structurelle du projet : ce qui existe, et où le trouver.

Ce document ne décrit pas l’avancement des travaux — c’est le rôle du suivi, document unique et vivant. Il ne consigne pas non plus les décisions : elles vivent dans les ADR.

Les parties factuelles de cette page — versions de sceau, nombre de crates, arborescence, volumétrie — sont générées depuis leur source de vérité par scripts/generer-index-general.py, et vérifiées à chaque PR. Elles ne peuvent donc plus dériver du réel. La prose, elle, est écrite à la main.

Par où commencer

Ordre d’autorité en cas de divergence : charte → principes d’ingénierie → ADR → specs → setup. Le suivi fait foi sur l’avancement ; cet index fait foi sur la structure.

Identité du projet

Les couches

Air se construit de bas en haut. Une couche scellée a son API gelée : elle n’évolue plus que par descellement additif, qui exige un ADR et repose un tag.

La règle de dépendance est stricte et vérifiée en CI (cargo xtask check-layers) : seule la couche 1 consomme la couche 0 ; la couche 2 ne descend jamais directement au syscall.

Décisions d’architecture

182 décisions d’architecture. Le registre complet — trié par numéro, avec liens FR/EN et avancement — est le document de référence :

Registre des ADR

Le registre est généré (scripts/generer-registre-adrs.py) : il ne peut plus diverger des fichiers présents sur disque.

Un ADR consigne une décision structurante : son contexte, la décision, ses conséquences. Ils sont numérotés et immuables une fois acceptés — toute évolution passe par un RFC (ADR-015), jamais par une retouche silencieuse.

Chaque ADR existe en français et en anglais. Le champ **Statut :** qu’il porte décrit sa décision (Accepté, Proposé) ; la colonne « Mise en œuvre » du registre décrit son avancement — deux dimensions distinctes.

Arborescence du dépôt

air/
├── crates/                # les crates du workspace, une par brique
│   ├── (couche 0) 2 crates
│   ├── (couche 1) 37 crates
│   └── (couche 2) 53 crates
├── docs/                  # toute la documentation (voir la carte ci-dessous)
├── fuzz/                  # cibles cargo-fuzz
├── maquette-zola/         # maquette d'évaluation d'un rendu possédé — TEMPORAIRE
├── rt/                    # arbre hors-source des cibles `*-linux-air` (expérimental)
├── scripts/               # outillage de documentation et de vérification
├── xtask/                 # commandes de développement (`cargo xtask …`)
├── AGENTS.md              # mémo d'exécution pour les agents (EN)
├── CLAUDE.md              # mémo d'exécution pour les agents (FR)
├── Cargo.lock             # verrou committé (ADR-025, builds reproductibles)
├── Cargo.toml             # manifeste du workspace
├── LICENSE                # MPL 2.0
├── README-fr.md           # présentation publique (FR)
├── README.md              # présentation publique
├── REPRISE.md
├── book.toml              # configuration mdBook
├── deny.toml              # politique de licences et d'avis de sécurité
└── rust-toolchain.toml    # toolchain épinglée

Carte de la documentation

Toute la documentation vit sous docs/. Les seuls points d’entrée à la racine sont les fichiers conventionnels : README.md, README-fr.md, LICENSE, CLAUDE.md, AGENTS.md.

Convention de nommage des fichiers

Le numéro d’ADR est sur trois chiffres, le suffixe de langue est -fr ou -en. Les deux langues sont obligatoires : une version manquante fait échouer la vérification du registre.

Documents encore à produire

Ces documents n’existent pas, et c’est assumé : l’ouverture publique ne prime pas sur la couche 0 tant que celle-ci n’est pas opérationnelle en pratique. Ils sont listés ici pour mémoire, non comme un retard.

Les conventions de style, de test, de gestion d’erreurs et de commit ne sont pas listées ici : elles font déjà autorité dans CLAUDE.md, dans les principes d’ingénierie et dans les ADR concernés. Les extraire en fichiers racine dupliquerait la source de vérité — à ne faire qu’à l’ouverture publique, et par extraction, pas par réécriture.

Tenir cette page à jour

Les blocs encadrés par <!-- GÉNÉRÉ:… --> ne se modifient pas à la main : ils seraient écrasés, et la CI signalerait l’écart. Après un changement de structure — nouveau crate, nouveau tag de sceau, nouvelle rubrique de documentation :

scripts/generer-index-general.py          # met à jour les blocs générés
scripts/generer-index-general.py --check  # ce que vérifie la CI

Pour ajouter une rubrique de documentation ou changer sa description, éditer la table RUBRIQUES du script — la description est de la prose, seul le volume est relevé sur disque.

Licence du document : MPL 2.0