fix(showcase): restore authored shell-docs sidebar

Author: tylerslaton

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

@@ -23,9 +23,13 @@ import { ShellDocsLayout } from "@/components/shell-docs-layout";
 import { SidebarFrameworkSelector } from "@/components/sidebar-framework-selector";
 import { UnscopedDocsPage } from "@/components/unscoped-docs-page";
 import { FrameworkLogo } from "@/components/icons/framework-icons";
-import { buildFrameworkNav, loadDoc } from "@/lib/docs-render";
+import {
+  buildFrameworkNav,
+  buildFrameworkOnlyNav,
+  loadDoc,
+} from "@/lib/docs-render";
 import { navTreeToPageTree } from "@/lib/page-tree-bridge";
-import { getDocsFolder, getIntegration } from "@/lib/registry";
+import { getDocsFolder, getDocsMode, getIntegration } from "@/lib/registry";
 import { buildDocMetadata } from "@/lib/seo-metadata";
 
 // Force dynamic rendering so unknown slugs reliably return HTTP 404
@@ -78,16 +82,14 @@ export async function generateMetadata({
 
 function DocsOverview() {
   // Sidebar matches the soft-default framework so home `/` and
-  // post-click `/built-in-agent/...` views share the same merged IA used
-  // by every framework-scoped route.
+  // post-click `/built-in-agent/...` views share the same authored IA.
   const docsFolder = getDocsFolder(HOME_DEFAULT_FRAMEWORK);
   const integrationName =
     getIntegration(HOME_DEFAULT_FRAMEWORK)?.name ?? "Built-in Agent";
-  const navTree = buildFrameworkNav(
-    docsFolder,
-    integrationName,
-    HOME_DEFAULT_FRAMEWORK,
-  );
+  const navTree =
+    getDocsMode(HOME_DEFAULT_FRAMEWORK) === "authored"
+      ? buildFrameworkOnlyNav(docsFolder)
+      : buildFrameworkNav(docsFolder, integrationName, HOME_DEFAULT_FRAMEWORK);
   const pageTree = navTreeToPageTree(navTree, `/${HOME_DEFAULT_FRAMEWORK}`);
 
   // Rewrite the Introduction entry's URL from `/built-in-agent` (or

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

@@ -41,6 +41,7 @@ import { transformerMeta } from "@/lib/rehype-code-meta";
 import {
   CONTENT_DIR,
   buildFrameworkNav,
+  buildFrameworkOnlyNav,
   findFrameworksWithCell,
   findFrameworksWithPage,
   loadDoc,
@@ -270,7 +271,8 @@ export default async function FrameworkScopedDocsPage({
   // Content resolution order depends on docs_mode:
   //
   //   authored  — per-framework MDX wins for every slug. Authored pages
-  //               can replace root pages without changing sidebar IA.
+  //               can replace root pages while keeping the framework's
+  //               authored sidebar IA.
   //               Only fall back to root if the framework simply has no
   //               file for the requested slug (preserves the "shared"
   //               fallback for slugs the framework intentionally leaves
@@ -302,13 +304,13 @@ export default async function FrameworkScopedDocsPage({
     }
   }
 
-  // Sidebar IA is mode-independent: authored/generated controls which
-  // MDX file renders, not the user's navigation structure.
-  const navTree: NavNode[] = buildFrameworkNav(
-    docsFolder,
-    frameworkName,
-    framework,
-  );
+  // Authored integrations own their full docs tree and sidebar IA.
+  // Generated integrations use the root docs IA with a sparse
+  // framework-specific override section.
+  const navTree: NavNode[] =
+    docsMode === "authored"
+      ? buildFrameworkOnlyNav(docsFolder)
+      : buildFrameworkNav(docsFolder, frameworkName, framework);
 
   if (!doc) {
     // No root MDX and no override for this framework. If the topic
@@ -433,8 +435,9 @@ async function FrameworkRootPage({ framework }: { framework: string }) {
   // let the Tier 1/2/3 cascade below decide whether to render or 404.
   const integration = getIntegration(framework);
 
-  // Same nav merge as the scoped-page route. Resolve the URL slug to
-  // its docs folder — see comment in FrameworkScopedDocsPage above.
+  // Resolve the URL slug to its docs folder — see comment in
+  // FrameworkScopedDocsPage above. Authored frameworks get their own
+  // sidebar tree; generated frameworks get the merged root/override IA.
   // `getDocsFolder` already falls back to the slug itself when there's
   // no override, so it's safe for docs-only frameworks.
   const docsFolder = getDocsFolder(framework);
@@ -445,11 +448,10 @@ async function FrameworkRootPage({ framework }: { framework: string }) {
     frameworkOverviews[framework]?.frameworkName ??
     framework;
   const docsMode = getDocsMode(framework);
-  const navTree: NavNode[] = buildFrameworkNav(
-    docsFolder,
-    integrationName,
-    framework,
-  );
+  const navTree: NavNode[] =
+    docsMode === "authored"
+      ? buildFrameworkOnlyNav(docsFolder)
+      : buildFrameworkNav(docsFolder, integrationName, framework);
 
   // Tier 1: data-driven FrameworkOverview. ONLY for `generated` mode —
   // `authored` frameworks skip straight to Tier 2 so their ported

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

@@ -559,10 +559,9 @@ export function buildFrameworkOverridesNav(folder: string): NavNode[] {
 
 /**
  * Build a sidebar that contains ONLY the per-framework MDX tree
- * (no merge with root nav, no root-equivalent filtering). Retained for
- * diagnostics and any callers that need to inspect a package-owned IA
- * directly; framework routes use `buildFrameworkNav` so authored and
- * generated modes share the same sidebar structure.
+ * (no merge with root nav, no root-equivalent filtering). Authored
+ * integrations use this because their `integrations/<folder>/meta.json`
+ * is the source of truth for page order and section grouping.
  *
  * Slugs are rewritten to drop the `integrations/<folder>/` prefix and
  * the literal `index` → "" rewrite, so links resolve at
@@ -721,9 +720,9 @@ export function mergeFrameworkNav(
 }
 
 /**
- * Build the framework-scoped sidebar IA used by every framework route.
- * This is intentionally independent of docs_mode: generated/authored
- * controls MDX resolution, not navigation structure.
+ * Build the framework-scoped sidebar IA used by generated framework
+ * routes. Generated docs share the root docs IA and layer sparse
+ * framework-specific overrides into that tree.
  */
 export function buildFrameworkNav(
   docsFolder: string,

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

@@ -38,9 +38,10 @@ export interface Integration {
    * - `generated` (default): data-driven `FrameworkOverview` + agnostic
    *   root MDX merged with per-framework overrides. Kept for the three
    *   "ready" frameworks (langgraph-{python,typescript}, google-adk).
-   * - `authored`: render only the per-framework MDX tree under
+   * - `authored`: render the per-framework MDX tree under
    *   `content/docs/integrations/<docsFolder>/` with its own sidebar
-   *   (built from that folder's meta.json). No root-MDX fallback.
+   *   (built from that folder's meta.json). Root MDX may still be used
+   *   as a fallback for intentionally shared pages.
    * - `hidden`: exclude from the docs site entirely — no `/<slug>`
    *   route, no switcher entry. Single toggle for "framework has no
    *   v1 docs to port" (or otherwise should not appear in docs yet).