diff --git a/CHANGELOG.md b/CHANGELOG.md
index dd93f2a1..9fa52af1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,9 @@
+## [3.9.27](https://github.com/salesforcecli/plugin-deploy-retrieve/compare/3.9.26...3.9.27) (2024-08-13)
+
+### Bug Fixes
+
+- clarify help docs and command output for package-name flag ([16b2993](https://github.com/salesforcecli/plugin-deploy-retrieve/commit/16b29938835bf09ad91e05385a5d1650325334ae))
+
 ## [3.9.26](https://github.com/salesforcecli/plugin-deploy-retrieve/compare/3.9.25...3.9.26) (2024-08-10)
 
 ### Bug Fixes
diff --git a/README.md b/README.md
index 71bb749b..2291c76f 100644
--- a/README.md
+++ b/README.md
@@ -141,7 +141,7 @@ FLAG DESCRIPTIONS
     If you specify this parameter, don’t specify --metadata or --source-dir.
 ```
 
-_See code: [src/commands/project/convert/mdapi.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.9.26/src/commands/project/convert/mdapi.ts)_
+_See code: [src/commands/project/convert/mdapi.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.9.27/src/commands/project/convert/mdapi.ts)_
 
 ## `sf project convert source`
 
@@ -153,7 +153,7 @@ USAGE
     [-p <value>... | -x <value> | -m <value>...]
 
 FLAGS
-  -d, --output-dir=<value>     [default: metadataPackage_1723279441384] Output directory to store the Metadata
+  -d, --output-dir=<value>     [default: metadataPackage_1723521142975] Output directory to store the Metadata
                                API–formatted files in.
   -m, --metadata=<value>...    Metadata component names to convert.
   -n, --package-name=<value>   Name of the package to associate with the metadata-formatted files.
@@ -214,7 +214,7 @@ FLAG DESCRIPTIONS
     Override the api version used for api requests made by this command
 ```
 
-_See code: [src/commands/project/convert/source.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.9.26/src/commands/project/convert/source.ts)_
+_See code: [src/commands/project/convert/source.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.9.27/src/commands/project/convert/source.ts)_
 
 ## `sf project convert source-behavior`
 
@@ -271,7 +271,7 @@ EXAMPLES
     $ sf project convert source-behavior --behavior decomposeCustomLabelsBeta --dry-run --preserve-temp-dir
 ```
 
-_See code: [src/commands/project/convert/source-behavior.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.9.26/src/commands/project/convert/source-behavior.ts)_
+_See code: [src/commands/project/convert/source-behavior.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.9.27/src/commands/project/convert/source-behavior.ts)_
 
 ## `sf project delete source`
 
@@ -411,7 +411,7 @@ FLAG DESCRIPTIONS
     - Separate the test names with spaces: --tests Test1 Test2 "Test With Space"
 ```
 
-_See code: [src/commands/project/delete/source.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.9.26/src/commands/project/delete/source.ts)_
+_See code: [src/commands/project/delete/source.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.9.27/src/commands/project/delete/source.ts)_
 
 ## `sf project delete tracking`
 
@@ -448,7 +448,7 @@ EXAMPLES
     $ sf project delete tracking --target-org my-scratch
 ```
 
-_See code: [src/commands/project/delete/tracking.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.9.26/src/commands/project/delete/tracking.ts)_
+_See code: [src/commands/project/delete/tracking.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.9.27/src/commands/project/delete/tracking.ts)_
 
 ## `sf project deploy cancel`
 
@@ -520,7 +520,7 @@ FLAG DESCRIPTIONS
     project deploy report".
 ```
 
-_See code: [src/commands/project/deploy/cancel.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.9.26/src/commands/project/deploy/cancel.ts)_
+_See code: [src/commands/project/deploy/cancel.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.9.27/src/commands/project/deploy/cancel.ts)_
 
 ## `sf project deploy preview`
 
@@ -603,7 +603,7 @@ FLAG DESCRIPTIONS
     All child components are included. If you specify this flag, don’t specify --metadata or --source-dir.
 ```
 
-_See code: [src/commands/project/deploy/preview.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.9.26/src/commands/project/deploy/preview.ts)_
+_See code: [src/commands/project/deploy/preview.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.9.27/src/commands/project/deploy/preview.ts)_
 
 ## `sf project deploy quick`
 
@@ -687,7 +687,7 @@ FLAG DESCRIPTIONS
     deploy report".
 ```
 
-_See code: [src/commands/project/deploy/quick.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.9.26/src/commands/project/deploy/quick.ts)_
+_See code: [src/commands/project/deploy/quick.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.9.27/src/commands/project/deploy/quick.ts)_
 
 ## `sf project deploy report`
 
@@ -779,7 +779,7 @@ FLAG DESCRIPTIONS
     --coverage-formatters lcov --coverage-formatters clover
 ```
 
-_See code: [src/commands/project/deploy/report.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.9.26/src/commands/project/deploy/report.ts)_
+_See code: [src/commands/project/deploy/report.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.9.27/src/commands/project/deploy/report.ts)_
 
 ## `sf project deploy resume`
 
@@ -864,7 +864,7 @@ FLAG DESCRIPTIONS
     --coverage-formatters lcov --coverage-formatters clover
 ```
 
-_See code: [src/commands/project/deploy/resume.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.9.26/src/commands/project/deploy/resume.ts)_
+_See code: [src/commands/project/deploy/resume.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.9.27/src/commands/project/deploy/resume.ts)_
 
 ## `sf project deploy start`
 
@@ -1100,7 +1100,7 @@ FLAG DESCRIPTIONS
     --coverage-formatters lcov --coverage-formatters clover
 ```
 
-_See code: [src/commands/project/deploy/start.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.9.26/src/commands/project/deploy/start.ts)_
+_See code: [src/commands/project/deploy/start.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.9.27/src/commands/project/deploy/start.ts)_
 
 ## `sf project deploy validate`
 
@@ -1273,7 +1273,7 @@ FLAG DESCRIPTIONS
     --coverage-formatters lcov --coverage-formatters clover
 ```
 
-_See code: [src/commands/project/deploy/validate.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.9.26/src/commands/project/deploy/validate.ts)_
+_See code: [src/commands/project/deploy/validate.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.9.27/src/commands/project/deploy/validate.ts)_
 
 ## `sf project generate manifest`
 
@@ -1350,7 +1350,7 @@ EXAMPLES
     $ sf project generate manifest --from-org test@myorg.com --include-packages unlocked
 ```
 
-_See code: [src/commands/project/generate/manifest.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.9.26/src/commands/project/generate/manifest.ts)_
+_See code: [src/commands/project/generate/manifest.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.9.27/src/commands/project/generate/manifest.ts)_
 
 ## `sf project list ignored`
 
@@ -1392,7 +1392,7 @@ EXAMPLES
     $ sf project list ignored --source-dir package.xml
 ```
 
-_See code: [src/commands/project/list/ignored.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.9.26/src/commands/project/list/ignored.ts)_
+_See code: [src/commands/project/list/ignored.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.9.27/src/commands/project/list/ignored.ts)_
 
 ## `sf project reset tracking`
 
@@ -1441,7 +1441,7 @@ EXAMPLES
     $ sf project reset tracking --revision 30
 ```
 
-_See code: [src/commands/project/reset/tracking.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.9.26/src/commands/project/reset/tracking.ts)_
+_See code: [src/commands/project/reset/tracking.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.9.27/src/commands/project/reset/tracking.ts)_
 
 ## `sf project retrieve preview`
 
@@ -1495,7 +1495,7 @@ FLAG DESCRIPTIONS
     production orgs.
 ```
 
-_See code: [src/commands/project/retrieve/preview.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.9.26/src/commands/project/retrieve/preview.ts)_
+_See code: [src/commands/project/retrieve/preview.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.9.27/src/commands/project/retrieve/preview.ts)_
 
 ## `sf project retrieve start`
 
@@ -1514,7 +1514,8 @@ FLAGS
   -d, --source-dir=<value>...    File paths for source to retrieve from the org.
   -m, --metadata=<value>...      Metadata component names to retrieve. Wildcards (`*`) supported as long as you use
                                  quotes, such as `ApexClass:MyClass*`.
-  -n, --package-name=<value>...  Package names to retrieve.
+  -n, --package-name=<value>...  Package names to retrieve. Use of this flag is for reference only; don't use it to
+                                 retrieve packaged metadata for development.
   -o, --target-org=<value>       (required) Username or alias of the target org. Not required if the `target-org`
                                  configuration variable is already set.
   -r, --output-dir=<value>       Directory root for the retrieved source files.
@@ -1637,6 +1638,17 @@ FLAG DESCRIPTIONS
     The supplied paths can be to a single file (in which case the operation is applied to only one file) or to a folder
     (in which case the operation is applied to all source files in the directory and its subdirectories).
 
+  -n, --package-name=<value>...
+
+    Package names to retrieve. Use of this flag is for reference only; don't use it to retrieve packaged metadata for
+    development.
+
+    The metadata of the supplied package name(s) will be retrieved into a child directory of the project. The name of
+    that child directory matches the name of the package. The retrieved metadata is meant for your reference only, don't
+    add it to a source control system for development and deployment. For package development, retrieve the metadata
+    using a manifest (`--manifest` flag) or by targeting a source controlled package directory within your project
+    (`--source-dir` flag).
+
   -r, --output-dir=<value>  Directory root for the retrieved source files.
 
     The root of the directory structure into which the source files are retrieved.
@@ -1652,6 +1664,6 @@ FLAG DESCRIPTIONS
     If you specify this parameter, don’t specify --metadata or --source-dir.
 ```
 
-_See code: [src/commands/project/retrieve/start.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.9.26/src/commands/project/retrieve/start.ts)_
+_See code: [src/commands/project/retrieve/start.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.9.27/src/commands/project/retrieve/start.ts)_
 
 <!-- commandsstop -->
diff --git a/package.json b/package.json
index 8288e115..8bbaba30 100644
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@salesforce/plugin-deploy-retrieve",
   "description": "deploy and retrieve commands for sf",
-  "version": "3.9.26",
+  "version": "3.9.27",
   "author": "Salesforce",
   "bugs": "https://github.com/forcedotcom/cli/issues",
   "dependencies": {