docs: clarify response validation boundaries

Avoid implying Rouzer is a poor fit for any runtime response validation. The docs now distinguish server-boundary response validation from the intended model: response markers are type contracts, with runtime integrity checks placed where data enters server or client code.

Author: aleclarson

README.md

@@ -24,15 +24,17 @@ Use Rouzer if:
 
 - your server and client can import the same TypeScript route tree
 - you want Zod request validation on both sides of an HTTP boundary
+- response data is validated at data/client boundaries, not by re-checking every
+  handler return
 - a Hattip-compatible handler fits your server runtime
 - you prefer named resource/action functions over a generated client class
 
 Consider something else if:
 
 - you need OpenAPI-first workflows, schema files, or generated clients for other
   languages
-- you need runtime response-body validation; `$type<T>()`, `$error<T>()`, and
-  `ndjson.$type<T>()` are compile-time only
+- you want the router to validate every response body at the server boundary;
+  `$type<T>()`, `$error<T>()`, and `ndjson.$type<T>()` are type contracts
 - you want a framework that owns controllers, data loading, rendering, and
   deployment adapters
 - you cannot use ESM or Zod v4+

docs/context.md

@@ -17,9 +17,12 @@ Use Rouzer when:
 - generated clients should stay close to route definitions instead of being
   produced by a separate OpenAPI build step
 
-Rouzer is not a response validation library, an OpenAPI generator, or a complete
+Rouzer is not a server response validator, an OpenAPI generator, or a complete
 server framework. It focuses on typed route contracts, request validation,
-routing, and a small client wrapper.
+routing, and a small client wrapper. Response markers are type contracts; if
+response data comes from an untrusted source, validate it where it enters your
+server or client code instead of relying on the router to re-check handler
+returns.
 
 ## Core abstractions
 
@@ -96,7 +99,9 @@ and server support.
 
 `response: $type<T>()` is a TypeScript-only marker for JSON success payloads. It
 tells handlers and client action functions what payload type to expect, but
-Rouzer does not validate response bodies at runtime.
+Rouzer does not validate handler return values at the server boundary. Validate
+response data where it enters your system, such as an external API client,
+database decoder, or UI/client boundary, when runtime integrity is required.
 
 Use a status-keyed response map when callers need to branch on declared statuses:
 
@@ -496,8 +501,9 @@ await client.profiles.update({
 
 ## Constraints and gotchas
 
-- `$type<T>()`, `$error<T>()`, and `ndjson.$type<T>()` are compile-time only and
-  do not validate response payloads or streamed items.
+- `$type<T>()`, `$error<T>()`, and `ndjson.$type<T>()` are compile-time-only type
+  contracts. Rouzer does not re-validate handler return values at the server
+  boundary.
 - NDJSON support is for response streams; request bodies still use the existing
   JSON body schema path.
 - Declared `$error<T>()` responses are JSON responses. Use a custom `Response`

src/type.ts

@@ -3,10 +3,12 @@ import type { Unchecked, UncheckedError } from './common.js'
 /**
  * Create a compile-time-only marker for an action's JSON response payload type.
  *
- * @remarks `$type<T>()` does not perform runtime validation. It lets Rouzer type
- * server handler return values and client action functions for HTTP actions
- * whose responses are expected to be JSON. Use it directly as `response` for one
- * JSON success shape, or as a success entry in a status-keyed response map.
+ * @remarks `$type<T>()` does not validate handler return values at the server
+ * boundary. It lets Rouzer type server handler return values and client action
+ * functions for HTTP actions whose responses are expected to be JSON. Use it
+ * directly as `response` for one JSON success shape, or as a success entry in a
+ * status-keyed response map. Validate response data where it enters your server
+ * or client code when runtime integrity is required.
  *
  * @example
  * ```ts
@@ -28,9 +30,10 @@ $type.symbol = Symbol()
  * Create a compile-time-only marker for a declared error response type.
  *
  * @remarks `$error<T>()` marks a non-success response branch in a status-keyed
- * response map. On the server, handlers use `ctx.error(status, body)` to return
- * declared errors. On the client, declared error responses resolve as
- * `[error, null, status]` tuple entries instead of rejecting the promise.
+ * response map. It is a type contract, not a runtime validator. On the server,
+ * handlers use `ctx.error(status, body)` to return declared errors. On the
+ * client, declared error responses resolve as `[error, null, status]` tuple
+ * entries instead of rejecting the promise.
  *
  * @example
  * ```ts