diff --git a/AGENTS.md b/AGENTS.md
index a263bd4f56..eefc4bb5bd 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -178,8 +178,8 @@ The CLI follows a layered testing pyramid. Each layer has a different goal, syst
 ## Running Tests
 
 ```sh
-# TypeScript unit tests
-npm run test:unit
+# TypeScript unit tests (some suites validate credentials, so a token is required)
+TEST_SNYK_TOKEN=<token> npm run test:unit
 
 # TypeScript acceptance tests (requires a built binary)
 TEST_SNYK_COMMAND=./binary-releases/snyk-macos-arm64 npm run test:acceptance
@@ -191,6 +191,8 @@ cd cliv2 && make test
 npx jest --runInBand test/jest/unit/path/to/test.spec.ts
 ```
 
+`SNYK_TOKEN` is **not** an alternative to `TEST_SNYK_TOKEN` — `test/setup.js` removes `SNYK_TOKEN` (and `SNYK_API_KEY`) from the environment when either is set, and writes `TEST_SNYK_TOKEN` into the CLI user config so tests run against a known configuration.
+
 ## Running the CLI Locally
 
 ```sh
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 08919bfea0..f3b2c90f1e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -156,6 +156,13 @@ Avoid using mocks as these can go out of sync and be challenging to maintain; pr
 If you are mostly testing functions calling other functions, consider writing an acceptance test instead. Otherwise,
 your tests will likely mirror the implementation and rely heavily on mocks; making future changes difficult.
 
+Despite the above, `npm run test:unit` currently needs `TEST_SNYK_TOKEN` set to a
+[valid API token](https://docs.snyk.io/snyk-api/authentication-for-api). A handful of suites drive command entry points
+that validate credentials before doing anything else, so without it they fail with `MissingApiTokenError`. Note that
+setting `SNYK_TOKEN` does not work: [`test/setup.js`](./test/setup.js) removes `SNYK_TOKEN` (and `SNYK_API_KEY`) from the
+environment when either is set, and separately writes `TEST_SNYK_TOKEN` into the CLI user config so tests run against a
+known configuration rather than whatever the developer happens to be authenticated as.
+
 ### Acceptance tests
 
 Acceptance tests enforce the correctness of our distribution and are written from the perspective of a user.