From 414c26a8895fae7cdde348240b0e25ab3614439b Mon Sep 17 00:00:00 2001
From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com>
Date: Fri, 8 May 2026 11:39:17 -1000
Subject: [PATCH 1/2] docs: add section eyebrow text above page H1

Show the current topic label (e.g. TERMINAL, AGENTS, ENTERPRISE)
as a small uppercase eyebrow above the H1 on every page. Helps
orient readers who land directly from search without sidebar context.

Derived from starlightSidebarTopics middleware (same data as the
header topic nav). Styled with accent blue, xs font, 600 weight,
and 0.08em letter-spacing matching the sidebar tier-1 treatment.

Co-Authored-By: Oz <oz-agent@warp.dev>
---
 src/components/CustomPageTitle.astro | 21 ++++++++++++++++++++-
 1 file changed, 20 insertions(+), 1 deletion(-)

diff --git a/src/components/CustomPageTitle.astro b/src/components/CustomPageTitle.astro
index fc93fe15..05ea2d76 100644
--- a/src/components/CustomPageTitle.astro
+++ b/src/components/CustomPageTitle.astro
@@ -13,8 +13,17 @@ const title = Astro.locals.starlightRoute.entry.data.title;
 // an empty paragraph.
 const description = Astro.locals.starlightRoute.entry.data.description;
 const body = Astro.locals.starlightRoute.entry.body ?? '';
+
+// Eyebrow: the current topic label (e.g. "Terminal", "Agents", "Enterprise")
+// shown as a small uppercase label above the H1 to orient readers who land
+// directly on a page from search. Uses the same `starlightSidebarTopics`
+// middleware data as WarpTopicNav.astro.
+const topics = Astro.locals.starlightSidebarTopics?.topics;
+const currentTopic = topics?.find((t: { isCurrent: boolean }) => t.isCurrent);
+const eyebrow = currentTopic?.label;
 ---
 
+{eyebrow && <p class="page-eyebrow">{eyebrow}</p>}
 <div class="page-title-row">
   <h1 id="_top">{title}</h1>
   <CopyPageButton body={body} title={title} />
@@ -29,10 +38,20 @@ const body = Astro.locals.starlightRoute.entry.body ?? '';
     gap: 1rem;
   }
 
+  .page-eyebrow {
+    margin-top: 1rem;
+    margin-bottom: 0.25rem;
+    font-size: var(--sl-text-xs);
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+    color: var(--sl-color-text-accent);
+  }
+
   .page-title-row h1 {
     flex: 1;
     min-width: 0;
-    margin-top: 1rem;
+    margin-top: 0;
     font-size: var(--sl-text-h1);
     line-height: var(--sl-line-height-headings);
     font-weight: 700;

From a66992478578dcc40e067a7c8d655586f4208958 Mon Sep 17 00:00:00 2001
From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com>
Date: Fri, 8 May 2026 12:16:08 -1000
Subject: [PATCH 2/2] docs: upgrade eyebrow to 2-level breadcrumb (topic +
 parent group)

Walk the sidebar tree to find the immediate parent group of the
current page and show it as a breadcrumb: 'AGENTS > THIRD-PARTY
CLI AGENTS' instead of just 'AGENTS'. Falls back to topic-only
when the page is at the top level of its topic. Truncated to 2
levels max to keep the eyebrow short.

Co-Authored-By: Oz <oz-agent@warp.dev>
---
 src/components/CustomPageTitle.astro | 32 +++++++++++++++++++++++-----
 1 file changed, 27 insertions(+), 5 deletions(-)

diff --git a/src/components/CustomPageTitle.astro b/src/components/CustomPageTitle.astro
index 05ea2d76..d6902c10 100644
--- a/src/components/CustomPageTitle.astro
+++ b/src/components/CustomPageTitle.astro
@@ -14,13 +14,35 @@ const title = Astro.locals.starlightRoute.entry.data.title;
 const description = Astro.locals.starlightRoute.entry.data.description;
 const body = Astro.locals.starlightRoute.entry.body ?? '';
 
-// Eyebrow: the current topic label (e.g. "Terminal", "Agents", "Enterprise")
-// shown as a small uppercase label above the H1 to orient readers who land
-// directly on a page from search. Uses the same `starlightSidebarTopics`
-// middleware data as WarpTopicNav.astro.
+// Eyebrow: a 2-level breadcrumb (e.g. "Agents > Third-Party CLI Agents")
+// shown above the H1 to orient readers who land directly from search.
+// Level 1 = the current sidebar topic (from starlightSidebarTopics).
+// Level 2 = the immediate parent group of the current page in the sidebar
+// tree (from starlightRoute.sidebar). Truncated to 2 levels max.
 const topics = Astro.locals.starlightSidebarTopics?.topics;
 const currentTopic = topics?.find((t: { isCurrent: boolean }) => t.isCurrent);
-const eyebrow = currentTopic?.label;
+const topicLabel = currentTopic?.label;
+
+// Walk the sidebar tree to find the parent group of the current page.
+type SidebarEntry = { type: string; label: string; isCurrent?: boolean; entries?: SidebarEntry[] };
+function findParentGroup(entries: SidebarEntry[], parentLabel?: string): string | undefined {
+  for (const entry of entries) {
+    if (entry.type === 'link' && entry.isCurrent) return parentLabel;
+    if (entry.type === 'group' && entry.entries) {
+      const found = findParentGroup(entry.entries, entry.label);
+      if (found) return found;
+    }
+  }
+  return undefined;
+}
+const sidebar = Astro.locals.starlightRoute?.sidebar as SidebarEntry[] | undefined;
+const parentGroup = sidebar ? findParentGroup(sidebar) : undefined;
+
+// Build the eyebrow: "Topic > Parent Group" or just "Topic" if the page
+// is at the top level of its topic (no parent group, or parent matches topic).
+const eyebrow = topicLabel && parentGroup && parentGroup !== topicLabel
+  ? `${topicLabel} > ${parentGroup}`
+  : topicLabel;
 ---
 
 {eyebrow && <p class="page-eyebrow">{eyebrow}</p>}