Acknowledge .NET limitation when appending to existing ZipArchive

README.md

@@ -74,6 +74,9 @@
   </tr>
 </table>
 
+> [!NOTE]
+> Due to a .NET limitation, cmdlets like `New-ZipEntry`, `Compress-ZipArchive` with `-Update`, and `Set-ZipEntryContent` may fail when handling files or content > 2 GB __in existing zip archives__. As a workaround, recreate the zip archive or use tools like 7-Zip, which support larger files. See issue #19 for details.
+
 ### Tar Archive Cmdlets
 
 <table>

docs/en-US/Compress-ZipArchive.md

@@ -45,17 +45,20 @@ Compress-ZipArchive
 
 PowerShell cmdlet that overcomes the limitation that the built-in cmdlet `Compress-Archive` has:
 
-> The `Compress-Archive` cmdlet uses the Microsoft .NET API [`System.IO.Compression.ZipArchive`](https://docs.microsoft.com/en-us/dotnet/api/system.io.compression.ziparchive?view=net-6.0) to compress files. The maximum file size is 2 GB because there's a limitation of the underlying API.
+> The `Compress-Archive` cmdlet uses the Microsoft .NET API [`System.IO.Compression.ZipArchive`](https://docs.microsoft.com/en-us/dotnet/api/system.io.compression.ziparchive) to compress files. The maximum file size is 2 GB because there's a limitation of the underlying API.
 
-The easy workaround would be to use the [`ZipFile.CreateFromDirectory` Method](https://docs.microsoft.com/en-us/dotnet/api/system.io.compression.zipfile.createfromdirectory?view=net-6.0#system-io-compression-zipfile-createfromdirectory(system-string-system-string)).
+The easy workaround would be to use the [`ZipFile.CreateFromDirectory` Method](https://docs.microsoft.com/en-us/dotnet/api/system.io.compression.zipfile.createfromdirectory#system-io-compression-zipfile-createfromdirectory(system-string-system-string)).
 
 However, there are 3 limitations while using this method:
 
    1. The source __must be a directory__, a single file cannot be compressed.
    2. All files (recursively) on the source folder __will be compressed__, we can't pick / filter files to compress.
    3. It's not possible to __Update__ the entries of an existing Zip Archive.
 
-This cmdlet should be able to handle compression same as `ZipFile.CreateFromDirectory` Method but also allow filtering files and folders to compress while keeping the __file / folder structure untouched__.
+This cmdlet should be able to handle compression same as `ZipFile.CreateFromDirectory` Method but also allow filtering files and folders to compress while keeping the __file / folder structure intact__.
+
+> [!NOTE]
+> When appending to an existing zip archive using the [`-Update` parameter](#-update), a .NET limitation may cause failures for files larger than 2 GB. To handle such files, recreate the archive or use tools like 7-Zip. See issue #19 for details.
 
 ## EXAMPLES
 

docs/en-US/New-ZipEntry.md

@@ -55,6 +55,9 @@ Entry paths, _arguments of the `-EntryPath` parameter_, are always normalized, a
 
 In addition, `New-ZipEntry` can set the content of the entries that it creates from string input or by specifying a source file path.
 
+> [!NOTE]
+> Due to a .NET limitation, adding files larger than 2 GB to an existing zip archive may fail. To handle such files, recreate the zip archive or use tools like 7-Zip. See issue #19 for details.
+
 ## EXAMPLES
 
 ### Example 1: Create empty entries

docs/en-US/Set-ZipEntryContent.md

@@ -18,7 +18,7 @@ Sets or appends content to an existing zip entry.
 ```powershell
 Set-ZipEntryContent
     -Value <Object[]>
-    -SourceEntry <ZipEntryFile>
+    [-SourceEntry] <ZipEntryFile>
     [-Encoding <Encoding>]
     [-Append]
     [-PassThru]
@@ -30,7 +30,7 @@ Set-ZipEntryContent
 ```powershell
 Set-ZipEntryContent
     -Value <Object[]>
-    -SourceEntry <ZipEntryFile>
+    [-SourceEntry] <ZipEntryFile>
     [-AsByteStream]
     [-Append]
     [-BufferSize <Int32>]
@@ -44,6 +44,9 @@ The `Set-ZipEntryContent` cmdlet can write or append content to a Zip Archive En
 
 If you need to create a new Zip Archive Entry you can use the [`New-ZipEntry` cmdlet](./New-ZipEntry.md).
 
+> [!NOTE]
+> Due to a .NET limitation, writing or appending content larger than 2 GB to an existing zip entry may fail. To handle such content, recreate the zip archive or use tools like 7-Zip. See issue #19 for details.
+
 ## EXAMPLES
 
 ### Example 1: Write new content to a Zip Archive Entry