docs(test-suite): document env var version override mechanism

The CLI overlays *_VERSION env vars onto resolved bundles, which is how
the merge queue workflow injects SHA-tagged images. This was undocumented.

Author: Eikix

test-suite/fhevm/ARCHITECTURE.md

@@ -45,6 +45,24 @@ flowchart TD
   L --> D
 ```
 
+## Version Override (CI Integration)
+
+After resolving a target bundle, `applyVersionEnvOverrides` overlays any matching `*_VERSION`
+environment variables onto the bundle. This is the mechanism CI uses:
+
+```
+resolve target (e.g. latest-release)
+  → baseline bundle with release tag for all repo-owned packages
+  → applyVersionEnvOverrides(bundle, process.env)
+  → env vars like COPROCESSOR_HOST_LISTENER_VERSION=<sha> replace baseline versions
+  → lock file records overrides in its "sources" field
+```
+
+The merge queue workflow (`test-suite-orchestrate-e2e-tests.yml`) builds Docker images tagged
+with the PR's HEAD SHA, exports them as env vars, then calls `./fhevm-cli up --target latest-release`.
+The target provides companion defaults (CORE_VERSION, RELAYER_VERSION); the env vars provide
+the SHA-tagged images for every component built from the PR.
+
 ## Notes
 
 - Version selection is explicit. The CLI does not silently use a vague "latest".

test-suite/fhevm/README.md

@@ -45,6 +45,53 @@ bun test
 
 Only `devnet`, `testnet`, and `mainnet` resolve from GitOps. Non-network targets do not.
 
+## Version Override via Environment Variables
+
+After resolving a target bundle, the CLI applies **environment variable overrides**: any
+`*_VERSION` env var that matches a key in the resolved bundle replaces that version.
+
+This is how CI works. The merge queue workflow:
+
+1. Builds Docker images tagged with the PR's HEAD SHA (e.g., `abc1234`)
+2. Sets env vars like `COPROCESSOR_HOST_LISTENER_VERSION=abc1234`
+3. Runs `./fhevm-cli up --target latest-release`
+
+The CLI resolves `latest-release` as the baseline (providing companion versions like
+`CORE_VERSION` and `RELAYER_VERSION` that aren't built from this repo), then overlays the
+SHA-tagged env vars for every component that was built from the PR.
+
+Supported override keys (any subset):
+
+```
+GATEWAY_VERSION
+HOST_VERSION
+COPROCESSOR_DB_MIGRATION_VERSION
+COPROCESSOR_HOST_LISTENER_VERSION
+COPROCESSOR_GW_LISTENER_VERSION
+COPROCESSOR_TX_SENDER_VERSION
+COPROCESSOR_TFHE_WORKER_VERSION
+COPROCESSOR_ZKPROOF_WORKER_VERSION
+COPROCESSOR_SNS_WORKER_VERSION
+CONNECTOR_DB_MIGRATION_VERSION
+CONNECTOR_GW_LISTENER_VERSION
+CONNECTOR_KMS_WORKER_VERSION
+CONNECTOR_TX_SENDER_VERSION
+CORE_VERSION
+RELAYER_VERSION
+RELAYER_MIGRATE_VERSION
+TEST_SUITE_VERSION
+```
+
+Example — test a local coprocessor image without `--override`:
+
+```sh
+COPROCESSOR_HOST_LISTENER_VERSION=abc1234 \
+COPROCESSOR_TFHE_WORKER_VERSION=abc1234 \
+  ./fhevm-cli up --target latest-release
+```
+
+The resolved lock file records which keys were overridden in its `sources` field.
+
 ## Main Commands
 
 ```sh