diff --git a/docs/configuration.mdx b/docs/configuration.mdx
index 4e48d70..5b45dd5 100644
--- a/docs/configuration.mdx
+++ b/docs/configuration.mdx
@@ -154,7 +154,7 @@ Supported actions:
 
 Unlike PII Redactor, `entities` defaults to only the high-risk set: `credit_card`, `api_key` and `bearer_token`. Contact data and locators are supported but opt-in. In a proposed tool argument, they are usually the tool's own parameters rather than an exfiltration signal. `scan_injection` is off by default for the same reason. See the [Tool Approval Guard guide](/middleware/tool-approval-guard#secret-like-data).
 
-Note that `block_entities` stops the run whatever `action` is set to, so `action: 'log'` is only observe-only if you also set `block_entities` to `[]`.
+`block_entities` stops the run regardless of the `action` setting. For an observe-only `action: 'log'` setup, also set `block_entities` to `[]`.
 
 This middleware acts on the response rather than the prompt, because the model proposes the tool calls it guards. It has no mutating action, since a proposed tool call belongs to the paused turn the provider recorded.
 
@@ -179,7 +179,7 @@ Supported actions:
 2. log
 3. truncate
 
-Every budget is disabled until you set a limit. `truncate` only applies to the per-request budget; a session or daily breach degrades to `block`, since shrinking the current prompt cannot undo spend already recorded. `sessionKeyResolver`, `userKeyResolver`, and `tokenEstimator` are constructor-only options (closures cannot live in a config file). See the [Budget Guard guide](/middleware/budget-guard) for defaults and examples.
+Every budget is disabled until you set a limit. `truncate` only applies to the per-request budget. A session or daily breach degrades to `block`, since shrinking the current prompt cannot undo spend already recorded. `sessionKeyResolver`, `userKeyResolver`, and `tokenEstimator` are constructor-only options, because closures cannot live in a config file. See the [Budget Guard guide](/middleware/budget-guard) for defaults and examples.
 
 ## Tool approval resumes
 
diff --git a/docs/contributor-resources/support.mdx b/docs/contributor-resources/support.mdx
index a3bea21..e5c393b 100644
--- a/docs/contributor-resources/support.mdx
+++ b/docs/contributor-resources/support.mdx
@@ -53,7 +53,7 @@ Missing config sections are safe.
 
 For example, you may publish `config/intercept.php` while only using Injection Guard. If you later install PII Redactor, your existing config file may not contain a `pii_redactor` section.
 
-That is fine. PII Redactor will still work using its internal defaults.
+That is fine. PII Redactor still works using its internal defaults.
 
 You only need to add a middleware section to `config/intercept.php` when you want to customise global behaviour.
 
diff --git a/docs/middleware/budget-guard.mdx b/docs/middleware/budget-guard.mdx
index 3def0fa..6b2471e 100644
--- a/docs/middleware/budget-guard.mdx
+++ b/docs/middleware/budget-guard.mdx
@@ -4,13 +4,13 @@ description: "Use BudgetGuard to estimate a generation step's cost before the pr
 sidebarTitle: "Budget Guard"
 ---
 
-`BudgetGuard` estimates the cost of a generation step before the provider is called, and enforces per-request, per-session, and per-user-per-day spending budgets.
+`BudgetGuard` estimates the cost of a generation step before it reaches the provider, and enforces per-request, per-session, and per-user-per-day spending budgets.
 
 It can block, log, or truncate the prompt down to size, or fully delegate handling to a custom callback.
 
 ## Why this middleware exists
 
-A runaway tool-calling loop, a model switched to something far pricier, or simple abuse can turn one agent into an open-ended bill. `BudgetGuard` is the gate that sits just before the provider call and stops a request before it adds to that bill, rather than reporting on the damage afterwards.
+A runaway tool-calling loop, a model switched to something far pricier, or simple abuse can turn one agent into an open-ended bill. `BudgetGuard` sits just before the provider call. It stops a request before it adds to that bill, rather than reporting on the damage afterwards.
 
 <Tip>
     Every budget is disabled until you set a limit. Adding this middleware with no options does nothing.
@@ -51,7 +51,7 @@ class SupportAgent implements Agent, HasMiddleware
 
 ## What it checks
 
-Three budgets, each independent and each optional. A step reports the first one it would exceed.
+`BudgetGuard` checks three budgets. Each one is independent and optional. A step reports the first one it would exceed.
 
 ### Per-request budget
 
