docs: heph run fails when the selector matches nothing

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

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