diff --git a/docs/usage/configuration.mdx b/docs/usage/configuration.mdx
index 31ec182..67d98b8 100644
--- a/docs/usage/configuration.mdx
+++ b/docs/usage/configuration.mdx
@@ -70,9 +70,15 @@ This configuration object contains all the options that are currently supported
 
 ## PesterPreference
 
-There is one more way to provide the configuration object which is `$PesterPreference`. On `Invoke-Pester` (in case of interactive execution `Invoke-Pester` is called inside of the first `Describe`) the preference is collected and merged with the configuration object if provided. This allows you to configure everything that you would via Invoke-Pester also when you are running interactively (via `F5`). You can also use this to define the defaults for your session by putting $PesterPreference into your PowerShell profile.
+`$PesterPreference` is a variable Pester reads when a run starts. It holds a configuration object and applies to that run exactly as if the same object had been passed to `Invoke-Pester -Configuration`.
 
-Here is a simple example of enabling Mock logging output while running interactively :
+It exists for the two cases where you have no `Invoke-Pester` call of your own to pass a configuration to.
+
+### Running a test file directly
+
+When you run a test file instead of calling `Invoke-Pester` yourself, by pressing `F5` in VS Code or dot-sourcing the file, Pester calls `Invoke-Pester` for you from inside the first `Describe`. There is no call for you to add `-Configuration` to, so you define `$PesterPreference` in the file, above the first `Describe`.
+
+This turns on Mock debug output for such a run:
 
 ```powershell
 $PesterPreference = New-PesterConfiguration
@@ -93,7 +99,7 @@ Describe "pester preference" {
 ```
 Running tests from 1 files.
 
-Running tests from 'C:\Users\jajares\Desktop\mck.tests.ps1'
+Running tests from 'mck.tests.ps1'
 Describing pester preference
 Mock: Setting up mock for a.
 Mock: We are in a test. Returning mock table from test scope.
@@ -101,24 +107,54 @@ Mock: Resolving command a.
 Mock: Searching for command in the caller scope.
 Mock: Found the command a in the caller scope.
 Mock: Mock does not have a hook yet, creating a new one.
-Mock: Defined new hook with bootstrap function PesterMock_b0bde5ee-1b4f-4b8f-b1dd-aef38b3bc13d and aliases a.
-Mock: Adding a new default behavior to a.
-Mock: Mock bootstrap function a called from block Begin.
-Mock: Capturing arguments of the mocked command.
-Mock: Mock for a was invoked from block Begin.
-Mock: Getting all defined mock behaviors in this and parent scopes for command a.
-Mock: We are in a test. Finding all behaviors in this test.
-Mock: Found behaviors for 'a' in the test.
-Mock: Finding all behaviors in this block and parents.
-... shortened Mock does a lot of stuff
-Verifiable: False
-Mock: We are in a test. Returning mock table from test scope.
+... shortened, Mock does a lot of stuff
 Mock: Removing function PesterMock_b0bde5ee-1b4f-4b8f-b1dd-aef38b3bc13d and aliases a for .
   [+] mocks 857ms
 Tests completed in 1.12s
 Tests Passed: 1, Failed: 0, Skipped: 0, Inconclusive: 0, NotRun: 0
 ```
 
+:::note
+This only affects running the file directly. `Invoke-Pester ./mck.tests.ps1` ignores the assignment, because the run has already started by the time the file is read. Configure that run with `-Configuration` instead.
+:::
+
+### Defaults for your session
+
+Put `$PesterPreference` in your PowerShell profile and every run in that session starts from it, including runs you start with `Invoke-Pester`:
+
+```powershell
+# in $PROFILE
+$PesterPreference = New-PesterConfiguration
+$PesterPreference.Output.Verbosity = 'Detailed'
+```
+
+### How it combines with -Configuration
+
+When you call `Invoke-Pester -Configuration` and `$PesterPreference` is also set, both are used. The two are merged one option at a time:
+
+- an option you set on the configuration object wins
+- an option you did not set there falls back to `$PesterPreference`
+- an option set in neither uses its default
+
+So a `$PesterPreference` in your profile provides your defaults, and a configuration object overrides only the options it actually sets.
+
+```powershell
+# in $PROFILE
+$PesterPreference = New-PesterConfiguration
+$PesterPreference.Output.Verbosity = 'Detailed'
+$PesterPreference.Should.ErrorAction = 'Continue'
+
+# in a script, later
+$config = New-PesterConfiguration
+$config.Output.Verbosity = 'Diagnostic'
+Invoke-Pester -Configuration $config
+
+# runs with Verbosity = Diagnostic (from $config)
+# and Should.ErrorAction = Continue (from $PesterPreference)
+```
+
+Pester never modifies `$PesterPreference` itself, so options resolved for one run, such as filters, do not leak into the next one.
+
 ## PesterConfiguration Options
 
 :::tip TestResult and CodeCoverage auto-enable