From ba37b391e6b1df243b10397c9d27ae322d1f3b32 Mon Sep 17 00:00:00 2001
From: Tom Longhurst <30480171+thomhurst@users.noreply.github.com>
Date: Mon, 1 Jun 2026 13:39:26 +0100
Subject: [PATCH 1/4] docs: add a short description to each benchmark page

Each runtime, build, and mock benchmark page now opens with a one-line blockquote describing what the benchmark measures, placed under the title.

The descriptions are emitted by the generator scripts (sourced from the existing RUNTIME_DESCRIPTIONS and categoryDescriptions maps), so they persist across the weekly CI regeneration. The already-generated .md files are updated to match so the descriptions show before the next run.
---
 .github/scripts/process-benchmarks.js          | 4 ++++
 .github/scripts/process-mock-benchmarks.js     | 2 ++
 docs/docs/benchmarks/AsyncTests.md             | 2 ++
 docs/docs/benchmarks/BuildTime.md              | 2 ++
 docs/docs/benchmarks/DataDrivenTests.md        | 2 ++
 docs/docs/benchmarks/MassiveParallelTests.md   | 2 ++
 docs/docs/benchmarks/MatrixTests.md            | 2 ++
 docs/docs/benchmarks/ScaleTests.md             | 2 ++
 docs/docs/benchmarks/SetupTeardownTests.md     | 2 ++
 docs/docs/benchmarks/mocks/Callback.md         | 2 ++
 docs/docs/benchmarks/mocks/CombinedWorkflow.md | 2 ++
 docs/docs/benchmarks/mocks/Invocation.md       | 2 ++
 docs/docs/benchmarks/mocks/MockCreation.md     | 2 ++
 docs/docs/benchmarks/mocks/Setup.md            | 2 ++
 docs/docs/benchmarks/mocks/Verification.md     | 2 ++
 15 files changed, 32 insertions(+)

diff --git a/.github/scripts/process-benchmarks.js b/.github/scripts/process-benchmarks.js
index a558c9ac5b..62080b5aea 100644
--- a/.github/scripts/process-benchmarks.js
+++ b/.github/scripts/process-benchmarks.js
@@ -178,6 +178,8 @@ sidebar_position: ${Object.keys(categories.runtime).indexOf(testClass) + 2}
 
 # ${testClass} Benchmark
 
+> ${RUNTIME_DESCRIPTIONS[testClass] || `Performance benchmark for ${testClass}.`}
+
 :::info Last Updated
 This benchmark was automatically generated on **${timestamp}** from the latest CI run.
 
@@ -275,6 +277,8 @@ sidebar_position: ${Object.keys(categories.runtime).length + 2}
 
 # Build Performance Benchmark
 
+> Compilation time from a clean build across frameworks — how long it takes to build an identical test project.
+
 :::info Last Updated
 This benchmark was automatically generated on **${timestamp}** from the latest CI run.
 
diff --git a/.github/scripts/process-mock-benchmarks.js b/.github/scripts/process-mock-benchmarks.js
index c4529d5f9d..4903bb77bb 100644
--- a/.github/scripts/process-mock-benchmarks.js
+++ b/.github/scripts/process-mock-benchmarks.js
@@ -305,6 +305,8 @@ sidebar_position: ${index + 2}
 
 # ${category} Benchmark
 
+> ${description} — comparing **TUnit.Mocks** (source-generated) against runtime proxy-based mocking libraries.
+
 :::info Last Updated
 This benchmark was automatically generated on **${timestamp}** from the latest CI run.
 
diff --git a/docs/docs/benchmarks/AsyncTests.md b/docs/docs/benchmarks/AsyncTests.md
index 62c4ea378d..caad4a533e 100644
--- a/docs/docs/benchmarks/AsyncTests.md
+++ b/docs/docs/benchmarks/AsyncTests.md
@@ -6,6 +6,8 @@ sidebar_position: 2
 
 # AsyncTests Benchmark
 
+> Realistic async/await patterns with I/O simulation
+
 :::info Last Updated
 This benchmark was automatically generated on **2026-05-31** from the latest CI run.
 
