@rsc-kit/mcp 0.18.1 → 0.20.0

package/guides/deployment.md

@@ -42,6 +42,21 @@ CMD ["bun", ".output/server/index.mjs"]
 The second stage carries `.output` and nothing else. On the docs application
 that is 1.0 MB against 104 MB of `node_modules`.
 
+<Aside type="tip" title="What a port measured">
+  A production app ported from Next, same pages, same backend, the Bun binary
+  image beside the Next one it replaced:
+
+  | | Next | rsc-kit |
+  | --- | --- | --- |
+  | docker image | 104.56 MiB | 50.12 MiB |
+  | docker build | 5 m 13 s | 2 m 45 s |
+  | Lighthouse | — | 99 mobile, 100 desktop |
+
+  Nothing was tuned for the numbers. The image is smaller because the bundle
+  carries no `node_modules`; the build is faster because there is one build,
+  not a build and a trace.
+</Aside>
+
 ## Or a platform, without a Dockerfile
 
 Change the preset and Nitro produces what that platform expects — a Worker and
@@ -124,6 +139,16 @@ they are covered. See [serving shells from a CDN](/guides/edge-caching).
 
 Cached responses carry a build version, so a deploy invalidates them.
 
+**Build, then start — never build under a running server.** The server loads
+its rsc and ssr services lazily, on the first request that needs each, and
+a `vite build` that is rewriting `.output/` at that moment hands it a file
+that is half-written or briefly missing. The runtime caches that failed
+import — Bun does, and so does Node's ESM loader — so the route answers 500
+with an `ENOENT` for a file that now exists, and keeps doing so until the
+process restarts. In development use `vite` (the dev server), which owns its
+own rebuilds; in production build into a fresh directory or stop the server
+first, and start it against a finished `.output/`.
+
 Ship `.output/` from the same commit as the code that serves it. A server
 running one build against another's frozen pages is the one combination nothing
 checks for you.

package/guides/emails.md

