@rsc-kit/mcp 0.15.0 → 0.16.1

package/dist/report.d.ts

@@ -4,6 +4,8 @@ export interface ReportedRoute {
     type: string;
     reason: string | null;
     warning: string | null;
+    /** How it was stored, when that is worth knowing - "no client components, so ships no javascript". */
+    note?: string | null;
     clientJs: number | null;
 }
 export interface ReportedApiRoute {

package/dist/report.js.map

@@ -1 +1 @@
-{"version":3,"file":"report.js","sourceRoot":"","sources":["../src/report.ts"],"names":[],"mappings":"AAAA,qCAAqC;AACrC,EAAE;AACF,8EAA8E;AAC9E,2EAA2E;AAC3E,6EAA6E;AAC7E,yEAAyE;AACzE,EAAE;AACF,6EAA6E;AAC7E,2EAA2E;AAC3E,mDAAmD;AAEnD,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAC5D,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAqCzC,mEAAmE;AACnE,MAAM,MAAM,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,CAAA;AAEnD,MAAM,OAAO,QAAS,SAAQ,KAAK;IACjC,YAAY,IAAY;QACtB,KAAK,CACH,yBAAyB,IAAI,iDAAiD;YAC5E,uEAAuE,CAC1E,CAAA;QACD,IAAI,CAAC,IAAI,GAAG,UAAU,CAAA;IACxB,CAAC;CACF;AAED,qCAAqC;AACrC,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE1B,KAAK,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE,mBAAmB,CAAC,CAAA;QAEjD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,SAAQ;QAE/B,OAAO;YACL,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAgB;YAC9D,0EAA0E;YAC1E,uEAAuE;YACvE,wDAAwD;YACxD,OAAO,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC,KAAK;YAC7B,IAAI,EAAE,IAAI;SACX,CAAA;IACH,CAAC;IAED,MAAM,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAA;AAC1B,CAAC;AAED,0FAA0F;AAC1F,MAAM,CAAC,MAAM,OAAO,GAA2B;IAC7C,MAAM,EAAE,iDAAiD;IACzD,KAAK,EAAE,oDAAoD;IAC3D,OAAO,EAAE,uFAAuF;IAChG,OAAO,EAAE,sBAAsB;IAC/B,KAAK,EAAE,kBAAkB;CAC1B,CAAA;AAED,8DAA8D;AAC9D,MAAM,UAAU,QAAQ,CAAC,MAAmB,EAAE,GAAW;IACvD,MAAM,MAAM,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,CAAA;IAC3E,MAAM,OAAO,GAAG,CAAC,SAAiB,EAAE,EAAE,CACpC,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,KAAK,MAAM,CAAA;IAEjE,OAAO,CACL,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,IAAI,CAC7F,CAAA;AACH,CAAC","sourcesContent":["// Reading what the build wrote down.\n//\n// Everything this server answers comes from one file: `build-report.json`, in\n// the build's own output directory. Nothing here runs a build, imports the\n// app, or re-derives the route tree — the build already decided all of this,\n// and a second implementation would be a second thing that can be wrong.\n//\n// The consequence to be honest about: an answer is only as fresh as the last\n// build. So every answer says when it was built, and a missing report says\n// \"run a build\" rather than \"there are no routes\".\n\nimport { existsSync, readFileSync, statSync } from 'node:fs'\nimport { join, resolve } from 'node:path'\n\nexport interface ReportedRoute {\n  url: string\n  component: string\n  type: string\n  reason: string | null\n  warning: string | null\n  clientJs: number | null\n}\n\nexport interface ReportedApiRoute {\n  url: string\n  name: string\n  type: string\n  reason: string | null\n}\n\nexport interface ReportedAction {\n  id: string\n  name: string\n  file: string\n  /** Built by createActionClient, so its middleware ran. */\n  client: boolean\n  /** A read (GET) rather than a mutation. */\n  query: boolean\n}\n\nexport interface BuildReport {\n  version: number\n  routes: ReportedRoute[]\n  apis: ReportedApiRoute[]\n  /** Absent from reports written before actions were audited. */\n  actions?: ReportedAction[]\n  totals: { static: number; partial: number; dynamic: number; failed: number }\n}\n\n/** Where a build leaves its report, in the order worth looking. */\nconst LIKELY = ['.rsc', 'build', 'dist', '.output']\n\nexport class NoReport extends Error {\n  constructor(root: string) {\n    super(\n      `No build report under ${root}. This server answers from what the last build ` +\n        'decided, so there has to have been one — run the build and ask again.',\n    )\n    this.name = 'NoReport'\n  }\n}\n\n/** The report, and how old it is. */\nexport function loadReport(root: string): { report: BuildReport; builtAt: Date; from: string } {\n  const base = resolve(root)\n\n  for (const dir of LIKELY) {\n    const file = join(base, dir, 'build-report.json')\n\n    if (!existsSync(file)) continue\n\n    return {\n      report: JSON.parse(readFileSync(file, 'utf-8')) as BuildReport,\n      // The file's own mtime rather than a timestamp inside it: a stamp written\n      // into the file changes the file on every build even when nothing else\n      // did, which defeats every cache keyed on its contents.\n      builtAt: statSync(file).mtime,\n      from: file,\n    }\n  }\n\n  throw new NoReport(base)\n}\n\n/** What each classification means, in one line, for an answer that has to stand alone. */\nexport const MEANING: Record<string, string> = {\n  frozen: 'stored whole at build time and served as a file',\n  shell: 'a stored shell, with the rest rendered per request',\n  blocked: 'REFUSED — nothing could paint before it read the request, so the build did not finish',\n  dynamic: 'answered per request',\n  error: 'failed to render',\n}\n\n/** A route by url, tolerating a trailing slash either way. */\nexport function routeFor(report: BuildReport, url: string): ReportedRoute | ReportedApiRoute | null {\n  const wanted = (url.split('?')[0].replace(/\\/+$/, '') || '/').toLowerCase()\n  const matches = (candidate: string) =>\n    (candidate.replace(/\\/+$/, '') || '/').toLowerCase() === wanted\n\n  return (\n    report.routes.find((r) => matches(r.url)) ?? report.apis.find((a) => matches(a.url)) ?? null\n  )\n}\n"]}
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../src/report.ts"],"names":[],"mappings":"AAAA,qCAAqC;AACrC,EAAE;AACF,8EAA8E;AAC9E,2EAA2E;AAC3E,6EAA6E;AAC7E,yEAAyE;AACzE,EAAE;AACF,6EAA6E;AAC7E,2EAA2E;AAC3E,mDAAmD;AAEnD,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAC5D,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAuCzC,mEAAmE;AACnE,MAAM,MAAM,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,CAAA;AAEnD,MAAM,OAAO,QAAS,SAAQ,KAAK;IACjC,YAAY,IAAY;QACtB,KAAK,CACH,yBAAyB,IAAI,iDAAiD;YAC5E,uEAAuE,CAC1E,CAAA;QACD,IAAI,CAAC,IAAI,GAAG,UAAU,CAAA;IACxB,CAAC;CACF;AAED,qCAAqC;AACrC,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE1B,KAAK,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE,mBAAmB,CAAC,CAAA;QAEjD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,SAAQ;QAE/B,OAAO;YACL,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAgB;YAC9D,0EAA0E;YAC1E,uEAAuE;YACvE,wDAAwD;YACxD,OAAO,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC,KAAK;YAC7B,IAAI,EAAE,IAAI;SACX,CAAA;IACH,CAAC;IAED,MAAM,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAA;AAC1B,CAAC;AAED,0FAA0F;AAC1F,MAAM,CAAC,MAAM,OAAO,GAA2B;IAC7C,MAAM,EAAE,iDAAiD;IACzD,KAAK,EAAE,oDAAoD;IAC3D,OAAO,EAAE,uFAAuF;IAChG,OAAO,EAAE,sBAAsB;IAC/B,KAAK,EAAE,kBAAkB;CAC1B,CAAA;AAED,8DAA8D;AAC9D,MAAM,UAAU,QAAQ,CAAC,MAAmB,EAAE,GAAW;IACvD,MAAM,MAAM,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,CAAA;IAC3E,MAAM,OAAO,GAAG,CAAC,SAAiB,EAAE,EAAE,CACpC,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,KAAK,MAAM,CAAA;IAEjE,OAAO,CACL,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,IAAI,CAC7F,CAAA;AACH,CAAC","sourcesContent":["// Reading what the build wrote down.\n//\n// Everything this server answers comes from one file: `build-report.json`, in\n// the build's own output directory. Nothing here runs a build, imports the\n// app, or re-derives the route tree — the build already decided all of this,\n// and a second implementation would be a second thing that can be wrong.\n//\n// The consequence to be honest about: an answer is only as fresh as the last\n// build. So every answer says when it was built, and a missing report says\n// \"run a build\" rather than \"there are no routes\".\n\nimport { existsSync, readFileSync, statSync } from 'node:fs'\nimport { join, resolve } from 'node:path'\n\nexport interface ReportedRoute {\n  url: string\n  component: string\n  type: string\n  reason: string | null\n  warning: string | null\n  /** How it was stored, when that is worth knowing - \"no client components, so ships no javascript\". */\n  note?: string | null\n  clientJs: number | null\n}\n\nexport interface ReportedApiRoute {\n  url: string\n  name: string\n  type: string\n  reason: string | null\n}\n\nexport interface ReportedAction {\n  id: string\n  name: string\n  file: string\n  /** Built by createActionClient, so its middleware ran. */\n  client: boolean\n  /** A read (GET) rather than a mutation. */\n  query: boolean\n}\n\nexport interface BuildReport {\n  version: number\n  routes: ReportedRoute[]\n  apis: ReportedApiRoute[]\n  /** Absent from reports written before actions were audited. */\n  actions?: ReportedAction[]\n  totals: { static: number; partial: number; dynamic: number; failed: number }\n}\n\n/** Where a build leaves its report, in the order worth looking. */\nconst LIKELY = ['.rsc', 'build', 'dist', '.output']\n\nexport class NoReport extends Error {\n  constructor(root: string) {\n    super(\n      `No build report under ${root}. This server answers from what the last build ` +\n        'decided, so there has to have been one — run the build and ask again.',\n    )\n    this.name = 'NoReport'\n  }\n}\n\n/** The report, and how old it is. */\nexport function loadReport(root: string): { report: BuildReport; builtAt: Date; from: string } {\n  const base = resolve(root)\n\n  for (const dir of LIKELY) {\n    const file = join(base, dir, 'build-report.json')\n\n    if (!existsSync(file)) continue\n\n    return {\n      report: JSON.parse(readFileSync(file, 'utf-8')) as BuildReport,\n      // The file's own mtime rather than a timestamp inside it: a stamp written\n      // into the file changes the file on every build even when nothing else\n      // did, which defeats every cache keyed on its contents.\n      builtAt: statSync(file).mtime,\n      from: file,\n    }\n  }\n\n  throw new NoReport(base)\n}\n\n/** What each classification means, in one line, for an answer that has to stand alone. */\nexport const MEANING: Record<string, string> = {\n  frozen: 'stored whole at build time and served as a file',\n  shell: 'a stored shell, with the rest rendered per request',\n  blocked: 'REFUSED — nothing could paint before it read the request, so the build did not finish',\n  dynamic: 'answered per request',\n  error: 'failed to render',\n}\n\n/** A route by url, tolerating a trailing slash either way. */\nexport function routeFor(report: BuildReport, url: string): ReportedRoute | ReportedApiRoute | null {\n  const wanted = (url.split('?')[0].replace(/\\/+$/, '') || '/').toLowerCase()\n  const matches = (candidate: string) =>\n    (candidate.replace(/\\/+$/, '') || '/').toLowerCase() === wanted\n\n  return (\n    report.routes.find((r) => matches(r.url)) ?? report.apis.find((a) => matches(a.url)) ?? null\n  )\n}\n"]}

package/guides/coming-from-next.md

@@ -0,0 +1,151 @@
+# Coming from Next.js
+
+> What carries over unchanged, what to rename, and what is different on purpose.
+
+Most of a Next.js app directory moves over as it is. This page is the rest,
+in the order a port meets it.
+
+## What is the same
+
+The `app/` conventions are the same conventions: `layout.tsx`, `page.tsx`,
+`loading.tsx`, `error.tsx`, `not-found.tsx`, `route.ts`, `[slug]`,
+`[...path]`, `(group)`, `@slot` and `(.)intercept`. `"use client"` and
+`"use server"` mean what they mean in React. `cookies()` and `headers()` are
+async and have the same names. `redirect()`, `notFound()`,
+`generateStaticParams()` and `export const metadata` all exist. Streaming
+through `<Suspense>` works the same way, because it is React doing it.
+
+Copy `src/app` across first and fix imports second. Most files need only the
+imports.
+
+## Imports
+
+| Next.js | here |
+| --- | --- |
+| `next/link` | `@rsc-kit/core/Link` — `href` is typed to your routes, and `search` to the page's schema |
+| `useRouter().push(url)` | `visit(url)` from `@rsc-kit/core/router`; `replace: true` for `.replace()` |
+| `useRouter().refresh()` | `refresh()` from `@rsc-kit/core/router` — or better, `revalidate()` from the action |
+| `usePathname()` | `@rsc-kit/core/usePathname` |
+| `useSearchParams()` | `@rsc-kit/core/useSearchParams`, or [nuqs](/guides/routing#search-params-as-state) with our adapter |
+| `useParams()` | the page's `params` prop, passed down |
+| `cookies()`, `headers()` from `next/headers` | the same names from `@rsc-kit/core/request` |
+| `redirect()` from `next/navigation` | `@rsc-kit/core/redirect` |
+| `notFound()` | `@rsc-kit/core/not-found` |
+| `revalidatePath()`, `revalidateTag()` | `revalidate('tag')` from `@rsc-kit/core/revalidate` — see below, it is narrower |
+| `Metadata` from `next` | `@rsc-kit/core/metadata` — `metadataBase`, `openGraph`, `twitter`, `icons` as you had them |
+| `next/font` | [Fontsource](/guides/fonts): install the font, import its CSS |
+| `next/image` | [unpic](/guides/images) for a CDN, `vite-imagetools` for files in the repo |
+| `next/script` | [a `<script>` tag](/guides/third-party-scripts): React 19 hoists and dedupes `async` scripts itself |
+| `NEXT_PUBLIC_*` | `VITE_*`, read through `import.meta.env`; everything else stays `process.env` on the server |
+| `next.config.js` | `vite.config.ts` — Tailwind, aliases and plugins are Vite's |
+| `next-safe-action` | `createActionClient()` — same shape, [below](#actions) |
+
+## Different on purpose
+
+### Nothing is dynamic by declaration
+
+There is no `export const dynamic = 'force-dynamic'` and no `revalidate = 60`.
+A page is frozen at build time unless it **reads the request** — `cookies()`,
+`headers()`, `searchParams`, `await connection()` — and then it renders per
+request, or as a shell with the reading part streamed in. The build prints
+which, and why:
+
+```
+  ○  /about               no js
+  ◐  /orders              85 kB
+     dynamic — called cookies()
+```
+
+`await connection()` is the one explicit mark, for a page that must render per
+visitor and does not happen to read anything. Time-based ISR does not exist:
+a frozen page changes when you build, a dynamic one on every request, and
+[edge caching](/guides/edge-caching) covers the middle.
+
+### Middleware is per directory, not one file at the edge
+
+Next has one `middleware.ts` that runs on a matcher, on the edge runtime, with
+a restricted API. Here a `middleware.ts` sits in the directory it protects,
+runs on the server with the full API, and covers everything below it:
+
+```ts title="src/app/admin/middleware.ts"
+export default async function middleware() {
+  if (!(await currentUser())?.isAdmin) redirect('/login');
+}
+```
+
+It does not run for actions — an action renders no route — which is why the
+check for an action belongs in the action. See [Authorization](/guides/authorization).
+
+### Actions
+
+`next-safe-action` users will find the same shape under a different name.
+`createActionClient()` chains middleware, validates with any Standard Schema,
+and **returns** failures as `{ validationErrors }` or `{ serverError }` rather
+than throwing them across the wire:
+
+```ts
+export const client = createActionClient().use(async ({ next }) => {
+  const user = await currentUser();
+  if (!user) throw new ServerAuthenticationError();
+  return next({ ctx: { user } });
+});
+
+export const createPost = client.input(schema).handler(async ({ input, ctx, fieldErrors }) => {
+  if (await slugTaken(input.slug)) return fieldErrors({ slug: 'Already taken' });
+  return save(input, ctx.user);
+});
+```
+
+`returnValidationErrors(schema, { email: { _errors: [...] } })` becomes
+`return fieldErrors({ email: 'Account not found' })`. `useAction` from
+next-safe-action is `useActionState`, or a `<Form action={createPost}>` that
+reads the returned errors on its own. The build lists any action not built
+from a client, because nothing checks who calls those.
+
+### Revalidation is targeted
+
+`revalidatePath('/orders')` re-renders the page. `revalidate('orders')`
+re-renders the [section](/guides/sections) registered under that name and
+sends it back **with the action's own response** — one request, the rest of
+the page untouched, a half-typed input elsewhere on it still typed. Wrap the
+region in `section('orders', Orders)` and name it from the action.
+
+### Forms
+
+`<Form>` from `@rsc-kit/core/form` submits to an action, shows pending state,
+places field errors, and works before hydration. It is uncontrolled by
+default like React Hook Form's `register`, with `field()` for a controlled
+binding and `useField()` for a value read anywhere. shadcn's `Field`
+components fit as they are. See [Forms](/guides/forms).
+
+### Query strings are typed
+
+Export a schema beside the page and the values arrive parsed; the same schema
+types every `<Link search={…}>` to it. `Number(searchParams.get('page'))` is
+not a thing you write here. See [URL validation](/guides/url-validation).
+
+### There is no image optimizer, and no `opengraph-image.tsx`
+
+Both are processes Next runs for you at request time. Put `opengraph-image.png`
+in `src/app` and it is picked up; generate one at build time if it has to be
+generated. Images: [unpic or imagetools](/guides/images).
+
+### Testing does not need a browser
+
+`createTestApp()` hands back the deployed `Request → Response` handler.
+Actions, queries and api routes are plain functions. There is no equivalent
+in Next; see [Testing](/guides/testing).
+
+## The porting order that worked
+
+1. `bun create rsc-kit@latest` and copy `src/app` over the scaffold's.
+2. Fix imports from the table. `bun run typecheck` finds the rest.
+3. `bun run build` and **read the output**: every route that is not `○` says
+   why. Most surprises are a `cookies()` in a layout making everything
+   dynamic — the build says so under the summary.
+4. Actions not built from a client are listed. Decide for each.
+5. `bun run check`. Then a browser, for the parts that are a browser's.
+
+An agent doing the port has all of this: the `.mcp.json` in the scaffold
+answers `how_to({ topic })` and `read_guide({ slug })` from the installed
+version, and the build report is what it reads instead of guessing.

package/guides/getting-started.md

@@ -0,0 +1,132 @@
+# Getting started
+
+> Serve React Server Components from any JavaScript backend.
+
+A host is a `Request` in and a `Response` out. You do not normally write the
+server that calls it: [Nitro](https://nitro.build) builds one around your route
+tree, and where it runs is a preset in `vite.config.ts`.
+
+## Building
+
+Three steps, and only the first is required:
+
+```bash
+npm run dev         # vite — serves from source, no build step
+npm run build       # bundles, renders every route once, then Nitro assembles .output/
+npm run start       # runs .output/server/index.mjs
+```
+
+`dev` is Vite's own dev server, and edits reach the browser without a reload:
+
+| you edit | what happens |
+| --- | --- |
+| a client component | Fast Refresh — the code updates and its state survives |
+| a page or layout | the payload is re-fetched and the tree re-rendered |
+| adding or deleting a page | the server restarts to pick up the new route table |
+
+The browser never holds a server component, so Vite cannot hot-swap it. Instead
+the client re-fetches the page — which remounts any client component below, so
+their state resets.
+
+Edit a client component directly and its state does survive; that is Fast
+Refresh.
+
+The restart on a new page is because the route tree is read when the server
+starts: a page that appears later would otherwise 404 while sitting right there
+on disk.
+
+`build` ends by rendering every route once and storing what it can, which is
+what turns a route into a file on disk instead of a render per request.
+
+It is part of `build` rather than a separate command because forgetting it costs
+you everything and looks like nothing — every page still works, each one just
+renders again for every visitor.
+
+Turn it off with `rscKit({ prerender: false })` when the build machine
+cannot do what the pages need. See [Static
+generation](/guides/static-generation).
+
+<Aside type="note" title="There is no NODE_ENV to set">
+  React picks its build from it, and getting it wrong gives you a page that
+  renders perfectly and never hydrates. The build stamps the mode it ran in
+  into the server bundles, so a server is production because it was built that
+  way — `npm run start` needs no environment at all.
+</Aside>
+
+## Compiling to a single binary
+
+With the Bun preset the whole application ends up in one file:
+
+```bash
+npm run compile   # builds, then bun build --compile
+./dist/app
+```
+
+That works because the generated config sets `serveStatic: 'inline'`. Without
+it the binary compiles, starts, serves pages, and 404s every asset — the static
+path resolves into Bun's virtual filesystem, where the files on disk are not.
+
+### What it costs
+
+Measured on the example — eleven routes, 240 KB of assets, 164 KB of stored
+pages:
+
+| | compiled | run from `.output/` |
+| --- | --- | --- |
+| Cold start | 45 ms | 56–65 ms |
+| Resident, idle | 18 MB | 19 MB |
+| Resident, after 300 requests | 27 MB | 32 MB |
+| On disk | 62 MB | 240 KB + a runtime |
+
+Memory is flat between the two: the binary holds its assets as `Response`
+objects built at boot, which for 240 KB is nothing, and both settle in the high
+twenties once React has warmed up. A live render is what moves it — 40 MB after
+200 of them — and that is the renderer, not the packaging.
+
+<Aside type="note" title="What compiling is actually for">
+  Deployment shape, not speed. One file, no `node_modules`, no runtime to
+  install. Throughput between the two is inside the noise of any benchmark I
+  could run on one machine — the only differences I can defend are the ~15 ms
+  of cold start and the shape of what you ship.
+</Aside>
+
+<Aside type="caution" title="What embedding costs">
+  Every asset goes in whole. Three files is nothing; a media-heavy app is
+  hundreds of megabytes of executable, with no CDN in front and no streaming
+  from disk. Keep large or rarely-read files outside the binary and serve them
+  from wherever they already live.
+
+  Frozen pages are not embedded either. The build writes them to
+  `.output/server/rsc-static` and the server reads them from beside itself; a
+  binary has no filesystem to read, so it renders those pages live. Everything
+  still answers — what you lose is the stored render, not the page.
+</Aside>
+
+## If you work with an AI agent
+
+The scaffold writes an `AGENTS.md` beside your `README.md`. Claude Code, Cursor
+and the rest read it, and it covers the things an agent otherwise gets wrong
+from React or Next habits — `"use client"` versus `"use server"`, where an
+authorisation check belongs, which props are async, and that the build output is
+worth reading rather than ignoring.
+
+Beside it is `.mcp.json`, which connects the [MCP server](/guides/mcp): Claude
+Code asks you to approve it on first use, and from then on an agent can read
+what your last build actually did instead of guessing.
+
+And there is a test to extend, `tests/app.test.ts`, which goes through the
+real build: `bun run check` runs typecheck, lint and tests together, and is
+the one command an agent — or you — runs before calling something done.
+
+Edit it as your project grows. It is yours; nothing regenerates it.
+
+There is also an MCP server, which answers from your actual build rather than
+from memory:
+
+```sh
+claude mcp add rsc-kit -- npx -y @rsc-kit/mcp
+```
+
+It can say why a particular page is not static, what each route ships to the
+browser, and how to build a form or an api route the way this framework
+expects. See [Working with an AI agent](/guides/mcp/).

package/guides/index.json

@@ -14,6 +14,11 @@
     "title": "Asking once per request",
     "description": "cache() — one lookup, however many places need it."
   },
+  {
+    "slug": "coming-from-next",
+    "title": "Coming from Next.js",
+    "description": "What carries over unchanged, what to rename, and what is different on purpose."
+  },
   {
     "slug": "connection",
     "title": "Rendering per request",
@@ -44,11 +49,26 @@
     "title": "Forms",
     "description": "Progressive forms, pending state and validation errors."
   },
+  {
+    "slug": "getting-started",
+    "title": "Getting started",
+    "description": "Serve React Server Components from any JavaScript backend."
+  },
   {
     "slug": "images",
     "title": "Images",
     "description": "Responsive images with no optimizer to run — unpic for a CDN, imagetools for files in the repo."
   },
+  {
+    "slug": "installation",
+    "title": "Installation",
+    "description": "From an empty directory to a streaming RSC app."
+  },
+  {
+    "slug": "introduction",
+    "title": "Introduction",
+    "description": "React Server Components as a Vite plugin, deployed wherever you like."
+  },
   {
     "slug": "mcp",
     "title": "Working with an AI agent",
@@ -67,7 +87,7 @@
   {
     "slug": "no-javascript",
     "title": "A page with no JavaScript",
-    "description": "Rendering a route to HTML and stopping there."
+    "description": "The default is none. A client component is how a page asks for it."
   },
   {
     "slug": "offline",
@@ -89,6 +109,11 @@
     "title": "Queries",
     "description": "Reading from the server over GET, and letting TanStack Query or SWR own everything above it."
   },
+  {
+    "slug": "quick-start",
+    "title": "Quick start",
+    "description": "A running app in one command, or added to a project you already have."
+  },
   {
     "slug": "react-compiler",
     "title": "React Compiler",