From 7f8bbc93d63401e41368d6ddc46a4f631610fa90 Mon Sep 17 00:00:00 2001
From: Austin Horstman <khaneliman12@gmail.com>
Date: Sun, 26 Apr 2026 21:57:05 -0500
Subject: [PATCH] mkFirefoxModule: document impermanence extensions

Clarify that extensions.autoDisableScopes only handles manual extension approval. Firefox still owns mutable extension runtime state, so impermanent setups must persist the relevant profile state or configure supported extension settings declaratively.

Closes #6398
---
 modules/programs/firefox/mkFirefoxModule.nix | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/modules/programs/firefox/mkFirefoxModule.nix b/modules/programs/firefox/mkFirefoxModule.nix
index 6c1001b04..f95faec41 100644
--- a/modules/programs/firefox/mkFirefoxModule.nix
+++ b/modules/programs/firefox/mkFirefoxModule.nix
@@ -692,6 +692,20 @@ in
                         `"extensions.autoDisableScopes" = 0;`
                         to
                         [{option}`${moduleName}.profiles.<profile>.settings`](#opt-${moduleName}.profiles._name_.settings)
+
+                        On systems using impermanence, this only prevents
+                        ${name} from requiring manual extension approval. It
+                        does not preserve extension runtime state such as
+                        extension UUIDs, logins, local storage, or
+                        per-extension data. Persist the ${name} profile state
+                        needed by your extensions, or configure supported
+                        extension settings declaratively with
+                        [{option}`${moduleName}.profiles.<profile>.extensions.settings`](#opt-${moduleName}.profiles._name_.extensions.settings).
+
+                        Persisting only the `extensions` directory is generally
+                        not sufficient, because ${name} stores extension state
+                        in other profile files and databases that are managed
+                        outside Home Manager.
                       '';
                     };