docs(benchmarks): document per-profile benchmark commands

Author: stephenlclarke

BENCHMARK.md

@@ -18,17 +18,6 @@ cmake --build build-review --target demo_benchmark_matrix
 matrix, appends `benchmarks/demo_benchmark_history.json`, and refreshes
 this file with the latest snapshot.
 
-## Profile meanings
-
-| Profile | Meaning |
-| --- | --- |
-| Standard timer, default sink | Baseline ScopeTimer cost with the normal synchronous sink and wall-clock timestamps enabled. |
-| Standard timer, wall time disabled | Standard timer with `SCOPE_TIMER_WALLTIME=0` so the report shows the cost of dropping `start=` and `end=` timestamp formatting. |
-| Standard timer, buffered sink | Single-thread run with the thread-buffered sink enabled to show how much caller-thread write overhead falls when flushes are batched. |
-| Standard timer, buffered sink (threaded stress) | Multi-threaded buffered run that stresses contention and cross-thread flush behavior under the standard timer format. |
-| Standard timer, async sink | Multi-threaded run with the async sink so flush work moves to the background writer instead of the calling thread. |
-| Hot-path timer, async sink | Lowest-overhead profile: hot-path timer format plus the async sink, measured under the threaded stress workload. |
-
 ## Current benchmark snapshot
 
 - Recorded at: `2026-04-16T10:45:23+00:00`
@@ -51,3 +40,60 @@ this file with the latest snapshot.
 
 Full historical results remain in
 `benchmarks/demo_benchmark_history.json`.
+
+## Profile reference
+
+The commands below rerun one profile at a time through
+`scripts/benchmark_demo.py`. The harness handles the alternating
+`SCOPE_TIMER=0` and `SCOPE_TIMER=1` passes for you; the `--env` flags
+shown here are only the profile-specific knobs.
+
+These examples use `binary=./build-bench/Benchmark`, `scenario=hotpath-bench`, `iterations=5`, `runs=8`, `threads=4`, and `sink_bytes=4096`.
+
+### Standard timer, default sink
+
+Baseline ScopeTimer cost with the normal synchronous sink and wall-clock timestamps enabled.
+
+```bash
+python3 scripts/benchmark_demo.py --binary ./build-bench/Benchmark --scenario hotpath-bench --iterations 5 --runs 8
+```
+
+### Standard timer, wall time disabled
+
+Standard timer with `SCOPE_TIMER_WALLTIME=0` so the report shows the cost of dropping `start=` and `end=` timestamp formatting.
+
+```bash
+python3 scripts/benchmark_demo.py --binary ./build-bench/Benchmark --scenario hotpath-bench --iterations 5 --runs 8 --env SCOPE_TIMER_WALLTIME=0
+```
+
+### Standard timer, buffered sink
+
+Single-thread run with the thread-buffered sink enabled to show how much caller-thread write overhead falls when flushes are batched.
+
+```bash
+python3 scripts/benchmark_demo.py --binary ./build-bench/Benchmark --scenario hotpath-bench --iterations 5 --runs 8 --env SCOPE_TIMER_BENCH_SINK=BUFFERED --env SCOPE_TIMER_WALLTIME=0
+```
+
+### Standard timer, buffered sink (threaded stress)
+
+Multi-threaded buffered run that stresses contention and cross-thread flush behavior under the standard timer format.
+
+```bash
+python3 scripts/benchmark_demo.py --binary ./build-bench/Benchmark --scenario hotpath-bench --iterations 5 --runs 8 --env SCOPE_TIMER_BENCH_SINK=BUFFERED --env SCOPE_TIMER_BENCH_SINK_BYTES=4096 --env SCOPE_TIMER_BENCH_THREADS=4 --env SCOPE_TIMER_WALLTIME=0
+```
+
+### Standard timer, async sink
+
+Multi-threaded run with the async sink so flush work moves to the background writer instead of the calling thread.
+
+```bash
+python3 scripts/benchmark_demo.py --binary ./build-bench/Benchmark --scenario hotpath-bench --iterations 5 --runs 8 --env SCOPE_TIMER_BENCH_SINK=ASYNC --env SCOPE_TIMER_BENCH_SINK_BYTES=4096 --env SCOPE_TIMER_BENCH_THREADS=4 --env SCOPE_TIMER_WALLTIME=0
+```
+
+### Hot-path timer, async sink
+
+Lowest-overhead profile: hot-path timer format plus the async sink, measured under the threaded stress workload.
+
+```bash
+python3 scripts/benchmark_demo.py --binary ./build-bench/Benchmark --scenario hotpath-bench --iterations 5 --runs 8 --env SCOPE_TIMER_BENCH_SINK=ASYNC --env SCOPE_TIMER_BENCH_SINK_BYTES=4096 --env SCOPE_TIMER_BENCH_THREADS=4 --env SCOPE_TIMER_BENCH_TIMER=HOTPATH --env SCOPE_TIMER_WALLTIME=0
+```