@@ -87,4 +87,16 @@ src/lib/nodemailer.ts. Put the rendering — the template and the call — in a
 module that starts with "use ssr" …
 ```
 
-A build prints the same once, as a warning, naming the file.
+A build prints the same once, as a warning, naming the file — and the
+build still succeeds, because the refusal is the call's, not the import's:
+every export of the stub throws it when called, so a server does not fail to
+boot over an action nobody has run yet.
+
+A dependency whose imports the build never looks inside — `@react-email/render`
+imported from an action, say — is read once for the import and warned about
+the same way, naming the app file and the package:
+
+```
+src/actions/send-otp.ts imports @react-email/render, which imports
+react-dom/server, and that cannot run where server components render …
+```

package/guides/feature-flags.md

@@ -0,0 +1,63 @@
+# Feature flags
+
+> Vercel's Flags SDK runs unchanged — flags/next, without Next.
+
+Nothing to install from here. The [Flags SDK](https://flags-sdk.dev) is
+framework-agnostic at its core, and its Next integration — `flags/next`,
+the one with `flag()`, `dedupe()` and the adapters — needs one thing from
+Next: `next/headers`, for `headers()` and `cookies()`. Those exist here
+under the same names and with the same shapes, one object per request,
+which is what the SDK's per-request dedupe keys on. The build answers
+`next/headers` with them, so the SDK runs as written:
+
+```sh
+bun add flags
+```
+
+```ts title="src/flags.ts"
+import { flag, dedupe } from 'flags/next'
+
+const visitor = dedupe(async ({ cookies, headers }) => ({
+  id: cookies.get('visitor')?.value ?? 'anonymous',
+  country: headers.get('x-vercel-ip-country') ?? headers.get('cf-ipcountry') ?? '',
+}))
+
+export const showBanner = flag<boolean, { id: string; country: string }>({
+  key: 'show-banner',
+  identify: visitor,
+  decide: ({ entities }) => entities?.country === 'GB',
+})
+```
+
+```tsx title="src/app/page.tsx"
+import { showBanner } from '../flags'
+
+export default async function Home() {
+  const banner = await showBanner()
+
+  return banner ? <Banner /> : null
+}
+```
+
+A flag reads the request, so the page that awaits one renders per visitor —
+the build says `headers() in run, cookies() in run stream per request` and
+stores the rest as a shell, given a `<Suspense>` or a `loading.tsx` above
+the read. That is the same line any `headers()` call earns; see
+[Static generation](/guides/static-generation). An adapter — Statsig,
+LaunchDarkly, Vercel's own — is the SDK's, configured the way its docs say.
+
+The discovery endpoint is a route handler in the shape a `route.ts` already
+has:
+
+```ts title="src/app/.well-known/vercel/flags/route.ts"
+import { createFlagsDiscoveryEndpoint, getProviderData } from 'flags/next'
+import * as flags from '../../../../flags'
+
+export const GET = createFlagsDiscoveryEndpoint(async () => getProviderData(flags))
+export const openapi = false
+```
+
+What does not carry over is `precompute()`: it is built on a Next
+middleware rewriting the url to a permutation, which is Next's routing.
+Read the flag in the page instead; a flag read under a boundary costs one
+streamed hole, not the page.

package/guides/fonts.md

@@ -110,6 +110,31 @@ export default function RootLayout({ children }) {
 the one file the first paint needs, usually the Latin regular; preloading all
 of them defeats the subsetting.
 
+## A font never blocks the page
+
+Text paints before the web font arrives, always. That is not a tuning
+choice; it is the rule everything below serves, and a font can break it in
+three ways, each of which the setup above has already closed:
+
+- **A stylesheet from another origin.** `<link href="https://fonts.googleapis.com/…">`
+  is render-blocking CSS from a host the browser has not connected to: a DNS
+  lookup, a TLS handshake and a round trip before the first paint, on every
+  cold load. Self-hosting through Fontsource keeps the `@font-face` rules in
+  your own stylesheet, which is inlined into the document.
+- **`font-display: block`, or none at all.** Without a `font-display`, the
+  browser is free to hide text for up to three seconds while it waits — the
+  invisible-text flash. Every rule the setup writes says `swap` (paint the
+  fallback now, swap when the font lands) or `optional` (paint once, in
+  whichever is ready). Never `block`, and never leave it unset in a rule you
+  own.
+- **Preloading everything.** A `<link rel="preload">` per file puts every
+  weight and subset ahead of the page in the network queue. Preload the one
+  file the first paint needs; the rest arrive with the stylesheet.
+
+A font that is slow — a cold cache, a throttled connection — then costs a
+swap or a fallback, never a blank page. The section below is how to make
+that swap invisible.
+
 ## Getting to 100 on a phone
 
 Fontsource's stylesheet is the right default and the wrong last mile. It

package/guides/forms.md

@@ -7,6 +7,21 @@ that handles the state for you, and a hook for when you want to hold it
 yourself. Both cover validation errors, pending state, optimistic updates and
 GET-form navigation.
 
+## The rule: uncontrolled, unless one field needs otherwise
+
+A form here is **uncontrolled by default**. Inputs keep their own value in
+the DOM, an initial value is React's `defaultValue`, and the action reads
+`FormData` on submit. No `useState` per field, no `value`/`onChange` pair,
+no re-render of the whole form on every keystroke — and after a refused
+submit the values are still there, because nothing re-rendered the inputs.
+
+Reach for a controlled field only where the UI has to react *as* the user
+types — a character count, a live preview, a dependent select — and bind
+that one field with `useField` (below), which scopes the re-render to it.
+Coming from react-hook-form this is the same default; coming from TanStack
+Form or from `useState`-per-input it is the opposite, and the difference is
+most of why these forms stay fast.
+
 ## The `<Form>` component
 
 The simplest way to handle forms. Works without any hooks — just pass a server action and use the render-prop for pending state and errors.
@@ -275,6 +290,54 @@ genuinely reloads. Then the server renders the page again, and putting the
 values back is the server's job — return them from the action and render them
 as `defaultValue`.
 
+### The schema is written for the shape it wants
+
+Every value in a `FormData` is a string or a file, and a control that is off
+is not there at all — a fact that used to leak into every schema as
+`z.coerce.number()` and a per-checkbox `.transform()`. It does not any more.
+The form is read *the way the schema means it*, on both sides:
+
+```ts
+const settings = z.object({
+  notify: z.boolean(),                 // unchecked posts nothing → false; "on" → true
+  limit: z.number().int().min(1),      // "5" → 5
+  tags: z.array(z.string()),           // one tag → ['a']; none ticked → []
+  policy: z.string().optional(),       // hidden behind a switch → absent when off
+  auth: z.discriminatedUnion('kind', [ // auth[kind] picks the branch
+    z.object({ kind: z.literal('none') }),
+    z.object({ kind: z.literal('bearer'), token: z.string().min(1) }),
+  ]),
+  rules: z.array(z.object({ on: z.boolean(), max: z.number() })),  // rules[0][on], rules[0][max]
+}).refine((s) => !s.notify || (s.policy ?? '').length > 0, {
+  path: ['policy'],
+  message: 'Say what to notify about.',
+})
+```
+
+Nothing in that schema knows it will meet a form. A schema describes itself
+(Standard JSON Schema — Zod 4 and ArkType do; Valibot not yet, and its
+values arrive as strings), and the decoder coerces to it: an absent
+`boolean` is `false`, `"on"`/`"1"` is `true`; a numeric string for a
+`number` is the number, an empty one for an optional number is absent; an
+`array` given one value is a list of one and given nothing is empty; nested
+names nest (`fields[0][name]` and `fields[0].name` alike); a union takes the
+branch its discriminator names; a control left blank is absent for a field
+the schema does not require, whatever its type — `z.email().optional()`
+accepts the empty input, an optional union is not read as its first branch
+— and is `""` for one it requires, so `z.string().min(1)` can say so. A value the schema refuses is still refused as itself — `"many"` for a
+number is the error you expect.
+
+A leaf JSON Schema cannot describe — `z.date()`, a custom check — costs only
+that leaf, which arrives as posted; the fields beside it are still read the
+way the schema means. A schema that cannot describe itself at all is said
+once, in development, with the library's reason.
+
+`<Form>` validates that object in the browser and the action decodes the
+same object on the server, from one codec, so a form that passes here passes
+there. A value sent through `<Form transform>` is encoded the same way back
+— a boolean as `"1"`/`"0"`, a nested object as `key[prop]` — and decodes to
+what was given.
+
 ### Lists of values
 
 A repeated name is an array:
@@ -405,6 +468,28 @@ and fades. It is state rather than a timer in every form that wants one,
 because the timer has to be cleared when the component goes away and that is
 the part people forget.
 
+### Nothing to save yet
+
+```tsx
+{({ dirty, reset }) => (
+  <>
+    <Button type="submit" disabled={!dirty}>Save</Button>
+    {dirty && <Button type="button" variant="ghost" onClick={reset}>Discard</Button>}
+  </>
+)}
+```
+
+`dirty` is whether anything differs from what the form started with. It is
+read from the form itself — a snapshot of its `FormData` on mount, compared
+on every input — so an uncontrolled field counts, which is the reason it is
+the form's to answer and not something a component beside it could work
+out. A successful submit makes the current values the new baseline;
+`reset()` goes back to the first one. A bound control with no native
+element behind it counts too, through the store. Only a form that reads
+`dirty` is measured, and it renders once when the value first differs — not
+on the keystrokes after — so a field that subscribes for itself keeps its
+promise of rendering alone.
+
 ### Why not a `<Field>` component
 
 TanStack Form and react-hook-form both hand you a field through a render prop —
@@ -519,6 +604,24 @@ the markup is submittable on its own. Someone who hits enter before the
 javascript arrives still reaches the server; the page reloads with the result
 instead of updating in place.
 
+What happens on the wire: React writes the action's id into the form as a
+hidden field and points the form at the page's own url, and the browser
+posts there. The host reads the fields, runs the action they name exactly as
+the enhanced path would have called it, and renders the page again with what
+it returned seated in the form that posted — so a refusal shows on its
+fields, `error('email')` and `fieldState` included, for a visitor with no
+javascript at all. A `redirect()` the action throws is followed as a
+document's would be; a cookie it sets is on the answer. Same origin only, as
+an action is, and the answer is never stored. A stored page is the one most
+likely to be submitted this way — it paints before its runtime arrives —
+which is why this is not optional.
+
+The seating is React's own `useActionState`, which `<Form>` uses under a
+wrapper bound to your action: React hands a form-state action a
+`(previousState, formData)` pair, and your action keeps taking the
+`FormData` alone. A `useActionState` of your own works the same way, with
+an action written for the pair.
+
 The two do not fight. The handler calls `preventDefault()` first, and React does
 not run a form action for a submit that was cancelled — so the enhanced path
 wins whenever there is one, and the native path is what is left when there is

package/guides/index.json

@@ -59,6 +59,11 @@
     "title": "Errors and 404s",
     "description": "What a visitor sees when a page throws, or asks for a url nothing answers."
   },
+  {
+    "slug": "feature-flags",
+    "title": "Feature flags",
+    "description": "Vercel's Flags SDK runs unchanged — flags/next, without Next."
+  },
   {
     "slug": "file-uploads",
     "title": "File uploads",
@@ -134,6 +139,11 @@
     "title": "Offline",
     "description": "Knowing when the server cannot be reached, and carrying on without it."
   },
+  {
+    "slug": "openapi",
+    "title": "OpenAPI",
+    "description": "A document derived from your route.ts files, and Scalar's page over it."
+  },
   {
     "slug": "ppr",
     "title": "Partial prerendering",

package/guides/installation.md

@@ -63,6 +63,7 @@ export default defineConfig({
       sourceDir: "src",
       outDir: "build",
       offline: true,
+      openapi: { info: { title: 'Example API', version: '1.0.0' } },
     }),
     react(),
   ],
@@ -171,7 +172,7 @@ runs](/hosts/where-it-runs).
     "dev": "bun --bun vite",
     "build": "bun --bun vite build",
     "start": "bun .output/server/index.mjs",
-    "compile": "bun --bun vite build && bun build --compile .output/server/index.mjs --outfile dist/app"
+    "compile": "bun --bun vite build && bun build --compile .output/server/compile.mjs --outfile dist/app"
   }
 }
 ```
