diff --git a/docs/how-tos/multiple-version-bootstrap.rst b/docs/how-tos/multiple-version-bootstrap.rst
index 4ea1bbeb..41bb9d1a 100644
--- a/docs/how-tos/multiple-version-bootstrap.rst
+++ b/docs/how-tos/multiple-version-bootstrap.rst
@@ -80,18 +80,47 @@ Output Files
 
 When ``--multiple-versions`` is active:
 
+.. versionchanged:: 0.95.0
+   Failed versions are recorded in ``partial-failures.json``. The file is
+   removed when a subsequent run has no reportable failures.
+
 - ``build-order.json`` --- created normally, listing every version built
 - ``graph.json`` --- created normally, containing all versions in the
   dependency graph
+- ``partial-failures.json`` --- created when one or more versions fail. Each
+  failure includes the package name, version, phase, exception type, and
+  message.
 - ``constraints.txt`` --- **not generated**
 
+The report contains a top-level ``failures`` list. For a resolved version,
+``name`` includes the package version (for example, ``requests==2.28.0``),
+and ``version`` contains the version separately. For an unresolved
+requirement, ``version`` is ``null`` and ``name`` contains only the package
+name.
+
+.. code-block:: json
+
+   {
+     "failures": [
+       {
+         "name": "requests==2.28.0",
+         "version": "2.28.0",
+         "phase": "failed during build phase",
+         "error_type": "CalledProcessError",
+         "message": "build command failed"
+       }
+     ]
+   }
+
 Combining with Other Flags
 --------------------------
 
 ``--test-mode``
   Supported with serial ``bootstrap`` only. Failures are collected and
   reported at the end rather than aborting early (same behavior as without
-  ``--multiple-versions``).
+  ``--multiple-versions``). When combined with ``--multiple-versions``,
+  failed versions are also included in ``partial-failures.json`` and test
+  mode retains its non-zero exit code for recorded failures.
 
 ``--skip-constraints``
   Redundant when ``--multiple-versions`` is set. Fromager automatically
diff --git a/docs/proposals/test-mode.md b/docs/proposals/test-mode.md
index fba1aef7..6545c666 100644
--- a/docs/proposals/test-mode.md
+++ b/docs/proposals/test-mode.md
@@ -89,7 +89,7 @@ graph node `pre_built` reflects settings only (not updated after fallback).
 | -- | -- | -- |
 | Purpose | Source-build gap analysis | All matching versions |
 | On build failure | Pre-built fallback, keep traversing | Remove version from graph |
-| Output | `test-mode-failures-*.json` | Logs only |
+| Output | `test-mode-failures-*.json` | `partial-failures.json` |
 
 ## Usage
 
@@ -97,7 +97,9 @@ graph node `pre_built` reflects settings only (not updated after fallback).
 fromager bootstrap --test-mode -r requirements.txt
 ```
 
-Review `test-mode-failures-*.json`, `build-order.json` (`source_url_type: "prebuilt"`), and `graph.json`. Tests: `tests/test_bootstrap_test_mode.py`,
+Review `test-mode-failures-*.json`, `partial-failures.json` for failed
+multi-version builds, `build-order.json` (`source_url_type: "prebuilt"`), and
+`graph.json`. Tests: `tests/test_bootstrap_test_mode.py`,
 `e2e/test_mode_*.sh`.
 
 ## Limitations