From c039df423fdb9aa11b5431794e5b9c611772b83c Mon Sep 17 00:00:00 2001
From: shamoon <4887959+shamoon@users.noreply.github.com>
Date: Fri, 3 Apr 2026 15:41:38 -0700
Subject: [PATCH] Documentation: note required secret key in v3 guide (#12513)

---
 docs/migration-v3.md | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/docs/migration-v3.md b/docs/migration-v3.md
index 1cfb212ff..afbc83186 100644
--- a/docs/migration-v3.md
+++ b/docs/migration-v3.md
@@ -1,5 +1,24 @@
 # v3 Migration Guide
 
+## Secret Key is Now Required
+
+The `PAPERLESS_SECRET_KEY` environment variable is now required. This is a critical security setting used for cryptographic signing and should be set to a long, random value.
+
+### Action Required
+
+If you are upgrading an existing installation, you must now set `PAPERLESS_SECRET_KEY` explicitly.
+
+If your installation was relying on the previous built-in default key, you have two options:
+
+- Set `PAPERLESS_SECRET_KEY` to that previous value to preserve existing sessions and tokens.
+- Set `PAPERLESS_SECRET_KEY` to a new random value to improve security, understanding that this will invalidate existing sessions and other signed tokens.
+
+For new installations, or if you choose to rotate the key, you may generate a new secret key with:
+
+```bash
+python3 -c "import secrets; print(secrets.token_urlsafe(64))"
+```
+
 ## Consumer Settings Changes
 
 The v3 consumer command uses a [different library](https://watchfiles.helpmanual.io/) to unify