1 files changed, 50 insertions, 0 deletions
diff --git a/scripts/README.md b/scripts/README.md
new file mode 100644
index 0000000..91adbd3
--- /dev/null
+++ b/scripts/README.md
@@ -0,0 +1,50 @@
+# Report scripts
+
+Portable POSIX-sh tooling to generate reports from the bats test suite. All
+entrypoints run under mingw bash, WSL bash and Alpine/busybox ash, and depend
+only on `bats`, `awk`, `sort` and coreutils.
+
+## `profile-tests.sh` 
+
+Per-test timing (and optional per-line hotspots). See `doc/profiling.md`.
+## `profile-run.sh`
+
+Direct profiling for real `trbldoc.sh` invocations (outside bats). Produces:
+
+- per-run wall-clock summary (`run-summary.csv`)
+- line hotspots (`hotspots.html`)
+- pipeline phase hotspots inferred from trace line ranges (`phase-hotspots.html`)
+
+Example:
+
+```sh
+sh scripts/profile-run.sh -n 3 -C -- -s tests/fixtures/pipeline -o .trblcache/built
+```
+## `hotspot-tests.sh`
+
+Repeatable hotspot analysis for the bats suite without relying on JUnit output.
+It captures:
+
+- per-test timing from raw `bats --timing` output
+- line hotspots from xtrace logs
+- optional phase hotspots for `trbldoc.sh` (when helper scripts are present)
+
+```sh
+sh scripts/hotspot-tests.sh -s all -n 30
+```
+
+## `coverage-tests.sh` 
+
+Shell line coverage of `trbldoc.sh`. See `doc/coverage.md`.
+
+## `generate-reports.sh` 
+
+Run both into one timestamped `reports/` directory. Puts reports into a
+`reports/run-<timestamp>/` directory.
+
+```sh
+sh scripts/generate-reports.sh -p
+```
+
+`lib/` holds shared helpers: `common.sh` (sh helpers), `trace-init.sh` (the
+`BASH_ENV` xtrace hook), and the `*.awk` extractors/renderers.