Add documentation for bin directory bundling with Wave and Fusion

docs/nextflow/configuration.md

@@ -39,6 +39,12 @@ Use the following options to configure general Wave settings:
 `wave.strategy`
 : Sets the strategy used when resolving ambiguous Wave container requirements (default: `'container,dockerfile,conda'`).
 
+`wave.bundleProjectResources`
+: When enabled, bundles the workflow's `bin/` directory into the container image at `/usr/local/bin/` (default: `false`).
+  This is automatically enabled when Fusion is used.
+  Changes to bundled scripts will trigger a container rebuild.
+  See [Workflow bin scripts with Fusion](./use-cases.md#workflow-bin-scripts-with-fusion) for more information.
+
 ## Build
 
 Use the following options to configure Wave build settings:

docs/nextflow/use-cases.md

@@ -275,3 +275,35 @@ For more information about Fusion capabilities and configuration options, see th
 :::
 
 </details>
+
+## Workflow bin scripts with Fusion
+
+When using Wave with Fusion, your workflow's `bin/` directory is automatically bundled into the container image. This differs from standard Nextflow behavior where bin scripts are staged separately to the work directory at runtime.
+
+<details open>
+<summary>**How bin script bundling works**</summary>
+
+**With Fusion enabled:**
+
+- The `bin/` directory contents are bundled into the container at `/usr/local/bin/`
+- Changes to bin scripts trigger a container rebuild (the fingerprint includes file content hashes)
+- Remote bin directory upload is disabled
+
+**Without Fusion (standard Wave):**
+
+- The `bin/` directory is NOT bundled into the container by default
+- Scripts are uploaded separately to cloud storage at runtime
+- Changes to bin scripts do NOT trigger a container rebuild
+
+**To explicitly enable bin bundling without Fusion:**
+
+```groovy
+wave.enabled = true
+wave.bundleProjectResources = true
+```
+
+</details>
+
+:::warning
+If you freeze an image with `wave.freeze=true` and later run with Wave disabled (`wave.enabled=false`), your pipeline will use the bin scripts that were baked into the frozen image at build time. Local changes to bin scripts will not be reflected. To pick up script changes, re-enable Wave to trigger a rebuild with the updated fingerprint.
+:::

docs/provisioning.md

@@ -63,11 +63,16 @@ Notable parts of this workflow include:
 
 - Container images provisioned with freeze mode are regular container builds.
 - Each container image is associated with a unique ID that is obtained by hashing the following elements:
-  - The Container file
-  - Any package dependencies
+  - The Container file (Dockerfile/Singularityfile)
+  - Any package dependencies (Conda, pip, etc.)
   - The target platform, which is either AMD64 or ARM64
   - The target repository name
+  - Any container layers included in the request
 - When a request for the same container is made, the same ID is assigned to it and therefore, the build is skipped.
+
+:::note
+When Nextflow is the Wave client, additional resources may be bundled as container layers, such as module resources and the workflow's `bin/` directory. Changes to these bundled files will affect the container fingerprint and trigger a rebuild. See [Wave with Nextflow](./nextflow/use-cases.md) for details.
+:::
 - The resulting images are hosted in your selected repository and not cached locally, unless a cache repository is specified.
 - The container images are stored permanently unless the repository owner deletes them.