feat(shell-docs): resolve framework-variant URL slugs end-to-end

Registry slugs don't always match the integrations/<folder>/ name on
disk. Three LangChain/LangGraph variants (langgraph-python, langgraph-
typescript, langgraph-fastapi) read from the single langgraph/ tree,
ms-agent-dotnet and ms-agent-python share microsoft-agent-framework/,
and google-adk/strands are legacy renames that point at adk/ and
aws-strands/ respectively.

Before: the framework-scoped router, the sidebar-override nav
builder, and the "not available for this framework" fallback all
used the URL slug directly as a folder name, so any of the seven
mismatched slugs showed empty sidebars, 404s on framework-unique
pages (/langgraph-python/auth, /ms-agent-dotnet/auth), and missing
'available in other integrations' matches.

After: lib/registry exposes getDocsFolder(slug) backed by a small
DOCS_FOLDER_OVERRIDES table. Callers resolve the URL slug to its
actual folder before touching disk; findFrameworksWithPage takes the
resolver as a parameter so docs-render stays registry-free.

Per-page variant selectors authored as <Tabs groupId="..." default="Python">
now open with the URL-matching tab preselected instead of the author's
hardcoded default. getTabDefault(slug, groupId) reads
TAB_DEFAULTS_BY_SLUG; a wrapper in DocsPageView's MDX components map
injects the resolved value into <Tabs> via a 'default' prop alias.
/langgraph-typescript/configurable opens TypeScript, /ms-agent-dotnet/
auth opens .NET, /langgraph-fastapi/deep-agents opens FastAPI. Slugs
and groupIds without a mapping fall through to the existing behavior
(author default, then first items label).

Author: samjulien

showcase/shell-docs/src/app/[framework]/[[...slug]]/page.tsx

@@ -29,7 +29,12 @@ import {
   loadDoc,
   type NavNode,
 } from "@/lib/docs-render";
-import { getIntegration, getIntegrations, type Integration } from "@/lib/registry";
+import {
+  getDocsFolder,
+  getIntegration,
+  getIntegrations,
+  type Integration,
+} from "@/lib/registry";
 import { RESERVED_ROUTE_SLUGS } from "@/app/layout";
 import demoContent from "@/data/demo-content.json";
 
