diff --git a/automated_updates_data.json b/automated_updates_data.json
index b2d10e2b2e4..488d8be0a72 100644
--- a/automated_updates_data.json
+++ b/automated_updates_data.json
@@ -92,6 +92,10 @@
     {
       "date": "2026-04-22",
       "summary": "Improved resources-loading docs (named Preload scene action, documented SceneLoadingProgress expression and AreSceneAssetsLoaded condition, clarified custom loading screen approach) and added extension lifecycle functions table to events/functions docs"
+    },
+    {
+      "date": "2026-06-16",
+      "summary": "Improved window docs: clarified game resolution vs window size, added resize mode (adaptWidth/adaptHeight), auto-adapt resolution, window centering/icon, and screen/window size expressions"
     }
   ]
 }
diff --git a/docs/gdevelop5/all-features/window/index.md b/docs/gdevelop5/all-features/window/index.md
index c3ef482243a..73c82eb3f28 100644
--- a/docs/gdevelop5/all-features/window/index.md
+++ b/docs/gdevelop5/all-features/window/index.md
@@ -15,21 +15,30 @@ The margin of the window is the distance between the side of the window and the
 
 Notice the black borders on all for sides of the window. The width of the borders is 100px.
 
-## Size of the window
+## Game resolution and window size
 
-Size of the window is the number of pixels visible in the game. The "Width" field refers to the number of pixels in the horizontal directions while the "Height" field refers to the number of pixels in the vertical direction.
+It's important to distinguish two different things:
 
-While setting the size of the window, if you want to scale the current area to the set resolution, choose "NO". This will decrease the visual quality of the game if the size entered is lower than default and will increase the visual quality if the size entered is higher than the default size.
+* The **game resolution** is the size of the game area, in pixels. It defines how much of your game world is visible at once. Changing it with the "Game resolution" action does not resize the system window: the game is stretched or shrunk to keep filling the window.
+* The **game window size** is the size of the system window on the player's desktop. The "Game window size" action only works on Windows, macOS and Linux — games running in a browser or on mobile can't resize their window.
+
+When changing the window size, you can also choose to update the game resolution to match. If you don't, the game keeps its current resolution and is stretched or reduced to fit the new window.
 
 ![](/gdevelop5/all-features/annotation_2019-06-29_175454.png)
 
-If you want to scale the set resolution to the window area, choose "YES". This will crop the window and display only the number of pixels entered in the action. This does not affect the visual quality as long as the game is scaled up or down because of the size of the system window.
+## Adapting to the screen size
+
+The **resize mode** controls how the game resolution reacts when the window or screen size changes:
+
+* `adaptWidth` keeps the game height fixed and adjusts the width to fill the window or screen.
+* `adaptHeight` keeps the height adjusting instead, fixing the width.
+* Leaving it empty disables resizing, so the game is stretched or reduced to fit the window.
 
-!!! note
+This is useful to support many screen ratios (for example on mobile) without leaving black borders. By default the game resolution is decided at startup; use the "Automatically adapt the game resolution" action so it keeps updating as the window or screen size changes.
 
-    The game is cropped starting from the top-left corner of the game.
+## Centering and the window icon
 
-![](/gdevelop5/all-features/annotation_2019-06-29_175540.png)
+On Windows, macOS and Linux you can center the game window on the screen, and change the icon used by the game's window. These actions have no effect in a browser or on mobile.
 
 ## Window title
 
@@ -39,6 +48,13 @@ By default, the game name is used for the executable name (on Windows, macOS and
 
 With the action to change the title, the title bar on Windows, macOS and Linux will be changed. Nothing will be visible on Android and iOS. For HTML5 games, the web page title will be changed.
 
+## Reading the screen and window size
+
+Several expressions let you read sizes at runtime, which is handy to position interface elements relative to the visible area:
+
+* `SceneWindowWidth` and `SceneWindowHeight` return the size of the scene window (the game canvas for HTML5 games).
+* `ScreenWidth` and `ScreenHeight` return the size of the screen, or of the page for HTML5 games running in a browser.
+
 ## Reference
 
 All actions, conditions and expressions are listed in [the window reference page](/gdevelop5/all-features/window/reference/).
\ No newline at end of file