diff --git a/src/content/docs/merge-queue/monitoring.mdx b/src/content/docs/merge-queue/monitoring.mdx
index fee333e4c0..67e3600084 100644
--- a/src/content/docs/merge-queue/monitoring.mdx
+++ b/src/content/docs/merge-queue/monitoring.mdx
@@ -6,8 +6,8 @@ description: Monitor key metrics of your merge queue to improve throughput and r
import { Image } from "astro:assets"
import dashboardStatsScreenshot from "../../images/merge-queue/monitoring/dashboard.png"
-Monitoring your merge queue's key metrics helps you identify bottlenecks,
-optimize throughput, and maintain an efficient development cycle.
+The Mergify dashboard reports how your merge queue has performed over time, and
+the Mergify CLI reports what it is doing right now.
## The Statistics Page
@@ -17,14 +17,29 @@ Open **Merge Queue → Statistics** in your
Use the date picker to select the time range you want to review. Presets go up to
-"Past 3 months". Queue data is retained for 90 days, so the oldest day or two of
-that longest preset can come back empty. A repository selector and filters narrow
-every widget on the page at once.
+"Past 3 months". Queue data is retained for 90 days: the calendar will not let you
+pick a day older than that, and the oldest day or two of the longest preset can
+come back empty.
+
+Three controls apply to every widget on the page at once:
+
+- The **repository selector** chooses which repository the page reports on.
+
+- **Filters** restrict the data to a set of branches,
+ [queue rules](/merge-queue/rules), or
+ [priority rules](/merge-queue/priority).
+
+- **Breakdown** keeps all the data but splits each chart into one series per
+ branch, queue rule, or priority rule, so you can compare them side by side.
+ Clicking a series narrows the page down to it. **Max Running Checks** is the
+ one widget that cannot be broken down by priority rule: a running check covers
+ a batch of pull requests that may come from different priority rules, so it
+ cannot be attributed to a single one.
A row of headline figures sits at the top: pull requests entered and merged, the
-merged rate, time spent waiting for CI, max queue size, throughput, queue time,
-CI runtime, and CI failure rate. Below it, the widgets are grouped into three
-sections.
+merged rate, the share of queue time spent waiting for CI capacity, max queue
+size, throughput, queue time, CI runtime, and CI failure rate. Below it, the
+widgets are grouped into three sections.
### Queue Health
@@ -53,8 +68,7 @@ Exit reasons, interruptions, and failure trends.
Volume of pull requests processed and queue capacity.
- **Entered PRs** and **Merged PRs**: how many pull requests joined and left the
- queue over time. A consistent trend indicates a stable development
- environment; sudden drops or spikes are worth investigating.
+ queue over time. Sudden drops or spikes are worth investigating.
- **Max Queue Size**: the largest the queue got. The reference line marks your
max checks capacity (max batch size ×
@@ -65,8 +79,10 @@ Volume of pull requests processed and queue capacity.
[`batch_size`](/merge-queue/batches) configured across your queue rules. Sitting
at the maximum suggests the queue is saturated.
-- **Max Running Checks**: peak concurrent checks. If you are often at capacity,
- raising `max_parallel_checks` improves throughput.
+- **Max Running Checks**: peak concurrent checks. The reference line is your
+ effective `max_parallel_checks` (the configured value, or the default when it
+ is unset). If you are often at that line, raising `max_parallel_checks`
+ improves throughput.
### Performance
@@ -131,12 +147,8 @@ mergify queue show
```
This displays the PR's position, priority, queue rule, CI checks summary, and
-blocking conditions. Use `--verbose` (`-v`) for the full checks table and
-conditions tree:
-
-```bash
-mergify queue show 123 --verbose
-```
+blocking conditions. See the
+[`mergify queue show` reference](/cli/queue#mergify-queue-show) for its flags.
## Integrations
diff --git a/src/content/docs/test-insights.mdx b/src/content/docs/test-insights.mdx
index bc6c1a720b..dc6fc1c918 100644
--- a/src/content/docs/test-insights.mdx
+++ b/src/content/docs/test-insights.mdx
@@ -53,6 +53,11 @@ known flakiness.
decisions. The test still runs and results are still collected, preserving
full visibility.
+- **Default branch scope**: Test health across repositories comes from runs on
+ the default branch. Pull request runs feed
+ [Prevention](/test-insights/prevention) instead. See
+ [which runs Detection reports on](/test-insights/detection#which-runs-detection-reports-on).
+
## Setup
Test Insights is powered by the same CI integration as
diff --git a/src/content/docs/test-insights/detection.mdx b/src/content/docs/test-insights/detection.mdx
index ae497fb510..ff0f844653 100644
--- a/src/content/docs/test-insights/detection.mdx
+++ b/src/content/docs/test-insights/detection.mdx
@@ -12,6 +12,23 @@ see the full picture and prioritize what to fix.
+## Which runs Detection reports on
+
+Detection reports on tests that ran on your repository's default branch.
+Results uploaded from pull request branches are stored, but they do not
+contribute to the metrics shown here.
+
+A repository whose CI has only ever run on pull requests shows an empty
+Detection page, even though uploads are working. Merge to the default branch
+and the tests appear after that run completes.
+
+The same scope applies outside the dashboard: the
+[`mergify tests show`](/cli/tests) command and the
+[test search API](/api/test-insights) return default-branch results.
+
+[Prevention](/test-insights/prevention) covers the pull request side of Test
+Insights: it reports on tests running on pull request branches.
+
## How tests are classified
Mergify classifies tests based on their results across multiple CI runs,
diff --git a/src/content/images/merge-queue/monitoring/dashboard.png b/src/content/images/merge-queue/monitoring/dashboard.png
index 8bb6939d6e..09f844905b 100644
Binary files a/src/content/images/merge-queue/monitoring/dashboard.png and b/src/content/images/merge-queue/monitoring/dashboard.png differ