docs(documentation): Update server docs for v5 architecture

internal/documentation/docs/index.md

@@ -141,4 +141,98 @@ async function buildApp(projectPath, destinationPath) {
     });
 }
 ```
+:::
+
+#### Starting a Server
+
+`@ui5/server` starts a development server for a project graph. It binds a port, serves the built resources, watches the sources, and rebuilds on demand.
+
+::: code-group
+```js [ESM]
+import {graphFromPackageDependencies} from "@ui5/project/graph";
+import {serve} from "@ui5/server";
+
+async function startServer(projectPath) {
+    const graph = await graphFromPackageDependencies({
+        cwd: projectPath
+    });
+    const {port, close} = await serve(graph, {
+        port: 8080,
+        changePortIfInUse: true
+    });
+    console.log(`Server started on port ${port}`);
+
+    // Later, to stop the server:
+    // await new Promise((resolve) => close(resolve));
+}
+```
+
+```js [CommonJS]
+async function startServer(projectPath) {
+    const {graphFromPackageDependencies} =
+        await import("@ui5/project/graph");
+    const {serve} = await import("@ui5/server");
+    const graph = await graphFromPackageDependencies({
+        cwd: projectPath
+    });
+    const {port, close} = await serve(graph, {
+        port: 8080,
+        changePortIfInUse: true
+    });
+    console.log(`Server started on port ${port}`);
+
+    // Later, to stop the server:
+    // await new Promise((resolve) => close(resolve));
+}
+```
+:::
+
+#### Embedding the Middleware
+
+`serveMiddleware` assembles the UI5 middleware as a single connect/Express handler, for mounting into an HTTP server you own instead of starting one. It does not bind a port or attach the Live Reload WebSocket server.
+
+Call `close` on teardown to release the server's source watcher and build-cache handle. A project graph can be served only once, so do not call both `serveMiddleware` and `serve` for the same graph.
+
+::: code-group
+```js [ESM]
+import express from "express";
+import {graphFromPackageDependencies} from "@ui5/project/graph";
+import {serveMiddleware} from "@ui5/server";
+
+async function mountUI5(projectPath) {
+    const graph = await graphFromPackageDependencies({
+        cwd: projectPath
+    });
+    const {middleware, close} = await serveMiddleware(graph);
+
+    const app = express();
+    app.use(middleware);
+    const listener = app.listen(8080);
+
+    // On teardown:
+    // listener.close();
+    // await close();
+}
+```
+
+```js [CommonJS]
+async function mountUI5(projectPath) {
+    const {default: express} = await import("express");
+    const {graphFromPackageDependencies} =
+        await import("@ui5/project/graph");
+    const {serveMiddleware} = await import("@ui5/server");
+    const graph = await graphFromPackageDependencies({
+        cwd: projectPath
+    });
+    const {middleware, close} = await serveMiddleware(graph);
+
+    const app = express();
+    app.use(middleware);
+    const listener = app.listen(8080);
+
+    // On teardown:
+    // listener.close();
+    // await close();
+}
+```
 :::

internal/documentation/docs/pages/Server.md

@@ -176,13 +176,19 @@ By default, build caches created by `ui5 build` and `ui5 serve` are **separate a
 
 ### Watch Mode Behavior
 
-Once started with `ui5 serve`, the server automatically monitors 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.
+Once started with `ui5 serve`, the server monitors your project sources throughout the session. When a request arrives, it checks for cached results first and only rebuilds the affected resources and tasks if no cache is available. Saving multiple files at once triggers a single rebuild, not one per file.
 
-- **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
+- **Monitored**: All files in your project's source directories (`src/`, `webapp/`, `test/`, etc.)
+- **Not monitored**: Custom task and middleware implementation code
+
+### Project Definition Changes
+
+The server also watches the project definition files: `ui5.yaml`, `package.json`, the workspace configuration, and any file passed via `--config` or `--dependency-definition`. When one of these changes, the server re-resolves the project graph and re-creates itself behind the same URL and port. Connected browsers stay connected and reload once the server is ready.
+
+This covers configuration changes (for example adding a framework library or changing the project type) as well as switching branches with `git checkout`. While the graph is being re-resolved, requests are held with a page that reloads automatically once the server is ready.
 
 ::: info
-Changes to configuration files or custom tasks require a server restart to take effect.
+Changes to custom task or middleware implementation code still require a server restart to take effect.
 :::
 
 ## SSL Certificates