diff --git a/docs/docs/execution/test-filters.md b/docs/docs/execution/test-filters.md
index df8349c7b6..8fc6690b83 100644
--- a/docs/docs/execution/test-filters.md
+++ b/docs/docs/execution/test-filters.md
@@ -2,6 +2,27 @@
 
 Running TUnit via `dotnet run` supports test filters.
 
+:::tip Coming from xUnit, NUnit, or MSTest?
+
+TUnit runs on Microsoft.Testing.Platform, not VSTest. The familiar
+`dotnet test --filter "Category=X"` is **not supported** — the flag is
+silently rejected, the MTP help is printed, and the run exits with
+`Zero tests ran`. This can look like a test failure when it's actually
+just an unrecognised flag.
+
+Use `--treenode-filter` instead:
+
+| VSTest (xUnit / NUnit / MSTest)            | TUnit                                                  |
+|--------------------------------------------|--------------------------------------------------------|
+| `--filter "Category=Integration"`          | `--treenode-filter "/*/*/*/*[Category=Integration]"`   |
+| `--filter "FullyQualifiedName~LoginTests"` | `--treenode-filter "/*/*/LoginTests/*"`                |
+| `--filter "Name=AcceptCookiesTest"`        | `--treenode-filter "/*/*/*/AcceptCookiesTest"`         |
+
+When using `dotnet test`, pass the flag as an application argument:
+`dotnet test -- --treenode-filter "..."`.
+
+:::
+
 TUnit can select tests by:
 
 - Assembly