From 2d2b4bc31add6959b740a27ad4f1c2a08659085e Mon Sep 17 00:00:00 2001
From: Kevin Longe <273747162+kvlonge@users.noreply.github.com>
Date: Fri, 11 Sep 2026 18:17:45 +0100
Subject: [PATCH] docs: explain selector name patterns

---
 concepts/rules.mdx                         |  6 +++---
 concepts/rules/findings-and-exceptions.mdx | 24 +++++++++++++++++++++-
 concepts/selectors.mdx                     | 17 +++++++++++++--
 3 files changed, 41 insertions(+), 6 deletions(-)

diff --git a/concepts/rules.mdx b/concepts/rules.mdx
index b0a78e1..4a6dcb9 100644
--- a/concepts/rules.mdx
+++ b/concepts/rules.mdx
@@ -196,9 +196,9 @@ need to execute SQL against controlled data. Use an audit when the answer depend
 A finding contains a stable code, project-relative path, line, column, explanation, and remediation.
 This makes the same requirement usable in a terminal, JSON output, CI annotation, or agent workflow.
 
-Intentional departures remain explicit. Exact exceptions and path-scoped ignores require a reason;
-exact exceptions are stale-checked so obsolete suppressions do not silently accumulate. Mandatory
-compiler correctness cannot be suppressed.
+Intentional departures remain explicit. Exact exceptions and path- or resource-scoped ignores
+require a reason; exact exceptions are stale-checked so obsolete suppressions do not silently
+accumulate. Mandatory compiler correctness cannot be suppressed.
 
 See [Findings and exceptions](/concepts/rules/findings-and-exceptions) for configuration examples.
 
diff --git a/concepts/rules/findings-and-exceptions.mdx b/concepts/rules/findings-and-exceptions.mdx
index df2adf7..30b4338 100644
--- a/concepts/rules/findings-and-exceptions.mdx
+++ b/concepts/rules/findings-and-exceptions.mdx
@@ -20,7 +20,7 @@ reason = "This example intentionally demonstrates one sampled row."
 An exception refers to one exact Rule code and path. If the finding disappears, SQLBuild reports
 the stale exception so obsolete configuration does not accumulate silently.
 
-## Path-scoped ignores
+## Path- and resource-scoped ignores
 
 Use a path ignore when a documented project area intentionally follows a different convention:
 
@@ -34,6 +34,28 @@ reason = "Examples retain intentionally minimal SQL."
 Path ignores accept exact codes and family prefixes. Keep their scope narrow and explain why the
 project differs from the selected requirement.
 
+Use `selectors` when the exception follows graph-resource identities or lineage rather than files:
+
+```toml
+[[rules.rule_ignores]]
+rules = ["SQBRSQL021"]
+selectors = ["intermediate_*"]
+reason = "These intermediate interfaces intentionally preserve upstream columns."
+```
+
+Selectors use the same grammar as SQLBuild commands, including exact names, name globs, tags,
+resource paths, and graph expansion such as `+intermediate_*`. Use `paths` for authored-file glob
+matching, including SQL tests and audits that are not graph resources:
+
+```toml
+[[rules.rule_ignores]]
+rules = ["SQBRSQL021"]
+paths = ["models/**/intermediate_*.sql"]
+reason = "These intermediate SQL files intentionally preserve upstream columns."
+```
+
+`paths` and `selectors` may be combined in one scoped ignore. Both forms require a reason.
+
 ## Mandatory correctness
 
 Mandatory compiler correctness is not configurable and cannot be suppressed. A project must first
diff --git a/concepts/selectors.mdx b/concepts/selectors.mdx
index 3354e00..f9b0ee1 100644
--- a/concepts/selectors.mdx
+++ b/concepts/selectors.mdx
@@ -21,12 +21,23 @@ When no `--select` is provided, all models are selected.
 
 ### Name
 
-Select a single model by name:
+Select a single resource by name:
 
 ```bash
 sqb build --select fact_orders
 ```
 
+Bare names accept glob patterns. This selects every resource whose name starts with
+`intermediate_`:
+
+```bash
+sqb build --select "intermediate_*"
+```
+
+Name globs compose with graph expansion. For example, `+intermediate_*` selects every matching
+resource and all of their upstream dependencies. Quote patterns in shell commands so your shell
+does not expand `*` against files in the current directory.
+
 ### Tag
 
 Select all models with a specific tag:
@@ -129,10 +140,12 @@ sqb build --select +fact_orders --exclude tag:staging
 
 ## Error handling
 
-Unknown model names, empty paths, and malformed selectors produce clear error messages:
+Unknown resource names, name patterns with no matches, empty paths, and malformed selectors produce
+clear error messages:
 
 ```
 unknown selector name 'nonexistent_model'
+unknown selector pattern 'missing_*'
 no models found under path 'models/nonexistent'.
 no models found with tag 'nonexistent_tag'
 path selector 'fact_orders~' requires names on both sides of '~'