@@ -59,7 +59,7 @@ Three budgets, each independent and each optional. A step reports the first one
 new BudgetGuard(maxCostPerRequest: 0.50)
 ```
 
-The whole run, including the cost already accrued by its earlier steps. The Laravel AI SDK runs agent middleware once per generation step, and a multi-step tool-calling loop keeps spending with every round trip, so this is checked again on every step of a run, not only the first.
+The whole run, including the cost already accrued by its earlier steps. The Laravel AI SDK runs agent middleware once per generation step. A multi-step tool-calling loop keeps spending with every round trip, so the middleware checks this budget on every step of a run, not only the first.
 
 ### Per-session budget
 
@@ -109,7 +109,7 @@ new BudgetGuard(
 
 ## How cost is estimated and tracked
 
-Before the provider is called, the middleware estimates the step's input tokens from the full message history it is about to send, including tool call arguments and tool results, divided by an average characters-per-token ratio. Output tokens are assumed (`assumedOutputTokens`, default 1000), since the real count is not known until the provider replies.
+Before the step reaches the provider, the middleware estimates the step's input tokens. It divides the character count of the full message history it is about to send, including tool call arguments and tool results, by an average characters-per-token ratio. Output tokens are assumed (`assumedOutputTokens`, default 1000), since the real count is not known until the provider replies.
 
 ```php
 new BudgetGuard(
@@ -129,11 +129,11 @@ new BudgetGuard(
     ```
 </Tip>
 
-Once the provider replies, the step's actual usage prices the spend recorded against the session and daily budgets, so the running total stays accurate even though the pre-call check was only an estimate.
+Once the provider replies, the middleware prices the spend recorded against the session and daily budgets from the step's actual usage. The running total stays accurate even though the pre-call check was only an estimate.
 
 ### Pricing
 
-A built-in table prices common models from Anthropic, OpenAI, Google, xAI, DeepSeek, and Mistral, in US dollars per million tokens. A model id is matched exactly first, then by the longest pricing key it starts with or contains, so a dated or gateway-prefixed id such as `us.anthropic.claude-3-5-haiku-20241022-v1:0` or `bedrock/gpt-4o-mini-2024-07-18` still resolves to its family.
+A built-in table prices common models from Anthropic, OpenAI, Google, xAI, DeepSeek, and Mistral, in US dollars per million tokens. The middleware matches a model ID exactly first, then by the longest pricing key it starts with or contains. A dated or gateway-prefixed id such as `us.anthropic.claude-3-5-haiku-20241022-v1:0` or `bedrock/gpt-4o-mini-2024-07-18` still resolves to its family.
 
 Published pricing changes faster than this package releases. Override or extend it:
 
diff --git a/docs/middleware/injection-guard.mdx b/docs/middleware/injection-guard.mdx
index 8b26357..dcdcb31 100644
--- a/docs/middleware/injection-guard.mdx
+++ b/docs/middleware/injection-guard.mdx
@@ -29,7 +29,7 @@ composer require promptphp/intercept
 
 ## Basic usage
 
-Return the `PromptInjectionGuard` middleware on an agent's middleware method.
+Return the `PromptInjectionGuard` middleware from an agent's middleware method.
 
 <Tip>
     To add middleware to an agent, implement the `HasMiddleware` interface and define a middleware method that returns an array of middleware classes.
@@ -119,7 +119,7 @@ public function middleware(): array
 }
 ```
 
-In this case, the middleware will use `log` for that agent, even though the global config says `block`.
+In this case, the middleware uses `log` for that agent, even though the global config says `block`.
 
 ### Partial configuration
 
diff --git a/docs/middleware/pii-redactor.mdx b/docs/middleware/pii-redactor.mdx
index 0bff85b..9c5985e 100644
--- a/docs/middleware/pii-redactor.mdx
+++ b/docs/middleware/pii-redactor.mdx
@@ -30,7 +30,7 @@ composer require promptphp/intercept
 
 ## Basic usage
 
-Return the `PIIRedactor` middleware on an agent's middleware method.
+Return the `PIIRedactor` middleware from an agent's middleware method.
 
 <Tip>
     To add middleware to an agent, implement the `HasMiddleware` interface and define a middleware method that returns an array of middleware classes.
@@ -76,7 +76,7 @@ By default, the middleware will:
 
 The recommended default action is `redact`.
 
-Some entities can still be blocked even when the action is `redact`. By default, credit cards, API keys, and bearer tokens are blocked.
+The middleware can still block some entities even when the action is `redact`. By default, it blocks credit cards, API keys, and bearer tokens.
 
 ## Supported entities
 
@@ -139,7 +139,7 @@ public function middleware(): array
 }
 ```
 
-In this case, the middleware will use `log` for that agent, even though the global config says `redact`.
+In this case, the middleware uses `log` for that agent, even though the global config says `redact`.
 
 ### Partial configuration
 
diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx
index 931d415..75cfb09 100644
--- a/docs/quickstart.mdx
+++ b/docs/quickstart.mdx
@@ -50,7 +50,7 @@ config/intercept.php
   define a middleware method that returns an array of middleware classes.
 </Tip>
 
-Return Intercept middleware classes on your agent's middleware method.
+Return Intercept middleware classes from your agent's middleware method.
 
 ```php
 <?php