diff --git a/requirements.in b/requirements.in
index 0244f9fb..d086ce53 100644
--- a/requirements.in
+++ b/requirements.in
@@ -1,3 +1,28 @@
+# DIRECT requirements only. requirements.txt is COMPILED from this file:
+#
+#     uv pip compile requirements.in --universal --generate-hashes -o requirements.txt
+#
+# Upgrade one package without moving everything else:
+#
+#     uv pip compile requirements.in --universal --generate-hashes \
+#         --upgrade-package <name> -o requirements.txt
+#
+# This explanation lives HERE, not in requirements.txt, because a compile
+# rewrites that file from scratch. The same guidance was written into its
+# header once and was silently wiped by the next `uv pip compile` - including
+# the line warning that hand-edits vanish. It is restored there for readers,
+# but this copy is the one that survives.
+#
+# Only DIRECT requirements belong in this file. A runtime import satisfied in
+# dev only because some test dependency happens to pull it in will pass every
+# test and then fail on a production venv: `packaging` reached this project
+# through pytest, and the Windows install could not import shopdb at all until
+# it was declared. tests/test_runtime_dependencies.py guards that.
+#
+# Check dependencies against published advisories before a release:
+#
+#     venv/bin/python scripts/scan_sbom.py --gate
+
 # Flask and extensions
 flask>=3.0
 flask-sqlalchemy>=3.1