From 930a4165b74d51d26b0a3ae952be1088a8bf744f Mon Sep 17 00:00:00 2001
From: Anna Nguyen <anna.nguyen42@gmail.com>
Date: Thu, 10 Sep 2026 13:58:11 -0400
Subject: [PATCH 01/13] Anchor docs search and Ask AI in the toolbar.

Makes the Kapa assistant discoverable from the docs header and keeps the reading layout stable across regular and API pages.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 js/documentation/pages/_app.tsx               |  47 +++--
 js/documentation/pages/_document.tsx          |   5 +
 .../src/components/Breadcrumbs.tsx            |  97 ++++++++-
 .../src/components/DocsSearch.tsx             | 187 ++++++++++++++++++
 .../src/components/ExternalScripts.tsx        |  16 +-
 .../src/components/GlobalStyles.tsx           |   4 +-
 .../src/components/MainContent.tsx            |   9 +-
 js/documentation/src/components/PageGrid.tsx  |  81 +++++---
 .../src/components/PageHeader.tsx             |  22 ++-
 .../RestApiReference.styles.ts                |   9 +-
 .../RestApiReference/SidebarNav.tsx           |  64 ++++--
 .../src/components/RestApiReference/index.tsx | 158 +++++++--------
 js/documentation/src/components/SideNav.tsx   |  38 ++--
 .../src/components/TableOfContents.tsx        |  27 ++-
 .../src/components/types/window.d.ts          |   9 +-
 js/documentation/src/lib/kapa.ts              |  49 +++++
 16 files changed, 618 insertions(+), 204 deletions(-)
 create mode 100644 js/documentation/src/components/DocsSearch.tsx
 create mode 100644 js/documentation/src/lib/kapa.ts

diff --git a/js/documentation/pages/_app.tsx b/js/documentation/pages/_app.tsx
index 356ec612a1..573d77731f 100644
--- a/js/documentation/pages/_app.tsx
+++ b/js/documentation/pages/_app.tsx
@@ -42,6 +42,7 @@ import MainContent from '@src/components/MainContent'
 import PageFooter from '@src/components/PageFooter'
 import {
   ContentContainer,
+  MainColumn,
   PageGrid,
   SideCarContainer,
   SideNavContainer,
@@ -169,29 +170,33 @@ function App({ Component, pageProps = {}, swrConfig }: MyAppProps) {
                   <FullNav desktop />
                 )}
               </SideNavContainer>
-              <ContentContainer>
-                <MainContent
-                  Component={Component}
-                  title={displayTitle}
-                  description={displayDescription}
-                />
-                <PageFooter />
-              </ContentContainer>
-              <SideCarContainer>
-                {isClient ? (
-                  <Suspense fallback={<div>Loading table of contents...</div>}>
-                    <TableOfContents
-                      key={router.asPath}
-                      toc={toc}
-                    />
-                  </Suspense>
-                ) : (
-                  <TableOfContents
-                    key={router.asPath}
-                    toc={toc}
+              <MainColumn>
+                <ContentContainer>
+                  <MainContent
+                    Component={Component}
+                    title={displayTitle}
+                    description={displayDescription}
                   />
+                  <PageFooter />
+                </ContentContainer>
+                {toc?.length > 0 && (
+                  <SideCarContainer>
+                    {isClient ? (
+                      <Suspense fallback={<div>Loading table of contents...</div>}>
+                        <TableOfContents
+                          key={router.asPath}
+                          toc={toc}
+                        />
+                      </Suspense>
+                    ) : (
+                      <TableOfContents
+                        key={router.asPath}
+                        toc={toc}
+                      />
+                    )}
+                  </SideCarContainer>
                 )}
-              </SideCarContainer>
+              </MainColumn>
             </PageGrid>
           )}
         </Page>
diff --git a/js/documentation/pages/_document.tsx b/js/documentation/pages/_document.tsx
index 8245cf98de..1c2d464b1d 100644
--- a/js/documentation/pages/_document.tsx
+++ b/js/documentation/pages/_document.tsx
@@ -43,6 +43,11 @@ class MyDocument extends Document {
             type="text/javascript"
             data-widget-position="bottom-right"
           />
+          <script
+            dangerouslySetInnerHTML={{
+              __html: `window.Kapa=window.Kapa||function(){(window.Kapa.q=window.Kapa.q||[]).push(arguments)};`,
+            }}
+          />
           <script
             async
             src={`https://www.googletagmanager.com/gtag/js?id=${process.env.NEXT_PUBLIC_GA_ID}`}
diff --git a/js/documentation/src/components/Breadcrumbs.tsx b/js/documentation/src/components/Breadcrumbs.tsx
index a940ac1ade..a78a0af44d 100644
--- a/js/documentation/src/components/Breadcrumbs.tsx
+++ b/js/documentation/src/components/Breadcrumbs.tsx
@@ -1,14 +1,20 @@
 import { useMemo } from 'react'
 
-import { Breadcrumbs as BreadcrumbsComponent } from '@pluralsh/design-system'
+import NextLink from 'next/link'
 import { useRouter } from 'next/router'
+import styled from 'styled-components'
 
 import { useNavMenu } from '../contexts/NavDataContext'
 import { getBarePathFromPath, removeTrailingSlashes } from '../utils/text'
 
 import type { NavItem } from '../NavData'
 
-function findCrumbs(path, sections: NavItem[]) {
+export type DocsBreadcrumb = {
+  label: string
+  url?: string
+}
+
+function findCrumbs(path, sections: NavItem[]): DocsBreadcrumb[] {
   path = removeTrailingSlashes(path)
 
   for (const { title: label, href: url, sections: sects } of sections) {
@@ -25,20 +31,95 @@ function findCrumbs(path, sections: NavItem[]) {
   return []
 }
 
-export default function Breadcrumbs() {
+export default function Breadcrumbs({
+  breadcrumbs: breadcrumbsProp,
+}: {
+  breadcrumbs?: DocsBreadcrumb[]
+}) {
   const { asPath } = useRouter()
-
   const path = getBarePathFromPath(asPath)
   const navData = useNavMenu()
 
   const crumbs = useMemo(
-    () => [{ label: 'Docs', url: '/' }, ...findCrumbs(path, navData)],
-    [navData, path]
+    () =>
+      breadcrumbsProp ?? [
+        { label: 'Docs', url: '/' },
+        ...findCrumbs(path, navData),
+      ],
+    [breadcrumbsProp, navData, path]
   )
 
-  if (crumbs.length <= 1) {
+  if (crumbs.length === 0) {
     return null
   }
 
-  return <BreadcrumbsComponent breadcrumbs={crumbs ?? []} />
+  return (
+    <Nav aria-label="breadcrumbs">
+      <List>
+        {crumbs.map((crumb, index) => {
+          const isLast = index === crumbs.length - 1
+
+          return (
+            <Item key={`${crumb.label}-${crumb.url ?? index}`}>
+              {index > 0 && <Separator aria-hidden>/</Separator>}
+              {isLast || !crumb.url ? (
+                <Current aria-current="page">{crumb.label}</Current>
+              ) : (
+                <CrumbLink href={crumb.url}>{crumb.label}</CrumbLink>
+              )}
+            </Item>
+          )
+        })}
+      </List>
+    </Nav>
+  )
 }
+
+const Nav = styled.nav({
+  minWidth: 0,
+})
+
+const List = styled.ol(({ theme }) => ({
+  ...theme.partials.reset.list,
+  display: 'flex',
+  alignItems: 'center',
+  flexWrap: 'wrap',
+  gap: theme.spacing.xsmall,
+  minWidth: 0,
+}))
+
+const Item = styled.li(({ theme }) => ({
+  ...theme.partials.reset.li,
+  display: 'flex',
+  alignItems: 'center',
+  gap: theme.spacing.xsmall,
+  minWidth: 0,
+}))
+
+const Separator = styled.span(({ theme }) => ({
+  ...theme.partials.text.body2,
+  color: theme.colors['text-input-disabled'],
+  userSelect: 'none',
+}))
+
+const crumbText = ({ theme }) => ({
+  ...theme.partials.text.body2,
+  overflow: 'hidden',
+  textOverflow: 'ellipsis',
+  whiteSpace: 'nowrap',
+})
+
+const CrumbLink = styled(NextLink)(({ theme }) => ({
+  ...crumbText({ theme }),
+  color: theme.colors['text-xlight'],
+  textDecoration: 'none',
+  '&:hover': {
+    color: theme.colors.text,
+  },
+}))
+
+const Current = styled.span(({ theme }) => ({
+  ...crumbText({ theme }),
+  color: theme.colors.text,
+  fontWeight: 600,
+}))
diff --git a/js/documentation/src/components/DocsSearch.tsx b/js/documentation/src/components/DocsSearch.tsx
new file mode 100644
index 0000000000..4f25c198e0
--- /dev/null
+++ b/js/documentation/src/components/DocsSearch.tsx
@@ -0,0 +1,187 @@
+import {
+  AiSparkleFilledIcon,
+  Button,
+  IconFrame,
+  SearchIcon,
+} from '@pluralsh/design-system'
+import styled from 'styled-components'
+
+import { openKapa } from '@src/lib/kapa'
+
+import { mqs } from './Breakpoints'
+
+function SearchTrigger({ compact = false }: { compact?: boolean }) {
+  if (compact) {
+    return (
+      <IconFrame
+        clickable
+        size="large"
+        type="floating"
+        tooltip="Search docs"
+        icon={<SearchIcon size={16} />}
+        onClick={() => openKapa('search')}
+        className="docs-search-trigger"
+      />
+    )
+  }
+
+  return (
+    <SearchBar
+      type="button"
+      className="docs-search-trigger"
+      onClick={() => openKapa('search')}
+      aria-label="Search docs"
+    >
+      <SearchIcon
+        size={16}
+        className="searchIcon"
+      />
+      <span className="placeholder">Search docs...</span>
+      <Kbd>⌘K</Kbd>
+    </SearchBar>
+  )
+}
+
+function AskAiTrigger({ compact = false }: { compact?: boolean }) {
+  if (compact) {
+    return (
+      <IconFrame
+        clickable
+        size="large"
+        type="secondary"
+        tooltip="Ask AI"
+        icon={<AiSparkleFilledIcon size={16} />}
+        onClick={() => openKapa('ai')}
+        className="docs-ai-trigger"
+      />
+    )
+  }
+
+  return (
+    <AskAiButton
+      className="docs-ai-trigger"
+      secondary
+      startIcon={<AiSparkleFilledIcon size={16} />}
+      onClick={() => openKapa('ai')}
+    >
+      Ask AI
+    </AskAiButton>
+  )
+}
+
+export function DocsSearch() {
+  return (
+    <>
+      <CenterCluster>
+        <SearchTrigger />
+        <WideAskAi>
+          <AskAiTrigger />
+        </WideAskAi>
+        <NarrowAskAi>
+          <AskAiTrigger compact />
+        </NarrowAskAi>
+      </CenterCluster>
+      <ToolbarCluster>
+        <SearchTrigger compact />
+        <AskAiTrigger compact />
+      </ToolbarCluster>
+    </>
+  )
+}
+
+const AskAiButton = styled(Button)({
+  height: 40,
+  minHeight: 40,
+})
+
+const SearchBar = styled.button(({ theme }) => ({
+  display: 'flex',
+  alignItems: 'center',
+  gap: theme.spacing.small,
+  width: 220,
+  [mqs.threeColumn]: {
+    width: 360,
+    maxWidth: '32vw',
+  },
+  height: 40,
+  padding: `0 ${theme.spacing.xsmall}px 0 ${theme.spacing.medium}px`,
+  border: theme.borders.input,
+  borderRadius: theme.borderRadiuses.medium,
+  background: theme.colors['fill-one'],
+  color: theme.colors['text-xlight'],
+  cursor: 'pointer',
+  ...theme.partials.text.body2,
+  '.searchIcon': {
+    flexShrink: 0,
+    color: theme.colors['text-light'],
+  },
+  '.placeholder': {
+    flex: 1,
+    minWidth: 0,
+    textAlign: 'left',
+    overflow: 'hidden',
+    textOverflow: 'ellipsis',
+    whiteSpace: 'nowrap',
+  },
+  '&:hover': {
+    background: theme.colors['fill-one-hover'],
+    color: theme.colors['text-light'],
+  },
+  '&:focus, &:focus-visible': {
+    outline: 'none',
+  },
+  '&:focus-visible': {
+    ...theme.partials.focus.default,
+  },
+}))
+
+const Kbd = styled.span(({ theme }) => ({
+  ...theme.partials.text.caption,
+  display: 'inline-flex',
+  alignItems: 'center',
+  justifyContent: 'center',
+  flexShrink: 0,
+  minWidth: 28,
+  height: 22,
+  padding: `0 ${theme.spacing.xsmall}px`,
+  borderRadius: theme.borderRadiuses.medium,
+  background: theme.colors['fill-two'],
+  color: theme.colors['text-xlight'],
+}))
+
+const CenterCluster = styled.div(({ theme }) => ({
+  display: 'none',
+  [mqs.fullHeader]: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: theme.spacing.small,
+    position: 'absolute',
+    left: '50%',
+    top: '50%',
+    transform: 'translate(-50%, -50%)',
+    zIndex: 1,
+  },
+}))
+
+const ToolbarCluster = styled.div(({ theme }) => ({
+  display: 'flex',
+  alignItems: 'center',
+  gap: theme.spacing.xsmall,
+  [mqs.fullHeader]: {
+    display: 'none',
+  },
+}))
+
+const WideAskAi = styled.div({
+  display: 'none',
+  [mqs.threeColumn]: {
+    display: 'block',
+  },
+})
+
+const NarrowAskAi = styled.div({
+  display: 'block',
+  [mqs.threeColumn]: {
+    display: 'none',
+  },
+})
diff --git a/js/documentation/src/components/ExternalScripts.tsx b/js/documentation/src/components/ExternalScripts.tsx
index daad5052d6..0d6b7ce632 100644
--- a/js/documentation/src/components/ExternalScripts.tsx
+++ b/js/documentation/src/components/ExternalScripts.tsx
@@ -102,13 +102,27 @@ function KapaWidget() {
       src="https://widget.kapa.ai/kapa-widget.bundle.js"
       data-website-id="8288b978-8aca-4409-9cbd-de12c446cf07"
       data-project-name="Plural"
-      data-view-mode="sidebar"
+      data-view-mode="default"
+      data-button-hide="true"
+      data-launcher-button-hidden="true"
       data-modal-open-on-command-k="true"
+      data-modal-command-k-search-mode-default="true"
       data-search-mode-enabled="true"
+      data-modal-override-open-selector-search=".docs-search-trigger"
+      data-modal-override-open-selector=".docs-ai-trigger"
       data-mcp-enabled="true"
       data-mcp-server-url="https://plural.mcp.kapa.ai"
       data-project-color="#5D63F4"
       data-project-logo="https://docs.plural.sh/favicon-192.png"
+      data-kapa-branding-hidden="true"
+      data-color-scheme="dark"
+      data-surface-color-dark="#12151B"
+      data-surface-elevated-color-dark="#1B1F27"
+      data-surface-hover-color-dark="#252932"
+      data-text-color-dark="#EEF0F1"
+      data-text-muted-color-dark="#A1A5B0"
+      data-border-color-dark="#303540"
+      data-anchor-color-dark="#5D63F4"
     />
   )
 }
diff --git a/js/documentation/src/components/GlobalStyles.tsx b/js/documentation/src/components/GlobalStyles.tsx
index 2f7704bf84..b74c552985 100644
--- a/js/documentation/src/components/GlobalStyles.tsx
+++ b/js/documentation/src/components/GlobalStyles.tsx
@@ -22,6 +22,8 @@ const GlobalStyles = createGlobalStyle(({ theme }) => ({
   ':root': {
     '--top-nav-height': '72px',
     '--menu-extra-bpad': '0px',
+    '--docs-sidenav-width': '306px',
+    '--docs-sidecar-width': '220px',
   },
   'a:any-link': {
     color: 'unset',
@@ -39,7 +41,7 @@ const GlobalStyles = createGlobalStyle(({ theme }) => ({
   },
   body: {
     margin: 0,
-    overflowX: 'hidden',
+    overflowX: 'clip',
     color: theme.colors.text,
     backgroundColor: theme.colors['fill-zero'],
     ...fillAvailable('minHeight'),
diff --git a/js/documentation/src/components/MainContent.tsx b/js/documentation/src/components/MainContent.tsx
index e2f32fbdc2..4b5df1280d 100644
--- a/js/documentation/src/components/MainContent.tsx
+++ b/js/documentation/src/components/MainContent.tsx
@@ -15,12 +15,15 @@ import Breadcrumbs from './Breadcrumbs'
 import { FooterLink } from './PageFooter'
 import { PagePropsContext } from './PagePropsContext'
 
-const ContentWrapper = styled.div(({ theme }) => ({
-  marginTop: theme.spacing.xlarge,
+const ContentWrapper = styled.div((_) => ({
+  minWidth: 0,
 }))
 
 const BreadcrumbsWrapper = styled.div(({ theme }) => ({
-  marginTop: theme.spacing.xlarge,
+  display: 'flex',
+  alignItems: 'center',
+  minHeight: 40,
+  marginBottom: theme.spacing.large,
 }))
 
 const Title = styled.h1(({ theme }) => ({
diff --git a/js/documentation/src/components/PageGrid.tsx b/js/documentation/src/components/PageGrid.tsx
index e34243bb9a..d8493a92dd 100644
--- a/js/documentation/src/components/PageGrid.tsx
+++ b/js/documentation/src/components/PageGrid.tsx
@@ -2,23 +2,37 @@ import styled from 'styled-components'
 
 import { mqs } from './Breakpoints'
 
-export const PageGrid = styled.div((_p) => ({
-  display: 'flex',
-  flexDirection: 'row',
+export const PageGrid = styled.div({
+  display: 'grid',
+  gridTemplateColumns: 'minmax(0, 1fr)',
   width: '100%',
-  maxWidth: 1588,
-  marginLeft: 'auto',
-  marginRight: 'auto',
-  position: 'relative',
-}))
+  minHeight: 'calc(100vh - var(--top-nav-height))',
+  [mqs.twoColumn]: {
+    gridTemplateColumns: 'var(--docs-sidenav-width) minmax(0, 1fr)',
+  },
+})
 
 export const SideNavContainer = styled.div(({ theme }) => ({
   display: 'none',
   [mqs.twoColumn]: {
     display: 'block',
-    flex: '0 0 300px',
-    marginRight: 'auto',
-    marginLeft: theme.spacing.large,
+    minWidth: 0,
+    backgroundColor: theme.colors['fill-one'],
+  },
+}))
+
+export const MainColumn = styled.div(({ theme }) => ({
+  display: 'flex',
+  justifyContent: 'center',
+  alignItems: 'flex-start',
+  minWidth: 0,
+  width: '100%',
+  padding: `0 ${theme.spacing.large}px`,
+  [mqs.twoColumn]: {
+    padding: `0 ${theme.spacing.xlarge}px`,
+  },
+  [mqs.maxWidth]: {
+    padding: '0 64px',
   },
 }))
 
@@ -27,25 +41,38 @@ export const SideCarContainer = styled.div(({ theme }) => ({
 
   [mqs.threeColumn]: {
     position: 'sticky',
-    marginRight: theme.spacing.large,
     top: 'var(--top-nav-height)',
-    bottom: 0,
+    alignSelf: 'flex-start',
+    flex: '0 0 var(--docs-sidecar-width)',
+    width: 'var(--docs-sidecar-width)',
     maxHeight: 'calc(100vh - var(--top-nav-height))',
-    flex: '0 0 200px',
+    overflow: 'auto',
     display: 'block',
-  },
-}))
-
-export const ContentContainer = styled.main(({ theme }) => ({
-  flex: '1 1',
-  marginRight: theme.spacing.large,
-  marginLeft: theme.spacing.large,
-  // Don't remove this min width, or it will paradoxically allow
-  // the content to stretch wider than the flex container
-  minWidth: '100px',
-  [mqs.threeColumn]: {
-    maxWidth: 896,
-    marginRight: theme.spacing.xlarge,
     marginLeft: theme.spacing.xlarge,
   },
 }))
+
+export const ContentContainer = styled.main<{ $wide?: boolean }>(
+  ({ theme, $wide }) => ({
+    flex: '1 1 auto',
+    minWidth: 0,
+    width: '100%',
+    padding: `${theme.spacing.medium}px 0 ${theme.spacing.xxxlarge}px`,
+    ...(!$wide
+      ? {
+          maxWidth: 896,
+          [mqs.threeColumn]: {
+            maxWidth: 960,
+          },
+          [mqs.maxWidth]: {
+            maxWidth: 1120,
+          },
+        }
+      : {
+          maxWidth: 1120,
+          [mqs.maxWidth]: {
+            maxWidth: 1280,
+          },
+        }),
+  })
+)
diff --git a/js/documentation/src/components/PageHeader.tsx b/js/documentation/src/components/PageHeader.tsx
index c431373c38..2013fd2a2e 100644
--- a/js/documentation/src/components/PageHeader.tsx
+++ b/js/documentation/src/components/PageHeader.tsx
@@ -10,6 +10,7 @@ import styled from 'styled-components'
 import { DISCORD_LINK } from '@src/consts'
 
 import { BreakpointIsGreaterOrEqual, mqs, useBreakpoint } from './Breakpoints'
+import { DocsSearch } from './DocsSearch'
 import GithubStars from './GithubStars'
 import MobileMenu from './MobileMenu'
 import { HamburgerButton, SocialLink } from './PageHeaderButtons'
@@ -59,6 +60,7 @@ function PageHeaderUnstyled({ ...props }) {
       </nav>
       <Filler />
       <section className="rightSection">
+        <DocsSearch />
         <div className="socialIcons">
           <SocialLink
             className="discordIcon"
@@ -112,15 +114,16 @@ const PageHeader = styled(PageHeaderUnstyled)(({ theme }) => ({
   display: 'flex',
   alignItems: 'center',
   justifyContent: 'left',
-  paddingLeft: theme.spacing.large,
+  paddingLeft: 40,
   paddingRight: theme.spacing.large,
+  borderBottom: theme.borders['fill-one'],
   [mqs.fullHeader]: {
-    paddingLeft: 40,
+    paddingLeft: 0,
     paddingRight: 40,
   },
   '.socialIcons': {
     display: 'none',
-    [mqs.fullHeader]: {
+    [mqs.maxWidth]: {
       display: 'flex',
       flexDirection: 'row',
       gap: theme.spacing.medium,
@@ -136,11 +139,18 @@ const PageHeader = styled(PageHeaderUnstyled)(({ theme }) => ({
   },
   '.logo': {
     width: 162,
+    display: 'block',
+  },
+  '.leftSection': {
+    display: 'flex',
+    alignItems: 'center',
+    gap: theme.spacing.medium,
     [mqs.fullHeader]: {
-      // width: 216,
+      paddingLeft: 40,
+      paddingRight: theme.spacing.large,
     },
   },
-  '.rightSection, .leftSection': {
+  '.rightSection': {
     display: 'flex',
     alignItems: 'center',
     gap: theme.spacing.medium,
@@ -171,7 +181,7 @@ const PageHeaderLinks = styled(({ ...props }) => (
   </div>
 ))(({ theme }) => ({
   display: 'none',
-  [mqs.fullHeader]: {
+  [mqs.threeColumn]: {
     display: 'flex',
     gap: theme.spacing.xsmall,
   },
diff --git a/js/documentation/src/components/RestApiReference/RestApiReference.styles.ts b/js/documentation/src/components/RestApiReference/RestApiReference.styles.ts
index f910316297..97b65fd2c7 100644
--- a/js/documentation/src/components/RestApiReference/RestApiReference.styles.ts
+++ b/js/documentation/src/components/RestApiReference/RestApiReference.styles.ts
@@ -2,13 +2,14 @@ import styled from 'styled-components'
 
 // ─── Content layout (uses shared PageGrid from PageGrid.tsx) ───────────────────
 
-export const RestContentWrapper = styled.div(({ theme }) => ({
-  marginTop: theme.spacing.xlarge,
-  padding: `0 ${theme.spacing.xlarge}px`,
+export const RestContentWrapper = styled.div((_) => ({
+  minWidth: 0,
 }))
 
 export const BreadcrumbsWrapper = styled.div(({ theme }) => ({
-  marginTop: theme.spacing.xlarge,
+  display: 'flex',
+  alignItems: 'center',
+  minHeight: 40,
   marginBottom: theme.spacing.large,
 }))
 
diff --git a/js/documentation/src/components/RestApiReference/SidebarNav.tsx b/js/documentation/src/components/RestApiReference/SidebarNav.tsx
index 6d8f78f00f..6aa0d4e58c 100644
--- a/js/documentation/src/components/RestApiReference/SidebarNav.tsx
+++ b/js/documentation/src/components/RestApiReference/SidebarNav.tsx
@@ -5,6 +5,7 @@
 
 import { useMemo, useState } from 'react'
 
+import { CloseIcon } from '@pluralsh/design-system'
 import NextLink from 'next/link'
 
 import isEmpty from 'lodash/isEmpty'
@@ -18,7 +19,7 @@ const Sidebar = styled.aside(({ theme: _theme }) => ({
   position: 'sticky',
   top: 'var(--top-nav-height)',
   height: 'calc(100vh - var(--top-nav-height))',
-  width: 300,
+  width: '100%',
   flexShrink: 0,
   display: 'flex',
   flexDirection: 'column',
@@ -33,12 +34,14 @@ const SidebarInner = styled.div(({ theme }) => ({
   bottom: 0,
   overflowY: 'auto',
   backgroundColor: theme.colors['fill-one'],
-  borderRight: theme.borders.default,
+  borderRight: theme.borders['fill-one'],
   paddingBottom: theme.spacing.xlarge,
+  paddingLeft: theme.spacing.medium,
+  paddingRight: theme.spacing.medium,
 }))
 
 const SearchWrapper = styled.div(({ theme }) => ({
-  padding: `${theme.spacing.medium}px ${theme.spacing.medium}px`,
+  padding: `${theme.spacing.medium}px 0`,
   position: 'sticky',
   top: 0,
   backgroundColor: theme.colors['fill-one'],
@@ -62,12 +65,42 @@ const SearchInput = styled.div(({ theme }) => ({
   },
   input: {
     flex: 1,
+    minWidth: 0,
     background: 'transparent',
     border: 'none',
     outline: 'none',
     color: theme.colors.text,
     ...theme.partials.text.body2,
     '::placeholder': { color: theme.colors['text-xlight'] },
+    '&::-webkit-search-decoration, &::-webkit-search-cancel-button': {
+      WebkitAppearance: 'none',
+      appearance: 'none',
+      display: 'none',
+    },
+    '&::-ms-clear': {
+      display: 'none',
+      width: 0,
+      height: 0,
+    },
+  },
+}))
+
+const ClearButton = styled.button(({ theme }) => ({
+  display: 'flex',
+  alignItems: 'center',
+  justifyContent: 'center',
+  flexShrink: 0,
+  width: 20,
+  height: 20,
+  padding: 0,
+  border: 'none',
+  borderRadius: '50%',
+  background: theme.colors['fill-three'] ?? theme.colors['fill-two'],
+  color: theme.colors['text-xlight'],
+  cursor: 'pointer',
+  '&:hover': {
+    color: theme.colors.text,
+    background: theme.colors['fill-two-hover'] ?? theme.colors['fill-one-hover'],
   },
 }))
 
@@ -94,7 +127,7 @@ const EndpointLabel = styled.span(({ theme }) => ({
   textOverflow: 'ellipsis',
   whiteSpace: 'nowrap',
   ...theme.partials.text.body2,
-  color: theme.colors['text-light'],
+  color: theme.colors['text-xlight'],
 }))
 
 const EndpointRowLink = styled(NextLink)<{ $active: boolean }>(
@@ -110,10 +143,7 @@ const EndpointRowLink = styled(NextLink)<{ $active: boolean }>(
     textAlign: 'left',
     textDecoration: 'none',
     color: 'inherit',
-    borderStartStartRadius: theme.borderRadiuses.medium,
-    borderEndStartRadius: theme.borderRadiuses.medium,
-    borderStartEndRadius: 0,
-    borderEndEndRadius: 0,
+    borderRadius: theme.borderRadiuses.medium,
     backgroundColor: $active ? theme.colors['action-primary'] : 'transparent',
     '&:hover': {
       backgroundColor: $active
@@ -167,12 +197,9 @@ const TopNavItemLink = styled(NextLink)<{ $active: boolean }>(
     cursor: 'pointer',
     textAlign: 'left',
     textDecoration: 'none',
-    borderStartStartRadius: theme.borderRadiuses.medium,
-    borderEndStartRadius: theme.borderRadiuses.medium,
-    borderStartEndRadius: 0,
-    borderEndEndRadius: 0,
+    borderRadius: theme.borderRadiuses.medium,
     backgroundColor: $active ? theme.colors['action-primary'] : 'transparent',
-    color: $active ? theme.colors.text : theme.colors['text-light'],
+    color: $active ? theme.colors.text : theme.colors['text-xlight'],
     '&:hover': {
       backgroundColor: $active
         ? theme.colors['action-primary-hover']
@@ -231,12 +258,21 @@ export function SidebarNav({
               <SearchIcon />
             </span>
             <input
-              type="search"
+              type="text"
               placeholder="Filter API"
               value={filter}
               onChange={(e) => setFilter(e.target.value)}
               aria-label="Filter API endpoints"
             />
+            {filter && (
+              <ClearButton
+                type="button"
+                aria-label="Clear filter"
+                onClick={() => setFilter('')}
+              >
+                <CloseIcon size={10} />
+              </ClearButton>
+            )}
           </SearchInput>
         </SearchWrapper>
         <nav aria-label="REST API endpoints">
diff --git a/js/documentation/src/components/RestApiReference/index.tsx b/js/documentation/src/components/RestApiReference/index.tsx
index 47ba92f2d5..50f21de204 100644
--- a/js/documentation/src/components/RestApiReference/index.tsx
+++ b/js/documentation/src/components/RestApiReference/index.tsx
@@ -6,15 +6,14 @@
 
 import { useMemo, useState } from 'react'
 
-import { Breadcrumbs, CheckIcon, CopyIcon, Tab } from '@pluralsh/design-system'
+import { CheckIcon, CopyIcon, Tab } from '@pluralsh/design-system'
 import { useRouter } from 'next/router'
 
-import styled from 'styled-components'
-
-import { mqs } from '@src/components/Breakpoints'
+import Breadcrumbs from '@src/components/Breadcrumbs'
 import { PageDivider } from '@src/components/MainContent'
 import {
   ContentContainer,
+  MainColumn,
   PageGrid,
   SideNavContainer,
 } from '@src/components/PageGrid'
@@ -46,13 +45,6 @@ import type {
   Parameter,
 } from '@src/lib/openapi-rest'
 
-// REST API has no right TOC column; SideNavContainer's auto margin is for centering regular docs.
-const RestSideNavContainer = styled(SideNavContainer)({
-  [mqs.twoColumn]: {
-    marginRight: 0,
-  },
-})
-
 type TabId = 'query' | 'responses'
 
 export type RestApiReferenceProps = {
@@ -104,82 +96,84 @@ export function RestApiReference({
 
   return (
     <PageGrid>
-      <RestSideNavContainer>
+      <SideNavContainer>
         <SidebarNav
           sections={apiSections}
           selectedId={selectedId}
         />
-      </RestSideNavContainer>
-      <ContentContainer>
-        <RestContentWrapper>
-          <BreadcrumbsWrapper>
-            <Breadcrumbs breadcrumbs={breadcrumbs} />
-          </BreadcrumbsWrapper>
-
-          {isAuthPage && <AuthPageContent />}
-
-          {!isAuthPage && detail && (
-            <ContentGrid>
-              <div>
-                <EndpointTitleRow>
-                  <EndpointName>{detail.operationName}</EndpointName>
-                  <PathGroup>
-                    <MethodBadge method={detail.method} />
-                    <EndpointPath>{detail.path}</EndpointPath>
-                    <CopyIconButton
-                      onClick={() => handleCopyPath()}
-                      type="button"
-                      title={pathCopied ? 'Copied' : 'Copy path'}
+      </SideNavContainer>
+      <MainColumn>
+        <ContentContainer $wide>
+          <RestContentWrapper>
+            <BreadcrumbsWrapper>
+              <Breadcrumbs breadcrumbs={breadcrumbs} />
+            </BreadcrumbsWrapper>
+
+            {isAuthPage && <AuthPageContent />}
+
+            {!isAuthPage && detail && (
+              <ContentGrid>
+                <div>
+                  <EndpointTitleRow>
+                    <EndpointName>{detail.operationName}</EndpointName>
+                    <PathGroup>
+                      <MethodBadge method={detail.method} />
+                      <EndpointPath>{detail.path}</EndpointPath>
+                      <CopyIconButton
+                        onClick={() => handleCopyPath()}
+                        type="button"
+                        title={pathCopied ? 'Copied' : 'Copy path'}
+                      >
+                        <CopyIconWrapper $visible={!pathCopied}>
+                          <CopyIcon size={16} />
+                        </CopyIconWrapper>
+                        <CopyIconWrapper $visible={pathCopied}>
+                          <CheckIcon size={16} />
+                        </CopyIconWrapper>
+                      </CopyIconButton>
+                    </PathGroup>
+                  </EndpointTitleRow>
+
+                  {detail.description && (
+                    <PageDescription>{detail.description}</PageDescription>
+                  )}
+
+                  <TabBar>
+                    <Tab
+                      active={activeTab === 'query'}
+                      onClick={() => setActiveTab('query')}
+                    >
+                      {getParameterTabLabel(detail.parameters ?? [])}
+                    </Tab>
+                    <Tab
+                      active={activeTab === 'responses'}
+                      onClick={() => setActiveTab('responses')}
                     >
-                      <CopyIconWrapper $visible={!pathCopied}>
-                        <CopyIcon size={16} />
-                      </CopyIconWrapper>
-                      <CopyIconWrapper $visible={pathCopied}>
-                        <CheckIcon size={16} />
-                      </CopyIconWrapper>
-                    </CopyIconButton>
-                  </PathGroup>
-                </EndpointTitleRow>
-
-                {detail.description && (
-                  <PageDescription>{detail.description}</PageDescription>
-                )}
-
-                <TabBar>
-                  <Tab
-                    active={activeTab === 'query'}
-                    onClick={() => setActiveTab('query')}
-                  >
-                    {getParameterTabLabel(detail.parameters ?? [])}
-                  </Tab>
-                  <Tab
-                    active={activeTab === 'responses'}
-                    onClick={() => setActiveTab('responses')}
-                  >
-                    Responses
-                  </Tab>
-                </TabBar>
-
-                {activeTab === 'query' && (
-                  <ParameterTable parameters={detail.parameters} />
-                )}
-
-                {activeTab === 'responses' && (
-                  <ResponseSchemaView
-                    key={detail.id}
-                    schemas={detail.responseSchemas ?? []}
-                  />
-                )}
-              </div>
-              <ResponsePanel
-                key={detail.id}
-                detail={detail}
-              />
-            </ContentGrid>
-          )}
-        </RestContentWrapper>
-        <PageDivider />
-      </ContentContainer>
+                      Responses
+                    </Tab>
+                  </TabBar>
+
+                  {activeTab === 'query' && (
+                    <ParameterTable parameters={detail.parameters} />
+                  )}
+
+                  {activeTab === 'responses' && (
+                    <ResponseSchemaView
+                      key={detail.id}
+                      schemas={detail.responseSchemas ?? []}
+                    />
+                  )}
+                </div>
+                <ResponsePanel
+                  key={detail.id}
+                  detail={detail}
+                />
+              </ContentGrid>
+            )}
+          </RestContentWrapper>
+          <PageDivider />
+        </ContentContainer>
+      </MainColumn>
     </PageGrid>
   )
 }
diff --git a/js/documentation/src/components/SideNav.tsx b/js/documentation/src/components/SideNav.tsx
index f46ecd0385..da46ff4ed1 100644
--- a/js/documentation/src/components/SideNav.tsx
+++ b/js/documentation/src/components/SideNav.tsx
@@ -60,9 +60,7 @@ const KeyboardNavContext = createContext<{
   keyboardNavigable: true,
 })
 
-const StyledLink = styled(NextLink as any)<{
-  $desktop: boolean
-}>(({ $desktop, theme }) => ({
+const StyledLink = styled(NextLink as any)(({ theme }) => ({
   display: 'flex',
   gap: theme.spacing.small,
   cursor: 'pointer',
@@ -72,7 +70,7 @@ const StyledLink = styled(NextLink as any)<{
   padding: `${theme.spacing.xsmall}px ${theme.spacing.medium}px`,
   ...theme.partials.text.body2,
   textDecoration: 'none',
-  color: theme.colors['text-light'],
+  color: theme.colors['text-xlight'],
   '.iconRight': {
     display: 'flex',
     justifyContent: 'right',
@@ -86,10 +84,7 @@ const StyledLink = styled(NextLink as any)<{
     boxShadow: 'none',
   },
   '&:focus-visible::after': {
-    borderStartStartRadius: theme.borderRadiuses.medium,
-    borderEndStartRadius: theme.borderRadiuses.medium,
-    borderStartEndRadius: $desktop ? 0 : theme.borderRadiuses.medium,
-    borderEndEndRadius: $desktop ? 0 : theme.borderRadiuses.medium,
+    borderRadius: theme.borderRadiuses.medium,
     ...theme.partials.focus.insetAbsolute,
   },
 }))
@@ -102,12 +97,10 @@ type LinkBaseProps = Partial<ComponentProps<typeof StyledLink>> & {
 const LinkBase = forwardRef<HTMLAnchorElement, LinkBaseProps>(
   ({ className, children, iconLeft, iconRight, href, ...props }, ref) => {
     const { keyboardNavigable } = useContext(KeyboardNavContext)
-    const { desktop } = useContext(NavContext)
     const content = (
       <StyledLink
         href={href}
         className={className}
-        $desktop={desktop}
         tabIndex={keyboardNavigable ? 0 : -1}
         ref={ref}
         {...props}
@@ -285,7 +278,7 @@ function NavLinkUnstyled({
   )
 }
 
-const NavLink = styled(NavLinkUnstyled)(({ desktop, theme }) => ({
+const NavLink = styled(NavLinkUnstyled)(({ theme }) => ({
   display: 'flex',
   flexDirection: 'row',
   position: 'relative',
@@ -295,10 +288,7 @@ const NavLink = styled(NavLinkUnstyled)(({ desktop, theme }) => ({
   padding: 0,
   listStyle: 'none',
 
-  borderStartStartRadius: theme.borderRadiuses.medium,
-  borderEndStartRadius: theme.borderRadiuses.medium,
-  borderStartEndRadius: desktop ? 0 : theme.borderRadiuses.medium,
-  borderEndEndRadius: desktop ? 0 : theme.borderRadiuses.medium,
+  borderRadius: theme.borderRadiuses.medium,
 
   '&:hover': {
     backgroundColor: theme.colors['fill-one-hover'],
@@ -310,6 +300,7 @@ const NavLink = styled(NavLinkUnstyled)(({ desktop, theme }) => ({
   '&.selected': {
     backgroundColor: theme.colors['action-primary'],
     '&:hover': { backgroundColor: theme.colors['action-primary-hover'] },
+    a: { color: theme.colors.text },
   },
 }))
 
@@ -481,8 +472,6 @@ function SubSection({
     </>
   )
 }
-const navLeftOffset = 1000
-
 export const NavPositionWrapper = styled.nav(({ theme: _theme }) => ({
   position: 'sticky',
   height: 'calc(100vh - var(--top-nav-height))',
@@ -506,17 +495,14 @@ const NavScrollContainer = styled.div<{
   borderRight: desktop ? theme.borders['fill-one'] : 'none',
   paddingBottom: `calc(${theme.spacing.xlarge}px + var(--menu-extra-bpad))`,
   paddingTop: padTop ? theme.spacing.large : 0,
-  paddingRight: desktop ? 0 : theme.spacing.medium,
-  paddingLeft: desktop ? 0 : theme.spacing.medium,
-  marginLeft: desktop ? -navLeftOffset : 0,
+  paddingRight: theme.spacing.medium,
+  paddingLeft: theme.spacing.medium,
   display: hide ? 'none' : 'block',
 }))
 
-const Nav = styled.nav<{ $desktop: boolean }>(
-  ({ $desktop: desktop, theme: _theme }) => ({
-    marginLeft: desktop ? navLeftOffset : 0,
-  })
-)
+const Nav = styled.nav(() => ({
+  minHeight: '100%',
+}))
 
 export function SideNav({
   navData,
@@ -586,7 +572,7 @@ export function SideNav({
         $padTop={padTop}
         $hide={hide}
       >
-        <Nav $desktop={desktop}>
+        <Nav>
           {(navData || []).map(({ title, sections }) => (
             <TopSection
               title={title}
diff --git a/js/documentation/src/components/TableOfContents.tsx b/js/documentation/src/components/TableOfContents.tsx
index 86ae791fb7..0f9dae6ead 100644
--- a/js/documentation/src/components/TableOfContents.tsx
+++ b/js/documentation/src/components/TableOfContents.tsx
@@ -15,14 +15,16 @@ const Title = styled.h2(({ theme }) => ({
   marginTop: theme.spacing.large,
   marginBottom: theme.spacing.medium,
   '&::after': {
-    // Use to align baseline with Hero 2 text
+    // Align baseline with Hero 2 without expanding the title box (Safari).
     ...theme.partials.marketingText.hero2,
-    display: 'inline',
+    display: 'inline-block',
     verticalAlign: 'baseline',
-    content: '"​"',
-    width: '0',
+    content: '"\\200b"',
+    width: 0,
+    height: 0,
     overflow: 'hidden',
-    position: 'relative',
+    lineHeight: 0,
+    fontSize: 0,
   },
 }))
 
@@ -54,6 +56,9 @@ const StyledLink = styled(NextLink as any)<{ $active: boolean }>(
     display: 'block',
     ...theme.partials.marketingText.componentLinkSmall,
     color: theme.colors['text-xlight'],
+    '&&:any-link': {
+      color: theme.colors['text-xlight'],
+    },
     textDecoration: 'none',
     margin: 0,
     paddingLeft: theme.spacing.medium,
@@ -70,6 +75,9 @@ const StyledLink = styled(NextLink as any)<{ $active: boolean }>(
     ...($active
       ? {
           color: theme.colors.text,
+          '&&:any-link': {
+            color: theme.colors.text,
+          },
           '&::before ': {
             zIndex: 1,
             borderLeft: `3px solid ${theme.colors['border-primary']}`,
@@ -78,7 +86,7 @@ const StyledLink = styled(NextLink as any)<{ $active: boolean }>(
           },
         }
       : {}),
-    '&:hover': {
+    '&:hover, &&:any-link:hover': {
       textDecoration: 'underline',
       color: theme.colors.text,
     },
@@ -102,7 +110,8 @@ const StyledLink = styled(NextLink as any)<{ $active: boolean }>(
 
 export const ScrollContainer = styled.div(({ theme: _ }) => ({
   overflowY: 'auto',
-  maxHeight: '-webkit-fill-available',
+  minHeight: 0,
+  maxHeight: 'calc(100vh - var(--top-nav-height) - 72px)',
 }))
 
 const scrollThreshold = 48
@@ -247,8 +256,6 @@ const getRenderedElementTops = (items: MarkdocHeading[]) =>
 const WrapperNavSC = styled.nav(({ theme: _ }) => ({
   display: 'flex',
   flexDirection: 'column',
-  position: 'absolute',
-  top: 0,
-  bottom: 0,
   width: '100%',
+  minHeight: 0,
 }))
diff --git a/js/documentation/src/components/types/window.d.ts b/js/documentation/src/components/types/window.d.ts
index 77b57ba615..7be90fde5f 100644
--- a/js/documentation/src/components/types/window.d.ts
+++ b/js/documentation/src/components/types/window.d.ts
@@ -29,7 +29,14 @@ interface Window {
     ): void
   }
   // Kapa docs widget (stub queue or loaded API)
-  Kapa?: (command: string, ...args: unknown[]) => void
+  Kapa?: ((command: string, ...args: unknown[]) => void) & {
+    open?: (options?: {
+      mode?: 'search' | 'ai'
+      query?: string
+      submit?: boolean
+    }) => void
+    q?: unknown[]
+  }
   // Hubspot
   _hsq?: any[]
   // Gtag
diff --git a/js/documentation/src/lib/kapa.ts b/js/documentation/src/lib/kapa.ts
new file mode 100644
index 0000000000..5fbd362205
--- /dev/null
+++ b/js/documentation/src/lib/kapa.ts
@@ -0,0 +1,49 @@
+export type KapaMode = 'search' | 'ai'
+
+type KapaApi = ((command: string, ...args: unknown[]) => void) & {
+  open?: (options?: { mode?: KapaMode; query?: string; submit?: boolean }) => void
+  q?: unknown[]
+}
+
+function getKapa(): KapaApi | undefined {
+  return window.Kapa as KapaApi | undefined
+}
+
+export function openKapa(mode: KapaMode, query?: string) {
+  if (typeof window === 'undefined') {
+    return
+  }
+
+  const tryOpen = () => {
+    const kapa = getKapa()
+
+    if (!kapa) {
+      return false
+    }
+
+    if (typeof kapa.open === 'function') {
+      kapa.open({ mode, ...(query ? { query } : {}) })
+
+      return true
+    }
+
+    if (typeof kapa === 'function') {
+      kapa('open', { mode, ...(query ? { query } : {}) })
+
+      return true
+    }
+
+    return false
+  }
+
+  if (tryOpen()) {
+    return
+  }
+
+  const started = Date.now()
+  const id = window.setInterval(() => {
+    if (tryOpen() || Date.now() - started > 8000) {
+      window.clearInterval(id)
+    }
+  }, 100)
+}

From 5eb6a0cf5f4a7d282f00c7d76d4c9b4ec75384ed Mon Sep 17 00:00:00 2001
From: Anna Nguyen <anna.nguyen42@gmail.com>
Date: Thu, 10 Sep 2026 14:10:51 -0400
Subject: [PATCH 02/13] Reuse Console breadcrumbs instead of a docs-only trail.

Keeps markdown and REST API pages on the design-system component so the PR does not restyle an existing control.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../src/components/Breadcrumbs.tsx            | 97 ++-----------------
 .../src/components/RestApiReference/index.tsx |  4 +-
 2 files changed, 9 insertions(+), 92 deletions(-)

diff --git a/js/documentation/src/components/Breadcrumbs.tsx b/js/documentation/src/components/Breadcrumbs.tsx
index a78a0af44d..a940ac1ade 100644
--- a/js/documentation/src/components/Breadcrumbs.tsx
+++ b/js/documentation/src/components/Breadcrumbs.tsx
@@ -1,20 +1,14 @@
 import { useMemo } from 'react'
 
-import NextLink from 'next/link'
+import { Breadcrumbs as BreadcrumbsComponent } from '@pluralsh/design-system'
 import { useRouter } from 'next/router'
-import styled from 'styled-components'
 
 import { useNavMenu } from '../contexts/NavDataContext'
 import { getBarePathFromPath, removeTrailingSlashes } from '../utils/text'
 
 import type { NavItem } from '../NavData'
 
-export type DocsBreadcrumb = {
-  label: string
-  url?: string
-}
-
-function findCrumbs(path, sections: NavItem[]): DocsBreadcrumb[] {
+function findCrumbs(path, sections: NavItem[]) {
   path = removeTrailingSlashes(path)
 
   for (const { title: label, href: url, sections: sects } of sections) {
@@ -31,95 +25,20 @@ function findCrumbs(path, sections: NavItem[]): DocsBreadcrumb[] {
   return []
 }
 
-export default function Breadcrumbs({
-  breadcrumbs: breadcrumbsProp,
-}: {
-  breadcrumbs?: DocsBreadcrumb[]
-}) {
+export default function Breadcrumbs() {
   const { asPath } = useRouter()
+
   const path = getBarePathFromPath(asPath)
   const navData = useNavMenu()
 
   const crumbs = useMemo(
-    () =>
-      breadcrumbsProp ?? [
-        { label: 'Docs', url: '/' },
-        ...findCrumbs(path, navData),
-      ],
-    [breadcrumbsProp, navData, path]
+    () => [{ label: 'Docs', url: '/' }, ...findCrumbs(path, navData)],
+    [navData, path]
   )
 
-  if (crumbs.length === 0) {
+  if (crumbs.length <= 1) {
     return null
   }
 
-  return (
-    <Nav aria-label="breadcrumbs">
-      <List>
-        {crumbs.map((crumb, index) => {
-          const isLast = index === crumbs.length - 1
-
-          return (
-            <Item key={`${crumb.label}-${crumb.url ?? index}`}>
-              {index > 0 && <Separator aria-hidden>/</Separator>}
-              {isLast || !crumb.url ? (
-                <Current aria-current="page">{crumb.label}</Current>
-              ) : (
-                <CrumbLink href={crumb.url}>{crumb.label}</CrumbLink>
-              )}
-            </Item>
-          )
-        })}
-      </List>
-    </Nav>
-  )
+  return <BreadcrumbsComponent breadcrumbs={crumbs ?? []} />
 }
-
-const Nav = styled.nav({
-  minWidth: 0,
-})
-
-const List = styled.ol(({ theme }) => ({
-  ...theme.partials.reset.list,
-  display: 'flex',
-  alignItems: 'center',
-  flexWrap: 'wrap',
-  gap: theme.spacing.xsmall,
-  minWidth: 0,
-}))
-
-const Item = styled.li(({ theme }) => ({
-  ...theme.partials.reset.li,
-  display: 'flex',
-  alignItems: 'center',
-  gap: theme.spacing.xsmall,
-  minWidth: 0,
-}))
-
-const Separator = styled.span(({ theme }) => ({
-  ...theme.partials.text.body2,
-  color: theme.colors['text-input-disabled'],
-  userSelect: 'none',
-}))
-
-const crumbText = ({ theme }) => ({
-  ...theme.partials.text.body2,
-  overflow: 'hidden',
-  textOverflow: 'ellipsis',
-  whiteSpace: 'nowrap',
-})
-
-const CrumbLink = styled(NextLink)(({ theme }) => ({
-  ...crumbText({ theme }),
-  color: theme.colors['text-xlight'],
-  textDecoration: 'none',
-  '&:hover': {
-    color: theme.colors.text,
-  },
-}))
-
-const Current = styled.span(({ theme }) => ({
-  ...crumbText({ theme }),
-  color: theme.colors.text,
-  fontWeight: 600,
-}))
diff --git a/js/documentation/src/components/RestApiReference/index.tsx b/js/documentation/src/components/RestApiReference/index.tsx
index 50f21de204..dfd70c8603 100644
--- a/js/documentation/src/components/RestApiReference/index.tsx
+++ b/js/documentation/src/components/RestApiReference/index.tsx
@@ -6,10 +6,8 @@
 
 import { useMemo, useState } from 'react'
 
-import { CheckIcon, CopyIcon, Tab } from '@pluralsh/design-system'
+import { Breadcrumbs, CheckIcon, CopyIcon, Tab } from '@pluralsh/design-system'
 import { useRouter } from 'next/router'
-
-import Breadcrumbs from '@src/components/Breadcrumbs'
 import { PageDivider } from '@src/components/MainContent'
 import {
   ContentContainer,

From 920135a613410f6164b09e743f5ff0e5a414dbe8 Mon Sep 17 00:00:00 2001
From: Anna Nguyen <anna.nguyen42@gmail.com>
Date: Thu, 10 Sep 2026 14:15:33 -0400
Subject: [PATCH 03/13] Give breadcrumb wrappers a full column width.

The design-system trail collapses to ... when its flex parent shrink-wraps and the resize observer measures ~0px.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 js/documentation/src/components/MainContent.tsx             | 6 ++++++
 .../components/RestApiReference/RestApiReference.styles.ts  | 6 ++++++
 2 files changed, 12 insertions(+)

diff --git a/js/documentation/src/components/MainContent.tsx b/js/documentation/src/components/MainContent.tsx
index 4b5df1280d..9f90a194c2 100644
--- a/js/documentation/src/components/MainContent.tsx
+++ b/js/documentation/src/components/MainContent.tsx
@@ -22,8 +22,14 @@ const ContentWrapper = styled.div((_) => ({
 const BreadcrumbsWrapper = styled.div(({ theme }) => ({
   display: 'flex',
   alignItems: 'center',
+  width: '100%',
+  minWidth: 0,
   minHeight: 40,
   marginBottom: theme.spacing.large,
+  '& > *': {
+    minWidth: 0,
+    width: '100%',
+  },
 }))
 
 const Title = styled.h1(({ theme }) => ({
diff --git a/js/documentation/src/components/RestApiReference/RestApiReference.styles.ts b/js/documentation/src/components/RestApiReference/RestApiReference.styles.ts
index 97b65fd2c7..5b9a4c8f3d 100644
--- a/js/documentation/src/components/RestApiReference/RestApiReference.styles.ts
+++ b/js/documentation/src/components/RestApiReference/RestApiReference.styles.ts
@@ -9,8 +9,14 @@ export const RestContentWrapper = styled.div((_) => ({
 export const BreadcrumbsWrapper = styled.div(({ theme }) => ({
   display: 'flex',
   alignItems: 'center',
+  width: '100%',
+  minWidth: 0,
   minHeight: 40,
   marginBottom: theme.spacing.large,
+  '& > *': {
+    minWidth: 0,
+    width: '100%',
+  },
 }))
 
 export const ContentGrid = styled.div(({ theme }) => ({

From 2d425f3ae9b1829df650922d53ccaae261583c56 Mon Sep 17 00:00:00 2001
From: Anna Nguyen <anna.nguyen42@gmail.com>
Date: Thu, 10 Sep 2026 14:19:05 -0400
Subject: [PATCH 04/13] Use the design-system Input2 for the REST API filter.

Replaces the custom search field and clear button with the shared search-icon + showClearButton pattern.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../RestApiReference/SidebarNav.tsx           | 118 ++----------------
 1 file changed, 12 insertions(+), 106 deletions(-)

diff --git a/js/documentation/src/components/RestApiReference/SidebarNav.tsx b/js/documentation/src/components/RestApiReference/SidebarNav.tsx
index 6aa0d4e58c..e2939b9f68 100644
--- a/js/documentation/src/components/RestApiReference/SidebarNav.tsx
+++ b/js/documentation/src/components/RestApiReference/SidebarNav.tsx
@@ -5,7 +5,7 @@
 
 import { useMemo, useState } from 'react'
 
-import { CloseIcon } from '@pluralsh/design-system'
+import { Input2, SearchIcon } from '@pluralsh/design-system'
 import NextLink from 'next/link'
 
 import isEmpty from 'lodash/isEmpty'
@@ -48,61 +48,9 @@ const SearchWrapper = styled.div(({ theme }) => ({
   zIndex: 1,
 }))
 
-const SearchInput = styled.div(({ theme }) => ({
-  display: 'flex',
-  alignItems: 'center',
-  gap: theme.spacing.small,
-  background: theme.colors['fill-two'] ?? theme.colors['fill-zero'],
-  border: theme.borders.default,
-  borderRadius: theme.borderRadiuses.medium,
-  padding: `${theme.spacing.xsmall}px ${theme.spacing.medium}px`,
-  '&:focus-within': {
-    borderColor: theme.colors['border-primary'],
-  },
-  '.icon': {
-    color: theme.colors['text-xlight'],
-    flexShrink: 0,
-  },
-  input: {
-    flex: 1,
-    minWidth: 0,
-    background: 'transparent',
-    border: 'none',
-    outline: 'none',
-    color: theme.colors.text,
-    ...theme.partials.text.body2,
-    '::placeholder': { color: theme.colors['text-xlight'] },
-    '&::-webkit-search-decoration, &::-webkit-search-cancel-button': {
-      WebkitAppearance: 'none',
-      appearance: 'none',
-      display: 'none',
-    },
-    '&::-ms-clear': {
-      display: 'none',
-      width: 0,
-      height: 0,
-    },
-  },
-}))
-
-const ClearButton = styled.button(({ theme }) => ({
-  display: 'flex',
-  alignItems: 'center',
-  justifyContent: 'center',
-  flexShrink: 0,
-  width: 20,
-  height: 20,
-  padding: 0,
-  border: 'none',
-  borderRadius: '50%',
-  background: theme.colors['fill-three'] ?? theme.colors['fill-two'],
-  color: theme.colors['text-xlight'],
-  cursor: 'pointer',
-  '&:hover': {
-    color: theme.colors.text,
-    background: theme.colors['fill-two-hover'] ?? theme.colors['fill-one-hover'],
-  },
-}))
+const FilterInput = styled(Input2)({
+  width: '100%',
+})
 
 const SectionGroup = styled.div(({ theme }) => ({
   display: 'block',
@@ -156,32 +104,6 @@ const EndpointRowLink = styled(NextLink)<{ $active: boolean }>(
   })
 )
 
-function SearchIcon() {
-  return (
-    <svg
-      width={14}
-      height={14}
-      viewBox="0 0 16 16"
-      fill="none"
-      xmlns="http://www.w3.org/2000/svg"
-    >
-      <circle
-        cx="7"
-        cy="7"
-        r="5"
-        stroke="currentColor"
-        strokeWidth="1.4"
-      />
-      <path
-        d="M10.5 10.5 14 14"
-        stroke="currentColor"
-        strokeWidth="1.4"
-        strokeLinecap="round"
-      />
-    </svg>
-  )
-}
-
 export const AUTH_PAGE_ID = '__authentication__'
 
 const TopNavItemLink = styled(NextLink)<{ $active: boolean }>(
@@ -250,30 +172,14 @@ export function SidebarNav({
     <Sidebar>
       <SidebarInner>
         <SearchWrapper>
-          <SearchInput>
-            <span
-              className="icon"
-              aria-hidden
-            >
-              <SearchIcon />
-            </span>
-            <input
-              type="text"
-              placeholder="Filter API"
-              value={filter}
-              onChange={(e) => setFilter(e.target.value)}
-              aria-label="Filter API endpoints"
-            />
-            {filter && (
-              <ClearButton
-                type="button"
-                aria-label="Clear filter"
-                onClick={() => setFilter('')}
-              >
-                <CloseIcon size={10} />
-              </ClearButton>
-            )}
-          </SearchInput>
+          <FilterInput
+            showClearButton
+            placeholder="Filter API"
+            startIcon={<SearchIcon />}
+            value={filter}
+            onChange={(e) => setFilter(e.currentTarget.value)}
+            inputProps={{ 'aria-label': 'Filter API endpoints' }}
+          />
         </SearchWrapper>
         <nav aria-label="REST API endpoints">
           {showAuthItem && (

From 0ace58b36bbc172bc8991baf846ab8e82d6186a4 Mon Sep 17 00:00:00 2001
From: Anna Nguyen <anna.nguyen42@gmail.com>
Date: Thu, 10 Sep 2026 14:26:05 -0400
Subject: [PATCH 05/13] Show the REST API sidebar in the mobile hamburger.

The desktop endpoint nav is hidden below the two-column breakpoint; the existing menu overlay now hosts that list so mobile can still browse endpoints.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 js/documentation/pages/_app.tsx               | 17 +++--
 .../src/components/MobileMenu.tsx             | 68 +++++++++++++++++--
 .../src/components/PageHeader.tsx             |  2 +
 .../src/components/PageHeaderButtons.tsx      |  1 +
 .../RestApiReference/SidebarNav.tsx           | 25 +++++--
 .../src/components/RestApiReference/index.tsx |  3 +
 .../src/contexts/RestNavContext.tsx           | 48 +++++++++++++
 7 files changed, 143 insertions(+), 21 deletions(-)
 create mode 100644 js/documentation/src/contexts/RestNavContext.tsx

diff --git a/js/documentation/pages/_app.tsx b/js/documentation/pages/_app.tsx
index 573d77731f..7620a68153 100644
--- a/js/documentation/pages/_app.tsx
+++ b/js/documentation/pages/_app.tsx
@@ -57,6 +57,7 @@ import {
   ROOT_TITLE,
 } from '@src/consts'
 import { NavDataProvider } from '@src/contexts/NavDataContext'
+import { RestNavProvider } from '@src/contexts/RestNavContext'
 import { collectHeadings } from '@src/markdoc/utils/parseHeadings'
 import { getNavData } from '@src/NavData'
 
@@ -216,13 +217,15 @@ function App({ Component, pageProps = {}, swrConfig }: MyAppProps) {
         <NavigationContextProvider value={navContextVal}>
           <SWRConfig value={swrConfig}>
             <NavDataProvider value={navData}>
-              <BreakpointProvider>
-                <StyledThemeProvider theme={docsStyledTheme}>
-                  <HonorableThemeProvider>
-                    <FillLevelProvider value={0}>{app}</FillLevelProvider>
-                  </HonorableThemeProvider>
-                </StyledThemeProvider>
-              </BreakpointProvider>
+              <RestNavProvider>
+                <BreakpointProvider>
+                  <StyledThemeProvider theme={docsStyledTheme}>
+                    <HonorableThemeProvider>
+                      <FillLevelProvider value={0}>{app}</FillLevelProvider>
+                    </HonorableThemeProvider>
+                  </StyledThemeProvider>
+                </BreakpointProvider>
+              </RestNavProvider>
             </NavDataProvider>
           </SWRConfig>
         </NavigationContextProvider>
diff --git a/js/documentation/src/components/MobileMenu.tsx b/js/documentation/src/components/MobileMenu.tsx
index 4ed11f12be..63f3cf3815 100644
--- a/js/documentation/src/components/MobileMenu.tsx
+++ b/js/documentation/src/components/MobileMenu.tsx
@@ -1,15 +1,24 @@
-import { DiscordIcon } from '@pluralsh/design-system'
+import { useState } from 'react'
+
+import {
+  ArrowLeftIcon,
+  ArrowRightIcon,
+  Button,
+  DiscordIcon,
+} from '@pluralsh/design-system'
 
 import styled from 'styled-components'
 import { useIsomorphicLayoutEffect } from 'usehooks-ts'
 
 import { DISCORD_LINK } from '@src/consts'
+import { useRestNav } from '@src/contexts/RestNavContext'
 
-import { FullNav, type NavContextValue } from './FullNav'
+import { FullNav, NavButtons, type NavContextValue } from './FullNav'
 import GithubStars from './GithubStars'
 import useScrollLock from './hooks/useScrollLock'
 import { MainLink } from './PageHeader'
 import { SocialLink } from './PageHeaderButtons'
+import { SidebarNav } from './RestApiReference/SidebarNav'
 import { TopHeading } from './SideNav'
 
 type MobileMenuProps = NavContextValue & {
@@ -84,23 +93,68 @@ const Content = styled.div(({ theme }) => ({
   background: theme.colors['fill-one'],
   display: 'flex',
   flexDirection: 'column',
+  minHeight: 0,
+  overflow: 'hidden',
 }))
 
 function MobileMenu({ isOpen, setIsOpen, className }: MobileMenuProps) {
   const [, setScrollLock] = useScrollLock(false)
+  const restNav = useRestNav()
+  const [showDocsMenu, setShowDocsMenu] = useState(false)
 
   useIsomorphicLayoutEffect(() => {
     setScrollLock(isOpen)
   }, [isOpen, setScrollLock])
 
+  useIsomorphicLayoutEffect(() => {
+    if (isOpen) {
+      setShowDocsMenu(false)
+    }
+  }, [isOpen])
+
+  const showRestNav = !!restNav && !showDocsMenu
+
   return (
     <div className={className}>
       <Content>
-        <FullNav
-          desktop={false}
-          isOpen={isOpen}
-          setIsOpen={setIsOpen}
-        />
+        {showRestNav ? (
+          <>
+            <NavButtons desktop={false}>
+              <Button
+                tertiary
+                startIcon={<ArrowLeftIcon />}
+                onClick={() => setShowDocsMenu(true)}
+              >
+                Docs menu
+              </Button>
+            </NavButtons>
+            <SidebarNav
+              overlay
+              sections={restNav.sections}
+              selectedId={restNav.selectedId}
+            />
+          </>
+        ) : (
+          <>
+            {restNav && (
+              <NavButtons desktop={false}>
+                <div />
+                <Button
+                  tertiary
+                  endIcon={<ArrowRightIcon />}
+                  onClick={() => setShowDocsMenu(false)}
+                >
+                  API menu
+                </Button>
+              </NavButtons>
+            )}
+            <FullNav
+              desktop={false}
+              isOpen={isOpen}
+              setIsOpen={setIsOpen}
+            />
+          </>
+        )}
       </Content>
     </div>
   )
diff --git a/js/documentation/src/components/PageHeader.tsx b/js/documentation/src/components/PageHeader.tsx
index 2013fd2a2e..f2844a5260 100644
--- a/js/documentation/src/components/PageHeader.tsx
+++ b/js/documentation/src/components/PageHeader.tsx
@@ -139,6 +139,8 @@ const PageHeader = styled(PageHeaderUnstyled)(({ theme }) => ({
   },
   '.logo': {
     width: 162,
+    maxWidth: '100%',
+    minWidth: 0,
     display: 'block',
   },
   '.leftSection': {
diff --git a/js/documentation/src/components/PageHeaderButtons.tsx b/js/documentation/src/components/PageHeaderButtons.tsx
index e3d532c18c..5dac9f669f 100644
--- a/js/documentation/src/components/PageHeaderButtons.tsx
+++ b/js/documentation/src/components/PageHeaderButtons.tsx
@@ -38,6 +38,7 @@ export const SocialLink = styled(ButtonFillTwo)(({ theme }) => ({
 export const HamburgerButtonWrap = styled(ButtonFillTwo)((_) => ({
   width: 40,
   height: 40,
+  flexShrink: 0,
   alignItems: 'center',
   justifyContent: 'center',
   [mqs.fullHeader]: {
diff --git a/js/documentation/src/components/RestApiReference/SidebarNav.tsx b/js/documentation/src/components/RestApiReference/SidebarNav.tsx
index e2939b9f68..7ede512e17 100644
--- a/js/documentation/src/components/RestApiReference/SidebarNav.tsx
+++ b/js/documentation/src/components/RestApiReference/SidebarNav.tsx
@@ -15,15 +15,24 @@ import { MethodBadge } from './MethodBadge'
 
 import type { ApiSection, Endpoint } from '@src/lib/openapi-rest'
 
-const Sidebar = styled.aside(({ theme: _theme }) => ({
-  position: 'sticky',
-  top: 'var(--top-nav-height)',
-  height: 'calc(100vh - var(--top-nav-height))',
-  width: '100%',
-  flexShrink: 0,
+const Sidebar = styled.aside<{ $overlay?: boolean }>(({ $overlay }) => ({
   display: 'flex',
   flexDirection: 'column',
   overflow: 'hidden',
+  width: '100%',
+  ...($overlay
+    ? {
+        flex: 1,
+        minHeight: 0,
+        height: '100%',
+        position: 'relative',
+      }
+    : {
+        position: 'sticky',
+        top: 'var(--top-nav-height)',
+        height: 'calc(100vh - var(--top-nav-height))',
+        flexShrink: 0,
+      }),
 }))
 
 const SidebarInner = styled.div(({ theme }) => ({
@@ -140,9 +149,11 @@ const TopNavDivider = styled.hr(({ theme }) => ({
 export function SidebarNav({
   sections,
   selectedId,
+  overlay = false,
 }: {
   sections: ApiSection[]
   selectedId: string
+  overlay?: boolean
 }) {
   const [filter, setFilter] = useState('')
 
@@ -169,7 +180,7 @@ export function SidebarNav({
   const showAuthItem = !filter
 
   return (
-    <Sidebar>
+    <Sidebar $overlay={overlay}>
       <SidebarInner>
         <SearchWrapper>
           <FilterInput
diff --git a/js/documentation/src/components/RestApiReference/index.tsx b/js/documentation/src/components/RestApiReference/index.tsx
index dfd70c8603..671f48750d 100644
--- a/js/documentation/src/components/RestApiReference/index.tsx
+++ b/js/documentation/src/components/RestApiReference/index.tsx
@@ -15,6 +15,7 @@ import {
   PageGrid,
   SideNavContainer,
 } from '@src/components/PageGrid'
+import { useSetRestNav } from '@src/contexts/RestNavContext'
 import { useCopyText } from '@src/hooks/useCopyText'
 
 import { AuthPageContent } from './AuthPageContent'
@@ -82,6 +83,8 @@ export function RestApiReference({
     ? 'Authentication'
     : (detail?.operationName ?? selectedId)
 
+  useSetRestNav(apiSections, selectedId)
+
   const breadcrumbs = useMemo(
     () => [
       { label: 'Docs', url: '/' },
diff --git a/js/documentation/src/contexts/RestNavContext.tsx b/js/documentation/src/contexts/RestNavContext.tsx
new file mode 100644
index 0000000000..1dd97c0872
--- /dev/null
+++ b/js/documentation/src/contexts/RestNavContext.tsx
@@ -0,0 +1,48 @@
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+  type ReactNode,
+} from 'react'
+
+import type { ApiSection } from '@src/lib/openapi-rest'
+
+export type RestNavValue = {
+  sections: ApiSection[]
+  selectedId: string
+}
+
+type RestNavContextValue = {
+  restNav: RestNavValue | null
+  setRestNav: (value: RestNavValue | null) => void
+}
+
+const RestNavContext = createContext<RestNavContextValue>({
+  restNav: null,
+  setRestNav: () => {},
+})
+
+export function RestNavProvider({ children }: { children: ReactNode }) {
+  const [restNav, setRestNav] = useState<RestNavValue | null>(null)
+  const value = useMemo(() => ({ restNav, setRestNav }), [restNav])
+
+  return (
+    <RestNavContext.Provider value={value}>{children}</RestNavContext.Provider>
+  )
+}
+
+export function useRestNav() {
+  return useContext(RestNavContext).restNav
+}
+
+export function useSetRestNav(sections: ApiSection[], selectedId: string) {
+  const { setRestNav } = useContext(RestNavContext)
+
+  useEffect(() => {
+    setRestNav({ sections, selectedId })
+
+    return () => setRestNav(null)
+  }, [sections, selectedId, setRestNav])
+}

From 4d44aea17217b08b4ddebd8202d0d11ef39c0db6 Mon Sep 17 00:00:00 2001
From: Anna Nguyen <anna.nguyen42@gmail.com>
Date: Thu, 10 Sep 2026 14:27:46 -0400
Subject: [PATCH 06/13] Keep the REST overlay from covering the Docs menu
 control.

The endpoint list was sized to the full overlay height, so clicks on Docs menu hit the sidebar instead of the button.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../src/components/MobileMenu.tsx             |  6 +++++
 .../RestApiReference/SidebarNav.tsx           | 25 ++++++++++++-------
 2 files changed, 22 insertions(+), 9 deletions(-)

diff --git a/js/documentation/src/components/MobileMenu.tsx b/js/documentation/src/components/MobileMenu.tsx
index 63f3cf3815..1247a262a7 100644
--- a/js/documentation/src/components/MobileMenu.tsx
+++ b/js/documentation/src/components/MobileMenu.tsx
@@ -95,6 +95,11 @@ const Content = styled.div(({ theme }) => ({
   flexDirection: 'column',
   minHeight: 0,
   overflow: 'hidden',
+  [`${NavButtons}`]: {
+    position: 'relative',
+    zIndex: 1,
+    flexShrink: 0,
+  },
 }))
 
 function MobileMenu({ isOpen, setIsOpen, className }: MobileMenuProps) {
@@ -121,6 +126,7 @@ function MobileMenu({ isOpen, setIsOpen, className }: MobileMenuProps) {
           <>
             <NavButtons desktop={false}>
               <Button
+                type="button"
                 tertiary
                 startIcon={<ArrowLeftIcon />}
                 onClick={() => setShowDocsMenu(true)}
diff --git a/js/documentation/src/components/RestApiReference/SidebarNav.tsx b/js/documentation/src/components/RestApiReference/SidebarNav.tsx
index 7ede512e17..c208b4f9e7 100644
--- a/js/documentation/src/components/RestApiReference/SidebarNav.tsx
+++ b/js/documentation/src/components/RestApiReference/SidebarNav.tsx
@@ -24,7 +24,6 @@ const Sidebar = styled.aside<{ $overlay?: boolean }>(({ $overlay }) => ({
     ? {
         flex: 1,
         minHeight: 0,
-        height: '100%',
         position: 'relative',
       }
     : {
@@ -35,18 +34,26 @@ const Sidebar = styled.aside<{ $overlay?: boolean }>(({ $overlay }) => ({
       }),
 }))
 
-const SidebarInner = styled.div(({ theme }) => ({
-  position: 'absolute',
-  top: 0,
-  left: 0,
-  right: 0,
-  bottom: 0,
+const SidebarInner = styled.div<{ $overlay?: boolean }>(({ theme, $overlay }) => ({
   overflowY: 'auto',
   backgroundColor: theme.colors['fill-one'],
-  borderRight: theme.borders['fill-one'],
+  borderRight: $overlay ? 'none' : theme.borders['fill-one'],
   paddingBottom: theme.spacing.xlarge,
   paddingLeft: theme.spacing.medium,
   paddingRight: theme.spacing.medium,
+  ...($overlay
+    ? {
+        flex: 1,
+        minHeight: 0,
+        position: 'relative',
+      }
+    : {
+        position: 'absolute',
+        top: 0,
+        left: 0,
+        right: 0,
+        bottom: 0,
+      }),
 }))
 
 const SearchWrapper = styled.div(({ theme }) => ({
@@ -181,7 +188,7 @@ export function SidebarNav({
 
   return (
     <Sidebar $overlay={overlay}>
-      <SidebarInner>
+      <SidebarInner $overlay={overlay}>
         <SearchWrapper>
           <FilterInput
             showClearButton

From 402bfe854c56d26ef3097256fdce4b133f8ee924 Mon Sep 17 00:00:00 2001
From: Anna Nguyen <anna.nguyen42@gmail.com>
Date: Thu, 10 Sep 2026 14:46:32 -0400
Subject: [PATCH 07/13] Keep the mobile menu open when switching to the docs
 tree.

FullNav treated its first mount as a route change and closed the overlay, so Docs menu looked like a no-op.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 js/documentation/src/components/FullNav.tsx   |  4 +-
 .../src/components/MobileMenu.tsx             | 61 ++++++++++++-------
 .../src/components/PageHeaderButtons.tsx      |  5 +-
 3 files changed, 47 insertions(+), 23 deletions(-)

diff --git a/js/documentation/src/components/FullNav.tsx b/js/documentation/src/components/FullNav.tsx
index 77473face1..14bd00cdb0 100644
--- a/js/documentation/src/components/FullNav.tsx
+++ b/js/documentation/src/components/FullNav.tsx
@@ -72,6 +72,8 @@ export const NavButtons = styled(NavButtonsUnstyled)<{ desktop: boolean }>(
 export const NavWrap = styled.div((_) => ({
   position: 'relative',
   flexGrow: 1,
+  flex: 1,
+  minHeight: 0,
 }))
 
 function NavButton({
@@ -102,7 +104,7 @@ export function FullNav({
   const previousPath = usePrevious(thisPath)
 
   useEffect(() => {
-    if (thisPath !== previousPath) {
+    if (previousPath && thisPath !== previousPath) {
       if (setIsOpen) {
         setIsOpen(false)
       }
diff --git a/js/documentation/src/components/MobileMenu.tsx b/js/documentation/src/components/MobileMenu.tsx
index 1247a262a7..0f23c3693f 100644
--- a/js/documentation/src/components/MobileMenu.tsx
+++ b/js/documentation/src/components/MobileMenu.tsx
@@ -1,4 +1,4 @@
-import { useState } from 'react'
+import { useRef, useState } from 'react'
 
 import {
   ArrowLeftIcon,
@@ -82,6 +82,20 @@ export const PluralMenu = styled(PluralMenuContent)(
   })
 )
 
+const Panel = styled.div<{ $hidden: boolean }>(({ $hidden }) => ({
+  display: $hidden ? 'none' : 'flex',
+  flexDirection: 'column',
+  flex: 1,
+  minHeight: 0,
+}))
+
+const DocsNavWrap = styled.div({
+  display: 'flex',
+  flexDirection: 'column',
+  flex: 1,
+  minHeight: 0,
+})
+
 const Content = styled.div(({ theme }) => ({
   pointerEvents: 'all',
   position: 'absolute',
@@ -111,10 +125,13 @@ function MobileMenu({ isOpen, setIsOpen, className }: MobileMenuProps) {
     setScrollLock(isOpen)
   }, [isOpen, setScrollLock])
 
+  const wasOpen = useRef(isOpen)
+
   useIsomorphicLayoutEffect(() => {
-    if (isOpen) {
+    if (isOpen && !wasOpen.current) {
       setShowDocsMenu(false)
     }
+    wasOpen.current = isOpen
   }, [isOpen])
 
   const showRestNav = !!restNav && !showDocsMenu
@@ -122,8 +139,8 @@ function MobileMenu({ isOpen, setIsOpen, className }: MobileMenuProps) {
   return (
     <div className={className}>
       <Content>
-        {showRestNav ? (
-          <>
+        {restNav && (
+          <Panel $hidden={!showRestNav}>
             <NavButtons desktop={false}>
               <Button
                 type="button"
@@ -139,28 +156,30 @@ function MobileMenu({ isOpen, setIsOpen, className }: MobileMenuProps) {
               sections={restNav.sections}
               selectedId={restNav.selectedId}
             />
-          </>
-        ) : (
-          <>
-            {restNav && (
-              <NavButtons desktop={false}>
-                <div />
-                <Button
-                  tertiary
-                  endIcon={<ArrowRightIcon />}
-                  onClick={() => setShowDocsMenu(false)}
-                >
-                  API menu
-                </Button>
-              </NavButtons>
-            )}
+          </Panel>
+        )}
+        <Panel $hidden={showRestNav}>
+          {restNav && (
+            <NavButtons desktop={false}>
+              <div />
+              <Button
+                type="button"
+                tertiary
+                endIcon={<ArrowRightIcon />}
+                onClick={() => setShowDocsMenu(false)}
+              >
+                API menu
+              </Button>
+            </NavButtons>
+          )}
+          <DocsNavWrap>
             <FullNav
               desktop={false}
               isOpen={isOpen}
               setIsOpen={setIsOpen}
             />
-          </>
-        )}
+          </DocsNavWrap>
+        </Panel>
       </Content>
     </div>
   )
diff --git a/js/documentation/src/components/PageHeaderButtons.tsx b/js/documentation/src/components/PageHeaderButtons.tsx
index 5dac9f669f..93b50be4a1 100644
--- a/js/documentation/src/components/PageHeaderButtons.tsx
+++ b/js/documentation/src/components/PageHeaderButtons.tsx
@@ -51,7 +51,10 @@ export function HamburgerButton({
   ...props
 }: { isOpen: boolean } & ComponentPropsWithoutRef<'a'>) {
   return (
-    <HamburgerButtonWrap {...props}>
+    <HamburgerButtonWrap
+      aria-label={isOpen ? 'Close menu' : 'Open menu'}
+      {...props}
+    >
       {!isOpen && <MenuOpenIcon size={22} />}
       {isOpen && <MenuCloseIcon size={22} />}
     </HamburgerButtonWrap>

From adf979dfbfde1a6449faa012a971294485cb6d76 Mon Sep 17 00:00:00 2001
From: Anna Nguyen <anna.nguyen42@gmail.com>
Date: Thu, 10 Sep 2026 14:52:14 -0400
Subject: [PATCH 08/13] Close the mobile menu when a REST endpoint is selected.

REST routes share one Next.js pathname, so the overlay now watches asPath the same way docs navigation does.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 js/documentation/src/components/PageHeader.tsx | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/js/documentation/src/components/PageHeader.tsx b/js/documentation/src/components/PageHeader.tsx
index f2844a5260..a2b724c3c6 100644
--- a/js/documentation/src/components/PageHeader.tsx
+++ b/js/documentation/src/components/PageHeader.tsx
@@ -8,6 +8,7 @@ import { useKey } from 'rooks'
 import styled from 'styled-components'
 
 import { DISCORD_LINK } from '@src/consts'
+import { getBarePathFromPath } from '@src/utils/text'
 
 import { BreakpointIsGreaterOrEqual, mqs, useBreakpoint } from './Breakpoints'
 import { DocsSearch } from './DocsSearch'
@@ -21,8 +22,9 @@ const Filler = styled.div((_) => ({
 
 function PageHeaderUnstyled({ ...props }) {
   const [menuIsOpen, setMenuIsOpen] = useState(false)
-  const { pathname } = useRouter()
-  const prevPathname = usePrevious(pathname)
+  const { asPath } = useRouter()
+  const thisPath = getBarePathFromPath(asPath)
+  const prevPath = usePrevious(thisPath)
 
   const breakpoint = useBreakpoint()
 
@@ -33,10 +35,10 @@ function PageHeaderUnstyled({ ...props }) {
   }, [breakpoint])
 
   useEffect(() => {
-    if (pathname !== prevPathname) {
+    if (prevPath && thisPath !== prevPath) {
       setMenuIsOpen(false)
     }
-  }, [pathname, prevPathname])
+  }, [thisPath, prevPath])
 
   useKey(['Escape'], () => {
     setMenuIsOpen(false)

From b991d2f2257d79123911a75d645c5791e95ae2d4 Mon Sep 17 00:00:00 2001
From: Anna Nguyen <anna.nguyen42@gmail.com>
Date: Thu, 10 Sep 2026 14:55:38 -0400
Subject: [PATCH 09/13] Remove the API menu switcher from the mobile docs tree.

Once the user leaves the REST overlay for docs navigation, they do not need a path back to the endpoint list.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../src/components/MobileMenu.tsx             | 20 +------------------
 1 file changed, 1 insertion(+), 19 deletions(-)

diff --git a/js/documentation/src/components/MobileMenu.tsx b/js/documentation/src/components/MobileMenu.tsx
index 0f23c3693f..c9909f450d 100644
--- a/js/documentation/src/components/MobileMenu.tsx
+++ b/js/documentation/src/components/MobileMenu.tsx
@@ -1,11 +1,6 @@
 import { useRef, useState } from 'react'
 
-import {
-  ArrowLeftIcon,
-  ArrowRightIcon,
-  Button,
-  DiscordIcon,
-} from '@pluralsh/design-system'
+import { ArrowLeftIcon, Button, DiscordIcon } from '@pluralsh/design-system'
 
 import styled from 'styled-components'
 import { useIsomorphicLayoutEffect } from 'usehooks-ts'
@@ -159,19 +154,6 @@ function MobileMenu({ isOpen, setIsOpen, className }: MobileMenuProps) {
           </Panel>
         )}
         <Panel $hidden={showRestNav}>
-          {restNav && (
-            <NavButtons desktop={false}>
-              <div />
-              <Button
-                type="button"
-                tertiary
-                endIcon={<ArrowRightIcon />}
-                onClick={() => setShowDocsMenu(false)}
-              >
-                API menu
-              </Button>
-            </NavButtons>
-          )}
           <DocsNavWrap>
             <FullNav
               desktop={false}

From d0932dffbeac534a9e3603cb2969a3ff48425de5 Mon Sep 17 00:00:00 2001
From: Anna Nguyen <anna.nguyen42@gmail.com>
Date: Thu, 10 Sep 2026 15:02:20 -0400
Subject: [PATCH 10/13] Open Kapa from header selectors instead of a custom
 helper.

The centered modal is still the widget script; header buttons only use Kapa's own trigger classes.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 js/documentation/pages/_document.tsx          |  5 --
 .../src/components/DocsSearch.tsx             |  6 ---
 .../src/components/types/window.d.ts          |  9 +---
 js/documentation/src/lib/kapa.ts              | 49 -------------------
 4 files changed, 1 insertion(+), 68 deletions(-)
 delete mode 100644 js/documentation/src/lib/kapa.ts

diff --git a/js/documentation/pages/_document.tsx b/js/documentation/pages/_document.tsx
index 1c2d464b1d..8245cf98de 100644
--- a/js/documentation/pages/_document.tsx
+++ b/js/documentation/pages/_document.tsx
@@ -43,11 +43,6 @@ class MyDocument extends Document {
             type="text/javascript"
             data-widget-position="bottom-right"
           />
-          <script
-            dangerouslySetInnerHTML={{
-              __html: `window.Kapa=window.Kapa||function(){(window.Kapa.q=window.Kapa.q||[]).push(arguments)};`,
-            }}
-          />
           <script
             async
             src={`https://www.googletagmanager.com/gtag/js?id=${process.env.NEXT_PUBLIC_GA_ID}`}
diff --git a/js/documentation/src/components/DocsSearch.tsx b/js/documentation/src/components/DocsSearch.tsx
index 4f25c198e0..0badbfb6a1 100644
--- a/js/documentation/src/components/DocsSearch.tsx
+++ b/js/documentation/src/components/DocsSearch.tsx
@@ -6,8 +6,6 @@ import {
 } from '@pluralsh/design-system'
 import styled from 'styled-components'
 
-import { openKapa } from '@src/lib/kapa'
-
 import { mqs } from './Breakpoints'
 
 function SearchTrigger({ compact = false }: { compact?: boolean }) {
@@ -19,7 +17,6 @@ function SearchTrigger({ compact = false }: { compact?: boolean }) {
         type="floating"
         tooltip="Search docs"
         icon={<SearchIcon size={16} />}
-        onClick={() => openKapa('search')}
         className="docs-search-trigger"
       />
     )
@@ -29,7 +26,6 @@ function SearchTrigger({ compact = false }: { compact?: boolean }) {
     <SearchBar
       type="button"
       className="docs-search-trigger"
-      onClick={() => openKapa('search')}
       aria-label="Search docs"
     >
       <SearchIcon
@@ -51,7 +47,6 @@ function AskAiTrigger({ compact = false }: { compact?: boolean }) {
         type="secondary"
         tooltip="Ask AI"
         icon={<AiSparkleFilledIcon size={16} />}
-        onClick={() => openKapa('ai')}
         className="docs-ai-trigger"
       />
     )
@@ -62,7 +57,6 @@ function AskAiTrigger({ compact = false }: { compact?: boolean }) {
       className="docs-ai-trigger"
       secondary
       startIcon={<AiSparkleFilledIcon size={16} />}
-      onClick={() => openKapa('ai')}
     >
       Ask AI
     </AskAiButton>
diff --git a/js/documentation/src/components/types/window.d.ts b/js/documentation/src/components/types/window.d.ts
index 7be90fde5f..77b57ba615 100644
--- a/js/documentation/src/components/types/window.d.ts
+++ b/js/documentation/src/components/types/window.d.ts
@@ -29,14 +29,7 @@ interface Window {
     ): void
   }
   // Kapa docs widget (stub queue or loaded API)
-  Kapa?: ((command: string, ...args: unknown[]) => void) & {
-    open?: (options?: {
-      mode?: 'search' | 'ai'
-      query?: string
-      submit?: boolean
-    }) => void
-    q?: unknown[]
-  }
+  Kapa?: (command: string, ...args: unknown[]) => void
   // Hubspot
   _hsq?: any[]
   // Gtag
diff --git a/js/documentation/src/lib/kapa.ts b/js/documentation/src/lib/kapa.ts
deleted file mode 100644
index 5fbd362205..0000000000
--- a/js/documentation/src/lib/kapa.ts
+++ /dev/null
@@ -1,49 +0,0 @@
-export type KapaMode = 'search' | 'ai'
-
-type KapaApi = ((command: string, ...args: unknown[]) => void) & {
-  open?: (options?: { mode?: KapaMode; query?: string; submit?: boolean }) => void
-  q?: unknown[]
-}
-
-function getKapa(): KapaApi | undefined {
-  return window.Kapa as KapaApi | undefined
-}
-
-export function openKapa(mode: KapaMode, query?: string) {
-  if (typeof window === 'undefined') {
-    return
-  }
-
-  const tryOpen = () => {
-    const kapa = getKapa()
-
-    if (!kapa) {
-      return false
-    }
-
-    if (typeof kapa.open === 'function') {
-      kapa.open({ mode, ...(query ? { query } : {}) })
-
-      return true
-    }
-
-    if (typeof kapa === 'function') {
-      kapa('open', { mode, ...(query ? { query } : {}) })
-
-      return true
-    }
-
-    return false
-  }
-
-  if (tryOpen()) {
-    return
-  }
-
-  const started = Date.now()
-  const id = window.setInterval(() => {
-    if (tryOpen() || Date.now() - started > 8000) {
-      window.clearInterval(id)
-    }
-  }, 100)
-}

From 6c27d6df2fc0f9b31528575f59b329c9b32576b8 Mon Sep 17 00:00:00 2001
From: Anna Nguyen <anna.nguyen42@gmail.com>
Date: Thu, 10 Sep 2026 15:29:45 -0400
Subject: [PATCH 11/13] Name compact search buttons and drop the REST filter
 clear control.

Icon-only toolbar triggers need textValue for an accessible name, and the Input2 clear button was leftover from the custom filter we already removed.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 js/documentation/src/components/DocsSearch.tsx                  | 2 ++
 js/documentation/src/components/RestApiReference/SidebarNav.tsx | 1 -
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/js/documentation/src/components/DocsSearch.tsx b/js/documentation/src/components/DocsSearch.tsx
index 0badbfb6a1..3d8db488e1 100644
--- a/js/documentation/src/components/DocsSearch.tsx
+++ b/js/documentation/src/components/DocsSearch.tsx
@@ -15,6 +15,7 @@ function SearchTrigger({ compact = false }: { compact?: boolean }) {
         clickable
         size="large"
         type="floating"
+        textValue="Search docs"
         tooltip="Search docs"
         icon={<SearchIcon size={16} />}
         className="docs-search-trigger"
@@ -45,6 +46,7 @@ function AskAiTrigger({ compact = false }: { compact?: boolean }) {
         clickable
         size="large"
         type="secondary"
+        textValue="Ask AI"
         tooltip="Ask AI"
         icon={<AiSparkleFilledIcon size={16} />}
         className="docs-ai-trigger"
diff --git a/js/documentation/src/components/RestApiReference/SidebarNav.tsx b/js/documentation/src/components/RestApiReference/SidebarNav.tsx
index c208b4f9e7..dd04b7fc00 100644
--- a/js/documentation/src/components/RestApiReference/SidebarNav.tsx
+++ b/js/documentation/src/components/RestApiReference/SidebarNav.tsx
@@ -191,7 +191,6 @@ export function SidebarNav({
       <SidebarInner $overlay={overlay}>
         <SearchWrapper>
           <FilterInput
-            showClearButton
             placeholder="Filter API"
             startIcon={<SearchIcon />}
             value={filter}

From 4a097f7b73934cbda6c7e09f9d52900a9947253d Mon Sep 17 00:00:00 2001
From: Anna Nguyen <anna.nguyen42@gmail.com>
Date: Thu, 10 Sep 2026 16:17:03 -0400
Subject: [PATCH 12/13] Fix documentation Prettier formatting in lint-failing
 files.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 js/documentation/pages/_app.tsx               |  4 +-
 .../RestApiReference/SidebarNav.tsx           | 44 ++++++++++---------
 2 files changed, 26 insertions(+), 22 deletions(-)

diff --git a/js/documentation/pages/_app.tsx b/js/documentation/pages/_app.tsx
index 7620a68153..b7cb23e843 100644
--- a/js/documentation/pages/_app.tsx
+++ b/js/documentation/pages/_app.tsx
@@ -183,7 +183,9 @@ function App({ Component, pageProps = {}, swrConfig }: MyAppProps) {
                 {toc?.length > 0 && (
                   <SideCarContainer>
                     {isClient ? (
-                      <Suspense fallback={<div>Loading table of contents...</div>}>
+                      <Suspense
+                        fallback={<div>Loading table of contents...</div>}
+                      >
                         <TableOfContents
                           key={router.asPath}
                           toc={toc}
diff --git a/js/documentation/src/components/RestApiReference/SidebarNav.tsx b/js/documentation/src/components/RestApiReference/SidebarNav.tsx
index dd04b7fc00..6b7e4b1dec 100644
--- a/js/documentation/src/components/RestApiReference/SidebarNav.tsx
+++ b/js/documentation/src/components/RestApiReference/SidebarNav.tsx
@@ -34,27 +34,29 @@ const Sidebar = styled.aside<{ $overlay?: boolean }>(({ $overlay }) => ({
       }),
 }))
 
-const SidebarInner = styled.div<{ $overlay?: boolean }>(({ theme, $overlay }) => ({
-  overflowY: 'auto',
-  backgroundColor: theme.colors['fill-one'],
-  borderRight: $overlay ? 'none' : theme.borders['fill-one'],
-  paddingBottom: theme.spacing.xlarge,
-  paddingLeft: theme.spacing.medium,
-  paddingRight: theme.spacing.medium,
-  ...($overlay
-    ? {
-        flex: 1,
-        minHeight: 0,
-        position: 'relative',
-      }
-    : {
-        position: 'absolute',
-        top: 0,
-        left: 0,
-        right: 0,
-        bottom: 0,
-      }),
-}))
+const SidebarInner = styled.div<{ $overlay?: boolean }>(
+  ({ theme, $overlay }) => ({
+    overflowY: 'auto',
+    backgroundColor: theme.colors['fill-one'],
+    borderRight: $overlay ? 'none' : theme.borders['fill-one'],
+    paddingBottom: theme.spacing.xlarge,
+    paddingLeft: theme.spacing.medium,
+    paddingRight: theme.spacing.medium,
+    ...($overlay
+      ? {
+          flex: 1,
+          minHeight: 0,
+          position: 'relative',
+        }
+      : {
+          position: 'absolute',
+          top: 0,
+          left: 0,
+          right: 0,
+          bottom: 0,
+        }),
+  })
+)
 
 const SearchWrapper = styled.div(({ theme }) => ({
   padding: `${theme.spacing.medium}px 0`,

From 93f5c0b4ae7d2b397c2c43ed463636aea195a164 Mon Sep 17 00:00:00 2001
From: Anna Nguyen <anna.nguyen42@gmail.com>
Date: Thu, 10 Sep 2026 16:24:16 -0400
Subject: [PATCH 13/13] Fix documentation import/order lint errors.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 js/documentation/src/components/DocsSearch.tsx             | 1 +
 js/documentation/src/components/RestApiReference/index.tsx | 1 +
 2 files changed, 2 insertions(+)

diff --git a/js/documentation/src/components/DocsSearch.tsx b/js/documentation/src/components/DocsSearch.tsx
index 3d8db488e1..28f7ed991c 100644
--- a/js/documentation/src/components/DocsSearch.tsx
+++ b/js/documentation/src/components/DocsSearch.tsx
@@ -4,6 +4,7 @@ import {
   IconFrame,
   SearchIcon,
 } from '@pluralsh/design-system'
+
 import styled from 'styled-components'
 
 import { mqs } from './Breakpoints'
diff --git a/js/documentation/src/components/RestApiReference/index.tsx b/js/documentation/src/components/RestApiReference/index.tsx
index 671f48750d..798a1040ef 100644
--- a/js/documentation/src/components/RestApiReference/index.tsx
+++ b/js/documentation/src/components/RestApiReference/index.tsx
@@ -8,6 +8,7 @@ import { useMemo, useState } from 'react'
 
 import { Breadcrumbs, CheckIcon, CopyIcon, Tab } from '@pluralsh/design-system'
 import { useRouter } from 'next/router'
+
 import { PageDivider } from '@src/components/MainContent'
 import {
   ContentContainer,