docs(deactivate): add flox-deactivate man page and deactivation section [DO NOT MERGE]

concepts/activation.mdx

@@ -75,6 +75,8 @@ When you activate this way your existing shell is paused and you're put into a
 new one configured by Flox.
 Once this shell exits (via `exit` or `Ctrl-D`, for example), your original shell
 is resumed and your are put back into it.
+Running [`flox deactivate`](/man/flox-deactivate) inside the subshell has the
+same effect.
 
 ```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}}}%%
@@ -358,6 +360,15 @@ If you edit your manifest and activate in a new shell,
 the whole activation process is run again and subsequent activations will
 attach to this new version of the environment.
 
+## Deactivating environments
+
+Activation is reversible.
+[`flox deactivate`](/man/flox-deactivate) tears down the most recently
+activated environment in your shell,
+restoring the environment variables and shell customizations that activation
+changed.
+See [`flox deactivate`](/man/flox-deactivate) for the full command reference.
+
 ## Development vs. runtime mode
 
 See the [`options.activate.mode`](/man/manifest.toml#options) option in the manifest.

docs.json

@@ -164,6 +164,7 @@
             "group": "Environments",
             "pages": [
               "man/flox-activate",
+              "man/flox-deactivate",
               "man/flox-edit",
               "man/flox-delete",
               "man/flox-envs"

man/flox-activate.mdx

@@ -67,6 +67,10 @@ for the environment in which the shell hook was defined. See
 [`manifest.toml(5)`](/man/manifest.toml) for more details on shell
 hooks.
 
+To reverse activation, run
+[`flox deactivate`](/man/flox-deactivate). Inside a `flox activate`
+subshell, `flox deactivate` is equivalent to `exit`.
+
 ## OPTIONS
 
 ### Activate Options
@@ -239,5 +243,6 @@ eval "$(flox activate)"
 
 ## SEE ALSO
 
+[`flox-deactivate(1)`](/man/flox-deactivate),
 [`flox-push(1)`](/man/flox-push), [`flox-pull(1)`](/man/flox-pull),
 [`flox-edit(1)`](/man/flox-edit), [`flox-delete(1)`](/man/flox-delete)

man/flox-deactivate.mdx

@@ -0,0 +1,82 @@
+---
+title: "flox deactivate"
+---
+
+## NAME
+
+flox-deactivate - deactivate an environment
+
+## SYNOPSIS
+
+```text
+flox [<general-options>] deactivate
+```
+
+## DESCRIPTION
+
+Deactivates an active Flox environment in the current shell, reversing
+the changes made by [`flox activate`](/man/flox-activate).
+
+`flox deactivate` deactivates the innermost (most recently activated)
+environment. When multiple environments are layered, running
+`flox deactivate` repeatedly deactivates them one at a time, innermost
+first.
+
+Deactivation performs the following steps:
+
+- Runs the `profile.deactivate.${shell}` script from the environment's
+  manifest, if defined, allowing the environment to undo modifications
+  it made during activation.
+- Restores environment variables and shell state to their pre-activation
+  values. Only variables that activation set are reverted; variables that
+  activation did not touch are left alone.
+- Reverts shell customizations: the prompt is restored from its saved
+  value (or recomputed from the remaining active environments if any
+  remain), command hashing is re-enabled, and any zsh `FPATH` entries,
+  completion caches, and precmd hooks installed by activation are
+  removed.
+- Detaches the current shell from the activation. When the last shell
+  detaches, services started by the activation are stopped.
+
+### Interactive subshells
+
+Inside a subshell created by an interactive `flox activate`,
+`flox deactivate` is equivalent to `exit`: it exits the subshell and
+returns to the parent shell, where any previously active environments
+are restored automatically.
+
+## OPTIONS
+
+### General Options
+
+`-h`, `--help`
+:   Prints help information.
+
+The following options can be passed when running any `flox` subcommand
+but must be specified *before* the subcommand.
+
+`-v`, `--verbose`
+:   Increase logging verbosity.
+    Invoke multiple times for increasing detail.
+
+`-q`, `--quiet`
+:   Silence logs except for errors.
+
+## EXAMPLES
+
+Deactivate the innermost active environment:
+
+```bash
+flox deactivate
+```
+
+Exit a `flox activate` subshell (equivalent to running `exit`):
+
+```console
+flox [myenv] $ flox deactivate
+$
+```
+
+## SEE ALSO
+
+[`flox-activate(1)`](/man/flox-activate)