docs: index.html is generated into frontend/generated again

articles/flow/advanced/modifying-the-bootstrap-page.adoc

@@ -18,25 +18,25 @@
 
 The developer has full control of the contents of [filename]`index.html`. You can modify it in various ways.
 
-On the client side, you can edit [filename]`frontend/index.html` when the content is static, for instance the `<viewport>` tag. On the server side, you can make changes that require dynamic server content, or when Java syntax is preferred. An example of would be making the application installable by enabling the `@PWA` built-in feature.
+On the client side, you can take control of [filename]`index.html` when the content is static, for instance the `<viewport>` tag. Copy the generated file into the [filename]`frontend` folder rather than writing one from scratch, as described in <<default-bootstrap-template-and-entry-point, Default Template & Entry Point>>. On the server side, you can make changes that require dynamic server content, or when Java syntax is preferred. An example of would be making the application installable by enabling the `@PWA` built-in feature.
 
 You can implement [interfacename]`AppShellConfigurator` for cases covered by the [classname]`AppShellSettings` API, or by annotations. And you can configure an [interfacename]`IndexHtmlRequestListener` for advanced cases to modify the document structure.
 
 
 == Application Shell Template
 
-The Vaadin servlet uses the [filename]`frontend/index.html` file as a template to generate the bootstrap page response. The servlet processes the template and injects the following information:
+The Vaadin servlet uses an [filename]`index.html` file as a template to generate the bootstrap page response: the one in the [filename]`frontend` folder where the project has one, and the generated default otherwise. The servlet processes the template and injects the following information:
 
 - `<base href='./relative/to/root'>`: Vaadin calculates the relative path from the current request path to the root path of the application. This is required for relative links in view templates to work correctly.
-- Bundled script: Vaadin automatically adds the bundled and optimized script generated from the [filename]`frontend/index.tsx` file. It uses a pre-configured https://vitejs.dev/[Vite] instance that's included with `vaadin-maven-plugin` as a module bundler. Therefore, the [filename]`frontend/index.html` template doesn't need to include explicitly the [filename]`index.tsx` script -- or the [filename]`index.ts` or [filename]`index.js` script.
+- Bundled script: Vaadin automatically adds the bundled and optimized script generated from the [filename]`frontend/index.tsx` file. It uses a pre-configured https://vitejs.dev/[Vite] instance that's included with `vaadin-maven-plugin` as a module bundler. Therefore, the [filename]`index.html` template doesn't need to include explicitly the [filename]`index.tsx` script -- or the [filename]`index.ts` or [filename]`index.js` script.
 
 [TIP]
 The `frontend` directory path can be changed with the `frontendDirectory` parameter of `vaadin-maven-plugin`, which the `prepare-frontend` and `build-frontend` goals use. The build records the path so that the application can read it at runtime from the `vaadin.frontend.folder` property. See <<{articles}/flow/configuration/maven#properties, Plugin Configuration Options>> for details.
 
 
 === Default Template & Entry Point [[default-bootstrap-template-and-entry-point]]
 
-If the [filename]`index.html` or [filename]`index.tsx` files in the frontend folder are missing, `vaadin-maven-plugin` generates a default corresponding file in the [filename]`target` folder. In that case, the application uses only server-side routing. You can take control of these files by moving them into the [filename]`frontend` folder. By default, these files look similar to the following:
+Where the [filename]`index.html` or [filename]`index.tsx` file is missing from the frontend folder, the build generates a default into [filename]`frontend/generated/`, so neither file has to exist in the project. For [filename]`index.html`, that location is [since:com.vaadin:vaadin@V25.3]#new in Vaadin 25.3#: earlier versions generated the file into the [filename]`frontend` folder itself. Without an [filename]`index.tsx`, the application uses only server-side routing. To take control of one of these files, copy it from [filename]`frontend/generated/` into the [filename]`frontend` folder, where it replaces the generated default. By default, these files look similar to the following:
 
 .Default `index.html`
 [source,html]

