diff --git a/README.md b/README.md
index 29b9541..b6a3424 100644
--- a/README.md
+++ b/README.md
@@ -142,6 +142,10 @@ hrsh7th/cmp-path                 @main          start tracking branch main, fetc
 nvim-lua/plenary.nvim            v0.1.4         start installed
 ```
 
+The digest is a content identity, not a file checksum: Neovim's `sha256()`
+refuses binary input, so it hashes the archive's base64 form. It will not match
+`sha256sum <archive>`.
+
 A branch plugin is never reported as up to date: nothing on disk can know
 whether upstream has moved. After an update, an unchanged digest is reported as
 `unchanged` rather than as an update that changed nothing.
diff --git a/doc/arti-pack.txt b/doc/arti-pack.txt
index 2cf50fd..79eb818 100644
--- a/doc/arti-pack.txt
+++ b/doc/arti-pack.txt
@@ -108,6 +108,10 @@ one. |:ArtiPackList| reports that rather than guessing: >
     hrsh7th/cmp-path     @main    start  tracking branch main, fetched
                                          2026-09-08 10:14 (7db8f64a)
 <
+The digest is a content identity, not a file checksum: Neovim's sha256()
+refuses binary input, so it hashes the archive's base64 form. It will not
+match sha256sum on the archive.
+
 A branch plugin is never reported as up to date, because nothing on disk can
 know whether upstream has moved. An update that brings back the same digest is
 reported as unchanged, not as an update.