From aa442fcfde0ace47d5242e5204363f472649d559 Mon Sep 17 00:00:00 2001
From: Liam Horne <liam@lihorne.com>
Date: Wed, 24 Jun 2026 13:20:28 -0700
Subject: [PATCH 1/4] docs: add section navigation

---
 src/components/DocsHeader.tsx                 |   8 +-
 src/components/DocsSectionNav.tsx             | 137 ++++++++++++++++++
 src/pages/_root.css                           |  24 ++-
 src/pages/docs/_layout.tsx                    |   2 +
 src/pages/docs/build.mdx                      |  76 ++++++++++
 src/pages/docs/guide/node/index.mdx           |  89 +++++++++---
 src/pages/docs/guide/using-tempo-with-ai.mdx  |  10 +-
 src/pages/docs/index.mdx                      | 102 ++++++++++---
 src/pages/docs/protocol/index.mdx             |  81 +++++++----
 src/pages/docs/quickstart/integrate-tempo.mdx |  90 +++++++-----
 src/pages/docs/tools.mdx                      |  70 +++++++++
 vocs.config.ts                                | 136 ++++++++++++-----
 12 files changed, 667 insertions(+), 158 deletions(-)
 create mode 100644 src/components/DocsSectionNav.tsx
 create mode 100644 src/pages/docs/build.mdx
 create mode 100644 src/pages/docs/tools.mdx

