@bezda/rhp-mcp 0.0.0-stage → 0.1.1

package/src/guard/rules.js

@@ -0,0 +1,125 @@
+// What each rhp component takes, and the names people write instead. The guard (rhp.js) checks props against these.
+
+// A Plot's own settings (plot.jsx). Every other prop of a Plot is a data group.
+export const PLOT_SETTINGS = ["children", "order", "reorder", "orientation", "overlap", "slats", "key", "rows", "animate", "thick", "class", "style", "ref", "onLoop", "static", "keyboard"];
+
+// The settings a data group's name is checked against for typos, and what a value of each looks like
+const isList = (v) => Array.isArray(v) || (ArrayBuffer.isView(v) && !(v instanceof DataView));
+const isObject = (v) => v !== null && typeof v === "object" && !isList(v);
+
+export const SETTING_VALUE = {
+  order: (v) => typeof v === "function" || (isList(v) && Array.from(v).every((x) => x == null || typeof x === "number")),
+  reorder: (v) => v === "slide" || v === "move" || v === "refill",
+  orientation: (v) => v === "horizontal" || v === "vertical" || v === "across",
+  overlap: (v) => typeof v === "boolean",
+  slats: (v) => typeof v === "number",
+  key: (v) => typeof v === "string" || typeof v === "function",
+  rows: (v) => isList(v) && v.length > 0 && Array.from(v).every(isObject),
+  animate: (v) => typeof v === "boolean" || (isList(v) && Array.from(v).every((x) => typeof x === "string")) || isObject(v),
+  thick: (v) => typeof v === "number" || typeof v === "string",
+  static: (v) => typeof v === "boolean",
+  keyboard: (v) => typeof v === "boolean",
+  class: (v) => typeof v === "string",
+  style: (v) => typeof v === "string" || isObject(v),
+  ref: (v) => typeof v === "function",
+  children: (v) => typeof v === "function",
+};
+
+export const CHART_PROPS = ["scale", "orientation", "height", "aspect", "ticks", "grid", "format", "animate", "theme", "static", "cross", "crossTicks", "crossGrid", "crossFormat", "label", "id", "class", "role", "style", "ref", "children"];
+
+export const THEME_KEYS = ["series", "positive", "negative", "ink", "muted", "grid", "surface", "low", "high", "font"];
+
+export const SLAT_SETTINGS = ["css", "thickness", "inset", "room"];
+
+export const ROOM_SIDES = ["start", "end", "before", "after"];
+
+// Each block's own props (blocks.jsx), and its numbers
+export const BLOCKS = {
+  Bar: { own: ["from", "to", "thick", "color", "shape"], numbers: ["from", "to"] },
+  Dot: { own: ["at", "size", "across", "cross", "color", "shape"], numbers: ["at", "across", "cross"] },
+  Tick: { own: ["at", "thick", "color", "shape"], numbers: ["at"] },
+  Cell: { own: ["value", "color", "shape"], numbers: ["value"] },
+  Place: { own: ["at", "across", "cross"], numbers: ["at", "across", "cross"] },
+  Label: { own: ["at", "side", "edge", "cross", "shape"], numbers: ["at", "cross"] },
+  Area: { own: ["points", "peak", "mirror", "smooth", "color"], numbers: ["peak"], svg: true },
+  Line: { own: ["points", "peak", "fill", "base", "smooth", "color"], numbers: ["peak", "base"], svg: true },
+};
+
+// What a block's length props take: a share of the band (a number) or a CSS length
+export const LENGTHS = { Bar: ["thick"], Dot: ["size"], Tick: ["thick"] };
+
+// Names people give a prop, and the prop it is
+export const RENAMES = {
+  Bar: { value: "to", end: "to", length: "to", x: "to", start: "from", begin: "from", base: "from", width: "thick", height: "thick", size: "thick", thickness: "thick", fill: "color", background: "color", colour: "color" },
+  Dot: { value: "at", x: "at", y: "cross", r: "size", radius: "size", width: "size", fill: "color", background: "color", colour: "color" },
+  Tick: { value: "at", x: "at", length: "thick", width: "thick", size: "thick", fill: "color", background: "color", colour: "color" },
+  Cell: { at: "value", fill: "color", background: "color", colour: "color" },
+  Place: { value: "at", x: "at", y: "cross" },
+  Label: { value: "at", x: "at", y: "cross", position: "side", align: "side", text: "children", label: "children" },
+  Area: { data: "points", values: "points", max: "peak", fill: "color", colour: "color", curved: "smooth" },
+  Line: { data: "points", values: "points", max: "peak", curved: "smooth", area: "fill", colour: "color" },
+  Chart: { domain: "scale", range: "scale", extent: "scale", horizontal: "orientation", vertical: "orientation", direction: "orientation", colors: "theme", palette: "theme", tickFormat: "format", ariaLabel: "label", title: "label" },
+  Poster: { headline: "title", heading: "title", subtitle: "dek", subheading: "dek", subhead: "dek", description: "dek", lede: "dek", standfirst: "dek", source: "note", footnote: "note", credit: "note", credits: "note", caption: "note", footer: "note", eyebrow: "kicker", overline: "kicker", tag: "kicker" },
+  slat: { height: "thickness", width: "thickness", size: "thickness", thick: "thickness", pitch: "thickness", padding: "room", margin: "room", gutter: "room", gutters: "room", gap: "inset", style: "css", styles: "css", class: "css", className: "css" },
+  theme: { colors: "series", palette: "series", accent: "series", text: "ink", foreground: "ink", color: "ink", background: "surface", bg: "surface", paper: "surface", gridline: "grid", gridlines: "grid", axis: "grid", fontFamily: "font", family: "font", typeface: "font" },
+};
+
+// What goes on a block's element as it is: the global HTML attributes (as Solid takes them), and SVG's for Area and Line
+const GLOBAL = ["accesskey", "accessKey", "autocapitalize", "autoCapitalize", "autocorrect", "autofocus", "autoFocus", "class", "classList", "contenteditable", "contentEditable", "dir", "draggable", "enterkeyhint", "enterKeyHint", "exportparts", "hidden", "id", "inert", "inputmode", "inputMode", "is", "itemid", "itemprop", "itemProp", "itemref", "itemscope", "itemScope", "itemtype", "itemType", "lang", "nonce", "part", "popover", "role", "slot", "spellcheck", "spellCheck", "style", "tabindex", "tabIndex", "title", "translate", "writingsuggestions", "ref", "children", "innerHTML", "textContent", "innerText"];
+const SVG = ["opacity", "transform", "filter", "mask", "stroke", "fill", "x", "y", "width", "height", "overflow", "visibility", "display", "cursor", "pathLength", "preserveAspectRatio", "viewBox", "xmlns", "focusable"];
+
+export const HTML_ATTRIBUTES = new Set(GLOBAL);
+export const SVG_ATTRIBUTES = new Set([...GLOBAL, ...SVG]);
+
+// data-*, aria-*, handlers (onClick, on:click, oncapture:click), Solid's namespaces (use:, prop:, attr:, bool:), and
+// SVG's hyphenated attributes (stroke-width)
+export const passesThrough = (name) => /^(data|aria)-/.test(name) || /^on[A-Za-z:]/.test(name) || /^(use|prop|attr|bool):/.test(name) || /^[a-z]+(-[a-z]+)+$/.test(name);
+
+// Edit distance (a swap of two letters side by side counts as one edit), with a cap: anything past it counts as far
+function distance(a, b, cap = 3) {
+
+  if (Math.abs(a.length - b.length) > cap) return cap + 1;
+
+  const d = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+
+  for (let j = 1; j <= b.length; j++) {
+    d[0][j] = j;
+  }
+
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + cost);
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) d[i][j] = Math.min(d[i][j], d[i - 2][j - 2] + 1);
+    }
+  }
+
+  return d[a.length][b.length];
+}
+
+// The name in a list closest to a name, if one is close enough to be a typo of it: one edit for names of up to six
+// letters, two for longer ones
+export function closest(name, names) {
+
+  const low = name.toLowerCase();
+  let best = null;
+  let bestD = Infinity;
+
+  for (const candidate of names) {
+    const cap = Math.min(name.length, candidate.length) <= 6 ? 1 : 2;
+    const d = distance(low, candidate.toLowerCase(), cap);
+    if (d <= cap && d < bestD) {
+      best = candidate;
+      bestD = d;
+    }
+  }
+
+  return best;
+}
+
+export const THEME_KEY = /^(series-\d+|positive|negative|ink|muted|grid|surface|low|high)$/;
+
+// A data group that is a palette: every item a color or a theme key
+export const isPalette = (list, isColor) => list.length > 0 && Array.from(list).every((c) => typeof c === "string" && (THEME_KEY.test(c) || isColor(c)));
+
+export { isList, isObject };

package/src/server.js

@@ -0,0 +1,266 @@
+// The MCP server, over stdio: the rhp skill's guide, references and recipes, and the checker, as four tools and one
+// prompt. stdout carries the protocol, so everything else goes to stderr.
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { SKILL_DIR, skillBody, references, recipes, reference, recipe } from "./skill.js";
+
+console.log = console.info = console.debug = console.error;
+
+const { version } = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+
+// A check that runs longer than this (in seconds) is stuck, a page in an endless loop: it is stopped and reported.
+// Checks take 3 to 11 seconds; many clients stop waiting for a tool at 60.
+const LIMIT = 50;
+
+// The screenshots go back at most 1280px wide and 2000px tall: Claude refuses a request holding over 20 images when
+// one is larger than 2000px, and a few checks reach 20 images
+const MAX_WIDTH = 1280;
+const MAX_HEIGHT = 2000;
+
+const INSTRUCTIONS = `rhp 2 (@bezda/rhp) makes charts out of HTML elements and CSS with SolidJS. It came out in September 2026, after your training data, so what you remember about rhp is wrong or belongs to the unrelated rhp 1. Before you write or change any rhp code, call rhp_guide and follow its workflow. Take each chart's technique from the closest recipe (rhp_recipe) and design the chart for its own subject, and look up every prop you are unsure of with rhp_reference instead of guessing. After every edit, call rhp_check with the chart file's absolute path, fix what it reports and look at its screenshots, until it reports no errors and no warnings.`;
+
+const text = (body) => ({ content: [{ type: "text", text: body }] });
+const failure = (body) => ({ content: [{ type: "text", text: body }], isError: true });
+
+// The guide: SKILL.md with a note on reading it through this server, and the names the other tools take
+function guide() {
+
+  return [
+    "You are reading the rhp skill through the rhp MCP server, so:",
+    "- where it says to run the checker, call the rhp_check tool with the chart file's absolute path;",
+    '- where it links a reference such as references/api.md, call rhp_reference with its name ("api");',
+    '- where it names a recipe such as recipes/bar.html or `bar`, call rhp_recipe with its type ("bar").',
+    "",
+    skillBody().trimEnd(),
+    "",
+    "## The references and recipes this server returns",
+    "",
+    "rhp_reference names:",
+    ...references().map((r) => `- ${r.name}: ${r.about}`),
+    "",
+    `rhp_recipe types: ${recipes().map((r) => r.type).join(", ")}. Call rhp_recipe with no type to see what each is for.`,
+    "",
+  ].join("\n");
+}
+
+function recipeList() {
+
+  const all = recipes();
+
+  return [
+    `${all.length} recipes. Each is a complete, tested chart page: call rhp_recipe with its type, for example { "type": "bar" }, to get the whole file.`,
+    "",
+    ...all.map((r) => `- ${r.type}: "${r.title}". ${r.description}`),
+    "",
+  ].join("\n");
+}
+
+// One browser for every check: launched by the first, launched again if it died, closed when the server stops.
+// With no browser, { error } (the check then reports how to install one).
+let launched = null;
+
+async function sharedBrowser() {
+
+  const current = (launched ??= import("./check/browser.js").then(({ launch }) => launch()).catch((e) => ({ error: [String(e?.message ?? e)] })));
+  const got = await current;
+  if (got.browser?.isConnected()) return got;
+  if (launched === current) launched = null;
+
+  return got.browser ? sharedBrowser() : got;
+}
+
+// Closes a browser (the shared one when none is given), and forgets it when it is the shared one
+async function closeBrowser(browser) {
+
+  const shared = (await launched)?.browser;
+  if (!browser || browser === shared) launched = null;
+  await (browser ?? shared)?.close().catch(() => {});
+}
+
+// The screenshots as JPEG images, drawn again on a canvas in the browser
+async function images(browser, shots) {
+
+  const page = await browser.newPage();
+  const out = [];
+
+  try {
+    for (const shot of shots) {
+      const data = await page.evaluate(async ({ png, width, height }) => {
+        const img = new Image();
+        img.src = "data:image/png;base64," + png;
+        await img.decode();
+        const k = Math.min(1, width / img.naturalWidth, height / img.naturalHeight);
+        const canvas = document.createElement("canvas");
+        canvas.width = Math.round(img.naturalWidth * k);
+        canvas.height = Math.round(img.naturalHeight * k);
+        const g = canvas.getContext("2d");
+        g.imageSmoothingQuality = "high";
+        g.drawImage(img, 0, 0, canvas.width, canvas.height);
+        return canvas.toDataURL("image/jpeg", 0.8).split(",")[1];
+      }, { png: fs.readFileSync(shot.path).toString("base64"), width: MAX_WIDTH, height: MAX_HEIGHT });
+      out.push({ shot, data });
+    }
+  } finally {
+    await page.close().catch(() => {});
+  }
+
+  return out;
+}
+
+// Checks a chart: the report, then each screenshot as an image after a line saying what it shows
+async function checkTool({ file, code, format, widths, dark, interact, settleTimeout }) {
+
+  if (file && code) return failure("Give file or code, not both.");
+  if (!file && !code) return failure("Give the chart to check: file (the absolute path of its file) or code (its code).");
+
+  if (file) {
+    if (file.startsWith("file:")) {
+      try {
+        file = fileURLToPath(file);
+      } catch {
+        return failure(`${file} is not a file URL this server can read. Give the chart file's absolute path.`);
+      }
+    }
+    if (!path.isAbsolute(file)) return failure(`"${file}" is a relative path. Give the chart file's absolute path (for example /home/me/project/chart.html): this server runs in its own folder, not in your project, so it cannot tell which file a relative path means.`);
+  }
+
+  const { check } = await import("./check/index.js");
+  const got = await sharedBrowser();
+  const browser = got.browser;
+  const running = check({ file, code, format, widths, dark, interact, settleTimeout, browser }).then((result) => ({ result }), (error) => ({ error }));
+  let timer;
+  const late = new Promise((resolve) => {
+    timer = setTimeout(resolve, LIMIT * 1000, { late: true });
+  });
+  const done = await Promise.race([running, late]);
+  clearTimeout(timer);
+
+  if (done.late) {
+    if (browser) await closeBrowser(browser);
+    return failure(`The check stopped after ${LIMIT} seconds: the chart's page never finished. A page stuck in an endless loop does this (a loop whose end never comes, or an effect that keeps setting a signal it reads). Find it, fix it and check again.`);
+  }
+  if ("error" in done) {
+    console.error(`rhp-mcp: the check failed: ${done.error?.stack ?? done.error}`);
+    if (browser) await closeBrowser(browser);
+    return failure(`The check failed before it could report: ${done.error?.message ?? done.error}. Call rhp_check again; it starts a new browser.`);
+  }
+
+  const result = done.result;
+  const content = [{ type: "text", text: result.text }];
+  const shots = [...result.screenshots].sort((a, b) => b.width - a.width || a.hover - b.hover);
+
+  if (browser && shots.length) {
+    try {
+      const first = new Map();
+      for (const { shot, data } of await images(browser, shots)) {
+        const label = `Screenshot at ${shot.width}px${shot.dark ? ", dark" : ""}${shot.hover ? ", pointing at a slat" : ""}`;
+        if (shot.hover && first.get(shot.width) === data) {
+          content.push({ type: "text", text: `${label}: the same as the one above (pointing at a slat changed nothing visible).` });
+          continue;
+        }
+        if (!shot.hover) first.set(shot.width, data);
+        content.push({ type: "text", text: `${label}:` });
+        content.push({ type: "image", data, mimeType: "image/jpeg" });
+      }
+    } catch (e) {
+      console.error(`rhp-mcp: the screenshots could not be attached: ${e.message}`);
+      content.push({ type: "text", text: "The screenshots could not be attached here: open them at the paths above and look at them." });
+    }
+  }
+
+  return { content };
+}
+
+const server = new McpServer({ name: "rhp", title: "rhp charts", version }, { instructions: INSTRUCTIONS });
+
+server.registerTool("rhp_guide", {
+  title: "How to make charts with rhp",
+  description: "Start here, before you write or change any rhp chart code. Returns how to make a chart with rhp 2 (@bezda/rhp): the workflow from the request to a checked chart, the rules that prevent most bugs, the code format, and the names of the references and recipes the other tools return. rhp 2 is newer than your training data, so call this first, once per conversation in which you make or change an rhp chart, and follow it.",
+  annotations: { readOnlyHint: true, openWorldHint: false },
+}, async () => text(guide()));
+
+server.registerTool("rhp_reference", {
+  title: "rhp reference",
+  description: "Returns one of rhp's references by name: api (every component, prop, helper and CSS variable, exactly), design (art direction from the subject, the editorial poster, color, type, layout), looks (eight looks written out in full, as examples), interaction (which interaction for which story, with code), environments (plain HTML, Solid, React, Next.js, Vue, Svelte, Angular, Astro), forms (the subject's own form, which chart for which data and story), pitfalls (mistakes and their fixes). Look props up here instead of guessing. A long reference comes back as its list of sections: call again with section to get the one you need.",
+  inputSchema: {
+    name: z.string().describe("The reference: api, design, environments, forms, interaction, looks or pitfalls"),
+    section: z.string().optional().describe('One "##" section of the reference, by its number or title, for example "4" or "Plot"'),
+  },
+  annotations: { readOnlyHint: true, openWorldHint: false },
+}, async ({ name, section }) => {
+
+  const got = reference(name, section);
+
+  return got.error ? failure(got.error) : text(got.text);
+});
+
+server.registerTool("rhp_recipe", {
+  title: "rhp recipe",
+  description: 'Lists rhp\'s recipes (call it with no type), or returns one recipe\'s complete HTML file (type, for example "bar"). A recipe is a tested chart page that shows the technique for one kind of chart: take its technique (how its Plots, slats and blocks are composed, its interaction, its phone rules) and leave its design, which was made for its own subject.',
+  inputSchema: {
+    type: z.string().optional().describe('The recipe, for example "bar", "line" or "donut"; leave it out for the list'),
+  },
+  annotations: { readOnlyHint: true, openWorldHint: false },
+}, async ({ type }) => {
+
+  if (type === undefined || !type.trim()) return text(recipeList());
+  const got = recipe(type);
+
+  return got.error ? failure(got.error) : text(got.text);
+});
+
+server.registerTool("rhp_check", {
+  title: "Check an rhp chart",
+  description: "Renders an rhp chart in a headless browser at 1280px and 390px wide, tries its interactions, and reports what is wrong: errors and warnings, each with what to change, then screenshots to look at. Call it after every edit to a chart until it reports no errors and no warnings, and look at the screenshots each time. Give file, the chart file's ABSOLUTE path (an .html page, a Solid or React .jsx/.tsx component, or a .js module that uses @bezda/rhp/standalone), or code when you cannot write files.",
+  inputSchema: {
+    file: z.string().optional().describe("The chart file's absolute path"),
+    code: z.string().optional().describe("The chart's code, instead of a file, when you cannot write files"),
+    format: z.enum(["html", "solid", "react", "module"]).optional().describe("What the code is; found from the file's extension and the code when left out"),
+    widths: z.array(z.number().int().min(200).max(2560)).min(1).max(6).optional().describe("Page widths in px, [1280, 390] by default; the interactions are tried at the first, and slats are tapped at phone widths (600px or less)"),
+    dark: z.boolean().optional().describe("Render with a dark color scheme (prefers-color-scheme: dark)"),
+    interact: z.boolean().optional().describe("Try the chart's interactions (true by default)"),
+    settleTimeout: z.number().int().min(100).max(30000).optional().describe("Maximum milliseconds per readiness wait, 10000 by default. Increase for a slow machine; the overall check still has a 50-second limit."),
+  },
+  annotations: { readOnlyHint: true, openWorldHint: true },
+}, checkTool);
+
+server.registerPrompt("chart", {
+  title: "Make a chart with rhp",
+  description: "Make a chart with rhp, following rhp_guide, checked with rhp_check until it is clean",
+  argsSchema: {
+    request: z.string().describe("The chart: its subject and data, and anything about its look, interaction or framework"),
+  },
+}, ({ request }) => ({
+  messages: [{
+    role: "user",
+    content: {
+      type: "text",
+      text: `Make this chart with rhp (@bezda/rhp): ${request}\n\nFirst call rhp_guide and follow its workflow: write the brief, take the technique from the closest recipe (rhp_recipe), design the chart for its own subject, and look up props with rhp_reference instead of guessing. After every edit, call rhp_check with the chart file's absolute path, fix what it reports and look at its screenshots, until it reports no errors and no warnings.`,
+    },
+  }],
+}));
+
+// Stop when the client goes: close the browser first, so no Chromium is left running
+let stopping = false;
+
+async function stop() {
+
+  if (stopping) return;
+  stopping = true;
+  await closeBrowser();
+  process.exit(0);
+}
+
+process.stdin.on("end", stop);
+process.stdin.on("close", stop);
+process.on("SIGINT", stop);
+process.on("SIGTERM", stop);
+process.on("unhandledRejection", (e) => console.error(`rhp-mcp: ${e?.stack ?? e}`));
+server.server.onclose = stop;
+
+await server.connect(new StdioServerTransport());
+console.error(`rhp-mcp ${version}: ready, serving the skill in ${SKILL_DIR}`);