@@ -259,12 +260,12 @@ for before they will run.
 There is nothing to install and nothing this package adds — Vite already owns
 this. Two rules and one declaration.
 
-Anything named `VITE_*` is **inlined into the client bundle** and ships to the
-browser, whether or not a browser file reads it. Everything else stays on the
-server, read through `process.env`.
+Anything named `PUBLIC_*` (or Vite's own `VITE_*`) is **inlined into the
+client bundle** and ships to the browser, whether or not a browser file reads
+it. Everything else stays on the server, read through `process.env`.
 
 The prefix is the whole boundary, so never put a secret behind it.
-`VITE_STRIPE_KEY` is a published key.
+`PUBLIC_STRIPE_KEY` is a published key.
 
 And one line never to write into a `.env`: `NODE_ENV`. Vite sets it itself —
 `development` under `vite`, `production` under `vite build` — and honours a
@@ -287,7 +288,7 @@ interface ViteTypeOptions {
 }
 
 interface ImportMetaEnv {
-  readonly VITE_API_URL: string;
+  readonly PUBLIC_API_URL: string;
 }
 ```
 
@@ -299,7 +300,7 @@ interface ImportMetaEnv {
 
 #### When they are read
 
-`import.meta.env.VITE_*` is a literal in the bundle: changing one means a
+`import.meta.env.PUBLIC_*` is a literal in the bundle: changing one means a
 rebuild. `process.env.*` is a live read, so the deploy's environment wins —
 with one exception the build makes for you. A route that reads an environment
 variable and nothing request-bound is frozen at build time, value included,
@@ -321,13 +322,18 @@ import { z } from 'zod';
 
 export const env = createEnv({
   server: { DATABASE_URL: z.string().url() },
-  clientPrefix: 'VITE_',
-  client: { VITE_API_URL: z.string().url() },
+  clientPrefix: 'PUBLIC_',
+  client: { PUBLIC_API_URL: z.string().url() },
   runtimeEnv: typeof process === 'undefined' ? import.meta.env : { ...import.meta.env, ...process.env },
   emptyStringAsUndefined: true,
 });
 ```
 
+`typeof process === 'undefined'` is not decoration: a `"use client"` file
+that imports this for a `PUBLIC_` value runs where there is no `process`,
+and `{ ...process.env }` there is a `ReferenceError` before the first
+render. The scaffold's `env.ts` is written this way.
+
 Read `env.DATABASE_URL` instead of `process.env.DATABASE_URL` and three things
 follow. It is a `string`, not `string | undefined`. A server variable touched
 from a client component throws by name rather than being silently `undefined`.

package/guides/laravel.md

@@ -127,6 +127,16 @@ already use. Vite **is** the renderer in development. It writes
 Laravel does not route is handed through to the address inside it. Stop the
 dev server and the file goes with it, and so does the proxy.
 
+Per url the rule is: **if the React tree has it, React renders it**;
+otherwise Laravel does. That holds for a url Laravel also routes — a fresh
+application ships `Route::get('/', …)` to its welcome page, and after
+install `/` is `resources/js/app/page.tsx`, not the welcome page. The build
+writes its route table to `bootstrap/rsc/vite/routes.json` on every `vite`
+and `vite build`, and the package registers those urls after `routes/web.php`
+loads, so a page added to the tree is routed on the next request. The
+welcome route can stay or go; it answers nothing while the page exists.
+Until the first `vite` there is no table, and Laravel answers everything.
+
 The other direction works too. The renderer reads `APP_URL` and
 `RSC_HOST_CALL_SECRET` from the app's own `.env`, and a url the route tree does
 not own — `/login`, a Blade page, a webhook, a file under `/storage` — is
@@ -232,7 +242,21 @@ method runs, which is where `ValidationException` usually comes from.
 
 A class under `app/Rsc/Actions/` is a server action. `rsc:action-manifest`
 writes the map, and the build writes a `"use server"` module beside your pages
-exporting one function per method, named `classMethod`:
+exporting one function per method, named `classMethod`.
+
+Make one with its guards already on it:
+
+```sh
+php artisan make:rsc-action Orders --method=cancel --auth --can=update,Order --revalidate=orders
+```
+
+`--method` per call (none makes the class invokable, reached as `orders`),
+`--auth` for `#[Authenticated]`, `--can=ability` or `--can=ability,Model` for
+`#[Can]`, `--middleware=throttle:60,1` for `#[Middleware]`, `--revalidate`
+for the `Rsc::revalidate()` line, and `--rpc` to make a class for `rpc()`
+under `app/Rsc` instead. A slash nests: `Billing/Invoices`. The attributes it
+writes are the ones the registry reads, so what you asked for at the prompt
+is what runs.
 
 ```php title="app/Rsc/Actions/Orders.php"
 namespace App\Rsc\Actions;
@@ -362,7 +386,8 @@ closer to a millisecond. What matters is how many *sequential* calls a page
 needs. A page with no `middleware.ts` middleware makes no guard call; sibling
 components awaiting `rpc()` are rendered concurrently, so their calls
 overlap — and calls issued in the same tick travel as **one** request, a
-batch the package answers in one Laravel request; `cache()` dedupes
+batch the package answers in one Laravel request, one line per call as
+each finishes, so a fast read is not held behind a slow one; `cache()` dedupes
 identical calls within a request; a frozen page makes none at all and a
 shell only for its holes. A guarded page is therefore typically two Laravel
 requests — the guard, then the batch of its reads — and a host-call-heavy app

package/guides/offline.md

@@ -65,8 +65,10 @@ rscKit({ offline: true })
 ```
 
 The build writes `sw.js` beside the assets and the generated entry registers
-it. With it on, a page you have visited survives a full reload with no network
-at all — not just a navigation, a reload — and comes back interactive.
+it — once the page has loaded, or at once if it already has by the time the
+runtime boots. With it on, a page you have visited survives a full reload
+with no network at all — not just a navigation, a reload — and comes back
+interactive.
 
 Everything else lives in one page's memory — the pages a boundary keeps
 mounted, the prefetch cache. Reload with no network and the browser shows its
@@ -86,7 +88,8 @@ on every navigation, so it happens on the first load.
 
 | | |
 | --- | --- |
-| hashed assets | at install, and answered from the cache forever after — the name changes when the bytes do |
+| what boots the app | at install: the scripts, stylesheets, fonts, manifest and icons, plus `/` and the offline page with the payloads they boot from. Not an image, a wasm module or the share card — those are cached the first time they are used, so an install costs what a first page costs and not a megabyte more |
+| any other hashed asset | the first time it is asked for, and from the cache forever after — the name changes when the bytes do |
 | a page you loaded | its document, and the payload it boots from |
 | a page you reached by link | its payload, and its document fetched once to go with it |
 | a page you never visited | nothing |
@@ -178,7 +181,9 @@ export default function Offline() {
 Nothing in the file makes it special. It is an ordinary route, and what makes it
 the fallback is that the build stored it and the worker precached it. It is also
 the one page that can honestly stand in for another, because it is about being
-offline rather than about the url it appears under.
+offline rather than about the url it appears under. It stands in for every
+navigation nothing can answer — a page the build stored but this browser
+never visited included.
 
 **It has to be static.** A fallback that renders per request cannot be served
 when there is no request to be made, so the build checks and says when it will

package/guides/openapi.md

@@ -0,0 +1,99 @@
+# OpenAPI
+
+> A document derived from your route.ts files, and Scalar's page over it.
+
+Every `route.ts` already says what an OpenAPI operation needs: the methods it
+exports, and the `params`, `searchParams` and `body` schemas beside them. So
+the document is derived, not written — the way Elysia derives its from the
+schemas on its routes — and it cannot go stale.
+
+```ts title="vite.config.ts"
+rscKit({
+  openapi: {
+    info: { title: 'Shop API', version: '1.0.0' },
+    servers: [{ url: 'https://api.shop.example' }],
+    security: [{ bearerAuth: [] }],
+    components: { securitySchemes: { bearerAuth: { type: 'http', scheme: 'bearer' } } },
+  },
+})
+```
+
+`openapi: true` is the same with defaults. The document answers at
+`/openapi.json` (`path` moves it), as an api route the build stores, without
+middleware — a document exists to be read.
+
+## What a route contributes
+
+```ts title="src/app/api/orders/[id]/route.ts"
+import { z } from 'zod'
+import type { RouteContext } from '@rsc-kit/core/route-schema'
+
+export const params = z.object({ id: z.coerce.number().int() })
+export const searchParams = z.object({ expand: z.boolean().optional() })
+export const body = z.object({ title: z.string().min(1) })
+
+export const openapi = {
+  tags: ['Orders'],
+  PATCH: { summary: 'Rename an order' },
+  responses: { 200: { description: 'The order' } },
+}
+
+export async function GET(request: Request, { params }: RouteContext<typeof params>) { … }
+export async function PATCH(request: Request, { params, body }: RouteContext<typeof params, never, typeof body>) { … }
+```
+
+| from | into the document |
+| --- | --- |
+| the directory | the path: `/api/orders/[id]` → `/api/orders/{id}` |
+| each method export | an operation |
+| `params` | the path parameters' types; a segment with no schema is a string |
+| `searchParams` | one query parameter per property, required where the schema requires it |
+| `body` | the request body of `POST`, `PUT`, `PATCH`, `DELETE`, and a documented `422` |
+| a `middleware.ts` above | a `session` security requirement, and `401`/`403` |
+| `export const openapi` | anything else an operation may say — `summary`, `description`, `tags`, `responses` — shared, or per method under `GET`/`POST`/… |
+
+A schema contributes by describing itself as JSON Schema (Standard JSON
+Schema): Zod 4 and ArkType do; Valibot needs its own converter and
+contributes nothing yet. Response bodies are what a route declares in
+`openapi.responses` — a handler returns `Response`, so nothing else knows the
+shape — until a typed response helper carries it.
+
+`export const openapi = false` leaves a route out: the page that renders the
+document, a webhook meant for one caller. `{ DELETE: false }` leaves one
+method out. An app whose routes are mostly webhooks turns the default
+around with `rscKit({ openapi: { include: 'declared' } })`: only a route
+that exports `openapi` is documented, and a callback needs no line. `HEAD` and `OPTIONS` are never documented — the engine answers
+them for every route, and a file exporting `OPTIONS` for a CORS preflight is
+not describing an operation.
+
+## The page
+
+Scalar's API Reference is a route handler in this shape already, so the
+page is one file and none of it is ours:
+
+```sh
+bun add @scalar/nextjs-api-reference
+```
+
+```ts title="src/app/reference/route.ts"
+import { ApiReference } from '@scalar/nextjs-api-reference'
+
+export const GET = ApiReference({ url: '/openapi.json' })
+export const openapi = false
+```
+
+Stored at build like any route that reads nothing per request. Scalar's
+package is the app's dependency and the app's version; the engine ships no
+UI and no dependency for it, whether or not the document is on.
+
+## Coming from a hand-written spec
+
+A spec kept in a file has three parts, and two of them move:
+
+- the `paths` — delete them; they are the routes and their schemas now, and
+  the same `body` schema validates the request at runtime, which the
+  hand-written spec never did
+- `info`, `servers`, `security`, `components.securitySchemes` — into
+  `rscKit({ openapi })`
+- a route's `summary`, `tags` and response shapes — into its
+  `export const openapi`

package/guides/quick-start.md

@@ -29,7 +29,9 @@ export const env = createEnv({
   },
   clientPrefix: 'PUBLIC_',
   client: {},
-  runtimeEnv: { ...process.env, ...import.meta.env },
+  // No bare process.env: a "use client" file importing this for a PUBLIC_
+  // value has no process, and the spread would throw before the first render.
+  runtimeEnv: { ...(typeof process === 'undefined' ? {} : process.env), ...import.meta.env },
   emptyStringAsUndefined: true,
 })
 ```

package/guides/redirects.md

@@ -55,7 +55,11 @@ windows, and nothing you write chooses between them:
 Neither buffers the response. Before anything is written the host is still
 waiting on the shell, so a component that redirects instead of rendering is
 caught there. After that, React already carries an error digest to the client
-and the destination rides along in it.
+and the destination rides along in it, and the browser performs it as a
+navigation — the layouts above stay mounted, the url being left is replaced
+rather than kept in history. An `error.tsx` on the route never sees it: a
+redirect is the page's answer, not a failure, whether it is thrown by the
+page, by a component under its own `<Suspense>`, or by a parallel route slot.
 
 <Aside type="caution" title="Middleware belongs above the boundaries">
   A `loading.tsx` wraps the whole page in `<Suspense>`. That is usually what you
@@ -85,10 +89,10 @@ renders, on every path. This is the one built for the job.
   layout skips the check:
 
   ```bash
-  curl -H 'X-RSC: true' -H 'X-RSC-Segments: app/layout' /guarded
+  curl -H 'X-RSC: 1' -H 'X-RSC-Segments: app/layout' /guarded
   # 204, X-RSC-Redirect: /orders        ← the middleware ran
 
-  curl -H 'X-RSC: true' -H 'X-RSC-Segments: app/layout,app/guarded/layout' /guarded
+  curl -H 'X-RSC: 1' -H 'X-RSC-Segments: app/layout,app/guarded/layout' /guarded
   # 200, and the page's content         ← it did not
   ```
 
@@ -123,7 +127,18 @@ window, and nothing warns.
 ## From a server action
 
 An action is not a render, so there is no shell to be on either side of. Throw
-from the action and the client follows it:
+from the action — a plain `"use server"` function or one built from
+`createActionClient()` — and the client follows it as a navigation: the
+layouts stay mounted and the history entry the form was on is replaced, so
+Back does not return to the submitted form. A `<Form>` shows nothing for it;
+signing in and arriving is the success.
+
+To the caller, the action **resolves** — with `{ redirected: '/where' }` —
+once the navigation is under way. It does not throw: a `startTransition(async
+() => { await logOut() })` with no `catch` around it would otherwise reject
+into React, which unmounts the root, and a logout ended on a white page.
+There is nothing to catch; a component that awaited the action is on its
+way off the screen, and the object it got is safe to read any field of.
 
 ```ts title="src/actions.ts"
 'use server'

package/guides/routing.md

@@ -232,14 +232,14 @@ fails at the list rather than at the `Link` that renders it:
 
 ```tsx title="src/components/Nav.tsx"
 // `satisfies` rather than a type annotation: an annotation would widen href to
-// Href and lose which one each entry is, while this keeps the literals and
+// Route and lose which one each entry is, while this keeps the literals and
 // still checks them — so a typo fails here, at the list, rather than at the
 // Link that renders it.
 const links = [
   { href: '/', label: 'Home' },
   { href: '/dashboard', label: 'Dashboard' },
   { href: '/posts/hello-world', label: 'A Post' },
-] satisfies { href: Href; label: string }[]
+] satisfies { href: Route; label: string }[]
 ```
 
 ### When the value is not already a url
@@ -269,9 +269,9 @@ When a destination is computed rather than written, cast it — that is the seam
 where you are telling the typechecker something it cannot know:
 
 ```ts
-import type { Href } from '@rsc-kit/core/routes';
+import type { Route } from '@rsc-kit/core/routes';
 
-<Link href={savedPath as Href}>Resume</Link>
+<Link href={savedPath as Route}>Resume</Link>
 ```
 
 Two limits. A dynamic segment widens to `${string}`, and a template literal type