more lang

guides/manual/1-overview.md

@@ -2,19 +2,56 @@
 
 WarpDrive is a suite of features built around orchestrated data-fetching.
 
-## Motivations
+At its most basic, it is "managed fetch". At its most advanced it is a powerful
+local-first or offline-first solution that dedupes and reactively updates requests
+across tabs.
 
-At its most basic, it is "managed fetch". At its most advanced it is a powerful local-first or offline-first solution that dedupes and reactively updates requests across tabs.
+Usage across various rendering frameworks will be similar. In fact, this is an
+explicit goal: WarpDrive enables developers to quickly port and re-use data
+patterns.
 
-> [!TIP]
-> When we want to show integration with a framework, this tutorial
-> uses [EmberJS](https://emberjs.com), a powerful modern web framework with an established multi-decade legacy.
+We see this as one of the keys to scalability. Providing a stable framework
+for how data is requested, cached, mutated, and mocked allows developers to
+focus more time on the product requirements that matter.
 
-Usage across various rendering frameworks will be similar. In fact, this is an explicit goal: WarpDrive enables developers to quickly port and re-use data patterns.
+This also means that a single WarpDrive configuration can power multiple web-apps
+using varying frameworks sharing a single domain: bridging the gap between MPA
+and SPA.
 
-We see this as one of the keys to scalability. Providing a stable framework for how data is requested, cached, mutated, and mocked allows developers to focus more time on the product requirements that matter.
+WarpDrive began in ~2006 as a suite of ORM-like data utilities in SproutCore that
+later evolved into EmberData. Beginning in ~2017 the team plotted a course towards
+a significant evolution of the library based on the lessons learned in the first
+eleven years.
 
-This also means that a single WarpDrive configuration can power multiple web-apps using varying frameworks sharing a single domain: bridging the gap between MPA and SPA.
+In ~2023 we lifted the veil on that work, shifting from a resource-centric library
+to a request-centric library and began accelerating towards our goal of becoming
+a universal library prepared for the demands of web applications over the coming
+decades.
+
+## Why WarpDrive?
+
+WarpDrive is the data framework for building ambitious applications.
+
+What do we mean by ambitious? WarpDrive is ideal for applications looking to
+be best-in-class: whether that's a small todo app, e-commerce, a
+social app, or an enterprise b2b software solution.
+
+That's because WarpDrive is designed to seamlessly handle the hardest parts
+of state management when building an app, helping you focus on creating the
+features and user experiences that drive value.
+
+Our value goes beyond our feature set. WarpDrive embraces the platform, making it
+quick to pickup the basics. Our patterns are portable and scalable, meaning that as
+your app, team and data needs evolve we'll be right there with you.
+
+Because we are universal and also not tied to any API Format or backend architecture,
+there's no lock-in. The data patterns you learn, the code you write is portable
+between frontend frameworks and backends and can help smooth the evolution of both.
+
+We're also not specific to a given frontend architecture. When serving on the same
+domain, you can dedupe and cache requests across multiple apps and tabs at once!
+This means we are as good for embedded content and MPAs as we are for SPAs.
+
+Our core philosophy is to deliver value that lasts decades and evolves with your app.
 
-Data fetching is managed by a `RequestManager`, which executes handlers you provide 
 

guides/manual/2-requests.md

@@ -10,14 +10,20 @@ Though the actual source and connection type do not matter, in a typical app req
 
 ### Fetch Example
 
+> [!TIP]
+> When we want to show integration with a framework, this tutorial
+> uses [EmberJS](https://emberjs.com), a powerful modern web framework with an established multi-decade legacy.
+
 <br>
 
 *Run This Example* → [Request | Fetch Example](https://warpdrive.nullvoxpopuli.com/manual/requests/fetch)
 
 <br>
 
-In order to make requests, first we create a request manager for our
-application, and we tell it to fulfill requests using the `Fetch` handler.
+Data fetching is managed by a `RequestManager`, which executes handlers you provide.
+
+In order to make requests, first we create a `RequestManager` for our
+application, and we tell it to fulfill requests using a `Fetch` handler.
 
 ```ts
 import RequestManager from '@ember-data/request';
@@ -90,7 +96,19 @@ flowchart LR
 
 ### Handlers
 
-Requests are fulfilled by handlers. A handler receives the RequestContext as well as a `next` function with which to pass along a request to the next handler if it so chooses.
+Requests are completed by handlers. Each handler may choose to fulfill the request, modify it,
+or pass it along unchanged to the next handler.
+
+A handler receives the request `context` as well as a `next` function with which to pass along
+a request if it so chooses.
+
+`next` returns a Future, which is a promise with a few additional capabilities. Futures resolve
+with the response from the next handler in the chain. This allows a handler to read or modify
+the response if it wants.
+
+> [!Important]
+> requests are immutable, to modify one the handler must create a new request, copying over or
+> cloning the parts it wants to leave unchanged.
 
 ```ts
 type NextFn<T> = (req: RequestInfo) => Future<T>;