diff --git a/docs/getting-started/overview.md b/docs/getting-started/overview.md
index ee81750..cf8d2ef 100644
--- a/docs/getting-started/overview.md
+++ b/docs/getting-started/overview.md
@@ -40,8 +40,9 @@ behind that connection — the thing the gateway actually talks to.
   headers and bodies, the resolved identity, the response status and
   size, and the duration.
 - **Portal**: React 19 SPA embedded in the binary; Dashboard,
-  Endpoints with Try-It, Audit, API Keys, Config, Discovery (Redoc/Swagger
-  UI over `/openapi.json`).
+  Endpoints with Try-It, Audit, API Keys, Config, Discovery (native
+  OpenAPI 3.1 reference rendered from `/openapi.json`, with `/docs`
+  Redoc available as a sibling).
 - **OpenAPI document** at `/openapi.{json,yaml}`, generated in-tree
   from the registered endpoint metadata so it can't drift from the
   served routes.
diff --git a/docs/images/portal/about-dark.png b/docs/images/portal/about-dark.png
index dd22518..3c5039c 100644
Binary files a/docs/images/portal/about-dark.png and b/docs/images/portal/about-dark.png differ
diff --git a/docs/images/portal/about-light.png b/docs/images/portal/about-light.png
index ddc3c16..4f83fc5 100644
Binary files a/docs/images/portal/about-light.png and b/docs/images/portal/about-light.png differ
diff --git a/docs/images/portal/audit-dark.png b/docs/images/portal/audit-dark.png
index 2909e59..93d3b99 100644
Binary files a/docs/images/portal/audit-dark.png and b/docs/images/portal/audit-dark.png differ
diff --git a/docs/images/portal/audit-detail-dark.png b/docs/images/portal/audit-detail-dark.png
index 8ad5368..38c5a3c 100644
Binary files a/docs/images/portal/audit-detail-dark.png and b/docs/images/portal/audit-detail-dark.png differ
diff --git a/docs/images/portal/audit-detail-light.png b/docs/images/portal/audit-detail-light.png
index 1fe4892..1cb62d6 100644
Binary files a/docs/images/portal/audit-detail-light.png and b/docs/images/portal/audit-detail-light.png differ
diff --git a/docs/images/portal/audit-light.png b/docs/images/portal/audit-light.png
index 6974f1a..249321b 100644
Binary files a/docs/images/portal/audit-light.png and b/docs/images/portal/audit-light.png differ
diff --git a/docs/images/portal/config-dark.png b/docs/images/portal/config-dark.png
index 7c9a226..e39c09f 100644
Binary files a/docs/images/portal/config-dark.png and b/docs/images/portal/config-dark.png differ
diff --git a/docs/images/portal/config-light.png b/docs/images/portal/config-light.png
index 565c8de..216d61a 100644
Binary files a/docs/images/portal/config-light.png and b/docs/images/portal/config-light.png differ
diff --git a/docs/images/portal/dashboard-dark.png b/docs/images/portal/dashboard-dark.png
index 8f049f6..26e3fb7 100644
Binary files a/docs/images/portal/dashboard-dark.png and b/docs/images/portal/dashboard-dark.png differ
diff --git a/docs/images/portal/dashboard-light.png b/docs/images/portal/dashboard-light.png
index bfa5f56..5e01ebf 100644
Binary files a/docs/images/portal/dashboard-light.png and b/docs/images/portal/dashboard-light.png differ
diff --git a/docs/images/portal/discovery-dark.png b/docs/images/portal/discovery-dark.png
new file mode 100644
index 0000000..58a8fa9
Binary files /dev/null and b/docs/images/portal/discovery-dark.png differ
diff --git a/docs/images/portal/discovery-light.png b/docs/images/portal/discovery-light.png
new file mode 100644
index 0000000..02503f2
Binary files /dev/null and b/docs/images/portal/discovery-light.png differ
diff --git a/docs/images/portal/endpoints-dark.png b/docs/images/portal/endpoints-dark.png
index 4a05795..e416f14 100644
Binary files a/docs/images/portal/endpoints-dark.png and b/docs/images/portal/endpoints-dark.png differ
diff --git a/docs/images/portal/endpoints-detail-dark.png b/docs/images/portal/endpoints-detail-dark.png
index dc4e570..1560c7c 100644
Binary files a/docs/images/portal/endpoints-detail-dark.png and b/docs/images/portal/endpoints-detail-dark.png differ
diff --git a/docs/images/portal/endpoints-detail-light.png b/docs/images/portal/endpoints-detail-light.png
index ca71010..bc4b944 100644
Binary files a/docs/images/portal/endpoints-detail-light.png and b/docs/images/portal/endpoints-detail-light.png differ
diff --git a/docs/images/portal/endpoints-light.png b/docs/images/portal/endpoints-light.png
index 6c70e10..569dd54 100644
Binary files a/docs/images/portal/endpoints-light.png and b/docs/images/portal/endpoints-light.png differ
diff --git a/docs/images/portal/keys-dark.png b/docs/images/portal/keys-dark.png
index 8f27093..664e64b 100644
Binary files a/docs/images/portal/keys-dark.png and b/docs/images/portal/keys-dark.png differ
diff --git a/docs/images/portal/keys-light.png b/docs/images/portal/keys-light.png
index 5715af4..5c0c612 100644
Binary files a/docs/images/portal/keys-light.png and b/docs/images/portal/keys-light.png differ
diff --git a/docs/operations/portal.md b/docs/operations/portal.md
index e25bbfc..0addf96 100644
--- a/docs/operations/portal.md
+++ b/docs/operations/portal.md
@@ -22,7 +22,7 @@ operator session cookie established via OIDC PKCE.
 | **Audit** | Filterable, paginated event view; click a row for the full request/response drawer with redaction overlays. |
 | **API Keys** | Create / revoke Postgres-backed bcrypt keys. Plaintext shown once. |
 | **Config** | Read-only YAML of the running server, with secrets masked. |
-| **Discovery** | Redoc/Swagger UI iframe over `/openapi.json`; click-to-copy connection-registration YAML for the Plexara admin API. |
+| **Discovery** | Native OpenAPI 3.1 reference rendered from `/openapi.json` (groups, operations, parameters, schemas, response samples; full dark/light parity with the portal). Links out to `/docs` (Redoc) for the canonical view. |
 | **About** | Build info + "test against Plexara" cheat sheet. |
 
 ## Authentication
