Add docs for package substitution

Assisted By: Claude Opus 4.6

Author: jobselko

docs/user/guides/_SUMMARY.md

@@ -5,3 +5,4 @@
 * [Vulnerability Report](vulnerability_report.md)
 * [Attestation Hosting](attestation.md)
 * [Package Blocklist](blocklist.md)
+* [Package Substitution](package_substitution.md)

docs/user/guides/package_substitution.md

@@ -0,0 +1,43 @@
+# 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).
+
+## 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")
+```
+
+## Disable package substitution
+
+```bash
+http PATCH "${PULP_API}${REPO_HREF}" allow_package_substitution=false
+```
+
+You can also set this when creating a repository:
+
+```bash
+http POST "${PULP_API}/pulp/api/v3/repositories/python/python/" name="bar" allow_package_substitution=false
+```
+
+## Re-enable package substitution
+
+```bash
+http PATCH "${PULP_API}${REPO_HREF}" allow_package_substitution=true
+```
+
+Once re-enabled, packages with duplicate filenames can replace existing content again.