diff --git a/README.md b/README.md
index 13faa798..3f4ec8fa 100644
--- a/README.md
+++ b/README.md
@@ -450,6 +450,15 @@ steps:
   - run: poetry install
 ```
 
+### Input Environment Variables
+
+| Environment Variable                    | Description                                                                          |
+|-----------------------------------------|--------------------------------------------------------------------------------------|
+| `BUILD_NUMBER`                          | If present, it will be reused by the [`get-build-number`](#get-build-number) action. |
+| `CURRENT_VERSION` and `PROJECT_VERSION` | If both are set, they will be used as-is and no version update will be performed.    |
+
+See also [`get-build-number`](#get-build-number) input environment variables.
+
 ### Inputs
 
 | Input                     | Description                                                                 | Default                                                              |
@@ -543,6 +552,10 @@ jobs:
     disable-caching: 'true'
 ```
 
+### Input Environment Variables
+
+See also [`config-poetry`](#config-poetry) input environment variables.
+
 ### Inputs
 
 | Input                       | Description                                                                                                                                                                                   | Default                                                                                               |
@@ -1126,6 +1139,8 @@ See also [`config-npm`](#config-npm) output environment variables.
 
 Build, test, analyze, and deploy a Yarn project with SonarQube integration and Artifactory deployment.
 
+> **Note:** This action automatically calls [`get-build-number`](#get-build-number) to manage the build number.
+
 ### Requirements
 
 #### Required GitHub Permissions
@@ -1173,9 +1188,10 @@ jobs:
 
 ### Input Environment Variables
 
-| Environment Variable | Description                | Default |
-|----------------------|----------------------------|---------|
-| `SQ_SCANNER_VERSION` | SonarQube scanner version. | '4.3.0' |
+| Environment Variable | Description                                                                          | Default |
+|----------------------|--------------------------------------------------------------------------------------|---------|
+| `BUILD_NUMBER`       | If present, it will be reused by the [`get-build-number`](#get-build-number) action. |         |
+| `SQ_SCANNER_VERSION` | SonarQube scanner version.                                                           | '4.3.0' |
 
 ### Inputs
 
@@ -1262,6 +1278,12 @@ steps:
       disable-caching: false
 ```
 
+### Input Environment Variables
+
+| Environment Variable | Description                                                                          |
+|----------------------|--------------------------------------------------------------------------------------|
+| `BUILD_NUMBER`       | If present, it will be reused by the [`get-build-number`](#get-build-number) action. |
+
 ### Inputs
 
 | Input                     | Description                                                                 | Default                                                              |
@@ -1357,6 +1379,12 @@ steps:
 
 For build-info collection, pass `--build-name` and `--build-number` to `jf uv` and publish with `jf rt build-publish`.
 
+### Input Environment Variables
+
+| Environment Variable | Description                                                                          |
+|----------------------|--------------------------------------------------------------------------------------|
+| `BUILD_NUMBER`       | If present, it will be reused by the [`get-build-number`](#get-build-number) action. |
+
 ### Inputs
 
 | Input                     | Description                                                                 | Default                                                              |
@@ -1394,6 +1422,11 @@ This action promotes a build in JFrog Artifactory and updates the GitHub status
 
 The GitHub status check is named `repox-${GITHUB_REF_NAME}`.
 
+> **Note:** This action automatically calls [`get-build-number`](#get-build-number) to manage the build number. `promote` is intended
+> to run as a job in the same workflow run as the job that built and deployed the artifacts (e.g. `needs: [build]`) - it then
+> automatically reuses that job's build number, no manual wiring through job outputs/`env:` is needed. Since v2 this reuse is
+> coordinated through [Git References](#git-references).
+
 ### Requirements
 
 #### Required GitHub Permissions
@@ -1428,6 +1461,7 @@ promote:
     id-token: write
     contents: write
   steps:
+    # BUILD_NUMBER is automatically reused from the `build` job's run - no manual wiring needed.
     - uses: SonarSource/ci-github-actions/promote@v1
 ```
 
@@ -1450,9 +1484,10 @@ promote:
 
 ### Input Environment Variables
 
-| Environment Variable | Description                                                                                              |
-|----------------------|----------------------------------------------------------------------------------------------------------|
-| `PROJECT_VERSION`    | Version of the project (e.g. 1.2.3). If set, it takes precedence over the version from JFrog build info. |
+| Environment Variable | Description                                                                                                                                                                                            |
+|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `BUILD_NUMBER`       | If present, it will be reused by the [`get-build-number`](#get-build-number) action. Not needed when `promote` runs in the same workflow run as the job that built the artifacts - see the note above. |
+| `PROJECT_VERSION`    | Version of the project (e.g. 1.2.3). If set, it takes precedence over the version from JFrog build info.                                                                                               |
 
 ### Inputs