blume 1.7.2 → 1.7.3

package/src/ai/ai-catalog.ts

@@ -0,0 +1,241 @@
+import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
+import type { ResolvedConfig } from "../core/schema.ts";
+import { absoluteUrl } from "../core/site-url.ts";
+import { resolveReferences } from "../openapi/references.ts";
+import { API_CATALOG_PATH, hasApiCatalog } from "./api-catalog.ts";
+import { OPENAPI_PATH } from "./api/paths.ts";
+import { asciiSlugify } from "./mcp/discovery.ts";
+import { AGENT_SKILLS_DIR } from "./skills.ts";
+import type { SkillArtifact } from "./skills.ts";
+
+/**
+ * The AI Catalog (Agent-Card/ai-catalog data model, `specVersion` 1.0) at
+ * `/.well-known/ai-catalog.json`, which is also the Agentic Resource
+ * Discovery (ARD) manifest: one entry per agent-facing resource the site
+ * publishes, each an `urn:air:<host>:<namespace>:<name>` identifier, a
+ * display name, the artifact's media type, a URL, and the
+ * `representativeQueries` registries embed for semantic search. Like the
+ * RFC 9727 catalog next to it, everything is derived from `blume.config.ts`
+ * and the build's published skills — nothing is hand-written.
+ *
+ * ARD v0.91 moved its manifest to `/.well-known/ard.json` and calls
+ * `ai-catalog.json` the predecessor path that consumers only *may* consult,
+ * while the ai-catalog spec and today's agent-readiness scanners key on
+ * `ai-catalog.json`. The ARD manifest is just an `entries` array (other
+ * members are ignored), so the one document is written to both paths.
+ *
+ * Served as plain `application/json`: the `.json` extension gets it from
+ * every static host with no header rule, and the scanners that gate on the
+ * file ask for exactly that type. The registered `application/ai-catalog+json`
+ * is what the `Link`/`<link>` advertisements declare the document to be.
+ */
+
+export const AI_CATALOG_PATH = "/.well-known/ai-catalog.json";
+export const ARD_MANIFEST_PATH = "/.well-known/ard.json";
+export const AI_CATALOG_TYPE = "application/ai-catalog+json";
+const SPEC_VERSION = "1.0";
+
+/** One catalog entry, restricted to the terms Blume emits. */
+interface CatalogEntry {
+  identifier: string;
+  displayName: string;
+  type: string;
+  url: string;
+  description?: string;
+  capabilities?: string[];
+  representativeQueries: string[];
+}
+
+/** An entry before its identifier and queries are resolved against the host. */
+interface EntrySeed {
+  /** `<namespace>:<name>` — the identifier's tail and the `queries` key. */
+  key: string;
+  displayName: string;
+  type: string;
+  url: string;
+  description?: string;
+  capabilities?: string[];
+  /** Generated queries, replaced wholesale by a configured `queries[key]`. */
+  queries: string[];
+}
+
+const REFERENCE_KIND_LABEL = {
+  asyncapi: "AsyncAPI",
+  graphql: "GraphQL",
+  openapi: "OpenAPI",
+} as const;
+
+/** The `urn:air` publisher: the configured site's hostname. */
+const publisherHost = (site: string): string => new URL(site).hostname;
+
+/**
+ * Whether the site publishes a catalog: the feature is on, a `deployment.site`
+ * anchors the identifiers, and at least one entry exists. Every entry source
+ * is a config flag, so the answer needs no build output — the same gate the
+ * header rules, the `Link` header, and the head links read.
+ */
+export const hasAiCatalog = (config: ResolvedConfig): boolean =>
+  config.ai.catalog.enabled &&
+  Boolean(config.deployment.site) &&
+  (config.ai.mcp.enabled ||
+    config.ai.api ||
+    config.ai.llmsTxt.enabled ||
+    Boolean(config.ai.skills) ||
+    resolveReferences(config).length > 0);
+
+/**
+ * The `.well-known` documents agent registries fetch cross-origin (browser
+ * agents, hosted registries reading through a page). Each needs
+ * `Access-Control-Allow-Origin: *` on the static surface; the MCP endpoint
+ * itself already sets it at runtime.
+ */
+export const crossOriginDiscoveryPaths = (config: ResolvedConfig): string[] => {
+  const paths: string[] = [];
+  if (hasAiCatalog(config)) {
+    paths.push(AI_CATALOG_PATH, ARD_MANIFEST_PATH);
+  }
+  if (hasApiCatalog(config)) {
+    paths.push(API_CATALOG_PATH);
+  }
+  if (config.ai.mcp.enabled) {
+    paths.push("/.well-known/mcp.json", "/.well-known/mcp/server-card.json");
+  }
+  return paths;
+};
+
+const entrySeeds = (
+  config: ResolvedConfig,
+  skills: readonly SkillArtifact[],
+  abs: (path: string) => string
+): EntrySeed[] => {
+  const { title } = config;
+  const seeds: EntrySeed[] = [];
+
+  if (config.ai.mcp.enabled) {
+    const name = config.ai.mcp.name ?? title;
+    seeds.push({
+      capabilities: ["search_docs", "get_page", "list_pages", "get_navigation"],
+      description:
+        config.ai.mcp.instructions ??
+        `Model Context Protocol server over the ${title} documentation: full-text search, page Markdown, the page index, and the navigation tree.`,
+      displayName: name,
+      key: `mcp:${asciiSlugify(name) || "docs"}`,
+      queries: [
+        `search the ${title} documentation`,
+        `get a ${title} docs page as Markdown`,
+        `list every page in the ${title} docs`,
+      ],
+      type: "application/mcp-server-card+json",
+      url: abs("/.well-known/mcp/server-card.json"),
+    });
+  }
+
+  for (const skill of skills) {
+    seeds.push({
+      description: skill.description,
+      displayName: skill.name,
+      key: `skill:${skill.name}`,
+      queries: [
+        `load the ${skill.name} agent skill`,
+        `how do I use ${skill.name}`,
+      ],
+      type:
+        skill.type === "archive"
+          ? "application/agent-skills+gzip"
+          : "application/agent-skills+md",
+      url: abs(`${AGENT_SKILLS_DIR}/${skill.path}`),
+    });
+  }
+
+  if (config.ai.api) {
+    seeds.push({
+      description: `REST API over the ${title} documentation: the page index, each page as JSON or Markdown, and the navigation tree, described by this OpenAPI document.`,
+      displayName: `${title} docs API`,
+      key: "api:docs",
+      queries: [
+        `fetch a ${title} docs page as JSON`,
+        `list the pages in the ${title} docs`,
+        `get the ${title} docs navigation tree`,
+      ],
+      type: "application/vnd.oai.openapi+json",
+      url: abs(OPENAPI_PATH),
+    });
+  }
+
+  for (const reference of resolveReferences(config)) {
+    // Blume-rendered pages mount under `basePath`; Scalar pages stay at the
+    // raw route (see `referenceRoutes`). The rendered reference is the
+    // resource this publisher owns — the spec itself is catalogued by URL in
+    // the RFC 9727 linkset.
+    const docRoute =
+      reference.renderer === "blume"
+        ? withBasePath(reference.basePath, reference.route)
+        : reference.route;
+    seeds.push({
+      description: `${reference.label}: rendered ${REFERENCE_KIND_LABEL[reference.kind]} reference in the ${title} documentation.`,
+      displayName: reference.label,
+      key: `reference:${reference.slug}`,
+      queries: [
+        `what operations does the ${reference.label} API expose`,
+        `how do I call the ${reference.label} API`,
+      ],
+      type: "text/html",
+      url: abs(docRoute),
+    });
+  }
+
+  if (config.ai.llmsTxt.enabled) {
+    seeds.push({
+      description: `llms.txt index of the ${title} documentation: every page with a one-line summary, plus the agent-facing resources on this site.`,
+      displayName: `${title} llms.txt`,
+      key: "docs:llms-txt",
+      queries: [`what is ${title}`, `overview of the ${title} documentation`],
+      type: "text/plain",
+      url: abs("/llms.txt"),
+    });
+  }
+
+  return seeds;
+};
+
+/** The catalog document, or null when the site publishes none. */
+export const buildAiCatalog = (
+  config: ResolvedConfig,
+  skills: readonly SkillArtifact[]
+): string | null => {
+  const site = config.deployment.site ?? null;
+  if (!(site && hasAiCatalog(config))) {
+    return null;
+  }
+  const deployBase = normalizeBasePath(config.deployment.base);
+  const abs = (path: string): string =>
+    absoluteUrl(site, withBasePath(deployBase, path));
+  const host = publisherHost(site);
+  const entries = entrySeeds(config, skills, abs).map((seed): CatalogEntry => {
+    const entry: CatalogEntry = {
+      displayName: seed.displayName,
+      identifier: `urn:air:${host}:${seed.key}`,
+      representativeQueries:
+        config.ai.catalog.queries[seed.key] ?? seed.queries,
+      type: seed.type,
+      url: seed.url,
+    };
+    if (seed.description) {
+      entry.description = seed.description;
+    }
+    if (seed.capabilities) {
+      entry.capabilities = seed.capabilities;
+    }
+    return entry;
+  });
+  const catalog = {
+    entries,
+    host: {
+      displayName: config.title,
+      documentationUrl: abs("/"),
+      identifier: `did:web:${host}`,
+    },
+    specVersion: SPEC_VERSION,
+  };
+  return `${JSON.stringify(catalog, null, 2)}\n`;
+};

package/src/ai/link-headers.ts

@@ -1,5 +1,10 @@
 import { normalizeBasePath } from "../core/base-path.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
+import {
+  AI_CATALOG_PATH,
+  AI_CATALOG_TYPE,
+  hasAiCatalog,
+} from "./ai-catalog.ts";
 import { API_CATALOG_PATH, hasApiCatalog } from "./api-catalog.ts";
 import { OPENAPI_PATH } from "./api/paths.ts";
 
@@ -37,6 +42,13 @@ export const buildHomeLinkHeader = (
       `<${deployBase}${API_CATALOG_PATH}>; rel="api-catalog"; type="application/linkset+json"`
     );
   }
+  // The ai-catalog spec's own relation for its well-known document, the
+  // header form of the `<link rel="ai-catalog">` every page carries.
+  if (hasAiCatalog(config)) {
+    links.push(
+      `<${deployBase}${AI_CATALOG_PATH}>; rel="ai-catalog"; type="${AI_CATALOG_TYPE}"`
+    );
+  }
   // RFC 8631: `service-desc` is the relation for a machine-readable
   // description of the service — the JSON docs API's OpenAPI document.
   if (config.ai.api) {

package/src/ai/llms.ts

@@ -6,6 +6,7 @@ import { absoluteUrl } from "../core/site-url.ts";
 import { readExpandedEntryText } from "../core/sources/read.ts";
 import type { NavNode, Navigation, PageRecord } from "../core/types.ts";
 import { buildRssFeeds } from "../deploy/rss.ts";
+import { AI_CATALOG_PATH, hasAiCatalog } from "./ai-catalog.ts";
 import { API_CATALOG_PATH, hasApiCatalog } from "./api-catalog.ts";
 import { API_PAGES_PATH, OPENAPI_PATH } from "./api/paths.ts";
 import { downlevelComponents } from "./component-markdown.ts";
@@ -75,6 +76,11 @@ const agentResourceLines = (project: BlumeProject): string[] => {
       `- [API catalog](${url(API_CATALOG_PATH)}): RFC 9727 linkset of the APIs documented here.`
     );
   }
+  if (hasAiCatalog(config)) {
+    lines.push(
+      `- [AI catalog](${url(AI_CATALOG_PATH)}): ARD manifest of the agent-facing resources on this site (MCP server, skills, APIs).`
+    );
+  }
   if (config.seo.agentReadability) {
     lines.push(
       `- [agent-readability.json](${url("/agent-readability.json")}): Manifest of every agent-facing artifact on this site.`

package/src/ai/mcp/discovery.ts

@@ -56,7 +56,7 @@ const truncate = (text: string): string =>
 const NON_ASCII_SLUG = /[^a-z0-9]+/gu;
 const COMBINING_MARKS = /\p{M}+/gu;
 
-const asciiSlugify = (text: string): string =>
+export const asciiSlugify = (text: string): string =>
   trimChar(
     text
       .normalize("NFKD")

package/src/astro/generate.ts

@@ -24,6 +24,7 @@ import {
 } from "pathe";
 import { glob } from "tinyglobby";
 
+import { hasAiCatalog } from "../ai/ai-catalog.ts";
 import { OPENAPI_PATH } from "../ai/api/paths.ts";
 import { buildApiSpec } from "../ai/api/spec.ts";
 import { buildAskData } from "../ai/ask-data.ts";
@@ -1357,6 +1358,7 @@ export const buildRuntimeData = (project: BlumeProject): string => {
       description: config.description,
       discovery: {
         agentReadability: config.seo.agentReadability,
+        aiCatalog: hasAiCatalog(config),
         api: config.ai.api,
         llmsTxt: config.ai.llmsTxt.enabled,
         // Mirrors `buildSitemapFiles`: no site, no sitemap.

package/src/cli/commands/build.ts

@@ -5,6 +5,7 @@ import { build } from "astro";
 import { defineCommand } from "citty";
 import { join } from "pathe";
 
+import { crossOriginDiscoveryPaths } from "../../ai/ai-catalog.ts";
 import {
   API_CATALOG_PATH,
   API_CATALOG_TYPE,
@@ -128,7 +129,8 @@ const emitVercelNegotiation = async (
     {
       json: existsSync(join(staticDir, "404.json")),
       markdown: existsSync(join(staticDir, "404.md")),
-    }
+    },
+    crossOriginDiscoveryPaths(config)
   );
   if (injected === null) {
     logger.warn(

package/src/components/islands/hooks.ts

@@ -1,6 +1,7 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 
 import type { BlumeClientData } from "../../core/data.ts";
+import { track } from "../layout/analytics-client.ts";
 import type { SearchFn, SearchResult } from "../layout/search/types.ts";
 import { joinBase, stripBase } from "./base-path.ts";
 
@@ -196,6 +197,42 @@ export const useAskAI = (options: UseAskAIOptions = {}): UseAskAI => {
       const controller = new AbortController();
       abortRef.current = controller;
       const live = () => current === generation.current;
+      const path = currentPath();
+      // Usage reaches the configured analytics providers the same way page
+      // feedback does: the question now, its outcome once the stream settles.
+      // A reset mid-answer revokes the outcome along with the UI update.
+      // Analytics keys on the raw pathname, like page feedback and the
+      // providers' own pageviews, so the events join under a `base`; the
+      // endpoint gets the base-stripped route for grounding. Providers receive
+      // the question's length only: its text is free-form reader input (pasted
+      // keys, error logs) that would breach their PII terms and their
+      // per-value size caps, so it rides the `blume:track` event alone for a
+      // site to bridge on its own terms.
+      const { pathname } = window.location;
+      const report = (
+        event: "ask" | "ask_answer" | "ask_error",
+        props: Record<string, number>
+      ) =>
+        track(
+          event,
+          { ...props, path: pathname, questionChars: trimmed.length },
+          { question: trimmed }
+        );
+      report("ask", {});
+      // A monotonic clock: the wall clock can jump mid-stream (NTP, sleep).
+      const startedAt = performance.now();
+      const outcome = (
+        event: "ask_answer" | "ask_error",
+        props: Record<string, number>
+      ) =>
+        report(event, {
+          ...props,
+          ms: Math.round(performance.now() - startedAt),
+        });
+      // The HTTP status once a response exists. `streamText` defers provider
+      // errors to stream consumption, so a 200 can still break mid-flight;
+      // that reports as a 200 error, not as "no response".
+      let status = 0;
       const history: AskMessage[] = [
         ...messages,
         { content: trimmed, role: "user" },
@@ -207,16 +244,18 @@ export const useAskAI = (options: UseAskAIOptions = {}): UseAskAI => {
         const response = await fetch(endpoint, {
           body: JSON.stringify({
             messages: history,
-            page: { path: currentPath() },
+            page: { path },
           }),
           headers: { "content-type": "application/json" },
           method: "POST",
           signal: controller.signal,
         });
+        ({ status } = response);
         if (!response.ok) {
           // An error body (JSON, HTML error page) must not stream in as the
           // assistant's answer.
           if (live()) {
+            outcome("ask_error", { status });
             assistant.content = errorMessage;
             setMessages([...history, { ...assistant }]);
           }
@@ -243,11 +282,21 @@ export const useAskAI = (options: UseAskAIOptions = {}): UseAskAI => {
             }
           }
         }
+        if (live()) {
+          // A 200 with nothing in it (no body, an empty stream) leaves the
+          // reader a blank bubble — that is not an answer.
+          if (assistant.content) {
+            outcome("ask_answer", { chars: assistant.content.length });
+          } else {
+            outcome("ask_error", { status });
+          }
+        }
       } catch {
         // A thrown fetch (offline, DNS failure, CORS) must not strand the
         // pre-appended empty assistant message as a stuck placeholder. A
         // reset's abort lands here too — the guard keeps it silent.
         if (live()) {
+          outcome("ask_error", { status });
           assistant.content = errorMessage;
           setMessages([...history, { ...assistant }]);
         }

package/src/components/layout/RootLayout.astro

@@ -146,7 +146,11 @@ interface Props {
    * the site root. The HTML counterpart of the homepage-only HTTP `Link`
    * header (see `ai/link-headers.ts`).
    */
-  discovery?: { agentReadability: boolean; llmsTxt: boolean } | null;
+  discovery?: {
+    agentReadability: boolean;
+    aiCatalog: boolean;
+    llmsTxt: boolean;
+  } | null;
   siteUrl?: string | null;
   pageType?: string;
   published?: string | Date | null;
@@ -548,6 +552,25 @@ createIconSprite(Astro.locals);
         <link href={withBase("/llms.txt")} rel="describedby" type="text/plain" />
       )
     }
+    {/* The AI Catalog / ARD manifest under both relations its two specs
+        define: `ai-catalog` (ai-catalog spec) and `ard` (ARD v0.91), each
+        pointing at that spec's own well-known path. */}
+    {
+      discovery?.aiCatalog && (
+        <>
+          <link
+            href={withBase("/.well-known/ai-catalog.json")}
+            rel="ai-catalog"
+            type="application/ai-catalog+json"
+          />
+          <link
+            href={withBase("/.well-known/ard.json")}
+            rel="ard"
+            type="application/json"
+          />
+        </>
+      )
+    }
     {
       markdownMirror && (
         <link href={markdownMirror} rel="alternate" type="text/markdown" />

package/src/components/layout/analytics-client.ts

@@ -6,7 +6,10 @@
  * `analytics.scripts` is reached via best-effort global detection or the
  * `blume:track` CustomEvent, which fires unconditionally so a project can bridge
  * the event to anything. Every call no-ops cleanly when a provider isn't present
- * — for example during `blume dev`, where `Analytics.astro` injects nothing.
+ * — for example during `blume dev`, where `Analytics.astro` injects nothing —
+ * and a provider that throws (a consent shim that stubs `gtag` with a raise, a
+ * broken snippet) is isolated so it neither starves the providers after it nor
+ * surfaces in the feature that reported the event.
  */
 import { track as vercelTrack } from "@vercel/analytics";
 
@@ -19,7 +22,27 @@ interface AnalyticsWindow {
   posthog?: { capture?: (event: string, props?: TrackProps) => void };
 }
 
-export const track = (event: string, props: TrackProps): void => {
+/** Run one provider call; its failure must not reach the others or the caller. */
+const attempt = (send: () => void): void => {
+  try {
+    send();
+  } catch {
+    // Analytics never breaks the feature that reported the event.
+  }
+};
+
+/**
+ * @param event The event name.
+ * @param props Properties every provider receives.
+ * @param local Properties only the `blume:track` CustomEvent carries — free
+ *   text a site may bridge to a provider on its own terms, but that must not
+ *   reach third parties unasked (a reader's Ask AI question, for instance).
+ */
+export const track = (
+  event: string,
+  props: TrackProps,
+  local: TrackProps = {}
+): void => {
   // Read through `globalThis` so an SSR/import-time call sees `undefined`
   // instead of a bare-identifier ReferenceError.
   const browserWindow = globalThis.window;
@@ -31,12 +54,18 @@ export const track = (event: string, props: TrackProps): void => {
   const w = browserWindow as typeof browserWindow & AnalyticsWindow;
 
   // Vercel Web Analytics — self-gates to a no-op until `window.va` is set up.
-  vercelTrack(event, props);
+  attempt(() => vercelTrack(event, props));
   // PostHog — the injected array.js stub queues calls until the lib loads.
-  w.posthog?.capture?.(event, props);
+  attempt(() => w.posthog?.capture?.(event, props));
   // Popular providers wired through `analytics.scripts` (GA4/GTM, Plausible).
-  w.gtag?.("event", event, props);
-  w.plausible?.(event, { props });
+  attempt(() => w.gtag?.("event", event, props));
+  attempt(() => w.plausible?.(event, { props }));
   // Universal hook for any other integration.
-  w.dispatchEvent(new CustomEvent("blume:track", { detail: { event, props } }));
+  attempt(() =>
+    w.dispatchEvent(
+      new CustomEvent("blume:track", {
+        detail: { event, props: { ...props, ...local } },
+      })
+    )
+  );
 };

package/src/core/config-input.ts

@@ -776,6 +776,31 @@ export interface AskConfig {
   suggestions?: AskSuggestion[];
 }
 
+/** What the AI Catalog (ARD) manifest carries. */
+export interface AiCatalogConfig {
+  /** Emit `/.well-known/ai-catalog.json` and `/.well-known/ard.json`. Defaults to `true`. */
+  enabled?: boolean;
+  /**
+   * Representative queries per entry, keyed by the entry's `<namespace>:<name>`
+   * — its identifier minus the `urn:air:<host>:` prefix (`mcp:docs`,
+   * `skill:blume`, `api:docs`, `reference:<slug>`, `docs:llms-txt`). Each
+   * list replaces the generated defaults for that entry: 2–5 short
+   * natural-language questions the resource can answer, which agent
+   * registries embed for semantic search.
+   *
+   * ```ts
+   * ai: {
+   *   catalog: {
+   *     queries: {
+   *       "mcp:acme": ["how do I install Acme", "search the Acme docs"],
+   *     },
+   *   },
+   * }
+   * ```
+   */
+  queries?: Record<string, string[]>;
+}
+
 /** What the `llms.txt`/`llms-full.txt` files include. */
 export interface LlmsTxtConfig {
   /**
@@ -832,6 +857,15 @@ export interface AiConfig {
   api?: boolean;
   /** The Ask AI chat assistant. */
   ask?: AskConfig;
+  /**
+   * The AI Catalog / ARD manifest (`/.well-known/ai-catalog.json`, mirrored
+   * at `/.well-known/ard.json`): a domain-level index of the agent-facing
+   * resources the site publishes — MCP server, agent skills, the JSON docs
+   * API, API references, llms.txt — for agent registries. Needs a
+   * `deployment.site`. Defaults to `true`; the object form overrides the
+   * generated representative queries per entry.
+   */
+  catalog?: boolean | AiCatalogConfig;
   /**
    * Emit `llms.txt` (an index of the docs for LLMs). Defaults to `true`.
    * The object form adds knobs for what the files include.

package/src/core/data.ts

@@ -140,6 +140,8 @@ export interface BlumeDataConfig {
    */
   discovery: {
     agentReadability: boolean;
+    /** Whether the AI Catalog / ARD manifest is published (`ai.catalog`). */
+    aiCatalog: boolean;
     /** Whether the JSON docs API and its `/openapi.json` are published. */
     api: boolean;
     llmsTxt: boolean;

package/src/core/navigation.ts

@@ -112,6 +112,8 @@ interface MutableGroup {
   path: string;
   /** The group's URL path (folder route prefix); set as pages are inserted. */
   routePath?: string;
+  /** The folder's index page route, when it has one; the group row's link. */
+  route?: string;
   label: string;
   icon?: string;
   collapsed?: boolean;
@@ -214,8 +216,14 @@ const applyFolderMeta = (
   sharedMeta: Map<string, FolderMeta>,
   metaPrefix: string,
   sharedMetaPrefix: string,
-  indexDisplay: Map<string, SidebarDisplay>
+  indexDisplay: Map<string, SidebarDisplay>,
+  indexRoute: Map<string, string>
 ): void => {
+  // A folder with an index page links its group row to it — the same shape
+  // as an explicit-config group's `root`, and the only sidebar link to the
+  // section's own page once the index row is hidden. Index-less folders keep
+  // no link: their row would 404.
+  group.route = indexRoute.get(group.path);
   // Locale-specific meta wins; a shared `meta.$.*` (keyed by the locale-stripped
   // group path — version-prefixed inside a snapshot) applies to every locale
   // otherwise.
@@ -254,7 +262,8 @@ const applyFolderMeta = (
         sharedMeta,
         metaPrefix,
         sharedMetaPrefix,
-        indexDisplay
+        indexDisplay,
+        indexRoute
       );
     }
   }
@@ -510,6 +519,7 @@ const toNavNode = (node: MutableNode, display: SidebarDisplay): NavNode => {
     kind: "group",
     label: node.label,
     path: node.routePath,
+    route: node.route,
   };
 };
 
@@ -529,6 +539,11 @@ const buildFileSystemSidebar = (
   // Collected before the hidden filter (like the title check): hiding the index
   // row from the panel shouldn't stop it configuring its group.
   const indexDisplay = new Map<string, SidebarDisplay>();
+  // Folder path -> that folder's index page route, for the group row's link.
+  // Also collected before the hidden filter: hiding the index row is how a
+  // site drops the duplicate label under a linked header, so the link must
+  // survive it. The content root is not a group, so its index is skipped.
+  const indexRoute = new Map<string, string>();
 
   for (const page of pages) {
     // Group by the locale-stripped path so the locale dir is not a nav group.
@@ -558,6 +573,9 @@ const buildFileSystemSidebar = (
       if (page.meta.sidebar.display && !page.fallback) {
         indexDisplay.set(dirs.join("/"), page.meta.sidebar.display);
       }
+      if (dirs.length > 0) {
+        indexRoute.set(dirs.join("/"), page.route);
+      }
     }
 
     if (page.meta.sidebar.hidden) {
@@ -611,7 +629,8 @@ const buildFileSystemSidebar = (
     sharedMeta,
     metaPrefix,
     sharedMetaPrefix,
-    indexDisplay
+    indexDisplay,
+    indexRoute
   );
   sortNodes(root.children, diagnostics);
   hoistPages(root.children, display, true);