README.md

@@ -222,6 +222,11 @@ Build, coverage, Sonar, and benchmark-target usage now live in
 Elapsed-format examples and the log-summary pipeline now live in
 [TESTS.md](TESTS.md).
 
+## Benchmarks ##
+
+Current benchmark results, profile guidance, and reproducible per-profile
+commands now live in [BENCHMARK.md](BENCHMARK.md).
+
 ---
 
 <!-- markdownlint-disable MD034 -->

scripts/record_demo_benchmarks.py

@@ -11,17 +11,27 @@
 
 import argparse
 import json
+import shlex
 import subprocess
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
 
 import benchmark_demo
 
+REPO_ROOT = Path(__file__).resolve().parent.parent
 SCHEMA_VERSION = 1
 NOISE_TOLERANCE_PCT = 2.0
 SINK_BYTES_PLACEHOLDER = "{sink_bytes}"
 THREADS_PLACEHOLDER = "{threads}"
+DEFAULT_REPORT_CONFIG: dict[str, Any] = {
+    "binary": "./build-bench/Benchmark",
+    "scenario": "hotpath-bench",
+    "iterations": 5,
+    "runs": 8,
+    "threads": 4,
+    "sink_bytes": 4096,
+}
 
 PROFILE_DEFS: list[dict[str, Any]] = [
     {
@@ -171,6 +181,88 @@ def format_profile_env(template_env: dict[str, str], threads: int, sink_bytes: i
     }
 
 
+def display_path(path_value: str) -> str:
+    if not path_value:
+        return path_value
+
+    path = Path(path_value).expanduser()
+    try:
+        return f"./{path.resolve().relative_to(REPO_ROOT)}"
+    except (OSError, ValueError):
+        return path_value
+
+
+def profile_doc_config(entry: dict[str, Any] | None) -> dict[str, Any]:
+    config = dict(DEFAULT_REPORT_CONFIG)
+    if entry is None:
+        return config
+
+    config.update(entry.get("benchmark_config", {}))
+    config["binary"] = display_path(str(config.get("binary", DEFAULT_REPORT_CONFIG["binary"])))
+    return config
+
+
+def profile_benchmark_command(profile_def: dict[str, Any], config: dict[str, Any]) -> str:
+    env = format_profile_env(
+        profile_def["env"],
+        int(config.get("threads", DEFAULT_REPORT_CONFIG["threads"])),
+        int(config.get("sink_bytes", DEFAULT_REPORT_CONFIG["sink_bytes"])),
+    )
+    command = [
+        "python3",
+        "scripts/benchmark_demo.py",
+        "--binary",
+        str(config.get("binary", DEFAULT_REPORT_CONFIG["binary"])),
+        "--scenario",
+        str(config.get("scenario", DEFAULT_REPORT_CONFIG["scenario"])),
+        "--iterations",
+        str(config.get("iterations", DEFAULT_REPORT_CONFIG["iterations"])),
+        "--runs",
+        str(config.get("runs", DEFAULT_REPORT_CONFIG["runs"])),
+    ]
+    for key, value in env.items():
+        command.extend(["--env", f"{key}={value}"])
+    return shlex.join(command)
+
+
+def profile_reference_lines(config: dict[str, Any]) -> list[str]:
+    lines = [
+        "## Profile reference",
+        "",
+        "The commands below rerun one profile at a time through",
+        "`scripts/benchmark_demo.py`. The harness handles the alternating",
+        "`SCOPE_TIMER=0` and `SCOPE_TIMER=1` passes for you; the `--env` flags",
+        "shown here are only the profile-specific knobs.",
+        "",
+        (
+            "These examples use "
+            f"`binary={config.get('binary', DEFAULT_REPORT_CONFIG['binary'])}`, "
+            f"`scenario={config.get('scenario', DEFAULT_REPORT_CONFIG['scenario'])}`, "
+            f"`iterations={config.get('iterations', DEFAULT_REPORT_CONFIG['iterations'])}`, "
+            f"`runs={config.get('runs', DEFAULT_REPORT_CONFIG['runs'])}`, "
+            f"`threads={config.get('threads', DEFAULT_REPORT_CONFIG['threads'])}`, "
+            f"and `sink_bytes={config.get('sink_bytes', DEFAULT_REPORT_CONFIG['sink_bytes'])}`."
+        ),
+        "",
+    ]
+
+    for profile_def in PROFILE_DEFS:
+        lines.extend(
+            [
+                f"### {profile_def['label']}",
+                "",
+                profile_def["description"],
+                "",
+                "```bash",
+                profile_benchmark_command(profile_def, config),
+                "```",
+                "",
+            ]
+        )
+
+    return lines
+
+
 def load_history(path: Path) -> dict[str, Any]:
     if not path.exists():
         return {"schema_version": SCHEMA_VERSION, "history": []}
@@ -247,6 +339,8 @@ def comparison_delta_text(comparison: dict[str, Any]) -> str:
 
 def render_report(history: dict[str, Any]) -> str:
     entries = history.get("history", [])
+    latest = entries[-1] if entries else None
+    doc_config = profile_doc_config(latest)
     lines = [
         "<!-- markdownlint-disable MD013 -->",
         "",
@@ -267,25 +361,12 @@ def render_report(history: dict[str, Any]) -> str:
         "`example/Benchmark.cpp`. `demo_benchmark_matrix` runs the full profile",
         "matrix, appends `benchmarks/demo_benchmark_history.json`, and refreshes",
         "this file with the latest snapshot.",
-        "",
-        "## Profile meanings",
-        "",
-        "| Profile | Meaning |",
-        "| --- | --- |",
     ]
 
-    for profile_def in PROFILE_DEFS:
-        lines.append(
-            "| "
-            f"{profile_def['label']} | "
-            f"{profile_def['description']} |"
-        )
-
-    lines.append("")
-
     if not entries:
         lines.extend(
             [
+                "",
                 "## Current benchmark snapshot",
                 "",
                 "No benchmark history has been recorded yet.",
@@ -299,15 +380,16 @@ def render_report(history: dict[str, Any]) -> str:
                 "`demo_benchmark_matrix` run.",
             ]
         )
+        lines.extend(["", *profile_reference_lines(doc_config)])
         return "\n".join(lines)
 
-    latest = entries[-1]
     previous = entries[-2] if len(entries) > 1 else None
     git = latest.get("git", {})
     config = latest.get("benchmark_config", {})
 
     lines.extend(
         [
+            "",
             "## Current benchmark snapshot",
             "",
             f"- Recorded at: `{latest.get('recorded_at_utc', 'unknown')}`",
@@ -373,6 +455,7 @@ def render_report(history: dict[str, Any]) -> str:
             "`benchmarks/demo_benchmark_history.json`.",
         ]
     )
+    lines.extend(["", *profile_reference_lines(doc_config)])
 
     return "\n".join(lines)