diff --git a/docs/src/test-reporter-api/class-reporter.md b/docs/src/test-reporter-api/class-reporter.md
index 48a5654208..ead4002171 100644
--- a/docs/src/test-reporter-api/class-reporter.md
+++ b/docs/src/test-reporter-api/class-reporter.md
@@ -87,6 +87,15 @@ and [`method: Reporter.onError`] is called when something went wrong outside of
 
 If your custom reporter does not print anything to the terminal, implement [`method: Reporter.printsToStdio`] and return `false`. This way, Playwright will use one of the standard terminal reporters in addition to your custom reporter to enhance user experience.
 
+**Merged report API notes**
+
+When merging mutliple [`blob`](./test-reporters#blob-reporter) reports via [`merge-reports`](./test-sharding#merge-reports-cli) CLI
+command, the same [Reporter] API is called to produce final reports and all existing reporters
+should work without any changes. There some subtle differences though which might affect some custom
+reporters.
+
+* Projects from different shards are always kept as separate [TestProject] objects. E.g. if project 'Desktop Chrome' was sharded across 5 machines then there will be 5 instances of projects with the same name in the config passed to [`method: Reporter.onBegin`].
+
 ## optional method: Reporter.onBegin
 * since: v1.10
 
diff --git a/packages/playwright/types/testReporter.d.ts b/packages/playwright/types/testReporter.d.ts
index 987d51e004..605012071c 100644
--- a/packages/playwright/types/testReporter.d.ts
+++ b/packages/playwright/types/testReporter.d.ts
@@ -441,6 +441,17 @@ export interface FullResult {
  * [reporter.printsToStdio()](https://playwright.dev/docs/api/class-reporter#reporter-prints-to-stdio) and return
  * `false`. This way, Playwright will use one of the standard terminal reporters in addition to your custom reporter
  * to enhance user experience.
+ *
+ * **Merged report API notes**
+ *
+ * When merging mutliple [`blob`](https://playwright.dev/docs/api/test-reporters#blob-reporter) reports via
+ * [`merge-reports`](https://playwright.dev/docs/api/test-sharding#merge-reports-cli) CLI command, the same {@link Reporter} API is called to
+ * produce final reports and all existing reporters should work without any changes. There some subtle differences
+ * though which might affect some custom reporters.
+ * - Projects from different shards are always kept as separate {@link TestProject} objects. E.g. if project
+ *   'Desktop Chrome' was sharded across 5 machines then there will be 5 instances of projects with the same name in
+ *   the config passed to
+ *   [reporter.onBegin(config, suite)](https://playwright.dev/docs/api/class-reporter#reporter-on-begin).
  */
 export interface Reporter {
   /**