diff --git a/CLAUDE.md b/CLAUDE.md
index 58428d3..a9bf70d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -61,7 +61,7 @@ Full guide in `CONTRIBUTING.md`; the operationally important parts (the ones tha
 - ⚠️ **A `!` (or `BREAKING CHANGE:` footer) bumps the MAJOR — do not use it casually.** The configs set `bump-minor-pre-major: true`, but that only applies **below 1.0.0**; we are on 5.x, so it is inert and a breaking marker means exactly what semver says. A `refactor(cloud)!:` PR title once produced a `6.0.0-beta.1` release PR for what was only a flag rename in an unconsumed beta. Because PRs are squash-merged, **the PR title IS the commit** — the `!` lands even if no branch commit carried it.
 - **Never hand-edit `package.json` version, `CHANGELOG.md`, or the `.release-please-manifest*.json` files** — release-please owns all of them. `src/types/generated/schema.types.ts` is likewise generated (openapi-typescript).
 - A first-time contributor must sign the CLA (the CLA Assistant bot comments on the first PR); the CLA check must be green to merge.
-- **CI (`.github/workflows/cli-ci.yml`) runs on every PR** including forks: gitleaks secret scan, `pnpm lint`, `pnpm typecheck`, `pnpm build`, `pnpm audit --audit-level moderate`. The **integration tests need the private `devicecloud-dev/dcd` mock-api** (cloned via the `DCD_SSH_DEPLOY_KEY` secret), and GitHub withholds secrets from fork and Dependabot PRs — so `pnpm test` is **skipped there** and a maintainer runs the full suite before merge. gitleaks also runs as a pre-commit hook (allowlist in `.gitleaks.toml`); without the binary installed the hook self-skips and CI is the backstop.
+- **CI (`.github/workflows/cli-ci.yml`) runs the same steps on every PR** — fork, Dependabot and same-repo alike, with no privileged path: gitleaks secret scan, `pnpm lint`, `pnpm typecheck`, `pnpm test:unit`, `pnpm build`, `pnpm audit --audit-level moderate`. **`test/integration/*` is not run by CI at all** (see the Commands section: this public repo no longer reaches into the private `devicecloud-dev/dcd` repo for a mock API), so a green PR says nothing about the integration suite — run it locally with `MOCK_API_DIR` set if a change touches the API surface. gitleaks also runs as a pre-commit hook (allowlist in `.gitleaks.toml`); without the binary installed the hook self-skips and CI is the backstop.
 
 ## Releases
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1761173..1560eac 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -37,19 +37,29 @@ Useful scripts:
 | `pnpm lint` | ESLint over `src/` and `test/` |
 | `pnpm typecheck` | Strict `tsc --noEmit` over `src/` and `test/` |
 | `pnpm build` | Compile to `dist/` |
-| `pnpm test` | Build + boot the mock API + run integration/unit tests |
+| `pnpm test:unit` | Run the unit suite — no backend needed. **This is what CI runs.** |
+| `pnpm test` | The same, plus the integration suite if `MOCK_API_DIR` points at a mock API |
 
-**Before pushing, make sure `pnpm lint`, `pnpm typecheck`, and `pnpm build`
-pass.** These run for every PR (including from forks) and are required to merge.
+**Before pushing, make sure `pnpm lint`, `pnpm typecheck`, `pnpm test:unit`, and
+`pnpm build` pass.** These run for every PR and are required to merge.
 
 ### About the test suite
 
-`pnpm test` boots a **mock API that lives in a private repository**, so the full
-integration suite only runs on branches inside this repo. **On pull requests from
-forks the integration tests are automatically skipped** — you'll see a CI notice
-saying so. That's expected: lint, typecheck, and build still run and gate your
-PR, and a maintainer runs the full suite before merge. You don't need backend
-access to contribute.
+Tests split in two. `test/unit/*` is pure — no network, no backend — and runs
+everywhere, in CI and locally.
+
+`test/integration/*` drives the built CLI against a Prism mock of the dcd API on
+port 3001. **CI does not run it**, on any PR, from a fork or otherwise: this repo
+is public and deliberately holds no credentials for, and makes no requests to,
+our private infrastructure. There is no default mock API — set
+`MOCK_API_DIR=/path/to/mock-api` (a package exposing a `start:auth` script on
+port 3001) and `pnpm test` picks the integration suite up. Without it the runner
+prints a notice and runs the unit suite alone.
+
+So every contributor, maintainers included, gets the same CI signal, and you
+don't need backend access to contribute. The flip side is worth knowing: a green
+PR says nothing about the integration suite, so if your change touches the API
+surface, say so in the PR and a maintainer will exercise it before merge.
 
 ### Secret scanning
 
diff --git a/README.md b/README.md
index f0da192..fdb4804 100644
--- a/README.md
+++ b/README.md
@@ -78,7 +78,8 @@ $ pnpm install        # install deps, build, set up git hooks
 $ pnpm dcd <args>     # run the CLI from source
 $ pnpm lint           # ESLint
 $ pnpm typecheck      # strict tsc, no emit
-$ pnpm test           # build + boot mock API + integration/unit tests
+$ pnpm test:unit      # unit tests, no backend needed — what CI runs
+$ pnpm test           # the above, plus integration tests if MOCK_API_DIR is set
 ```
 
 ### Secret scanning