docs: Add Incremental Build Vitepress docs

internal/documentation/docs/pages/Builder.md

@@ -199,3 +199,30 @@ sap.ui.define([], () => {
     text-decoration: inherit;
 }
 </style>
+
+## Build Cache Control
+
+The UI5 Builder integrates **build caches**. Instead of rebuilding everything from scratch, the UI5 Builder tracks which resources have changed and which build tasks need to be re-executed:
+
+You can control the build cache behavior using the `--cache` option:
+
+- `--cache Default` (default): Use the cache if available, create it if missing
+- `--cache Force`: Only use the cache; fail if the cache is unavailable or invalid
+- `--cache ReadOnly`: Use existing cache but don't update it (useful for CI/CD)
+- `--cache Off`: Disable caching entirely and always perform a full rebuild
+
+Example:
+```sh
+ui5 build --cache Off
+```
+In this scenario, when a source file change is made, always perform a full rebuild (even if this source version already existed sometime ago).
+
+::: info
+By default, the build cache is stored inside UI5 CLI's Data Dir (`~/.ui5/buildCache/`). You can customize the location (see [Changing UI5 CLI's Data Directory](./Troubleshooting#changing-ui5-cli-s-data-directory)).
+:::
+
+::: info
+Build caches created by `ui5 build` and `ui5 serve` are **separate and cannot be mixed**. Each command maintains its own cache optimized for its specific use case. For more details on server caching, see the [UI5 Server documentation](./Server.md).
+:::
+
+

internal/documentation/docs/pages/Server.md

@@ -87,6 +87,49 @@ Answers all non-read requests (POST, PUT, DELETE, etc.) that have not been answe
 ### serveIndex
 In case a directory has been requested, this middleware renders an HTML with a list of the directory's content.
 
+## Standard Tasks
+As with the UI5 Builder, a set of standard tasks is being executed during a server build. However, following tasks are being **excluded by default**:
+- `minify`
+- `generateLibraryPreload`
+- `generateComponentPreload`
+- `generateBundle`
+
+::: info
+See [Builder Standard Tasks](./Builder.md#standard-tasks) for more explanation about each task.
+:::
+
+## Build Cache Control
+
+The UI5 Server performs a build of the projects by utilizing **build caches**.
+
+You can control the build cache behavior using the `--cache` option:
+
+- `--cache Default` (default): Use the cache if available, create it if missing
+- `--cache Force`: Only use the cache; fail if the cache is unavailable or invalid
+- `--cache ReadOnly`: Use existing cache but don't update it (useful for CI/CD)
+- `--cache Off`: Disable caching entirely and always perform a full rebuild
+
+Example:
+```sh
+ui5 serve --cache Off
+```
+In this scenario, when a source file change is made and a request comes in, the server always performs a full rebuild (even if this source version already existed sometime ago).
+
+::: info
+Build caches created by `ui5 build` and `ui5 serve` are **separate and cannot be mixed**. Each command maintains its own cache optimized for its specific use case. For more details on builder caching, see the [UI5 Builder documentation](./Builder.md).
+:::
+
+### Watch Mode Behavior
+
+Once started with `ui5 serve`, the server automatically keeps watch over changes to the source files throughout the session. When a request arrives, it checks for cached results first and only triggers a rebuild of the respective resources and tasks if no cache is available.
+
+- **Monitored files**: All files in your project's source directories (`src/`, `webapp/`, `test/`, etc.)
+- **Not monitored**: Configuration files (`ui5.yaml`, `package.json`), custom task implementations, and dependency files
+
+::: info
+Changes to configuration files or custom tasks require a server restart to take effect.
+:::
+
 ## SSL Certificates
 When starting the UI5 Server in HTTPS- or HTTP/2 mode, for example by using UI5 CLI parameter `--h2`, you will be prompted for the automatic generation of a local SSL certificate if necessary.
 

internal/documentation/docs/pages/extensibility/CustomTasks.md

@@ -286,11 +286,37 @@ module.exports.determineRequiredDependencies = async function({availableDependen
 ```
 :::
 
+### "Cache-aware" Tasks 
+
+Due to UI5 Builder and UI5 Server supporting **build caches** of task data, custom tasks can opt into this behavior to improve performance. This is done by implementing the following features:
+
+#### `supportsDifferentialBuilds()`
+
+This method indicates whether your task can perform differential builds:
+
+```js
+/**
+ * Indicates whether this task can perform differential builds
+ * 
+ * @returns {boolean} True if the task can process only modified resources
+ */
+export function supportsDifferentialBuilds() {
+    return true;
+}
+```
+
+When this returns `true`, your task's main function receives an additional parameter indicating which resources have changed. The task can then process only those resources instead of all resources.
+
+::: info Best Practices for Cache-aware Tasks
+1. **Keep tasks deterministic**: Given the same inputs, always produce the same outputs
+2. **Opt into differential builds carefully**: Only set `supportsDifferentialBuilds = true` if your task can safely process files independently
+:::
+
 ### Examples
 
 The following code snippets show examples for custom task implementations.
 
-### Example: lib/tasks/renderMarkdownFiles.js
+#### Example: lib/tasks/renderMarkdownFiles.js
 
 This example is making use of the `resourceFactory` [TaskUtil](https://ui5.github.io/cli/v5/api/@ui5_project_build_helpers_TaskUtil.html)
 API to create new resources based on the output of a third-party module for rendering Markdown files. The created resources are added to the build
@@ -364,7 +390,7 @@ Tasks should ideally use the reader/writer APIs provided by UI5 CLI for working
 
 :::
 
-### Example: lib/tasks/compileLicenseSummary.js
+#### Example: lib/tasks/compileLicenseSummary.js
 
 This example is making use of multiple [TaskUtil](https://ui5.github.io/cli/v5/api/@ui5_project_build_helpers_TaskUtil.html)
 APIs to retrieve additional information about the project currently being built (`taskUtil.getProject()`) and its direct dependencies

internal/documentation/docs/updates/migrate-v5.md

@@ -29,6 +29,47 @@ UI5 CLI 5.x introduces **Specification Version 5.0**, which enables the new Comp
 
 Projects using older **Specification Versions** are expected to be **fully compatible with UI5 CLI v5**.
 
+## Build Cache
+
+UI5 CLI v5 introduces **builds with caching** for both commands `ui5 build` and `ui5 serve`. This fundamental architectural change significantly improves build performance by reusing cached results from previous builds.
+
+### What Changed
+
+**Previous Behavior (v4 and earlier):**
+- Every source change resulted in an entire rebuild of all projects
+- Every build re-executed all tasks
+- No caching between builds or server sessions
+
+**New Behavior (v5):**
+- Only relevant projects are rebuilt
+- Only modified resources and affected tasks are re-processed
+
+### Impact on Your Workflow
+
+- **First build**: Probably slightly slower, as the cache is populated with all build outputs
+- **Subsequent builds**: Significantly faster — only modified resources and affected tasks are reprocessed
+- **Quick iterations**: Changes to individual files typically rebuild very quickly
+- **Cross-session**: Caches are used between server restarts and build runs
+
+### For `ui5 build`
+
+When `ui5 build` is executed, build caches are automatically serialized and reused when available.
+
+::: tip Tip for Single Builds (e.g. CI/CD)
+If you plan to execute a build only once (e.g. during a CI run), consider using `--cache "Off"` (see [Build Cache Control](../pages/Builder.md#build-cache-control)) to skip cache serialization.
+:::
+
+### For `ui5 serve`
+
+During a server session (started by `ui5 serve`), source changes are automatically being monitered. Then, if a request was made, the server detects this, tries to use caches and only rebuilds when none are available. For more information see [Watch Mode Behavior](../pages/Server.md#watch-mode-behavior).
+
+::: info Review custom middleware
+
+With this feature, **build tasks are executed in server sessions**. For this reason, some custom middleware might be obsolete or cause problems. Projects utilizing such might need to adapt their configuration.
+
+E.g. Middleware for browser live reloads is obsolete and can be removed. Also, middleware for Typescript transpilation is not required anymore (as long as the respective task is still set up).
+:::
+
 ## Rename of Command Option
 
 With UI5 CLI v5, the option `--cache-mode` (for commands `ui5 build` and `ui5 serve`) has been renamed to `--snapshot-cache`.