Update CLI docs to reflect TE3 PR 3254 bpa run resolution chain

content/features/te-cli/te-cli-commands.md

@@ -407,7 +407,7 @@ Run Best Practice Analyzer rules against a model.
 `te bpa run` accepts:
 
 - `<model>` - positional argument: path to model (alternative to the `--model` global flag).
-- `-r, --rules <file-or-url>` - path(s) or URL(s) to additional BPA rule file(s) in JSON format. Repeatable.
+- `-r, --rules <rules>` - path(s) or URL(s) to BPA rule file(s) in JSON format. Repeatable. Replaces the user-rule layer for this invocation: see [Rule sources and resolution](#rule-sources-and-resolution) below.
 - `--no-model-rules` - exclude BPA rules embedded in the model's annotations.
 - `--no-defaults` - exclude built-in default BPA rules.
 - `--vpax <file>` - load VertiPaq Analyzer stats from a `.vpax` file to enable VPA-aware rules.
@@ -433,6 +433,25 @@ te bpa run --path 'Sa*'            # Wildcard - every table starting with Sa
 te bpa run --path Sales/Measures   # Path filter applied to the matched tables
 ```
 
+#### Rule sources and resolution
+
+Each `te bpa run` invocation assembles rules from three independent layers:
+
+1. **User rules** - exactly one source wins, in priority order:
+   - `-r, --rules <rules>` flag, accepts a file path or URL (highest)
+   - `TE_BPA_RULES` environment variable
+   - `bpa.rules` array from CLI config (`~/.config/te/config.json`)
+2. **Built-in defaults** - loaded unless `--no-defaults` is passed or [`bpa.builtInRules`](xref:te-cli-config#built-in-bpa-rules) is `false` in config. Individual built-ins listed in `bpa.disabledBuiltInRuleIds` are skipped.
+3. **Model-embedded rules** - rules in the model's `BestPracticeAnalyzer_Rules` annotation, loaded unless `--no-model-rules` is passed. External URL annotations are skipped unless `--allow-external-rules` is also passed.
+
+Duplicate rule IDs are de-duplicated (user rules win over built-ins). Rule IDs in the model's `BestPracticeAnalyzer_IgnoreRules` annotation are then removed.
+
+The `Rules loaded:` line in the output attributes each contributing layer, for example:
+
+```
+Rules loaded: 41 from 1 file(s) from bpa.rules config + built-in defaults + model annotations
+```
+
 ### bpa rules
 
 Manage BPA rule collections — list, inspect, initialize, and toggle rules in your local rules file or in model annotations. Built-in rules are read-only - to skip one without losing the rest, use `te bpa rules disable` (do not edit the built-in set directly).

content/features/te-cli/te-cli-config.md

@@ -121,7 +121,7 @@ Set these in your config to avoid passing the same paths on every command. Per-c
 | Key | Meaning |
 | -- | -- |
 | `macros` | Explicit path to a macros JSON file (typically `MacroActions.json`). Resolved by every `te macro` command. Point at a shared file (network share, repo-local, or even the TE3 desktop file) to reuse the same set of macros across machines and between the CLI and TE3 Desktop. |
-| `bpa.rules` | Ordered list of paths or URLs to BPA rule files. The deploy/save gate loads **every** existing entry; `te bpa rules list` and `te config paths` use the first existing entry. Comma-separated values on `te config set bpa.rules ...` are split into the array. |
+| `bpa.rules` | Ordered list of paths or URLs to BPA rule files. `te bpa run` and the deploy/save gate load **every** existing entry; `te bpa rules list` and `te config paths` use the first existing entry. Comma-separated values on `te config set bpa.rules ...` are split into the array. |
 | `te3ExePath` | Explicit path to the Tabular Editor 3 Desktop executable (`TabularEditor.exe`). Used **only** by `te open` to launch the desktop app; safe to leave unset on Linux/macOS or when you don't use `te open`. If unset, `te open` falls back to a `PATH` lookup. |
 | `queryLog` | Path to a log file where every `te query` invocation appends its query text and execution metadata. Useful for audit trails or analyzing query patterns over time. Supports `~` for the home directory (e.g., `~/.config/te/queries.log`). |
 

content/features/te-cli/te-cli-limitations.md

@@ -44,8 +44,8 @@ The CLI runs C# scripts (`te script`) against the same `Model` object you use in
 | -- | -- |
 | **BPA rule sources must be HTTPS URLs or local file paths** | Only `https://` URLs and bare local file paths are accepted. `http://` is recognized but deliberately rejected at load time with a clear error - BPA rules are executable rule expressions, and fetching them over an unauthenticated channel would be a tampering risk. Other URL schemes (`file://`, `ftp://`, …) are not supported. Applies to both `te bpa run --rules` and the rule list configured via [`te config set`](xref:te-cli-commands#config-show--paths--init--set). |
 | **Rule-URL validation runs at gate time, not on `te config set`** | A typo such as `http://` is accepted by `te config set` and only surfaces when BPA actually runs. After editing the configured rule sources, run `te bpa run` (or `te validate`) once to verify each URL loads. |
-| **`--rules` does not suppress built-in rules** | When `te bpa run --rules <path-or-url>` is passed, the supplied rules replace the entries in [`bpa.rules`](xref:te-cli-commands#config-show--paths--init--set) and `TE_BPA_PATH` for that invocation, but the built-in defaults still load alongside. To run only the explicit rule file, also pass `--no-defaults`. |
-| **No per-invocation flag to skip `bpa.rules` config** | Once `bpa.rules` is configured, every `te bpa run` loads those rules in addition to the built-ins. There is currently no flag to skip the configured rule files for a single run. Workaround: pass `--rules <path-or-url>` explicitly - the flag fully replaces `bpa.rules` and `TE_BPA_PATH` for that invocation. |
+| **`--rules` does not suppress built-in rules** | When `te bpa run --rules <path-or-url>` is passed, the supplied rules replace the entries in [`bpa.rules`](xref:te-cli-commands#config-show--paths--init--set) and `TE_BPA_RULES` for that invocation, but the built-in defaults still load alongside. To run only the explicit rule file, also pass `--no-defaults`. |
+| **No per-invocation flag to skip `bpa.rules` config** | Once `bpa.rules` is configured, every `te bpa run` loads those rules in addition to the built-ins. There is currently no flag to skip the configured rule files for a single run. Workaround: pass `--rules <path-or-url>` explicitly - the flag fully replaces `bpa.rules` and `TE_BPA_RULES` for that invocation. |
 
 ## Validation