diff --git a/docs/docs/benchmarks/BuildTime.md b/docs/docs/benchmarks/BuildTime.md
index 65896f2129..a0b1eebd5f 100644
--- a/docs/docs/benchmarks/BuildTime.md
+++ b/docs/docs/benchmarks/BuildTime.md
@@ -6,6 +6,8 @@ sidebar_position: 8
 
 # Build Performance Benchmark
 
+> Compilation time from a clean build across frameworks — how long it takes to build an identical test project.
+
 :::info Last Updated
 This benchmark was automatically generated on **2026-05-31** from the latest CI run.
 
diff --git a/docs/docs/benchmarks/DataDrivenTests.md b/docs/docs/benchmarks/DataDrivenTests.md
index a2798d2049..917691a619 100644
--- a/docs/docs/benchmarks/DataDrivenTests.md
+++ b/docs/docs/benchmarks/DataDrivenTests.md
@@ -6,6 +6,8 @@ sidebar_position: 3
 
 # DataDrivenTests Benchmark
 
+> Parameterized tests with multiple data sources
+
 :::info Last Updated
 This benchmark was automatically generated on **2026-05-31** from the latest CI run.
 
diff --git a/docs/docs/benchmarks/MassiveParallelTests.md b/docs/docs/benchmarks/MassiveParallelTests.md
index 7ee922a8e3..f74b78b2e6 100644
--- a/docs/docs/benchmarks/MassiveParallelTests.md
+++ b/docs/docs/benchmarks/MassiveParallelTests.md
@@ -6,6 +6,8 @@ sidebar_position: 4
 
 # MassiveParallelTests Benchmark
 
+> Parallel execution stress tests
+
 :::info Last Updated
 This benchmark was automatically generated on **2026-05-31** from the latest CI run.
 
diff --git a/docs/docs/benchmarks/MatrixTests.md b/docs/docs/benchmarks/MatrixTests.md
index 9ce91c5d2a..0a0f3c7fe8 100644
--- a/docs/docs/benchmarks/MatrixTests.md
+++ b/docs/docs/benchmarks/MatrixTests.md
@@ -6,6 +6,8 @@ sidebar_position: 5
 
 # MatrixTests Benchmark
 
+> Combinatorial test generation and execution
+
 :::info Last Updated
 This benchmark was automatically generated on **2026-05-31** from the latest CI run.
 
diff --git a/docs/docs/benchmarks/ScaleTests.md b/docs/docs/benchmarks/ScaleTests.md
index 3c545d3437..a5ea0da421 100644
--- a/docs/docs/benchmarks/ScaleTests.md
+++ b/docs/docs/benchmarks/ScaleTests.md
@@ -6,6 +6,8 @@ sidebar_position: 6
 
 # ScaleTests Benchmark
 
+> Large test suites (150+ tests) measuring scalability
+
 :::info Last Updated
 This benchmark was automatically generated on **2026-05-31** from the latest CI run.
 
diff --git a/docs/docs/benchmarks/SetupTeardownTests.md b/docs/docs/benchmarks/SetupTeardownTests.md
index 73c6f34d29..8b9c1ba1f7 100644
--- a/docs/docs/benchmarks/SetupTeardownTests.md
+++ b/docs/docs/benchmarks/SetupTeardownTests.md
@@ -6,6 +6,8 @@ sidebar_position: 7
 
 # SetupTeardownTests Benchmark
 
+> Expensive test fixtures with setup/teardown overhead
+
 :::info Last Updated
 This benchmark was automatically generated on **2026-05-31** from the latest CI run.
 
diff --git a/docs/docs/benchmarks/mocks/Callback.md b/docs/docs/benchmarks/mocks/Callback.md
index cbe8a8aa9d..b1827252fc 100644
--- a/docs/docs/benchmarks/mocks/Callback.md
+++ b/docs/docs/benchmarks/mocks/Callback.md
@@ -6,6 +6,8 @@ sidebar_position: 2
 
 # Callback Benchmark
 