@@ -53,6 +53,23 @@ and a curl hint for invoking the route directly.
 ![Endpoints catalog with the right-pane detail card for a selected route, light theme](../images/portal/endpoints-detail-light.png#only-light)
 ![Endpoints catalog with the right-pane detail card for a selected route, dark theme](../images/portal/endpoints-detail-dark.png#only-dark)
 
+## Discovery
+
+A native OpenAPI 3.1 reference rendered directly from
+[/openapi.json](../reference/http-api.md#discovery), with full
+light / dark parity against the portal's design tokens. Operations are
+grouped by tag in a left rail; each card expands to show parameters,
+request body schema, responses, and a minimal example synthesized from
+the schema. The page-level filter searches path, summary, and
+operationId across every operation.
+
+The canonical Redoc view at `/docs` is still served by the binary and
+is linked from the page header (top right) for operators who prefer
+it.
+
+![Discovery page with the tag rail, operation list, and an expanded operation card, light theme](../images/portal/discovery-light.png#only-light)
+![Discovery page with the tag rail, operation list, and an expanded operation card, dark theme](../images/portal/discovery-dark.png#only-dark)
+
 ## Audit log
 
 The Audit page is the filterable, paginated event view. Filters cover
diff --git a/docs/overrides/home.html b/docs/overrides/home.html
index 87dcbef..9ed23a7 100644
--- a/docs/overrides/home.html
+++ b/docs/overrides/home.html
@@ -84,7 +84,8 @@ <h2>Inspect every request from the browser</h2>
           ["audit",            "Audit log",       "Every request, filterable by method, path, and success / error. Auto-refreshing on a 5-second interval; click a row to inspect the full request and response."],
           ["audit-detail",     "Inspection panel", "Side-pane detail card with timestamp, duration, request id, identity, remote address, byte counts, and the full headers / query / body trees for both sides of the call."],
           ["endpoints",        "Endpoints",       "Catalog of every registered route, grouped by behavior — identity, deterministic data, echo, controlled failure modes."],
-          ["endpoints-detail", "Endpoint detail", "Method, path, group, auth requirement, and an inline curl hint per route. Try-It panel arrives with the OpenAPI generator in."],
+          ["endpoints-detail", "Endpoint detail", "Method, path, group, auth requirement, and an inline curl hint per route, plus a Try-It panel that dispatches a real call through the portal API."],
+          ["discovery",        "Discovery",       "Native OpenAPI 3.1 reference rendered from /openapi.json — groups, operations, parameters, schemas, examples — with full light / dark parity against the portal's design tokens."],
           ["keys",             "API keys",        "Create or revoke Postgres-backed bcrypt keys. Plaintext is shown once, then never again."],
           ["config",           "Config",          "Read-only view of the running server config, with secrets masked. Useful for sanity-checking what's actually loaded."],
           ["about",            "About",           "Build info plus the same well-known metadata an MCP / API client sees: api endpoint, OIDC issuer, audience."]
diff --git a/docs/reference/http-api.md b/docs/reference/http-api.md
index 18be160..c6c97e4 100644
--- a/docs/reference/http-api.md
+++ b/docs/reference/http-api.md
@@ -39,7 +39,10 @@ GET /docs
 ```
 
 Renders a Redoc / Swagger UI view of `/openapi.json` for human
-inspection. The portal's Discovery page iframes this.
+inspection. The portal's Discovery page renders its own native
+reference against the same `/openapi.json` document (for full
+light/dark parity with the portal); `/docs` is still served as the
+canonical Redoc view and is linked from the portal header.
 
 ## Well-known metadata
 
diff --git a/scripts/screenshots/screenshots.mjs b/scripts/screenshots/screenshots.mjs
index f7f26fa..bfc2fbc 100644
--- a/scripts/screenshots/screenshots.mjs
+++ b/scripts/screenshots/screenshots.mjs
@@ -68,6 +68,21 @@ const PAGES = [
       await page.waitForTimeout(400);
     } },
 
+  // discovery: native OpenAPI 3.1 reference rendered from /openapi.json.
+  // Capture an expanded operation so the screenshot communicates what the
+  // page actually does (parameter tables, response schema, examples) and
+  // not just the closed-card list.
+  { slug: "discovery",
+    path: "/portal/discovery",
+    requiresAuth: true,
+    prep: async (page) => {
+      await page.waitForSelector('section button code', { timeout: 5000 });
+      // Click the first operation card so its parameter/response/schema
+      // detail expands.
+      await page.locator('section button').first().click();
+      await page.waitForTimeout(400);
+    } },
+
   // audit-detail: click the first row so the right-pane EventDetail card
   // (timestamp, duration, request_id, auth, user, remote, bytes, plus
   // request/response headers / query / body trees) is rendered.
diff --git a/ui/src/App.tsx b/ui/src/App.tsx
index 42cadc4..376e38d 100644
--- a/ui/src/App.tsx
+++ b/ui/src/App.tsx
@@ -43,8 +43,15 @@ export default function App() {
   }
 
   return (
-    <div className="grid grid-cols-[14rem_1fr] min-h-full bg-background text-foreground">
-      <aside className="border-r border-border bg-card p-4 flex flex-col">
+    // h-full (not min-h-full) so <main> is height-constrained: with
+    // min-h-full the outer grid grows with its content and the
+    // document does the scrolling, which means main's overflow-auto
+    // never fires and position: sticky inside any page has no scroll
+    // context to anchor to. h-full pins the chrome to the viewport so
+    // main owns the scroll, sticky works, and pages get the
+    // h-[calc(100vh-...)] sizing they already assume.
+    <div className="grid grid-cols-[14rem_1fr] h-full bg-background text-foreground">
+      <aside className="border-r border-border bg-card p-4 flex flex-col overflow-y-auto">
         <SidebarBrand />
         <nav className="flex flex-col gap-1">
           {NAV.map((it) => (
diff --git a/ui/src/pages/Audit.tsx b/ui/src/pages/Audit.tsx
index ea485bf..1f1daa4 100644
--- a/ui/src/pages/Audit.tsx
+++ b/ui/src/pages/Audit.tsx
@@ -22,7 +22,7 @@ export default function Audit() {
   return (
     <div className="space-y-4 max-w-6xl">
       <div className="flex items-baseline justify-between">
-        <h1 className="text-2xl font-semibold">Audit</h1>
+        <h1 className="text-2xl font-semibold tracking-tight">Audit</h1>
         <div className="text-xs text-muted-foreground">
           {q.data ? `${q.data.events.length} of ${q.data.total}` : "…"}
         </div>
@@ -42,11 +42,37 @@ export default function Audit() {
         </select>
       </div>
 
-      <div className="grid grid-cols-[2fr_3fr] gap-4">
+      {/*
+        Fixed-width left column + flexible right column on lg+; stacked on
+        narrow viewports. `minmax(0,1fr)` on the right cell is required:
+        without the 0 floor, grid children inherit `min-width: auto` and
+        the right column fights the left when JSON values are long.
+        `table-fixed` + an explicit `<colgroup>` pin the inner table so
+        the cells honor the declared widths.
+      */}
+      <div className="grid grid-cols-1 lg:grid-cols-[460px_minmax(0,1fr)] gap-4">
         <div className="bg-card text-card-foreground border border-border rounded-lg overflow-hidden">
-          <table className="w-full text-sm">
-            <thead className="bg-muted/50 text-muted-foreground">
-              <tr>
+          <table className="w-full text-sm table-fixed">
+            {/*
+              Column widths are sized empirically (measured via getBoundingClientRect):
+              - Time: 76px fits "23:59:59" in mono text-xs with breathing room.
+                We deliberately use 24-hour format so a 12-hour "PM" suffix
+                can't push the column wider than the colgroup declares.
+              - Method: 88px fits the widest pill — DELETE (~78px rendered)
+                and OPTIONS (~80px rendered) — including px-1.5 padding,
+                tracking-wider, and ring. 72px was too narrow and DELETE
+                pills overflowed the Path column by ~7px.
+              - Status: 64px fits a 3-digit pill ("500") right-aligned.
+              - Path takes the remainder and truncates with a title tooltip.
+            */}
+            <colgroup>
+              <col className="w-[76px]" />
+              <col className="w-[88px]" />
+              <col />
+              <col className="w-[64px]" />
+            </colgroup>
+            <thead className="bg-muted/40 text-muted-foreground border-b border-border">
+              <tr className="text-xs uppercase tracking-wider">
                 <th className="text-left px-3 py-2 font-medium">Time</th>
                 <th className="text-left px-3 py-2 font-medium">Method</th>
                 <th className="text-left px-3 py-2 font-medium">Path</th>
@@ -58,13 +84,17 @@ export default function Audit() {
                 <tr
                   key={e.id}
                   onClick={() => setSelected(e.id)}
-                  className={`border-t border-border cursor-pointer hover:bg-muted/40 ${selected === e.id ? "bg-muted/60" : ""}`}
+                  className={`border-t border-border/60 cursor-pointer transition-colors hover:bg-muted/40 ${selected === e.id ? "bg-muted/60" : ""}`}
                 >
-                  <td className="px-3 py-1.5 text-muted-foreground mono text-xs">{new Date(e.timestamp).toLocaleTimeString()}</td>
-                  <td className="px-3 py-1.5 mono">{e.method}</td>
-                  <td className="px-3 py-1.5 mono truncate max-w-xs">{e.path}</td>
-                  <td className="px-3 py-1.5 text-right mono">
-                    <span className={statusColor(e.status)}>{e.status}</span>
+                  <td className="px-3 py-2 text-muted-foreground mono text-xs whitespace-nowrap">
+                    {formatTime(e.timestamp)}
+                  </td>
+                  <td className="px-3 py-2 whitespace-nowrap">
+                    <MethodPill method={e.method} />
+                  </td>
+                  <td className="px-3 py-2 mono text-xs truncate" title={e.path}>{e.path}</td>
+                  <td className="px-3 py-2 text-right whitespace-nowrap">
+                    <StatusPill status={e.status} />
                   </td>
                 </tr>
               ))}
@@ -74,7 +104,20 @@ export default function Audit() {
             </tbody>
           </table>
         </div>
-        <div>
+        {/*
+          Sticky detail panel. Click an event at the bottom of a long
+          list and you should NOT have to scroll back to the top to see
+          the detail. `lg:sticky lg:top-6 lg:self-start` pins the panel
+          to the top of the viewport (top-6 = 1.5rem, matching the
+          parent <main className="p-6"> padding). `lg:self-start` is
+          required: without it the right grid track stretches to the
+          left track's height and `sticky` has nothing to anchor to.
+          `lg:max-h-[calc(100vh-3rem)] lg:overflow-y-auto` lets the
+          detail itself scroll when its JSON payloads exceed the
+          viewport — so long bodies don't push the sticky panel off
+          screen.
+        */}
+        <div className="min-w-0 lg:sticky lg:top-6 lg:self-start lg:max-h-[calc(100vh-3rem)] lg:overflow-y-auto">
           {selected ? <EventDetail id={selected} /> : <div className="text-muted-foreground text-sm">Click a row to inspect the request.</div>}
         </div>
       </div>
@@ -88,23 +131,26 @@ function EventDetail({ id }: { id: string }) {
   if (q.error || !q.data) return <div className="text-destructive text-sm">Failed to load event.</div>;
   const e = q.data;
   return (
-    <div className="bg-card text-card-foreground border border-border rounded-lg p-4 space-y-3 text-sm">
-      <div className="flex items-baseline justify-between">
-        <div className="font-semibold mono">{e.method} {e.path}</div>
-        <span className={`mono ${statusColor(e.status)}`}>{e.status}</span>
+    <div className="bg-card text-card-foreground border border-border rounded-lg p-4 space-y-4 text-sm min-w-0">
+      <div className="flex items-center justify-between gap-3 min-w-0">
+        <div className="flex items-center gap-2 min-w-0">
+          <MethodPill method={e.method} />
+          <code className="mono text-sm font-medium truncate min-w-0" title={e.path}>{e.path}</code>
+        </div>
+        <StatusPill status={e.status} />
       </div>
-      <div className="grid grid-cols-2 gap-2 text-xs">
+      <div className="grid grid-cols-2 gap-x-4 gap-y-2 text-xs min-w-0">
         <Field label="Timestamp" value={new Date(e.timestamp).toLocaleString()} />
         <Field label="Duration" value={`${e.duration_ms}ms`} />
-        <Field label="Request ID" value={e.request_id || "-"} />
+        <Field label="Request ID" value={e.request_id || "-"} mono />
         <Field label="Auth" value={e.auth_type || "-"} />
         <Field label="User" value={e.user_email || e.user_subject || "-"} />
-        <Field label="Remote" value={e.remote_addr || "-"} />
-        <Field label="Bytes in" value={String(e.bytes_in)} />
-        <Field label="Bytes out" value={String(e.bytes_out)} />
+        <Field label="Remote" value={e.remote_addr || "-"} mono />
+        <Field label="Bytes in" value={String(e.bytes_in)} mono />
+        <Field label="Bytes out" value={String(e.bytes_out)} mono />
       </div>
       {e.payload && (
-        <div className="space-y-2">
+        <div className="space-y-3 pt-2 border-t border-border">
           {e.payload.request_headers && <JsonView label="request_headers" value={e.payload.request_headers} />}
           {e.payload.request_query && <JsonView label="request_query" value={e.payload.request_query} />}
           {e.payload.request_body && <JsonView label="request_body" value={tryParseJSON(e.payload.request_body)} />}
@@ -116,6 +162,17 @@ function EventDetail({ id }: { id: string }) {
   );
 }
 
+// formatTime renders an ISO timestamp as locale-independent 24-hour HH:MM:SS.
+// Built explicitly (not via toLocaleTimeString) so a user with an en-US
+// locale doesn't get "12:34:56 PM" that overflows the 76px Time column.
+function formatTime(iso: string): string {
+  const d = new Date(iso);
+  const hh = String(d.getHours()).padStart(2, "0");
+  const mm = String(d.getMinutes()).padStart(2, "0");
+  const ss = String(d.getSeconds()).padStart(2, "0");
+  return `${hh}:${mm}:${ss}`;
+}
+
 function tryParseJSON(s: string): unknown {
   try {
     return JSON.parse(s);
@@ -124,11 +181,11 @@ function tryParseJSON(s: string): unknown {
   }
 }
 
-function Field({ label, value }: { label: string; value: string }) {
+function Field({ label, value, mono = false }: { label: string; value: string; mono?: boolean }) {
   return (
-    <div>
-      <div className="text-muted-foreground">{label}</div>
-      <div className="mono truncate" title={value}>{value}</div>
+    <div className="min-w-0">
+      <div className="text-muted-foreground text-[10px] uppercase tracking-wider mb-0.5">{label}</div>
+      <div className={`truncate ${mono ? "mono" : ""}`} title={value}>{value}</div>
     </div>
   );
 }
@@ -145,9 +202,38 @@ function FilterInput({ placeholder, value, onChange }: { placeholder: string; va
   );
 }
 
-function statusColor(status: number): string {
-  if (status >= 500) return "text-destructive";
-  if (status >= 400) return "text-destructive/80";
-  if (status >= 300) return "text-muted-foreground";
-  return "text-success";
+// Method/status pills are pulled into local helpers (no Discovery import)
+// to avoid a cross-page coupling. The HSL palette is the same one
+// Discovery uses, replicated here to keep both pages visually consistent;
+// if a third surface ever needs the colors, factor into ui/src/lib/.
+const METHOD_PILL: Record<string, string> = {
+  GET:     "bg-emerald-500/15 text-emerald-700 dark:text-emerald-300 ring-1 ring-emerald-500/30",
+  POST:    "bg-sky-500/15     text-sky-700     dark:text-sky-300     ring-1 ring-sky-500/30",
+  PUT:     "bg-amber-500/15   text-amber-700   dark:text-amber-300   ring-1 ring-amber-500/30",
+  PATCH:   "bg-violet-500/15  text-violet-700  dark:text-violet-300  ring-1 ring-violet-500/30",
+  DELETE:  "bg-rose-500/15    text-rose-700    dark:text-rose-300    ring-1 ring-rose-500/30",
+  OPTIONS: "bg-slate-500/15   text-slate-700   dark:text-slate-300   ring-1 ring-slate-500/30",
+  HEAD:    "bg-slate-500/15   text-slate-700   dark:text-slate-300   ring-1 ring-slate-500/30",
+};
+
+function MethodPill({ method }: { method: string }) {
+  const cls = METHOD_PILL[method.toUpperCase()] ?? METHOD_PILL.OPTIONS;
+  return (
+    <span className={`mono text-[10px] font-semibold uppercase tracking-wider px-1.5 py-0.5 rounded ${cls}`}>
+      {method}
+    </span>
+  );
+}
+
+function StatusPill({ status }: { status: number }) {
+  let cls = "bg-slate-500/15 text-slate-700 dark:text-slate-300 ring-1 ring-slate-500/30";
+  if (status >= 500)      cls = "bg-rose-500/15    text-rose-700    dark:text-rose-300    ring-1 ring-rose-500/30";
+  else if (status >= 400) cls = "bg-amber-500/15   text-amber-700   dark:text-amber-300   ring-1 ring-amber-500/30";
+  else if (status >= 300) cls = "bg-sky-500/15     text-sky-700     dark:text-sky-300     ring-1 ring-sky-500/30";
+  else if (status >= 200) cls = "bg-emerald-500/15 text-emerald-700 dark:text-emerald-300 ring-1 ring-emerald-500/30";
+  return (
+    <span className={`mono text-[10px] font-semibold tabular-nums px-1.5 py-0.5 rounded ${cls}`}>
+      {status}
+    </span>
+  );
 }
diff --git a/ui/src/pages/Discovery.tsx b/ui/src/pages/Discovery.tsx
index 978c311..3a7be42 100644
--- a/ui/src/pages/Discovery.tsx
+++ b/ui/src/pages/Discovery.tsx
@@ -1,93 +1,710 @@
-// Discovery page: embeds the Redoc viewer served at /docs (rendered
-// against /openapi.json by the oapi-generator backend). The iframe
-// loads the same /docs URL an operator would visit directly; the
-// portal just frames it alongside the rest of the sidebar nav.
+// Discovery page: native OpenAPI 3.1 reference view.
+//
+// We deliberately do NOT iframe /docs (Redoc). Reasons, in order of
+// importance:
+//   1. Design-system parity. The portal's CSS variables (light/dark)
+//      cannot reach into a same-origin iframe to restyle the embedded
+//      Redoc bundle; the operator sees a light Redoc against a dark
+//      shell. (Redoc itself supports a theme config, but plumbing it
+//      through a build-time-rendered docs HTML is a heavier lift than
+//      rendering the OpenAPI document directly here.)
+//   2. In-portal search/filter — the iframe can't participate in the
+//      portal's tag rail or query bar.
+//   3. Clipboard copy works without sandbox gymnastics.
+//
+// /docs is still linked from the page header for operators who want the
+// canonical Redoc view; the link opens in a new tab.
 
-import { useEffect, useState } from "react";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { Search, ChevronDown, ChevronRight, Lock, Copy, Check, ExternalLink } from "lucide-react";
+
+type OpenAPIDoc = {
+  openapi?: string;
+  info?: { title?: string; version?: string; description?: string };
+  tags?: Array<{ name: string; description?: string }>;
+  paths?: Record<string, Record<string, Operation>>;
+  components?: { schemas?: Record<string, Schema>; securitySchemes?: Record<string, unknown> };
+};
+
+type Operation = {
+  tags?: string[];
+  summary?: string;
+  description?: string;
+  operationId?: string;
+  parameters?: Parameter[];
+  requestBody?: { description?: string; required?: boolean; content?: Record<string, MediaType> };
+  responses?: Record<string, ResponseObject>;
+  security?: Array<Record<string, string[]>>;
+  deprecated?: boolean;
+};
+
+type Parameter = { name: string; in: "query" | "header" | "path" | "cookie"; required?: boolean; description?: string; schema?: Schema };
+type MediaType = { schema?: Schema; example?: unknown; examples?: Record<string, { value?: unknown; summary?: string }> };
+type ResponseObject = { description?: string; content?: Record<string, MediaType>; headers?: Record<string, unknown> };
+type Schema = {
+  type?: string | string[];
+  format?: string;
+  description?: string;
+  enum?: unknown[];
+  default?: unknown;
+  example?: unknown;
+  examples?: unknown[];
+  items?: Schema;
+  properties?: Record<string, Schema>;
+  required?: string[];
+  additionalProperties?: boolean | Schema;
+  $ref?: string;
+  oneOf?: Schema[];
+  anyOf?: Schema[];
+  allOf?: Schema[];
+  nullable?: boolean;
+  minimum?: number;
+  maximum?: number;
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  // OpenAPI 3.1 / JSON Schema allows arbitrary extension keywords.
+  [key: string]: unknown;
+};
+
+const METHODS = ["get", "post", "put", "patch", "delete", "options", "head"] as const;
+type Method = (typeof METHODS)[number];
+
+// Method palette is fixed in HSL so the badges stay legible against both
+// the light card background and the dark slate. Each color stays inside
+// the WCAG AA contrast band for foreground/background pairs we ship.
+const METHOD_COLOR: Record<Method, string> = {
+  get:     "bg-emerald-500/15 text-emerald-700 dark:text-emerald-300 ring-1 ring-emerald-500/30",
+  post:    "bg-sky-500/15     text-sky-700     dark:text-sky-300     ring-1 ring-sky-500/30",
+  put:     "bg-amber-500/15   text-amber-700   dark:text-amber-300   ring-1 ring-amber-500/30",
+  patch:   "bg-violet-500/15  text-violet-700  dark:text-violet-300  ring-1 ring-violet-500/30",
+  delete:  "bg-rose-500/15    text-rose-700    dark:text-rose-300    ring-1 ring-rose-500/30",
+  options: "bg-slate-500/15   text-slate-700   dark:text-slate-300   ring-1 ring-slate-500/30",
+  head:    "bg-slate-500/15   text-slate-700   dark:text-slate-300   ring-1 ring-slate-500/30",
+};
 
 export default function Discovery() {
-  const [reachable, setReachable] = useState<"checking" | "ok" | "missing">("checking");
+  const [doc, setDoc] = useState<OpenAPIDoc | null>(null);
+  const [status, setStatus] = useState<"loading" | "ok" | "missing" | "error">("loading");
+  const [query, setQuery] = useState("");
+  const [activeTag, setActiveTag] = useState<string | "all">("all");
 
   useEffect(() => {
-    // Probe /openapi.json so we can show a friendly empty-state if
-    // the operator is running a build without the oapi-generator
-    // surface mounted. We HEAD the JSON rather than the HTML because
-    // a 404 on /openapi.json is the most reliable signal that the
-    // OpenAPI surface isn't wired up; the /docs HTML may exist as a
-    // static asset even when the generator is absent.
-    fetch("/openapi.json", { method: "HEAD", credentials: "include" })
-      .then((r) => setReachable(r.ok ? "ok" : "missing"))
-      .catch(() => setReachable("missing"));
+    const ctrl = new AbortController();
+    fetch("/openapi.json", { credentials: "include", signal: ctrl.signal })
+      .then(async (r) => {
+        if (!r.ok) {
+          setStatus(r.status === 404 ? "missing" : "error");
+          return;
+        }
+        setDoc(await r.json());
+        setStatus("ok");
+      })
+      .catch((err) => {
+        if (err?.name === "AbortError") return;
+        setStatus("error");
+      });
+    return () => ctrl.abort();
   }, []);
 
+  const groups = useMemo(() => groupOperations(doc), [doc]);
+  const tags = useMemo(() => ["all" as const, ...groups.map((g) => g.tag)], [groups]);
+  const filtered = useMemo(() => filterGroups(groups, query, activeTag), [groups, query, activeTag]);
+
+  if (status === "loading") {
+    return <DiscoveryShell status="loading" info={doc?.info}><div className="px-6 py-12 text-sm text-muted-foreground">Loading OpenAPI document…</div></DiscoveryShell>;
+  }
+  if (status === "missing") {
+    return (
+      <DiscoveryShell status="missing">
+        <div className="px-6 py-8 max-w-3xl text-sm text-muted-foreground space-y-2">
+          <div className="text-foreground font-medium">OpenAPI surface not available.</div>
+          <p>
+            This deployment of api-test is running without the OpenAPI generator surface
+            mounted. The Discovery page expects <code className="mono">/openapi.json</code> to
+            be reachable; the request returned 404.
+          </p>
+        </div>
+      </DiscoveryShell>
+    );
+  }
+  if (status === "error" || !doc) {
+    return (
+      <DiscoveryShell status="error">
+        <div className="px-6 py-8 max-w-3xl text-sm text-destructive">
+          Failed to load <code className="mono">/openapi.json</code>.
+        </div>
+      </DiscoveryShell>
+    );
+  }
+
   return (
-    <div className="flex flex-col h-[calc(100vh-3rem)] max-w-none -mx-6 -my-6">
-      <div className="px-6 py-3 border-b border-border bg-card flex items-center justify-between">
-        <div>
-          <h1 className="text-lg font-semibold">Discovery</h1>
-          <div className="text-xs text-muted-foreground">
-            OpenAPI 3.1 reference rendered from{" "}
-            <a href="/openapi.json" className="underline hover:text-foreground">/openapi.json</a>
-            {" "}via{" "}
-            <a href="/docs" className="underline hover:text-foreground">/docs</a>.
+    <DiscoveryShell info={doc.info}>
+      <div className="grid grid-cols-[260px_minmax(0,1fr)] min-h-0 flex-1">
+        {/* Sticky tag rail. */}
+        <aside aria-label="Operation groups" className="border-r border-border bg-muted/20 overflow-y-auto px-3 py-4 space-y-1 text-sm">
+          {tags.map((t) => {
+            const count = t === "all"
+              ? groups.reduce((n, g) => n + g.operations.length, 0)
+              : groups.find((g) => g.tag === t)?.operations.length ?? 0;
+            return (
+              <button
+                key={t}
+                onClick={() => setActiveTag(t)}
+                aria-pressed={activeTag === t}
+                className={[
+                  // min-w-0 + truncate inside is required: without it the long
+                  // tag name forces the button wider than the column, pushing
+                  // the count badge off-screen.
+                  "w-full text-left px-2 py-1.5 rounded transition-colors flex items-center justify-between gap-2 min-w-0",
+                  activeTag === t
+                    ? "bg-primary/15 text-foreground ring-1 ring-primary/30"
+                    : "hover:bg-muted text-muted-foreground hover:text-foreground",
+                ].join(" ")}
+              >
+                <span className="truncate min-w-0">{t === "all" ? "All operations" : t}</span>
+                <span className="mono text-xs text-muted-foreground shrink-0">{count}</span>
+              </button>
+            );
+          })}
+        </aside>
+
+        {/* Main scroll area. */}
+        <main className="overflow-y-auto">
+          <div className="px-6 py-4 sticky top-0 z-10 bg-background/85 backdrop-blur border-b border-border">
+            <div className="relative max-w-2xl">
+              <Search className="size-4 absolute left-2.5 top-1/2 -translate-y-1/2 text-muted-foreground" />
+              <input
+                value={query}
+                onChange={(e) => setQuery(e.target.value)}
+                placeholder="Filter by path, summary, or operationId…"
+                className="w-full pl-8 pr-3 py-2 bg-background border border-input rounded-md text-sm focus:outline-none focus:ring-2 focus:ring-ring"
+              />
+            </div>
           </div>
+          <div className="px-6 py-4 space-y-8">
+            {filtered.length === 0 && (
+              <div className="text-sm text-muted-foreground">No operations match.</div>
+            )}
+            {filtered.map((g) => (
+              <section key={g.tag} className="space-y-3">
+                <header className="flex items-baseline gap-3">
+                  <h2 className="text-lg font-semibold tracking-tight">{g.tag}</h2>
+                  <span className="mono text-xs text-muted-foreground">{g.operations.length}</span>
+                  {g.description && (
+                    <span className="text-xs text-muted-foreground truncate min-w-0">{g.description}</span>
+                  )}
+                </header>
+                <div className="space-y-2">
+                  {g.operations.map((op) => (
+                    <OperationCard
+                      key={`${op.method}-${op.path}`}
+                      method={op.method}
+                      path={op.path}
+                      op={op.op}
+                      schemas={doc.components?.schemas ?? {}}
+                    />
+                  ))}
+                </div>
+              </section>
+            ))}
+          </div>
+        </main>
+      </div>
+    </DiscoveryShell>
+  );
+}
+
+// DiscoveryShell holds the page chrome (title row + downloads + bordered
+// frame) and slots the variable content underneath. Pulled out so the
+// loading / missing / error states get the same chrome as the live view.
+function DiscoveryShell({
+  info,
+  status = "ok",
+  children,
+}: {
+  info?: OpenAPIDoc["info"];
+  status?: "ok" | "loading" | "missing" | "error";
+  children: React.ReactNode;
+}) {
+  const subtitle = (() => {
+    if (status === "loading") return "Fetching /openapi.json…";
+    if (status === "missing") return "/openapi.json is not mounted on this deployment.";
+    if (status === "error")   return "Could not load /openapi.json.";
+    // Avoid concatenating with an em-dash: many published OpenAPI titles
+    // already contain em-dashes, which would render "Foo — bar — /openapi.json".
+    if (info?.title) return `${info.title}  /  /openapi.json`;
+    return "OpenAPI 3.1 reference  /  /openapi.json";
+  })();
+  // /openapi.json, /openapi.yaml, and /docs are all mounted together
+  // (pkg/httpsrv/openapi.go); a missing/errored /openapi.json means the
+  // sibling links also 404. Hide them in those states so we don't offer
+  // dead links the user just told us are broken.
+  const showDownloads = status === "ok";
+  return (
+    <div className="flex flex-col h-[calc(100vh-3rem)] -mx-6 -my-6">
+      <div className="px-6 py-3 border-b border-border bg-card flex items-center justify-between gap-4">
+        <div className="min-w-0">
+          <h1 className="text-lg font-semibold flex items-baseline gap-2">
+            <span>Discovery</span>
+            {info?.version && (
+              // OpenAPI docs use either "1.0.0" or "v1.0.0" for info.version;
+              // prepending "v" unconditionally produced "vv1.0.0". Strip a
+              // leading "v" before re-adding.
+              <span className="mono text-xs text-muted-foreground">
+                v{info.version.replace(/^v/i, "")}
+              </span>
+            )}
+          </h1>
+          <div className="text-xs text-muted-foreground truncate">{subtitle}</div>
         </div>
-        <div className="flex gap-2 text-xs">
-          <a
-            href="/openapi.json"
-            className="bg-card border border-input rounded px-2 py-1 hover:bg-muted"
-            download
-          >
-            Download JSON
-          </a>
-          <a
-            href="/openapi.yaml"
-            className="bg-card border border-input rounded px-2 py-1 hover:bg-muted"
-            download
-          >
-            Download YAML
-          </a>
-        </div>
+        {showDownloads && (
+          <div className="flex gap-2 text-xs shrink-0">
+            <a
+              href="/docs"
+              target="_blank"
+              rel="noopener noreferrer"
+              className="bg-background border border-input rounded px-2 py-1 hover:bg-muted inline-flex items-center gap-1"
+            >
+              Redoc <ExternalLink className="size-3" />
+            </a>
+            <a
+              href="/openapi.json"
+              className="bg-background border border-input rounded px-2 py-1 hover:bg-muted"
+              download
+            >
+              JSON
+            </a>
+            <a
+              href="/openapi.yaml"
+              className="bg-background border border-input rounded px-2 py-1 hover:bg-muted"
+              download
+            >
+              YAML
+            </a>
+          </div>
+        )}
       </div>
+      {children}
+    </div>
+  );
+}
 
-      {reachable === "ok" && (
-        // sandbox keeps the embedded Redoc from navigating the parent
-        // window if a future spec extension introduces an external link
-        // with target=_top. allow-scripts is required for the Redoc
-        // bundle to render; allow-same-origin lets it fetch
-        // /openapi.json relative to the parent origin.
-        <iframe
-          src="/docs"
-          title="API reference"
-          className="flex-1 w-full border-0"
-          sandbox="allow-scripts allow-same-origin"
-        />
+// OperationCard renders one HTTP operation as a collapsible card. Closed
+// state shows method+path+summary; open state shows parameters, request
+// body, responses, and a JSON example pulled from the schema.
+function OperationCard({
+  method,
+  path,
+  op,
+  schemas,
+}: {
+  method: Method;
+  path: string;
+  op: Operation;
+  schemas: Record<string, Schema>;
+}) {
+  const [open, setOpen] = useState(false);
+  const needsAuth = (op.security?.length ?? 0) > 0;
+
+  return (
+    <div className="bg-card border border-border rounded-md overflow-hidden">
+      <button
+        onClick={() => setOpen(!open)}
+        aria-expanded={open}
+        className="w-full flex items-center gap-3 px-3 py-2 hover:bg-muted/40 text-left min-w-0"
+      >
+        {open
+          ? <ChevronDown className="size-4 text-muted-foreground shrink-0" />
+          : <ChevronRight className="size-4 text-muted-foreground shrink-0" />}
+        <span className={`mono text-xs font-semibold uppercase px-2 py-0.5 rounded ${METHOD_COLOR[method]} shrink-0`}>
+          {method}
+        </span>
+        <code className="mono text-sm text-foreground truncate min-w-0">{path}</code>
+        {needsAuth && (
+          <span title="Auth required" className="text-muted-foreground shrink-0">
+            <Lock className="size-3.5" />
+          </span>
+        )}
+        {op.deprecated && (
+          <span className="text-xs uppercase tracking-wide text-amber-600 dark:text-amber-400 shrink-0">deprecated</span>
+        )}
+        {op.summary && (
+          <span className="text-sm text-muted-foreground truncate min-w-0 ml-auto pl-3">
+            {op.summary}
+          </span>
+        )}
+      </button>
+
+      {open && (
+        <div className="border-t border-border px-4 py-3 space-y-4 text-sm">
+          {op.description && (
+            <p className="text-muted-foreground whitespace-pre-wrap">{op.description}</p>
+          )}
+
+          {op.parameters && op.parameters.length > 0 && (
+            <Section title="Parameters">
+              <ParameterTable params={op.parameters} schemas={schemas} />
+            </Section>
+          )}
+
+          {op.requestBody && (
+            <Section title="Request body">
+              <RequestBodyView body={op.requestBody} schemas={schemas} />
+            </Section>
+          )}
+
+          {op.responses && (
+            <Section title="Responses">
+              <ResponsesView responses={op.responses} schemas={schemas} />
+            </Section>
+          )}
+        </div>
       )}
+    </div>
+  );
+}
 
-      {reachable === "missing" && (
-        <div className="p-6 max-w-3xl text-sm text-muted-foreground space-y-2">
-          <div className="text-foreground font-medium">OpenAPI surface not available.</div>
-          <p>
-            This deployment of api-test is running without the OpenAPI
-            generator surface mounted. The Discovery page expects{" "}
-            <code className="mono">/openapi.json</code> and{" "}
-            <code className="mono">/docs</code> to be reachable; the
-            HEAD probe returned a non-OK status.
-          </p>
-          <p>
-            Bring it online by running an api-test build that includes
-            the in-tree <code className="mono">pkg/oapi</code>{" "}
-            generator (any build from <code className="mono">main</code>{" "}
-            once the openapi branch lands). The Plexara API gateway
-            also needs this surface to register api-test as a
-            connection — Discovery doubles as a quick health check.
-          </p>
+function Section({ title, children }: { title: string; children: React.ReactNode }) {
+  return (
+    <div className="space-y-2">
+      <div className="text-xs uppercase tracking-wider text-muted-foreground">{title}</div>
+      {children}
+    </div>
+  );
+}
+
+function ParameterTable({ params, schemas }: { params: Parameter[]; schemas: Record<string, Schema> }) {
+  return (
+    <div className="border border-border rounded overflow-hidden">
+      <table className="w-full text-xs table-fixed">
+        <colgroup>
+          <col className="w-[160px]" />
+          <col className="w-[80px]" />
+          <col className="w-[120px]" />
+          <col />
+        </colgroup>
+        <thead className="bg-muted/40 text-muted-foreground">
+          <tr>
+            <th className="text-left px-3 py-1.5 font-medium">Name</th>
+            <th className="text-left px-3 py-1.5 font-medium">In</th>
+            <th className="text-left px-3 py-1.5 font-medium">Type</th>
+            <th className="text-left px-3 py-1.5 font-medium">Description</th>
+          </tr>
+        </thead>
+        <tbody>
+          {params.map((p) => (
+            <tr key={`${p.in}-${p.name}`} className="border-t border-border align-top">
+              <td className="px-3 py-1.5 mono whitespace-nowrap">
+                {p.name}
+                {p.required && <span className="text-rose-600 dark:text-rose-400 ml-1">*</span>}
+              </td>
+              <td className="px-3 py-1.5 text-muted-foreground">{p.in}</td>
+              <td className="px-3 py-1.5 mono text-muted-foreground truncate" title={schemaType(p.schema, schemas)}>{schemaType(p.schema, schemas)}</td>
+              <td className="px-3 py-1.5 text-muted-foreground break-words">{p.description ?? p.schema?.description ?? ""}</td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+}
+
+function RequestBodyView({ body, schemas }: { body: NonNullable<Operation["requestBody"]>; schemas: Record<string, Schema> }) {
+  const entries = Object.entries(body.content ?? {});
+  if (entries.length === 0) {
+    return <div className="text-muted-foreground text-xs italic">(no body schema)</div>;
+  }
+  return (
+    <div className="space-y-2">
+      {body.description && <p className="text-muted-foreground">{body.description}</p>}
+      {entries.map(([ct, mt]) => (
+        <MediaTypeView key={ct} contentType={ct} mt={mt} schemas={schemas} />
+      ))}
+    </div>
+  );
+}
+
+function ResponsesView({ responses, schemas }: { responses: Record<string, ResponseObject>; schemas: Record<string, Schema> }) {
+  const entries = Object.entries(responses);
+  return (
+    <div className="space-y-2">
+      {entries.map(([code, resp]) => (
+        <ResponseRow key={code} code={code} resp={resp} schemas={schemas} />
+      ))}
+    </div>
+  );
+}
+
+function ResponseRow({ code, resp, schemas }: { code: string; resp: ResponseObject; schemas: Record<string, Schema> }) {
+  const [open, setOpen] = useState(false);
+  const hasBody = Object.keys(resp.content ?? {}).length > 0;
+  const head = (
+    <>
+      {hasBody && (open
+        ? <ChevronDown className="size-3.5 text-muted-foreground shrink-0" />
+        : <ChevronRight className="size-3.5 text-muted-foreground shrink-0" />)}
+      <span className={`mono text-xs font-semibold ${statusBadgeColor(code)}`}>{code}</span>
+      <span className="text-muted-foreground truncate min-w-0">{resp.description ?? ""}</span>
+    </>
+  );
+  return (
+    <div className="border border-border rounded overflow-hidden">
+      {hasBody ? (
+        // Disclosure: button + aria-expanded so screen readers announce
+        // expanded/collapsed state.
+        <button
+          onClick={() => setOpen(!open)}
+          aria-expanded={open}
+          className="w-full flex items-center gap-3 px-3 py-1.5 text-left hover:bg-muted/40 cursor-pointer min-w-0"
+        >
+          {head}
+        </button>
+      ) : (
+        // No body: render a non-interactive row so keyboard users don't
+        // tab through a button that does nothing.
+        <div className="w-full flex items-center gap-3 px-3 py-1.5 min-w-0">{head}</div>
+      )}
+      {open && hasBody && (
+        <div className="border-t border-border px-3 py-2 space-y-2">
+          {Object.entries(resp.content ?? {}).map(([ct, mt]) => (
+            <MediaTypeView key={ct} contentType={ct} mt={mt} schemas={schemas} />
+          ))}
         </div>
       )}
+    </div>
+  );
+}
 
-      {reachable === "checking" && (
-        <div className="p-6 text-sm text-muted-foreground">Probing OpenAPI surface…</div>
+function MediaTypeView({ contentType, mt, schemas }: { contentType: string; mt: MediaType; schemas: Record<string, Schema> }) {
+  const resolved = resolveSchema(mt.schema, schemas);
+  const example = pickExample(mt) ?? exampleFromSchema(resolved, schemas);
+  return (
+    <div className="space-y-2">
+      <div className="mono text-xs text-muted-foreground">{contentType}</div>
+      {resolved && <SchemaView schema={resolved} schemas={schemas} />}
+      {example !== undefined && (
+        <CodeBlock title="Example" code={typeof example === "string" ? example : JSON.stringify(example, null, 2)} />
       )}
     </div>
   );
 }
+
+function SchemaView({ schema, schemas, depth = 0 }: { schema: Schema; schemas: Record<string, Schema>; depth?: number }) {
+  const resolved = resolveSchema(schema, schemas);
+  if (!resolved) return null;
+  if (resolved.type === "object" || resolved.properties) {
+    const required = new Set(resolved.required ?? []);
+    return (
+      <div className="border border-border rounded overflow-hidden">
+        <table className="w-full text-xs table-fixed">
+          <colgroup>
+            <col className="w-[200px]" />
+            <col className="w-[140px]" />
+            <col />
+          </colgroup>
+          <thead className="bg-muted/40 text-muted-foreground">
+            <tr>
+              <th className="text-left px-3 py-1.5 font-medium">Field</th>
+              <th className="text-left px-3 py-1.5 font-medium">Type</th>
+              <th className="text-left px-3 py-1.5 font-medium">Description</th>
+            </tr>
+          </thead>
+          <tbody>
+            {Object.entries(resolved.properties ?? {}).map(([name, prop]) => {
+              const r = resolveSchema(prop, schemas);
+              return (
+                <tr key={name} className="border-t border-border align-top">
+                  <td className="px-3 py-1.5 mono whitespace-nowrap">
+                    {name}
+                    {required.has(name) && <span className="text-rose-600 dark:text-rose-400 ml-1">*</span>}
+                  </td>
+                  <td className="px-3 py-1.5 mono text-muted-foreground truncate" title={schemaType(r, schemas)}>{schemaType(r, schemas)}</td>
+                  <td className="px-3 py-1.5 text-muted-foreground break-words">{r?.description ?? ""}</td>
+                </tr>
+              );
+            })}
+            {!resolved.properties && (
+              <tr><td colSpan={3} className="px-3 py-2 text-muted-foreground italic">(no declared fields)</td></tr>
+            )}
+          </tbody>
+        </table>
+      </div>
+    );
+  }
+  if (resolved.type === "array" && resolved.items) {
+    return (
+      <div className="space-y-2">
+        <div className="mono text-xs text-muted-foreground">array&lt;{schemaType(resolved.items, schemas)}&gt;</div>
+        {depth < 3 && <SchemaView schema={resolved.items} schemas={schemas} depth={depth + 1} />}
+      </div>
+    );
+  }
+  // Scalar — type + optional enum/format/constraints.
+  return (
+    <div className="text-xs text-muted-foreground space-x-2">
+      <span className="mono">{schemaType(resolved, schemas)}</span>
+      {resolved.enum && <span>enum: [{resolved.enum.map((e) => JSON.stringify(e)).join(", ")}]</span>}
+      {resolved.format && <span>format: {resolved.format}</span>}
+    </div>
+  );
+}
+
+function CodeBlock({ title, code }: { title?: string; code: string }) {
+  const [copied, setCopied] = useState(false);
+  // Track the active reset timer so an unmount mid-window doesn't fire
+  // setCopied on a dead component. React strict-mode double-mount would
+  // otherwise queue two timers from one click.
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  useEffect(() => () => {
+    if (timerRef.current) clearTimeout(timerRef.current);
+  }, []);
+  async function copy() {
+    try {
+      await navigator.clipboard.writeText(code);
+      setCopied(true);
+      if (timerRef.current) clearTimeout(timerRef.current);
+      timerRef.current = setTimeout(() => setCopied(false), 1500);
+    } catch { /* clipboard unavailable on http:// origins */ }
+  }
+  return (
+    <div className="relative group">
+      {title && <div className="text-xs text-muted-foreground mb-1">{title}</div>}
+      <pre className="mono text-xs bg-muted/30 border border-border rounded p-3 overflow-auto max-h-[40vh] whitespace-pre-wrap break-words">{code}</pre>
+      <button
+        onClick={copy}
+        className="absolute top-1 right-1 opacity-0 group-hover:opacity-100 transition-opacity bg-card border border-border rounded p-1 text-muted-foreground hover:text-foreground"
+        title={copied ? "copied" : "copy"}
+      >
+        {copied ? <Check className="size-3.5" /> : <Copy className="size-3.5" />}
+      </button>
+    </div>
+  );
+}
+
+// --- helpers ---
+
+type GroupedOp = { method: Method; path: string; op: Operation };
+type Group = { tag: string; description?: string; operations: GroupedOp[] };
+
+function groupOperations(doc: OpenAPIDoc | null): Group[] {
+  if (!doc?.paths) return [];
+  const buckets = new Map<string, GroupedOp[]>();
+  for (const [path, item] of Object.entries(doc.paths)) {
+    for (const m of METHODS) {
+      const op = item[m] as Operation | undefined;
+      if (!op) continue;
+      const tag = op.tags?.[0] ?? "untagged";
+      const arr = buckets.get(tag) ?? [];
+      arr.push({ method: m, path, op });
+      buckets.set(tag, arr);
+    }
+  }
+  const declaredOrder = (doc.tags ?? []).map((t) => t.name);
+  const tags = Array.from(buckets.keys()).sort((a, b) => {
+    const ai = declaredOrder.indexOf(a);
+    const bi = declaredOrder.indexOf(b);
+    if (ai !== -1 && bi !== -1) return ai - bi;
+    if (ai !== -1) return -1;
+    if (bi !== -1) return 1;
+    return a.localeCompare(b);
+  });
+  return tags.map((t) => ({
+    tag: t,
+    description: doc.tags?.find((x) => x.name === t)?.description,
+    operations: (buckets.get(t) ?? []).sort((a, b) => a.path.localeCompare(b.path) || a.method.localeCompare(b.method)),
+  }));
+}
+
+function filterGroups(groups: Group[], query: string, tag: string | "all"): Group[] {
+  const q = query.trim().toLowerCase();
+  const byTag = tag === "all" ? groups : groups.filter((g) => g.tag === tag);
+  if (!q) return byTag;
+  return byTag
+    .map((g) => ({
+      ...g,
+      operations: g.operations.filter((op) =>
+        op.path.toLowerCase().includes(q) ||
+        (op.op.summary?.toLowerCase().includes(q) ?? false) ||
+        (op.op.operationId?.toLowerCase().includes(q) ?? false) ||
+        (op.op.description?.toLowerCase().includes(q) ?? false),
+      ),
+    }))
+    .filter((g) => g.operations.length > 0);
+}
+
+function resolveSchema(schema: Schema | undefined, schemas: Record<string, Schema>, seen: Set<string> = new Set()): Schema | undefined {
+  if (!schema) return undefined;
+  if (schema.$ref) {
+    const name = schema.$ref.replace(/^#\/components\/schemas\//, "");
+    if (seen.has(name)) return { type: "object", description: `circular ref → ${name}` };
+    const next = schemas[name];
+    if (!next) return { type: "object", description: `unresolved ref → ${name}` };
+    return resolveSchema(next, schemas, new Set([...seen, name]));
+  }
+  return schema;
+}
+
+function schemaType(schema: Schema | undefined, schemas: Record<string, Schema>): string {
+  if (!schema) return "";
+  if (schema.$ref) return schema.$ref.replace(/^#\/components\/schemas\//, "");
+  const resolved = resolveSchema(schema, schemas);
+  if (!resolved) return "";
+  if (resolved.oneOf) return `oneOf<${resolved.oneOf.map((s) => schemaType(s, schemas)).join(" | ")}>`;
+  if (resolved.anyOf) return `anyOf<${resolved.anyOf.map((s) => schemaType(s, schemas)).join(" | ")}>`;
+  if (resolved.allOf) return `allOf<${resolved.allOf.map((s) => schemaType(s, schemas)).join(" & ")}>`;
+  if (resolved.type === "array" && resolved.items) return `array<${schemaType(resolved.items, schemas)}>`;
+  if (Array.isArray(resolved.type)) return resolved.type.join("|");
+  const base = resolved.type ?? "object";
+  return resolved.format ? `${base}<${resolved.format}>` : base;
+}
+
+function pickExample(mt: MediaType): unknown {
+  if (mt.example !== undefined) return mt.example;
+  if (mt.examples) {
+    const first = Object.values(mt.examples)[0];
+    if (first && "value" in first) return first.value;
+  }
+  return undefined;
+}
+
+// exampleFromSchema fabricates a minimal example value for a schema when
+// the document doesn't provide one. Walks objects + arrays one level
+// deep beyond named refs to keep the rendered example readable.
+function exampleFromSchema(schema: Schema | undefined, schemas: Record<string, Schema>, depth = 0): unknown {
+  if (!schema || depth > 4) return undefined;
+  const resolved = resolveSchema(schema, schemas);
+  if (!resolved) return undefined;
+  if (resolved.example !== undefined) return resolved.example;
+  if (resolved.default !== undefined) return resolved.default;
+  if (resolved.enum && resolved.enum.length > 0) return resolved.enum[0];
+  if (resolved.type === "array" && resolved.items) {
+    const inner = exampleFromSchema(resolved.items, schemas, depth + 1);
+    return inner === undefined ? [] : [inner];
+  }
+  if (resolved.type === "object" || resolved.properties) {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(resolved.properties ?? {})) {
+      const ex = exampleFromSchema(v, schemas, depth + 1);
+      if (ex !== undefined) out[k] = ex;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+  }
+  switch (resolved.type) {
+    case "string":  return resolved.format === "uuid" ? "00000000-0000-0000-0000-000000000000"
+                       : resolved.format === "date-time" ? new Date().toISOString()
+                       : "string";
+    case "integer": return 0;
+    case "number":  return 0;
+    case "boolean": return false;
+  }
+  return undefined;
+}
+
+function statusBadgeColor(code: string): string {
+  if (code.startsWith("2")) return "text-emerald-700 dark:text-emerald-300";
+  if (code.startsWith("3")) return "text-sky-700 dark:text-sky-300";
+  if (code.startsWith("4")) return "text-amber-700 dark:text-amber-300";
+  if (code.startsWith("5")) return "text-rose-700 dark:text-rose-300";
+  return "text-muted-foreground";
+}