diff --git a/website/docs/guides/ci.md b/website/docs/guides/ci.md
index 1964c22..02cc396 100644
--- a/website/docs/guides/ci.md
+++ b/website/docs/guides/ci.md
@@ -28,6 +28,21 @@ If a generated file is missing or out of date, the run exits non-zero with a
 diff — so a contributor who forgot to regenerate gets a red build, not a silent
 drift.
 
+## Selectors that match nothing fail the run
+
+`heph run` exits non-zero if its selector matches no targets. A typo'd label,
+an unbuilt variant, or a package matcher outside the workspace used to build
+nothing and exit 0 — indistinguishable from a job that legitimately had
+nothing to do. Now it fails loud instead. Debug a selector that isn't
+matching what you expect with:
+
+```bash title="terminal"
+heph query -e '<expr>'
+```
+
+This only applies to `heph run`. A `heph query` that matches nothing is a
+legitimate answer.
+
 ## Validate the workspace
 
 [`heph validate`](/docs/guides/validate) checks that every target resolves, that
diff --git a/website/docs/plugins/query.md b/website/docs/plugins/query.md
index 8e6ddf0..a5c7357 100644
--- a/website/docs/plugins/query.md
+++ b/website/docs/plugins/query.md
@@ -113,6 +113,12 @@ The old `-e`/`--exclude` flag was removed. Use `!` inside a query expression
 to exclude targets — for example `//... && !//vendor/...`.
 :::
 
+:::note
+`heph run` fails if a selector — whether a label, a package matcher, or a
+`-e` expression — matches no targets, instead of silently building nothing.
+`heph query` has no such check: an empty result is a valid answer.
+:::
+
 ## `query()` in BUILD files
 
 The `query()` builtin lets a BUILD file select targets dynamically, the same