+> Callback registration and execution — comparing **TUnit.Mocks** (source-generated) against runtime proxy-based mocking libraries.
+
 :::info Last Updated
 This benchmark was automatically generated on **2026-06-01** from the latest CI run.
 
diff --git a/docs/docs/benchmarks/mocks/CombinedWorkflow.md b/docs/docs/benchmarks/mocks/CombinedWorkflow.md
index b7cefce6d4..c97fa778a7 100644
--- a/docs/docs/benchmarks/mocks/CombinedWorkflow.md
+++ b/docs/docs/benchmarks/mocks/CombinedWorkflow.md
@@ -6,6 +6,8 @@ sidebar_position: 3
 
 # CombinedWorkflow Benchmark
 
+> Full workflow: create → setup → invoke → verify — comparing **TUnit.Mocks** (source-generated) against runtime proxy-based mocking libraries.
+
 :::info Last Updated
 This benchmark was automatically generated on **2026-06-01** from the latest CI run.
 
diff --git a/docs/docs/benchmarks/mocks/Invocation.md b/docs/docs/benchmarks/mocks/Invocation.md
index b6e2b2f448..ae632e9309 100644
--- a/docs/docs/benchmarks/mocks/Invocation.md
+++ b/docs/docs/benchmarks/mocks/Invocation.md
@@ -6,6 +6,8 @@ sidebar_position: 4
 
 # Invocation Benchmark
 
+> Calling methods on mock objects — comparing **TUnit.Mocks** (source-generated) against runtime proxy-based mocking libraries.
+
 :::info Last Updated
 This benchmark was automatically generated on **2026-06-01** from the latest CI run.
 
diff --git a/docs/docs/benchmarks/mocks/MockCreation.md b/docs/docs/benchmarks/mocks/MockCreation.md
index 160c4c4306..2a47a1c6a5 100644
--- a/docs/docs/benchmarks/mocks/MockCreation.md
+++ b/docs/docs/benchmarks/mocks/MockCreation.md
@@ -6,6 +6,8 @@ sidebar_position: 5
 
 # MockCreation Benchmark
 
+> Mock instance creation performance — comparing **TUnit.Mocks** (source-generated) against runtime proxy-based mocking libraries.
+
 :::info Last Updated
 This benchmark was automatically generated on **2026-06-01** from the latest CI run.
 
diff --git a/docs/docs/benchmarks/mocks/Setup.md b/docs/docs/benchmarks/mocks/Setup.md
index a06229d7a2..bcf010a96e 100644
--- a/docs/docs/benchmarks/mocks/Setup.md
+++ b/docs/docs/benchmarks/mocks/Setup.md
@@ -6,6 +6,8 @@ sidebar_position: 6
 
 # Setup Benchmark
 
+> Mock behavior configuration (returns, matchers) — comparing **TUnit.Mocks** (source-generated) against runtime proxy-based mocking libraries.
+
 :::info Last Updated
 This benchmark was automatically generated on **2026-06-01** from the latest CI run.
 
diff --git a/docs/docs/benchmarks/mocks/Verification.md b/docs/docs/benchmarks/mocks/Verification.md
index a0f5936654..33cf3eb380 100644
--- a/docs/docs/benchmarks/mocks/Verification.md
+++ b/docs/docs/benchmarks/mocks/Verification.md
@@ -6,6 +6,8 @@ sidebar_position: 7
 
 # Verification Benchmark
 
+> Verifying mock method calls — comparing **TUnit.Mocks** (source-generated) against runtime proxy-based mocking libraries.
+
 :::info Last Updated
 This benchmark was automatically generated on **2026-06-01** from the latest CI run.
 

From 5751b7ededbf82c81a0b075b8cd2a16f4740de5d Mon Sep 17 00:00:00 2001
From: Tom Longhurst <30480171+thomhurst@users.noreply.github.com>
Date: Mon, 1 Jun 2026 13:41:11 +0100
Subject: [PATCH 2/4] docs: promote Benchmarks to a top-level sidebar entry

