diff --git a/QUICK_REFERENCE.md b/QUICK_REFERENCE.md
index 0cc5c16f60..512d0c9433 100644
--- a/QUICK_REFERENCE.md
+++ b/QUICK_REFERENCE.md
@@ -21,13 +21,35 @@ pnpm --filter @object-ui/site dev        # Docs site at http://localhost:3000
 
 ### Test
 
+Always run vitest **from the repo root**, with paths written relative to it and **no
+`--`** before them:
+
 ```bash
-pnpm test                                 # Run every vitest project
-pnpm --filter @object-ui/console test     # Run just the console tests
-pnpm --filter @object-ui/core test        # Run a single package's tests
-pnpm playwright test                      # End-to-end tests
+pnpm test                                              # Run every vitest project (CI runs this)
+pnpm exec vitest run packages/core/                    # Run a single package's tests
+pnpm exec vitest run packages/core/src/<file>.test.ts  # Run a single test file
+pnpm exec vitest run apps/console/                     # Run just the console tests
+pnpm playwright test                                   # End-to-end tests
+```
+
+Not `pnpm --filter <pkg> test`, not `turbo run test`, not `cd packages/x && pnpm exec
+vitest`, and never a path behind `--`. Each of those moved vitest's root into a package,
+where the root `unit`/`dom`/`dom-heavy` projects match nothing and only `apps/console`
+resolves: 22 foreign files passed, your package never ran, output green
+(objectui#3378/#3288). A guard in `vitest.config.mts` now **exits non-zero** on all of
+them and prints the correct invocation:
+
+```
+vitest 调用被拒绝:从包目录跑 vitest 会静默跑错测试集 (objectui#3378)
+...
+正确跑法 —— 一律在【仓库根目录】执行,路径前【不要】加 `--`:
+  pnpm exec vitest run packages/<pkg>/src/<file>.test.ts   # 只跑一个文件
+  pnpm exec vitest run packages/<pkg>/   # 只跑一个包
+  pnpm test   # 全量(CI 跑的就是它)
 ```
 
+Details in [AGENTS.md](./AGENTS.md) (“怎么跑测试”) and `scripts/vitest-invocation-guard.mjs`.
+
 ### Run Examples
 
 ```bash
diff --git a/skills/objectui/guides/project-setup.md b/skills/objectui/guides/project-setup.md
index 7a27e8adb7..ea151170b3 100644
--- a/skills/objectui/guides/project-setup.md
+++ b/skills/objectui/guides/project-setup.md
@@ -306,9 +306,12 @@ pnpm type-check             # TypeScript check all
 
 # Scoped commands
 pnpm --filter @object-ui/core build       # Build single package
-pnpm --filter @object-ui/core test        # Test single package
 pnpm --filter "apps/*" dev                # Dev all apps
 
+# Scoped tests — always from the repo root, paths relative to it, no `--`
+pnpm exec vitest run packages/core/                  # Test single package
+pnpm exec vitest run packages/core/src/<file>.test.ts   # Test single file
+
 # Setup from clean clone
 ./scripts/setup.sh                        # Full automated setup
 # Or manually:
@@ -317,6 +320,28 @@ pnpm build
 pnpm test
 ```
 
+Note that tests are scoped by a **path filter from the repo root**, not by
+`pnpm --filter <pkg> test`. The `--filter` form (and `turbo run test`, and
+`cd packages/x && pnpm exec vitest`) makes vitest treat the package directory as its
+root: the root-level `unit`/`dom`/`dom-heavy` projects declare their `include` globs
+relative to that root and match nothing, while the `apps/console` project — brought in
+by absolute path — still resolves. The run then executes console's 22 files, reports
+`Test Files 22 passed (22)`, and never touches the package you asked for. A guard in
+`vitest.config.mts` rejects those invocations with a non-zero exit and prints the
+correct form:
+
+```
+vitest 调用被拒绝:从包目录跑 vitest 会静默跑错测试集 (objectui#3378)
+...
+正确跑法 —— 一律在【仓库根目录】执行,路径前【不要】加 `--`:
+  pnpm exec vitest run packages/<pkg>/src/<file>.test.ts   # 只跑一个文件
+  pnpm exec vitest run packages/<pkg>/   # 只跑一个包
+  pnpm test   # 全量(CI 跑的就是它)
+```
+
+The same guard rejects a path placed behind `--` (`pnpm --filter <pkg> test --
+--run <path>`), which pnpm forwards verbatim and vitest's CLI parser discards.
+
 ### Adding a workspace package as dependency
 
 ```bash