From 09beb36acca34223fca7bc0882ff5ce04e5acb4d Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 15 Oct 2026 16:13:14 +0000
Subject: [PATCH] build: point llms.txt at the Solid 2.0 files

The 1.x index at docs.solidjs.com/llms.txt is the canonical one that
Context7 and per-page fetchers read, so an agent that starts there learns
1.x only. Add a postbuild step (`pnpm build:llms`, the same name the
v2-rebuild branch uses) that inserts one blockquote line under the title
naming the Solid 2.0 release-candidate files on v2.solidjs.com.

solidbase 0.6.13 exposes `llms` as a boolean only and writes the index
during `buildStart` into `node_modules/.solidbase/llms`, with no hook to
decorate it; a `public/llms.txt` would replace the generated index rather
than annotate it. Rewriting the built file after `vite build` keeps the
generator untouched. The script also covers `llms-full.txt` when a future
solidbase emits one; today main produces `llms.txt` only.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ka6h98478umeFadcRV1KLY
---
 package.json           |  3 ++-
 scripts/build-llms.mjs | 52 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 54 insertions(+), 1 deletion(-)
 create mode 100644 scripts/build-llms.mjs

diff --git a/package.json b/package.json
index f8db86fdf3..6342845cc6 100644
--- a/package.json
+++ b/package.json
@@ -7,7 +7,8 @@
 	"scripts": {
 		"sync:orama": "pnpm build && node scripts/sync-orama.mjs",
 		"dev": "vite dev",
-		"build": "vite build",
+		"build": "vite build && pnpm build:llms",
+		"build:llms": "node scripts/build-llms.mjs",
 		"start": "vite start",
 		"e2e": "npx playwright test",
 		"format": "prettier . --write",
diff --git a/scripts/build-llms.mjs b/scripts/build-llms.mjs
new file mode 100644
index 0000000000..df941c56ad
--- /dev/null
+++ b/scripts/build-llms.mjs
@@ -0,0 +1,52 @@
+// Post-processes the llms files that solidbase writes into the build output.
+// The 1.x index is the canonical https://docs.solidjs.com/llms.txt; the first
+// line under its title points tools at the Solid 2.0 files, which live on
+// their own host until 2.0 is stable.
+import { readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const OUTPUT_DIR = resolve(ROOT, process.argv[2] ?? "dist");
+const V2_ORIGIN = "https://v2.solidjs.com";
+const V2_POINTER = `> Solid 2.0 (release candidate) documentation for tools: ${V2_ORIGIN}/llms.txt and ${V2_ORIGIN}/llms-full.txt`;
+const FILES = ["llms.txt", "llms-full.txt"];
+
+async function readIfPresent(filePath) {
+	try {
+		return await readFile(filePath, "utf8");
+	} catch (error) {
+		if (error.code === "ENOENT") return undefined;
+		throw error;
+	}
+}
+
+// Inserts the pointer as a blockquote directly under the level-one heading,
+// where the llms.txt convention keeps its summary line.
+function addV2Pointer(fileName, content) {
+	if (content.includes(V2_POINTER)) return content;
+
+	const lines = content.split("\n");
+	if (!lines[0]?.startsWith("# ")) {
+		throw new Error(`${fileName} must start with a level-one heading`);
+	}
+
+	lines.splice(1, 0, "", V2_POINTER);
+	return lines.join("\n");
+}
+
+const updated = [];
+for (const fileName of FILES) {
+	const filePath = resolve(OUTPUT_DIR, fileName);
+	const content = await readIfPresent(filePath);
+	if (content === undefined) continue;
+
+	await writeFile(filePath, addV2Pointer(fileName, content), "utf8");
+	updated.push(fileName);
+}
+
+if (updated.length === 0) {
+	throw new Error(`No llms files found in ${OUTPUT_DIR}`);
+}
+
+console.log(`Added the Solid 2.0 pointer to ${updated.join(" and ")}.`);