Add machine policy - package cache retention policy details (#2736)

* Add machine policy - package cache retention policy details

* Remove toggle

* Remove extra header

* Add feature availability note

Author: bec-callow-oct

public/docs/infrastructure/deployment-targets/machine-policies/machine-policies-package-cache-retention.png

@@ -50,8 +50,15 @@ Note that if you use the [Custom Installation Directory](/docs/projects/steps/co
 
 #### Packages
 
-Packages that are transferred during the deployment are managed based on free disk space. For each deployment, prior to acquiring the package, the free disk space is checked and if less than 20% it will delete the “least used” package(s) from the Tentacle file store location. Packages that gets removed will be reacquired if needed for another deployment.
-The disk space calculation for both targets and workers looks at the entire disk, however Octopus only cleans up in the file store.
+Packages that are transferred during the deployment are managed based on quantities of packages and version to keep. By default, Octopus keeps all packages, with a maximum of 2 versions of each. 
+These options can be configured for each machine under the Machine Policy.
+
+To configure quantity to keep, create a custom [Machine Policy](/docs/infrastructure/deployment-targets/machine-policies) and set the `Package Cache` policy to `Keep a limited number`. This will allow you to specify a number of versions to keep per package in the cache. By default this number of versions will be kept for all packages in the cache. 
+To restrict the number of packages to keep, select `From the most recently used packages`, and enter your preferred number of packages to keep. Octopus will ensure that only the least recently used packages and versions are removed.
+
+:::figure
+![Machine policy settings for package cache retention](/docs/infrastructure/deployment-targets/machine-policies/machine-policies-package-cache-retention.png)
+:::
 
 ### Built-in repository \{#built-in-repo-whats-deleted}
 

src/pages/docs/administration/retention-policies/index.mdx

@@ -311,6 +311,18 @@ Machine policies can be configured to automatically remove unavailable machines
 ![](/docs/infrastructure/deployment-targets/machine-policies/machine-policies-clean-up-unavailable.png)
 :::
 
+## Package cache retention policy
+
+:::div{.hint}
+Configurable machine package cache retention was introduced in **Octopus 2025.3**. This feature will roll out to Octopus Cloud customers first, and will be available to Octopus Server customers in Q4 2025.
+:::
+
+The machine package cache retention policy ensures that packages are periodically removed from the machine cache. This is handled by Octopus by default, but can be configured per machine policy as required.
+
+:::figure
+![](/docs/infrastructure/deployment-targets/machine-policies/machine-policies-package-cache-retention.png)
+:::
+
 ## Assign machine policies to machines
 
 Assign a machine policy to a machine by selecting a machine from the *Deployment Targets* or *Workers* screen and using the *Policy* drop down to select the machine policy: