diff --git a/README.md b/README.md
index b337f7d..8aadfa6 100644
--- a/README.md
+++ b/README.md
@@ -333,6 +333,53 @@ nix build github:DeterminateSystems/nix-installer#nix-installer.doc
 firefox result-doc/nix-installer/index.html
 ```
 
+## Quirks
+
+While `nix-installer` tries to provide a comprehensive and unquirky experience, there are unfortunately some issues which may require manual intervention or operator choices.
+
+### Using MacOS remote SSH builders, Nix binaries are not on `$PATH`
+
+When connecting to a Mac remote SSH builder users may sometimes see this error:
+
+```bash
+$ nix store ping --store "ssh://$USER@$HOST"
+Store URL: ssh://$USER@$HOST
+zsh:1: command not found: nix-store
+error: cannot connect to '$USER@$HOST'
+```
+
+The way MacOS populates the `PATH` environment differs from other environments. ([Some background](https://gist.github.com/Linerre/f11ad4a6a934dcf01ee8415c9457e7b2))
+
+There are two possible workarounds for this:
+
+* **(Preferred)** Update the remote builder URL to include the `remote-program` parameter pointing to `nix-store`. For example:
+  ```bash
+  nix store ping --store "ssh://$USER@$HOST?remote-program=/nix/var/nix/profiles/default/bin/nix-store"
+  ```
+  If you are unsure where the `nix-store` binary is located, run `which nix-store` on the remote.
+* Update `/etc/zshenv` on the remote so that `zsh` populates the Nix path for every shell, even those that are neither *interactive* or *login*:
+  ```bash
+  # Nix
+  if [ -e '/nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh' ]; then
+      . '/nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh'
+  fi
+  # End Nix
+  ```
+  <details>
+    <summary>This strategy has some behavioral caveats, namely, `$PATH` may have unexpected contents</summary>
+
+    For example, if `PATH` gets unset then a script invoked, `PATH` may not be as empty as expected:
+    ```bash
+    $ cat example.sh     
+    #! /bin/zsh
+    echo $PATH
+    $ PATH= ./example.sh 
+    /Users/ephemeraladmin/.nix-profile/bin:/nix/var/nix/profiles/default/bin:
+    ```
+    This strategy results in Nix's paths being present on `$PATH` twice and may have a minor impact on performance.
+
+  </details>
+
 ## Diagnostics
 
 The goal of the Determinate Nix Installer is to successfully and correctly install Nix.
@@ -351,7 +398,7 @@ Here is a table of the [diagnostic data we collect][diagnosticdata]:
 | `is_ci`               | Whether the installer is being used in CI (e.g. GitHub Actions).                                      |
 | `action`              | Either `Install` or `Uninstall`.                                                                      |
 | `status`              | One of `Success`, `Failure`, `Pending`, or `Cancelled`.                                               |
-| `failure_variant`     | A high level description of what the failure was, if any. For example: `Command` if a command failed. |
+| `failure_chain`     | A high level description of what the failure was, if any. For example: `Command("diskutil")` if the command `diskutil list` failed. |
 
 To disable diagnostic reporting, set the diagnostics URL to an empty string by passing `--diagnostic-endpoint=""` or setting `NIX_INSTALLER_DIAGNOSTIC_ENDPOINT=""`.
 
diff --git a/src/action/common/configure_shell_profile.rs b/src/action/common/configure_shell_profile.rs
index a0783d3..0c593e1 100644
--- a/src/action/common/configure_shell_profile.rs
+++ b/src/action/common/configure_shell_profile.rs
@@ -34,9 +34,10 @@ const PROFILE_FISH_CONFD_PREFIXES: &[&str] = &[
 const PROFILE_TARGETS: &[&str] = &[
     "/etc/bashrc",
     "/etc/profile.d/nix.sh",
-    "/etc/zshenv",
     "/etc/bash.bashrc",
-    "/etc/zsh/zshenv",
+    // https://zsh.sourceforge.io/Intro/intro_3.html
+    "/etc/zshrc",
+    "/etc/zsh/zshrc",
 ];
 const PROFILE_NIX_FILE_SHELL: &str = "/nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh";
 const PROFILE_NIX_FILE_FISH: &str = "/nix/var/nix/profiles/default/etc/profile.d/nix-daemon.fish";