articles/flow/configuration/source-control.adoc

@@ -19,8 +19,8 @@ src/
 │   │   ├── dev.bundle           <4>
 │   │   └── prod.bundle          <5>
 │   ├── frontend/                <6>
-│   │   ├── generated/
-│   │   └── index.html           <7>
+│   │   └── generated/
+│   │       └── index.html       <7>
 │   ├── java/
 │   └── resources/
 │       └── META-INF/
@@ -41,7 +41,7 @@ vite.generated.ts                <16>
 <4> Compressed archive containing development time frontend files/resources.
 <5> Compressed archive containing production time frontend files/resources.
 <6> Frontend resources, like TypeScript and JavaScript files, are placed in this folder.
-<7> [filename]`index.html` is an initially auto-generated file that defines the outermost structure of the application. This file can be added to source control, and should be if customized. For customization of index.html see <<../advanced/modifying-the-bootstrap-page#modifying-the-application-shell, Modifying the Application Shell>>.
+<7> [filename]`index.html` defines the outermost structure of the application. A project doesn't need one of its own: Vaadin generates a default into [filename]`frontend/generated/`, which stays out of source control. To customize the application shell, copy the generated file into the [filename]`frontend` folder. It then replaces the generated default and should be committed. For customization of index.html see <<../advanced/modifying-the-bootstrap-page#modifying-the-application-shell, Modifying the Application Shell>>.
 <8> Static web resources such as images and stylesheets are placed in this folder.
 <9> Test sources.
 <10> [filename]`package.json` defines the version ranges of the frontend dependencies.
@@ -64,7 +64,7 @@ The following files and folders should be added to source control:
 * <2> [filename]`src/main/` - Application sources
 * <3> <4> <5> [filename]`bundles/` - Pre-compiled frontend bundles
 * <6> [filename]`frontend/` - Frontend resources (excluding `generated/`)
-* <7> [filename]`index.html` - Can be committed if generated, should be if customized
+* <7> [filename]`index.html` - Only when the project has one of its own
 * <8> [filename]`META-INF/resources/` - Static web resources
 * <9> [filename]`src/test/` - Test sources
 * <10> [filename]`package.json` - If exists

articles/upgrading/index.adoc

@@ -222,6 +222,12 @@ Update any build step that reads the bundle straight from the build directory --
 
 Starting with Vaadin 25.2, npm package versions published less than one day ago are ignored when frontend dependencies are installed, as a protection against supply-chain attacks. If your project depends on a package version that was published less than a day ago, the installation fails or resolves to an older version until the package version is old enough. The minimum age is configured with the `vaadin.npm.minimumFrontendPackageAgeDays` system property; setting it to `0` disables the check. See <<{articles}/flow/configuration/development-mode/npm-pnpm-bun#delayed-package-installation, Delayed Installation of Recently Published Packages>> for details.
 
+=== Default `index.html` Generated Into `frontend/generated/`
+
+Starting with Vaadin 25.3, the build writes the default [filename]`index.html` to [filename]`frontend/generated/` rather than to the [filename]`frontend` folder, and generates it only when the project has no [filename]`frontend/index.html` of its own.
+
+A project upgraded from an earlier version usually has an [filename]`index.html` in [filename]`frontend`, auto-generated there by the older build and committed to source control. That file still takes precedence, so an uncustomized copy keeps shadowing the default and the application doesn't pick up later improvements to it. Compare the file against the default; if it hasn't been customized, delete it and let the build generate it. Keep it only for customizations of the application shell. See <<{articles}/flow/advanced/modifying-the-bootstrap-page#default-bootstrap-template-and-entry-point, Default Template & Entry Point>> for details.
+
 == Development Tools
 
 Development tools are opt-in feature in Vaadin 25. `vaadin-dev` module isn't included transitively by default anymore via `vaadin` or `vaadin-core` or any other Vaadin dependencies. To include it, add following dependency to your build configuration: