@rsc-kit/mcp 0.14.0 → 0.15.0

package/dist/answers.d.ts

@@ -19,3 +19,10 @@ export declare function explainRoute(report: BuildReport, url: string, builtAt:
 export declare function whatIsDynamic(report: BuildReport, builtAt: Date, now: number): string;
 /** The heaviest routes, for the question that follows the size column. */
 export declare function heaviestRoutes(report: BuildReport, builtAt: Date, now: number, top?: number): string;
+/**
+ * The actions, and the one fact about each that nothing else states: whether
+ * anything checks who calls it. A bare "use server" export runs with no
+ * middleware; an agent adding a delete button needs to know that before it
+ * trusts the id it was handed.
+ */
+export declare function actionLines(report: BuildReport): string[];

package/dist/answers.js

@@ -33,6 +33,11 @@ export function listRoutes(report, builtAt, now) {
         `${report.routes.length} routes and ${report.apis.length} api routes ${asOf(builtAt, now)}`,
         '',
     ];
+    // First, before the table, because it changes what the table means: these
+    // rows are from a build that did not finish, and nothing below is deployed.
+    if (report.totals.failed > 0) {
+        lines.unshift(`THE LAST BUILD FAILED: ${report.totals.failed} route${report.totals.failed === 1 ? '' : 's'} refused. Each one's line below says what to change. Fix it and build again.`, '');
+    }
     for (const route of report.routes) {
         const size = route.clientJs === null ? '' : `  ${kb(route.clientJs)}`;
         lines.push(`${route.url}${size}  — ${MEANING[route.type] ?? route.type}`);
@@ -49,6 +54,7 @@ export function listRoutes(report, builtAt, now) {
     }
     lines.push('', `${report.totals.static} static, ${report.totals.partial} partial prerender, ${report.totals.dynamic} dynamic` +
         (report.totals.failed ? `, ${report.totals.failed} failed` : ''));
+    lines.push('', ...actionLines(report));
     return lines.join('\n');
 }
 function isPage(route) {
@@ -121,4 +127,24 @@ export function heaviestRoutes(report, builtAt, now, top = 10) {
         'which every route pays for.',
     ].join('\n');
 }
+/**
+ * The actions, and the one fact about each that nothing else states: whether
+ * anything checks who calls it. A bare "use server" export runs with no
+ * middleware; an agent adding a delete button needs to know that before it
+ * trusts the id it was handed.
+ */
+export function actionLines(report) {
+    const actions = report.actions;
+    if (!actions)
+        return ['actions: not audited by this build (older @rsc-kit/core)'];
+    if (actions.length === 0)
+        return ['actions: none'];
+    const bare = actions.filter((a) => !a.client);
+    const lines = [`actions: ${actions.length}, ${actions.length - bare.length} built from an action client`];
+    if (bare.length > 0) {
+        lines.push(`${bare.length} run NO middleware — nothing checks who calls them: ` +
+            bare.map((a) => `${a.name}${a.query ? ' (query)' : ''} in ${a.file}`).join(', '), 'Fine for a public action. For anything else, build it from an action client so the check cannot be forgotten — how_to({ topic: "action-client" }).');
+    }
+    return lines;
+}
 //# sourceMappingURL=answers.js.map

package/dist/answers.js.map

@@ -1 +1 @@
-{"version":3,"file":"answers.js","sourceRoot":"","sources":["../src/answers.ts"],"names":[],"mappings":"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","sourcesContent":["// The answers, as text, with no protocol in them.\n//\n// Separated from the server so they can be tested by calling them, and so the\n// wording is reviewable in one place. An agent reads these as prose and acts on\n// them, so a vague sentence here becomes a wrong edit somewhere else — \"this\n// route is dynamic\" invites a fix, \"this route reads cookies, which is why\"\n// invites the right one.\n\nimport type { BuildReport, ReportedApiRoute, ReportedRoute } from './report.js'\nimport { MEANING, routeFor } from './report.js'\n\nconst kb = (bytes: number) => `${bytes < 10_000 ? (bytes / 1000).toFixed(1) : Math.round(bytes / 1000)} kB`\n\nconst age = (builtAt: Date, now: number): string => {\n  const minutes = Math.round((now - builtAt.getTime()) / 60_000)\n\n  if (minutes < 1) return 'just now'\n  if (minutes < 60) return `${minutes} minute${minutes === 1 ? '' : 's'} ago`\n\n  const hours = Math.round(minutes / 60)\n\n  if (hours < 24) return `${hours} hour${hours === 1 ? '' : 's'} ago`\n\n  return `${Math.round(hours / 24)} days ago`\n}\n\n/**\n * Every answer says how old it is.\n *\n * The one way this server misleads is by being confidently stale: it reports\n * the last build, and the file on disk may have changed since. Saying so on\n * every answer is cheaper than being wrong once.\n */\nexport function asOf(builtAt: Date, now: number): string {\n  return `(from the last build, ${age(builtAt, now)})`\n}\n\nexport function listRoutes(report: BuildReport, builtAt: Date, now: number): string {\n  const lines = [\n    `${report.routes.length} routes and ${report.apis.length} api routes ${asOf(builtAt, now)}`,\n    '',\n  ]\n\n  for (const route of report.routes) {\n    const size = route.clientJs === null ? '' : `  ${kb(route.clientJs)}`\n\n    lines.push(`${route.url}${size}  — ${MEANING[route.type] ?? route.type}`)\n\n    if (route.reason) lines.push(`    ${route.reason}`)\n  }\n\n  if (report.apis.length) {\n    lines.push('', 'api routes:')\n\n    for (const api of report.apis) {\n      lines.push(`${api.url}  — ${MEANING[api.type] ?? api.type}`)\n\n      if (api.reason) lines.push(`    ${api.reason}`)\n    }\n  }\n\n  lines.push(\n    '',\n    `${report.totals.static} static, ${report.totals.partial} partial prerender, ${report.totals.dynamic} dynamic` +\n      (report.totals.failed ? `, ${report.totals.failed} failed` : ''),\n  )\n\n  return lines.join('\\n')\n}\n\nfunction isPage(route: ReportedRoute | ReportedApiRoute): route is ReportedRoute {\n  return 'component' in route\n}\n\nexport function explainRoute(\n  report: BuildReport,\n  url: string,\n  builtAt: Date,\n  now: number,\n): string {\n  const route = routeFor(report, url)\n\n  if (!route) {\n    // The urls, not just \"not found\": the caller has a url that does not exist,\n    // and the most useful next thing is the ones that do.\n    return (\n      `No route for ${url} ${asOf(builtAt, now)}.\\n\\n` +\n      'Known urls:\\n' +\n      [...report.routes, ...report.apis].map((r) => `  ${r.url}`).join('\\n')\n    )\n  }\n\n  const lines = [`${route.url} — ${MEANING[route.type] ?? route.type} ${asOf(builtAt, now)}`]\n\n  if (isPage(route)) {\n    lines.push(`Rendered by ${route.component}.`)\n\n    if (route.clientJs !== null) {\n      lines.push(`Ships ${kb(route.clientJs)} of javascript, gzipped.`)\n    }\n  }\n\n  if (route.reason) lines.push('', `Why it is not stored whole: ${route.reason}`)\n\n  if (isPage(route) && route.warning) lines.push('', `Warning: ${route.warning}`)\n\n  if (route.type === 'frozen') {\n    lines.push(\n      '',\n      'Nothing to fix. It is rendered once at build time and served as a file.',\n    )\n  }\n\n  return lines.join('\\n')\n}\n\n/**\n * The routes that are not stored, and why.\n *\n * The question behind most of the others — someone asking \"why is my site\n * slow\" wants this list, not the whole table. Routes that are fine are left\n * out entirely rather than listed and dismissed.\n */\nexport function whatIsDynamic(report: BuildReport, builtAt: Date, now: number): string {\n  const pages = report.routes.filter((r) => r.type !== 'frozen')\n  const apis = report.apis.filter((a) => a.type !== 'frozen')\n\n  if (pages.length === 0 && apis.length === 0) {\n    return `Every route is stored at build time ${asOf(builtAt, now)}. Nothing renders per request.`\n  }\n\n  const lines = [\n    `${pages.length + apis.length} of ${report.routes.length + report.apis.length} routes render per request ${asOf(builtAt, now)}:`,\n    '',\n  ]\n\n  for (const route of [...pages, ...apis]) {\n    lines.push(`${route.url} — ${route.reason ?? MEANING[route.type] ?? route.type}`)\n  }\n\n  lines.push(\n    '',\n    'Reading the request is what makes a route dynamic: cookies(), headers(), searchParams(),',\n    'or connection() said deliberately. That is usually correct — a page whose content depends',\n    'on who is asking cannot be one stored file. Change it only if the read was accidental.',\n  )\n\n  return lines.join('\\n')\n}\n\n/** The heaviest routes, for the question that follows the size column. */\nexport function heaviestRoutes(report: BuildReport, builtAt: Date, now: number, top = 10): string {\n  const weighed = report.routes\n    .filter((r) => r.clientJs !== null)\n    .sort((a, b) => (b.clientJs ?? 0) - (a.clientJs ?? 0))\n\n  if (weighed.length === 0) {\n    return `No route shipped measurable javascript ${asOf(builtAt, now)}.`\n  }\n\n  const lightest = weighed[weighed.length - 1].clientJs ?? 0\n\n  return [\n    `Heaviest routes ${asOf(builtAt, now)}:`,\n    '',\n    ...weighed.slice(0, top).map((r) => `${kb(r.clientJs ?? 0)}  ${r.url}`),\n    '',\n    `The lightest route ships ${kb(lightest)}, so the difference between them is`,\n    `${kb((weighed[0].clientJs ?? 0) - lightest)} of client components — most of the rest is React itself,`,\n    'which every route pays for.',\n  ].join('\\n')\n}\n"]}
+{"version":3,"file":"answers.js","sourceRoot":"","sources":["../src/answers.ts"],"names":[],"mappings":"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","sourcesContent":["// The answers, as text, with no protocol in them.\n//\n// Separated from the server so they can be tested by calling them, and so the\n// wording is reviewable in one place. An agent reads these as prose and acts on\n// them, so a vague sentence here becomes a wrong edit somewhere else — \"this\n// route is dynamic\" invites a fix, \"this route reads cookies, which is why\"\n// invites the right one.\n\nimport type { BuildReport, ReportedApiRoute, ReportedRoute } from './report.js'\nimport { MEANING, routeFor } from './report.js'\n\nconst kb = (bytes: number) => `${bytes < 10_000 ? (bytes / 1000).toFixed(1) : Math.round(bytes / 1000)} kB`\n\nconst age = (builtAt: Date, now: number): string => {\n  const minutes = Math.round((now - builtAt.getTime()) / 60_000)\n\n  if (minutes < 1) return 'just now'\n  if (minutes < 60) return `${minutes} minute${minutes === 1 ? '' : 's'} ago`\n\n  const hours = Math.round(minutes / 60)\n\n  if (hours < 24) return `${hours} hour${hours === 1 ? '' : 's'} ago`\n\n  return `${Math.round(hours / 24)} days ago`\n}\n\n/**\n * Every answer says how old it is.\n *\n * The one way this server misleads is by being confidently stale: it reports\n * the last build, and the file on disk may have changed since. Saying so on\n * every answer is cheaper than being wrong once.\n */\nexport function asOf(builtAt: Date, now: number): string {\n  return `(from the last build, ${age(builtAt, now)})`\n}\n\nexport function listRoutes(report: BuildReport, builtAt: Date, now: number): string {\n  const lines = [\n    `${report.routes.length} routes and ${report.apis.length} api routes ${asOf(builtAt, now)}`,\n    '',\n  ]\n\n  // First, before the table, because it changes what the table means: these\n  // rows are from a build that did not finish, and nothing below is deployed.\n  if (report.totals.failed > 0) {\n    lines.unshift(\n      `THE LAST BUILD FAILED: ${report.totals.failed} route${report.totals.failed === 1 ? '' : 's'} refused. Each one's line below says what to change. Fix it and build again.`,\n      '',\n    )\n  }\n\n  for (const route of report.routes) {\n    const size = route.clientJs === null ? '' : `  ${kb(route.clientJs)}`\n\n    lines.push(`${route.url}${size}  — ${MEANING[route.type] ?? route.type}`)\n\n    if (route.reason) lines.push(`    ${route.reason}`)\n  }\n\n  if (report.apis.length) {\n    lines.push('', 'api routes:')\n\n    for (const api of report.apis) {\n      lines.push(`${api.url}  — ${MEANING[api.type] ?? api.type}`)\n\n      if (api.reason) lines.push(`    ${api.reason}`)\n    }\n  }\n\n  lines.push(\n    '',\n    `${report.totals.static} static, ${report.totals.partial} partial prerender, ${report.totals.dynamic} dynamic` +\n      (report.totals.failed ? `, ${report.totals.failed} failed` : ''),\n  )\n\n  lines.push('', ...actionLines(report))\n\n  return lines.join('\\n')\n}\n\nfunction isPage(route: ReportedRoute | ReportedApiRoute): route is ReportedRoute {\n  return 'component' in route\n}\n\nexport function explainRoute(\n  report: BuildReport,\n  url: string,\n  builtAt: Date,\n  now: number,\n): string {\n  const route = routeFor(report, url)\n\n  if (!route) {\n    // The urls, not just \"not found\": the caller has a url that does not exist,\n    // and the most useful next thing is the ones that do.\n    return (\n      `No route for ${url} ${asOf(builtAt, now)}.\\n\\n` +\n      'Known urls:\\n' +\n      [...report.routes, ...report.apis].map((r) => `  ${r.url}`).join('\\n')\n    )\n  }\n\n  const lines = [`${route.url} — ${MEANING[route.type] ?? route.type} ${asOf(builtAt, now)}`]\n\n  if (isPage(route)) {\n    lines.push(`Rendered by ${route.component}.`)\n\n    if (route.clientJs !== null) {\n      lines.push(`Ships ${kb(route.clientJs)} of javascript, gzipped.`)\n    }\n  }\n\n  if (route.reason) lines.push('', `Why it is not stored whole: ${route.reason}`)\n\n  if (isPage(route) && route.warning) lines.push('', `Warning: ${route.warning}`)\n\n  if (route.type === 'frozen') {\n    lines.push(\n      '',\n      'Nothing to fix. It is rendered once at build time and served as a file.',\n    )\n  }\n\n  return lines.join('\\n')\n}\n\n/**\n * The routes that are not stored, and why.\n *\n * The question behind most of the others — someone asking \"why is my site\n * slow\" wants this list, not the whole table. Routes that are fine are left\n * out entirely rather than listed and dismissed.\n */\nexport function whatIsDynamic(report: BuildReport, builtAt: Date, now: number): string {\n  const pages = report.routes.filter((r) => r.type !== 'frozen')\n  const apis = report.apis.filter((a) => a.type !== 'frozen')\n\n  if (pages.length === 0 && apis.length === 0) {\n    return `Every route is stored at build time ${asOf(builtAt, now)}. Nothing renders per request.`\n  }\n\n  const lines = [\n    `${pages.length + apis.length} of ${report.routes.length + report.apis.length} routes render per request ${asOf(builtAt, now)}:`,\n    '',\n  ]\n\n  for (const route of [...pages, ...apis]) {\n    lines.push(`${route.url} — ${route.reason ?? MEANING[route.type] ?? route.type}`)\n  }\n\n  lines.push(\n    '',\n    'Reading the request is what makes a route dynamic: cookies(), headers(), searchParams(),',\n    'or connection() said deliberately. That is usually correct — a page whose content depends',\n    'on who is asking cannot be one stored file. Change it only if the read was accidental.',\n  )\n\n  return lines.join('\\n')\n}\n\n/** The heaviest routes, for the question that follows the size column. */\nexport function heaviestRoutes(report: BuildReport, builtAt: Date, now: number, top = 10): string {\n  const weighed = report.routes\n    .filter((r) => r.clientJs !== null)\n    .sort((a, b) => (b.clientJs ?? 0) - (a.clientJs ?? 0))\n\n  if (weighed.length === 0) {\n    return `No route shipped measurable javascript ${asOf(builtAt, now)}.`\n  }\n\n  const lightest = weighed[weighed.length - 1].clientJs ?? 0\n\n  return [\n    `Heaviest routes ${asOf(builtAt, now)}:`,\n    '',\n    ...weighed.slice(0, top).map((r) => `${kb(r.clientJs ?? 0)}  ${r.url}`),\n    '',\n    `The lightest route ships ${kb(lightest)}, so the difference between them is`,\n    `${kb((weighed[0].clientJs ?? 0) - lightest)} of client components — most of the rest is React itself,`,\n    'which every route pays for.',\n  ].join('\\n')\n}\n\n/**\n * The actions, and the one fact about each that nothing else states: whether\n * anything checks who calls it. A bare \"use server\" export runs with no\n * middleware; an agent adding a delete button needs to know that before it\n * trusts the id it was handed.\n */\nexport function actionLines(report: BuildReport): string[] {\n  const actions = report.actions\n\n  if (!actions) return ['actions: not audited by this build (older @rsc-kit/core)']\n  if (actions.length === 0) return ['actions: none']\n\n  const bare = actions.filter((a) => !a.client)\n  const lines = [`actions: ${actions.length}, ${actions.length - bare.length} built from an action client`]\n\n  if (bare.length > 0) {\n    lines.push(\n      `${bare.length} run NO middleware — nothing checks who calls them: ` +\n        bare.map((a) => `${a.name}${a.query ? ' (query)' : ''} in ${a.file}`).join(', '),\n      'Fine for a public action. For anything else, build it from an action client so the check cannot be forgotten — how_to({ topic: \"action-client\" }).',\n    )\n  }\n\n  return lines\n}\n"]}

package/dist/bundleGuides.d.ts

@@ -0,0 +1,22 @@
+export interface GuideEntry {
+    slug: string;
+    title: string;
+    description: string;
+}
+/** One guide's MDX as markdown, with the samples it names inlined. */
+export declare function toMarkdown(mdx: string, repoRoot: string): {
+    entry: Omit<GuideEntry, 'slug'>;
+    body: string;
+};
+/** Every guide under `from`, written as markdown into `into`, with an index. */
+export declare function bundleGuides(from: string, into: string, repoRoot: string): GuideEntry[];
+/** Where the bundled guides are, beside dist — or nowhere, before a build. */
+export declare function guidesDir(): string | null;
+export declare function listGuides(): string;
+export declare function readGuide(slug: string): string;
+/**
+ * Lines matching a phrase across every bundled guide, with the guide and a
+ * little context. A grep, deliberately - the guides are 250 KB and an agent
+ * asking "where is fieldErrors mentioned" wants the lines, not a ranking.
+ */
+export declare function searchGuides(phrase: string, limit?: number): string;

package/dist/bundleGuides.js

@@ -0,0 +1,130 @@
+// The guides, as files an agent can read without leaving its editor.
+//
+// how_to answers are short and opinionated, and they are copies — of the
+// guides at rsc-kit.dev, by hand, which is how a recipe once said <Form> worked
+// without javascript when it did not yet. The guides are the source. This
+// bundles them into the package at build time so read_guide answers with the
+// same text the site shows, and a recipe can point at the full version instead
+// of restating it.
+//
+// MDX to markdown is three edits: the frontmatter becomes a heading, the
+// component imports go, and <CodeFromFile> becomes the code it names — cut the
+// same way the site cuts it, region and all.
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { basename, extname, join } from 'node:path';
+const FRONTMATTER = /^---\n([\s\S]*?)\n---\n/;
+const COMPONENT_IMPORT = /^import .* from ["']@\/components\/.*["'];?\n/gm;
+const CODE_FROM_FILE = /<CodeFromFile\s+([^>]*?)\/>/g;
+function attribute(attrs, name) {
+    return new RegExp(`${name}="([^"]*)"`).exec(attrs)?.[1];
+}
+function frontmatterField(block, name) {
+    const match = new RegExp(`^${name}:\\s*(.*)$`, 'm').exec(block);
+    return (match?.[1] ?? '').trim().replace(/^["'](.*)["']$/, '$1');
+}
+/** The lines between `#region <name>` and its `#endregion`, dedented. */
+function region(source, name, file) {
+    const lines = source.split('\n');
+    const start = lines.findIndex((line) => new RegExp(`#region\\s+${name}\\b`).test(line));
+    if (start === -1)
+        throw new Error(`No region "${name}" in ${file}`);
+    const end = lines.findIndex((line, i) => i > start && /#endregion\b/.test(line));
+    if (end === -1)
+        throw new Error(`Region "${name}" in ${file} is never closed`);
+    const body = lines.slice(start + 1, end).filter((line) => !/#(region|endregion)\b/.test(line));
+    const indent = Math.min(...body.filter((l) => l.trim()).map((l) => /^\s*/.exec(l)[0].length));
+    return body.map((line) => line.slice(indent)).join('\n');
+}
+/** One guide's MDX as markdown, with the samples it names inlined. */
+export function toMarkdown(mdx, repoRoot) {
+    const fm = FRONTMATTER.exec(mdx);
+    const title = fm ? frontmatterField(fm[1], 'title') : '';
+    const description = fm ? frontmatterField(fm[1], 'description') : '';
+    let body = mdx.replace(FRONTMATTER, '').replace(COMPONENT_IMPORT, '');
+    body = body.replace(CODE_FROM_FILE, (_, attrs) => {
+        const file = attribute(attrs, 'file');
+        const source = readFileSync(join(repoRoot, file), 'utf-8');
+        const name = attribute(attrs, 'region');
+        const code = name ? region(source, name, file) : source.trimEnd();
+        const lang = attribute(attrs, 'lang') ?? extname(file).slice(1);
+        const heading = attribute(attrs, 'title') ?? file;
+        return `\`\`\`${lang} title="${heading}"\n${code}\n\`\`\``;
+    });
+    return {
+        entry: { title, description },
+        body: `# ${title}\n\n${description ? `> ${description}\n\n` : ''}${body.trim()}\n`,
+    };
+}
+/** Every guide under `from`, written as markdown into `into`, with an index. */
+export function bundleGuides(from, into, repoRoot) {
+    rmSync(into, { recursive: true, force: true });
+    mkdirSync(into, { recursive: true });
+    const index = [];
+    for (const file of readdirSync(from).filter((f) => f.endsWith('.mdx')).sort()) {
+        const slug = basename(file, '.mdx');
+        const { entry, body } = toMarkdown(readFileSync(join(from, file), 'utf-8'), repoRoot);
+        writeFileSync(join(into, `${slug}.md`), body);
+        index.push({ slug, ...entry });
+    }
+    writeFileSync(join(into, 'index.json'), JSON.stringify(index, null, 2) + '\n');
+    return index;
+}
+/** Where the bundled guides are, beside dist — or nowhere, before a build. */
+export function guidesDir() {
+    const dir = new URL('../guides/', import.meta.url).pathname;
+    return existsSync(join(dir, 'index.json')) ? dir : null;
+}
+export function listGuides() {
+    const dir = guidesDir();
+    if (!dir)
+        return 'No guides are bundled in this install. They are at https://rsc-kit.dev.';
+    const index = JSON.parse(readFileSync(join(dir, 'index.json'), 'utf-8'));
+    const width = Math.max(...index.map((g) => g.slug.length));
+    return [
+        'The guides, as published. Read one with read_guide({ slug }).',
+        '',
+        ...index.map((g) => `${g.slug.padEnd(width)}  ${g.description || g.title}`),
+    ].join('\n');
+}
+export function readGuide(slug) {
+    const dir = guidesDir();
+    if (!dir)
+        return `No guides are bundled in this install. This one is at https://rsc-kit.dev/guides/${slug}.`;
+    const file = join(dir, `${basename(slug)}.md`);
+    if (!existsSync(file))
+        return `No guide called "${slug}". list_guides has the names.`;
+    return readFileSync(file, 'utf-8');
+}
+/**
+ * Lines matching a phrase across every bundled guide, with the guide and a
+ * little context. A grep, deliberately - the guides are 250 KB and an agent
+ * asking "where is fieldErrors mentioned" wants the lines, not a ranking.
+ */
+export function searchGuides(phrase, limit = 40) {
+    const dir = guidesDir();
+    if (!dir)
+        return 'No guides are bundled in this install. Search https://rsc-kit.dev instead.';
+    const needle = phrase.trim().toLowerCase();
+    if (!needle)
+        return 'Give a word or phrase to search for.';
+    const index = JSON.parse(readFileSync(join(dir, 'index.json'), 'utf-8'));
+    const hits = [];
+    for (const { slug } of index) {
+        const lines = readFileSync(join(dir, `${slug}.md`), 'utf-8').split('\n');
+        for (let i = 0; i < lines.length && hits.length < limit; i++) {
+            if (!lines[i].toLowerCase().includes(needle))
+                continue;
+            hits.push(`${slug}:${i + 1}  ${lines[i].trim()}`);
+        }
+        if (hits.length >= limit)
+            break;
+    }
+    if (hits.length === 0)
+        return `Nothing in the guides mentions "${phrase}".`;
+    return [
+        `${hits.length}${hits.length === limit ? '+' : ''} lines mention "${phrase}". Read a guide with read_guide({ slug }).`,
+        '',
+        ...hits,
+    ].join('\n');
+}
+//# sourceMappingURL=bundleGuides.js.map

package/dist/bundleGuides.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundleGuides.js","sourceRoot":"","sources":["../src/bundleGuides.ts"],"names":[],"mappings":"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","sourcesContent":["// The guides, as files an agent can read without leaving its editor.\n//\n// how_to answers are short and opinionated, and they are copies — of the\n// guides at rsc-kit.dev, by hand, which is how a recipe once said <Form> worked\n// without javascript when it did not yet. The guides are the source. This\n// bundles them into the package at build time so read_guide answers with the\n// same text the site shows, and a recipe can point at the full version instead\n// of restating it.\n//\n// MDX to markdown is three edits: the frontmatter becomes a heading, the\n// component imports go, and <CodeFromFile> becomes the code it names — cut the\n// same way the site cuts it, region and all.\n\nimport { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs'\nimport { basename, extname, join } from 'node:path'\n\nexport interface GuideEntry {\n  slug: string\n  title: string\n  description: string\n}\n\nconst FRONTMATTER = /^---\\n([\\s\\S]*?)\\n---\\n/\nconst COMPONENT_IMPORT = /^import .* from [\"']@\\/components\\/.*[\"'];?\\n/gm\nconst CODE_FROM_FILE = /<CodeFromFile\\s+([^>]*?)\\/>/g\n\nfunction attribute(attrs: string, name: string): string | undefined {\n  return new RegExp(`${name}=\"([^\"]*)\"`).exec(attrs)?.[1]\n}\n\nfunction frontmatterField(block: string, name: string): string {\n  const match = new RegExp(`^${name}:\\\\s*(.*)$`, 'm').exec(block)\n\n  return (match?.[1] ?? '').trim().replace(/^[\"'](.*)[\"']$/, '$1')\n}\n\n/** The lines between `#region <name>` and its `#endregion`, dedented. */\nfunction region(source: string, name: string, file: string): string {\n  const lines = source.split('\\n')\n  const start = lines.findIndex((line) => new RegExp(`#region\\\\s+${name}\\\\b`).test(line))\n\n  if (start === -1) throw new Error(`No region \"${name}\" in ${file}`)\n\n  const end = lines.findIndex((line, i) => i > start && /#endregion\\b/.test(line))\n\n  if (end === -1) throw new Error(`Region \"${name}\" in ${file} is never closed`)\n\n  const body = lines.slice(start + 1, end).filter((line) => !/#(region|endregion)\\b/.test(line))\n  const indent = Math.min(...body.filter((l) => l.trim()).map((l) => /^\\s*/.exec(l)![0].length))\n\n  return body.map((line) => line.slice(indent)).join('\\n')\n}\n\n/** One guide's MDX as markdown, with the samples it names inlined. */\nexport function toMarkdown(mdx: string, repoRoot: string): { entry: Omit<GuideEntry, 'slug'>; body: string } {\n  const fm = FRONTMATTER.exec(mdx)\n  const title = fm ? frontmatterField(fm[1]!, 'title') : ''\n  const description = fm ? frontmatterField(fm[1]!, 'description') : ''\n\n  let body = mdx.replace(FRONTMATTER, '').replace(COMPONENT_IMPORT, '')\n\n  body = body.replace(CODE_FROM_FILE, (_, attrs: string) => {\n    const file = attribute(attrs, 'file')!\n    const source = readFileSync(join(repoRoot, file), 'utf-8')\n    const name = attribute(attrs, 'region')\n    const code = name ? region(source, name, file) : source.trimEnd()\n    const lang = attribute(attrs, 'lang') ?? extname(file).slice(1)\n    const heading = attribute(attrs, 'title') ?? file\n\n    return `\\`\\`\\`${lang} title=\"${heading}\"\\n${code}\\n\\`\\`\\``\n  })\n\n  return {\n    entry: { title, description },\n    body: `# ${title}\\n\\n${description ? `> ${description}\\n\\n` : ''}${body.trim()}\\n`,\n  }\n}\n\n/** Every guide under `from`, written as markdown into `into`, with an index. */\nexport function bundleGuides(from: string, into: string, repoRoot: string): GuideEntry[] {\n  rmSync(into, { recursive: true, force: true })\n  mkdirSync(into, { recursive: true })\n\n  const index: GuideEntry[] = []\n\n  for (const file of readdirSync(from).filter((f) => f.endsWith('.mdx')).sort()) {\n    const slug = basename(file, '.mdx')\n    const { entry, body } = toMarkdown(readFileSync(join(from, file), 'utf-8'), repoRoot)\n\n    writeFileSync(join(into, `${slug}.md`), body)\n    index.push({ slug, ...entry })\n  }\n\n  writeFileSync(join(into, 'index.json'), JSON.stringify(index, null, 2) + '\\n')\n\n  return index\n}\n\n/** Where the bundled guides are, beside dist — or nowhere, before a build. */\nexport function guidesDir(): string | null {\n  const dir = new URL('../guides/', import.meta.url).pathname\n\n  return existsSync(join(dir, 'index.json')) ? dir : null\n}\n\nexport function listGuides(): string {\n  const dir = guidesDir()\n\n  if (!dir) return 'No guides are bundled in this install. They are at https://rsc-kit.dev.'\n\n  const index = JSON.parse(readFileSync(join(dir, 'index.json'), 'utf-8')) as GuideEntry[]\n  const width = Math.max(...index.map((g) => g.slug.length))\n\n  return [\n    'The guides, as published. Read one with read_guide({ slug }).',\n    '',\n    ...index.map((g) => `${g.slug.padEnd(width)}  ${g.description || g.title}`),\n  ].join('\\n')\n}\n\nexport function readGuide(slug: string): string {\n  const dir = guidesDir()\n\n  if (!dir) return `No guides are bundled in this install. This one is at https://rsc-kit.dev/guides/${slug}.`\n\n  const file = join(dir, `${basename(slug)}.md`)\n\n  if (!existsSync(file)) return `No guide called \"${slug}\". list_guides has the names.`\n\n  return readFileSync(file, 'utf-8')\n}\n\n/**\n * Lines matching a phrase across every bundled guide, with the guide and a\n * little context. A grep, deliberately - the guides are 250 KB and an agent\n * asking \"where is fieldErrors mentioned\" wants the lines, not a ranking.\n */\nexport function searchGuides(phrase: string, limit = 40): string {\n  const dir = guidesDir()\n\n  if (!dir) return 'No guides are bundled in this install. Search https://rsc-kit.dev instead.'\n\n  const needle = phrase.trim().toLowerCase()\n\n  if (!needle) return 'Give a word or phrase to search for.'\n\n  const index = JSON.parse(readFileSync(join(dir, 'index.json'), 'utf-8')) as GuideEntry[]\n  const hits: string[] = []\n\n  for (const { slug } of index) {\n    const lines = readFileSync(join(dir, `${slug}.md`), 'utf-8').split('\\n')\n\n    for (let i = 0; i < lines.length && hits.length < limit; i++) {\n      if (!lines[i]!.toLowerCase().includes(needle)) continue\n\n      hits.push(`${slug}:${i + 1}  ${lines[i]!.trim()}`)\n    }\n\n    if (hits.length >= limit) break\n  }\n\n  if (hits.length === 0) return `Nothing in the guides mentions \"${phrase}\".`\n\n  return [\n    `${hits.length}${hits.length === limit ? '+' : ''} lines mention \"${phrase}\". Read a guide with read_guide({ slug }).`,\n    '',\n    ...hits,\n  ].join('\\n')\n}\n"]}

package/dist/index.js

@@ -26,6 +26,7 @@ import { z } from 'zod';
 import { explainRoute, heaviestRoutes, listRoutes, whatIsDynamic } from './answers.js';
 import { NoReport, loadReport } from './report.js';
 import { howTo, listTopics } from './recipes.js';
+import { listGuides, readGuide, searchGuides } from './bundleGuides.js';
 /** The project to read, from the argument or the working directory. */
 const root = process.argv[2] ?? process.cwd();
 /**
@@ -46,6 +47,8 @@ const read = () => loadReport(root);
  */
 const URL_ARG = { url: z.string().describe('The url, e.g. /orders or /posts/hello') };
 const TOPIC_ARG = { topic: z.string().describe('One of the topics from list_topics, e.g. forms or validation') };
+const SLUG_ARG = { slug: z.string().describe('One of the slugs from list_guides, e.g. forms or server-actions') };
+const PHRASE_ARG = { phrase: z.string().describe('A word or phrase, e.g. fieldErrors or metadataBase') };
 const text = (body) => ({ content: [{ type: 'text', text: body }] });
 /** A missing report is an answer, not a crash: it says to run a build. */
 const answering = (produce) => {
@@ -94,7 +97,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.',
+    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.',
     inputSchema: TOPIC_ARG,
     annotations: { readOnlyHint: true },
 }, (async ({ topic }) => text(howTo(topic))));
@@ -103,5 +106,22 @@ server.registerTool('list_topics', {
     description: 'Every topic how_to knows about, one line each.',
     annotations: { readOnlyHint: true },
 }, async () => text(listTopics()));
+server.registerTool('list_guides', {
+    title: 'The guides',
+    description: 'Every guide from rsc-kit.dev, bundled with this server — the full text behind how_to, one line each.',
+    annotations: { readOnlyHint: true },
+}, async () => text(listGuides()));
+server.registerTool('read_guide', {
+    title: 'Read a guide',
+    description: 'The complete guide for one topic, as published at 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.',
+    inputSchema: SLUG_ARG,
+    annotations: { readOnlyHint: true },
+}, (async ({ slug }) => text(readGuide(slug))));
+server.registerTool('search_guides', {
+    title: 'Search the guides',
+    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.',
+    inputSchema: PHRASE_ARG,
+    annotations: { readOnlyHint: true },
+}, (async ({ phrase }) => text(searchGuides(phrase))));
 await server.connect(new StdioServerTransport());
 //# sourceMappingURL=index.js.map

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'\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') }\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.',\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\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 { 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 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 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

@@ -214,6 +214,18 @@ export const searchParams = z.object({ page: z.coerce.number().int().min(1).defa
 Values arrive parsed and typed — \`?page=3\` is the number 3, a missing one is
 the default. Never hand-parse \`Number(searchParams.get('page'))\`.
 
+The same schema types every LINK to that page. Write search params as an
+object, never as a string:
+
+\`\`\`tsx
+<Link href="/search" search={{ q: 'shoes', page: 2 }}>…</Link>   // typed by the page's schema
+visit(href('/search', { q: 'shoes' }))                              // same check, as a string
+\`\`\`
+
+A key the page never reads, or a number written as text, does not compile;
+a key the page requires is required on the link. A page with no schema takes
+any scalars. Do NOT build \`?q=\${q}\` by hand when the page has a schema.
+
 **Api route bodies** the same way:
 
 \`\`\`ts
@@ -267,14 +279,20 @@ schema does not have is a compile error:
 
 \`\`\`ts
 .handler(async ({ input, fieldErrors }) => {
-  if (!account) fieldErrors({ email: 'Account not found' })
+  if (!account) return fieldErrors({ email: 'Account not found' })
 })
 \`\`\`
 
-It throws, so nothing after it runs. It lands in validationErrors on that
-field, the same place a schema refusal does. This is next-safe-action's
-returnValidationErrors with no schema argument, no _errors nesting and no
-return to forget.
+WRITE return fieldErrors(...). It throws either way, but TypeScript cannot see
+a never-return through a destructured argument, so without the return the
+value you checked stays possibly-undefined on the next line. It lands in
+validationErrors on that field, the same place a schema refusal does. This is
+next-safe-action's returnValidationErrors with no schema argument and no
+_errors nesting.
+
+A plain "use server" function with no action client imports the same thing,
+untyped, from '@rsc-kit/core/action' - the engine converts the throw into the
+returned { validationErrors } on the way out. Same rule: return fieldErrors(...).
 
 The point is not convenience. An action cannot be added without the check,
 because there is no other constructor to reach for.
@@ -666,6 +684,39 @@ import fraunces from '@fontsource-variable/fraunces/files/fraunces-latin-full-no
 needs; preloading all of them defeats the subsetting.
 
 Do NOT reach for next/font, @next/font or a Google Fonts link tag.`,
+    },
+    {
+        topic: 'images',
+        summary: 'Responsive images with no optimizer - unpic for a CDN, imagetools for files in the repo',
+        body: `There is NO image component and NO image server. Do not add next/image or
+write an optimizer route. next/image is a srcset-writing component plus a
+resize-on-request process; the first is a library, the second belongs to the
+CDN.
+
+An image on a CDN (Cloudinary, imgix, Cloudflare Images, Bunny, Vercel,
+Netlify, ...): @unpic/react. Plain component, works in a server component,
+ships no javascript, detects the CDN from the url:
+
+\`\`\`tsx
+import { Image } from '@unpic/react'
+
+<Image src="https://res.cloudinary.com/demo/image/upload/sample.jpg" layout="constrained" width={800} height={600} alt="..." />
+\`\`\`
+
+A file in the repo, a handful of them: vite-imagetools, resized ONCE at build
+time. Add imagetools() to the vite plugins, then:
+
+\`\`\`tsx
+import hero from '../hero.png?w=400;800;1200&format=webp&as=srcset'
+import heroSrc from '../hero.png?w=800&format=webp'
+
+<img srcSet={hero} src={heroSrc} sizes="(min-width: 800px) 800px, 100vw" width={800} height={600} alt="..." />
+\`\`\`
+
+Hundreds of files in the repo: that is a CDN's job; move them and use unpic.
+An icon or a logo: a plain <img>, or inline the svg.
+
+Full guide: read_guide({ slug: 'images' }).`,
     },
     {
         topic: 'scripts',
@@ -736,7 +787,31 @@ the rest do not. This is where a guard that never ran or a 404 that came back
 
 **What still needs a browser:** a server action called OVER THE WIRE (the id is
 React's and private), hydration, navigation. Playwright against vite preview.
-That limit is narrower than Next's: the action's logic is a unit test here.`,
+That limit is narrower than Next's: the action's logic is a unit test here.
+
+**What to write when you add something.** Before running check, not after:
+
+- A guarded route (middleware.ts, or a page reading the session): a stranger
+  is turned away, and someone signed in gets 200.
+  \`\`\`ts
+  expect((await app.fetch('/admin', { redirect: 'manual' })).status).toBe(302)
+  expect((await app.fetch('/admin', { headers: { Cookie: 'session=ada' } })).status).toBe(200)
+  \`\`\`
+- An action: its refusal, by calling it. Bad input answers validationErrors;
+  a stranger answers serverError (or throws ServerAuthenticationError if you
+  built it without the client).
+  \`\`\`ts
+  expect((await createPost({ title: '' })).validationErrors).toBeDefined()
+  \`\`\`
+- An action that takes an id: someone else's id is refused. This is the IDOR
+  test and the one most often missing.
+- A query: the shape of its answer, and what a filter changes.
+- An api route: status, content-type, and the 4xx it answers to a bad body.
+- A page that should stay static: assert on the build report - no test, a CI
+  check that build-report.json still says frozen for it.
+
+Do NOT start a dev server, spawn a process or pick a port in a test. Do NOT
+add a second runner. The one in tests/ goes through the real build already.`,
     },
 ];
 /** Every topic, with one line each — what a caller reads before choosing. */