docs: updates for vars and on-deactivate

concepts/activation.mdx

@@ -247,8 +247,8 @@
     rect rgb(235, 248, 240)
       Note over P: bash
       P->>P: run setup scripts
-      P->>P: source profile.d scripts (plugins)
       P->>P: set user variables
+      P->>P: source profile.d scripts (plugins)
       P->>P: source hook.on-activate
       P->>P: exec FLOX_SHELL
     end
@@ -278,13 +278,20 @@
 you activate an environment.
 
 As part of this activation script,
-Flox runs some initial setup, then sources every installed package's
-`profile.d` scripts — this is how [plugins](/concepts/plugins) hook into
-activation. This only happens in `dev` (the default) and `build` modes;
-`run` mode deliberately skips package `profile.d` scripts. Next, it sets
-the variables you've provided in the
-[[vars] section of your manifest](/man/manifest.toml#vars) — these aren't
-visible to profile.d scripts, only to what runs after them.
+Flox runs some initial setup, then sets the variables you've provided in the
+[[vars] section of your manifest](/man/manifest.toml#vars).
+It then sources every installed package's `profile.d` scripts —
+this is how [plugins](/concepts/plugins) hook into activation.
+Plugins are **experimental** and under active development,
+so this part of the timeline may change in future releases.
+These scripts only run in `dev` (the default) and `build` modes;
+`run` mode deliberately skips them.
+Because `[vars]` are set first, plugin scripts can read them,
+so a plugin can be configured through `[vars]` as well as through its own
+`[plugins.<name>]` table.
+If a plugin script exports a variable with the same name as a `[vars]` entry,
+the plugin's value wins;
+use `hook.on-activate` to override a variable set by a plugin.
 Next, the script _sources_ the `hook.on-activate` script that you've provided
 in the [[hook] section of your manifest](/man/manifest.toml#hook).
 Since this script is run by the Bash shell we're using,
@@ -318,7 +325,9 @@
 
 **vars**:
 
-- Defines environment variables before the `hook.on-activate` and `[profile]` scripts run.
+- Defines environment variables before plugin `profile.d` scripts,
+  `hook.on-activate`, and the `[profile]` scripts run.
+- Readable by plugins, so a plugin can be configured with `[vars]` entries.
 - In Flox CLI 1.14.1 and later, values can reference other `[vars]` entries with `${NAME}`.
 - References resolve in dependency order at activation time.
 
@@ -328,6 +337,9 @@
 - Can't use aliases.
 - Can define functions to use within the hook, but they won't be passed down to other shells.
 - Can define environment variables that require shell commands or conditional logic.
+- Runs for the first `flox activate`. Subsequent activations apply environment variables from the first activation
+- Bookended by `hook.on-deactivate`, which likewise runs once, when the last
+  activation detaches.
 
 **profile**:
 
@@ -386,6 +398,42 @@
 activated environment in your shell,
 restoring the environment variables and shell customizations that activation
 changed.
+Exiting the shell has the same effect.
+
+Just as `[profile]` scripts run for every single `flox activate`,
+`profile.deactivate` scripts run for every `flox deactivate`.
+Just as `hook.on-activate` runs once when the first `flox activate` runs,
+`hook.on-deactivate` runs once when the last `flox activate` detaches.
+
+```mermaid
+%%{init: {'theme':'base','themeVariables':{'primaryColor':'#e8eef6','primaryBorderColor':'#7d96b8','primaryTextColor':'#1f2937','lineColor':'#7d96b8','noteBkgColor':'#e8eef6','noteTextColor':'#1f2937','noteBorderColor':'#7d96b8','actorBkg':'#e8eef6','actorBorder':'#7d96b8','actorTextColor':'#1f2937','actorLineColor':'#7d96b8','signalColor':'#1f2937','signalTextColor':'#1f2937','labelBoxBkgColor':'#e8eef6','labelBoxBorderColor':'#7d96b8','labelTextColor':'#1f2937','loopTextColor':'#1f2937','sequenceNumberColor':'#1f2937'},'sequence':{'mirrorActors':false}}}%%
+sequenceDiagram
+    participant S1 as First shell
+    participant A as Activation
+    participant S2 as Second shell
+    S1->>A: flox activate
+    Note over A: hook.on-activate runs, services start
+    S2->>A: flox activate (attach)
+    S1->>A: flox deactivate
+    Note over S1: profile.deactivate runs
+    Note over A: Still active — one shell attached
+    S2->>A: flox deactivate
+    Note over S2: profile.deactivate runs
+    rect rgb(235, 248, 240)
+      Note over A: Teardown
+      A->>A: stop services
+      A->>A: run hook.on-deactivate
+    end
+```
+
+`hook.on-deactivate` runs in a background process rather than in one of your
+shells,
+so it can't prompt for input and its output goes to the activation's logs
+instead of your terminal.
+It's also best-effort:
+it doesn't run if the activation's background process is killed or the
+machine shuts down uncleanly.
+
 See [`flox deactivate`](/man/flox-deactivate) for the full command reference.
 
 ## Development vs. runtime mode

llms.txt

@@ -143,6 +143,7 @@ Key terms:
 - [Catalog imports](https://flox.dev/docs/concepts/catalog-imports.md): Import packages from external catalogs for Nix expression builds
 - [Publishing](https://flox.dev/docs/concepts/publishing.md): Understanding how to publish packages with Flox
 - [Secrets management](https://flox.dev/docs/concepts/secrets-management.md): Managing secrets in Flox environments using just-in-time retrieval
+- [Plugins](https://flox.dev/docs/concepts/plugins.md): Package reusable, manifest-configured behavior as an installable component
 - [Flox vs. container workflows](https://flox.dev/docs/concepts/flox-vs-containers.md): Where Flox environments and container workflows differ, and how teams combine them
 
 ## Languages