thomhurst · thomhurst · Jun 1, 2026 · Jun 1, 2026 · Jun 1, 2026 · Jun 1, 2026
diff --git 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 = [];
 
@@ -173,11 +182,13 @@ 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
 
+> ${RUNTIME_DESCRIPTIONS[testClass] || `Performance benchmark for ${testClass}.`}
+
 :::info Last Updated
 This benchmark was automatically generated on **${timestamp}** from the latest CI run.
 
@@ -246,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 = {
@@ -270,11 +281,13 @@ 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
 
+> 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.
 
@@ -341,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 = {
@@ -380,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
@@ -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.
 
@@ -360,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 → docs/docs/benchmarks/engine/AsyncTests.md b/docs/docs/benchmarks/AsyncTests.md → docs/docs/benchmarks/engine/AsyncTests.md
@@ -1,11 +1,13 @@
 ---
 title: AsyncTests
 description: Performance benchmark results for AsyncTests
-sidebar_position: 2
+sidebar_position: 3
 ---
 
 # 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 → docs/docs/benchmarks/engine/BuildTime.md b/docs/docs/benchmarks/BuildTime.md → docs/docs/benchmarks/engine/BuildTime.md
@@ -1,11 +1,13 @@
 ---
 title: Build Performance
 description: Compilation time benchmark results
-sidebar_position: 8
+sidebar_position: 9
 ---
 
 # 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 → ...docs/benchmarks/engine/DataDrivenTests.md b/docs/docs/benchmarks/DataDrivenTests.md → ...docs/benchmarks/engine/DataDrivenTests.md
@@ -1,11 +1,13 @@
 ---
 title: DataDrivenTests
 description: Performance benchmark results for DataDrivenTests
-sidebar_position: 3
+sidebar_position: 4
 ---
 
 # 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 → ...benchmarks/engine/MassiveParallelTests.md b/docs/docs/benchmarks/MassiveParallelTests.md → ...benchmarks/engine/MassiveParallelTests.md
@@ -1,11 +1,13 @@
 ---
 title: MassiveParallelTests
 description: Performance benchmark results for MassiveParallelTests
-sidebar_position: 4
+sidebar_position: 5
 ---
 
 # 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 → docs/docs/benchmarks/engine/MatrixTests.md b/docs/docs/benchmarks/MatrixTests.md → docs/docs/benchmarks/engine/MatrixTests.md
@@ -1,11 +1,13 @@
 ---
 title: MatrixTests
 description: Performance benchmark results for MatrixTests
-sidebar_position: 5
+sidebar_position: 6
 ---
 
 # 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 → docs/docs/benchmarks/engine/ScaleTests.md b/docs/docs/benchmarks/ScaleTests.md → docs/docs/benchmarks/engine/ScaleTests.md
@@ -1,11 +1,13 @@
 ---
 title: ScaleTests
 description: Performance benchmark results for ScaleTests
-sidebar_position: 6
+sidebar_position: 7
 ---
 
 # 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 → ...s/benchmarks/engine/SetupTeardownTests.md b/docs/docs/benchmarks/SetupTeardownTests.md → ...s/benchmarks/engine/SetupTeardownTests.md
@@ -1,11 +1,13 @@
 ---
 title: SetupTeardownTests
 description: Performance benchmark results for SetupTeardownTests
-sidebar_position: 7
+sidebar_position: 8
 ---
 
 # 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/engine/_category_.json 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
@@ -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/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

diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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.
 

diff --git 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

diff --git 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',
-            },
-          ],
-        },
       ],
     },
   ],