diff --git a/dotnet/BundleContents.md b/dotnet/BundleContents.md
index e9ebbc552a2..935a7ef1224 100644
--- a/dotnet/BundleContents.md
+++ b/dotnet/BundleContents.md
@@ -29,6 +29,9 @@ For this purpose, we support the `PublishFolderType` metadata on items in the
Below is a list of known/valid `PublishFolderType` values and the
corresponding action taken for each.
+> [!IMPORTANT]
+See [`PublishFolderType` doesn't work from a referenced library project](#transitiveProject) for using `PublishFolderType` in library projects.
+
In all cases the relative directory is preserved (i.e. we don't follow the
behavior in [dotnet/sdk#9643](https://github.com/dotnet/sdk/issues/9643).
@@ -276,6 +279,29 @@ The easiest way is to set `PublishFolderType` to `None`:
```
+
+
+### `PublishFolderType` doesn't work from a referenced library project.
+
+The `PublishFolderType` metadata does not work in transitive / referenced
+projects that aren't platform-specific. For example: if an executable project
+references a `net9.0` library project, adding the `PublishFolderType` metadata
+on items in the `net9.0` library project doesn't have any effect, and you'll get a warning like this:
+
+> Xamarin.Shared.Sdk.targets(1836,3): Warning : The file '/myresource/file.psd' does not specify a 'PublishFolderType' metadata, and a default value could not be calculated. The file will not be copied to the app bundle.
+
+The workaround is to set
+`MSBuildDisableGetCopyToPublishDirectoryItemsOptimization=true` in the
+library project:
+
+```xml
+
+ true
+
+```
+
+See https://github.com/xamarin/xamarin-macios/issues/20947 for more information.
+
## References
* [.NET: What to do about files in ResolvedFileToPublish](https://github.com/xamarin/xamarin-macios/issues/12572)