Add before cache documentation

docs.json

@@ -509,6 +509,7 @@
                 "group": "Reference",
                 "pages": [
                   "scripting/limits",
+                  "scripting/before-cache",
                   "scripting/api-reference"
                 ]
               }
@@ -642,7 +643,7 @@
               {
                 "group": "Reference",
                 "pages": [
-                   "stream/video-specification",
+                  "stream/video-specification",
                   "stream/vimeo2bunny",
                   "stream/data-and-privacy",
                   "stream/api-reference"

scripting/before-cache.mdx

@@ -0,0 +1,85 @@
+---
+title: "Before cache execution"
+sidebarTitle: "Before cache execution"
+description: "Run your edge scripts before the cache layer to take control of
+every request, instead of only executing when the cache is missed."
+tag: Preview
+---
+
+By default, edge scripts run **after** the cache. Cached responses are served
+directly by the CDN without invoking your script, which keeps cached traffic as
+fast and efficient as possible.
+
+With before cache execution enabled, your script runs on **every request**,
+before the cache lookup. This gives you full control over the request flow at
+the cost of executing your script even for cached content.
+
+Post-cache execution remains the default. Enable before cache execution when
+you need per-request logic, such as authentication, tenant-aware routing, or
+custom caching rules.
+
+## Enable before cache execution
+
+Before cache execution is enabled at the Pull Zone level and applies to the
+script linked to that Pull Zone.
+
+Navigate to your Pull Zone, then go to **General** > **Origin** and enable
+**Run script before cache**.
+
+For standalone scripts, you can use the same Pull Zone toggle or enable it
+directly in the script settings.
+
+## Middleware scripts
+
+When before cache execution is enabled, middleware scripts gain access to two
+additional hooks that run on the client side of the cache:
+
+- **`onClientRequest`**: runs on every incoming request before the cache
+  lookup. Modify the request or short-circuit by returning a response
+  directly.
+- **`onClientResponse`**: runs just before the response is sent to the
+  client, including responses served from the cache.
+
+```ts
+import * as BunnySDK from "@bunny.net/edgescript-sdk@0.13.0-rc.0";
+
+BunnySDK.net.http
+  .servePullZone({ url: "https://your-origin.com" })
+  .onClientRequest((ctx) => {
+    // Runs before the cache lookup on every request
+    return Promise.resolve(ctx.request);
+  })
+  .onClientResponse((ctx) => {
+    // Runs before the response is sent to the client
+    return Promise.resolve(ctx.response);
+  });
+```
+
+See [Middleware scripts](/scripting/middleware/overview) for the full hook
+reference and workflow.
+
+## Standalone scripts
+
+Standalone scripts act as the origin for their Pull Zone, so by default they
+only execute when the cache is missed. With before cache execution enabled,
+your script handles **every request** before the cache lookup, and decides
+whether and how responses are cached.
+
+See [Standalone scripts](/scripting/standalone/overview) for details.
+
+## Workflow
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Script
+    participant Cache
+    participant Origin
+
+    Client->>Script: Request
+    Script->>Cache: Cache lookup
+    Cache->>Origin: On cache MISS
+    Origin-->>Cache: Response
+    Cache-->>Script: Response
+    Script-->>Client: Response
+```

scripting/middleware/overview.mdx

@@ -1,7 +1,11 @@
 ---
 title: "Middleware scripts"
 sidebarTitle: "Introduction"
-description: "Middleware scripts allow you to transform and modify HTTP requests and responses as they flow through the CDN. Manipulate requests before they reach your origin server and alter responses before they are sent back to the client."
+description: "Middleware scripts allow you to transform and modify HTTP requests
+and responses as they flow through the CDN. Manipulate requests before they
+reach your origin server or the cache and alter responses before they are sent 
+back to the client."
+tag: New
 ---
 
 Middleware scripts act as intermediaries within the CDN request workflow, allowing you to insert custom logic that modifies requests or responses as they pass through the CDN.
@@ -58,6 +62,60 @@ servePullZone(options: { url: string }): PullZoneHandler
 
 The `servePullZone` function returns a `PullZoneHandler` object with chainable middleware methods:
 
+### `onClientRequest`
+<Badge color="orange" icon="sparkles">Preview</Badge>
+
+<Info>
+If your PullZone is configured to execute script before cache, you'll have
+access to this function.
+</Info>
+
+Intercepts requests before they are sent to the cache. You can modify the request
+or short-circuit by returning a response directly.
+
+```ts
+onClientRequest(
+  middleware: (ctx: { request: Request }) => Promise<Response> | Response | Promise<Request> | Request | void
+): PullZoneHandler
+```
+
+| Property      | Type      | Description                 |
+| ------------- | --------- | --------------------------- |
+| `ctx.request` | `Request` | The incoming request object |
+
+**Return value:**
+
+- Return `Promise<Request>` to continue to the origin with the (modified) request
+- Return `Promise<Response>` to short-circuit and respond immediately without
+  hitting the cache
+
+### `onClientResponse` 
+<Badge color="orange" icon="sparkles">Preview</Badge>
+
+<Info>
+If your PullZone is configured to execute script before cache, you'll have
+access to this function.
+</Info>
+
+Intercepts requests before they are returned to the user even after you return a
+cached response.
+
+```ts
+onClientResponse(
+  middleware: (ctx: { request: Request; response: Response }) => Promise<Response> | Response
+): PullZoneHandler
+```
+
+| Property       | Type       | Description                         |
+| -------------- | ---------- | ----------------------------------- |
+| `ctx.request`  | `Request`  | The original request object         |
+| `ctx.response` | `Response` | The response from the origin server |
+
+**Return value:**
+
+- Return `Promise<Response>` or `Response` with the (modified) response to send
+to the client.
+
 ### `onOriginRequest`
 
 Intercepts requests before they are sent to the origin server. You can modify the request or short-circuit by returning a response directly.
@@ -96,15 +154,45 @@ onOriginResponse(
 
 - Return `Promise<Response>` with the (modified) response to send to the client
 
+## Enable Before Cache Scripts
+<Badge color="orange" icon="sparkles">Preview</Badge>
+
+To enable Middleware script to run before cache, you'll need to enable it at 
+your PullZone level. Navigate to your Pull Zone, then go to **General** >
+**Origin** and enable **Run script before cache**.
+
+<Info>
+Learn more about [before cache execution](/scripting/before-cache).
+</Info>
+
 ## Workflow
 
 When a client makes a request to a Pull Zone, the request passes through middleware at different stages:
 
-1. **`onOriginRequest`** - Called before the request is sent to the origin. Modify the request or return a response to short-circuit.
-2. **Origin fetch** - The request is sent to your origin server (skipped if short-circuited).
-3. **`onOriginResponse`** - Called after the origin responds. Modify the response before it's sent to the client and cached.
+<Info>
+If your PullZone is configured to execute script before cache, you'll run the
+`onClientRequest` and `onClientResponse` if those are registered.
+</Info>
 
-![](/images/docs/e5c6548c1d23722bbb1206f3a6bffe69d07db1541499995b13e3101b0011f91b-image.png)
+1. **`onClientRequest`** - Called before the request is sent to the cache. Modify the request or return a response to short-circuit.
+2. **`onOriginRequest`** - Called before the request is sent to the origin (so
+if the cache is giving a *MISS*). Modify the request or return a response to short-circuit.
+3. **Origin fetch** - The request is sent to your origin server.
+4. **`onOriginResponse`** - Called after the origin responds. Modify the response before it's sent to the client and cached.
+3. **`onClientResponse`** - Called just before a Response is sent to the client
+expect if you short circuit it at the `onClientRequest` layer.
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Cache
+    participant Origin
+
+    Client->>Cache: onClientRequest
+    Cache->>Origin: onOriginRequest
+    Origin-->>Cache: onOriginResponse
+    Cache-->>Client: onClientResponse
+```
 
 ## Example
 

scripting/standalone/overview.mdx

@@ -42,6 +42,20 @@ serve(handler: (request: Request) => Response | Promise<Response>)
 
 The handler function receives a standard [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object and must return a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) or `Promise<Response>`.
 
+## Before cache execution
+<Badge color="orange" icon="sparkles">Preview</Badge>
+
+Standalone scripts act as the origin for their Pull Zone, so by default they
+only execute when the cache is missed. If your Pull Zone is configured to
+execute scripts before cache, your script runs on **every request**, before
+the cache lookup.
+
+<Info>
+You can enable it in your Pull Zone under **General** > **Origin** >
+**Run script before cache**, or directly in the script settings. Learn more
+about [before cache execution](/scripting/before-cache).
+</Info>
+
 ## Example
 
 This example demonstrates A/B testing based on a custom header: