docs: generate the metrics reference and bring the config reference to v1.6.5

.github/styles/config/vocabularies/TraceMachina/accept.txt

@@ -326,3 +326,6 @@ inlined
 protobufs
 arg
 rustfmt
+unreferenced
+quantile
+OTel

web/apps/docs/content/docs/reference/nativelink-config/meta.json

@@ -1,6 +1,5 @@
 {
   "pages": [
-    "index",
     "store-overview"
   ],
   "title": "NativeLink config"

web/apps/docs/package.json

@@ -32,6 +32,7 @@
     "gen:changelog": "node scripts/gen-changelog.mjs",
     "gen:config-reference": "node scripts/gen-config-reference.mjs",
     "gen:llms": "node scripts/gen-llms.mjs",
+    "gen:metrics-reference": "node scripts/gen-metrics-reference.mjs",
     "lint": "biome check .",
     "lint:anchors": "node scripts/lint-anchors.mjs",
     "lint:boundaries": "node scripts/lint-boundaries.mjs",

web/apps/docs/scripts/gen-changelog.mjs

@@ -134,6 +134,22 @@ const GIT_CLIFF_MARKER_LINES = new Set([
   "<!-- vale on -->",
 ]);
 
+/**
+ * git-cliff links each release heading to its compare view:
+ * `## [1.6.3](https://.../compare/v1.6.2..v1.6.3) - 2026-07-24`. Fumadocs
+ * wraps every heading in its own anchor link, and an `<a>` inside an `<a>`
+ * is invalid HTML that breaks hydration. Keep the version and date in the
+ * heading and move the compare link to a line of its own underneath.
+ */
+const unlinkReleaseHeading = (line) => {
+  const match = /^## \[([^\]]+)\]\((https?:\/\/[^)\s]+)\)(.*)$/.exec(line);
+  if (!match) {
+    return line;
+  }
+  const [, version, url, rest] = match;
+  return `## ${version}${rest}\n\n[Compare with the previous release](${url})`;
+};
+
 const { text: raw, origin } = await readChangelog();
 
 // Keep everything from the first release heading on; the git-cliff header
@@ -156,7 +172,10 @@ const body = raw
     if (inFence) {
       return line;
     }
-    return GIT_CLIFF_MARKER_LINES.has(line.trim()) ? null : escapeLine(line);
+    if (GIT_CLIFF_MARKER_LINES.has(line.trim())) {
+      return null;
+    }
+    return escapeLine(unlinkReleaseHeading(line));
   })
   .filter((line) => line !== null)
   .join("\n")

web/apps/docs/scripts/gen-config-reference.mjs

@@ -237,7 +237,10 @@ function generateOne(v, sharedTargetDir) {
 }
 
 function writeManifest(versions) {
-  const entries = versions.map((v) => ({
+  // A tag that could not be built (pre-1.0.2 releases have no build-schema
+  // binary) has no page, and a manifest entry for it would be a dead link in
+  // the version switcher.
+  const entries = versions.filter((v) => existsSync(outFileFor(v))).map((v) => ({
     version: v.version,
     label: v.label,
     href: hrefFor(v),
@@ -276,11 +279,12 @@ export const CONFIG_VERSIONS: ConfigVersion[] = ${JSON.stringify(entries, null,
 const HAND_WRITTEN_PAGES = ["store-overview"];
 
 function writeMeta() {
-  // The canonical page plus any hand-written companion pages appear in the
-  // sidebar; other versions are reached through the in-page version switcher.
+  // The canonical page is the folder's own link (Fumadocs uses index.mdx for
+  // that when meta.json does not list it); the hand-written companion pages
+  // appear under it. Other versions are reached through the in-page switcher.
   writeFileSync(
     join(contentDir, "meta.json"),
-    `${JSON.stringify({ pages: ["index", ...HAND_WRITTEN_PAGES], title: "NativeLink config" }, null, 2)}\n`,
+    `${JSON.stringify({ pages: [...HAND_WRITTEN_PAGES], title: "NativeLink config" }, null, 2)}\n`,
   );
 }