@@ -166,18 +171,26 @@ export default async function FrameworkScopedDocsPage({
   //      render a "not available for <framework>" fallback inside the
   //      docs shell (handled below, after the nav is built).
   //   4. Otherwise 404.
+  // Most registry slugs map 1:1 to a folder under `integrations/`, but
+  // language/runtime variants share a single docs folder:
+  // langgraph-python/typescript/fastapi → `langgraph/`, ms-agent-dotnet/
+  // python → `microsoft-agent-framework/`, plus legacy renames for
+  // google-adk → `adk/` and strands → `aws-strands/`. Resolve the URL
+  // slug to its docs folder before touching disk.
+  const docsFolder = getDocsFolder(framework);
+
   let contentSlugPath: string = slugPath;
   let doc = loadDoc(slugPath);
   if (!doc) {
-    const fallbackPath = `integrations/${framework}/${slugPath}`;
+    const fallbackPath = `integrations/${docsFolder}/${slugPath}`;
     doc = loadDoc(fallbackPath);
     if (doc) contentSlugPath = fallbackPath;
   }
 
   // Sidebar nav needs to render on both the happy path and the
   // "not available" fallback, so build it before branching.
   const rootNav = buildNavTree(CONTENT_DIR);
-  const overrideNav = buildFrameworkOverridesNav(framework);
+  const overrideNav = buildFrameworkOverridesNav(docsFolder);
   const navTree: NavNode[] = mergeFrameworkNav(
     rootNav,
     overrideNav,
@@ -192,7 +205,11 @@ export default async function FrameworkScopedDocsPage({
     // user keeps their framework context and gets a clear path
     // forward. Only 404 when the slug is unknown everywhere.
     const allFrameworkSlugs = getIntegrations().map((i) => i.slug);
-    const availableIn = findFrameworksWithPage(slugPath, allFrameworkSlugs);
+    const availableIn = findFrameworksWithPage(
+      slugPath,
+      allFrameworkSlugs,
+      getDocsFolder,
+    );
     if (availableIn.length > 0) {
       return (
         <NotAvailableForFrameworkPage
@@ -287,9 +304,10 @@ function FrameworkLandingPage({ framework }: { framework: string }) {
   const integration = getIntegration(framework);
   if (!integration) notFound();
 
-  // Same nav merge as the scoped-page route.
+  // Same nav merge as the scoped-page route. Resolve the URL slug to
+  // its docs folder — see comment in FrameworkScopedDocsPage above.
   const rootNav = buildNavTree(CONTENT_DIR);
-  const overrideNav = buildFrameworkOverridesNav(framework);
+  const overrideNav = buildFrameworkOverridesNav(getDocsFolder(framework));
   const tree = mergeFrameworkNav(rootNav, overrideNav, integration.name);
 
   return (

showcase/shell-docs/src/components/docs-page-view.tsx

@@ -17,7 +17,9 @@ import { SidebarLink } from "@/components/sidebar-link";
 import { SidebarFrameworkSelector } from "@/components/sidebar-framework-selector";
 import { Snippet } from "@/components/snippet";
 import { DocsToc } from "@/components/docs-toc";
+import { Tabs as DocsTabs } from "@/components/docs-tabs";
 import { docsComponents } from "@/lib/mdx-registry";
+import { getTabDefault } from "@/lib/registry";
 import {
   NavNode,
   buildBreadcrumbs,
@@ -235,6 +237,37 @@ export async function DocsPageView({
                           defaultCell={defaultCell}
                         />
                       ),
+                      // MDX pages author in-page variant selectors as
+                      // `<Tabs groupId="language_langgraph_agent" default="Python">`.
+                      // When the URL scope is a specific variant (e.g.
+                      // `/langgraph-typescript/*`), pre-select the
+                      // matching tab instead of the author's hardcoded
+                      // default so the code visible on arrival matches
+                      // the URL the user followed. Slugs without a
+                      // mapping (or tabs whose groupId isn't listed in
+                      // TAB_DEFAULTS_BY_SLUG) fall through to the MDX
+                      // `default` and the component's first-label
+                      // fallback unchanged.
+                      Tabs: (props: {
+                        groupId?: string;
+                        default?: string;
+                        items?: string[];
+                        children?: React.ReactNode;
+                        persist?: boolean;
+                      }) => {
+                        const urlDefault = getTabDefault(
+                          frameworkOverride ?? null,
+                          props.groupId,
+                        );
+                        return (
+                          <DocsTabs
+                            {...props}
+                            default={urlDefault ?? props.default}
+                          >
+                            {props.children}
+                          </DocsTabs>
+                        );
+                      },
                       InlineDemo: (props: Record<string, unknown>) => {
                         const InlineDemoComp = docsComponents.InlineDemo;
                         return (

showcase/shell-docs/src/components/docs-tabs.tsx

@@ -17,7 +17,26 @@ import React, { useState, useMemo, Children, isValidElement } from "react";
 
 interface TabsProps {
   items?: string[];
+  /**
+   * Initial active tab label. MDX authors write `default="Python"`
+   * (fumadocs convention); we also accept `defaultValue` for
+   * programmatic callers. Either name resolves the same initial tab.
+   */
+  default?: string;
   defaultValue?: string;
+  /**
+   * Author-supplied tab-group identifier used to key tab state across
+   * pages (e.g. "language_langgraph_agent"). Accepted for MDX source
+   * compatibility; the per-page `<Tabs>` override injected by
+   * DocsPageView reads it to compute URL-variant-driven defaults.
+   * Currently no persistence implemented.
+   */
+  groupId?: string;
+  /**
+   * Accepted for MDX source compatibility — fumadocs' persistent-tab
+   * feature. Not yet implemented here.
+   */
+  persist?: boolean;
   children: React.ReactNode;
 }
 
@@ -27,7 +46,12 @@ interface TabProps {
   children?: React.ReactNode;
 }
 
-export function Tabs({ items, defaultValue, children }: TabsProps) {
+export function Tabs({
+  items,
+  default: defaultProp,
+  defaultValue,
+  children,
+}: TabsProps) {
   // Discover tab labels from children when `items` isn't provided.
   const kids = useMemo(() => {
     const list: { label: string; content: React.ReactNode }[] = [];
@@ -42,7 +66,7 @@ export function Tabs({ items, defaultValue, children }: TabsProps) {
 
   const labels = items ?? kids.map((k) => k.label);
   const [active, setActive] = useState<string>(
-    defaultValue ?? labels[0] ?? "Tab",
+    defaultValue ?? defaultProp ?? labels[0] ?? "Tab",
   );
 
   return (

showcase/shell-docs/src/lib/docs-render.tsx

@@ -289,37 +289,34 @@ export function buildNavTreeFromFilesystem(
 }
 
 /**
- * Walk `content/docs/integrations/<framework>/` and return NavNodes for
- * pages that have NO root equivalent. These are framework-specific topics
- * (e.g. Built-in Agent's `copilot-runtime`, `server-tools`) that live
- * only in the per-framework tree and need their own sidebar entries.
- * Pages that duplicate root files are skipped — root wins, and the
- * framework view already renders the root MDX with a framework override.
+ * Walk `content/docs/integrations/<folder>/` and return NavNodes for
+ * pages that have NO root equivalent. These are framework-specific
+ * topics (e.g. Built-in Agent's `copilot-runtime`, LangGraph's `auth`
+ * and `subgraphs`) that live only in the per-framework tree and need
+ * their own sidebar entries. Pages that duplicate root files are
+ * skipped — root wins, and the framework view already renders the
+ * root MDX with a framework override.
+ *
+ * Takes the resolved folder name (not the URL slug). Callers should
+ * use `getDocsFolder(slug)` from lib/registry to map language/runtime
+ * variants to their shared folder (e.g. langgraph-python / typescript
+ * / fastapi → `langgraph/`).
  */
-export function buildFrameworkOverridesNav(framework: string): NavNode[] {
-  const frameworkDir = path.join(
-    CONTENT_DIR,
-    "integrations",
-    framework,
-  );
+export function buildFrameworkOverridesNav(folder: string): NavNode[] {
+  const frameworkDir = path.join(CONTENT_DIR, "integrations", folder);
   if (!fs.existsSync(frameworkDir)) return [];
-  const nodes = buildNavTree(
-    frameworkDir,
-    `integrations/${framework}`,
-  );
+  const nodes = buildNavTree(frameworkDir, `integrations/${folder}`);
 
   // Drop entries whose equivalent root file exists. Root wins when
   // both are present — the per-framework tree is only an escape hatch
   // for framework-specific topics, not an alternative rendering.
+  const prefix = `integrations/${folder}/`;
   const filtered: NavNode[] = [];
   for (const node of nodes) {
     if (node.type === "page") {
-      // node.slug looks like `integrations/<framework>/<topic>`.
-      // Strip the prefix to check the root-level equivalent.
-      const rootSlug = node.slug.replace(
-        `integrations/${framework}/`,
-        "",
-      );
+      // node.slug looks like `integrations/<folder>/<topic>`. Strip
+      // the prefix to check the root-level equivalent.
+      const rootSlug = node.slug.replace(prefix, "");
       const rootMdx = path.join(CONTENT_DIR, `${rootSlug}.mdx`);
       const rootIndex = path.join(CONTENT_DIR, rootSlug, "index.mdx");
       if (fs.existsSync(rootMdx) || fs.existsSync(rootIndex)) continue;
@@ -328,23 +325,19 @@ export function buildFrameworkOverridesNav(framework: string): NavNode[] {
       filtered.push({ ...node, slug: rootSlug });
     } else if (node.type === "group") {
       // Recursively filter children of a group.
-      const children = node.children.filter((c) => {
-        if (c.type !== "page") return true;
-        const rootSlug = c.slug.replace(
-          `integrations/${framework}/`,
-          "",
+      const children = node.children
+        .filter((c) => {
+          if (c.type !== "page") return true;
+          const rootSlug = c.slug.replace(prefix, "");
+          const rootMdx = path.join(CONTENT_DIR, `${rootSlug}.mdx`);
+          const rootIndex = path.join(CONTENT_DIR, rootSlug, "index.mdx");
+          return !fs.existsSync(rootMdx) && !fs.existsSync(rootIndex);
+        })
+        .map((c) =>
+          c.type === "page"
+            ? { ...c, slug: c.slug.replace(prefix, "") }
+            : c,
         );
-        const rootMdx = path.join(CONTENT_DIR, `${rootSlug}.mdx`);
-        const rootIndex = path.join(CONTENT_DIR, rootSlug, "index.mdx");
-        return !fs.existsSync(rootMdx) && !fs.existsSync(rootIndex);
-      }).map((c) =>
-        c.type === "page"
-          ? {
-              ...c,
-              slug: c.slug.replace(`integrations/${framework}/`, ""),
-            }
-          : c,
-      );
       if (children.length > 0) {
         filtered.push({ ...node, children });
       }
@@ -360,29 +353,38 @@ export function buildFrameworkOverridesNav(framework: string): NavNode[] {
 }
 
 /**
- * Return the list of framework slugs whose `integrations/<framework>/`
+ * Return the list of framework slugs whose `integrations/<folder>/`
  * tree contains an MDX file for `slugPath`. Matches either
  * `<slug>.mdx` or `<slug>/index.mdx`. Used by the framework-scoped
  * router to detect that a topic is available in *some* framework but
  * not the one the user is currently viewing, so we can render a
  * helpful "not available for <X>" page instead of a bare 404.
+ *
+ * Most slugs map 1:1 to their folder, but language/runtime variants
+ * share one folder (langgraph-python/typescript/fastapi → `langgraph/`,
+ * ms-agent-dotnet/python → `microsoft-agent-framework/`) and two
+ * legacy slugs were renamed after the folder existed (google-adk →
+ * `adk/`, strands → `aws-strands/`). The caller supplies the
+ * slug→folder resolver so this module stays registry-free.
  */
 export function findFrameworksWithPage(
   slugPath: string,
   integrationSlugs: readonly string[],
+  slugToFolder: (slug: string) => string,
 ): string[] {
   const matches: string[] = [];
   for (const slug of integrationSlugs) {
+    const folder = slugToFolder(slug);
     const mdx = path.join(
       CONTENT_DIR,
       "integrations",
-      slug,
+      folder,
       `${slugPath}.mdx`,
     );
     const indexMdx = path.join(
       CONTENT_DIR,
       "integrations",
-      slug,
+      folder,
       slugPath,
       "index.mdx",
     );

showcase/shell-docs/src/lib/registry.ts

@@ -73,6 +73,78 @@ export function getIntegration(slug: string): Integration | undefined {
   return registry.integrations.find((i) => i.slug === slug);
 }
 
+/**
+ * Maps a registry slug to the `integrations/<folder>/` directory name
+ * that holds its framework-unique docs content. Most slugs match their
+ * folder 1:1. These overrides exist because:
+ *
+ * - Three LangChain/LangGraph URL variants (`-python`, `-typescript`,
+ *   `-fastapi`) read from one shared `langgraph/` tree, with
+ *   in-page `<Tabs>` and `<TailoredContent>` handling the per-variant
+ *   code examples. The URL slug determines which tab opens by default
+ *   (see TAB_DEFAULTS_BY_SLUG below).
+ * - `microsoft-agent-framework/` serves both `ms-agent-dotnet` and
+ *   `ms-agent-python`, same in-page-tabs pattern.
+ * - `google-adk` / `strands` are legacy renames — the slug changed in
+ *   the registry but the docs folder still uses the earlier name.
+ *
+ * Unlisted slugs default to the slug itself, so registry entries
+ * whose folder already matches their slug need no entry here.
+ */
+const DOCS_FOLDER_OVERRIDES: Record<string, string> = {
+  "langgraph-python": "langgraph",
+  "langgraph-typescript": "langgraph",
+  "langgraph-fastapi": "langgraph",
+  "google-adk": "adk",
+  "strands": "aws-strands",
+  "ms-agent-dotnet": "microsoft-agent-framework",
+  "ms-agent-python": "microsoft-agent-framework",
+};
+
+export function getDocsFolder(slug: string): string {
+  return DOCS_FOLDER_OVERRIDES[slug] ?? slug;
+}
+
+/**
+ * Per-slug default-tab selections for the in-page `<Tabs>` component,
+ * keyed by the MDX `groupId` prop. When a page renders under one of
+ * these slugs, any tab whose `groupId` matches opens with the mapped
+ * value pre-selected — so `/langgraph-typescript/configurable` opens
+ * the TypeScript tab, `/ms-agent-dotnet/auth` opens .NET, etc.
+ *
+ * The MDX still authors `items={['Python', 'TypeScript']}` once; only
+ * the initially-selected label differs per URL variant. Unmapped
+ * slugs, or tabs with a `groupId` not listed here, fall back to the
+ * component's existing behavior (first label wins).
+ */
+const TAB_DEFAULTS_BY_SLUG: Record<string, Record<string, string>> = {
+  "langgraph-python": {
+    language_langgraph_agent: "Python",
+    deployment_method: "LangSmith",
+  },
+  "langgraph-typescript": {
+    language_langgraph_agent: "TypeScript",
+  },
+  "langgraph-fastapi": {
+    language_langgraph_agent: "Python",
+    deployment_method: "FastAPI",
+  },
+  "ms-agent-dotnet": {
+    "language_microsoft-agent-framework_agent": ".NET",
+  },
+  "ms-agent-python": {
+    "language_microsoft-agent-framework_agent": "Python",
+  },
+};
+
+export function getTabDefault(
+  slug: string | null | undefined,
+  groupId: string | undefined,
+): string | undefined {
+  if (!slug || !groupId) return undefined;
+  return TAB_DEFAULTS_BY_SLUG[slug]?.[groupId];
+}
+
 export function getFeatures(): Feature[] {
   return registry.feature_registry.features;
 }