docs: polish ArchASP dotfiles README

README.md

@@ -1,162 +1,291 @@
-# ArchASP Dotfiles
+<p align="center">
+  <img src=".assets/screen.jpg" alt="ArchASP — Sway desktop" width="100%">
+</p>
 
-Configuration de la couche utilisateur de la station Arch Linux ArchASP. Le
-dépôt privilégie des fichiers lisibles, déployés par GNU Stow, et sépare
-explicitement la session utilisateur de l'administration système.
+<h1 align="center">ArchASP Dotfiles</h1>
 
-## Overview
+<p align="center">
+  Configuration utilisateur reproductible pour une station Arch Linux sous
+  Wayland, déployée package par package avec GNU Stow.
+</p>
 
-Ce dépôt gère Sway, les applications de terminal, le shell, les scripts
-personnels et les unités systemd utilisateur. La configuration root, les
-paquets de base, le stockage, le réseau, le boot et les helpers sous
-`/usr/local` appartiennent au dépôt
-[`arch-system`](https://git.labfytools.com/fy59/arch-system).
+<p align="center">
+  <code>Arch Linux</code> · <code>Sway</code> · <code>GNU Stow</code> ·
+  <code>systemd --user</code> · <code>Zsh</code>
+</p>
 
-Certaines configurations restent liées à cette machine : sorties Sway,
-périphériques, chemins sous `/home/fy59` et projets présents dans `Documents`.
-Elles doivent être relues avant un déploiement sur un autre poste.
+<p align="center">
+  <a href="#overview">Overview</a> ·
+  <a href="#desktop-stack">Desktop</a> ·
+  <a href="#shell-stack">Shell</a> ·
+  <a href="#repository-layout">Layout</a> ·
+  <a href="#deployment">Deployment</a> ·
+  <a href="#rebuilding-archasp">Rebuild</a>
+</p>
 
-## Desktop Stack
+<a id="overview"></a>
 
-La chaîne de session canonique est :
+## ✦ Overview
+
+Ce dépôt contient la couche **utilisateur** d'ArchASP : session graphique,
+applications terminal, shell, scripts personnels et unités systemd user. La
+couche **système/root** est volontairement séparée.
+
+| Dépôt | Responsabilité |
+| --- | --- |
+| **`.dotfiles`** | Sway, Kitty, Neovim, Zsh, scripts, thèmes et services utilisateur |
+| **[`arch-system`](https://git.labfytools.com/fy59/arch-system)** | Installation Arch, boot, stockage, réseau, paquets, `/etc` et helpers root |
+
+Cette séparation évite de mêler état personnel et administration système. Le
+dépôt reste néanmoins spécifique à la machine : sorties Sway, périphériques,
+chemins sous `/home/fy59` et projets externes doivent être relus avant un
+déploiement ailleurs.
+
+<a id="desktop-stack"></a>
+
+## ✦ Desktop Stack
 
 ```text
-greetd -> tuigreet -> UWSM -> Sway
+greetd
+  └─ tuigreet
+      └─ UWSM
+          └─ Sway
+              ├─ Swaybar ── i3status-rs
+              ├─ Mako       notifications
+              ├─ Wofi       launcher
+              ├─ Swaylock   verrouillage
+              ├─ Cliphist   historique du presse-papiers
+              └─ Kitty      terminal
 ```
 
-Sway utilise sa barre native avec i3status-rs. Mako fournit les notifications,
-Wofi le lanceur, Swaylock le verrouillage, wl-clipboard et Cliphist
-l'historique du presse-papiers, et Kitty le terminal.
+| Fonction | Composant canonique |
+| --- | --- |
+| Session | `greetd → tuigreet → uwsm start default → sway.desktop` |
+| Compositor | Sway / SwayFX |
+| Barre | Swaybar avec i3status-rs |
+| Notifications | Mako |
+| Launcher | Wofi |
+| Verrouillage et idle | Swaylock + swayidle |
+| Presse-papiers | wl-clipboard + Cliphist |
+| Terminal | Kitty |
+| Profils d'énergie | TLP via l'interface utilisateur `tlpctl` |
 
-Le fichier `uwsm/.config/uwsm/default-id` sélectionne `sway.desktop`. La copie
-de référence de la configuration root de greetd se trouve dans
-`.assets/greetd/config.toml`; son installation réelle sous `/etc/greetd`
-relève de `arch-system`.
+`uwsm/.config/uwsm/default-id` sélectionne `sway.desktop`. La copie de
+référence de greetd se trouve dans `.assets/greetd/config.toml`; son
+installation sous `/etc/greetd` appartient à `arch-system`.
 
-## Shell Stack
+<a id="shell-stack"></a>
 
-Le shell interactif est Zsh. Son environnement associe Starship, Atuin, FZF,
-Zoxide, Eza, Bat et Yazi. `.zprofile` démarre la session graphique via UWSM
-lorsque celui-ci autorise un démarrage, et `.zshenv` publie le socket de
-l'agent SSH utilisateur.
-
-Les données Atuin, historiques de shell, clés, bases et états applicatifs ne
-font pas partie du dépôt.
-
-## Repository Layout
-
-Chaque répertoire de premier niveau, hors `.assets` et `.git`, est un paquet
-GNU Stow indépendant. Son contenu reproduit le chemin attendu depuis `$HOME` :
+## ✦ Shell Stack
 
 ```text
-kitty/.config/kitty/       -> ~/.config/kitty/
-nvim/.config/nvim/         -> ~/.config/nvim/
-sway/.config/sway/         -> ~/.config/sway/
-bin/.local/bin/            -> ~/.local/bin/
-systemd/.config/systemd/   -> ~/.config/systemd/
-zsh/.zshrc                 -> ~/.zshrc
+Zsh
+ ├─ Starship
+ ├─ Atuin
+ ├─ FZF
+ ├─ Zoxide
+ ├─ Eza
+ ├─ Bat
+ └─ Yazi
 ```
 
-Les thèmes, icônes et wallpapers sont volontairement versionnés. `.assets`
-contient les inventaires de reconstruction et des références système ; ce
-n'est pas un paquet Stow.
+`.zprofile` démarre la session graphique via UWSM lorsque celui-ci autorise un
+démarrage. `.zshenv` publie le socket de l'agent SSH utilisateur. L'historique,
+les bases et la clé Atuin restent strictement locaux et hors Git.
 
-## Deployment
+<a id="repository-layout"></a>
 
-Prérequis : Git, GNU Stow et les paquets décrits dans `.assets`. Cloner le
-dépôt principal avec ses sous-modules :
+## ✦ Repository Layout
+
+Chaque répertoire de premier niveau, hors `.assets` et `.git`, est un package
+GNU Stow indépendant. Son arborescence reproduit le chemin attendu depuis
+`$HOME`.
+
+```text
+.dotfiles/
+├── sway/.config/sway/             → ~/.config/sway/
+├── i3status-rust/.config/         → ~/.config/i3status-rust/
+├── kitty/.config/kitty/           → ~/.config/kitty/
+├── nvim/.config/nvim/             → ~/.config/nvim/
+├── systemd/.config/systemd/user/  → ~/.config/systemd/user/
+├── bin/.local/bin/                → ~/.local/bin/
+├── zsh/.zshrc                     → ~/.zshrc
+├── zsh/.zprofile                  → ~/.zprofile
+└── .assets/                       inventaires et références, non déployés
+```
+
+### Packages principaux
+
+| Groupe | Packages Stow |
+| --- | --- |
+| Desktop | `sway`, `swaylock`, `mako`, `wofi`, `cliphist`, `i3status-rust` |
+| Terminal et shell | `kitty`, `zsh`, `starship`, `atuin`, `fzf`, `eza`, `bat`, `yazi` |
+| Développement | `nvim`, `tmux`, `opencode`, `bin` |
+| Services | `systemd`, `uwsm` |
+| Apparence | `gtk-3.0`, `gtklock`, `qt5ct`, `qt6ct`, `themes`, `icons`, `wallpapers` |
+| Outils | `btop`, `fastfetch`, `hyprwhspr`, `ytmusic-tui` |
+
+Les thèmes, icônes et wallpapers sont volontairement versionnés. Les
+exécutables issus de projets externes restent hors Git même lorsqu'un script
+ou une unité user les utilise.
+
+### Sous-modules
+
+Les plugins Zsh et Tmux sont épinglés par Git :
+
+| Intégration | Chemin |
+| --- | --- |
+| Fast Syntax Highlighting | `zsh/.zsh/plugins/fast-syntax-highlighting` |
+| FZF Tab | `zsh/.zsh/plugins/fzf-tab` |
+| Zsh Autosuggestions | `zsh/.zsh/plugins/zsh-autosuggestions` |
+| Catppuccin Tmux | `tmux/.config/tmux/plugins/catppuccin/tmux` |
+
+<a id="deployment"></a>
+
+## ✦ Deployment
+
+### Prérequis
+
+- Git ;
+- GNU Stow ;
+- les paquets décrits dans `.assets` ;
+- une sauvegarde des fichiers existants qui pourraient entrer en conflit.
+
+### Clone
 
 ```bash
 git clone --recurse-submodules \
   ssh://git@git.labfytools.com:2223/fy59/Dotfiles_ArchAP.git \
   "$HOME/.dotfiles"
+
 cd "$HOME/.dotfiles"
 git submodule update --init --recursive
 ```
 
-Construire la liste des paquets, puis commencer obligatoirement par un dry-run :
+### Dry-run Stow
+
+Construire la liste des packages à partir des répertoires de premier niveau :
 
 ```bash
 mapfile -t packages < <(
   find . -mindepth 1 -maxdepth 1 -type d \
     ! -name .git ! -name .assets -printf '%f\n' | sort
 )
+
 stow --no --verbose=2 --target="$HOME" "${packages[@]}"
 ```
 
-Après examen des conflits éventuels, effectuer le déploiement :
+Examiner tout conflit avant le déploiement réel :
 
 ```bash
 stow --verbose=2 --target="$HOME" "${packages[@]}"
 ```
 
-Stow reçoit les noms des paquets. Il ne faut pas lancer `stow .`, car la
-racine du dépôt n'est pas elle-même un paquet.
+> Stow reçoit les **noms des packages**. La racine du dépôt n'est pas un
+> package : ne pas utiliser `stow .`.
 
-## Package Inventory
+<a id="package-inventory"></a>
 
-- `.assets/pkglist-pacman.txt` contient les paquets officiels explicitement
-  installés (`pacman -Qqen`).
-- `.assets/pkglist-aur.txt` contient les paquets foreign/AUR explicitement
-  installés (`pacman -Qqem`).
-- `.assets/external-tools.md` décrit Cargo, npm, builds manuels, projets locaux
-  et helpers système qui ne sont pas restaurés par Pacman.
+## ✦ Package Inventory
 
-Ces fichiers sont des instantanés, pas un programme d'installation. Leur
-application et la validation des paquets AUR relèvent de la reconstruction du
-système.
+| Fichier | Source | Contenu |
+| --- | --- | --- |
+| `.assets/pkglist-pacman.txt` | `pacman -Qqen` | Paquets officiels explicitement installés |
+| `.assets/pkglist-aur.txt` | `pacman -Qqem` | Paquets foreign/AUR explicitement installés |
+| `.assets/enabled-services.txt` | systemd système | Services système activés |
+| `.assets/enabled-system-aux-units.txt` | systemd système | Timers, sockets et paths activés |
+| `.assets/enabled-user-aux-units.txt` | systemd user | Timers, sockets et paths utilisateur activés |
+| `.assets/external-tools.md` | inventaire manuel | Cargo, npm, builds locaux, projets et helpers `/usr/local` |
 
-## Services
+Ces fichiers sont des instantanés vérifiables, pas un installateur. Les paquets
+AUR, outils Cargo/npm et builds locaux doivent être restaurés séparément.
 
-`.assets/enabled-services.txt` recense les services systemd système activés.
-Les timers, sockets et paths sont séparés dans
-`.assets/enabled-system-aux-units.txt` et
-`.assets/enabled-user-aux-units.txt`. Leur activation côté système appartient
-à `arch-system`.
+<a id="services"></a>
 
-Le paquet `systemd` contient les unités utilisateur et leurs liens
-d'activation canoniques. Après déploiement ou modification :
+## ✦ Services
+
+Le package `systemd` contient les unités utilisateur ainsi que leurs liens
+d'activation relatifs. Il couvre notamment Cliphist, swayidle, GNOME Keyring,
+l'agent SSH, les notifications de batterie et les intégrations Trainlog,
+Lardon et Arch Sentinel.
+
+Après une modification :
 
 ```bash
 systemctl --user daemon-reload
 systemd-analyze --user verify ~/.config/systemd/user/*.service
 ```
 
-Plusieurs unités lancent du code externe à ce dépôt, notamment Trainlog,
-Lardon et Arch Sentinel. Leurs sources et builds doivent être restaurés aux
-emplacements documentés dans `.assets/external-tools.md`.
+Certaines unités lancent du code externe au dépôt. Leurs chemins et
+dépendances sont documentés dans `.assets/external-tools.md`. Les services
+système et toute modification de `/etc` restent sous la responsabilité
+d'`arch-system`.
 
-## Secrets
+<a id="secrets"></a>
 
-Ne jamais versionner de clé SSH/GPG, `.netrc`, token, cookie, credential,
-configuration Rclone ou `gh` privée, clé WireGuard, base Atuin, clé Atuin ou
-secret Nextcloud. Les états et caches applicatifs restent sous `$HOME` et sont
-exclus de Stow ou de Git.
+## ✦ Secrets
 
-Un contrôle du HEAD ne remplace pas une analyse de l'historique Git. Tout
-secret ayant été commité doit être révoqué ou renouvelé avant une purge de
-l'historique et avant la publication d'un miroir.
+Ce dépôt n'a pas vocation à contenir :
 
-## Rebuilding ArchASP
+- clés SSH, GPG, WireGuard ou Atuin ;
+- `.netrc`, mots de passe, tokens, cookies ou credentials ;
+- configurations privées Rclone, GitHub CLI ou Nextcloud ;
+- bases de données, historiques shell ou états applicatifs personnels.
 
-Une reconstruction repose sur deux couches :
+Les ignorer dans le HEAD ne suffit pas : un secret déjà commité doit être
+renouvelé, puis supprimé de tout l'historique avant publication.
 
-1. `arch-system` restaure la base Arch, les paquets, greetd, le réseau, le
-   stockage et les services root ;
-2. ce dépôt restaure les sous-modules, fichiers Stow, scripts et unités
-   systemd utilisateur.
+<a id="rebuilding-archasp"></a>
 
-Restent manuels ou externes : installation des paquets AUR, outils Cargo/npm,
-builds des projets dans `Documents`, OpenMVS local, helpers `/usr/local`,
-secrets, données applicatives et activation contrôlée des unités. Le dépôt ne
-prétend donc pas reconstruire seul une machine complète.
+## ✦ Rebuilding ArchASP
 
-## Repository Mirrors
+```text
+┌──────────────────────────────────────────────────────┐
+│ arch-system                                          │
+│ Arch · boot · stockage · réseau · paquets · /etc    │
+└──────────────────────────┬───────────────────────────┘
+                           │ socle système prêt
+                           ▼
+┌──────────────────────────────────────────────────────┐
+│ .dotfiles                                            │
+│ Stow · session · shell · scripts · systemd user     │
+└──────────────────────────┬───────────────────────────┘
+                           │ restaurations externes
+                           ▼
+┌──────────────────────────────────────────────────────┐
+│ AUR · Cargo/npm · projets locaux · secrets · données│
+└──────────────────────────────────────────────────────┘
+```
 
-Forgejo est l'upstream principal et conserve le nom de remote `origin`.
-GitHub, lorsqu'il sera configuré, sera un miroir secondaire nommé `github`.
-Un historique contenant un secret ne doit jamais être envoyé vers ce miroir.
+Ordre de reconstruction recommandé :
 
-## License
+1. restaurer la couche système avec `arch-system` ;
+2. installer Git et GNU Stow ;
+3. cloner ce dépôt avec ses sous-modules ;
+4. restaurer les paquets officiels puis examiner les paquets AUR ;
+5. effectuer le dry-run et déployer les packages Stow ;
+6. restaurer les outils Cargo/npm et les projets locaux nécessaires ;
+7. restaurer les secrets et données applicatives depuis une sauvegarde sûre ;
+8. valider puis activer les unités systemd voulues.
+
+Le dépôt ne reconstruit pas seul les projets sous `Documents`, OpenMVS local,
+les helpers `/usr/local`, les secrets, les bases applicatives ou les réglages
+matériels propres à la machine.
+
+<a id="repository-mirrors"></a>
+
+## ✦ Repository Mirrors
+
+| Rôle | Hébergement | URL |
+| --- | --- | --- |
+| Upstream principal | Forgejo | `ssh://git@git.labfytools.com:2223/fy59/Dotfiles_ArchAP.git` |
+| Miroir public | GitHub | `https://github.com/labfytools/Dotfiles_ArchAP` |
+
+Le fetch d'`origin` reste attaché à Forgejo. Ses URLs de push publient vers
+Forgejo et GitHub afin qu'un `git push origin main` maintienne les deux copies.
+
+<a id="license"></a>
+
+## ✦ License
 
 Aucune licence n'est actuellement déclarée pour ce dépôt.