diff --git a/README.md b/README.md
index e71b6bc..455af49 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,5 @@
 # Netacea Cloudflare Worker Template
+
 ![Netacea Header](https://assets.ntcacdn.net/header.jpg)
 [![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)
 
@@ -32,12 +33,22 @@ Here you can find several parameters which need to be properly configured:
   - `netaceaCaptchaCookieName` - name of the Netacea captcha cookie. Name should set so as not to conflict with existing cookies on site.
   - `timeout` (optional) - the number of milliseconds to wait for a response from the Mitigation API before proceeding to the origin website. Default 3000ms.
 
+## ⬆️ Upgrading
+
+If you're upgrading from a previous version of the Netacea Cloudflare Worker Template,
+most of the time you should be able to upgrade by running `npm install --save @netacea/cloudflare@latest`.
+
+However, if you are upgrading from v5 to v6, then please see the
+[v5 to v6 upgrade guide.](./docs/upgrading_v5_to_v6.md)
+
 ## 💻 Development
+
 If you need to extend or enhance the functionality of the Cloudflare Worker, the documentation can be found [here](https://developers.cloudflare.com/workers/).
 Code extensions should be made in `./src/handler.ts`
 Please ensure that `worker.run(event, originRequest)` and `event.waitUntil(worker.ingest(event.request, response))` are called.
 
 ## ✔ Testing
+
 - `npm run test` - This will run a set of simple method tests against the worker (see `./tests/handler.test.ts`)
 - `npm run dev` - alias for `wrangler dev` - [documentation](https://developers.cloudflare.com/workers/wrangler/commands/#dev).
 - `npm run dev:local` - alias for `wrangler dev --local` - live preview of your code in a cloudflare sandbox - accessible from only your machine.
@@ -49,4 +60,5 @@ You can do this yourself by running `npm run build`, or use `npm run deploy`
 to build with webpack and publish to your Cloudflare distribution in one command.
 
 ## ❗ Issues
+
 If you run into issues with this specific project, please feel free to file an issue [here](https://github.com/Netacea/cloudflare-worker-template-typescript/issues). If the problem is with Wrangler, please file an issue [here](https://github.com/cloudflare/workers-sdk/tree/main/packages/wrangler).
diff --git a/docs/upgrading_v5_to_v6.md b/docs/upgrading_v5_to_v6.md
new file mode 100644
index 0000000..40d5f30
--- /dev/null
+++ b/docs/upgrading_v5_to_v6.md
@@ -0,0 +1,86 @@
+# ⬆ Netacea Cloudflare v5 to v6 Upgrade Guide
+
+This template has been updated to support the **v6** release of `@netacea/cloudflare`.
+This version introduces changes to the interface,
+requiring updates to how the module is integrated within the cloudflare handler.
+
+This guide walks you through the required changes and best practices when using v6.
+
+You can install v6 using `npm install --save @netacea/cloudflare@6`
+
+## 📦 What's New in v6?
+
+The `run` method now returns a result object with a `response` property, rather than returning a `Response` directly.
+This change allows for greater extensibility in the result metadata.
+
+### Old Usage (v5)
+
+```ts
+const response = await worker.run(event, originRequest)
+event.waitUntil(worker.ingest(event.request, response))
+return response
+```
+
+### New Usage (v6)
+
+```ts
+const result = await worker.run(event, originRequest)
+event.waitUntil(worker.ingest(event.request, result))
+return result.response
+```
+
+---
+
+## 🔧 Code Changes
+
+### Updated Handler
+
+Once updated, your handler should look something like:
+
+```ts
+import { Cloudflare } from '@netacea/cloudflare'
+
+const worker = new Cloudflare(NetaceaConfig)
+
+export async function handleRequestWithNetacea(event: FetchEvent): Promise<Response> {
+  const result = await worker.run(event, originRequest)
+  event.waitUntil(worker.ingest(event.request, result))
+  return result.response
+}
+
+async function originRequest(request: Request): Promise<Response> {
+  // Your origin logic here
+}
+```
+
+### Updated Tests
+
+The `run` method must now return an object with a `response` property in your mocks:
+
+```ts
+const { handleRequestWithNetacea } = proxyquire('../src/handler', {
+  '@netacea/cloudflare': function () {
+    return {
+      run: () => ({
+        response: new Response()
+      }),
+      ingest: () => {
+        // no-op
+      }
+    }
+  }
+})
+```
+
+Also, ensure your test requests include a fully qualified URL
+(e.g., `https://example.com`) to avoid errors when constructing `Request` objects.
+
+---
+
+## ✅ Summary of Required Changes
+
+| Area        | Change                                           |
+|-------------|--------------------------------------------------|
+| `run()` usage | Use `result.response` instead of `response`     |
+| `ingest()`    | Pass the full `result` to `ingest()`            |
+| Tests       | Update mocks to return `{ response: Response }` |