diff --git a/docs/images/full-oauth-flow-oidc/1-initial-load.png b/docs/images/full-oauth-flow-oidc/1-initial-load.png
index e6d2b2d..6e90401 100644
Binary files a/docs/images/full-oauth-flow-oidc/1-initial-load.png and b/docs/images/full-oauth-flow-oidc/1-initial-load.png differ
diff --git a/docs/images/full-oauth-flow-oidc/2-after-login-submit.png b/docs/images/full-oauth-flow-oidc/2-after-login-submit.png
index 36301e2..13dbc63 100644
Binary files a/docs/images/full-oauth-flow-oidc/2-after-login-submit.png and b/docs/images/full-oauth-flow-oidc/2-after-login-submit.png differ
diff --git a/docs/images/full-oauth-flow-oidc/3-after-consent-submit.png b/docs/images/full-oauth-flow-oidc/3-after-consent-submit.png
index dc0259c..fbc61cd 100644
Binary files a/docs/images/full-oauth-flow-oidc/3-after-consent-submit.png and b/docs/images/full-oauth-flow-oidc/3-after-consent-submit.png differ
diff --git a/docs/images/remember-me/1-initial-load.png b/docs/images/remember-me/1-initial-load.png
index 79a7219..6e90401 100644
Binary files a/docs/images/remember-me/1-initial-load.png and b/docs/images/remember-me/1-initial-load.png differ
diff --git a/docs/images/remember-me/2-after-login-submit.png b/docs/images/remember-me/2-after-login-submit.png
index 96dd487..13dbc63 100644
Binary files a/docs/images/remember-me/2-after-login-submit.png and b/docs/images/remember-me/2-after-login-submit.png differ
diff --git a/docs/images/remember-me/3-after-consent-submit.png b/docs/images/remember-me/3-after-consent-submit.png
index da6568c..dd8e5b8 100644
Binary files a/docs/images/remember-me/3-after-consent-submit.png and b/docs/images/remember-me/3-after-consent-submit.png differ
diff --git a/docs/images/remember-me/4-initial-load-second-time.png b/docs/images/remember-me/4-initial-load-second-time.png
index 8ce7e58..df99593 100644
Binary files a/docs/images/remember-me/4-initial-load-second-time.png and b/docs/images/remember-me/4-initial-load-second-time.png differ
diff --git a/docs/images/remember-me/5-after-login-submit-second-time.png b/docs/images/remember-me/5-after-login-submit-second-time.png
index 1c61ac7..a978c29 100644
Binary files a/docs/images/remember-me/5-after-login-submit-second-time.png and b/docs/images/remember-me/5-after-login-submit-second-time.png differ
diff --git a/reference-app/build.gradle.kts b/reference-app/build.gradle.kts
index 6ed71b5..63c2f12 100644
--- a/reference-app/build.gradle.kts
+++ b/reference-app/build.gradle.kts
@@ -47,6 +47,38 @@ tasks.withType<JavaCompile> {
     }
 }
 
+// The images embedded in the README are the screenshots the functional tests capture on every
+// run. This task republishes them into docs/images so they can be regenerated on purpose instead
+// of drifting (the previous set dated from 2022). Keys are docs/images/<flow> directory names,
+// values the producing test's screenshot directory under build/test-results/screenshots.
+val readmeScreenshotFlows =
+    mapOf(
+        "full-oauth-flow-oidc" to "completeFullOAuthFlowUsingUIToLogin",
+        "remember-me" to "skipConsentScreenOnSecondLoginWhenRememberMeIsUsed",
+    )
+
+tasks.register("refreshReadmeScreenshots") {
+    group = "documentation"
+    description = "Reruns the functional tests and copies their screenshots into docs/images."
+    dependsOn(tasks.test)
+    val screenshotsDir = layout.buildDirectory.dir("test-results/screenshots")
+    val docsImagesDir =
+        rootProject.layout.projectDirectory
+            .dir("docs/images")
+            .asFile
+    doLast {
+        readmeScreenshotFlows.forEach { (flow, testName) ->
+            val source = screenshotsDir.get().dir(testName).asFile
+            require(source.isDirectory && !source.listFiles().isNullOrEmpty()) {
+                "No screenshots at $source — did the test get renamed without updating this mapping?"
+            }
+            val target = docsImagesDir.resolve(flow)
+            target.deleteRecursively()
+            source.copyRecursively(target)
+        }
+    }
+}
+
 // A way to run Playwright CLI commands using the Java source dependency.
 // Particularly useful from within a CI context (see ./.github/workflows.gradle.yml).
 // https://playwright.dev/docs/cli#install-system-dependencies
diff --git a/reference-app/src/test/java/com/ardetrick/oryhydrareference/OryHydraReferenceApplicationFunctionalTests.java b/reference-app/src/test/java/com/ardetrick/oryhydrareference/OryHydraReferenceApplicationFunctionalTests.java
index 2b9ed92..8ce353a 100644
--- a/reference-app/src/test/java/com/ardetrick/oryhydrareference/OryHydraReferenceApplicationFunctionalTests.java
+++ b/reference-app/src/test/java/com/ardetrick/oryhydrareference/OryHydraReferenceApplicationFunctionalTests.java
@@ -123,10 +123,12 @@ void stopTestEnvironment() {
     oryHydraContainer.stop();
   }
 
-  // Every screenshot these tests capture is destined for the docs, so the viewport is pinned
-  // rather than left at Playwright's default — a Playwright upgrade must not resize the images.
+  // Every screenshot these tests capture is destined for the docs, so the viewport is pinned —
+  // a Playwright upgrade must not resize the images. 640x400 rather than the 1280x720 default
+  // because GitHub scales README images down to its ~880px column but never up: captures
+  // narrower than the column render 1:1, and the unstyled pages carry less dead space.
   private Page newPage() {
-    return browser.newPage(new Browser.NewPageOptions().setViewportSize(1280, 720));
+    return browser.newPage(new Browser.NewPageOptions().setViewportSize(640, 400));
   }
 
   @BeforeEach