Add missing V4 documentation

Author: maartenba

astro/src/content/docs/bff/fundamentals/apis/local.mdx

@@ -215,4 +215,32 @@ public class SampleApiController : ControllerBase
 
 :::note
 It's also possible to disable anti-forgery protection using _BffOptions.DisableAntiForgeryCheck()_
-:::
+:::
+
+### Skipping Response Handling
+
+By default, when BFF pre/post-processing is enabled on an endpoint (via `.AsBffApiEndpoint()`), the BFF framework
+intercepts authentication challenge and forbid responses. Instead of returning a 302 redirect to the identity provider
+(which is not useful for API calls), it converts them to API-friendly status codes:
+
+- **Challenge** (unauthenticated) → returns **401** (instead of 302 redirect)
+- **Forbid** (unauthorized) → returns **403** (instead of 302 redirect)
+
+If you want to opt out of this behavior and let the default authentication response handling occur (e.g., if your
+endpoint needs to trigger a redirect), you can use the `SkipResponseHandling()` extension method:
+
+```csharp
+app.MapGet("/my-endpoint", context => { /* ... */ })
+    .AsBffApiEndpoint()
+    .SkipResponseHandling();
+```
+
+For MVC controllers, you can use the `[BffApiSkipResponseHandling]` attribute:
+
+```csharp
+[Route("my-endpoint")]
+[BffApi]
+[BffApiSkipResponseHandling]
+public class MyController : ControllerBase
+{ /* ... */ }
+```

astro/src/content/docs/bff/fundamentals/multi-frontend/index.mdx

