diff --git a/.github/workflows/nix-build.yml b/.github/workflows/nix-build.yml
index b63f4238c..9e0fa48c2 100644
--- a/.github/workflows/nix-build.yml
+++ b/.github/workflows/nix-build.yml
@@ -42,10 +42,13 @@ jobs:
         run: nix build .#default -o result
 
       - name: Verify lockfile is complete
+        # npm silently omits resolved/integrity fields in workspace monorepos.
+        # Nix needs them for offline builds. See https://github.com/npm/cli/issues/4460
         run: |
           node scripts/fix-lockfile.mjs package-lock.json
           git diff --exit-code package-lock.json || {
             echo "ERROR: package-lock.json has missing resolved/integrity fields."
+            echo "This is a known npm bug: https://github.com/npm/cli/issues/4460"
             echo "Run 'node scripts/fix-lockfile.mjs' and commit the result."
             exit 1
           }
diff --git a/scripts/fix-lockfile.mjs b/scripts/fix-lockfile.mjs
index a76446fde..584ced79a 100644
--- a/scripts/fix-lockfile.mjs
+++ b/scripts/fix-lockfile.mjs
@@ -1,10 +1,20 @@
 #!/usr/bin/env node
-// Ensure all workspace-local node_modules entries in package-lock.json have
-// `resolved` and `integrity` fields. npm omits these for workspace-hoisted
-// overrides, but tools like Nix's offline `npm ci` require them.
+// Workaround for https://github.com/npm/cli/issues/4460
 //
-// This script is idempotent — running it on an already-complete lockfile
-// is a no-op. Run it after `npm install` when the lockfile changes.
+// npm silently omits `resolved` and `integrity` fields from some
+// package-lock.json entries in workspace monorepos (especially for
+// workspace-hoisted packages). npm acknowledged this as a bug in 2022
+// but has never shipped a fix.
+//
+// This is harmless for regular `npm ci`, but breaks offline installers
+// like Nix that need every entry to have a resolved URL + integrity hash
+// so they can pre-fetch all tarballs in a sandbox with no network access.
+//
+// This script finds incomplete entries and fills them in using `npm view`.
+// It's idempotent — running it on an already-complete lockfile is a no-op.
+//
+// See also: https://github.com/npm/cli/issues/4263
+//           https://github.com/npm/cli/issues/6301
 //
 // Usage:
 //   node scripts/fix-lockfile.mjs
diff --git a/scripts/update-nix.sh b/scripts/update-nix.sh
index 58e77cbff..9a314d574 100755
--- a/scripts/update-nix.sh
+++ b/scripts/update-nix.sh
@@ -18,6 +18,7 @@ if [[ "${1:-}" == "--check" ]]; then
 fi
 
 # 1. Fix lockfile (add resolved/integrity for workspace-local entries)
+#    Workaround for https://github.com/npm/cli/issues/4460
 echo "Fixing lockfile..."
 node "$SCRIPT_DIR/fix-lockfile.mjs" "$LOCK_FILE"