diff --git a/desktop/docs/dependencies.md b/desktop/docs/dependencies.md
index 0581adff0..314ddcc5a 100644
--- a/desktop/docs/dependencies.md
+++ b/desktop/docs/dependencies.md
@@ -22,6 +22,11 @@ a _renderer_ process.
     export of the [Photos web app](../web/README.md) in the generated app. This
     gets loaded by the embedded Chromium at runtime, acting as the app's UI.
 
+There is also a third environment that gets temporarily created:
+
+-   The [preload script](../src/preload.ts) acts as a gateway between the _main_
+    and the _renderer_ process. It runs in its own isolated environment.
+
 ### electron-builder
 
 [Electron Builder](https://www.electron.build) is used for packaging the app for
diff --git a/desktop/docs/dev.md b/desktop/docs/dev.md
index bfa80df69..a0471d87c 100644
--- a/desktop/docs/dev.md
+++ b/desktop/docs/dev.md
@@ -2,3 +2,11 @@
 
 -   `yarn build:quick` is a variant of `yarn build` that uses the
     `--config.compression=store` flag to (slightly) speed up electron-builder.
+
+## Notes
+
+-   When using native node modules (those written in C/C++), we need to ensure
+    they are built against `electron`'s packaged `node` version. We use
+    [electron-builder](https://www.electron.build/cli)'s `install-app-deps`
+    command to rebuild those modules automatically after each `yarn install` by
+    invoking it in as the `preinstall` step in our package.json.
diff --git a/desktop/src/preload.ts b/desktop/src/preload.ts
index 359c04266..7b2b988f6 100644
--- a/desktop/src/preload.ts
+++ b/desktop/src/preload.ts
@@ -1,3 +1,18 @@
+/**
+ * @file The preload script
+ *
+ * The preload script runs in an isolated environment. It has access to some of
+ * the Node imports. Its task is to expose these imports and other functions as
+ * an object on the DOM, so that the renderer process can invoke functions that
+ * live in the main (Node.js) process.
+ *
+ * Note that this script cannot import other code from `src/`. This is not an
+ * inherent limitation, just that we'll need to transpile our TypeScript and
+ * bundle it such that it can be imported from here at runtime, when this
+ * preload script is run by Electron inside its half-node half-DOM isolated
+ * environment.
+ */
+
 import { contextBridge } from "electron";
 import {
     deleteDiskCache,