Benchmarks was nested two levels deep under 'About TUnit'. Move it to a top-level entry placed just before 'Comparing & Migrating' so it's discoverable in the natural decision path before migrating from another framework.
---
 docs/sidebars.ts | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/docs/sidebars.ts b/docs/sidebars.ts
index 15728859b2..1ae3b4d312 100644
--- a/docs/sidebars.ts
+++ b/docs/sidebars.ts
@@ -202,6 +202,17 @@ const sidebars: SidebarsConfig = {
         'extending/libraries',
       ],
     },
+    {
+      type: 'category',
+      label: 'Benchmarks',
+      collapsed: true,
+      items: [
+        {
+          type: 'autogenerated',
+          dirName: 'benchmarks',
+        },
+      ],
+    },
     {
       type: 'category',
       label: 'Comparing & Migrating',
@@ -236,17 +247,6 @@ const sidebars: SidebarsConfig = {
       collapsed: true,
       items: [
         'guides/philosophy',
-        {
-          type: 'category',
-          label: 'Benchmarks',
-          collapsed: true,
-          items: [
-            {
-              type: 'autogenerated',
-              dirName: 'benchmarks',
-            },
-          ],
-        },
       ],
     },
   ],

From 4deba954c9e39ba67aa7d1e5e3228e507e04d221 Mon Sep 17 00:00:00 2001
From: Tom Longhurst <30480171+thomhurst@users.noreply.github.com>
Date: Mon, 1 Jun 2026 13:44:12 +0100
Subject: [PATCH 3/4] docs: move Benchmark Methodology above the result pages

Methodology was at sidebar_position 3, colliding with the auto-generated result pages (2-8) and getting buried mid-list. Move it to position 2 so it sits right after the overview pages, and bump the generated result pages to start at 3 (in both the generator script and the existing files) so the ordering survives the weekly regeneration.
---
 .github/scripts/process-benchmarks.js        | 4 ++--
 docs/docs/benchmarks/AsyncTests.md           | 2 +-
 docs/docs/benchmarks/BuildTime.md            | 2 +-
 docs/docs/benchmarks/DataDrivenTests.md      | 2 +-
 docs/docs/benchmarks/MassiveParallelTests.md | 2 +-
 docs/docs/benchmarks/MatrixTests.md          | 2 +-
 docs/docs/benchmarks/ScaleTests.md           | 2 +-
 docs/docs/benchmarks/SetupTeardownTests.md   | 2 +-
 docs/docs/benchmarks/methodology.md          | 2 +-
 9 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/.github/scripts/process-benchmarks.js b/.github/scripts/process-benchmarks.js
