docs: establish ArchASP 0.1.0 documentation

2026-09-25 06:37:43 +02:00 · 2026-09-25 06:37:43 +02:00 · d65f798039
commit d65f798039
parent f0d39800d6
12 changed files with 809 additions and 238 deletions
--- a/README.md
+++ b/README.md
@ -1,291 +1,143 @@
 <p align="center">
-  <img src=".assets/screen.jpg" alt="ArchASP — Sway desktop" width="100%">
+  <img src="docs/assets/banner.png" alt="ArchASP Dotfiles — Reproducible Arch Linux user environment" width="100%">
 </p>

 <h1 align="center">ArchASP Dotfiles</h1>

 <p align="center">
-  Configuration utilisateur reproductible pour une station Arch Linux sous
-  Wayland, déployée package par package avec GNU Stow.
+  Environnement utilisateur Arch Linux reproductible, composé avec GNU Stow.
 </p>

 <p align="center">
-  <code>Arch Linux</code> · <code>Sway</code> · <code>GNU Stow</code> ·
-  <code>systemd --user</code> · <code>Zsh</code>
+  <img alt="Arch Linux" src="https://img.shields.io/badge/Arch_Linux-user_environment-1793d1?style=flat-square&logo=archlinux&logoColor=white">
+  <img alt="Wayland avec Sway" src="https://img.shields.io/badge/Wayland-Sway-89b4fa?style=flat-square">
+  <img alt="GNU Stow" src="https://img.shields.io/badge/deployment-GNU_Stow-cba6f7?style=flat-square">
+  <img alt="Stable 0.1.0" src="https://img.shields.io/badge/stable-0.1.0-a6e3a1?style=flat-square">
 </p>

 <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>
+  <a href="#-overview">Overview</a> ·
+  <a href="#-stack">Stack</a> ·
+  <a href="#-preview">Preview</a> ·
+  <a href="#-quick-start">Quick Start</a> ·
+  <a href="#-documentation">Documentation</a> ·
+  <a href="#-version">Version</a>
 </p>

-<a id="overview"></a>
-
 ## ✦ 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.
+`Dotfiles_ArchAP` décrit la couche **utilisateur** d'ArchASP : session Wayland,
+shell, applications terminal, scripts personnels et unités systemd user. Chaque
+package reproduit son chemin sous `$HOME` et GNU Stow déploie les liens
+symboliques correspondants.

