docs(en): realign guides to v0.15 context namespace API

- Consolidate response helpers into download and empty
- Document ctx.get, ctx.set, and ctx.send namespaces
- Document timeout 503 and template limit 400 statuses
- Drop ctx.state in favor of signed session and validated
- Move worker pool guide to recipes
- Remove wildcard wording from route patterns description
- Rename lifecycle events and add security event group
- Rename routesDir to routes.directory across config
- Rename WrapMware to Wrap.apply and Validator.read to ctx.get.validated

Author: NeaByteLab

docs/by-design/bearer-auth.md

@@ -22,24 +22,23 @@ Bearer is the opposite. The token format, the signature, and the trust source al
 
 A token guard is a small composition over parts that already ship:
 
-- **Read the header** - [`ctx.header('authorization')`](/core-concepts/context-object#request-data-access) returns the raw `Authorization` value.
+- **Read the header** - [`ctx.get.header('authorization')`](/core-concepts/context-object#ctx-get-header-key) returns the raw `Authorization` value.
 - **Run early** - [global middleware](/middleware/global) runs before route handlers and can stop a request by returning a `Response`.
 - **Reject cleanly** - [`ctx.handleError(401, ...)`](/core-concepts/context-object#error-handling) routes through [`router.catch()`](/error-handling/object-details) when one is set.
-- **Carry the result** - [`ctx.state`](/core-concepts/context-object#sharing-state) hands the decoded identity to the handler downstream.
+- **Carry the result** - [`ctx.set.session(...)`](/core-concepts/context-object#ctx-set-session-data) signs the decoded identity into a cookie the handler reads back, covered in [session middleware](/middleware/session).
 
 ## A Bearer Guard
 
-This middleware pulls the token out of the header, verifies it, and stores the result for later handlers. The `verifyToken` placeholder stands in for the scheme of choice, a JWT check, a JWKS lookup, or an introspection call.
+This middleware pulls the token out of the header, verifies it, and stores the result for later handlers. The `verifyToken` placeholder stands in for the scheme of choice, a JWT check, a JWKS lookup, or an introspection call. Storing the identity needs the [session middleware](/middleware/session) registered first.
 
 ```typescript twoslash
-import type { Context } from '@neabyte/deserve'
-import { Router } from '@neabyte/deserve'
+import { Router, type Context } from '@neabyte/deserve'
 
 const router = new Router()
 declare function verifyToken(token: string): Promise<{ userId: string } | null>
 // ---cut---
 router.use(async (ctx, next) => {
-  const header = ctx.header('authorization')
+  const header = ctx.get.header('authorization')
   const spaceIndex = header ? header.indexOf(' ') : -1
   const scheme = spaceIndex > 0 ? header!.slice(0, spaceIndex) : ''
 
@@ -56,47 +55,46 @@ router.use(async (ctx, next) => {
   }
 
   // Hand the identity to handlers
-  ctx.state.userId = claims.userId
+  await ctx.set.session({ userId: claims.userId })
   return await next()
 })
 
 await router.serve(8000)
 ```
 
-The handler then reads the identity straight from state, with no token parsing of its own.
+The handler then reads the identity straight from the session, with no token parsing of its own.
 
 ```typescript twoslash
 import type { Context } from '@neabyte/deserve'
 // ---cut---
 export function GET(ctx: Context): Response {
   // Read what the guard stored
-  const userId = ctx.state.userId
-  return ctx.send.json({ userId })
+  const session = ctx.get.session()
+  return ctx.send.json({ userId: session?.userId })
 }
 ```
 
 ## Routing Failures Through One Handler
 
-The guard above returns the `401` from inside the middleware. To send every auth failure through one place, wrap the middleware with [`WrapMware`](/middleware/global#wrapping-middleware-with-error-handling) and throw on rejection, then shape the reply with [`router.catch()`](/error-handling/object-details).
+The guard above returns the `401` from inside the middleware. To send every auth failure through one place, wrap the middleware with [`Wrap.apply`](/middleware/global#wrapping-middleware-with-error-handling) and throw on rejection, then shape the reply with [`router.catch()`](/error-handling/object-details).
 
 ```typescript twoslash
-import type { Context } from '@neabyte/deserve'
-import { Router, WrapMware } from '@neabyte/deserve'
+import { Router, Wrap, type Context } from '@neabyte/deserve'
 
 const router = new Router()
 declare function verifyToken(token: string): Promise<{ userId: string } | null>
 // ---cut---
 // Throws reach router.catch when wrapped
-const bearer = WrapMware('Bearer', async (ctx: Context, next) => {
-  const header = ctx.header('authorization')
+const bearer = Wrap.apply('Bearer', async (ctx: Context, next) => {
+  const header = ctx.get.header('authorization')
   if (!header?.toLowerCase().startsWith('bearer ')) {
     throw new Error('Missing Bearer token')
   }
   const claims = await verifyToken(header.slice(7).trim())
   if (!claims) {
     throw new Error('Invalid token')
   }
-  ctx.state.userId = claims.userId
+  await ctx.set.session({ userId: claims.userId })
   return await next()
 })
 
@@ -121,22 +119,21 @@ This is the same wrapping pattern [Basic Auth](/middleware/basic-auth) uses inte
 A token guard often belongs on an API prefix while public pages stay open. Path-specific middleware scopes the check to one prefix, the same form shown in [global middleware](/middleware/global#path-specific-middleware).
 
 ```typescript twoslash
-import type { Context } from '@neabyte/deserve'
-import { Router } from '@neabyte/deserve'
+import { Router, type Context } from '@neabyte/deserve'
 
 const router = new Router()
 declare function verifyToken(token: string): Promise<{ userId: string } | null>
 // ---cut---
 // Guard only the /api routes
 router.use('/api', async (ctx, next) => {
-  const header = ctx.header('authorization')
+  const header = ctx.get.header('authorization')
   const claims = header?.toLowerCase().startsWith('bearer ')
     ? await verifyToken(header.slice(7).trim())
     : null
   if (!claims) {
     return await ctx.handleError(401, new Error('Invalid token'))
   }
-  ctx.state.userId = claims.userId
+  await ctx.set.session({ userId: claims.userId })
   return await next()
 })
 ```

docs/by-design/cache.md

@@ -29,7 +29,7 @@ import type { Context } from '@neabyte/deserve'
 const cache = new Map<string, unknown>()
 
 export async function GET(ctx: Context): Promise<Response> {
-  const key = ctx.pathname
+  const key = ctx.get.pathname()
 
   // Serve the cached value when present
   const hit = cache.get(key)
@@ -40,7 +40,7 @@ export async function GET(ctx: Context): Promise<Response> {
     })
   }
 
-  // Build it once, then store for next time
+  // Build once, then store for reuse
   const data = await buildExpensiveData()
   cache.set(key, data)
   return ctx.send.json({
@@ -64,10 +64,10 @@ const ttlMs = 30_000
 const cache = new Map<string, { value: unknown, expiresAt: number }>()
 
 export function GET(ctx: Context): Response {
-  const key = ctx.pathname
+  const key = ctx.get.pathname()
   const entry = cache.get(key)
 
-  // Fresh entry wins, expired one is dropped
+  // Fresh entry wins, expired one drops
   if (entry && Date.now() < entry.expiresAt) {
     return ctx.send.json({
       source: 'cache',
@@ -96,4 +96,4 @@ Two cases call for more than a process-local map. A cache that must survive a re
 
 ## Per-Request Sharing
 
-Caching across requests is one need, passing a value along a single request is another. A value computed in middleware and read by the handler does not belong in a cache at all, it belongs in [`ctx.state`](/core-concepts/context-object#sharing-state), which lives for exactly one request and is gone when the response is sent.
+Caching across requests is one need, passing a value along a single request is another. A value computed in middleware and read by the handler does not belong in a cache at all. For per-user identity the signed [session](/middleware/session) carries it through `ctx.set.session()` and `ctx.get.session()`, and for validated input the [validate middleware](/middleware/validation/overview) hands it on through `ctx.get.validated()`. Anything else the handler re-derives from the request it already holds.

docs/by-design/compress.md

@@ -56,15 +56,15 @@ To keep one response uncompressed, set a header the runtime treats as a stop sig
 import type { Context } from '@neabyte/deserve'
 // ---cut---
 export function GET(ctx: Context): Response {
-  // Block any layer from rewriting the body
-  ctx.setHeader('Cache-Control', 'no-transform')
+  // Block any layer from rewriting body
+  ctx.set.header('Cache-Control', 'no-transform')
   return ctx.send.json({
     message: 'sent verbatim'
   })
 }
 ```
 
-Setting headers through [`ctx.setHeader`](/core-concepts/context-object#response-headers) is the same path used everywhere else, so this opt-out reads like any other header.
+Setting headers through [`ctx.set.header`](/core-concepts/context-object#ctx-set-header-key-value) is the same path used everywhere else, so this opt-out reads like any other header.
 
 ## Already-Encoded Bodies
 

docs/by-design/https-redirect.md

@@ -38,21 +38,21 @@ await router.serve(8000)
 
 ## Reading the Real Scheme
 
-When the app does need to know whether the client used HTTPS, the answer rides in a forwarded header the proxy sets, not in the local connection. A trusted proxy adds [`X-Forwarded-Proto`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Proto), read through [`ctx.header`](/core-concepts/context-object#request-data-access).
+When the app does need to know whether the client used HTTPS, the answer rides in a forwarded header the proxy sets, not in the local connection. A trusted proxy adds [`X-Forwarded-Proto`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Proto), read through [`ctx.get.header`](/core-concepts/context-object#ctx-get-header-key).
 
 ```typescript twoslash
 import type { Context } from '@neabyte/deserve'
 // ---cut---
 export function GET(ctx: Context): Response {
   // Scheme the client actually used
-  const proto = ctx.header('x-forwarded-proto') ?? 'http'
+  const proto = ctx.get.header('x-forwarded-proto') ?? 'http'
   return ctx.send.json({
     secure: proto === 'https'
   })
 }
 ```
 
-Trust this header only behind a proxy configured through [`trustProxy`](/getting-started/server-configuration#client-ip-resolution), the same trust boundary [`ctx.ip`](/by-design/request-id#the-ip-is-the-source-of-truth) relies on. An untrusted client can set any header, so the value means nothing without that boundary.
+Trust this header only behind a proxy configured through [`trustProxy`](/getting-started/server-configuration#client-ip-resolution), the same trust boundary [`ctx.get.ip()`](/core-concepts/context-object#ctx-get-ip-options) relies on. An untrusted client can set any header, so the value means nothing without that boundary.
 
 ## Serving HTTPS Directly
 

docs/by-design/locale-redirect.md

@@ -14,14 +14,14 @@ Language choice is a product decision, not a transport rule. Which locales exist
 
 ## Reading the Preference
 
-The browser sends its language list in the [`Accept-Language`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language) header, read through [`ctx.header`](/core-concepts/context-object#request-data-access). A small match against the locales the app supports gives the target, then [`ctx.send.redirect`](/response/redirect) sends the visitor there.
+The browser sends its language list in the [`Accept-Language`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language) header, read through [`ctx.get.header`](/core-concepts/context-object#ctx-get-header-key). A small match against the locales the app supports gives the target, then [`ctx.send.redirect`](/response/redirect) sends the visitor there.
 
 ```typescript twoslash
 import type { Context } from '@neabyte/deserve'
 // ---cut---
 export function GET(ctx: Context): Response {
   // Read the browser language hint
-  const header = ctx.header('accept-language') ?? ''
+  const header = ctx.get.header('accept-language') ?? ''
   const supported = ['en', 'id']
 
   // Match a supported locale or default
@@ -37,7 +37,7 @@ A 302 keeps the redirect temporary, so a later visit can still be matched again.
 
 ## Sharing the Choice With Later Routes
 
-When several routes need the resolved locale, middleware can resolve it once and store it in [`ctx.state`](/core-concepts/context-object#sharing-state) instead of redirecting, so each handler reads the same value.
+When several routes need the resolved locale, middleware can resolve it once and store it in the signed [session](/middleware/session) instead of redirecting, so each handler reads the same value through `ctx.get.session()`.
 
 ```typescript twoslash
 import { Router } from '@neabyte/deserve'
@@ -46,15 +46,16 @@ const router = new Router()
 // ---cut---
 router.use(async (ctx, next) => {
   // Resolve locale once for the request
-  const header = ctx.header('accept-language') ?? ''
+  const header = ctx.get.header('accept-language') ?? ''
   const preferred = header.split(',')[0]?.slice(0, 2) ?? 'en'
 
   // Share it with the route handlers
-  ctx.state.locale = ['en', 'id'].includes(preferred) ? preferred : 'en'
+  const locale = ['en', 'id'].includes(preferred) ? preferred : 'en'
+  await ctx.set.session({ locale })
   return await next()
 })
 
 await router.serve(8000)
 ```
 
-The redirect form sends the visitor to a localized URL, while the state form keeps one URL and passes the locale inward. Both stay in plain route files, so the rule is where the language matters and nowhere else.
+The redirect form sends the visitor to a localized URL, while the session form keeps one URL and passes the locale inward. Both stay in plain route files, so the rule is where the language matters and nowhere else.

docs/by-design/method-override.md

@@ -22,15 +22,15 @@ Deserve also routes on the real `req.method`, which a handler cannot rewrite mid
 
 ## Every Method Is a Route
 
-A route file exports one function per method, and the name is the method. There is no table to register and no verb to translate. A file like `items/[id].ts` reads its `id` from the path through [`ctx.param`](/core-concepts/context-object#request-data-access).
+A route file exports one function per method, and the name is the method. There is no table to register and no verb to translate. A file like `items/[id].ts` reads its `id` from the path through [`ctx.get.param`](/core-concepts/context-object#ctx-get-param-key).
 
 ```typescript twoslash
 import type { Context } from '@neabyte/deserve'
 // ---cut---
 // Read one item by id
 export function GET(ctx: Context): Response {
   return ctx.send.json({
-    id: ctx.param('id')
+    id: ctx.get.param('id')
   })
 }
 
@@ -67,7 +67,7 @@ await fetch(
 )
 ```
 
-Building stateless or stateful is the same move, just drop the files. A stateless REST endpoint is a handler that reads the request and replies, while a stateful flow adds the [session middleware](/middleware/session) and reads per-user data from [`ctx.state`](/core-concepts/context-object#sharing-state). The method stays real either way, with nothing to disguise on the way in.
+Building stateless or stateful is the same move, just drop the files. A stateless REST endpoint is a handler that reads the request and replies, while a stateful flow adds the [session middleware](/middleware/session) and reads per-user data through `ctx.get.session()`. The method stays real either way, with nothing to disguise on the way in.
 
 A full REST or RESTful API falls out of this with no extra wiring. The verbs already line up with the actions, `GET` to read, `POST` to create, `PUT` and `PATCH` to update, `DELETE` to remove, so a resource is just a route file with those handlers. The behavior reads the same across every endpoint, which is what makes the whole API feel seamless.