Add README for performance regression

Author: Shigoto-dev19

tests/perf-regression/README.md

@@ -0,0 +1,73 @@
+# About Performance Regression — Developer Guide
+
+The performance regression framework is designed to detect regressions in
+ZkProgram execution (compile, prove, verify) and compile-time performance of
+constraint systems (CS) and zkApps.
+
+## Overview
+
+- **ZkProgram regression** — handled by
+  [src/lib/testing/perf-regression.ts](../../src/lib/testing/perf-regression.ts),
+  measuring individual ZkPrograms (e.g., SHA256, ECDSA).
+- **CS & zkApp regression** — handled by
+  [tests/perf-regression/perf-regression.ts](./perf-regression.ts), measuring
+  compile-time performance for zkApp examples.
+
+Both use the same JSON file,
+[tests/perf-regression/perf-regression.json](./perf-regression.json) and is
+automatically used by CI to compare new performance data against existing
+baselines and should only be dumped by triggering the CI workflow (see
+[CI Integration](#ci-integration)).
+
+## Modes
+
+- `--check`: Compares current benchmarks with the stored baseline to detect
+  regressions. Used by CI in PRs.
+- `--dump`: Regenerates the baseline with fresh values, replacing the JSON data.
+  Used only via GitHub runners for consistency.
+
+## Usage
+
+### Dump all examples (local)
+
+```bash
+npm run regression:dump-perf
+```
+
+### Check all examples (local)
+
+```bash
+npm run regression:check-perf
+```
+
+## CI Integration
+
+- **PR checks**: Automatically run in `--check` mode. CI compares results
+  against the committed baseline.
+- **Baseline updates**: Manually trigger the workflow
+  [dump-perf-baseline.yml](../../.github/workflows/dump-perf-baseline.yml) to
+  run in `--dump`, regenerate the baseline, and commit it to the same branch.
+  - To trigger the CI workflow manually:
+
+    ```bash
+    gh workflow run dump-perf-baseline.yml -r $(git rev-parse --abbrev-ref HEAD)
+    ```
+
+  - **Note:** Baselines must be generated by CI to avoid local machine variance.
+    That's why you should NOT commit local dumps.
+
+## Local vs CI
+
+| Environment          | Mode                 | Description                                                                                   |
+| -------------------- | -------------------- | --------------------------------------------------------------------------------------------- |
+| **Local**            | `--dump` / `--check` | Developers can test performance locally. Results vary by hardware; do not commit local dumps. |
+| **CI (PR)**          | `--check`            | Ensures performance consistency against the repo’s baseline.                                  |
+| **CI (Manual Dump)** | `--dump`             | Refreshes the baseline via GitHub runners and commits updates.                                |
+
+## Notes
+
+- To see which examples are covered, check
+  [perf-regression.sh](./perf-regression.sh).
+
+- Without explicit `--dump` or `--check`, the framework behaves like `tic/toc`,
+  enabling seamless use in standard runs.