diff --git a/.github/workflows/demo.yml b/.github/workflows/demo.yml
index edfe7842..ceebceed 100644
--- a/.github/workflows/demo.yml
+++ b/.github/workflows/demo.yml
@@ -42,58 +42,79 @@ jobs:
             -tz Asia/Saigon \
             -out demo
 
-      - name: Write demo README
+      - name: Write demo READMEs (index + per-theme)
         env:
           OWNER: ${{ github.repository_owner }}
           REPO: ${{ github.repository }}
         run: |
-          cards=(
-            profile-details
-            repos-per-language
-            most-commit-language
-            stats
-            productive-time
-            productive-weekday
-            contributions
-            contributions-heatmap
-            top-starred-repos
-            streak
-            most-commit-language-all-time
-            productive-time-all-time
-            productive-weekday-all-time
-            contributions-all-time
-            contributions-by-year
-          )
           themes=$(./ghstats -list-themes)
+
+          # Lightweight index so readers don't have to load ~975 images at once.
           {
             echo "# ghstats demo gallery"
             echo
-            echo "Every card in every theme, rendered for [\`$OWNER\`](https://github.com/$OWNER)."
+            echo "Every card rendered for [\`$OWNER\`](https://github.com/$OWNER) in every supported theme. Click a theme to open its gallery page — each page embeds 15 SVGs, so only the theme you're reviewing is fetched."
             echo
             echo "Auto-generated by [\`.github/workflows/demo.yml\`](../.github/workflows/demo.yml) on each push to \`main\`. Do not edit by hand."
             echo
             echo "## Themes"
             echo
-            for theme in $themes; do
-              echo "- [\`$theme\`](#$theme)"
-            done
-            echo
             for theme in $themes; do
               dir="demo/$theme"
               [ -d "$dir" ] || continue
-              echo "## $theme"
-              echo
-              for card in "${cards[@]}"; do
-                svg="$dir/$card.svg"
-                [ -f "$svg" ] || continue
-                echo "![$card](./$theme/$card.svg)"
-              done
-              echo
-              echo "[back to top](#themes)"
-              echo
+              echo "- [\`$theme\`](./$theme/README.md)"
             done
           } > demo/README.md
 
+          # Per-theme page groups singletons at top, then compares last-year
+          # vs all-time variants side-by-side so the reader can eyeball the
+          # evolution of each metric without scrolling.
+          for theme in $themes; do
+            dir="demo/$theme"
+            [ -d "$dir" ] || continue
+            out="$dir/README.md"
+            pair() {
+              local heading="$1" left="$2" right="$3"
+              [ -f "$dir/$left.svg" ] && [ -f "$dir/$right.svg" ] || return
+              printf '### %s\n\n' "$heading"
+              printf '<table><tr><th>Last year</th><th>All time</th></tr><tr>\n'
+              printf '<td><img src="./%s.svg" alt="%s" /></td>\n' "$left" "$left"
+              printf '<td><img src="./%s.svg" alt="%s" /></td>\n' "$right" "$right"
+              printf '</tr></table>\n\n'
+            }
+            single() {
+              local heading="$1" name="$2"
+              [ -f "$dir/$name.svg" ] || return
+              printf '### %s\n\n![%s](./%s.svg)\n\n' "$heading" "$name" "$name"
+            }
+            {
+              printf '# ghstats — %s\n\n' "$theme"
+              printf '[← back to index](../README.md)\n\n'
+              printf 'Rendered for [`%s`](https://github.com/%s). 15 SVGs below, ' "$OWNER" "$OWNER"
+              printf 'grouped so the last-year / all-time pairs sit next to each other.\n\n'
+              printf '## At-a-glance\n\n'
+              single "Profile" profile-details
+              single "Stats"   stats
+              single "Streak"  streak
+
+              printf '## Repos\n\n'
+              single "Top starred"     top-starred-repos
+              single "Repos per language" repos-per-language
+
+              printf '## Contributions — time series\n\n'
+              single "Calendar heatmap (last year)" contributions-heatmap
+              single "By year (all time)"           contributions-by-year
+              pair   "Monthly shape"  contributions            contributions-all-time
+
+              printf '## When you commit\n\n'
+              pair "By hour of day" productive-time    productive-time-all-time
+              pair "By day of week" productive-weekday productive-weekday-all-time
+
+              printf '## What you commit in\n\n'
+              pair "Byte-weighted language share" most-commit-language most-commit-language-all-time
+            } > "$out"
+          done
+
       - name: Commit demo back to main
         run: |
           git config user.name "github-actions[bot]"