diff --git a/docs/user/guides/_SUMMARY.md b/docs/user/guides/_SUMMARY.md
index b92c4aca..d9c01bdb 100644
--- a/docs/user/guides/_SUMMARY.md
+++ b/docs/user/guides/_SUMMARY.md
@@ -4,4 +4,4 @@
 * [Host Python Content](host.md)
 * [Vulnerability Report](vulnerability_report.md)
 * [Attestation Hosting](attestation.md)
-* [Package Blocklist](blocklist.md)
+* [Package Policies](package_policies.md)
diff --git a/docs/user/guides/blocklist.md b/docs/user/guides/blocklist.md
deleted file mode 100644
index 81feaa3b..00000000
--- a/docs/user/guides/blocklist.md
+++ /dev/null
@@ -1,73 +0,0 @@
-# Package Blocklist
-
-A repository can have a blocklist that prevents specific packages from being added.
-Blocklist entries can match by package `name` (all versions), package `name` with an exact `version`, or exact `filename`.
-Exactly one of `name` or `filename` must be provided.
-
-Each entry records the PRN of the user who created it in the `added_by` field.
-
-## Setup
-
-If you do not already have a repository, create one:
-
-```bash
-pulp python repository create --name foo
-```
-
-Set the API base URL and repository HREF for use in the subsequent commands:
-
-```bash
-PULP_API="http://localhost:5001"
-REPO_HREF=$(pulp python repository show --name foo | jq -r ".pulp_href")
-```
-
-## Add a blocklist entry
-
-=== "By name (all versions)"
-
-    ```bash
-    # Block all versions of shelf-reader
-    http POST "${PULP_API}${REPO_HREF}blocklist_entries/" name="shelf-reader"
-    ```
-
-=== "By name and version"
-
-    ```bash
-    # Block only shelf-reader 0.1
-    http POST "${PULP_API}${REPO_HREF}blocklist_entries/" name="shelf-reader" version="0.1"
-    ```
-
-=== "By filename"
-
-    ```bash
-    # Block only shelf-reader-0.1.tar.gz
-    http POST "${PULP_API}${REPO_HREF}blocklist_entries/" filename="shelf-reader-0.1.tar.gz"
-    ```
-
-Set the UUID of a created entry for use in the subsequent commands:
-
-```bash
-ENTRY_UUID=$(http GET "${PULP_API}${REPO_HREF}blocklist_entries/" | jq -r '.results[0].prn | split(":") | .[-1]')
-```
-
-## List blocklist entries
-
-List all entries for a repository:
-
-```bash
-http GET "${PULP_API}${REPO_HREF}blocklist_entries/"
-```
-
-Show a single entry:
-
-```bash
-http GET "${PULP_API}${REPO_HREF}blocklist_entries/${ENTRY_UUID}/"
-```
-
-## Remove a blocklist entry
-
-```bash
-http DELETE "${PULP_API}${REPO_HREF}blocklist_entries/${ENTRY_UUID}/"
-```
-
-Once an entry is removed, packages matching it can be added to the repository again.
diff --git a/docs/user/guides/package_policies.md b/docs/user/guides/package_policies.md
new file mode 100644
index 00000000..27d81e67
--- /dev/null
+++ b/docs/user/guides/package_policies.md
@@ -0,0 +1,95 @@
+# Package Policies
+
+Python repositories offer two mechanisms for controlling which packages they accept:
+**blocklists** to prevent specific packages from being added, and
+**package substitution control** to prevent silent replacement of existing packages.
+
+## Setup
+
+If you do not already have a repository, create one:
+
+```bash
+pulp python repository create --name foo
+```
+
+## Package Blocklist
+
+A repository can have a blocklist that prevents specific packages from being added.
+Blocklist entries can match by package `name` (all versions), package `name` with an exact `version`, or exact `filename`.
+Exactly one of `name` or `filename` must be provided.
+
+Each entry records the PRN of the user who created it in the `added_by` field.
+
+### Add a blocklist entry
+
+=== "By name (all versions)"
+
+    ```bash
+    # Block all versions of shelf-reader
+    pulp python repository blocklist add --repository "foo" --name "shelf-reader"
+    ```
+
+=== "By name and version"
+
+    ```bash
+    # Block only shelf-reader 0.1
+    pulp python repository blocklist add --repository "foo" --name "shelf-reader" --version "0.1"
+    ```
+
+=== "By filename"
+
+    ```bash
+    # Block only shelf-reader-0.1.tar.gz
+    pulp python repository blocklist add --repository "foo" --filename "shelf-reader-0.1.tar.gz"
+    ```
+
+### List blocklist entries
+
+List all entries for a repository:
+
+```bash
+pulp python repository blocklist list --repository "foo"
+```
+
+Show a single entry:
+
+```bash
+pulp python repository blocklist show --repository "foo" --name "shelf-reader" --version "0.1"
+```
+
+### Remove a blocklist entry
+
+```bash
+pulp python repository blocklist remove --repository "foo" --name "shelf-reader" --version "0.1"
+```
+
+Once an entry is removed, packages matching it can be added to the repository again.
+
+## Package Substitution
+
+By default, Python repositories allow package substitution: uploading, syncing, or adding a package
+with the same filename as an existing package but a different checksum will silently replace it.
+
+This behavior is controlled by the `allow_package_substitution` field on a Python repository.
+When set to `False`, any operation (upload, sync, or modify) that would replace an existing package with a different checksum is rejected.
+Re-adding a package with the same filename *and* the same checksum is always accepted (idempotent).
+
+### Disable package substitution
+
+```bash
+pulp python repository update --repository "foo" --block-package-substitution
+```
+
+You can also set this when creating a repository:
+
+```bash
+pulp python repository create --name "foo2" --block-package-substitution
+```
+
+### Re-enable package substitution
+
+```bash
+pulp python repository update --repository "foo" --allow-package-substitution
+```
+
+Once re-enabled, packages with duplicate filenames can replace existing content again.