@@ -184,6 +184,34 @@ var frontend = new BffFrontend(BffFrontendName.Parse("frontend1"))
 When you do this, the BFF automatically wires up a catch-all route that serves the `index.html` for that specific frontend. 
 See [Serve the index page from the BFF host](/bff/architecture/ui-hosting.md#serve-the-index-page-from-the-bff-host) for more information. 
 
+#### Transforming the `index.html`
+
+If you need to modify the `index.html` before it is served to the client (for example, to inject frontend-specific
+configuration or environment variables), you can implement the `IIndexHtmlTransformer` interface:
+
+```csharp
+public class MyIndexHtmlTransformer : IIndexHtmlTransformer
+{
+    public Task<string?> Transform(string indexHtml, BffFrontend frontend, CancellationToken ct = default)
+    {
+        // Inject a frontend-specific config script tag
+        var transformed = indexHtml.Replace(
+            "</head>",
+            $"<script>window.__CONFIG__ = {{ frontend: '{frontend.Name}' }};</script></head>");
+        return Task.FromResult<string?>(transformed);
+    }
+}
+```
+
+Register the transformer in the service collection:
+
+```csharp
+services.AddSingleton<IIndexHtmlTransformer, MyIndexHtmlTransformer>();
+```
+
+The transformer is called after the `index.html` is fetched from the CDN and before it is cached. The cache duration
+is controlled by the [`IndexHtmlDefaultCacheDuration`](/bff/fundamentals/options.md#cdn--static-assets) option. 
+
 ### Proxying All Static Assets 
 
 When developing a Single-Page Application (SPA), it's very common to use a development webserver such as Vite. While Vite can publish static assets with a base URL, this doesn't work well during development.

astro/src/content/docs/bff/fundamentals/options.md

@@ -48,7 +48,41 @@ builder.Services.AddBff(options =>
 
 * ***AutomaticallyRegisterBffMiddleware*** (added in 4.0)
 
-    When applying BFF V4 multiple frontends, a lot of middlewares get automatically added to the pipeline. For example, the frontend selection middleware, the authentication handlers, etc. If you don't want this automatic behavior, then you can turn it off and register these middlewares manually. 
+    When using BFF V4 with multiple frontends, several middlewares are automatically added to the pipeline (frontend
+    selection, path mapping, OpenID Connect callbacks, management endpoints, and static file proxying). If you need
+    full control over the middleware pipeline, set this to `false` and register the middleware manually:
+
+    ```csharp
+    builder.Services.AddBff(options =>
+    {
+        options.AutomaticallyRegisterBffMiddleware = false;
+    });
+    ```
+
+    When disabled, you must call `UseBffPreProcessing()` early in the pipeline (before authentication) and
+    `UseBffPostProcessing()` at the end:
+
+    ```csharp
+    app.UseForwardedHeaders();
+    app.UseBffPreProcessing();  // Frontend selection, path mapping, OpenID callbacks
+
+    app.UseAuthentication();
+    app.UseRouting();
+    app.UseBff();               // Anti-forgery checks
+    app.UseAuthorization();
+
+    // map your endpoints here...
+
+    app.UseBffPostProcessing();  // Management endpoints, remote API handling, static file proxying
+    ```
+
+    You can also use the individual middleware methods for even more granular control:
+
+    * `UseBffFrontendSelection()` — Selects the current frontend based on host/path matching
+    * `UseBffPathMapping()` — Adjusts `PathBase` and `Path` for the selected frontend
+    * `UseBffOpenIdCallbacks()` — Handles OpenID Connect callback requests
+    * `UseBffAntiForgery()` — Validates anti-forgery headers (same as `UseBff()`)
+    * `UseBffStaticFileProxying()` — Proxies static file requests to CDN or development server
 
 
 * ***StaticAssetsClientName***
@@ -151,6 +185,21 @@ builder.Services.AddBff(options =>
 * ***DisableAntiForgeryCheck*** (added in V4)
     A delegate that determines if the anti-forgery check should be disabled for a given request. The default is not to disable anti-forgery checks.
 
+## CDN / Static Assets
+
+* ***IndexHtmlDefaultCacheDuration*** (added in V4)
+
+    If you use CDN Index HTML proxying (via `BffFrontend.CdnIndexHtmlUrl`), this controls how long the fetched `index.html` is cached. Defaults to *5 minutes*.
+
+## Diagnostics
+
+* ***Diagnostics*** (added in V4)
+
+    Options that control the way that diagnostic data is logged. This is a nested options object with the following properties:
+
+    * ***LogFrequency*** — Frequency at which diagnostic summaries are logged. Defaults to *1 hour*.
+    * ***ChunkSize*** — Max size of diagnostic data log message chunks in bytes. Defaults to *8160 bytes* (8 KB minus 32 bytes for log message formatting overhead).
+
 
 # BFF Blazor Server Options
 

astro/src/content/docs/bff/fundamentals/session/management/user.md

@@ -95,7 +95,7 @@ To use the endpoint, make an HTTP GET request to it from your frontend javascrip
 could use the fetch API to make requests to the user endpoint like this:
 
 ```js title="session.js"
-var req = new Request("/user", {
+var req = new Request("/bff/user", {
     headers: new Headers({
         "X-CSRF": "1",
     }),
@@ -135,7 +135,7 @@ activity. To prevent the call to the user endpoint from sliding the cookie, add
 request.
 
 ```js title="site.js"
-var req = new Request("/user?slide=false", {
+var req = new Request("/bff/user?slide=false", {
     headers: new Headers({
         "X-CSRF": "1",
     }),

astro/src/content/docs/bff/getting-started/blazor.mdx

@@ -38,7 +38,7 @@ To configure the server, the first step is to add the BFF Blazor package.
 
 ```shell
 cd BlazorBffApp
-dotnet add package Duende.BFF.Blazor --version 3.0.0
+dotnet add package Duende.BFF.Blazor
 ```
 
 Then you need to configure the application to use the BFF Blazor application. Add this to your services:
@@ -171,7 +171,7 @@ To add the BFF to the client project, add the following:
 ```shell
 cd ..
 cd BlazorBffApp.Client
-dotnet add package Duende.BFF.Blazor.Client --version 3.0.0
+dotnet add package Duende.BFF.Blazor.Client
 ```
 
 Then add the following to your program.cs: