blume 1.7.1 → 1.7.3

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/NavTree.astro

@@ -35,7 +35,10 @@ interface Props {
   /**
    * Stable ids for the full sidebar's groups (`navGroupIds`), so panel and
    * fragment ids match across the scoped views the layout renders. Absent,
-   * ids fall back to positions within this render.
+   * ids fall back to positions within this render. A group missing from the
+   * map exists only in this render — a container the tab scoping rebuilt
+   * without a nested tab section — so no fragment can serve it: it renders
+   * in full instead of being deferred.
    */
   ids?: Map<NavNode, string>;
   /**
@@ -63,9 +66,12 @@ const {
 const idOf = (node: NavNode, positional: string): string =>
   ids?.get(node) ?? positional;
 
-/** The fragment a deferred section loads from, when sections are deferred. */
-const fragmentFor = (id: string): string | undefined =>
-  fragmentBase ? `${fragmentBase}/${id}` : undefined;
+/**
+ * The fragment a group's section loads from, when sections are deferred and
+ * the group is one the fragments know (in `ids`, or `ids` is absent).
+ */
+const fragmentFor = (node: NavNode, id: string): string | undefined =>
+  fragmentBase && (ids?.has(node) ?? true) ? `${fragmentBase}/${id}` : undefined;
 
 // Merge over the English defaults so a label missing from a translation (or
 // from a not-yet-regenerated snapshot) still renders instead of coming out
@@ -150,66 +156,56 @@ const initialId =
           strings={n}
         />
       </div>
-      {panels.map((panel) => (
-        <div
-          data-nav-depth={panel.depth}
-          data-nav-panel={panel.id}
-          data-nav-src={panel.active ? undefined : fragmentFor(panel.id)}
-          hidden={panel.id !== initialId}
-        >
-          {/* The title is the only sidebar link to the section's own page, so
-              a routed panel keeps it as a link; without a route the whole row
-              becomes the back button. Either way every part of the row is
-              interactive. */}
-          {panel.route ? (
-            <div class="mb-3 flex items-center gap-0.5">
+      {panels.map((panel) => {
+        const src = panel.active ? undefined : fragmentFor(panel.node, panel.id);
+        return (
+          <div
+            data-nav-depth={panel.depth}
+            data-nav-panel={panel.id}
+            data-nav-src={src}
+            hidden={panel.id !== initialId}
+          >
+            {/* The title is the only sidebar link to the section's own page, so
+                a routed panel keeps it as a link; without a route the whole row
+                becomes the back button. Either way every part of the row is
+                interactive. */}
+            {panel.route ? (
+              <div class="mb-3 flex items-center gap-0.5">
+                <button
+                  aria-label={n.back}
+                  class="-ml-1 flex shrink-0 items-center justify-center self-stretch rounded-[0.65rem] px-1 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+                  data-nav-back={panel.parentId}
+                  type="button"
+                >
+                  <Icon class="rtl:-scale-x-100" name="arrow-left" size={16} />
+                </button>
+                <a
+                  aria-current={panel.route === currentRoute ? "page" : undefined}
+                  class="flex-1 truncate rounded-[0.65rem] px-1 py-1 font-semibold text-foreground text-sm transition-colors hover:bg-muted"
+                  href={withBase(panel.route)}
+                >
+                  {panel.label}
+                </a>
+              </div>
+            ) : (
               <button
-                aria-label={n.back}
-                class="-ml-1 flex shrink-0 items-center justify-center self-stretch rounded-[0.65rem] px-1 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+                aria-label={`${n.back}: ${panel.label}`}
+                class="-ml-1 mb-3 flex w-full items-center gap-1.5 rounded-[0.65rem] p-1 text-left font-semibold text-foreground text-sm transition-colors hover:bg-muted"
                 data-nav-back={panel.parentId}
                 type="button"
               >
-                <Icon class="rtl:-scale-x-100" name="arrow-left" size={16} />
+                <Icon
+                  class="shrink-0 text-muted-foreground rtl:-scale-x-100"
+                  name="arrow-left"
+                  size={16}
+                />
+                <span class="flex-1 truncate">{panel.label}</span>
               </button>
-              <a
-                aria-current={panel.route === currentRoute ? "page" : undefined}
-                class="flex-1 truncate rounded-[0.65rem] px-1 py-1 font-semibold text-foreground text-sm transition-colors hover:bg-muted"
-                href={withBase(panel.route)}
-              >
-                {panel.label}
-              </a>
-            </div>
-          ) : (
-            <button
-              aria-label={`${n.back}: ${panel.label}`}
-              class="-ml-1 mb-3 flex w-full items-center gap-1.5 rounded-[0.65rem] p-1 text-left font-semibold text-foreground text-sm transition-colors hover:bg-muted"
-              data-nav-back={panel.parentId}
-              type="button"
-            >
-              <Icon
-                class="shrink-0 text-muted-foreground rtl:-scale-x-100"
-                name="arrow-left"
-                size={16}
-              />
-              <span class="flex-1 truncate">{panel.label}</span>
-            </button>
-          )}
-          {/* An inactive panel's contents are deferred (fetched into this
-              element on drill-in) when fragments are on; otherwise the
-              build-time cache renders them once. */}
-          {panel.active ? (
-            <Self
-              currentRoute={currentRoute}
-              depth={1}
-              fragmentBase={fragmentBase}
-              idPrefix={panel.id}
-              ids={ids}
-              items={panel.children}
-              root={false}
-              strings={n}
-            />
-          ) : fragmentBase ? null : (
-            <NavTreeCache node={panel.node} variant={`${panel.id}|${n.back}|${n.deprecated}`}>
+            )}
+            {/* An inactive panel's contents are deferred (fetched into this
+                element on drill-in) when it has a fragment; otherwise the
+                build-time cache renders them once. */}
+            {panel.active ? (
               <Self
                 currentRoute={currentRoute}
                 depth={1}
@@ -220,10 +216,23 @@ const initialId =
                 root={false}
                 strings={n}
               />
-            </NavTreeCache>
-          )}
-        </div>
-      ))}
+            ) : src ? null : (
+              <NavTreeCache node={panel.node} variant={`${panel.id}|${n.back}|${n.deprecated}`}>
+                <Self
+                  currentRoute={currentRoute}
+                  depth={1}
+                  fragmentBase={fragmentBase}
+                  idPrefix={panel.id}
+                  ids={ids}
+                  items={panel.children}
+                  root={false}
+                  strings={n}
+                />
+              </NavTreeCache>
+            )}
+          </div>
+        );
+      })}
     </blume-nav>
   ) : (
     <ul class="m-0 list-none space-y-px p-0">
@@ -362,11 +371,11 @@ const initialId =
                 </summary>
                 <div
                   class="space-y-0.5 border-border border-l pl-3"
-                  data-nav-src={open ? undefined : fragmentFor(id)}
+                  data-nav-src={open ? undefined : fragmentFor(item, id)}
                 >
                   {/* A closed group's children are deferred (fetched into this
-                      element on first open) when fragments are on. */}
-                  {!open && fragmentBase ? null : active ? (
+                      element on first open) when it has a fragment. */}
+                  {!open && fragmentFor(item, id) ? null : active ? (
                     <Self
                       currentRoute={currentRoute}
                       depth={depth + 1}

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;
@@ -407,7 +411,10 @@ const sidebar = sidebarForRoute(
   navigation.root
 );
 // Stable group ids over the full tree, so the scoped view above names its
-// panels and deferred fragments the same way every other page does.
+// panels and deferred fragments the same way every other page does. A
+// container the scoping rebuilt is not in the map, and NavTree renders it in
+// full rather than deferring it to a fragment that would render the full
+// tree's version.
 const navIds = navGroupIds(navigation.sidebar);
 const activeTab = currentTabForRoute(
   navigation.tabs,
@@ -545,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/components/layout/nav-utils.ts

@@ -151,6 +151,15 @@ const isTabSection = (node: NavNode, tabPaths: Set<string>): boolean => {
  * instead of duplicating each tab as a sidebar group. A container left empty by
  * this pruning is dropped too, so no bare heading is stranded. The root tab
  * spans everything, so it never removes anything.
+ *
+ * A group with no tab section anywhere beneath it is kept as the same object:
+ * the stable group ids (`navGroupIds`) and the build-time subtree cache are
+ * both keyed by node identity, so a copy would lose its id — its collapsed
+ * fragment was then requested by a positional name no route serves — and
+ * re-render on every page. A container that did lose a section is rebuilt,
+ * so it has no id: the deferred fragments render from the full tree, which
+ * would put the section back, so `NavTree` renders such a container in full
+ * instead (its untouched children still defer by their own ids).
  */
 const withoutTabSections = (
   nodes: NavNode[],
@@ -173,10 +182,15 @@ const withoutTabSections = (
         continue;
       }
       if (item.kind === "group") {
-        // A container left empty by pruning is dropped, so no bare heading is
-        // stranded.
         const children = prune(item.children);
-        if (children.length > 0) {
+        if (
+          children.length === item.children.length &&
+          children.every((child, index) => child === item.children[index])
+        ) {
+          kept.push(item);
+        } else if (children.length > 0) {
+          // A container left empty by pruning is dropped, so no bare heading
+          // is stranded.
           kept.push({ ...item, children });
         }
       } else {

package/src/core/adapter.ts

@@ -0,0 +1,61 @@
+import { z } from "zod";
+
+/**
+ * The serializable descriptor an integration factory returns — `posthog({ key })`,
+ * `vercel()`, `script({ src })` and their siblings. A descriptor is plain data:
+ * the CLI evaluates `blume.config.ts` once, validates what came back, and
+ * writes it into the generated project's data snapshot as a JSON literal. That
+ * is where the runtime reads it — nothing generated imports the config at
+ * request time — so a descriptor can't carry functions, class instances, or
+ * anything else JSON drops.
+ *
+ * Every consumer reads the descriptor instead of switching on a provider name:
+ * the head emitter and `blume doctor` branch on `kind`, the generated
+ * `.blume/package.json` declares `runtimeDeps`, and the secrets check warns
+ * when an entry of `requiredSecrets` is unset.
+ *
+ * An adapter's verbatim option passthrough is typed as {@link JsonValue} and
+ * validated with `z.json()`, so a function, `undefined`, a bigint, or a
+ * non-finite number fails config validation with a path instead of vanishing
+ * (or throwing) when the snapshot is serialized.
+ */
+export interface AdapterDescriptor<Kind extends string, Options> {
+  /** Which integration this is. */
+  kind: Kind;
+  /** The options the factory was called with, verbatim. */
+  options: Options;
+  /** Env vars the integration reads at runtime; `blume dev`/`build` warn when one is unset. */
+  requiredSecrets: string[];
+  /** Extra packages the generated `.blume/package.json` must declare. */
+  runtimeDeps: string[];
+}
+
+/**
+ * A value JSON can carry unchanged — what an adapter's passthrough options are
+ * typed as. Structurally identical to what `z.json()` accepts.
+ */
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+/**
+ * The schema for one descriptor `kind`, validating its `options` with the
+ * adapter's own option schema. Members of a `z.discriminatedUnion("kind", …)`.
+ */
+export const adapterDescriptorSchema = <
+  Kind extends string,
+  Options extends z.ZodType,
+>(
+  kind: Kind,
+  options: Options
+) =>
+  z.strictObject({
+    kind: z.literal(kind),
+    options,
+    requiredSecrets: z.array(z.string()),
+    runtimeDeps: z.array(z.string()),
+  });

package/src/core/config-input.ts

@@ -681,6 +681,8 @@ export interface AskSuggestion {
 /** Backends that can route an Ask AI request. */
 type AskProviderGateway = "gateway" | "openrouter" | "llmgateway";
 type AskProvider = AskProviderGateway | "inkeep" | "openai-compatible";
+/** How much the model reasons before answering (`ai.ask.reasoning`). */
+type AskReasoning = "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
 
 /** How much retrieved documentation each Ask AI question carries. */
 export interface AskRetrievalConfig {
@@ -715,6 +717,18 @@ export interface AskConfig {
    * overrides the built-in preset.
    */
   baseUrl?: string;
+  /**
+   * Origins allowed to call the generated endpoint from another site — a
+   * marketing page that embeds an ask box, for example — or `"*"` to allow
+   * every origin. The route answers preflight requests and names a listed
+   * origin on every response, errors included; every other origin stays
+   * subject to the browser's same-origin rule. Callers must send the body as
+   * JSON with a `content-type: application/json` header, or Astro's cross-site
+   * request check rejects the `POST` before the route runs. Only the generated
+   * route reads this; an external `endpoint` handles its own CORS and can't be
+   * combined with it.
+   */
+  cors?: string[];
   /** Turn Ask AI on. Defaults to `false`. */
   enabled?: boolean;
   /**
@@ -740,6 +754,18 @@ export interface AskConfig {
   model?: string;
   /** Which backend routes the request. Defaults to `gateway`. */
   provider?: AskProvider;
+  /**
+   * How much the model reasons before answering, from `"none"` to `"xhigh"`.
+   * Sent as the backend's own reasoning-effort control: the AI SDK's
+   * `reasoning` option on the gateway, `reasoning.effort` on OpenRouter, and
+   * `reasoning_effort` on OpenAI-compatible endpoints. The model has to
+   * support the level — OpenAI rejects one a model doesn't offer — and the
+   * endpoint has to accept the parameter; Inkeep has no reasoning control,
+   * so the field is rejected there. Omitted keeps the model's default.
+   * `"none"` is the fastest and cheapest for grounded docs Q&A, where the
+   * retrieved excerpts carry the answer.
+   */
+  reasoning?: AskReasoning;
   /**
    * How much documentation each question carries into the model's prompt.
    * Lower values cut time-to-first-token — which dominates on a self-hosted
@@ -750,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 {
   /**
@@ -806,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);