diff --git a/src/components/DocsHeader.tsx b/src/components/DocsHeader.tsx
index b885e322..2554b10c 100644
--- a/src/components/DocsHeader.tsx
+++ b/src/components/DocsHeader.tsx
@@ -61,7 +61,7 @@ export function usePathname() {
 }
 
 function isActiveMenuItem(pathname: string, item: MenuItem) {
-  if (item.label === 'Build') return pathname === '/' || pathname.startsWith('/build')
+  if (item.label === 'Build') return pathname.startsWith('/build')
   if (item.label === 'Resources')
     return pathname === '/docs/sdk' || pathname.startsWith('/docs/sdk/')
   if (item.label === 'Docs') return pathname === '/docs' || pathname.startsWith('/docs/')
@@ -1095,7 +1095,7 @@ export default function DocsHeader() {
       <div className="w-full border-line border-x bg-surface-shell">
         <nav
           ref={headerRef}
-          className="relative flex items-center justify-between border-line border-b px-5 py-4"
+          className="relative flex h-[var(--tempo-docs-primary-nav-height)] items-center justify-between border-line border-b px-5"
         >
           <a
             href="/"
@@ -1110,7 +1110,7 @@ export default function DocsHeader() {
                 <TempoLogo className="h-[18px] w-[80px]" />
                 <span
                   aria-hidden
-                  className="flex h-[18px] items-center bg-[#2b2b2b] px-[5px] font-mono text-[12px] text-[#b2b2b2] leading-none tracking-[0]"
+                  className="flex h-[18px] items-center bg-[#2b2b2b] px-[5px] font-mono text-[#b2b2b2] text-[12px] leading-none tracking-[0]"
                 >
                   API
                 </span>
@@ -1314,7 +1314,7 @@ export default function DocsHeader() {
             : 'pointer-events-none -translate-y-2 opacity-0'
         }`}
       >
-        <div className="flex h-[calc(100dvh-var(--vocs-spacing-topNav,65px))] w-full flex-col overflow-y-auto border-line border-x border-b bg-background px-5 pb-5">
+        <div className="flex h-[calc(100dvh-var(--tempo-docs-primary-nav-height,65px))] w-full flex-col overflow-y-auto border-line border-x border-b bg-background px-5 pb-5">
           {menu.map((item) => {
             const active = isActiveMenuItem(pathname, item)
             // The "Docs" item is the entry point to the docs sidebar: on docs
diff --git a/src/components/DocsSectionNav.tsx b/src/components/DocsSectionNav.tsx
new file mode 100644
index 00000000..e777e6a9
--- /dev/null
+++ b/src/components/DocsSectionNav.tsx
@@ -0,0 +1,137 @@
+'use client'
+
+import { useEffect, useRef } from 'react'
+import { useRouter } from 'waku'
+
+type SectionNavItem = {
+  id: 'overview' | 'build' | 'integrate' | 'protocol' | 'tools' | 'node'
+  label: string
+  href: string
+  matches: string[]
+}
+
+const sectionNavItems: SectionNavItem[] = [
+  {
+    id: 'overview',
+    label: 'Get Started',
+    href: '/docs',
+    matches: ['/docs', '/docs/guide/using-tempo-with-ai', '/docs/partners'],
+  },
+  {
+    id: 'build',
+    label: 'Build on Tempo',
+    href: '/docs/build',
+    matches: [
+      '/docs/build',
+      '/docs/guide/getting-funds',
+      '/docs/guide/payments',
+      '/docs/guide/issuance',
+      '/docs/guide/stablecoin-dex',
+      '/docs/guide/private-zones',
+      '/docs/guide/machine-payments',
+    ],
+  },
+  {
+    id: 'integrate',
+    label: 'Integrate Tempo',
+    href: '/docs/quickstart/integrate-tempo',
+    matches: [
+      '/docs/ecosystem',
+      '/docs/guide/bridge-bungee',
+      '/docs/guide/bridge-layerzero',
+      '/docs/guide/bridge-relay',
+      '/docs/guide/tempo-transaction',
+      '/docs/quickstart',
+    ],
+  },
+  {
+    id: 'protocol',
+    label: 'Tempo Protocol',
+    href: '/docs/protocol',
+    matches: ['/docs/protocol'],
+  },
+  {
+    id: 'tools',
+    label: 'Tools & SDKs',
+    href: '/docs/tools',
+    matches: [
+      '/api',
+      '/docs/cli',
+      '/docs/developer-tools',
+      '/docs/hosted-services',
+      '/docs/protocol/rpc',
+      '/docs/sdk',
+      '/docs/tools',
+      '/docs/wallet',
+    ],
+  },
+  {
+    id: 'node',
+    label: 'Run a Tempo Node',
+    href: '/docs/guide/node',
+    matches: ['/docs/changelog', '/docs/guide/node'],
+  },
+]
+
+function pathMatches(pathname: string, prefix: string) {
+  return pathname === prefix || pathname.startsWith(`${prefix}/`)
+}
+
+function isActive(pathname: string, item: SectionNavItem) {
+  if (item.id === 'overview') return item.matches.includes(pathname)
+  if (item.id === 'tools' && pathMatches(pathname, '/docs/protocol/rpc')) return true
+  if (item.id === 'protocol' && pathMatches(pathname, '/docs/protocol/rpc')) return false
+  return item.matches.some((prefix) => pathMatches(pathname, prefix))
+}
+
+export default function DocsSectionNav() {
+  const { path } = useRouter()
+  const pathname = path ?? '/'
+  const navRef = useRef<HTMLElement | null>(null)
+  const activeLinkRef = useRef<HTMLAnchorElement | null>(null)
+  const activeLabel = sectionNavItems.find((item) => isActive(pathname, item))?.label ?? null
+
+  useEffect(() => {
+    if (!activeLabel) return
+    const nav = navRef.current
+    const activeLink = activeLinkRef.current
+    if (!nav || !activeLink) return
+
+    const centeredLeft = activeLink.offsetLeft - nav.clientWidth / 2 + activeLink.offsetWidth / 2
+    nav.scrollTo({ left: Math.max(0, centeredLeft), behavior: 'instant' })
+  }, [activeLabel])
+
+  return (
+    <div className="docs-section-nav border-line border-x border-b bg-surface-shell">
+      <nav
+        ref={navRef}
+        aria-label="Documentation sections"
+        className="flex h-[var(--tempo-docs-section-nav-height)] items-center overflow-x-auto px-3 [scrollbar-width:none] sm:px-5 [&::-webkit-scrollbar]:hidden"
+      >
+        <ul className="flex min-w-max items-center gap-1">
+          {sectionNavItems.map((item) => {
+            const active = isActive(pathname, item)
+            return (
+              <li key={item.id}>
+                <a
+                  ref={(element) => {
+                    if (active) activeLinkRef.current = element
+                  }}
+                  href={item.href}
+                  aria-current={active ? 'page' : undefined}
+                  className={`flex h-8 items-center rounded-[4px] px-3 font-sans text-[13px] tracking-[0] transition-colors ${
+                    active
+                      ? 'bg-foreground/[0.06] text-foreground'
+                      : 'text-foreground/50 hover:bg-foreground/[0.035] hover:text-foreground'
+                  }`}
+                >
+                  {item.label}
+                </a>
+              </li>
+            )
+          })}
+        </ul>
+      </nav>
+    </div>
+  )
+}
diff --git a/src/pages/_root.css b/src/pages/_root.css
index 60af9c44..046e1c14 100644
--- a/src/pages/_root.css
+++ b/src/pages/_root.css
@@ -61,9 +61,14 @@
 @layer utilities {
   :root {
     --tempo-docs-outline-width: 280px;
+    --tempo-docs-primary-nav-height: 65px;
+    --tempo-docs-section-nav-height: 44px;
     --tempo-docs-shell-width: 100%;
     --tempo-docs-sidebar-width: 280px;
-    --vocs-spacing-topNav: 65px;
+    --vocs-spacing-topNav: calc(
+      var(--tempo-docs-primary-nav-height) +
+      var(--tempo-docs-section-nav-height)
+    );
   }
 
   html,
@@ -73,6 +78,22 @@
     font-family: var(--font-pilat-book), ui-sans-serif, system-ui, sans-serif;
   }
 
+  .docs-section-nav {
+    position: fixed;
+    top: var(--tempo-docs-primary-nav-height);
+    right: 0;
+    left: 0;
+    z-index: 50;
+
+    @media (width >= 1080px) {
+      right: max(0px, calc((100% - var(--tempo-docs-shell-width)) * 0.5));
+      left: calc(
+        max(0px, calc((100% - var(--tempo-docs-shell-width)) * 0.5)) +
+        var(--tempo-docs-sidebar-width)
+      );
+    }
+  }
+
   [data-v-gutter-top],
   [data-v-gutter-logo] {
     display: none;
@@ -86,6 +107,7 @@
     @media (width >= 1080px) {
       left: max(0px, calc((100% - var(--tempo-docs-shell-width)) * 0.5));
       width: var(--tempo-docs-sidebar-width);
+      padding-top: var(--tempo-docs-primary-nav-height);
       justify-content: flex-start;
       background: var(--vocs-background-color-primary);
       border-right: 1px solid var(--vocs-border-color-primary);
diff --git a/src/pages/docs/_layout.tsx b/src/pages/docs/_layout.tsx
index fad4f330..c6cac89f 100644
--- a/src/pages/docs/_layout.tsx
+++ b/src/pages/docs/_layout.tsx
@@ -2,6 +2,7 @@
 
 import { lazy, type PropsWithChildren, Suspense } from 'react'
 import DocsHeader from '../../components/DocsHeader'
+import DocsSectionNav from '../../components/DocsSectionNav'
 import DocsSidebarDrawer from '../../components/DocsSidebarDrawer'
 import { usePageSettled } from '../../lib/pageSettled'
 
@@ -37,6 +38,7 @@ export default function DocsLayout(
   return (
     <>
       <DocsHeader />
+      <DocsSectionNav />
       <DocsSidebarDrawer />
       {props.children}
       <Suspense fallback={null}>
diff --git a/src/pages/docs/build.mdx b/src/pages/docs/build.mdx
new file mode 100644
index 00000000..c47f597d
--- /dev/null
+++ b/src/pages/docs/build.mdx
@@ -0,0 +1,76 @@
+---
+title: Build on Tempo
+description: Choose Tempo build guides for stablecoin payments, issuance, exchange, private zones, agentic payments, fee sponsorship, and production workflows for launch.
+---
+
+import { Cards, Card } from 'vocs'
+
+# Build on Tempo
+
+Use this section when you are designing payment experiences or payment infrastructure on Tempo. The guides here focus on what your product should do: move stablecoins, issue assets, exchange liquidity, isolate activity in private zones, or let agents pay for services.
+
+Start with **Make Payments** if you are not sure where to begin. It covers the core transfer flow and introduces the payment primitives used throughout the rest of the docs.
+
+## Payment Workflows
+
+<Cards>
+  <Card
+    title="Make Payments"
+    description="Send and receive stablecoin payments, attach memos, sponsor fees, and handle parallel transactions."
+    to="/docs/guide/payments"
+    icon="lucide:send"
+  />
+  <Card
+    title="Issue Stablecoins"
+    description="Create, mint, manage, and distribute rewards for stablecoins using TIP-20 tokens."
+    to="/docs/guide/issuance"
+    icon="lucide:coins"
+  />
+  <Card
+    title="Exchange Stablecoins"
+    description="Use Tempo's enshrined stablecoin exchange for swaps and fee-liquidity workflows."
+    to="/docs/guide/stablecoin-dex"
+    icon="lucide:arrow-left-right"
+  />
+  <Card
+    title="Private Zones"
+    description="Connect to zones, deposit funds, send tokens privately, bridge, swap, and withdraw."
+    to="/docs/guide/private-zones"
+    icon="lucide:lock-keyhole"
+  />
+  <Card
+    title="Agentic Payments"
+    description="Accept one-time, pay-as-you-go, and streamed payments through the Machine Payments Protocol."
+    to="/docs/guide/machine-payments"
+    icon="lucide:bot"
+  />
+</Cards>
+
+## Before You Ship
+
+<Cards>
+  <Card
+    title="Get Funds"
+    description="Fund wallets and test payment flows before moving to production integrations."
+    to="/docs/guide/getting-funds"
+    icon="lucide:wallet"
+  />
+  <Card
+    title="Use Tempo Transactions"
+    description="Batch calls, sponsor fees, schedule execution, and build richer payment flows."
+    to="/docs/guide/tempo-transaction"
+    icon="lucide:layers"
+  />
+  <Card
+    title="Configure Receive Policies"
+    description="Control which tokens and senders an account can receive for TIP-20 transfers."
+    to="/docs/guide/payments/configure-receive-policies"
+    icon="lucide:shield-check"
+  />
+  <Card
+    title="Pay Fees in Any Stablecoin"
+    description="Use Tempo's fee system to pay transaction fees with supported stablecoins."
+    to="/docs/guide/payments/pay-fees-in-any-stablecoin"
+    icon="lucide:badge-dollar-sign"
+  />
+</Cards>
diff --git a/src/pages/docs/guide/node/index.mdx b/src/pages/docs/guide/node/index.mdx
index e6a6bb1f..42635a7d 100644
--- a/src/pages/docs/guide/node/index.mdx
+++ b/src/pages/docs/guide/node/index.mdx
@@ -1,48 +1,93 @@
 ---
-description: Run your own Tempo node for direct network access. Set up RPC nodes for API access or validator nodes to participate in consensus.
+title: Run a Tempo Node
+description: Run Tempo node infrastructure for RPC access, validator operations, system requirements, installation, monitoring, security, upgrades, and release operations.
 ---
 
 import { Cards, Card } from 'vocs'
 
-# Tempo Node
+# Run a Tempo Node
 
-Running a Tempo node allows you to interact with the network directly, providing your own RPC access or contributing to network infrastructure. Nodes provide JSON-RPC API access for applications, explorers, and wallets but do not participate in consensus.
+Run Tempo infrastructure when you need direct network access, dedicated RPC capacity, validator operations, or lower-level visibility into network behavior.
 
-## Supported Platforms
+Most teams should start with an RPC node. Validator operation requires coordination with the Tempo team and is documented separately from the RPC path.
 
-Prebuilt binaries are available for:
-- **Linux** (x86_64 and ARM64) - requires glibc ≥ 2.38
-- **macOS** (ARM64)
-
-## Getting Started
+## RPC Node Path
 
 <Cards>
   <Card
-    description="Hardware and software requirements for running a node"
+    title="System Requirements"
+    description="Hardware, operating system, and runtime requirements for Tempo node software."
     to="/docs/guide/node/system-requirements"
     icon="lucide:hard-drive"
-    title="System Requirements"
   />
   <Card
-    description="Download and install the Tempo node software"
+    title="Installation"
+    description="Download, install, and prepare the Tempo node binary for supported platforms."
     to="/docs/guide/node/installation"
     icon="lucide:download"
-    title="Installation"
   />
   <Card
-    description="Configure and run a full RPC node"
+    title="Run an RPC Node"
+    description="Configure and run a node that serves JSON-RPC traffic for apps, explorers, and wallets."
     to="/docs/guide/node/rpc"
-    icon="lucide:play"
-    title="Running an RPC Node"
+    icon="lucide:server"
+  />
+  <Card
+    title="Node Security"
+    description="Harden node operations, network exposure, key handling, and runtime configuration."
+    to="/docs/guide/node/security"
+    icon="lucide:shield"
+  />
+</Cards>
+
+## Validator Operations
+
+<Cards>
+  <Card
+    title="Validator Overview"
+    description="Understand validator responsibilities and the operational path before onboarding."
+    to="/docs/guide/node/validator"
+    icon="lucide:badge-check"
+  />
+  <Card
+    title="Validator Onboarding"
+    description="Set up validator software and prepare to participate in coordinated network operations."
+    to="/docs/guide/node/validator-setup"
+    icon="lucide:clipboard-check"
+  />
+  <Card
+    title="Monitoring"
+    description="Monitor validator health, status, failover, and lifecycle operations."
+    to="/docs/guide/node/validator-monitoring"
+    icon="lucide:activity"
+  />
+  <Card
+    title="Troubleshooting"
+    description="Debug validator issues, common failure modes, and operational questions."
+    to="/docs/guide/node/validator-troubleshooting"
+    icon="lucide:wrench"
+  />
+</Cards>
+
+## Releases
+
+<Cards>
+  <Card
+    title="Upgrade Cadence"
+    description="Understand how Tempo node upgrades are planned, communicated, and rolled out."
+    to="/docs/guide/node/upgrade-cadence"
+    icon="lucide:calendar-clock"
   />
   <Card
-    description="Upcoming and past network upgrades and important releases"
+    title="Network Upgrades"
+    description="Track upgrade instructions, release notes, and node operator actions."
     to="/docs/guide/node/network-upgrades"
     icon="lucide:arrow-up-circle"
-    title="Network Upgrades and Releases"
+  />
+  <Card
+    title="Changelog"
+    description="Review recent changes relevant to node operators and protocol users."
+    to="/docs/changelog"
+    icon="lucide:list-tree"
   />
 </Cards>
-
-:::info
-Validator onboarding requires coordination with the Tempo team. Reach out to us if you are interested.
-:::
diff --git a/src/pages/docs/guide/using-tempo-with-ai.mdx b/src/pages/docs/guide/using-tempo-with-ai.mdx
index 21f658cc..7dd317d0 100644
--- a/src/pages/docs/guide/using-tempo-with-ai.mdx
+++ b/src/pages/docs/guide/using-tempo-with-ai.mdx
@@ -1,6 +1,6 @@
 ---
-title: Developing with LLMs
-description: Give your AI coding agent Tempo documentation context with skills, Markdown pages, and MCP.
+title: Use Tempo with AI
+description: Connect AI coding agents to Tempo docs, source context, MCP tools, Markdown pages, plugins, workflow skills, and feedback loops for accurate development.
 interactive: true
 ---
 
@@ -8,7 +8,11 @@ import { Tabs, Tab } from 'vocs'
 import { DocsLinkButton } from '../../../components/DocsLinkButton.tsx'
 import { TempoMcpExplorer } from '../../../components/TempoMcpExplorer.tsx'
 
-# Developing with LLMs
+# Use Tempo with AI
+
+Tempo publishes documentation, Markdown pages, MCP tools, and agent plugins so AI coding agents can work with Tempo using current project context instead of guesses.
+
+Use this page when you want Claude, Codex, Cursor, Amp, or another MCP-compatible client to search Tempo docs, read source-linked references, and install reusable Tempo workflows.
 
 ## Connect to Tempo's MCP server
 
diff --git a/src/pages/docs/index.mdx b/src/pages/docs/index.mdx
index 823a2bb5..f7cc459d 100644
--- a/src/pages/docs/index.mdx
+++ b/src/pages/docs/index.mdx
@@ -1,48 +1,104 @@
 ---
-description: Explore Tempo's blockchain documentation, integration guides, and protocol specs. Build low-cost, high-throughput payment applications.
+title: Get Started
+description: Start building on Tempo with integration paths, payment guides, protocol references, SDKs, hosted services, node operations, AI resources, and partners.
 ---
 
 import { Cards, Card } from 'vocs'
 
-# Tempo [Documentation, integration guides, and protocol specifications]
+# Get Started
 
-## Welcome to Tempo! 
+Connect to Tempo and learn how to build stablecoin payment products. Start with network setup, fund a wallet, send a payment, then move into production workflows, protocol references, tooling, or infrastructure.
 
-Tempo is a general-purpose blockchain optimized for payments. Tempo is designed to be a low-cost, high-throughput blockchain with user and developer features that we believe should be core to a modern payment system.
+If you are new to Tempo, start with **Integrate Tempo** to connect to the network, then move to **Build on Tempo** for payment workflows.
 
-Tempo was designed in close collaboration with an exceptional group of [design partners](https://tempo.xyz/ecosystem) who are helping to validate the system against real payment workloads.
-
-These docs cover everything from creating a wallet to building payment systems on Tempo.
+## First Steps
 
 <Cards>
   <Card
-    title="Create a Wallet"
-    description="Set up a Tempo Wallet and run your first transaction on mainnet."
+    title="Connect to Tempo"
+    description="Add Tempo chain configuration, RPC endpoints, explorer links, and wallet connection details."
+    to="/docs/quickstart/integrate-tempo"
+    icon="lucide:plug"
+  />
+  <Card
+    title="Get Funds"
+    description="Fund a test wallet so you can deploy contracts, send payments, and exercise integration flows."
     to="/docs/guide/getting-funds"
     icon="lucide:wallet"
   />
   <Card
-    title="Connect to Tempo"
-    description="RPC endpoints, chain config, SDKs, and integration guides for mainnet."
+    title="Send a Payment"
+    description="Send a stablecoin payment, configure fees, attach memos, and handle receipt policies."
+    to="/docs/guide/payments"
+    icon="lucide:send"
+  />
+</Cards>
+
+## Choose a Section
+
+<Cards>
+  <Card
+    title="Build on Tempo"
+    description="Payments, stablecoin issuance, exchange, private zones, and agentic payment workflows."
+    to="/docs/build"
+    icon="lucide:blocks"
+  />
+  <Card
+    title="Integrate Tempo"
+    description="Network details, faucet funds, wallet support, EVM differences, bridges, and ecosystem entry points."
     to="/docs/quickstart/integrate-tempo"
-    icon="lucide:rocket"
+    icon="lucide:plug"
   />
   <Card
-    title="Make Payments"
-    description="Send payments, attach memos, sponsor fees, and build payment flows."
-    to="/docs/guide/payments"
-    icon="lucide:arrow-left-right"
+    title="Tempo Protocol"
+    description="Technical references for tokens, policies, fees, transactions, blockspace, exchange, zones, and TIPs."
+    to="/docs/protocol"
+    icon="lucide:file-code"
   />
   <Card
-    title="Make Agentic Payments"
-    description="Let agents pay for services using the Machine Payments Protocol - sessions and streaming payments."
-    to="/docs/guide/machine-payments"
+    title="Tools & SDKs"
+    description="SDKs, CLI, hosted services, wallet docs, JSON-RPC, and indexer tooling."
+    to="/docs/tools"
+    icon="lucide:terminal-square"
+  />
+  <Card
+    title="Run a Tempo Node"
+    description="Run Tempo infrastructure for direct RPC access, validation workflows, monitoring, and upgrades."
+    to="/docs/guide/node"
+    icon="lucide:server"
+  />
+</Cards>
+
+## Common Workflows
+
+<Cards>
+  <Card
+    title="Issue a Stablecoin"
+    description="Create, mint, manage, and distribute rewards for a TIP-20 stablecoin."
+    to="/docs/guide/issuance"
+    icon="lucide:coins"
+  />
+  <Card
+    title="Find Partners"
+    description="Explore ecosystem partners across issuers, wallets, ramps, compliance, custody, and infrastructure."
+    to="/docs/partners"
+    icon="lucide:network"
+  />
+</Cards>
+
+## Resources
+
+<Cards>
+  <Card
+    title="Use Tempo with AI"
+    description="Give coding agents Tempo docs, source context, MCP tools, and agent workflow plugins."
+    to="/docs/guide/using-tempo-with-ai"
     icon="lucide:bot"
   />
   <Card
-    title="Read Protocol Specs"
-    description="Native stablecoins, smart accounts, fee markets, and the full protocol specification."
-    to="/docs/protocol"
-    icon="lucide:file-text"
+    title="Partners"
+    description="Find issuers, wallets, ramps, compliance, custody, analytics, orchestration, and infrastructure partners."
+    to="/docs/partners"
+    icon="lucide:network"
   />
 </Cards>
diff --git a/src/pages/docs/protocol/index.mdx b/src/pages/docs/protocol/index.mdx
index 46073731..706ec893 100644
--- a/src/pages/docs/protocol/index.mdx
+++ b/src/pages/docs/protocol/index.mdx
@@ -1,70 +1,87 @@
 ---
-description: Technical specifications and reference documentation for the Tempo blockchain protocol, purpose-built for global payments at scale.
+title: Tempo Protocol
+description: Read Tempo protocol references for tokens, policies, fees, transactions, blockspace, exchange, zones, network upgrades, TIP specs, and implementation details.
 ---
 
 import { Cards, Card } from 'vocs'
 
 # Tempo Protocol
 
-Tempo is a blockchain protocol purpose-built for global payments. Rather than being a general-purpose platform, Tempo makes deliberate technical choices optimized for payments at scale.
+Use this section when you need the technical reference for Tempo itself. These pages are written for implementers, auditors, wallet teams, infrastructure operators, and anyone building against protocol-level behavior rather than a single product workflow.
 
-This section provides details on the Tempo Protocol specifications, and serves as a technical reference for protocol implementers, auditors, and core contributors building on Tempo. 
+If you are building an app, start with the guides in **Build on Tempo** and come here when you need exact semantics, ABI details, or protocol rationale.
 
-## Protocol Components
+## Core Primitives
 
 <Cards>
   <Card
-    description="Core token standard with native stablecoin features and policy registry integration"
+    title="TIP-20 Tokens"
+    description="Stablecoin-native token behavior, metadata, fees, memos, policies, and liquidity routing."
     to="/docs/protocol/tip20/overview"
     icon="lucide:coins"
-    title="TIP-20 Tokens"
-  />
-  <Card
-    description="Reward distribution system for token holders with automated yield mechanisms"
-    to="/docs/protocol/tip20-rewards/overview"
-    icon="lucide:gift"
-    title="Tempo Token Rewards"
   />
   <Card
-    description="Policy registry system for compliance, access control, and token governance"
+    title="Tempo Policies"
+    description="TIP-403 policy checks, receive policies, access controls, and registry behavior."
     to="/docs/protocol/tip403/overview"
-    icon="lucide:shield"
-    title="Tempo Policies (TIP-403)"
-  />
-  <Card
-    description="Receiver-side token and sender filters for inbound TIP-20 transfers and mints"
-    to="/docs/protocol/tip403/receive-policies"
     icon="lucide:shield-check"
-    title="Receive Policies"
   />
   <Card
-    description="Multi-token fee payment system with AMM for stablecoin conversion"
-    to="/docs/protocol/fees"
-    icon="lucide:wallet"
     title="Fees"
+    description="Stablecoin fee payment, fee accounting, and the fee AMM used for conversion."
+    to="/docs/protocol/fees"
+    icon="lucide:badge-dollar-sign"
   />
   <Card
-    description="EIP-2718 transaction type with native passkeys, batching, scheduling, and fee sponsorship"
+    title="Tempo Transactions"
+    description="Tempo transaction type, batching, scheduling, fee sponsorship, and account keychains."
     to="/docs/protocol/transactions"
     icon="lucide:layers"
-    title="Tempo Transactions"
   />
+</Cards>
+
+## Network Systems
+
+<Cards>
   <Card
-    description="Block format and payment lanes for optimized throughput"
-    to="/docs/protocol/blockspace/overview"
-    icon="lucide:layout"
     title="Blockspace"
+    description="Consensus, finality, block format, payment lanes, and throughput-oriented protocol design."
+    to="/docs/protocol/blockspace/overview"
+    icon="lucide:layout-dashboard"
   />
   <Card
-    description="Enshrined stablecoin DEX for stablecoin interoperability"
+    title="Stablecoin DEX"
+    description="Enshrined stablecoin exchange, quote tokens, swaps, liquidity, and exchange balances."
     to="/docs/protocol/exchange"
     icon="lucide:arrow-left-right"
-    title="Stablecoin DEX"
   />
   <Card
-    description="View the full Tempo protocol source code and implementation"
+    title="Zones"
+    description="Private zone architecture, accounts, bridging, RPC, execution, gas, and proving."
+    to="/docs/protocol/zones"
+    icon="lucide:scan"
+  />
+  <Card
+    title="Network Upgrades"
+    description="Track upgrade specifications, migration notes, and release-level protocol changes."
+    to="/docs/protocol/upgrades/t7"
+    icon="lucide:arrow-up-circle"
+  />
+</Cards>
+
+## Specifications
+
+<Cards>
+  <Card
+    title="TIPs"
+    description="Browse Tempo Improvement Proposals for standards, process changes, and protocol history."
+    to="/docs/protocol/tips"
+    icon="lucide:file-text"
+  />
+  <Card
+    title="GitHub Repository"
+    description="Read the Tempo source implementation and follow protocol development in the open."
     to="https://github.com/tempoxyz/tempo"
     icon="lucide:github"
-    title="GitHub Repository"
   />
 </Cards>
diff --git a/src/pages/docs/quickstart/integrate-tempo.mdx b/src/pages/docs/quickstart/integrate-tempo.mdx
index 8fbe67c5..3853f74e 100644
--- a/src/pages/docs/quickstart/integrate-tempo.mdx
+++ b/src/pages/docs/quickstart/integrate-tempo.mdx
@@ -1,76 +1,88 @@
 ---
-description: Build on Tempo Testnet. Connect to the network, explore SDKs, and follow guides for payments, stablecoin issuance, and exchange.
+title: Integrate Tempo
+description: Connect apps and wallets to Tempo with network configuration, faucet funding, EVM compatibility notes, bridges, verification, and ecosystem resources.
 interactive: true
 ---
 
-import * as Demo from '../../../components/guides/Demo.tsx'
-import { ConnectWallet } from '../../../components/ConnectWallet.tsx'
 import { Cards, Card } from 'vocs'
 
 # Integrate Tempo
 
-Tempo is fully compatible with the Ethereum Virtual Machine (EVM), targeting the **Osaka** EVM hard fork. So, everything you'd expect to work with Ethereum works on Tempo, with only a few exceptions which we detail on the [EVM Differences](/docs/quickstart/evm-compatibility) page. 
+Use this section when you are connecting an existing app, wallet, contract, bridge, or infrastructure service to Tempo. These pages cover the practical edges of integration: chain configuration, RPC endpoints, faucet funding, wallet support, EVM compatibility, predeploys, contract verification, and ecosystem resources.
 
+Tempo is EVM-compatible and targets the **Osaka** EVM hard fork. Most Ethereum tooling works as expected, with Tempo-specific differences documented where they matter.
+
+## First Connection
 
 <Cards>
   <Card
     icon="lucide:network"
     title="Connect to the Network"
-    description="Learn how to connect to the Tempo Testnet with your wallet or programmatically."
+    description="Add Tempo chain configuration, RPC endpoints, explorer links, and wallet connection details."
     to="/docs/quickstart/connection-details"
   />
   <Card
-    icon="lucide:wallet"
-    title="Integrate Wallet Support"
-    description="Support Tempo in your wallet with fee sponsorship and native stablecoins."
-    to="/docs/quickstart/wallet-developers"
+    icon="lucide:droplets"
+    title="Get Testnet Faucet Funds"
+    description="Fund test wallets so you can deploy contracts, send payments, and exercise integration flows."
+    to="/docs/quickstart/faucet"
+  />
+  <Card
+    icon="lucide:badge-check"
+    title="Verify Contracts"
+    description="Verify deployed contracts and make them easier to inspect, debug, and share."
+    to="/docs/quickstart/verify-contracts"
   />
 </Cards>
 
-## Start Building
-
-The guides below will help you get a sense for what is possible to do with Tempo. All of the guides below are fully-featured Tempo applications themselves, built with the [Tempo SDKs](/docs/sdk).
+## App and Wallet Integration
 
 <Cards>
   <Card
-    icon="lucide:send"
-    title="Make Payments"
-    description="Send and receive stablecoin payments with flexible fee options and sponsorship capabilities"
-    to="/docs/guide/payments"
+    icon="lucide:wallet"
+    title="Wallet Developers"
+    description="Support Tempo in wallets with stablecoin-native fees, chain metadata, and transaction behavior."
+    to="/docs/quickstart/wallet-developers"
+  />
+  <Card
+    icon="lucide:code-2"
+    title="EVM Differences"
+    description="Understand the Tempo-specific behavior that differs from default Ethereum assumptions."
+    to="/docs/quickstart/evm-compatibility"
   />
   <Card
-    icon="lucide:coins"
-    title="Issue Stablecoins"
-    description="Create and manage your own stablecoin with built-in compliance features"
-    to="/docs/guide/issuance"
+    icon="lucide:boxes"
+    title="Predeployed Contracts"
+    description="Find Tempo predeploys and system contracts used by integrations and protocol features."
+    to="/docs/quickstart/predeployed-contracts"
   />
   <Card
-    icon="lucide:arrow-left-right"
-    title="Exchange Stablecoins"
-    description="Trade between stablecoins on Tempo's enshrined decentralized exchange"
-    to="/docs/guide/stablecoin-dex"
+    icon="lucide:list"
+    title="Token List Registry"
+    description="Use Tempo token lists to discover supported assets and present stablecoins correctly."
+    to="/docs/quickstart/tokenlist"
   />
 </Cards>
 
-## Go Deeper
-
-The Tempo source code is fully open-source and available on [GitHub](https://github.com/tempoxyz).
-
-If you're interested in learning more about how Tempo works under the hood, feel free to explore the codebase directly, run a node for yourself, or refer to the protocol specifications for a deeper understanding. 
+## Interoperability
 
 <Cards>
   <Card
-    icon="lucide:server"
-    title="Run a Tempo Node"
-    description="System requirements, installation and usage instructions for running a Tempo node."
-    to="/docs/guide/node"
+    icon="lucide:bridge"
+    title="Bridge via LayerZero"
+    description="Bridge supported assets to and from Tempo using LayerZero."
+    to="/docs/guide/bridge-layerzero"
   />
   <Card
-    icon="lucide:book-open"
-    title="Protocol Specifications"
-    description="Technical specifications for tokens, fees, transactions, and protocol components."
-    to="/docs/protocol"
+    icon="lucide:route"
+    title="Bridge via Relay"
+    description="Use Relay to move assets between Tempo and other supported networks."
+    to="/docs/guide/bridge-relay"
+  />
+  <Card
+    icon="lucide:network"
+    title="Ecosystem"
+    description="Find bridges, wallets, analytics, infrastructure, compliance, and orchestration partners."
+    to="/docs/ecosystem"
   />
 </Cards>
-
-We welcome contributions from the community to help improve and expand the project.
diff --git a/src/pages/docs/tools.mdx b/src/pages/docs/tools.mdx
new file mode 100644
index 00000000..3e54c0d8
--- /dev/null
+++ b/src/pages/docs/tools.mdx
@@ -0,0 +1,70 @@
+---
+title: Tools & SDKs
+description: Find Tempo SDKs, CLI commands, hosted services, wallet docs, RPC references, and indexer tools for building, testing, and operating production integrations.
+---
+
+import { Cards, Card } from 'vocs'
+
+# Tools & SDKs
+
+Use this section when you need the implementation surface for Tempo: libraries, command-line tools, managed services, wallet integration, RPC references, and query access to network data.
+
+If you are integrating a product, start with the TypeScript SDKs and hosted services. If you are operating infrastructure or debugging low-level behavior, start with the CLI and RPC reference.
+
+## Developer Surfaces
+
+<Cards>
+  <Card
+    title="SDKs"
+    description="Use TypeScript, Go, Foundry, Python, and Rust tooling for Tempo applications."
+    to="/docs/sdk"
+    icon="lucide:package"
+  />
+  <Card
+    title="CLI"
+    description="Manage wallets, make requests, download binaries, and run node-related commands."
+    to="/docs/cli"
+    icon="lucide:terminal"
+  />
+  <Card
+    title="Hosted Services"
+    description="Use managed Tempo services for fee sponsorship and indexer-backed data access."
+    to="/docs/hosted-services"
+    icon="lucide:cloud"
+  />
+  <Card
+    title="Tempo Wallet"
+    description="Integrate the Tempo Wallet, recipes, references, and agent-oriented wallet flows."
+    to="/docs/wallet"
+    icon="lucide:wallet"
+  />
+</Cards>
+
+## References and Data
+
+<Cards>
+  <Card
+    title="JSON-RPC Reference"
+    description="Browse Tempo RPC methods, request shapes, and protocol-level API behavior."
+    to="/docs/protocol/rpc"
+    icon="lucide:braces"
+  />
+  <Card
+    title="Indexer (tidx)"
+    description="Query Tempo blocks, transactions, logs, token balances, and decoded events through SQL."
+    to="/docs/developer-tools/indexer"
+    icon="lucide:database"
+  />
+  <Card
+    title="Hosted Fee Payer"
+    description="Sponsor Tempo transaction fees through hosted JSON-RPC relay endpoints."
+    to="/docs/developer-tools/fee-payer"
+    icon="lucide:badge-dollar-sign"
+  />
+  <Card
+    title="Use Tempo with AI"
+    description="Install MCP, plugins, and docs context so coding agents can work with Tempo accurately."
+    to="/docs/guide/using-tempo-with-ai"
+    icon="lucide:bot"
+  />
+</Cards>
diff --git a/vocs.config.ts b/vocs.config.ts
index 859801bc..7603a884 100644
--- a/vocs.config.ts
+++ b/vocs.config.ts
@@ -115,7 +115,7 @@ export default defineConfig({
       path: '/api',
       spec: 'https://api.tempo.xyz/openapi.json',
       sidebar: {
-        collapsed: true,
+        collapsed: false,
         backLink: false,
         intro: [
           {
@@ -174,14 +174,14 @@ export default defineConfig({
       link: 'https://twitter.com/tempo',
     },
   ],
-  sidebar: {
-    '/docs': [
+  sidebar: (() => {
+    const docsSidebar = [
       {
-        text: 'Home',
+        text: 'Get Started',
         link: '/docs',
       },
       {
-        text: 'Developing with LLMs',
+        text: 'AI',
         link: '/docs/guide/using-tempo-with-ai',
       },
       {
@@ -191,13 +191,17 @@ export default defineConfig({
       {
         text: 'Build on Tempo',
         items: [
+          {
+            text: 'Overview',
+            link: '/docs/build',
+          },
           {
             text: 'Getting Funds on Tempo',
             link: '/docs/guide/getting-funds',
           },
           {
             text: 'Make Payments',
-            collapsed: true,
+            collapsed: false,
             items: [
               {
                 text: 'Overview',
@@ -249,7 +253,7 @@ export default defineConfig({
           },
           {
             text: 'Issue Stablecoins',
-            collapsed: true,
+            collapsed: false,
             items: [
               {
                 text: 'Overview',
@@ -279,7 +283,7 @@ export default defineConfig({
           },
           {
             text: 'Exchange Stablecoins',
-            collapsed: true,
+            collapsed: false,
             items: [
               {
                 text: 'Overview',
@@ -301,7 +305,7 @@ export default defineConfig({
           },
           {
             text: 'Private Zones',
-            collapsed: true,
+            collapsed: false,
             items: [
               {
                 text: 'Overview',
@@ -335,7 +339,7 @@ export default defineConfig({
           },
           {
             text: 'Make Agentic Payments',
-            collapsed: true,
+            collapsed: false,
             items: [
               {
                 text: 'Overview',
@@ -371,7 +375,7 @@ export default defineConfig({
               },
               {
                 text: 'Use Cases',
-                collapsed: true,
+                collapsed: false,
                 items: [
                   {
                     text: 'Monetize Your API',
@@ -472,7 +476,7 @@ export default defineConfig({
           },
           {
             text: 'Bridging',
-            collapsed: true,
+            collapsed: false,
             items: [
               {
                 text: 'Bridge via LayerZero',
@@ -490,7 +494,7 @@ export default defineConfig({
           },
           {
             text: 'Ecosystem',
-            collapsed: true,
+            collapsed: false,
             items: [
               {
                 text: 'Overview',
@@ -533,7 +537,7 @@ export default defineConfig({
         ],
       },
       {
-        text: 'Tempo Protocol Specs',
+        text: 'Tempo Protocol',
         items: [
           {
             text: 'Overview',
@@ -541,7 +545,7 @@ export default defineConfig({
           },
           {
             text: 'TIP-20 Tokens',
-            collapsed: true,
+            collapsed: false,
             items: [
               {
                 text: 'Overview',
@@ -563,7 +567,7 @@ export default defineConfig({
           },
           {
             text: 'Tempo Token Rewards',
-            collapsed: true,
+            collapsed: false,
             items: [
               {
                 text: 'Overview',
@@ -577,7 +581,7 @@ export default defineConfig({
           },
           {
             text: 'Tempo Policies (TIP-403)',
-            collapsed: true,
+            collapsed: false,
             items: [
               {
                 text: 'Overview',
@@ -599,7 +603,7 @@ export default defineConfig({
           },
           {
             text: 'Fees',
-            collapsed: true,
+            collapsed: false,
             items: [
               {
                 text: 'Overview',
@@ -611,7 +615,7 @@ export default defineConfig({
               },
               {
                 text: 'Fee AMM',
-                collapsed: true,
+                collapsed: false,
                 items: [
                   {
                     text: 'Overview',
@@ -631,7 +635,7 @@ export default defineConfig({
           },
           {
             text: 'Tempo Transactions',
-            collapsed: true,
+            collapsed: false,
             items: [
               {
                 text: 'Overview',
@@ -661,7 +665,7 @@ export default defineConfig({
           },
           {
             text: 'Blockspace',
-            collapsed: true,
+            collapsed: false,
             items: [
               {
                 text: 'Overview',
@@ -679,7 +683,7 @@ export default defineConfig({
           },
           {
             text: 'Stablecoin DEX',
-            collapsed: true,
+            collapsed: false,
             items: [
               {
                 text: 'Overview',
@@ -713,7 +717,7 @@ export default defineConfig({
           },
           {
             text: 'Zones',
-            collapsed: true,
+            collapsed: false,
             items: [
               {
                 text: 'Overview',
@@ -747,7 +751,7 @@ export default defineConfig({
           },
           {
             text: 'Network Upgrades',
-            collapsed: true,
+            collapsed: false,
             items: [
               {
                 text: 'T7',
@@ -784,11 +788,15 @@ export default defineConfig({
         ],
       },
       {
-        text: 'Tempo Developer Tools',
+        text: 'Tools & SDKs',
         items: [
+          {
+            text: 'Overview',
+            link: '/docs/tools',
+          },
           {
             text: 'Hosted Services',
-            collapsed: true,
+            collapsed: false,
             items: [
               {
                 text: 'Overview',
@@ -806,7 +814,7 @@ export default defineConfig({
           },
           {
             text: 'CLI',
-            collapsed: true,
+            collapsed: false,
             items: [
               {
                 text: 'Overview',
@@ -832,7 +840,7 @@ export default defineConfig({
           },
           {
             text: 'Tempo Wallet',
-            collapsed: true,
+            collapsed: false,
             items: [
               {
                 text: 'Overview',
@@ -858,7 +866,7 @@ export default defineConfig({
           },
           {
             text: 'SDKs',
-            collapsed: true,
+            collapsed: false,
             items: [
               {
                 text: 'Overview',
@@ -866,7 +874,7 @@ export default defineConfig({
               },
               {
                 text: 'TypeScript',
-                collapsed: true,
+                collapsed: false,
                 items: [
                   {
                     text: 'Overview',
@@ -897,7 +905,7 @@ export default defineConfig({
               },
               {
                 text: 'Foundry',
-                collapsed: true,
+                collapsed: false,
                 items: [
                   {
                     text: 'Overview',
@@ -927,7 +935,7 @@ export default defineConfig({
       },
       {
         text: 'Run a Tempo Node',
-        collapsed: true,
+        collapsed: false,
         items: [
           {
             text: 'Overview',
@@ -1026,8 +1034,68 @@ export default defineConfig({
       //     },
       //   ],
       // },
-    ],
-  },
+    ]
+
+    const section = (text: string) => {
+      const item = docsSidebar.find((item) => item.text === text)
+      return item ? [item] : []
+    }
+
+    const docsHomeSidebar = [
+      {
+        text: 'First Steps',
+        items: [
+          { text: 'Connect to Tempo', link: '/docs/quickstart/integrate-tempo' },
+          { text: 'Get Funds', link: '/docs/guide/getting-funds' },
+          { text: 'Send a Payment', link: '/docs/guide/payments' },
+          { text: 'Use Tempo Transactions', link: '/docs/guide/tempo-transaction' },
+          { text: 'Issue a Stablecoin', link: '/docs/guide/issuance' },
+        ],
+      },
+      {
+        text: 'Resources',
+        items: [
+          { text: 'Tools & SDKs', link: '/docs/tools' },
+          { text: 'Tempo Protocol', link: '/docs/protocol' },
+          { text: 'Run a Tempo Node', link: '/docs/guide/node' },
+          { text: 'Use Tempo with AI', link: '/docs/guide/using-tempo-with-ai' },
+          { text: 'Partners', link: '/docs/partners' },
+        ],
+      },
+    ]
+    const buildSidebar = section('Build on Tempo')
+    const integrateSidebar = section('Integrate Tempo')
+    const specsSidebar = section('Tempo Protocol')
+    const developerToolsSidebar = section('Tools & SDKs')
+    const nodeSidebar = section('Run a Tempo Node')
+
+    return {
+      '/docs': docsHomeSidebar,
+      '/docs/build': buildSidebar,
+      '/docs/guide/getting-funds': buildSidebar,
+      '/docs/guide/payments': buildSidebar,
+      '/docs/guide/issuance': buildSidebar,
+      '/docs/guide/stablecoin-dex': buildSidebar,
+      '/docs/guide/private-zones': buildSidebar,
+      '/docs/guide/machine-payments': buildSidebar,
+      '/docs/quickstart': integrateSidebar,
+      '/docs/guide/tempo-transaction': integrateSidebar,
+      '/docs/guide/bridge-layerzero': integrateSidebar,
+      '/docs/guide/bridge-bungee': integrateSidebar,
+      '/docs/guide/bridge-relay': integrateSidebar,
+      '/docs/ecosystem': integrateSidebar,
+      '/docs/protocol': specsSidebar,
+      '/docs/tools': developerToolsSidebar,
+      '/docs/hosted-services': developerToolsSidebar,
+      '/docs/developer-tools': developerToolsSidebar,
+      '/docs/cli': developerToolsSidebar,
+      '/docs/protocol/rpc': developerToolsSidebar,
+      '/docs/sdk': developerToolsSidebar,
+      '/docs/wallet': developerToolsSidebar,
+      '/docs/guide/node': nodeSidebar,
+      '/docs/changelog': nodeSidebar,
+    }
+  })(),
   topNav: [
     {
       text: 'Docs',

From 700fde1f687ca52118328435e3144bc534975a6b Mon Sep 17 00:00:00 2001
From: Liam Horne <liam@liamhorne.com>
Date: Thu, 25 Jun 2026 14:53:16 -0400
Subject: [PATCH 2/4] docs: use underline section nav

---
 src/components/DocsSectionNav.tsx | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/src/components/DocsSectionNav.tsx b/src/components/DocsSectionNav.tsx
index e777e6a9..34a520c5 100644
--- a/src/components/DocsSectionNav.tsx
+++ b/src/components/DocsSectionNav.tsx
@@ -106,9 +106,9 @@ export default function DocsSectionNav() {
       <nav
         ref={navRef}
         aria-label="Documentation sections"
-        className="flex h-[var(--tempo-docs-section-nav-height)] items-center overflow-x-auto px-3 [scrollbar-width:none] sm:px-5 [&::-webkit-scrollbar]:hidden"
+        className="flex h-[var(--tempo-docs-section-nav-height)] items-stretch overflow-x-auto px-4 [scrollbar-width:none] sm:px-6 [&::-webkit-scrollbar]:hidden"
       >
-        <ul className="flex min-w-max items-center gap-1">
+        <ul className="flex min-w-max items-stretch gap-8">
           {sectionNavItems.map((item) => {
             const active = isActive(pathname, item)
             return (
@@ -119,10 +119,10 @@ export default function DocsSectionNav() {
                   }}
                   href={item.href}
                   aria-current={active ? 'page' : undefined}
-                  className={`flex h-8 items-center rounded-[4px] px-3 font-sans text-[13px] tracking-[0] transition-colors ${
+                  className={`flex h-full items-center border-b-2 pt-0.5 font-sans text-[14px] tracking-[0] transition-colors ${
                     active
-                      ? 'bg-foreground/[0.06] text-foreground'
-                      : 'text-foreground/50 hover:bg-foreground/[0.035] hover:text-foreground'
+                      ? 'border-foreground font-medium text-foreground'
+                      : 'border-transparent text-foreground/50 hover:text-foreground'
                   }`}
                 >
                   {item.label}

From dc5f715a44d03da29e6a2250cf8a0dd88cd10166 Mon Sep 17 00:00:00 2001
From: Liam Horne <liam@liamhorne.com>
Date: Thu, 25 Jun 2026 14:58:57 -0400
Subject: [PATCH 3/4] docs: polish docs navigation header

---
 src/components/DocsSectionNav.tsx | 174 ++++++++++++++++++++++++------
 1 file changed, 143 insertions(+), 31 deletions(-)

diff --git a/src/components/DocsSectionNav.tsx b/src/components/DocsSectionNav.tsx
index 34a520c5..81abb37e 100644
--- a/src/components/DocsSectionNav.tsx
+++ b/src/components/DocsSectionNav.tsx
@@ -102,36 +102,148 @@ export default function DocsSectionNav() {
   }, [activeLabel])
 
   return (
-    <div className="docs-section-nav border-line border-x border-b bg-surface-shell">
-      <nav
-        ref={navRef}
-        aria-label="Documentation sections"
-        className="flex h-[var(--tempo-docs-section-nav-height)] items-stretch overflow-x-auto px-4 [scrollbar-width:none] sm:px-6 [&::-webkit-scrollbar]:hidden"
-      >
-        <ul className="flex min-w-max items-stretch gap-8">
-          {sectionNavItems.map((item) => {
-            const active = isActive(pathname, item)
-            return (
-              <li key={item.id}>
-                <a
-                  ref={(element) => {
-                    if (active) activeLinkRef.current = element
-                  }}
-                  href={item.href}
-                  aria-current={active ? 'page' : undefined}
-                  className={`flex h-full items-center border-b-2 pt-0.5 font-sans text-[14px] tracking-[0] transition-colors ${
-                    active
-                      ? 'border-foreground font-medium text-foreground'
-                      : 'border-transparent text-foreground/50 hover:text-foreground'
-                  }`}
-                >
-                  {item.label}
-                </a>
-              </li>
-            )
-          })}
-        </ul>
-      </nav>
-    </div>
+    <>
+      <style>{`
+        @media (width >= 1024px) {
+          body:has(.docs-section-nav) nav:has(> a[aria-label='Tempo home']) {
+            display: grid !important;
+            grid-template-columns: minmax(0, 1fr) minmax(300px, 460px) minmax(0, 1fr) !important;
+            align-items: center !important;
+            gap: 12px !important;
+            padding-inline: 20px !important;
+          }
+
+          body:has(.docs-section-nav) nav:has(> a[aria-label='Tempo home']) > ul {
+            display: none !important;
+          }
+
+          body:has(.docs-section-nav) nav:has(> a[aria-label='Tempo home']) > a[aria-label='Tempo home'] {
+            min-width: 0;
+          }
+
+          body:has(.docs-section-nav) nav:has(> a[aria-label='Tempo home']) > a[aria-label='Tempo home']::after {
+            content: 'Docs';
+            margin-left: 12px;
+            padding-left: 12px;
+            border-left: 1px solid var(--line);
+            color: color-mix(in srgb, var(--foreground) 80%, transparent);
+            font-family: var(--font-pilat-book), ui-sans-serif, system-ui, sans-serif;
+            font-size: 15px;
+            letter-spacing: 0;
+          }
+
+          body:has(.docs-section-nav) nav:has(> a[aria-label='Tempo home']) > div {
+            grid-column: 3;
+            justify-self: end;
+            gap: 20px !important;
+          }
+
+          body:has(.docs-section-nav) nav:has(> a[aria-label='Tempo home']) > div > button:first-child {
+            position: absolute;
+            top: 50%;
+            left: 50%;
+            display: flex !important;
+            width: min(460px, calc(100vw - 560px));
+            min-width: 300px;
+            height: 40px;
+            transform: translate(-50%, -50%);
+            justify-content: space-between;
+            border-radius: 6px;
+            background: var(--background);
+            padding-inline: 14px;
+            color: color-mix(in srgb, var(--foreground) 55%, transparent);
+            font-size: 0 !important;
+            box-shadow: 0 1px 1px rgb(0 0 0 / 0.03);
+          }
+
+          body:has(.docs-section-nav) nav:has(> a[aria-label='Tempo home']) > div > button:first-child::after {
+            content: 'Search docs...';
+            order: 1;
+            margin-right: auto;
+            font-size: 14px;
+          }
+
+          body:has(.docs-section-nav) nav:has(> a[aria-label='Tempo home']) > div > button:first-child svg {
+            order: 0;
+          }
+
+          body:has(.docs-section-nav) nav:has(> a[aria-label='Tempo home']) > div > button:first-child kbd {
+            order: 2;
+            background: var(--surface-input);
+            font-size: 11px !important;
+          }
+        }
+
+        @media (width >= 1080px) {
+          .docs-section-nav {
+            right: max(0px, calc((100% - var(--tempo-docs-shell-width)) * 0.5)) !important;
+            left: max(0px, calc((100% - var(--tempo-docs-shell-width)) * 0.5)) !important;
+          }
+
+          [data-layout][data-v-sidebar] > [data-v-gutter-left] {
+            padding-top: var(--vocs-spacing-topNav) !important;
+          }
+        }
+
+        .docs-header-github-link {
+          display: none;
+        }
+
+        @media (width >= 1280px) {
+          .docs-header-github-link {
+            position: fixed;
+            top: 0;
+            right: 150px;
+            z-index: 80;
+            display: flex;
+            height: var(--tempo-docs-primary-nav-height);
+            align-items: center;
+            color: color-mix(in srgb, var(--foreground) 65%, transparent);
+            font-family: var(--font-pilat-book), ui-sans-serif, system-ui, sans-serif;
+            font-size: 14px;
+            letter-spacing: 0;
+            transition: color 150ms ease;
+          }
+
+          .docs-header-github-link:hover {
+            color: var(--foreground);
+          }
+        }
+      `}</style>
+      <a className="docs-header-github-link" href="https://github.com/tempoxyz">
+        GitHub
+      </a>
+      <div className="docs-section-nav border-line border-x border-b bg-surface-shell">
+        <nav
+          ref={navRef}
+          aria-label="Documentation sections"
+          className="flex h-[var(--tempo-docs-section-nav-height)] items-stretch overflow-x-auto px-4 [scrollbar-width:none] sm:px-6 [&::-webkit-scrollbar]:hidden"
+        >
+          <ul className="flex min-w-max items-stretch gap-8">
+            {sectionNavItems.map((item) => {
+              const active = isActive(pathname, item)
+              return (
+                <li key={item.id}>
+                  <a
+                    ref={(element) => {
+                      if (active) activeLinkRef.current = element
+                    }}
+                    href={item.href}
+                    aria-current={active ? 'page' : undefined}
+                    className={`flex h-full items-center border-b-2 pt-0.5 font-sans text-[14px] tracking-[0] transition-colors ${
+                      active
+                        ? 'border-foreground font-medium text-foreground'
+                        : 'border-transparent text-foreground/50 hover:text-foreground'
+                    }`}
+                  >
+                    {item.label}
+                  </a>
+                </li>
+              )
+            })}
+          </ul>
+        </nav>
+      </div>
+    </>
   )
 }

From 312d181c5bebdbdd079baa24bb8c89bdba00b945 Mon Sep 17 00:00:00 2001
From: Liam Horne <liam@liamhorne.com>
Date: Thu, 25 Jun 2026 16:30:30 -0400
Subject: [PATCH 4/4] docs: remove overlapping docs header link

---
 src/components/DocsSectionNav.tsx | 28 ----------------------------
 1 file changed, 28 deletions(-)

diff --git a/src/components/DocsSectionNav.tsx b/src/components/DocsSectionNav.tsx
index 81abb37e..e6bea89b 100644
--- a/src/components/DocsSectionNav.tsx
+++ b/src/components/DocsSectionNav.tsx
@@ -184,35 +184,7 @@ export default function DocsSectionNav() {
             padding-top: var(--vocs-spacing-topNav) !important;
           }
         }
-
-        .docs-header-github-link {
-          display: none;
-        }
-
-        @media (width >= 1280px) {
-          .docs-header-github-link {
-            position: fixed;
-            top: 0;
-            right: 150px;
-            z-index: 80;
-            display: flex;
-            height: var(--tempo-docs-primary-nav-height);
-            align-items: center;
-            color: color-mix(in srgb, var(--foreground) 65%, transparent);
-            font-family: var(--font-pilat-book), ui-sans-serif, system-ui, sans-serif;
-            font-size: 14px;
-            letter-spacing: 0;
-            transition: color 150ms ease;
-          }
-
-          .docs-header-github-link:hover {
-            color: var(--foreground);
-          }
-        }
       `}</style>
-      <a className="docs-header-github-link" href="https://github.com/tempoxyz">
-        GitHub
-      </a>
       <div className="docs-section-nav border-line border-x border-b bg-surface-shell">
         <nav
           ref={navRef}