diff --git a/CHANGELOG.md b/CHANGELOG.md
index fb55355f..218bdfa1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,7 @@
 - `bashunit doc <filter>` says `No assertion matches '<filter>'` instead of printing nothing, which was indistinguishable from a broken install. Mirrors the existing `--custom` wording; the exit code stays 0 because `doc` is informational (#1201)
 - `install.sh` destination errors no longer advise a `-d` flag that does not exist — the script takes positional arguments, so following the advice produced `Invalid arguments`. The one message whose job is to tell you how to recover pointed at a form the parser rejects (#1221)
 - The `example/` demo is covered by the suite. `docs/examples.md` and `example/README.md` send new users to `./bashunit example` as their first contact with the framework, and nothing ran it — `make test` collects from `tests/` only — so it could break while CI stayed green. The dead `EXAMPLE_TEST_SCRIPTS` variable, pointing at a file deleted several releases ago, is gone with it (#1219)
+- Docs: the project overview told new contributors to run benchmarks with `-s -b` / `--simple --bench`, neither of which exists — both are rejected as unknown options. Benchmarks are the `bashunit bench [path]` subcommand (#1227)
 - Docs: the drop-in agent rules described `assert_equals` as trimming or normalizing. It strips ANSI colour codes, tabs and newlines — not spaces, so `assert_equals "a" " a "` fails. That block is written to be pasted verbatim into an `AGENTS.md`, so the error propagated into every repo adopting it (#1225)
 - Docs: an empty entry in the `-e/--env/--boot` file assigns an empty value rather than restoring the built-in default, so blanking a boolean disables it; the guide said it "wipes" the value, which reads as a reset. The rest of the precedence ladder is now covered by tests (#1217)
 - Docs: the test-function name rule is stated correctly — the prefix is a literal, lowercase `test_`, so the guide's own `testRenderAllTestsPassedWhenNotFailedTests` example and its claim that names are case-insensitive were both wrong, and a function named either way is silently never run (#1215)
diff --git a/docs/project-overview.md b/docs/project-overview.md
index d651504e..f62f1168 100644
--- a/docs/project-overview.md
+++ b/docs/project-overview.md
@@ -57,15 +57,17 @@ The project uses bashunit to test itself. To execute the full suite, run:
 
 ::: code-group
 ```bash [Quick]
-./bashunit -s -p tests # Regular tests
-./bashunit -s -b tests # Benchmark tests
+./bashunit -s -p tests      # Regular tests
+./bashunit bench -s tests   # Benchmark tests
 ```
 ```bash [Complete]
 ./bashunit --simple --parallel tests # Regular tests
-./bashunit --simple --bench    tests # Benchmark tests
+./bashunit bench --simple      tests # Benchmark tests
 ```
 :::
 
+Benchmarks are a subcommand, not a flag on the test run: `bashunit bench [path]`.
+
 
 > See more command line options: [here](/command-line)