diff --git a/xCAT-test/bats/README.md b/xCAT-test/bats/README.md
index ac65379ab..11dce7d9d 100644
--- a/xCAT-test/bats/README.md
+++ b/xCAT-test/bats/README.md
@@ -10,6 +10,9 @@ The GitHub Actions `xcat_test` workflow runs this command after the Perl `.t`
 unit tests. Use BATS for shell behavior that can be exercised from the source
 tree without an installed xCAT, a live management node, or real services.
 
+The existing `otherpkgs_upgrade_scope.t` remains in `unit/` for its structured
+command and repository assertions. See its [sandbox prerequisites](../unit/README.md#postscript-sandbox-prerequisites).
+
 Prefer sourcing an existing shell library or sourceable script and calling the
 function under test. Keep reusable install-template helpers in
 `xCAT-server/share/xcat/install/scripts/scriptlib`, and reusable postscript
diff --git a/xCAT-test/unit/README.md b/xCAT-test/unit/README.md
index daff2691c..ce343b18d 100644
--- a/xCAT-test/unit/README.md
+++ b/xCAT-test/unit/README.md
@@ -10,6 +10,19 @@ which calls `run_unit_tests()` in `github_action_xcat_test.pl`:
 prove -r xCAT-test/unit
 ```
 
+## Postscript sandbox prerequisites
+
+`otherpkgs_upgrade_scope.t` runs the complete postscript in a Linux filesystem
+sandbox. It requires Bubblewrap, Bash, GNU core utilities, and permission to create
+user namespaces. The CI workflow installs Bubblewrap and enables those namespaces.
+Missing prerequisites fail this test without stopping unrelated test files.
+Non-Linux hosts report a skip. Set `TMPDIR` to a writable, executable filesystem
+if the default temporary directory is mounted with `noexec`.
+
+This test is an exception to the shell-test placement rule below. It stays in Perl
+to compare structured command arguments and generated repository records with the
+existing test helpers. It does not read or extract postscript source.
+
 You can run exactly the same thing from a clean checkout:
 
 ```