package/src/skill.js

@@ -0,0 +1,140 @@
+// The rhp skill's text, as the MCP server and `rhp-mcp guide` serve it: SKILL.md, its references and its recipes.
+// In rhp's repository it is read from skills/rhp itself, so it is never stale; in the published package, from the copy
+// `npm run build` makes in skill/.
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const REPO = path.join(here, "../../skills/rhp");
+const COPY = path.join(here, "../skill");
+
+export const SKILL_DIR = fs.existsSync(path.join(REPO, "SKILL.md")) ? REPO : COPY;
+
+// A reference longer than this comes back as its list of sections (it would cost the agent over 10,000 tokens)
+const WHOLE = 40 * 1024;
+
+const read = (file) => fs.readFileSync(path.join(SKILL_DIR, file), "utf8");
+const kb = (text) => `${Math.max(1, Math.round(Buffer.byteLength(text) / 1024))} KB`;
+const entities = { amp: "&", lt: "<", gt: ">", quot: '"', "#39": "'" };
+const decode = (text) => (text ?? "").replace(/&(amp|lt|gt|quot|#39);/g, (_, e) => entities[e]);
+
+// SKILL.md without its frontmatter
+export function skillBody() {
+
+  return read("SKILL.md").replace(/^---\n[\s\S]*?\n---\n+/, "");
+}
+
+// The references: [{ name, about, file }], about from SKILL.md's list of references, else the file's title
+export function references() {
+
+  const dir = path.join(SKILL_DIR, "references");
+  const listed = new Map([...read("SKILL.md").matchAll(/^- \[[^\]]*\]\(references\/([\w-]+)\.md\):\s*(.+)$/gm)].map((m) => [m[1], m[2]]));
+
+  return fs.readdirSync(dir).filter((f) => f.endsWith(".md")).sort().map((f) => {
+    const name = f.slice(0, -3);
+    const about = listed.get(name) ?? fs.readFileSync(path.join(dir, f), "utf8").match(/^# (.+)$/m)?.[1] ?? "";
+    return { name, about, file: path.join(dir, f) };
+  });
+}
+
+// The recipes: [{ type, title, description, file }]
+export function recipes() {
+
+  const dir = path.join(SKILL_DIR, "recipes");
+
+  return fs.readdirSync(dir).filter((f) => f.endsWith(".html")).sort().map((f) => {
+    const text = fs.readFileSync(path.join(dir, f), "utf8");
+    return {
+      type: f.slice(0, -5),
+      title: decode(text.match(/<title>([^<]*)<\/title>/)?.[1]),
+      description: decode(text.match(/<meta name="description" content="([^"]*)"/)?.[1]),
+      file: path.join(dir, f),
+    };
+  });
+}
+
+// A markdown file's "## " sections, each with its first line of prose (headings inside code blocks don't count)
+function sections(text) {
+
+  const lines = text.split("\n");
+  const found = [];
+  let fenced = false;
+
+  lines.forEach((line, i) => {
+    if (/^\s*```/.test(line)) fenced = !fenced;
+    if (!fenced && line.startsWith("## ")) found.push({ title: line.slice(3).trim(), start: i });
+  });
+
+  return found.map((s, k) => {
+    const body = lines.slice(s.start, found[k + 1]?.start ?? lines.length);
+    let inCode = false;
+    const first = body.slice(1).find((line) => {
+      if (/^\s*```/.test(line)) inCode = !inCode;
+      return !inCode && line.trim() && !/^\s*(```|#|\||<!--)/.test(line);
+    });
+    return { title: s.title, first: first?.trim() ?? "", text: body.join("\n").trimEnd() + "\n" };
+  });
+}
+
+// The section a query names: its number ("4"), its title ("Plot"), the start of its title, or words in it
+function findSection(list, query) {
+
+  const q = query.trim().toLowerCase().replace(/^§\s*/, "");
+  const number = /^\d+\.?$/.test(q) ? parseInt(q, 10) : null;
+  const title = (s) => s.title.toLowerCase().replace(/^\d+\.\s*/, "");
+
+  return list.find((s) => number !== null && parseInt(s.title, 10) === number)
+    ?? list.find((s) => title(s) === q)
+    ?? list.find((s) => title(s).startsWith(q))
+    ?? list.find((s) => s.title.toLowerCase().includes(q));
+}
+
+// One reference: { text } (the whole file, its list of sections when it is long, or the section asked for) or { error }
+export function reference(name, section) {
+
+  const all = references();
+  const key = String(name ?? "").trim().toLowerCase().replace(/^references\//, "").replace(/\.md$/, "");
+  const ref = all.find((r) => r.name === key);
+  if (!ref) return { error: `There is no reference "${name}". The references are:\n${all.map((r) => `- ${r.name}: ${r.about}`).join("\n")}` };
+
+  const text = fs.readFileSync(ref.file, "utf8");
+  const list = sections(text).filter((s) => !/^contents$/i.test(s.title));
+
+  if (section !== undefined && section !== null && String(section).trim()) {
+    const found = findSection(list, String(section));
+    if (found) return { text: found.text };
+    return { error: `references/${ref.name}.md has no section "${section}". Its sections are:\n${list.map((s) => `- ${s.title}`).join("\n")}` };
+  }
+
+  if (Buffer.byteLength(text) <= WHOLE || !list.length) return { text };
+
+  const intro = text.slice(0, text.indexOf("\n## ") + 1).split("\n")
+    .filter((line) => !/^Contents\b/.test(line) && !/^\s*(?:[-*]|\d+\.)\s*\[[^\]]*\]\(#/.test(line))
+    .join("\n").replace(/\n{3,}/g, "\n\n").trim();
+  const pick = list[Math.min(3, list.length - 1)].title;
+  const examples = [parseInt(pick, 10), pick.replace(/^\d+\.\s*/, "")].filter((x) => !Number.isNaN(x));
+
+  return {
+    text: [
+      intro,
+      "",
+      `This reference is ${kb(text)}, too long to return whole, so here are its sections.`,
+      `Ask for the ones you need: call rhp_reference again with name "${ref.name}" and section set to a section's number or title, for example ${examples.map((x) => `{ "name": "${ref.name}", "section": "${x}" }`).join(" or ")}.`,
+      "",
+      ...list.map((s) => `- ${s.title} (${kb(s.text)})${s.first ? `: ${s.first}` : ""}`),
+      "",
+    ].join("\n"),
+  };
+}
+
+// One recipe's whole file: { text } or { error }
+export function recipe(type) {
+
+  const all = recipes();
+  const key = String(type ?? "").trim().toLowerCase().replace(/^recipes\//, "").replace(/\.html$/, "").replace(/\s+/g, "-");
+  const found = all.find((r) => r.type === key);
+  if (!found) return { error: `There is no recipe "${type}". The recipes are: ${all.map((r) => r.type).join(", ")}. Call rhp_recipe with no type to see what each is for.` };
+
+  return { text: fs.readFileSync(found.file, "utf8") };
+}