index 62080b5aea..3e36be74b4 100644
--- a/.github/scripts/process-benchmarks.js
+++ b/.github/scripts/process-benchmarks.js
@@ -173,7 +173,7 @@ Object.entries(categories.runtime).forEach(([testClass, data]) => {
   const benchmarkPage = `---
 title: ${testClass}
 description: Performance benchmark results for ${testClass}
-sidebar_position: ${Object.keys(categories.runtime).indexOf(testClass) + 2}
+sidebar_position: ${Object.keys(categories.runtime).indexOf(testClass) + 3}
 ---
 
 # ${testClass} Benchmark
@@ -272,7 +272,7 @@ if (Object.keys(categories.build).length > 0) {
     const benchmarkPage = `---
 title: Build Performance
 description: Compilation time benchmark results
-sidebar_position: ${Object.keys(categories.runtime).length + 2}
+sidebar_position: ${Object.keys(categories.runtime).length + 3}
 ---
 
 # Build Performance Benchmark
diff --git a/docs/docs/benchmarks/AsyncTests.md b/docs/docs/benchmarks/AsyncTests.md
index caad4a533e..b5c3e1c5de 100644
--- a/docs/docs/benchmarks/AsyncTests.md
+++ b/docs/docs/benchmarks/AsyncTests.md
@@ -1,7 +1,7 @@
 ---
 title: AsyncTests
 description: Performance benchmark results for AsyncTests
-sidebar_position: 2
+sidebar_position: 3
 ---
 
 # AsyncTests Benchmark
diff --git a/docs/docs/benchmarks/BuildTime.md b/docs/docs/benchmarks/BuildTime.md
index a0b1eebd5f..b50e0a8272 100644
--- a/docs/docs/benchmarks/BuildTime.md
+++ b/docs/docs/benchmarks/BuildTime.md
@@ -1,7 +1,7 @@
 ---
 title: Build Performance
 description: Compilation time benchmark results
-sidebar_position: 8
+sidebar_position: 9
 ---
 
 # Build Performance Benchmark
diff --git a/docs/docs/benchmarks/DataDrivenTests.md b/docs/docs/benchmarks/DataDrivenTests.md
index 917691a619..8a532bebd8 100644
--- a/docs/docs/benchmarks/DataDrivenTests.md
+++ b/docs/docs/benchmarks/DataDrivenTests.md
@@ -1,7 +1,7 @@
 ---
 title: DataDrivenTests
 description: Performance benchmark results for DataDrivenTests
-sidebar_position: 3
+sidebar_position: 4
 ---
 
 # DataDrivenTests Benchmark
diff --git a/docs/docs/benchmarks/MassiveParallelTests.md b/docs/docs/benchmarks/MassiveParallelTests.md
index f74b78b2e6..49acc5f78d 100644
--- a/docs/docs/benchmarks/MassiveParallelTests.md
+++ b/docs/docs/benchmarks/MassiveParallelTests.md
@@ -1,7 +1,7 @@
 ---
 title: MassiveParallelTests
 description: Performance benchmark results for MassiveParallelTests
-sidebar_position: 4
+sidebar_position: 5
 ---
 
 # MassiveParallelTests Benchmark
diff --git a/docs/docs/benchmarks/MatrixTests.md b/docs/docs/benchmarks/MatrixTests.md
index 0a0f3c7fe8..c373544d43 100644
--- a/docs/docs/benchmarks/MatrixTests.md
+++ b/docs/docs/benchmarks/MatrixTests.md
@@ -1,7 +1,7 @@
 ---
 title: MatrixTests
 description: Performance benchmark results for MatrixTests
-sidebar_position: 5
+sidebar_position: 6
 ---
 
 # MatrixTests Benchmark
diff --git a/docs/docs/benchmarks/ScaleTests.md b/docs/docs/benchmarks/ScaleTests.md
index a5ea0da421..dab59d6930 100644
--- a/docs/docs/benchmarks/ScaleTests.md
+++ b/docs/docs/benchmarks/ScaleTests.md
@@ -1,7 +1,7 @@
 ---
 title: ScaleTests
 description: Performance benchmark results for ScaleTests
-sidebar_position: 6
+sidebar_position: 7
 ---
 
 # ScaleTests Benchmark
diff --git a/docs/docs/benchmarks/SetupTeardownTests.md b/docs/docs/benchmarks/SetupTeardownTests.md
index 8b9c1ba1f7..5df72515c2 100644
--- a/docs/docs/benchmarks/SetupTeardownTests.md
+++ b/docs/docs/benchmarks/SetupTeardownTests.md
@@ -1,7 +1,7 @@
 ---
 title: SetupTeardownTests
 description: Performance benchmark results for SetupTeardownTests
-sidebar_position: 7
+sidebar_position: 8
 ---
 
 # SetupTeardownTests Benchmark
diff --git a/docs/docs/benchmarks/methodology.md b/docs/docs/benchmarks/methodology.md
index 0a23691825..070198a8fb 100644
--- a/docs/docs/benchmarks/methodology.md
+++ b/docs/docs/benchmarks/methodology.md
@@ -1,7 +1,7 @@
 ---
 title: Benchmark Methodology
 description: How TUnit's performance benchmarks are measured and compared
-sidebar_position: 3
+sidebar_position: 2
 ---
 
 # Benchmark Methodology

From 06e371d3bf295d22243e365ada8d7f0538d3d7d6 Mon Sep 17 00:00:00 2001
From: Tom Longhurst <30480171+thomhurst@users.noreply.github.com>
Date: Mon, 1 Jun 2026 13:51:39 +0100
Subject: [PATCH 4/4] docs: group engine benchmarks into an 'Engine Benchmarks'
 sub-list

The non-mock result pages (AsyncTests, DataDrivenTests, etc.) sat flat in the benchmarks list while mock benchmarks were grouped under 'Mock Library Benchmarks'. Move them into a benchmarks/engine/ subfolder with a _category_.json so they render as an 'Engine Benchmarks' sub-list sitting next to Mock Library Benchmarks.

The overview (index.md) stays at /docs/benchmarks so existing inbound links keep working; its links now point into ./engine/. Generator scripts updated to emit result pages into engine/ and write the _category_.json, so the structure survives weekly regeneration. Verified with a full docs build (no broken links).
---
 .github/scripts/process-benchmarks.js         | 23 +++++++++++++------
 .github/scripts/process-mock-benchmarks.js    |  2 +-
 .../benchmarks/{ => engine}/AsyncTests.md     |  0
 .../docs/benchmarks/{ => engine}/BuildTime.md |  0
 .../{ => engine}/DataDrivenTests.md           |  0
 .../{ => engine}/MassiveParallelTests.md      |  0
 .../benchmarks/{ => engine}/MatrixTests.md    |  0
 .../benchmarks/{ => engine}/ScaleTests.md     |  0
 .../{ => engine}/SetupTeardownTests.md        |  0
 docs/docs/benchmarks/engine/_category_.json   |  5 ++++
 docs/docs/benchmarks/index.md                 | 14 +++++------
 docs/docs/benchmarks/mocks/index.md           |  2 +-
 12 files changed, 30 insertions(+), 16 deletions(-)
 rename docs/docs/benchmarks/{ => engine}/AsyncTests.md (100%)
 rename docs/docs/benchmarks/{ => engine}/BuildTime.md (100%)
 rename docs/docs/benchmarks/{ => engine}/DataDrivenTests.md (100%)
 rename docs/docs/benchmarks/{ => engine}/MassiveParallelTests.md (100%)
 rename docs/docs/benchmarks/{ => engine}/MatrixTests.md (100%)
 rename docs/docs/benchmarks/{ => engine}/ScaleTests.md (100%)
 rename docs/docs/benchmarks/{ => engine}/SetupTeardownTests.md (100%)
 create mode 100644 docs/docs/benchmarks/engine/_category_.json

diff --git a/.github/scripts/process-benchmarks.js b/.github/scripts/process-benchmarks.js
index 3e36be74b4..7c83fce545 100644
--- a/.github/scripts/process-benchmarks.js
+++ b/.github/scripts/process-benchmarks.js
@@ -4,6 +4,9 @@ const path = require('path');
 const RUNTIME_DIR = 'benchmark-results/runtime';
 const BUILD_DIR = 'benchmark-results/build';
 const OUTPUT_DIR = 'docs/docs/benchmarks';
+// Individual result pages live in an "Engine Benchmarks" sub-list, mirroring the
+// "Mock Library Benchmarks" sub-list. The overview (index.md) stays at OUTPUT_DIR.
+const ENGINE_DIR = path.join(OUTPUT_DIR, 'engine');
 const STATIC_DIR = 'docs/static/benchmarks';
 
 const RUNTIME_DESCRIPTIONS = {
@@ -18,12 +21,18 @@ const RUNTIME_DESCRIPTIONS = {
 console.log('🚀 Processing benchmark results...\n');
 
 // Ensure output directories exist
-[OUTPUT_DIR, STATIC_DIR].forEach(dir => {
+[OUTPUT_DIR, ENGINE_DIR, STATIC_DIR].forEach(dir => {
   if (!fs.existsSync(dir)) {
     fs.mkdirSync(dir, { recursive: true });
   }
 });
 
+// Write the sub-list metadata so the "Engine Benchmarks" category persists.
+fs.writeFileSync(
+  path.join(ENGINE_DIR, '_category_.json'),
+  JSON.stringify({ label: 'Engine Benchmarks', position: 3, collapsed: true }, null, 2) + '\n'
+);
+
 function findMarkdownFiles(dir) {
   const files = [];
 
@@ -248,8 +257,8 @@ View the [benchmarks overview](/docs/benchmarks) for methodology details and env
 *Last generated: ${new Date().toISOString()}*
 `;
 
-  fs.writeFileSync(path.join(OUTPUT_DIR, `${testClass}.md`), benchmarkPage);
-  console.log(`  ✓ Created ${OUTPUT_DIR}/${testClass}.md`);
+  fs.writeFileSync(path.join(ENGINE_DIR, `${testClass}.md`), benchmarkPage);
+  console.log(`  ✓ Created ${ENGINE_DIR}/${testClass}.md`);
 
   // Generate individual JSON file for each benchmark
   const benchmarkJson = {
@@ -345,8 +354,8 @@ View the [benchmarks overview](/docs/benchmarks) for methodology details and env
 *Last generated: ${new Date().toISOString()}*
 `;
 
-    fs.writeFileSync(path.join(OUTPUT_DIR, 'BuildTime.md'), benchmarkPage);
-    console.log(`  ✓ Created ${OUTPUT_DIR}/BuildTime.md`);
+    fs.writeFileSync(path.join(ENGINE_DIR, 'BuildTime.md'), benchmarkPage);
+    console.log(`  ✓ Created ${ENGINE_DIR}/BuildTime.md`);
 
     // Generate build benchmark JSON
     const buildJson = {
@@ -384,13 +393,13 @@ These benchmarks were automatically generated on **${timestamp}** from the lates
 Click on any benchmark to view detailed results:
 
 ${Object.keys(categories.runtime).map(testClass =>
-  `- [${testClass}](./${testClass}.md)${RUNTIME_DESCRIPTIONS[testClass] ? ` — ${RUNTIME_DESCRIPTIONS[testClass]}` : ''}`
+  `- [${testClass}](./engine/${testClass}.md)${RUNTIME_DESCRIPTIONS[testClass] ? ` — ${RUNTIME_DESCRIPTIONS[testClass]}` : ''}`
 ).join('\n')}
 
 ${Object.keys(categories.build).length > 0 ? `
 ## 🔨 Build Benchmarks
 
-- [Build Performance](./BuildTime.md) - Compilation time comparison
+- [Build Performance](./engine/BuildTime.md) - Compilation time comparison
 ` : ''}
 
 ---
diff --git a/.github/scripts/process-mock-benchmarks.js b/.github/scripts/process-mock-benchmarks.js
index 4903bb77bb..db452204aa 100644
--- a/.github/scripts/process-mock-benchmarks.js
+++ b/.github/scripts/process-mock-benchmarks.js
@@ -362,7 +362,7 @@ const libraryTableRows = discoveredLibraries.map(lib => {
 const indexPage = `---
 title: Mock Library Benchmarks
 description: Performance comparisons between ${discoveredLibraries.join(', ')}
-sidebar_position: 1
+sidebar_position: 4
 ---
 
 # Mock Library Benchmarks
diff --git a/docs/docs/benchmarks/AsyncTests.md b/docs/docs/benchmarks/engine/AsyncTests.md
similarity index 100%
rename from docs/docs/benchmarks/AsyncTests.md
rename to docs/docs/benchmarks/engine/AsyncTests.md
diff --git a/docs/docs/benchmarks/BuildTime.md b/docs/docs/benchmarks/engine/BuildTime.md
similarity index 100%
rename from docs/docs/benchmarks/BuildTime.md
rename to docs/docs/benchmarks/engine/BuildTime.md
diff --git a/docs/docs/benchmarks/DataDrivenTests.md b/docs/docs/benchmarks/engine/DataDrivenTests.md
similarity index 100%
rename from docs/docs/benchmarks/DataDrivenTests.md
rename to docs/docs/benchmarks/engine/DataDrivenTests.md
diff --git a/docs/docs/benchmarks/MassiveParallelTests.md b/docs/docs/benchmarks/engine/MassiveParallelTests.md
similarity index 100%
rename from docs/docs/benchmarks/MassiveParallelTests.md
rename to docs/docs/benchmarks/engine/MassiveParallelTests.md
diff --git a/docs/docs/benchmarks/MatrixTests.md b/docs/docs/benchmarks/engine/MatrixTests.md
similarity index 100%
rename from docs/docs/benchmarks/MatrixTests.md
rename to docs/docs/benchmarks/engine/MatrixTests.md
diff --git a/docs/docs/benchmarks/ScaleTests.md b/docs/docs/benchmarks/engine/ScaleTests.md
similarity index 100%
rename from docs/docs/benchmarks/ScaleTests.md
rename to docs/docs/benchmarks/engine/ScaleTests.md
diff --git a/docs/docs/benchmarks/SetupTeardownTests.md b/docs/docs/benchmarks/engine/SetupTeardownTests.md
similarity index 100%
rename from docs/docs/benchmarks/SetupTeardownTests.md
rename to docs/docs/benchmarks/engine/SetupTeardownTests.md
diff --git a/docs/docs/benchmarks/engine/_category_.json b/docs/docs/benchmarks/engine/_category_.json
new file mode 100644
index 0000000000..3fd4a79ebb
--- /dev/null
+++ b/docs/docs/benchmarks/engine/_category_.json
@@ -0,0 +1,5 @@
+{
+  "label": "Engine Benchmarks",
+  "position": 3,
+  "collapsed": true
+}
diff --git a/docs/docs/benchmarks/index.md b/docs/docs/benchmarks/index.md
index 8c6d9eca84..95d6448e1c 100644
--- a/docs/docs/benchmarks/index.md
+++ b/docs/docs/benchmarks/index.md
@@ -16,17 +16,17 @@ These benchmarks were automatically generated on **2026-05-31** from the latest
 
 Click on any benchmark to view detailed results:
 
-- [AsyncTests](./AsyncTests.md) — Realistic async/await patterns with I/O simulation
-- [DataDrivenTests](./DataDrivenTests.md) — Parameterized tests with multiple data sources
-- [MassiveParallelTests](./MassiveParallelTests.md) — Parallel execution stress tests
-- [MatrixTests](./MatrixTests.md) — Combinatorial test generation and execution
-- [ScaleTests](./ScaleTests.md) — Large test suites (150+ tests) measuring scalability
-- [SetupTeardownTests](./SetupTeardownTests.md) — Expensive test fixtures with setup/teardown overhead
+- [AsyncTests](./engine/AsyncTests.md) — Realistic async/await patterns with I/O simulation
+- [DataDrivenTests](./engine/DataDrivenTests.md) — Parameterized tests with multiple data sources
+- [MassiveParallelTests](./engine/MassiveParallelTests.md) — Parallel execution stress tests
+- [MatrixTests](./engine/MatrixTests.md) — Combinatorial test generation and execution
+- [ScaleTests](./engine/ScaleTests.md) — Large test suites (150+ tests) measuring scalability
+- [SetupTeardownTests](./engine/SetupTeardownTests.md) — Expensive test fixtures with setup/teardown overhead
 
 
 ## 🔨 Build Benchmarks
 
-- [Build Performance](./BuildTime.md) - Compilation time comparison
+- [Build Performance](./engine/BuildTime.md) - Compilation time comparison
 
 
 ---
diff --git a/docs/docs/benchmarks/mocks/index.md b/docs/docs/benchmarks/mocks/index.md
index 87a23c9828..be392cdb31 100644
--- a/docs/docs/benchmarks/mocks/index.md
+++ b/docs/docs/benchmarks/mocks/index.md
@@ -1,7 +1,7 @@
 ---
 title: Mock Library Benchmarks
 description: Performance comparisons between TUnit.Mocks, Imposter, Mockolate, Moq, NSubstitute, FakeItEasy
-sidebar_position: 1
+sidebar_position: 4
 ---
 
 # Mock Library Benchmarks