diff --git a/README.fr.md b/README.fr.md
index 773ffc1..5cf77c8 100644
--- a/README.fr.md
+++ b/README.fr.md
@@ -96,6 +96,8 @@ powershell -ExecutionPolicy Bypass -File .\powershell\Configure-FirefoxDefaults.
Le script écrit les policies Firefox, force l'installation de uBlock Origin depuis Mozilla Add-ons, configure les paramètres gérés de uBlock Origin et importe les associations d'applications Windows par défaut pour les futurs utilisateurs.
+Documentation détaillée : [configuration Firefox ESR et uBlock Origin](./docs/firefox-ublock.md).
+
## 🧹 Supprimer des Applications Intégrées
Utilise le script de nettoyage Appx pour supprimer certaines applications intégrées sans winget et limiter leur reprovisionnement pour les nouveaux utilisateurs.
diff --git a/README.md b/README.md
index c9d7d6e..0af94c1 100644
--- a/README.md
+++ b/README.md
@@ -96,6 +96,8 @@ powershell -ExecutionPolicy Bypass -File .\powershell\Configure-FirefoxDefaults.
The script writes Firefox enterprise policies, force-installs uBlock Origin from Mozilla Add-ons, configures managed uBlock Origin defaults and imports Windows default app associations for future users.
+More details: [Firefox ESR and uBlock Origin configuration](./docs/firefox-ublock.md).
+
## 🧹 Remove Built-In Apps
Use the Appx cleanup script when you want to remove selected built-in applications without winget and reduce reprovisioning for newly created users.
diff --git a/docs/firefox-ublock.md b/docs/firefox-ublock.md
new file mode 100644
index 0000000..c1ec04f
--- /dev/null
+++ b/docs/firefox-ublock.md
@@ -0,0 +1,210 @@
+# Configuration Firefox ESR et uBlock Origin
+
+Cette page documente la configuration appliquee par
+[`powershell/Configure-FirefoxDefaults.ps1`](../powershell/Configure-FirefoxDefaults.ps1).
+
+Le but est de preparer Firefox ESR pour tous les utilisateurs Windows, y compris
+les futurs profils :
+
+- Firefox ESR devient le navigateur par defaut pour `.htm`, `.html`, `http` et `https`.
+- uBlock Origin est installe automatiquement depuis Mozilla Add-ons.
+- uBlock Origin recoit une configuration geree commune a tous les profils Firefox.
+
+## Execution
+
+Lance le script dans un terminal PowerShell administrateur, apres installation de
+Firefox ESR :
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\powershell\Configure-FirefoxDefaults.ps1
+```
+
+Le script est aussi appele automatiquement par
+[`powershell/libres-softwares-install.ps1`](../powershell/libres-softwares-install.ps1)
+quand Firefox ESR est installe via l'installateur interactif.
+
+## Fichiers et cles crees
+
+Le script ecrit un fichier `policies.json` dans le dossier d'installation Firefox :
+
+```text
+C:\Program Files\Mozilla Firefox\distribution\policies.json
+```
+
+Selon l'installation, le dossier peut etre sous `Program Files (x86)`.
+
+Le script ecrit aussi un fichier XML d'associations Windows :
+
+```text
+C:\ProgramData\WindowsLibreSoftwareToolkit\FirefoxDefaultAssociations.xml
+```
+
+Puis il configure la policy Windows :
+
+```text
+HKLM\SOFTWARE\Policies\Microsoft\Windows\System
+ DefaultAssociationsConfiguration
+```
+
+Enfin, il importe les associations par defaut pour les futurs utilisateurs avec :
+
+```powershell
+dism.exe /Online /Import-DefaultAppAssociations:C:\ProgramData\WindowsLibreSoftwareToolkit\FirefoxDefaultAssociations.xml
+```
+
+## Policies Firefox
+
+Firefox lit les policies machine au demarrage. Le fichier `policies.json` genere
+contient principalement :
+
+```json
+{
+ "policies": {
+ "DontCheckDefaultBrowser": true,
+ "DisableDefaultBrowserAgent": true,
+ "ExtensionSettings": {
+ "uBlock0@raymondhill.net": {
+ "installation_mode": "force_installed",
+ "install_url": "https://addons.mozilla.org/firefox/downloads/latest/ublock-origin/latest.xpi"
+ }
+ }
+ }
+}
+```
+
+`ExtensionSettings` force l'installation de uBlock Origin pour chaque profil
+Firefox. Si l'extension est supprimee ou absente, Firefox la reinstalle au
+demarrage suivant.
+
+L'identifiant officiel de l'extension Firefox est :
+
+```text
+uBlock0@raymondhill.net
+```
+
+## Configuration geree uBlock Origin
+
+La configuration uBlock Origin passe par la policy Firefox `3rdparty`.
+Firefox expose ensuite ces valeurs a l'extension via `storage.managed`.
+
+Extrait simplifie :
+
+```json
+{
+ "policies": {
+ "3rdparty": {
+ "Extensions": {
+ "uBlock0@raymondhill.net": {
+ "adminSettings": {
+ "selectedFilterLists": [
+ "user-filters",
+ "ublock-filters",
+ "ublock-badware",
+ "ublock-privacy",
+ "ublock-abuse",
+ "ublock-unbreak",
+ "ublock-quick-fixes",
+ "easylist",
+ "easyprivacy",
+ "urlhaus-1",
+ "plowe-0"
+ ],
+ "userSettings": {
+ "advancedUserEnabled": false,
+ "cloudStorageEnabled": false,
+ "contextMenuEnabled": true,
+ "showIconBadge": true
+ }
+ }
+ }
+ }
+ }
+ }
+}
+```
+
+## Listes de filtres activees
+
+| Liste | Role |
+| --- | --- |
+| `user-filters` | Reserve les filtres utilisateur. |
+| `ublock-filters` | Filtres principaux uBlock Origin. |
+| `ublock-badware` | Protection contre domaines malveillants. |
+| `ublock-privacy` | Protection vie privee. |
+| `ublock-abuse` | Protection contre abus et nuisances. |
+| `ublock-unbreak` | Corrections de compatibilite. |
+| `ublock-quick-fixes` | Correctifs rapides publies par uBlock Origin. |
+| `easylist` | Liste anti-publicite generaliste. |
+| `easyprivacy` | Liste anti-tracking generaliste. |
+| `urlhaus-1` | Blocage de domaines malveillants URLhaus. |
+| `plowe-0` | Liste de blocage complementaire. |
+
+## Parametres utilisateur imposes
+
+| Parametre | Valeur | Effet |
+| --- | --- | --- |
+| `advancedUserEnabled` | `false` | Desactive le mode utilisateur avance. |
+| `cloudStorageEnabled` | `false` | Desactive la synchronisation cloud uBlock. |
+| `contextMenuEnabled` | `true` | Garde le menu contextuel uBlock disponible. |
+| `showIconBadge` | `true` | Affiche le badge de compteur sur l'icone. |
+
+## Firefox navigateur par defaut
+
+Windows ne permet pas de forcer proprement le navigateur par defaut en modifiant
+simplement le registre utilisateur. Le script utilise donc la methode
+administrateur standard :
+
+1. lire les ProgID Firefox dans le registre ;
+2. generer un XML `DefaultAssociations` ;
+3. definir la policy `DefaultAssociationsConfiguration` ;
+4. importer le XML avec DISM pour les futurs profils.
+
+Les associations configurees sont :
+
+| Identifiant | Application |
+| --- | --- |
+| `.htm` | Firefox |
+| `.html` | Firefox |
+| `http` | Firefox |
+| `https` | Firefox |
+
+## Verification
+
+Pour verifier les policies Firefox :
+
+1. ouvre Firefox ;
+2. va sur `about:policies` ;
+3. verifie l'onglet `Active`.
+
+Pour verifier uBlock Origin :
+
+1. ouvre Firefox avec un nouveau profil utilisateur Windows ;
+2. va sur `about:addons` ;
+3. verifie que uBlock Origin est present ;
+4. ouvre le tableau de bord uBlock Origin ;
+5. verifie que les listes de filtres attendues sont selectionnees.
+
+Pour verifier les associations Windows :
+
+```powershell
+dism.exe /Online /Get-DefaultAppAssociations
+```
+
+## Limites
+
+Les associations importees par DISM ciblent les futurs profils Windows. Un profil
+deja cree peut conserver ses associations existantes.
+
+Firefox doit etre installe avant l'execution du script, sinon les ProgID Firefox
+peuvent etre absents.
+
+uBlock Origin est telecharge par Firefox depuis Mozilla Add-ons au demarrage. La
+machine doit donc avoir acces a `addons.mozilla.org`.
+
+## Sources
+
+- Mozilla Firefox policies :
+- Mozilla `ExtensionSettings` :
+- Mozilla `3rdparty` policies :
+- Mozilla Firefox default browser enterprise :
+- Microsoft DISM default app associations :