-| Dépôt | Responsabilité |
+L'administration système reste séparée dans
+[`arch-system`](https://git.labfytools.com/fy59/arch-system) : installation
+Arch, boot, stockage, réseau, paquets, `/etc` et helpers root. Les inventaires
+de ce dépôt documentent la machine réelle, mais ne constituent pas un
+installateur automatique.
+
+## ✦ Stack
+
+| Desktop | Shell |
 | --- | --- |
-| **`.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 |
+| `greetd → tuigreet → UWSM → Sway` | `Zsh → Starship → Atuin` |
+| `Swaybar → i3status-rs` | `FZF → Zoxide → Eza → Bat → Yazi` |
+| Mako · Wofi · Swaylock · Cliphist · Kitty | plugins Zsh et Tmux épinglés par sous-modules |

-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
-              ├─ Swaybar ── i3status-rs
-              ├─ Mako       notifications
-              ├─ Wofi       launcher
-              ├─ Swaylock   verrouillage
-              ├─ Cliphist   historique du presse-papiers
-              └─ Kitty      terminal
+```mermaid
+flowchart LR
+    G[greetd] --> T[tuigreet] --> U[UWSM] --> S[Sway]
+    S --> B[Swaybar] --> I[i3status-rs]
+    S --> M[Mako]
+    S --> W[Wofi]
+    S --> L[Swaylock]
+    S --> C[Cliphist]
+    S --> K[Kitty]
 ```

-| 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` |
+Les responsabilités et dépendances sont détaillées dans
+[`docs/desktop.md`](docs/desktop.md) et [`docs/shell.md`](docs/shell.md).

-`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`.
+## ✦ Preview

-<a id="shell-stack"></a>
+<p align="center">
+  <img src="docs/assets/screenshots/archasp.png" alt="Environnement ArchASP réel sous Sway" width="100%">
+</p>

-## ✦ Shell Stack
+<p align="center"><sub>Environnement ArchASP réel — Sway, applications terminal et palette Catppuccin.</sub></p>
+
+## ✦ Repository

 ```text
-Zsh
- ├─ Starship
- ├─ Atuin
- ├─ FZF
- ├─ Zoxide
- ├─ Eza
- ├─ Bat
- └─ Yazi
+ArchASP
+├── arch-system       système/root · /etc · services système · installation
+└── Dotfiles_ArchAP   utilisateur · $HOME · Stow · systemd --user
 ```

-`.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.
+Les 31 packages Stow couvrent le desktop, le shell, le développement, les
+services utilisateur et l'apparence. `.assets/` contient les inventaires de
+reconstruction ; `docs/` contient la documentation et n'est jamais un package
+Stow. Voir le [contrat d'architecture](docs/architecture.md).

-<a id="repository-layout"></a>
+## ✦ Quick Start

-## ✦ 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
+Le chemin heureux utilise Bash pour le tableau des packages :

 ```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
-```

-### 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
-)
+packages=(atuin bat bin btop cliphist eza fastfetch fzf gtk-3.0 gtklock \
+  hyprwhspr i3status-rust icons kitty mako nvim opencode qt5ct qt6ct \
+  starship sway swaylock systemd themes tmux uwsm wallpapers wofi yazi \
+  ytmusic-tui zsh)

 stow --no --verbose=2 --target="$HOME" "${packages[@]}"
-```
-
-Examiner tout conflit avant le déploiement réel :
-
-```bash
 stow --verbose=2 --target="$HOME" "${packages[@]}"
 ```

-> Stow reçoit les **noms des packages**. La racine du dépôt n'est pas un
-> package : ne pas utiliser `stow .`.
+Le dry-run doit être examiné avant le déploiement. Les prérequis, conflits,
+inventaires et validations sont décrits dans le
+[guide d'installation](docs/installation.md).

-<a id="package-inventory"></a>
+## ✦ Documentation

-## ✦ Package Inventory
+| Guide | Sujet |
+| --- | --- |
+| [Documentation](docs/README.md) | Index et responsabilités des documents |
+| [Architecture](docs/architecture.md) | Frontières ArchASP, Stow et données locales |
+| [Installation](docs/installation.md) | Clone neuf, sous-modules, Stow et validations |
+| [Desktop](docs/desktop.md) | Chaîne greetd/UWSM/Sway et composants Wayland |
+| [Shell](docs/shell.md) | Zsh, outils interactifs, plugins et scripts |
+| [systemd](docs/systemd.md) | Services système et unités utilisateur |
+| [Packages](docs/packages.md) | Inventaires Pacman, AUR, services et outils externes |
+| [Recovery](docs/recovery.md) | Reconstruction complète après perte du disque |
+| [Security](docs/security.md) | Secrets exclus et règles de publication |

-| 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` |
+## ✦ Mirrors

-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.
+| Rôle | Dépôt |
+| --- | --- |
+| Upstream principal | [Forgejo](https://git.labfytools.com/fy59/Dotfiles_ArchAP) |
+| Miroir public | [GitHub](https://github.com/labfytools/Dotfiles_ArchAP) |

-<a id="services"></a>
+Le fetch d'`origin` reste attaché à Forgejo. Ses deux URLs de push publient
+vers Forgejo et GitHub.

-## ✦ Services
+## ✦ Version

-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.
+| Branche | Rôle |
+| --- | --- |
+| `0.1.0` | Snapshot stable de la première version nettoyée et documentée |
+| `main` | Développement courant |

-Après une modification :
-
-```bash
-systemctl --user daemon-reload
-systemd-analyze --user verify ~/.config/systemd/user/*.service
-```
-
-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`.
-
-<a id="secrets"></a>
-
-## ✦ Secrets
-
-Ce dépôt n'a pas vocation à contenir :
-
- 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.
-
-Les ignorer dans le HEAD ne suffit pas : un secret déjà commité doit être
-renouvelé, puis supprimé de tout l'historique avant publication.
-
-<a id="rebuilding-archasp"></a>
-
-## ✦ Rebuilding ArchASP
-
-```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│
-└──────────────────────────────────────────────────────┘
-```
-
-Ordre de reconstruction recommandé :
-
-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>
+La branche stable est immobile : les développements suivants avancent sur
+`main` sans déplacer automatiquement `0.1.0`.

 ## ✦ License

-Aucune licence n'est actuellement déclarée pour ce dépôt.
+Aucune licence n'est actuellement déclarée pour ce dépôt. En l'absence de
+licence, aucun droit de réutilisation n'est accordé implicitement.
--- a/docs/README.md
+++ b/docs/README.md
@ -0,0 +1,42 @@
+# Documentation ArchASP Dotfiles
+
+Cet index répartit la documentation par responsabilité. Le `README.md` racine
+est la page d'accueil ; les pages ci-dessous portent les procédures et les
+limites détaillées.
+
+## Commencer ici
+
+| Document | Responsabilité |
+| --- | --- |
+| [Architecture](architecture.md) | Séparation `arch-system` / dotfiles, contrat Stow et frontières de propriété |
+| [Installation](installation.md) | Déploiement depuis un clone neuf et contrôles associés |
+| [Recovery](recovery.md) | Reconstruction complète après perte de la machine |
+
+## Environnement utilisateur
+
+| Document | Responsabilité |
+| --- | --- |
+| [Desktop](desktop.md) | Session greetd/UWSM/Sway et composants Wayland canoniques |
+| [Shell](shell.md) | Zsh, outils interactifs, plugins et scripts utilisateur |
+| [systemd](systemd.md) | Limite système/user, unités et activations utilisateur |
+
+## Inventaires et sécurité
+
+| Document | Responsabilité |
+| --- | --- |
+| [Packages](packages.md) | Snapshots Pacman/AUR, services et dépendances externes |
+| [Security](security.md) | Données interdites dans Git et règles de contrôle |
+
+## Règle de propriété
+
+Une information détaillée possède une page principale. Le README racine la
+résume et pointe vers cette page ; il ne doit pas recopier l'intégralité des
+procédures. Les fichiers de `.assets/` sont des inventaires factuels, pas une
+deuxième documentation normative ni un installateur.
+
+## Portée de la version 0.1.0
+
+`0.1.0` est le snapshot stable de la première version nettoyée, documentée et
+publiée. `main` demeure la branche de développement. La documentation décrit
+l'état de ce snapshot ; toute évolution ultérieure doit être portée par
+`main` avant une éventuelle nouvelle branche stable.
--- a/docs/architecture.md
+++ b/docs/architecture.md
@ -0,0 +1,86 @@
+# Architecture
+
+## Contrat global
+
+ArchASP sépare volontairement la couche système de la couche utilisateur.
+
+```mermaid
+flowchart TB
+    A[ArchASP] --> S[arch-system]
+    A --> D[Dotfiles_ArchAP]
+    S --> SR[Installation Arch · boot · stockage · réseau]
+    S --> SE[/etc · services système · helpers root]
+    D --> DH[$HOME · configuration utilisateur]
+    D --> DU[Stow · systemd --user · scripts]
+```
+
+| Couche | Possède | Ne possède pas |
+| --- | --- | --- |
+| `arch-system` | installation, partitions, boot, paquets de base, `/etc`, greetd installé, services système, helpers `/usr/local` | préférences et fichiers sous `$HOME` |
+| `Dotfiles_ArchAP` | session utilisateur, shell, applications terminal, scripts, thèmes, unités `systemd --user` | configuration root, secrets, données applicatives |
+
+La copie de référence de greetd située dans `.assets/greetd/config.toml`
+documente l'intégration, mais son installation dans `/etc/greetd` appartient
+à `arch-system`.
+
+## Contrat GNU Stow
+
+Chaque package de premier niveau reproduit une arborescence relative à
+`$HOME`. GNU Stow crée les liens symboliques ; le dépôt reste la source du
+fichier versionné.
+
+```mermaid
+flowchart LR
+    P[kitty/.config/kitty/kitty.conf] -->|stow kitty| H[~/.config/kitty/kitty.conf]
+    Z[zsh/.zshrc] -->|stow zsh| R[~/.zshrc]
+    U[systemd/.config/systemd/user/] -->|stow systemd| Y[~/.config/systemd/user/]
+```
+
+Exemples de correspondance :
+
+| Source versionnée | Cible utilisateur |
+| --- | --- |
+| `sway/.config/sway/` | `~/.config/sway/` |
+| `i3status-rust/.config/i3status-rust/` | `~/.config/i3status-rust/` |
+| `bin/.local/bin/` | `~/.local/bin/` |
+| `zsh/.zprofile` | `~/.zprofile` |
+| `wallpapers/.wallpapers/` | `~/.wallpapers/` |
+
+Les packages Stow sont une liste explicite de 31 noms, détaillée dans le
+[guide d'installation](installation.md). Il ne faut pas déduire cette liste de
+tous les répertoires de premier niveau : `.assets/` et `docs/` ne sont pas des
+packages. Il ne faut jamais exécuter `stow .`.
+
+## Frontières de propriété
+
+### Dans les dotfiles
+
+- configuration déclarative sous `$HOME` ;
+- scripts personnels déployés dans `~/.local/bin` ;
+- unités et liens d'activation `systemd --user` ;
+- thèmes, icônes et fonds d'écran nécessaires à l'environnement ;
+- inventaires de reconstruction sous `.assets/` ;
+- références Git des plugins Zsh et Tmux via sous-modules.
+
+### Dans `arch-system`
+
+- opérations privilégiées et fichiers sous `/etc` ;
+- activation des services système, dont greetd ;
+- configuration du boot, du stockage, du réseau et de la sécurité système ;
+- helpers locaux sous `/usr/local` ;
+- restauration initiale des paquets sur une installation minimale.
+
+### Dans les projets externes
+
+Trainlog, Lardon, Arch Sentinel, OpenMVS et les autres projets locaux gardent
+leur code, leurs builds et leurs données dans leurs propres dépôts. Les
+dotfiles peuvent référencer leurs commandes ou unités, sans en devenir la
+source. Les chemins attendus sont inventoriés dans
+[`external-tools.md`](../.assets/external-tools.md).
+
+### Machine-local ou secret
+
+Les bases applicatives, caches, historiques, identités SSH/GPG, clés Atuin,
+tokens, cookies et credentials ne sont ni des dotfiles ni des dépendances à
+publier. Ils doivent être restaurés séparément depuis une sauvegarde sûre. La
+[politique de sécurité](security.md) détaille cette frontière.
--- a/docs/assets/banner.png
+++ b/docs/assets/banner.png
--- a/docs/assets/screenshots/archasp.png
+++ b/docs/assets/screenshots/archasp.png
--- a/docs/desktop.md
+++ b/docs/desktop.md
@ -0,0 +1,72 @@
+# Desktop
+
+## Stack canonique
+
+```mermaid
+flowchart LR
+    G[greetd] --> T[tuigreet]
+    T --> U[UWSM]
+    U --> S[Sway]
+    S --> B[Swaybar]
+    B --> I[i3status-rs]
+    S --> M[Mako]
+    S --> W[Wofi]
+    S --> L[Swaylock]
+    S --> C[Cliphist]
+    S --> K[Kitty]
+```
+
+| Composant | Responsabilité | Propriété |
+| --- | --- | --- |
+| greetd | gestionnaire de connexion système | installé/configuré par `arch-system` |
+| tuigreet | interface terminal de greetd | paquet système ; commande référencée par greetd |
+| UWSM | cycle de vie de la session Wayland | package Stow `uwsm` et paquet système |
+| Sway | compositeur et configuration de session | package `sway` |
+| Swaybar | barre native de Sway | bloc `bar` de la configuration Sway |
+| i3status-rs | contenu et modules de la barre | package `i3status-rust` |
+| Mako | notifications Wayland | package `mako` |
+| Wofi | lanceur d'applications | package `wofi` |
+| Swaylock | verrouillage | package `swaylock`, appelé par les bindings et swayidle |
+| Cliphist | historique texte/image du presse-papiers | package `cliphist` et unités user |
+| Kitty | terminal principal | package `kitty` |
+
+La configuration `uwsm/.config/uwsm/default-id` sélectionne `sway.desktop`.
+La référence greetd de `.assets/greetd/config.toml` démarre la chaîne système,
+mais sa copie dans `/etc` ne relève pas des dotfiles.
+
+## Session Sway
+
+Le package `sway` sépare la configuration principale, les bindings, les règles,
+le style, la barre, l'autostart et les scripts. Swaybar exécute :
+
+```text
+i3status-rs ~/.config/i3status-rust/config.toml
+```
+
+Les scripts locaux sous `~/.config/sway/scripts` restent propres à la session.
+Les commandes sous `~/.local/bin` sont fournies par le package `bin` ou, quand
+cela est documenté, par un projet externe.
+
+## Services de session
+
+- `cliphist-text.service` et `cliphist-image.service` observent `wl-paste` ;
+- `swayidle.service` verrouille, éteint/rallume les sorties et suspend les
+  lecteurs selon les délais configurés ;
+- `wlsunset.service` gère la température de couleur ;
+- `gnome-keyring-daemon.service` et `ssh-agent.service` fournissent les agents
+  de session ;
+- Mako est le fournisseur de notifications retenu.
+
+Les unités attachées à `graphical-session.target` ne remplacent pas UWSM :
+elles consomment le cycle de vie de la session qu'UWSM expose à systemd user.
+
+## Dépendances visibles
+
+Les bindings Sway appellent notamment `pactl`, `brightnessctl`, `grim`,
+`slurp`, `wl-copy`, `wofi`, `swaylock`, `yazi` et des scripts de
+`~/.local/bin`. Les programmes spécifiques à des projets ou à la machine sont
+inventoriés dans [`external-tools.md`](../.assets/external-tools.md).
+
+Les anciens choix Mango, Waybar, SwayNC et Wlogout ne font pas partie de la
+stack supportée. Leur éventuelle présence comme paquet installé ne leur donne
+aucun rôle dans l'architecture actuelle.
--- a/docs/installation.md
+++ b/docs/installation.md
@ -0,0 +1,133 @@
+# Installation
+
+Ce guide déploie la couche utilisateur depuis un clone neuf. Il n'installe pas
+Arch Linux, ne modifie pas `/etc` et n'automatise pas les dépendances externes.
+Pour une reconstruction complète, commencer par [Recovery](recovery.md).
+
+## 1. Prérequis
+
+- une installation ArchASP dont la couche système est prête ;
+- un compte utilisateur et un `$HOME` sauvegardé avant tout remplacement ;
+- Git, GNU Stow et Bash ;
+- un accès au dépôt Forgejo ou au miroir GitHub ;
+- les paquets examinés dans les inventaires de `.assets/`.
+
+Vérifier les outils avant de continuer :
+
+```bash
+git --version
+stow --version
+bash --version
+```
+
+## 2. Cloner
+
+Forgejo est l'upstream principal :
+
+```bash
+git clone --recurse-submodules \
+  ssh://git@git.labfytools.com:2223/fy59/Dotfiles_ArchAP.git \
+  "$HOME/.dotfiles"
+cd "$HOME/.dotfiles"
+```
+
+Le miroir public peut servir de source de récupération :
+
+```bash
+git clone --recurse-submodules \
+  https://github.com/labfytools/Dotfiles_ArchAP.git \
+  "$HOME/.dotfiles"
+cd "$HOME/.dotfiles"
+```
+
+Pour restaurer le snapshot stable plutôt que `main` :
+
+```bash
+git switch 0.1.0
+```
+
+## 3. Vérifier les sous-modules
+
+```bash
+git submodule update --init --recursive
+git submodule status --recursive
+```
+
+Une ligne commençant par `-` indique un sous-module non initialisé ; une ligne
+commençant par `+` indique un commit différent de celui épinglé.
+
+## 4. Examiner les inventaires
+
+Les listes Pacman et AUR sont des snapshots, pas des commandes aveugles à
+installer. Comparer leur contenu à la machine cible et lire
+[`packages.md`](packages.md) ainsi que
+[`external-tools.md`](../.assets/external-tools.md) avant toute installation.
+
+## 5. Définir les 31 packages Stow
+
+Les commandes suivantes sont destinées à Bash :
+
+```bash
+packages=(
+  atuin bat bin btop cliphist eza fastfetch fzf gtk-3.0 gtklock
+  hyprwhspr i3status-rust icons kitty mako nvim opencode qt5ct qt6ct
+  starship sway swaylock systemd themes tmux uwsm wallpapers wofi yazi
+  ytmusic-tui zsh
+)
+
+printf '%s\n' "${packages[@]}"
+```
+
+`docs/` et `.assets/` ne doivent pas être ajoutés à ce tableau.
+
+## 6. Effectuer le dry-run
+
+Depuis la racine du dépôt :
+
+```bash
+stow --no --verbose=2 --target="$HOME" "${packages[@]}"
+```
+
+Lire chaque conflit. Un fichier réel déjà présent à la cible peut masquer ou
+bloquer un lien Stow ; le sauvegarder et décider explicitement de sa source
+avant le déploiement. Ne pas utiliser d'option d'adoption sans audit préalable.
+
+## 7. Déployer
+
+Une fois le dry-run accepté :
+
+```bash
+stow --verbose=2 --target="$HOME" "${packages[@]}"
+```
+
+Cette commande crée ou met à jour des liens sous `$HOME`. Elle ne doit pas être
+exécutée depuis une autre racine ni avec `.` comme nom de package.
+
+## 8. Recharger systemd user
+
+Les liens d'activation versionnés dans le package `systemd` expriment les
+unités utilisateur attendues. Recharger et vérifier avant tout démarrage :
+
+```bash
+systemctl --user daemon-reload
+systemd-analyze --user verify \
+  "$HOME"/.config/systemd/user/*.service \
+  "$HOME"/.config/systemd/user/*.timer
+systemctl --user --failed
+```
+
+Certaines unités dépendent de projets externes. Ne les démarrer que lorsque
+leurs chemins et configurations locales existent ; voir [`systemd.md`](systemd.md).
+
+## 9. Valider
+
+```bash
+git status --short
+git submodule status --recursive
+find "$HOME/.config" -xtype l -print
+systemctl --user --failed
+sway --validate --config "$HOME/.config/sway/config"
+```
+
+La dernière commande nécessite Sway installé. Un lien cassé ou une unité en
+échec doit être diagnostiqué avant de considérer la restauration terminée.
--- a/docs/packages.md
+++ b/docs/packages.md
@ -0,0 +1,64 @@
+# Packages et inventaires
+
+Les fichiers de `.assets/` sont des snapshots de reconstruction. Ils décrivent
+l'état observé ; ils ne garantissent ni l'ordre d'installation ni la présence
+des données et projets externes.
+
+## Inventaires
+
+| Fichier | Contenu | Source principale |
+| --- | --- | --- |
+| `.assets/pkglist-pacman.txt` | paquets officiels explicitement installés | `pacman -Qqen` |
+| `.assets/pkglist-aur.txt` | paquets foreign/AUR explicitement installés | `pacman -Qqem` |
+| `.assets/enabled-services.txt` | services système activés | `systemctl list-unit-files` |
+| `.assets/enabled-system-aux-units.txt` | timers, sockets et paths système activés | `systemctl list-unit-files` |
+| `.assets/enabled-user-aux-units.txt` | timers, sockets et paths utilisateur activés | `systemctl --user list-unit-files` |
+| [`.assets/external-tools.md`](../.assets/external-tools.md) | outils Cargo/npm, builds, projets et helpers locaux | inventaire manuel vérifié |
+
+## Régénérer les listes de paquets
+
+Depuis la racine du dépôt, après avoir contrôlé que la machine représente bien
+l'état à documenter :
+
+```bash
+pacman -Qqen | LC_ALL=C sort > .assets/pkglist-pacman.txt
+pacman -Qqem | LC_ALL=C sort > .assets/pkglist-aur.txt
+```
+
+`pkglist-aur.txt` signifie techniquement « paquets étrangers à la base de
+données sync ». Il peut contenir un paquet construit localement et pas
+nécessairement publié dans l'AUR. Chaque entrée doit donc être examinée.
+
+## Régénérer les snapshots systemd
+
+```bash
+systemctl list-unit-files --type=service --state=enabled \
+  --no-legend --no-pager | awk '{print $1}' | LC_ALL=C sort
+
+systemctl list-unit-files --type=socket,path,timer --state=enabled \
+  --no-legend --no-pager | awk '{print $1}' | LC_ALL=C sort
+
+systemctl --user list-unit-files --type=socket,path,timer --state=enabled \
+  --no-legend --no-pager | awk '{print $1}' | LC_ALL=C sort
+```
+
+Comparer d'abord la sortie aux fichiers versionnés. Certaines unités
+instanciées ou activations liées à la machine peuvent demander une revue
+manuelle ; ne pas remplacer un inventaire uniquement parce qu'une commande
+instantanée diffère.
+
+## Restaurer avec discernement
+
+Les listes peuvent aider à préparer une commande Pacman, mais le dépôt ne
+promet pas une restauration non interactive. Sur une machine neuve :
+
+1. restaurer d'abord la base système via `arch-system` ;
+2. examiner les paquets officiels encore voulus ;
+3. reconstruire les paquets étrangers avec une source AUR ou locale vérifiée ;
+4. restaurer séparément les outils Cargo/npm de
+   [`.assets/external-tools.md`](../.assets/external-tools.md) ;
+5. reconstruire ou cloner les projets externes à leurs chemins attendus ;
+6. vérifier les exécutables référencés par Sway, Zsh, les scripts et systemd.
+
+Les credentials, bases applicatives et caches ne doivent jamais être ajoutés
+aux inventaires de paquets.
--- a/docs/recovery.md
+++ b/docs/recovery.md
@ -0,0 +1,113 @@
+# Recovery — reconstruire ArchASP
+
+> **Question :** mon SSD meurt aujourd'hui. Comment reconstruire ArchASP ?
+
+Les deux dépôts reconstruisent la configuration déclarative, pas l'intégralité
+des données personnelles. Une sauvegarde séparée reste indispensable pour les
+secrets, bases, documents et états applicatifs.
+
+## 1. Installer un Arch Linux minimal
+
+Créer le système de fichiers, installer le système de base et obtenir un
+environnement démarrable avec réseau. Cette phase ne relève pas de
+`Dotfiles_ArchAP`.
+
+## 2. Restaurer `arch-system`
+
+Cloner le dépôt système et suivre sa procédure pour le boot, le stockage, le
+réseau, les paquets fondamentaux, `/etc`, greetd, les services système et les
+helpers root. Ne pas copier simplement `.assets/greetd/config.toml` sans suivre
+le contrat système.
+
+## 3. Restaurer `Dotfiles_ArchAP`
+
+Cloner l'upstream Forgejo ou, s'il est indisponible, le miroir GitHub :
+
+```bash
+git clone --recurse-submodules \
+  https://github.com/labfytools/Dotfiles_ArchAP.git \
+  "$HOME/.dotfiles"
+cd "$HOME/.dotfiles"
+git switch 0.1.0
+git submodule update --init --recursive
+```
+
+La branche `0.1.0` donne le snapshot stable ; `main` est la branche de
+développement.
+
+## 4. Restaurer les paquets officiels
+
+Comparer `.assets/pkglist-pacman.txt` avec le socle déjà installé par
+`arch-system`. Installer uniquement les entrées encore pertinentes et éviter
+de transformer une capture historique en commande aveugle.
+
+## 5. Restaurer les paquets AUR/foreign
+
+Examiner chaque entrée de `.assets/pkglist-aur.txt`, retrouver sa source et la
+reconstruire avec un processus AUR maîtrisé. Les paquets locaux ou disparus
+exigent une décision spécifique ; aucun helper AUR n'est supposé magique.
+
+## 6. Déployer Stow
+
+Suivre le [guide d'installation](installation.md) : définir explicitement les
+31 packages, exécuter le dry-run, résoudre les conflits, puis seulement lancer
+le déploiement réel. `docs/` et `.assets/` ne sont pas déployés.
+
+## 7. Restaurer les services
+
+- recharger et vérifier `systemd --user` ;
+- confirmer les liens d'activation versionnés ;
+- ne démarrer les unités de projets externes qu'après restauration de leurs
+  exécutables et configurations ;
+- restaurer les services système à partir d'`arch-system`, en utilisant les
+  snapshots `.assets/enabled-*.txt` comme contrôle croisé.
+
+## 8. Restaurer les projets externes
+
+Cloner ou reconstruire les projets et outils listés dans
+[`external-tools.md`](../.assets/external-tools.md), notamment Trainlog,
+Lardon, Arch Sentinel et les outils 3D locaux. Recréer leurs builds et liens
+utilisateur selon leurs propres instructions. Le dépôt de dotfiles ne contient
+pas leur code.
+
+## 9. Restaurer les secrets et données
+
+Depuis une sauvegarde chiffrée et hors Git, restaurer selon le besoin :
+
+- identités SSH et GPG ;
+- clé et store Atuin locaux ;
+- credentials Rclone, GitHub CLI, Nextcloud et applications ;
+- bases Trainlog et autres données applicatives ;
+- documents personnels et états non reconstructibles.
+
+Ne copier aucun de ces éléments dans le dépôt. Vérifier leurs permissions
+avant de lancer les applications.
+
+## 10. Valider
+
+```bash
+git -C "$HOME/.dotfiles" status --short
+git -C "$HOME/.dotfiles" submodule status --recursive
+find "$HOME" -xtype l -print
+systemctl --failed
+systemctl --user --failed
+sway --validate --config "$HOME/.config/sway/config"
+```
+
+Contrôler ensuite le login greetd/tuigreet, le démarrage UWSM/Sway, Swaybar,
+i3status-rs, les notifications, le verrouillage, le presse-papiers, Kitty et
+un nouveau shell Zsh.
+
+## Limites actuelles
+
+Une reconstruction à partir des seuls dépôts ne restitue pas :
+
+- secrets, historiques et bases applicatives ;
+- contenu des projets sous `~/Documents` ;
+- builds locaux, outils Cargo/npm et OpenMVS ;
+- helpers `/usr/local` si `arch-system` ne les recrée pas encore ;
+- réglages matériels spécifiques non documentés ;
+- paquets AUR disparus ou devenus incompatibles.
+
+La récupération est donc **documentée et largement reproductible**, mais pas
+une image complète et autonome du disque.
--- a/docs/security.md
+++ b/docs/security.md
@ -0,0 +1,69 @@
+# Sécurité
+
+## Politique de versionnement
+
+Ne jamais versionner, même temporairement :
+
+- clés Atuin et bases/store Atuin ;
+- clés privées SSH ;
+- clés privées GPG ;
+- tokens et clés API ;
+- mots de passe et cookies ;
+- `.netrc` ;
+- credentials Rclone ;
+- credentials GitHub ou Forgejo ;
+- secrets Nextcloud ;
+- credentials Proton, WireGuard ou autres applications ;
+- bases applicatives et historiques personnels.
+
+Un `.gitignore` limite les erreurs courantes, mais ne constitue pas une
+protection suffisante. Avant chaque publication, inspecter le diff, les
+nouveaux fichiers et les motifs de credentials sans jamais afficher leur
+valeur dans un rapport.
+
+## Stockage local
+
+Les secrets et données runtime appartiennent à la machine locale ou à une
+sauvegarde chiffrée externe. Ils ne doivent pas être placés dans un package
+Stow public. Les permissions doivent être restrictives, particulièrement pour
+les clés privées, `.netrc`, stores de credentials et clé Atuin.
+
+Les unités ou scripts peuvent référencer le chemin d'une configuration locale,
+mais ne doivent ni embarquer son contenu ni journaliser ses secrets.
+
+## Historique Git
+
+Supprimer un fichier du dernier commit ne le retire pas des anciens objets
+Git. Lorsqu'un secret a été commité, la réponse correcte est :
+
+1. considérer le secret comme compromis ;
+2. le révoquer ou le faire tourner ;
+3. préserver les sauvegardes nécessaires hors dépôt ;
+4. purger le chemin de tout l'historique ;
+5. vérifier les objets et toutes les refs avant publication.
+
+L'historique de `Dotfiles_ArchAP` a été assaini pendant la préparation de la
+version `0.1.0`, notamment pour retirer les anciennes données locales qui ne
+devaient pas être publiées. Cette mention ne révèle ni ancienne valeur, ni
+empreinte sensible, ni emplacement de sauvegarde.
+
+## Contrôles avant publication
+
+```bash
+git status --short
+git diff --check
+git diff --cached --check
+git fsck --full --no-dangling
+```
+
+Compléter ces contrôles par une recherche prudente de types de secrets dans le
+HEAD et l'historique. Les rapports doivent seulement indiquer le fichier, le
+type potentiel, sa présence actuelle ou historique et l'action recommandée ;
+ils ne doivent jamais reproduire la valeur détectée.
+
+## Dépôt public et licence
+
+Le miroir GitHub est public. Toute donnée commitée doit donc être considérée
+comme publiable immédiatement. Le dépôt ne possède actuellement aucune
+licence ; cette absence n'autorise pas implicitement la réutilisation du
+contenu.
--- a/docs/shell.md
+++ b/docs/shell.md
@ -0,0 +1,77 @@
+# Shell
+
+## Chaîne interactive
+
+```mermaid
+flowchart LR
+    Z[Zsh] --> S[Starship]
+    Z --> A[Atuin]
+    Z --> F[FZF]
+    Z --> X[Zoxide]
+    Z --> E[Eza]
+    Z --> B[Bat]
+    Z --> Y[Yazi]
+```
+
+| Élément | Rôle |
+| --- | --- |
+| Zsh | shell interactif et point d'intégration |
+| Starship | prompt configuré par `starship/.config/starship.toml` |
+| Atuin | recherche d'historique local ; base et clé exclues de Git |
+| FZF | sélection interactive et prévisualisations |
+| Zoxide | navigation par fréquence |
+| Eza | affichage enrichi des répertoires |
+| Bat | lecture et prévisualisation colorée |
+| Yazi | gestionnaire de fichiers terminal |
+
+`.zprofile` initialise la session graphique via UWSM lorsque son contexte le
+permet. `.zshenv` publie le socket de l'agent SSH utilisateur. `.zshrc` charge
+les intégrations interactives, aliases et fonctions.
+
+## Plugins Zsh et Tmux
+
+Les plugins ne sont pas téléchargés à chaque ouverture du shell. Git épingle
+leurs commits comme sous-modules :
+
+| Intégration | Chemin versionné |
+| --- | --- |
+| 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` |
+
+Initialisation et contrôle :
+
+```bash
+git submodule update --init --recursive
+git submodule status --recursive
+```
+
+La configuration Zsh vérifie la lisibilité des fichiers de plugins avant de
+les sourcer. Le dépôt parent, et non une commande lancée au démarrage du shell,
+reste propriétaire des versions.
+
+## Scripts utilisateur
+
+Le package `bin` déploie des commandes dans `~/.local/bin`. Les familles
+principales sont :
+
+- maintenance Pacman/AUR (`aurinstall`, `aurremove`, `aursearch`, `aurupdate`) ;
+- énergie et batterie (`batlimit`, `battery-low-notify.sh`, `tlp-profile.sh`) ;
+- session et applications (`sway-close`, `thunderbird-proton`,
+  `vmware-on-demand`, `nextcloud-sync`) ;
+- développement local (`dcnvim`, `goose`, `pi-dev`, `opencode-away`) ;
+- acquisition/3D (`colmap-amd`, `scan3d`, `scan3d-watch`) ;
+- intégrations Trainlog (`trainlog-bt-watch`) et autres projets locaux.
+
+Ces scripts orchestrent des outils existants ; ils ne fournissent pas les
+projets externes, credentials ou binaires système qu'ils appellent. Consulter
+[`external-tools.md`](../.assets/external-tools.md) avant de les réutiliser sur
+une autre machine.
+
+## Données locales
+
+L'historique Zsh et le store Atuin sont des données utilisateur, pas de la
+configuration. La clé, la base, les sessions et tout identifiant Atuin restent
+hors Git. Cette installation utilise Atuin localement ; aucune procédure de
+compte ou de synchronisation distante n'est requise par le dépôt.
--- a/docs/systemd.md
+++ b/docs/systemd.md
@ -0,0 +1,63 @@
+# systemd
+
+## Deux périmètres distincts
+
+| Périmètre | Commande | Propriété |
+| --- | --- | --- |
+| système | `systemctl ...` | `arch-system`, `/etc/systemd/system`, services root |
+| utilisateur | `systemctl --user ...` | package Stow `systemd`, `~/.config/systemd/user` |
+
+Le dépôt conserve dans `.assets/enabled-services.txt` et
+`.assets/enabled-system-aux-units.txt` des snapshots de la couche système,
+mais il ne l'active pas. Les unités effectivement versionnées sous
+`systemd/.config/systemd/user/` appartiennent à la couche utilisateur.
+
+## Unités utilisateur canoniques
+
+| Domaine | Unités | Fonction |
+| --- | --- | --- |
+| session | `gnome-keyring-daemon.service`, `ssh-agent.service`, `wlsunset.service` | agents et services de session |
+| clipboard | `cliphist-text.service`, `cliphist-image.service` | collecte texte et images Wayland |
+| idle | `swayidle.service` | verrouillage, alimentation des sorties et pause média |
+| batterie | `battery-low-notify.service/.timer` | contrôle et notification périodiques |
+| maintenance | `clean-makepkg.service` | nettoyage du cache temporaire utilisateur |
+| Arch Sentinel | `arch-sentinel-sample.service/.timer` | collecte périodique légère |
+| Trainlog | `trainlog-btd.service`, `trainlog-syncd.service`, `trainlog-web.service` | intégrations locales facultatives |
+| Lardon | `lardon-freecad.service` | session FreeCAD liée au projet externe |
+| autres | `hyprwhspr.service`, `protonmail-bridge.service` | intégrations déclenchées selon l'usage |
+
+Les liens versionnés dans `default.target.wants/`,
+`graphical-session.target.wants/` et `timers.target.wants/` expriment les
+activations utilisateur retenues. `.assets/enabled-user-aux-units.txt` capture
+en complément les timers et sockets activés observés sur la machine.
+
+## Dépendances externes
+
+Les unités Trainlog, Lardon et Arch Sentinel supposent que leurs projets ou
+binaires existent aux chemins décrits dans
+[`external-tools.md`](../.assets/external-tools.md).
+Certaines unités Trainlog sont conditionnées par une configuration locale.
+Ces fichiers de configuration et leurs éventuels secrets ne sont pas
+versionnés.
+
+Une unité absente du projet externe peut rester valide syntaxiquement tout en
+échouant à l'exécution. La restauration doit donc vérifier à la fois le fichier
+d'unité et son `ExecStart`.
+
+## Validation
+
+Après déploiement Stow :
+
+```bash
+systemctl --user daemon-reload
+systemd-analyze --user verify \
+  "$HOME"/.config/systemd/user/*.service \
+  "$HOME"/.config/systemd/user/*.timer
+systemctl --user list-unit-files --state=enabled
+systemctl --user --failed
+```
+
+Ne pas lancer ou activer en bloc toutes les unités : celles liées à des
+projets externes sont facultatives et peuvent exiger une configuration locale.
+Les modifications des services système se font dans `arch-system`, jamais par
+une commande `systemctl` non documentée dans ce dépôt.