@rsc-kit/mcp 0.17.0 → 0.18.1

package/dist/index.js

@@ -20,6 +20,7 @@
 // Everything is read-only. There is no tool here that edits, builds or deploys,
 // deliberately: an agent already has a shell for those, and a server that can
 // change the project is one that can change it while answering a question.
+import { readFileSync } from 'node:fs';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
@@ -61,7 +62,18 @@ const answering = (produce) => {
         throw error;
     }
 };
-const server = new McpServer({ name: 'rsc-kit', version: '0.1.0' });
+// The published version, read from this package's own manifest: the server
+// answered `0.1.0` to every client, which is the repo's placeholder and told
+// nobody which release they were talking to.
+const selfVersion = (() => {
+    try {
+        return JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf-8')).version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+})();
+const server = new McpServer({ name: 'rsc-kit', version: selfVersion });
 server.registerTool('list_routes', {
     title: 'List routes',
     description: 'Every route in this rsc-kit app, what the build did with each one, and how much javascript it ships. Start here when you need to know what exists.',
@@ -97,7 +109,7 @@ server.registerTool('heaviest_routes', {
 }));
 server.registerTool('how_to', {
     title: 'How to build it',
-    description: 'How to do something in an rsc-kit app — forms, prefetching, validation, the action client, data loading with TanStack Query or SWR, Suspense boundaries, offline, PWA, api routes, authorization, and why a page is dynamic. Read this BEFORE writing the code: the patterns here differ from Next and plain React in ways that compile either way. The short answer; read_guide has the full one.',
+    description: 'How to do something in an rsc-kit app — forms, prefetching, validation, the action client, data loading with TanStack Query or SWR, Suspense boundaries, offline, PWA, api routes, authorization, a Laravel or other backend, once-per-process startup, and why a page is dynamic. Read this BEFORE writing the code: the patterns here differ from Next and plain React in ways that compile either way. The short answer; read_guide has the full one.',
     inputSchema: TOPIC_ARG,
     annotations: { readOnlyHint: true },
 }, (async ({ topic }) => text(howTo(topic))));

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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","sourcesContent":["#!/usr/bin/env node\n// An MCP server over what an rsc-kit build decided.\n//\n//   claude mcp add rsc-kit -- npx -y @rsc-kit/mcp\n//\n// Four questions, all answered from `build-report.json` and none of them\n// requiring the app to be running:\n//\n//   what routes exist, and what happened to each\n//   why is this one not stored\n//   which ones render per request\n//   which ones cost the browser the most\n//\n// Why a server rather than letting an agent read the file: the file is JSON\n// with a `type` field whose values mean nothing without the documentation, and\n// an agent reading it guesses — \"shell\" invites being treated as a failure when\n// it is the normal, correct outcome for a page with data in it. These answers\n// say what each state means, in the same words the build printed.\n//\n// Everything is read-only. There is no tool here that edits, builds or deploys,\n// deliberately: an agent already has a shell for those, and a server that can\n// change the project is one that can change it while answering a question.\n\nimport { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'\nimport { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'\nimport { z } from 'zod'\nimport { explainRoute, heaviestRoutes, listRoutes, whatIsDynamic } from './answers.js'\nimport { NoReport, loadReport } from './report.js'\nimport { howTo, listTopics } from './recipes.js'\nimport { listGuides, readGuide, searchGuides } from './bundleGuides.js'\n\n/** The project to read, from the argument or the working directory. */\nconst root = process.argv[2] ?? process.cwd()\n\n/**\n * Loaded per call, never cached.\n *\n * A build happens while this server is running — that is the normal case, not\n * the exception — and an answer from the build before it is worse than a slow\n * one. The file is small and this is not a hot path.\n */\nconst read = () => loadReport(root)\n\n/**\n * Declared once, outside the call.\n *\n * Inline, TypeScript walks the sdk's tool generics against the zod shape and\n * gives up with \"type instantiation is excessively deep\" — a compiler limit\n * rather than anything wrong with the schema. A named const with the handler's\n * argument annotated stops the inference chain before it gets there.\n */\nconst URL_ARG = { url: z.string().describe('The url, e.g. /orders or /posts/hello') }\nconst TOPIC_ARG = { topic: z.string().describe('One of the topics from list_topics, e.g. forms or validation') }\nconst SLUG_ARG = { slug: z.string().describe('One of the slugs from list_guides, e.g. forms or server-actions') }\nconst PHRASE_ARG = { phrase: z.string().describe('A word or phrase, e.g. fieldErrors or metadataBase') }\n\nconst text = (body: string) => ({ content: [{ type: 'text' as const, text: body }] })\n\n/** A missing report is an answer, not a crash: it says to run a build. */\nconst answering = (produce: () => string) => {\n  try {\n    return text(produce())\n  } catch (error) {\n    if (error instanceof NoReport) return text(error.message)\n\n    throw error\n  }\n}\n\n/**\n * The registration surface, named rather than inferred.\n *\n * `registerTool` is generic over the zod shape, and TypeScript walks those\n * generics until it gives up — \"type instantiation is excessively deep\", which\n * is a compiler limit rather than anything wrong with the schema. Describing\n * the one method used, with the argument type written out, stops the inference\n * before it gets there and costs nothing: the schemas below are still real zod\n * and still validate at runtime.\n */\ninterface Registrar {\n  registerTool(\n    name: string,\n    config: {\n      title?: string\n      description?: string\n      inputSchema?: Record<string, unknown>\n      annotations?: { readOnlyHint?: boolean }\n    },\n    handler: (args: never) => Promise<{ content: { type: 'text'; text: string }[] }>,\n  ): unknown\n  connect(transport: StdioServerTransport): Promise<void>\n}\n\nconst server = new McpServer({ name: 'rsc-kit', version: '0.1.0' }) as unknown as Registrar\n\nserver.registerTool(\n  'list_routes',\n  {\n    title: 'List routes',\n    description:\n      'Every route in this rsc-kit app, what the build did with each one, and how much javascript it ships. Start here when you need to know what exists.',\n    annotations: { readOnlyHint: true },\n  },\n  async () =>\n    answering(() => {\n      const { report, builtAt } = read()\n\n      return listRoutes(report, builtAt, Date.now())\n    }),\n)\n\nserver.registerTool(\n  'explain_route',\n  {\n    title: 'Explain a route',\n    description:\n      'Why one url is stored at build time or rendered per request, what renders it, and what it costs the browser. Use this before changing a page to make it faster — the reason is recorded, not guessed.',\n    inputSchema: URL_ARG,\n    annotations: { readOnlyHint: true },\n  },\n  (async ({ url }: { url: string }) =>\n    answering(() => {\n      const { report, builtAt } = read()\n\n      return explainRoute(report, url, builtAt, Date.now())\n    })) as never,\n)\n\nserver.registerTool(\n  'what_is_dynamic',\n  {\n    title: 'What renders per request',\n    description:\n      'The routes that render per request rather than being stored, each with the reason. This is the answer to \"why is this site not static\".',\n    annotations: { readOnlyHint: true },\n  },\n  async () =>\n    answering(() => {\n      const { report, builtAt } = read()\n\n      return whatIsDynamic(report, builtAt, Date.now())\n    }),\n)\n\nserver.registerTool(\n  'heaviest_routes',\n  {\n    title: 'Heaviest routes',\n    description: 'The routes that make the browser download the most javascript, largest first.',\n    annotations: { readOnlyHint: true },\n  },\n  async () =>\n    answering(() => {\n      const { report, builtAt } = read()\n\n      return heaviestRoutes(report, builtAt, Date.now())\n    }),\n)\n\nserver.registerTool(\n  'how_to',\n  {\n    title: 'How to build it',\n    description:\n      'How to do something in an rsc-kit app — forms, prefetching, validation, the action client, data loading with TanStack Query or SWR, Suspense boundaries, offline, PWA, api routes, authorization, and why a page is dynamic. Read this BEFORE writing the code: the patterns here differ from Next and plain React in ways that compile either way. The short answer; read_guide has the full one.',\n    inputSchema: TOPIC_ARG,\n    annotations: { readOnlyHint: true },\n  },\n  (async ({ topic }: { topic: string }) => text(howTo(topic))) as never,\n)\n\nserver.registerTool(\n  'list_topics',\n  {\n    title: 'What this server can explain',\n    description: 'Every topic how_to knows about, one line each.',\n    annotations: { readOnlyHint: true },\n  },\n  async () => text(listTopics()),\n)\n\nserver.registerTool(\n  'list_guides',\n  {\n    title: 'The guides',\n    description: 'Every guide from docs.rsc-kit.dev, bundled with this server — the full text behind how_to, one line each.',\n    annotations: { readOnlyHint: true },\n  },\n  async () => text(listGuides()),\n)\n\nserver.registerTool(\n  'read_guide',\n  {\n    title: 'Read a guide',\n    description:\n      'The complete guide for one topic, as published at docs.rsc-kit.dev — routing, forms, server-actions, validation, metadata, testing, deployment and the rest. Use it when how_to is not enough or names something it does not explain.',\n    inputSchema: SLUG_ARG,\n    annotations: { readOnlyHint: true },\n  },\n  (async ({ slug }: { slug: string }) => text(readGuide(slug))) as never,\n)\n\nserver.registerTool(\n  'search_guides',\n  {\n    title: 'Search the guides',\n    description: 'Every line in the guides that mentions a word or phrase, with the guide it is in. Use it to find which guide covers something before reading it.',\n    inputSchema: PHRASE_ARG,\n    annotations: { readOnlyHint: true },\n  },\n  (async ({ phrase }: { phrase: string }) => text(searchGuides(phrase))) as never,\n)\n\nawait server.connect(new StdioServerTransport())\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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","sourcesContent":["#!/usr/bin/env node\n// An MCP server over what an rsc-kit build decided.\n//\n//   claude mcp add rsc-kit -- npx -y @rsc-kit/mcp\n//\n// Four questions, all answered from `build-report.json` and none of them\n// requiring the app to be running:\n//\n//   what routes exist, and what happened to each\n//   why is this one not stored\n//   which ones render per request\n//   which ones cost the browser the most\n//\n// Why a server rather than letting an agent read the file: the file is JSON\n// with a `type` field whose values mean nothing without the documentation, and\n// an agent reading it guesses — \"shell\" invites being treated as a failure when\n// it is the normal, correct outcome for a page with data in it. These answers\n// say what each state means, in the same words the build printed.\n//\n// Everything is read-only. There is no tool here that edits, builds or deploys,\n// deliberately: an agent already has a shell for those, and a server that can\n// change the project is one that can change it while answering a question.\n\nimport { readFileSync } from 'node:fs'\nimport { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'\nimport { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'\nimport { z } from 'zod'\nimport { explainRoute, heaviestRoutes, listRoutes, whatIsDynamic } from './answers.js'\nimport { NoReport, loadReport } from './report.js'\nimport { howTo, listTopics } from './recipes.js'\nimport { listGuides, readGuide, searchGuides } from './bundleGuides.js'\n\n/** The project to read, from the argument or the working directory. */\nconst root = process.argv[2] ?? process.cwd()\n\n/**\n * Loaded per call, never cached.\n *\n * A build happens while this server is running — that is the normal case, not\n * the exception — and an answer from the build before it is worse than a slow\n * one. The file is small and this is not a hot path.\n */\nconst read = () => loadReport(root)\n\n/**\n * Declared once, outside the call.\n *\n * Inline, TypeScript walks the sdk's tool generics against the zod shape and\n * gives up with \"type instantiation is excessively deep\" — a compiler limit\n * rather than anything wrong with the schema. A named const with the handler's\n * argument annotated stops the inference chain before it gets there.\n */\nconst URL_ARG = { url: z.string().describe('The url, e.g. /orders or /posts/hello') }\nconst TOPIC_ARG = { topic: z.string().describe('One of the topics from list_topics, e.g. forms or validation') }\nconst SLUG_ARG = { slug: z.string().describe('One of the slugs from list_guides, e.g. forms or server-actions') }\nconst PHRASE_ARG = { phrase: z.string().describe('A word or phrase, e.g. fieldErrors or metadataBase') }\n\nconst text = (body: string) => ({ content: [{ type: 'text' as const, text: body }] })\n\n/** A missing report is an answer, not a crash: it says to run a build. */\nconst answering = (produce: () => string) => {\n  try {\n    return text(produce())\n  } catch (error) {\n    if (error instanceof NoReport) return text(error.message)\n\n    throw error\n  }\n}\n\n/**\n * The registration surface, named rather than inferred.\n *\n * `registerTool` is generic over the zod shape, and TypeScript walks those\n * generics until it gives up — \"type instantiation is excessively deep\", which\n * is a compiler limit rather than anything wrong with the schema. Describing\n * the one method used, with the argument type written out, stops the inference\n * before it gets there and costs nothing: the schemas below are still real zod\n * and still validate at runtime.\n */\ninterface Registrar {\n  registerTool(\n    name: string,\n    config: {\n      title?: string\n      description?: string\n      inputSchema?: Record<string, unknown>\n      annotations?: { readOnlyHint?: boolean }\n    },\n    handler: (args: never) => Promise<{ content: { type: 'text'; text: string }[] }>,\n  ): unknown\n  connect(transport: StdioServerTransport): Promise<void>\n}\n\n// The published version, read from this package's own manifest: the server\n// answered `0.1.0` to every client, which is the repo's placeholder and told\n// nobody which release they were talking to.\nconst selfVersion = (() => {\n  try {\n    return (JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf-8')) as { version?: string }).version ?? '0.0.0'\n  } catch {\n    return '0.0.0'\n  }\n})()\n\nconst server = new McpServer({ name: 'rsc-kit', version: selfVersion }) as unknown as Registrar\n\nserver.registerTool(\n  'list_routes',\n  {\n    title: 'List routes',\n    description:\n      'Every route in this rsc-kit app, what the build did with each one, and how much javascript it ships. Start here when you need to know what exists.',\n    annotations: { readOnlyHint: true },\n  },\n  async () =>\n    answering(() => {\n      const { report, builtAt } = read()\n\n      return listRoutes(report, builtAt, Date.now())\n    }),\n)\n\nserver.registerTool(\n  'explain_route',\n  {\n    title: 'Explain a route',\n    description:\n      'Why one url is stored at build time or rendered per request, what renders it, and what it costs the browser. Use this before changing a page to make it faster — the reason is recorded, not guessed.',\n    inputSchema: URL_ARG,\n    annotations: { readOnlyHint: true },\n  },\n  (async ({ url }: { url: string }) =>\n    answering(() => {\n      const { report, builtAt } = read()\n\n      return explainRoute(report, url, builtAt, Date.now())\n    })) as never,\n)\n\nserver.registerTool(\n  'what_is_dynamic',\n  {\n    title: 'What renders per request',\n    description:\n      'The routes that render per request rather than being stored, each with the reason. This is the answer to \"why is this site not static\".',\n    annotations: { readOnlyHint: true },\n  },\n  async () =>\n    answering(() => {\n      const { report, builtAt } = read()\n\n      return whatIsDynamic(report, builtAt, Date.now())\n    }),\n)\n\nserver.registerTool(\n  'heaviest_routes',\n  {\n    title: 'Heaviest routes',\n    description: 'The routes that make the browser download the most javascript, largest first.',\n    annotations: { readOnlyHint: true },\n  },\n  async () =>\n    answering(() => {\n      const { report, builtAt } = read()\n\n      return heaviestRoutes(report, builtAt, Date.now())\n    }),\n)\n\nserver.registerTool(\n  'how_to',\n  {\n    title: 'How to build it',\n    description:\n      'How to do something in an rsc-kit app — forms, prefetching, validation, the action client, data loading with TanStack Query or SWR, Suspense boundaries, offline, PWA, api routes, authorization, a Laravel or other backend, once-per-process startup, and why a page is dynamic. Read this BEFORE writing the code: the patterns here differ from Next and plain React in ways that compile either way. The short answer; read_guide has the full one.',\n    inputSchema: TOPIC_ARG,\n    annotations: { readOnlyHint: true },\n  },\n  (async ({ topic }: { topic: string }) => text(howTo(topic))) as never,\n)\n\nserver.registerTool(\n  'list_topics',\n  {\n    title: 'What this server can explain',\n    description: 'Every topic how_to knows about, one line each.',\n    annotations: { readOnlyHint: true },\n  },\n  async () => text(listTopics()),\n)\n\nserver.registerTool(\n  'list_guides',\n  {\n    title: 'The guides',\n    description: 'Every guide from docs.rsc-kit.dev, bundled with this server — the full text behind how_to, one line each.',\n    annotations: { readOnlyHint: true },\n  },\n  async () => text(listGuides()),\n)\n\nserver.registerTool(\n  'read_guide',\n  {\n    title: 'Read a guide',\n    description:\n      'The complete guide for one topic, as published at docs.rsc-kit.dev — routing, forms, server-actions, validation, metadata, testing, deployment and the rest. Use it when how_to is not enough or names something it does not explain.',\n    inputSchema: SLUG_ARG,\n    annotations: { readOnlyHint: true },\n  },\n  (async ({ slug }: { slug: string }) => text(readGuide(slug))) as never,\n)\n\nserver.registerTool(\n  'search_guides',\n  {\n    title: 'Search the guides',\n    description: 'Every line in the guides that mentions a word or phrase, with the guide it is in. Use it to find which guide covers something before reading it.',\n    inputSchema: PHRASE_ARG,\n    annotations: { readOnlyHint: true },\n  },\n  (async ({ phrase }: { phrase: string }) => text(searchGuides(phrase))) as never,\n)\n\nawait server.connect(new StdioServerTransport())\n"]}

package/dist/recipes.js

@@ -342,20 +342,40 @@ export default function Page() {
 
 Reach for this first. It is the thing RSC is for.
 
-**When the BROWSER decides to refetch** — a filter, a poll, a refresh — that is
-a cache library's job and this package does not ship one:
+**When the BROWSER decides to refetch** — a filter, another page, a refresh —
+call fetchQuery. It is a plain async function that returns the typed answer;
+NO library is needed:
 
+\`\`\`tsx
+const [listings, setListings] = useState(initial)      // the server-rendered value
+const [pending, start] = useTransition()
+const show = (kind) => start(async () => setListings(await fetchQuery(getListings, [kind])))
+\`\`\`
+Works in an onClick, onSubmit, useEffect - anywhere in the browser.
+
+**When you want CACHING** (stale-while-revalidate, dedupe, offline), hand the
+same call to the library that holds the answer; this package ships none:
 \`\`\`tsx
 useQuery({ queryKey: ['posts', kind], queryFn: () => fetchQuery(getPosts, [kind]) })
 useSWR(['posts', kind], () => fetchQuery(getPosts, [kind]))
 \`\`\`
-
-\`fetchQuery\` sends the read as a GET and goes to the server every time, which
-is what a fetcher needs — staleness and revalidation belong to the library
-holding the answer. Do not add a cache on top of it.
+fetchQuery sends the read as a GET and goes to the server every time, which
+is what a fetcher needs. It will never cache, dedupe or batch: a client
+cache is the library's job, and a batch would lose the per-read cache key a
+GET has. The ladder, most reads stopping on the first rung:
+  1. the value now: fetchQuery + setState
+  2. survive a reload / let a CDN serve it: query(fn, { cache: 'public', maxAge })
+     - HTTP caching, no code in the page
+  3. staleness, background refresh, optimistic updates, shared across
+     components: TanStack or SWR with fetchQuery as the fetcher
+Do not add a cache on top of it, and do not install TanStack for a single
+button that reads once.
 
 Keep the arrow: TanStack calls a bare \`queryFn\` with its own context, and a
-server function serialises whatever it is handed.`,
+server function serialises whatever it is handed.
+
+A value that keeps CHANGING while someone watches - polling, SSE, realtime -
+is how_to live-data, not this.`,
     },
     {
         topic: 'suspense',
@@ -511,22 +531,30 @@ page that is 82 kB because of one <Link> is fine.`,
         body: `\`src/app/**/route.ts\`, one export per method:
 
 \`\`\`ts title="src/app/api/posts/[id]/route.ts"
+import type { RouteContext } from '@rsc-kit/core/route-schema'
+
 export const params = z.object({ id: z.coerce.number().int() })
 export const body = z.object({ title: z.string().min(1) })
 
-export async function GET(request: Request, { params }) {
+export async function GET(request: Request, { params }: RouteContext<typeof params>) {
   const { id } = await params
 
   return Response.json(await findPost(id))
 }
 
-export async function POST(request: Request, { params, body }) {
+export async function POST(request: Request, { params, body }: RouteContext<typeof params, never, typeof body>) {
   const { title } = await body
 
   return Response.json(await createPost(title), { status: 201 })
 }
 \`\`\`
 
+TYPE THE CONTEXT: RouteContext<'/api/items/[id]'> types params from the
+route's segments (the pattern is checked against the routes the build found);
+RouteContext<typeof params> from a schema. Every field is a PROMISE - a sync
+params.id is a compile error, never a route that 404s. Do NOT hand-write
+{ params: { id: string } }.
+
 A real \`Request\` in, a real \`Response\` out. \`params\`, \`searchParams\` and
 \`body\` are awaited, the same way a page's props are.
 
@@ -747,13 +775,15 @@ IMPORTS
   useParams()                  -> the page's params prop, passed down
   cookies(), headers()         -> same names, from @rsc-kit/core/request
   redirect() / notFound()      -> @rsc-kit/core/redirect / @rsc-kit/core/not-found
-  revalidatePath/Tag           -> revalidate('tag') on a section() - targeted, rides back with the action
+  revalidatePath/Tag           -> revalidate('name') on a section() - targeted, rides back with the action; the
+                                  name is typed to the sections and slots the build found
   Metadata                     -> @rsc-kit/core/metadata (metadataBase, openGraph, twitter, icons as-is)
   app/robots.ts, app/sitemap.ts -> the same files and shapes; app/llms.ts beside them (how_to seo-files)
+  middleware.ts subdomain rewrite -> nothing: a host is a route segment (how_to domains)
   next/font                    -> Fontsource (how_to fonts)
   next/image                   -> unpic or vite-imagetools (how_to images)
   next/script                  -> a <script> tag (how_to scripts)
-  NEXT_PUBLIC_*                -> VITE_* via import.meta.env; server vars stay process.env
+  NEXT_PUBLIC_*                -> PUBLIC_* in src/env.ts (how_to env); server vars typed there too
   next-safe-action             -> createActionClient() (how_to action-client); returnValidationErrors -> return fieldErrors({...})
   cache from 'react'           -> cache from @rsc-kit/core/cache: React's dedupes only inside a render; this one
                                   spans the request (guards, actions, api routes). The build names files still on React's
@@ -767,12 +797,18 @@ DIFFERENT ON PURPOSE
   It does not run for actions - the check goes in the action.
 - Actions return failures ({ validationErrors }, { serverError }), not throw.
 - No image optimizer, no opengraph-image.tsx - put opengraph-image.png in src/app.
-- Tests need no browser: createTestApp() is the deployed handler.
+- Tests need no browser: createTestApp() is the deployed handler. It builds
+  with the project's own build script on the runtime the tests run under.
 - A component library (base-ui, Radix) imports as it did, from server
   components too. A shadcn-style components/ui/ folder keeps "use client" at
   the top of each file, as shipped; without it the server evaluates the
   library's internals for nothing.
 
+SCAFFOLD FLAGS: --host=bun|node|worker --validation=zod|valibot|arktype|none
+--env/--no-env (typed env vars via @t3-oss/env-core in src/env.ts, in the
+chosen library; server vars never reach the browser, PUBLIC_ prefix for ones
+that may). Pick the library the Next app already uses.
+
 ORDER: scaffold -> copy src/app -> fix imports -> build (it typechecks first,
 so a Link to a route that does not exist fails here) and READ the output: a
 route that is not ○ names what streams and from which component (a cookies()
@@ -870,18 +906,331 @@ export default function llms(): MetadataRoute.Llms {
 A relative url is made absolute with the root layout's metadataBase; without
 one it is a build error. Any of them may return a string, served as written.
 
-Each becomes an api route, so: one that reads nothing per request (the
-database is fine) is stored at build and served from the file; one that reads
-cookies() or awaits connection() runs per request. No middleware runs for
+NO sitemap.ts? The build writes /sitemap.xml itself: every stored page and
+every generateStaticParams url, lastModified = the build, minus guarded
+routes (middleware.ts above them), failed pages and not-found. Needs the root
+layout's metadataBase. Write sitemap.ts only when you need urls the build
+cannot see or per-url changeFrequency/priority.
+
+HOW FRESH - the function decides, the same rule every route follows:
+  write nothing                        -> the build's own sitemap, stored; fresh every deploy
+  sitemap.ts that reads the database   -> stored at build (○); fresh every deploy
+  sitemap.ts that awaits connection()  -> rendered per request (ƒ); fresh every crawl
+\`\`\`ts
+export default async function sitemap() {
+  await connection()   // from '@rsc-kit/core/request' - per request, like a page
+  return (await db.post.findMany()).map((p) => ({ url: \`/blog/\${p.slug}\`, lastModified: p.updatedAt }))
+}
+\`\`\`
+Reading the database at build is fine; the REQUEST makes it dynamic, not the
+data. Same for robots.ts and llms.ts. No middleware runs for
 them - a root guard must not 401 the crawler. The url is typed
 (route('/sitemap.xml')).
 
 A file as written beside the root layout is served at the root as it is:
 robots.txt, sitemap.xml, sitemap-*.xml, llms.txt, llms-full.txt, humans.txt,
 security.txt, ads.txt. A file and a function for the same url is a build
-error. Do NOT put these in public/ and do NOT write a route.ts for them.
+error. Do NOT put these in public/ and do NOT write a middleware.ts for them.
 
 Full guide: read_guide({ slug: 'seo-files' }).`,
+    },
+    {
+        topic: 'domains',
+        summary: 'Subdomains and custom domains as route segments - admin.example.com reaches app/admin, a tenant host binds [domain], no rewrite',
+        body: `A request from a host that is not the site's own is matched with the host
+in FRONT of the path. The site's own hosts: the root layout's metadataBase,
+www. of it, and rscKit({ hosts: [...] }) - which is ONLY for a name that is
+neither the apex nor a subdomain of it (a staging/internal name, a second
+brand domain); a normal setup needs no config beyond metadataBase. localhost
+and ips are always own.
+
+  example.com/admin           -> /admin              app/admin/page.tsx
+  admin.example.com/          -> /admin              the same file (subdomain of an own host = its label)
+  acme.example.com/settings   -> /acme/settings      app/[domain]/settings/page.tsx, domain "acme"
+  acme.com/settings           -> /acme.com/settings  the same file, domain "acme.com" (other host = whole host)
+
+The visitor's url is untouched; only the match changes. A top-level [domain]
+binds ONLY from a host, never from a path: example.com/nope is a 404, not a
+tenant called "nope". Otherwise [domain] is an ordinary dynamic segment: params.domain in every page/layout under it, typed
+route('/[domain]/settings', { domain }), loading/error files as usual. A
+directory named for a host (app/admin/) wins over [domain].
+
+\`\`\`tsx
+// src/app/[domain]/layout.tsx
+export default async function TenantLayout({ params, children }) {
+  const { domain } = await params
+  const tenant = await tenantByDomain(domain)   // "acme" or "acme.com", as stored
+  if (!tenant) notFound()
+  return <TenantProvider tenant={tenant}>{children}</TenantProvider>
+}
+// src/app/[domain]/page.tsx - domains in a database: list them, they are stored at build
+export async function generateStaticParams() {
+  return (await db.tenant.findMany()).map((t) => ({ domain: t.domain }))
+}
+\`\`\`
+
+Only when a route could answer it (a top-level [domain] directory, or one
+named for the host); otherwise the host is the site's own. Keep metadataBase as
+the production host: localhost and ips are always own, so dev routes by path.
+To try a tenant locally: curl -H 'X-Forwarded-Host: acme.example.com'
+http://localhost:3000/ (or /etc/hosts). Behind a proxy the
+host is X-Forwarded-Host, then Host. Not for a static export (a file server
+sees no host). Do NOT write a middleware rewrite, do NOT
+read the host in every page - the segment already is the host. The root layout
+needs metadataBase (or rscKit({ hosts })) or every host is the site's own.
+
+Full guide: read_guide({ slug: 'domains' }).`,
+    },
+    {
+        topic: 'identify',
+        summary: 'What a response says about itself - X-RSC-Kit (how it was served, always) and X-Powered-By + a generator tag (what built it, off with identify: false)',
+        body: `Every response carries X-RSC-Kit: stored | rendered | shell - a page from a
+file the build wrote, rendered for this visitor, or a stored shell with its
+holes rendered now. The header to read when a page is slower than expected
+(like X-Nextjs-Cache); a CDN rule or health check can key on it. Names no
+product; always sent.
+
+By default a response also says what built it: X-Powered-By: rsc-kit and
+<meta name="generator" content="rsc-kit"> in every document (BuiltWith,
+Wappalyzer). The NAME only, never the version - a version in every response
+is what a vulnerability scanner filters on.
+
+rscKit({ identify: false }) turns off the name (header and tag) for a policy
+that strips framework identifiers; X-RSC-Kit stays. Do not strip X-RSC-Kit
+at the proxy - it is what tells you whether a stored page was served.
+
+Full guide: read_guide({ slug: 'response-headers' }).`,
+    },
+    {
+        topic: 'backend',
+        summary: 'BAP (Backend-Answered Pages): a Laravel, Go or other backend behind the renderer - rpc() reaches it, middleware.ts names its middleware, app/Rsc/Actions are its server actions',
+        body: `The model is a BAP - Backend-Answered Pages: a page rendered in front of
+the backend rather than by it (MPA: backend renders; SPA: browser renders and
+calls an API; BAP: a renderer on the server renders and calls the backend
+over loopback). The backend is the part that is not a page - models, session,
+auth, policies, jobs - answering one private endpoint, and it keeps every
+route of its own. The whole model, and how to build for it:
+read_guide({ slug: 'backend-answered-pages' }).
+
+Go: in a Go module, rsc-kit init sees go.mod, writes the JS half and .env
+(RSC_BACKEND + a generated secret) and prints the Go wiring; go get
+github.com/rsc-kit/go. A new app: bun create rsc-kit --backend=<url>.
+
+A backend in another language answers that ONE endpoint, POST /__rsc/host-call,
+and the renderer wires itself from two variables in .env: RSC_BACKEND (a
+Laravel app's APP_URL counts) and RSC_HOST_CALL_SECRET. Both or neither.
+
+Laravel: composer require rsc-kit/laravel, then php artisan rsc:install. It
+runs rsc-kit init, which writes ONE vite.config.ts (laravel-vite-plugin is
+moved aside - the renderer owns the frontend). Source is resources/js (the route tree is resources/js/app).
+
+Reach PHP from a server component - rpc() is a global, typed in
+.rsc-kit/rsc-env.d.ts, server render only:
+
+  // app/Rsc/Orders.php: public function recent(int $limit): array
+  const orders = await rpc<Order[]>('Orders.recent', 5)
+
+The call runs AS THE VISITOR (their cookie is forwarded; auth()->user() is
+them). Refuse with attributes: #[Authenticated], #[Can('update', Order::class)],
+#[Middleware('throttle:60,1')]. A ValidationException lands on the form as
+validationErrors; Authentication/Authorization exceptions answer 401/403.
+
+Guard a route in Laravel's vocabulary, no route declared in PHP:
+
+  // resources/js/app/admin/middleware.ts
+  export const middleware = ['auth', 'verified', 'can:update,post']
+
+Server actions are classes in app/Rsc/Actions; \`php artisan
+rsc:action-manifest\` (already in the dev/build scripts) writes the map and
+the build writes server-actions.generated.ts beside the app - import
+ordersCancel from it in a client component. Rsc::revalidate('orders') in the
+action returns the re-rendered region with the answer.
+
+php artisan serve is one worker, which deadlocks the proxy - unless
+PHP_CLI_SERVER_WORKERS=4 in .env AND serve --no-reload (Laravel ignores
+the variable otherwise). Herd, Valet, FPM, Octane are fine as they are. Production: put the renderer in front (bun
+.output/server/index.mjs with the app's .env), restrict /__rsc/host-call at
+the web server.
+
+Any other language implements the same endpoint - request { function, args },
+reply { result | validationErrors | unauthenticated | unauthorized | redirect
+| error, revalidate }, answers '__rsc.middleware' with true or a refusal, and
+a batch { calls: [...] } with { replies: [{ status, ...reply }] } in order.
+Calls issued in the same render tick travel as one batch, so parallel reads
+are one backend request; the renderer falls back to single calls for a
+backend without batches.
+
+Full guides: read_guide({ slug: 'backend-answered-pages' }), read_guide({ slug: 'laravel' }), read_guide({ slug: 'go' }), read_guide({ slug: 'your-own-backend' }).`,
+    },
+    {
+        topic: 'startup',
+        summary: 'Once-per-process setup - src/instrumentation.ts is imported before any page and its register() awaited before the first request',
+        body: `Setup that belongs to the process - validating env, configuring a shared
+package, warming a connection - goes in src/instrumentation.ts. Do NOT import
+a bootstrap module from pages to get the same effect; it depends on nobody
+forgetting, and the failure is a page throwing "not configured" for whoever
+reaches it first.
+
+  // src/instrumentation.ts
+  import './env'                       // refuses at import -> server fails at startup
+  export async function register() {   // optional; the first render waits for it
+    await db.connect()
+  }
+
+The generated entry imports this file FIRST, so a package configured here is
+configured before any page module evaluates. register() is awaited by every
+entry point (server, dev, prerender, middleware, actions, api routes), once
+per process. On a server it runs at startup and a failure exits the process;
+on a Worker it runs at the isolate's first request.
+
+Worker rule: read bindings INSIDE register(), not at the top of the module -
+process.env is empty until the first request arrives.
+
+A scaffolded app with env validation already has this file importing ./env.
+Build machines without production variables: SKIP_ENV_VALIDATION=1.
+
+Never NODE_ENV in a .env: Vite sets it (development under vite, production
+under vite build) and a .env line overrides it for the build, which then
+compiles pages against React's dev JSX runtime (jsxDEV) and every route
+fails with React's opaque "message omitted in production builds". The build
+refuses this and names the file:line. A plugin cannot override it (Vite
+applies the .env value after plugins run), so remove the line - other tools
+that want it keep it in their own .env.
+
+Full guide: read_guide({ slug: 'instrumentation' }).`,
+    },
+    {
+        topic: 'bun',
+        summary: 'Running on Bun - Vite on Bun\'s runtime (bun --bun vite), native deps external (serverExternalPackages), and the gotchas that are Bun\'s not ours',
+        body: `The vite bin has a node shebang: \`bun run dev\` alone starts Vite - dev
+server, build, prerender - under NODE, and an app importing 'bun' or
+'bun:sqlite' fails at first render with "Cannot find package 'bun'". Scripts
+on a Bun app: dev "bun --bun vite", build "bun --bun vite build". createTestApp
+runs the project's build script on the runtime the tests use.
+
+Native dependencies (sharp, bcrypt, better-sqlite3, @prisma/client, puppeteer,
+...) are external to the server bundles by default; Nitro traces them into
+.output/server/node_modules with their binaries. Add one:
+rscKit({ serverExternalPackages: ['@acme/native'] }). Same as Next's option.
+
+Bun's, not the framework's: bun test loads the package .env (use
+--env-file=/dev/null to isolate); Stripe's constructEvent throws on Bun
+(no sync WebCrypto) - use constructEventAsync; Bun's pg puts SQLSTATE in
+errno where Node's pg uses code.
+
+Never NODE_ENV in a .env (the build refuses it, naming the line). Build
+machines without secrets: SKIP_ENV_VALIDATION=1.
+
+Full guide: read_guide({ slug: 'bun' }).`,
+    },
+    {
+        topic: 'env',
+        summary: 'Typed environment variables - src/env.ts with @t3-oss/env-core in the app\'s validation library; refused at startup by name. Never NODE_ENV in .env',
+        body: `A scaffolded app has src/env.ts when it said yes to typed environment
+variables (create-rsc-kit --env, with --validation=zod|valibot|arktype). To
+add it to an app without one: install @t3-oss/env-core and write the same file.
+
+\`\`\`ts
+// src/env.ts
+import * as z from 'zod'   // or valibot / arktype - any Standard Schema library
+import { createEnv } from '@t3-oss/env-core'
+
+export const env = createEnv({
+  server: {
+    NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+    DATABASE_URL: z.url(),
+    SESSION_SECRET: z.string().min(1),
+  },
+  clientPrefix: 'PUBLIC_',
+  client: { PUBLIC_SITE_URL: z.url() },
+  runtimeEnv: { ...process.env, ...import.meta.env },
+  emptyStringAsUndefined: true,
+})
+\`\`\`
+
+Read env.DATABASE_URL, never process.env.DATABASE_URL: the first is typed and
+was checked at startup (a missing or malformed one fails then, with its name),
+the second is string | undefined. A server variable never reaches the browser;
+a browser-readable one MUST start with PUBLIC_ and is read from import.meta.env
+(Vite), which is why runtimeEnv merges both. Commit .env.example, not .env.
+
+Next: NEXT_PUBLIC_* becomes PUBLIC_*; @t3-oss/env-nextjs becomes
+@t3-oss/env-core with runtimeEnv as above (env-nextjs's experimental__runtimeEnv
+is not needed).`,
+    },
+    {
+        topic: 'live-data',
+        summary: 'A value that keeps changing - realtime, live updates: usePolling over a query, or server-sent events (SSE, streaming from a middleware.ts generator) with useEvents - both feed TanStack, SWR or setState',
+        body: `Neither is part of query() - a query answers once and is cacheable.
+
+POLLING - start here when you have no change feed yet. Reuses the query,
+goes through its Cache-Control (a CDN collapses many tabs into one origin
+read per interval), pauses when the tab is hidden, never overlaps two reads.
+\`\`\`tsx
+import { usePolling } from '@rsc-kit/core/usePolling'
+const { data, status, refresh } = usePolling(() => fetchQuery(getSeats), { every: 2_000 })
+\`\`\`
+UNTIL IT SETTLES - a job that ends. until(data) says the last read; onSettled
+fires once on it. The result is the DATA; what to
+do on settling is the page's choice:
+  // a server-rendered list, some jobs still running: re-render through the server
+  usePolling(() => fetchQuery(jobStatus, [id]), { every: 2_000, enabled: !isTerminal(job), until: isTerminal, onSettled: () => refresh('page') })
+  // the page that owns the job's state machine: the value in hand
+  const { data, status } = usePolling(read, { every: 1_500, until: isTerminal, onSettled: (f) => dispatch(f.status) })
+Settled = stopped until refresh() or the inputs change. status: 'reading' |
+'paused' | 'settled' | 'idle'.
+
+SERVER-SENT EVENTS - when something can push. Better per update (bytes only
+on change, instant), but holds a connection per open tab (fine on Bun/Node,
+a limit on Workers or a small container), is uncacheable, and needs a source
+of change to yield from - a generator that polls the DB itself just moved the
+polling. An ordinary route.ts: beside its pages, runs middleware.ts above it.
+\`\`\`ts
+// src/app/api/orders/[id]/events/route.ts
+import { events, named } from '@rsc-kit/core/events'
+export const GET = events(async function* ({ params, signal }) {
+  const { id } = await params
+  for await (const status of orderStatus(id, { signal })) yield { status }
+  // yield named('paid', order, { id: order.id }) names a message / gives an id
+})
+\`\`\`
+\`\`\`tsx
+import { useEvents } from '@rsc-kit/core/useEvents'
+const { latest, all, status, close } = useEvents<Status>(\`/api/orders/\${id}/events\`)
+// <Status> is the message type the route yields; a url infers nothing, so
+// without it latest is unknown. Declare the type beside the route, import both sides.
+\`\`\`
+events() frames JSON, sends a keepalive, sets text/event-stream + no-store,
+ends the generator on disconnect (signal). EventSource reconnects itself and
+resumes with Last-Event-ID when you yielded ids.
+
+NO LIBRARY NEEDED. Both hooks ARE state: read data (polling) or latest
+(events) and render it. Neither needs TanStack or SWR.
+  const { latest } = useEvents<Status>(url); const current = latest ?? initial   // the server value until the first message
+WITH A STORE - when the value already lives somewhere, hand every value on so
+that stays the truth: a useState, a reducer, or a cache library:
+  useEvents<Order>(url, { onMessage: setOrder })                                            // useState
+  useEvents<Order>(url, { onMessage: (m) => dispatch({ type: 'update', m }) })              // reducer
+  useEvents<Order>(url, { onMessage: (m) => queryClient.setQueryData(['order', id], m) })  // TanStack
+  useEvents<Order>(url, { onMessage: (m) => mutate(['order', id], m, false) })             // SWR
+  usePolling(read, { every, onData: setSeats })
+STABLE CALLBACKS: a callback a timer/subscription/listener calls that must see
+the latest props is useEffectEvent from React (19.2+), never a ref assigned
+each render, and never in a dependency array. Both hooks are built on it.
+
+ERRORS: both hooks expose error as state AND fire onError - a failed poll read
+(the next interval still reads) or a dropped stream (EventSource reconnects
+itself). Use onError for a toast/log; do NOT watch error in a useEffect.
+usePolling's onError gets (error, { failures }) - failed reads in a row, reset
+by a success - so toast on the third, not the first.
+fetchQuery(query, args) types args from the query: fetchQuery(getSeats) for a
+query that takes nothing, fetchQuery(status, [{ id }]) refused if the query's
+input has no id.
+Do NOT put a stream on query() or on a server action, and do NOT poll from
+inside an events() generator.
+
+Full guides: read_guide({ slug: 'queries' }) for polling, read_guide({ slug:
+'api-routes' }) for the streaming route.`,
     },
     {
         topic: 'images',
@@ -1033,7 +1382,8 @@ export function howTo(topic) {
         // A near miss is common and worth answering rather than refusing: someone
         // asks for "form" or "queries" and means the obvious thing.
         RECIPES.find((r) => r.topic.startsWith(wanted) || wanted.startsWith(r.topic)) ??
-        RECIPES.find((r) => r.summary.toLowerCase().includes(wanted));
+        // The summary is prose, so a multi-word ask is matched with its spaces back.
+        RECIPES.find((r) => r.summary.toLowerCase().replace(/[-\s]+/g, ' ').includes(wanted.replace(/-/g, ' ')));
     if (!found)
         return `No topic "${topic}".\n\n${listTopics()}`;
     return `# ${found.topic} — ${found.summary}\n\n${found.body}`;