diff --git a/build/ripple/README.md b/build/ripple/README.md
index 62e9a07e9e2abe..3bb871471b6004 100644
--- a/build/ripple/README.md
+++ b/build/ripple/README.md
@@ -4,6 +4,10 @@ A content-addressed change impact engine for TypeScript repositories, written in
 
 It is a prototype for running far fewer CI minutes on pull requests: instead of running every suite on every push on three operating systems, CI asks ripple what the change can affect and runs only that.
 
+An overview of the problem, how ripple works and how CI uses it, from [#342907](https://github.com/microsoft/vscode/pull/342907):
+
+https://github.com/user-attachments/assets/354ed24f-ebe3-44bf-a60f-32bc0fcbbe0a
+
 ## In pull request CI
 
 The `Detect Changes` job of [pr.yml](../../.github/workflows/pr.yml) runs `ripple plan --config build/ripple/vscode.jsonc --base HEAD^1 --head HEAD --out-dir .build/unit-test-plan` on the pull request's merge commit, uploads the plan as the `unit-test-plan` artifact and writes a summary to the job page. Linux runs every unit test on every push; the macOS and Windows unit test jobs download the artifact and pass its `unit.txt` to each test runner with `--runList`. Each runner runs the tests it would run by default, but only from the listed files (see [test/unit/README.md](../../test/unit/README.md)), so ripple needs no knowledge of the runners. When the plan selects no file, those jobs are skipped instead of setting up to run nothing (the `selected-unit-tests` output of `Detect Changes`). The Browser ones are also skipped when no selected file is a browser test, because the browser runner does not load the test files in `node`, `electron-browser`, `electron-main` and `electron-utility` folders (the `selected-browser-unit-tests` output; `BROWSER_EXCLUDED_FOLDERS` in the `Check ripple` step must match the `excludeGlob` of [test/unit/browser/index.js](../../test/unit/browser/index.js), which a test checks). The Electron ones load every test folder. They run every unit test when planning fails, when the artifact cannot be downloaded, or when the change touches a file that every unit test depends on (`runEverything` in the configuration); otherwise they run the selected files, however many. When planning fails, the job summary says that every unit test runs. The planning steps never fail `Detect Changes`, which a broken ripple must not block. When ripple fails to build, pass its tests or plan, the `Ripple` check fails for pull requests that change `build/ripple`; it is skipped for the others, which show a warning. So does a module that ripple cannot parse, which disables selection. The binary is cached by its sources; [pr-ripple.yml](../../.github/workflows/pr-ripple.yml) builds it on `main` when they change, and checks daily that the cache still exists.