From 13c0f6842a6bb8a99d0aa0b2fb3bd38a50782fec Mon Sep 17 00:00:00 2001
From: ArthurGamby <gamby@prisma.io>
Date: Thu, 19 Feb 2026 17:00:04 +0100
Subject: [PATCH 1/5] feat(docs): add "Was this helpful?" page feedback widget

Adds a thumbs-up/thumbs-down widget at the bottom of every docs page.
On thumbs-down, an optional textarea expands for free-text feedback.
Stores state in localStorage to prevent duplicate submissions.
Fires a PostHog event (docs:page_feedback) with path, vote, and comment.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../app/docs/(default)/[[...slug]]/page.tsx   |   2 +
 apps/docs/src/components/page-feedback.tsx    | 122 ++++++++++++++++++
 2 files changed, 124 insertions(+)
 create mode 100644 apps/docs/src/components/page-feedback.tsx

diff --git a/apps/docs/src/app/docs/(default)/[[...slug]]/page.tsx b/apps/docs/src/app/docs/(default)/[[...slug]]/page.tsx
index 1a70e9613e..e3e752d22d 100644
--- a/apps/docs/src/app/docs/(default)/[[...slug]]/page.tsx
+++ b/apps/docs/src/app/docs/(default)/[[...slug]]/page.tsx
@@ -13,6 +13,7 @@ import {
   PageLastUpdate,
 } from '@/components/layout/notebook/page';
 import { TechArticleSchema, BreadcrumbSchema } from '@/components/structured-data';
+import { PageFeedback } from '@/components/page-feedback';
 
 interface PageParams {
   slug?: string[];
@@ -68,6 +69,7 @@ export default async function Page({
           />
         )}
       </div>
+      <PageFeedback />
     </DocsPage>
     </>
   );
diff --git a/apps/docs/src/components/page-feedback.tsx b/apps/docs/src/components/page-feedback.tsx
new file mode 100644
index 0000000000..4166a47170
--- /dev/null
+++ b/apps/docs/src/components/page-feedback.tsx
@@ -0,0 +1,122 @@
+'use client';
+
+import { useState, useEffect, useCallback } from 'react';
+import { ThumbsUp, ThumbsDown, Send } from 'lucide-react';
+import { cn } from '@prisma-docs/ui/lib/cn';
+import { usePathname } from 'fumadocs-core/framework';
+import posthog from 'posthog-js';
+
+type FeedbackState = 'idle' | 'upvoted' | 'downvoted' | 'submitted';
+
+function getStorageKey(path: string) {
+  return `prisma-docs:page-feedback:${path}`;
+}
+
+export function PageFeedback() {
+  const pathname = usePathname();
+  const [state, setState] = useState<FeedbackState>('idle');
+  const [comment, setComment] = useState('');
+  const [showTextarea, setShowTextarea] = useState(false);
+
+  useEffect(() => {
+    try {
+      const stored = localStorage.getItem(getStorageKey(pathname));
+      if (stored) setState('submitted');
+    } catch {}
+  }, [pathname]);
+
+  const persist = useCallback(
+    (vote: 'up' | 'down', text?: string) => {
+      try {
+        localStorage.setItem(getStorageKey(pathname), JSON.stringify({ vote, text }));
+      } catch {}
+      posthog.capture('docs:page_feedback', {
+        path: pathname,
+        vote,
+        comment: text ?? null,
+      });
+    },
+    [pathname],
+  );
+
+  const handleUp = () => {
+    setState('submitted');
+    persist('up');
+  };
+
+  const handleDown = () => {
+    setState('downvoted');
+    setShowTextarea(true);
+  };
+
+  const handleSubmitComment = () => {
+    setState('submitted');
+    persist('down', comment || undefined);
+  };
+
+  if (state === 'submitted') {
+    return (
+      <div className="flex items-center gap-2 rounded-lg border border-fd-border bg-fd-card px-4 py-3 text-sm text-fd-muted-foreground">
+        <span>Thanks for your feedback!</span>
+      </div>
+    );
+  }
+
+  return (
+    <div className="flex flex-col gap-3 rounded-lg border border-fd-border bg-fd-card px-4 py-4">
+      <div className="flex items-center justify-between">
+        <span className="text-sm font-medium text-fd-foreground">
+          Was this page helpful?
+        </span>
+        <div className="flex items-center gap-1.5">
+          <button
+            type="button"
+            onClick={handleUp}
+            className={cn(
+              'inline-flex items-center gap-1.5 rounded-md border border-fd-border px-3 py-1.5 text-sm transition-colors hover:bg-fd-accent hover:text-fd-accent-foreground',
+              'text-fd-muted-foreground',
+            )}
+          >
+            <ThumbsUp className="size-3.5" />
+            Yes
+          </button>
+          <button
+            type="button"
+            onClick={handleDown}
+            className={cn(
+              'inline-flex items-center gap-1.5 rounded-md border border-fd-border px-3 py-1.5 text-sm transition-colors hover:bg-fd-accent hover:text-fd-accent-foreground',
+              showTextarea
+                ? 'bg-fd-accent text-fd-accent-foreground'
+                : 'text-fd-muted-foreground',
+            )}
+          >
+            <ThumbsDown className="size-3.5" />
+            No
+          </button>
+        </div>
+      </div>
+
+      {showTextarea && (
+        <div className="flex flex-col gap-2 animate-in fade-in slide-in-from-top-1 duration-200">
+          <textarea
+            value={comment}
+            onChange={(e) => setComment(e.target.value)}
+            placeholder="What was missing or unclear? (optional)"
+            rows={3}
+            className="w-full resize-none rounded-md border border-fd-border bg-fd-background px-3 py-2 text-sm text-fd-foreground placeholder:text-fd-muted-foreground focus:outline-none focus:ring-2 focus:ring-fd-ring"
+          />
+          <div className="flex justify-end">
+            <button
+              type="button"
+              onClick={handleSubmitComment}
+              className="inline-flex items-center gap-1.5 rounded-md bg-fd-primary px-3 py-1.5 text-sm font-medium text-fd-primary-foreground transition-colors hover:bg-fd-primary/90"
+            >
+              <Send className="size-3.5" />
+              Send feedback
+            </button>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}

From e052181c46fda81def65f144f699da7acd6aad1c Mon Sep 17 00:00:00 2001
From: ArthurGamby <gamby@prisma.io>
Date: Thu, 19 Feb 2026 17:00:10 +0100
Subject: [PATCH 2/5] feat(docs): add search analytics for failed/no-result
 searches

Track docs:search_no_results and docs:search_no_click PostHog events.
Adds a visible "No results" empty state in the search dialog.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 apps/docs/src/components/search.tsx | 54 ++++++++++++++++++++++++++---
 1 file changed, 50 insertions(+), 4 deletions(-)

diff --git a/apps/docs/src/components/search.tsx b/apps/docs/src/components/search.tsx
index e03b957fa7..9be46904d1 100644
--- a/apps/docs/src/components/search.tsx
+++ b/apps/docs/src/components/search.tsx
@@ -11,8 +11,8 @@ import {
   SearchDialogOverlay,
   type SharedProps,
 } from 'fumadocs-ui/components/dialog/search';
-import { SearchIcon, X } from 'lucide-react';
-import { ComponentProps, useEffect, useRef } from 'react';
+import { SearchIcon, SearchX, X } from 'lucide-react';
+import { type ComponentProps, useCallback, useEffect, useRef } from 'react';
 import posthog from 'posthog-js';
 
 export function CustomSearchDialogIcon(
@@ -38,7 +38,9 @@ export default function CustomSearchDialog(props: SharedProps) {
 
   const lastCapturedQueryRef = useRef<string | null>(null);
   const stabilityTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-  
+  const clickedResultRef = useRef(false);
+  const lastNoResultQueryRef = useRef<string | null>(null);
+
   useEffect(() => {
     if (
       search.length > 0 &&
@@ -62,12 +64,42 @@ export default function CustomSearchDialog(props: SharedProps) {
     };
   }, [query.data, query.isLoading, search]);
 
+  const resultsArray = query.data !== 'empty' && query.data !== undefined ? query.data : null;
+  const hasResults = Array.isArray(resultsArray) && resultsArray.length > 0;
+  const showNoResults = !query.isLoading && search.length > 0 && !hasResults;
+
+  useEffect(() => {
+    if (showNoResults && lastNoResultQueryRef.current !== search) {
+      lastNoResultQueryRef.current = search;
+      posthog.capture('docs:search_no_results', { query: search });
+    }
+  }, [showNoResults, search]);
+
+  const handleOpenChange = useCallback(
+    (open: boolean) => {
+      if (!open && search.length > 0 && !clickedResultRef.current) {
+        const resultCount = Array.isArray(resultsArray) ? resultsArray.length : 0;
+        posthog.capture('docs:search_no_click', {
+          query: search,
+          result_count: resultCount,
+        });
+      }
+      if (!open) {
+        clickedResultRef.current = false;
+        lastNoResultQueryRef.current = null;
+      }
+      props.onOpenChange?.(open);
+    },
+    [search, resultsArray, props],
+  );
+
   return (
     <SearchDialog
       search={search}
       onSearchChange={setSearch}
       isLoading={query.isLoading}
       {...props}
+      onOpenChange={handleOpenChange}
     >
       <SearchDialogOverlay suppressHydrationWarning />
       <SearchDialogContent>
@@ -78,7 +110,21 @@ export default function CustomSearchDialog(props: SharedProps) {
             <X className="size-4" aria-hidden="true" />
           </SearchDialogClose>
         </SearchDialogHeader>
-        <SearchDialogList items={query.data !== 'empty' ? query.data : null} />
+        {/* eslint-disable-next-line jsx-a11y/click-events-have-key-events, jsx-a11y/no-static-element-interactions */}
+        <div onClick={() => { clickedResultRef.current = true; }}>
+          <SearchDialogList items={resultsArray} />
+        </div>
+        {showNoResults && (
+          <div className="flex flex-col items-center gap-2 px-6 py-8 text-center">
+            <SearchX className="size-10 text-fd-muted-foreground/50" />
+            <p className="text-sm font-medium text-fd-muted-foreground">
+              No results for &ldquo;{search}&rdquo;
+            </p>
+            <p className="text-xs text-fd-muted-foreground/70">
+              Try different keywords or check for typos
+            </p>
+          </div>
+        )}
       </SearchDialogContent>
     </SearchDialog>
   );

From 35fed3a38f964ce60baae211994252368100b58d Mon Sep 17 00:00:00 2001
From: ArthurGamby <gamby@prisma.io>
Date: Thu, 19 Feb 2026 17:00:16 +0100
Subject: [PATCH 3/5] feat(docs): add status page indicator in navbar

Adds a green/amber/red dot with label in the top-right navbar.
Links to the Prisma status page. Status is hardcoded for demo purposes.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../src/components/layout/notebook/index.tsx  |  4 ++
 apps/docs/src/components/status-indicator.tsx | 51 +++++++++++++++++++
 2 files changed, 55 insertions(+)
 create mode 100644 apps/docs/src/components/status-indicator.tsx

diff --git a/apps/docs/src/components/layout/notebook/index.tsx b/apps/docs/src/components/layout/notebook/index.tsx
index 75b1c15f71..16b445f372 100644
--- a/apps/docs/src/components/layout/notebook/index.tsx
+++ b/apps/docs/src/components/layout/notebook/index.tsx
@@ -44,6 +44,7 @@ import {
   type SidebarTabWithProps,
 } from '../sidebar/tabs/dropdown';
 import { AIChatSidebar } from '@/components/ai-chat-sidebar';
+import { StatusIndicator } from '@/components/status-indicator';
 
 export interface DocsLayoutProps extends BaseLayoutProps {
   tree: PageTree.Root;
@@ -310,6 +311,9 @@ function DocsNavbar({
             />
           ))}
         <div className="flex flex-1 items-center justify-end gap-2">
+          <div className="max-md:hidden">
+            <StatusIndicator />
+          </div>
           <AIChatSidebar />
           <div className="flex items-center gap-2 max-md:hidden">
             {links
diff --git a/apps/docs/src/components/status-indicator.tsx b/apps/docs/src/components/status-indicator.tsx
new file mode 100644
index 0000000000..230a2ac81c
--- /dev/null
+++ b/apps/docs/src/components/status-indicator.tsx
@@ -0,0 +1,51 @@
+'use client';
+
+import { cn } from '@prisma-docs/ui/lib/cn';
+
+type Status = 'operational' | 'degraded' | 'incident';
+
+const statusConfig: Record<Status, { label: string; dotClass: string; pulseClass: string }> = {
+  operational: {
+    label: 'Available',
+    dotClass: 'bg-emerald-500',
+    pulseClass: 'bg-emerald-400',
+  },
+  degraded: {
+    label: 'Degraded',
+    dotClass: 'bg-amber-500',
+    pulseClass: 'bg-amber-400',
+  },
+  incident: {
+    label: 'Incident',
+    dotClass: 'bg-red-500',
+    pulseClass: 'bg-red-400',
+  },
+};
+
+export function StatusIndicator({ status = 'operational' }: { status?: Status }) {
+  const config = statusConfig[status];
+
+  return (
+    <a
+      href="https://www.prisma-status.com"
+      target="_blank"
+      rel="noopener noreferrer"
+      className={cn(
+        'inline-flex items-center gap-2 rounded-full border border-fd-border px-2.5 py-1 text-xs font-medium text-fd-muted-foreground transition-colors hover:text-fd-foreground hover:bg-fd-accent',
+      )}
+    >
+      <span className="relative flex size-2">
+        <span
+          className={cn(
+            'absolute inline-flex size-full animate-ping rounded-full opacity-75',
+            config.pulseClass,
+          )}
+        />
+        <span
+          className={cn('relative inline-flex size-2 rounded-full', config.dotClass)}
+        />
+      </span>
+      {config.label}
+    </a>
+  );
+}

From 673b10b43ba251f75bbfdb2427dffc5c91176245 Mon Sep 17 00:00:00 2001
From: ArthurGamby <gamby@prisma.io>
Date: Thu, 19 Feb 2026 17:00:23 +0100
Subject: [PATCH 4/5] feat(docs): add floating "Ask a question" bar

Adds a fixed-bottom floating input that opens the AI chat sidebar.
Fades out smoothly when scrolling near the page bottom.
Desktop-only (mobile uses the existing drawer trigger).

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 apps/docs/src/app/docs/(default)/layout.tsx | 22 +++---
 apps/docs/src/components/floating-ask.tsx   | 78 +++++++++++++++++++++
 2 files changed, 91 insertions(+), 9 deletions(-)
 create mode 100644 apps/docs/src/components/floating-ask.tsx

diff --git a/apps/docs/src/app/docs/(default)/layout.tsx b/apps/docs/src/app/docs/(default)/layout.tsx
index d2cd123927..a726ff3b85 100644
--- a/apps/docs/src/app/docs/(default)/layout.tsx
+++ b/apps/docs/src/app/docs/(default)/layout.tsx
@@ -4,6 +4,7 @@ import { VersionSwitcher } from '@/components/version-switcher';
 import type { LinkItemType } from 'fumadocs-ui/layouts/shared';
 import { DocsLayout } from '@/components/layout/notebook';
 import { LATEST_VERSION } from '@/lib/version';
+import { FloatingAsk } from '@/components/floating-ask';
 
 export default async function Layout({
   children,
@@ -21,14 +22,17 @@ export default async function Layout({
   ];
 
   return (
-    <DocsLayout
-      {...base}
-      links={navbarLinks}
-      nav={{ ...nav }}
-      sidebar={{ collapsible: false }}
-      tree={source.pageTree}
-    >
-      {children}
-    </DocsLayout>
+    <>
+      <DocsLayout
+        {...base}
+        links={navbarLinks}
+        nav={{ ...nav }}
+        sidebar={{ collapsible: false }}
+        tree={source.pageTree}
+      >
+        {children}
+      </DocsLayout>
+      <FloatingAsk />
+    </>
   );
 }
diff --git a/apps/docs/src/components/floating-ask.tsx b/apps/docs/src/components/floating-ask.tsx
new file mode 100644
index 0000000000..3b929a2e6d
--- /dev/null
+++ b/apps/docs/src/components/floating-ask.tsx
@@ -0,0 +1,78 @@
+'use client';
+
+import { useEffect, useCallback, useState } from 'react';
+import { ArrowUp } from 'lucide-react';
+import { cn } from '@prisma-docs/ui/lib/cn';
+import { useAIChatContext } from '@/hooks/use-ai-chat';
+
+export function FloatingAsk() {
+  const { setIsOpen, setPrompt } = useAIChatContext();
+  const [visible, setVisible] = useState(true);
+  const [inputValue, setInputValue] = useState('');
+  const [isMac, setIsMac] = useState(true);
+
+  useEffect(() => {
+    setIsMac(navigator.platform?.toUpperCase().includes('MAC') ?? true);
+  }, []);
+
+  const checkScroll = useCallback(() => {
+    const distanceFromBottom =
+      document.documentElement.scrollHeight -
+      window.scrollY -
+      window.innerHeight;
+    setVisible(distanceFromBottom > 200);
+  }, []);
+
+  useEffect(() => {
+    window.addEventListener('scroll', checkScroll, { passive: true });
+    checkScroll();
+    return () => window.removeEventListener('scroll', checkScroll);
+  }, [checkScroll]);
+
+  const handleSubmit = () => {
+    if (inputValue.trim()) {
+      setPrompt(inputValue.trim());
+    }
+    setIsOpen(true);
+    setInputValue('');
+  };
+
+  const handleKeyDown = (e: React.KeyboardEvent) => {
+    if (e.key === 'Enter' && !e.shiftKey) {
+      e.preventDefault();
+      handleSubmit();
+    }
+  };
+
+  return (
+    <div
+      className={cn(
+        'fixed bottom-6 left-1/2 z-40 -translate-x-1/2 w-full max-w-lg px-4 transition-opacity duration-500 ease-in-out max-md:hidden',
+        visible ? 'opacity-100' : 'opacity-0 pointer-events-none',
+      )}
+    >
+      <div className="group flex flex-col gap-2 rounded-2xl border border-fd-foreground/20 bg-fd-background/80 px-4 pt-3 pb-3 shadow-lg backdrop-blur-xl transition-transform duration-200 ease-out hover:scale-[1.025]">
+        <input
+          type="text"
+          value={inputValue}
+          onChange={(e) => setInputValue(e.target.value)}
+          onKeyDown={handleKeyDown}
+          placeholder="Ask a question..."
+          className="w-full bg-transparent text-sm text-fd-foreground placeholder:text-fd-muted-foreground focus:outline-none"
+        />
+        <div className="flex items-center justify-end gap-2">
+          <kbd className="hidden sm:inline-flex items-center gap-0.5 rounded-md border border-fd-border bg-fd-muted px-1.5 py-0.5 text-[10px] font-medium text-fd-muted-foreground">
+            {isMac ? '⌘' : 'Ctrl'}I
+          </kbd>
+          <button
+            type="button"
+            onClick={handleSubmit}
+            className="flex size-7 items-center justify-center rounded-full bg-fd-primary text-fd-primary-foreground transition-colors hover:bg-fd-primary/90"
+          >
+            <ArrowUp className="size-4" />
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}

From 0831b3adf17e787fc195705b318628c46eeb8d98 Mon Sep 17 00:00:00 2001
From: ArthurGamby <gamby@prisma.io>
Date: Thu, 19 Feb 2026 17:01:25 +0100
Subject: [PATCH 5/5] feat(docs): add full competitors report

---
 docs-feature-gap-analysis.md | 450 +++++++++++++++++++++++++++++++++++
 1 file changed, 450 insertions(+)
 create mode 100644 docs-feature-gap-analysis.md

diff --git a/docs-feature-gap-analysis.md b/docs-feature-gap-analysis.md
new file mode 100644
index 0000000000..c41a949bdd
--- /dev/null
+++ b/docs-feature-gap-analysis.md
@@ -0,0 +1,450 @@
+# Prisma Docs — Feature Gap Analysis & Improvement Opportunities
+
+> **Date:** February 19, 2026
+> **Scope:** `apps/docs/` (Fumadocs-based documentation site)
+> **Goal:** Identify high-value features that the best documentation websites have and that Prisma's docs site may be missing, ranked by impact and effort.
+
+---
+
+## What You Already Have (Strong Foundation)
+
+The Prisma docs site is already ahead of most competitors. Before looking at gaps, here's what's already in place:
+
+| Category | Feature | Details |
+|----------|---------|---------|
+| **AI** | AI Chat | Kapa AI via `Cmd+I`, with conversation persistence, source citations, and feedback (upvote/downvote) |
+| **AI** | "Use Prompt" Buttons | Open in ChatGPT, Claude, T3 Chat, Copy Markdown |
+| **AI** | `llms.txt` + `llms-full.txt` | AI-optimized documentation exports |
+| **Search** | Vector Search | Mixedbread-powered via `Cmd+K` with PostHog query tracking |
+| **Code** | Code Blocks | Copy buttons, line highlighting, file names, tabbed examples |
+| **Code** | Package Manager Tabs | npm / pnpm / yarn / bun |
+| **Navigation** | Version Switcher | v6 / v7 toggle |
+| **Navigation** | Breadcrumbs, TOC, Sidebar | Scroll-spy on TOC, collapsible sidebar |
+| **Content** | Edit on GitHub | Links on every page |
+| **Content** | Page Last Updated | Derived from git history |
+| **Theming** | Dark / Light / System | Theme toggle |
+| **Analytics** | PostHog + Sentry | Page views, search tracking, error monitoring |
+| **SEO** | OG Images, Schema.org, RSS | Auto-generated OG images, structured data, feed |
+| **Ops** | 404 Tracking | Missing page detection |
+
+---
+
+## Features You're Missing (Ranked by Impact)
+
+### Tier 1 — High Impact, Reasonable Effort
+
+---
+
+#### 1. "Was This Helpful?" Page Feedback Widget
+
+**Who does it:** Stripe, Vercel, Cloudflare, Mintlify, Clerk
+
+**What it is:**
+A thumbs-up / thumbs-down widget at the bottom of every documentation page. On thumbs-down, an optional free-text field appears asking "What was missing or unclear?" Feedback is routed to Slack/Linear via a webhook.
+
+**Why it matters:**
+- Direct, per-page signal on content quality — far more actionable than page views alone.
+- Combined with PostHog analytics (time-on-page, scroll depth), creates a powerful content health system.
+- You already have upvote/downvote on AI chat responses — extending this pattern to pages is natural and consistent.
+- Stripe and Vercel both credit page-level feedback as one of their most valuable docs inputs.
+
+**Implementation approach:**
+- React component with two states: initial (thumbs up/down) and expanded (text input on thumbs-down).
+- API route that forwards to Slack webhook and/or writes to a database/PostHog custom event.
+- Include page path, timestamp, and optional free text in the payload.
+- Store vote in `localStorage` to prevent duplicate submissions and show "Thanks for your feedback" on return visits.
+
+**Effort:** Low
+**Priority:** Start here — quick win with outsized signal value.
+
+**Reference sites:**
+- [Stripe Docs](https://stripe.com/docs) — bottom of every page
+- [Vercel Docs](https://vercel.com/docs) — "Was this helpful?" with emoji scale
+- [Cloudflare Docs](https://developers.cloudflare.com) — thumbs up/down + text
+
+---
+
+#### 2. Enable the API Playground / "Try It" Feature
+
+**Who does it:** Stripe, ReadMe, Mintlify, Scalar
+
+**What it is:**
+You already have `fumadocs-openapi@10.3.5` installed, but the playground feature is **disabled**. Enabling it would let developers fill in parameters and execute real API calls (e.g., against Prisma Accelerate or Pulse endpoints) directly from the documentation.
+
+**Why it matters:**
+- Interactive API exploration is consistently rated as the #1 most-valued feature in API docs surveys.
+- The difference between "read about it" and "try it now" is enormous for developer trust and adoption.
+- The infrastructure is already there — this is about configuration, not building from scratch.
+- Competitors like Scalar and ReadMe have made interactive API docs the baseline expectation.
+
+**Implementation approach:**
+- Enable the playground option in the fumadocs-openapi configuration.
+- Configure CORS and authentication for target endpoints (Accelerate, Pulse).
+- Consider a sandbox/demo environment for safe exploration.
+- Add rate limiting to prevent abuse.
+
+**Effort:** Low–Medium (infrastructure exists, needs enabling + endpoint configuration)
+**Priority:** Start here — high leverage from existing investment.
+
+**Reference sites:**
+- [Scalar](https://scalar.com) — modern OpenAPI viewer with playground
+- [Stripe API Reference](https://stripe.com/docs/api) — right-side request builder
+- [ReadMe](https://readme.com) — "Try It" panels on every endpoint
+
+---
+
+#### 3. Related Content / "Next Steps" Suggestions
+
+**Who does it:** Stripe, Vercel, Cloudflare
+
+**What it is:**
+Contextual links at the bottom of each page suggesting semantically related guides, API references, or deeper dives. Not just prev/next linear navigation, but "You might also be interested in..." recommendations that cross product boundaries.
+
+**Why it matters:**
+- Reduces bounce rate by guiding users to the next relevant piece of content.
+- Helps users discover content they didn't know existed — especially valuable for Prisma's multi-product surface (ORM, Accelerate, Pulse, Optimize).
+- Turns the docs from a reference lookup into a connected learning experience.
+- Stripe reports that related content suggestions significantly increase pages-per-session.
+
+**Implementation approach (two options):**
+
+*Option A — Manual (frontmatter-based):*
+- Add a `relatedContent` field to page frontmatter with slugs/paths.
+- Authors curate connections when writing/updating pages.
+- Simple, high-quality, but doesn't scale automatically.
+
+*Option B — Automated (embedding similarity):*
+- Use the existing Mixedbread embeddings from search to find semantically similar pages.
+- Pre-compute at build time and store as a JSON mapping.
+- Requires no manual curation, scales automatically, but may surface less-relevant results.
+
+*Recommended:* Start with Option A for key pages, add Option B as a fallback for pages without manual curation.
+
+**Effort:** Medium
+**Priority:** Next phase.
+
+**Reference sites:**
+- [Stripe Docs](https://stripe.com/docs) — "Related" section at page bottom
+- [Vercel Docs](https://vercel.com/docs) — "Related" cards
+- [Cloudflare Docs](https://developers.cloudflare.com) — "See also" sections
+
+---
+
+#### 4. Search Analytics: Failed / No-Result Searches
+
+**Who does it:** Mintlify, ReadMe, GitBook
+
+**What it is:**
+You already track search queries via PostHog, but specifically tracking searches that return **zero results** or where users **don't click any result** provides the highest-signal data for content gaps.
+
+**Why it matters:**
+- Failed searches are the single most actionable indicator of missing content.
+- "No result" queries directly tell you what users expect to find but can't.
+- "No click" queries tell you that results exist but don't match user intent (title/description mismatch).
+- This is one of the cheapest, most valuable analytics features any docs team can add.
+
+**Implementation approach:**
+- In the existing search component (`search.tsx`), fire a PostHog event when:
+  - A search returns 0 results: `docs_search_no_results` with the query string.
+  - A user closes search without clicking a result: `docs_search_no_click` with the query and result count.
+- Create a PostHog dashboard grouping these by frequency.
+- Optionally set up a weekly Slack digest of top failed queries.
+
+**Effort:** Low
+**Priority:** Start here — pure analytics enhancement, no UI changes needed.
+
+---
+
+#### 5. Global Language Switcher (Beyond Package Managers)
+
+**Who does it:** Stripe (8+ languages), Supabase, Clerk
+
+**What it is:**
+You have npm/pnpm/yarn/bun tabs for installation commands. But for Prisma Client code examples, a persistent **TypeScript / JavaScript** toggle (and potentially broader language support) that applies globally across all code examples on every page and is remembered across sessions.
+
+**Why it matters:**
+- Prisma users work in different environments — some use TypeScript, some plain JavaScript, and increasingly Python and Go via Prisma Client extensions.
+- A global toggle avoids users clicking language tabs on every single page.
+- Stripe's per-language docs experience is consistently cited as a gold standard — the key insight is persistence (your language choice follows you everywhere).
+
+**Implementation approach:**
+- Store language preference in a cookie or `localStorage`.
+- Create a global toggle in the header or sidebar (similar to the version switcher).
+- Tag code blocks in MDX with a `language` metadata attribute.
+- On render, show only the code block matching the user's preference.
+- Fall back gracefully when a specific language variant isn't available for a page.
+
+**Effort:** Medium (needs state persistence + consistent tagging across all code examples)
+**Priority:** Next phase.
+
+**Reference sites:**
+- [Stripe Docs](https://stripe.com/docs) — language selector in sidebar, persists across pages
+- [Supabase Docs](https://supabase.com/docs) — JS/Python/Dart toggle
+- [Clerk Docs](https://clerk.com/docs) — framework-specific examples
+
+---
+
+### Tier 2 — High Impact, Higher Effort
+
+---
+
+#### 6. Interactive Quickstart / Onboarding Flows
+
+**Who does it:** Stripe, Clerk, Vercel
+
+**What it is:**
+Step-by-step getting-started guides with:
+- Framework/stack selection upfront (Next.js, Express, Remix, Fastify, etc.)
+- Progress indicators showing completion
+- Checkboxes for completed steps
+- Code examples that adapt dynamically to the selected stack
+- A "copy your connection string" flow integrated with the platform
+
+**Why it matters:**
+- First-time experience is the single most critical moment in the developer journey.
+- Prisma serves many frameworks — letting users pick their stack once and seeing all content adapt is a huge DX improvement.
+- Reduces the "where do I start?" overwhelm that large docs sites often create.
+- Clerk's framework-specific quickstarts are frequently praised as best-in-class for this pattern.
+
+**Implementation approach:**
+- Custom MDX component or page template for quickstart flows.
+- Framework selector stored in cookie/localStorage (pairs with the global language switcher).
+- Content variants per framework in frontmatter or separate MDX files.
+- Progress state stored in localStorage for returning users.
+
+**Effort:** High
+**Priority:** Ambitious phase.
+
+**Reference sites:**
+- [Clerk Docs](https://clerk.com/docs) — framework quickstarts
+- [Stripe Docs](https://stripe.com/docs) — guided onboarding
+- [Vercel Docs](https://vercel.com/docs) — framework-aware getting started
+
+---
+
+#### 7. Changelog Page
+
+**Who does it:** Linear (visual benchmark), Stripe, Vercel, Clerk
+
+**What it is:**
+A dedicated, beautifully designed changelog page showing releases, new features, deprecations, and breaking changes. With filtering by:
+- Product (ORM, Accelerate, Pulse, Optimize)
+- Content type (feature, fix, breaking change, deprecation)
+- Date range
+
+**Why it matters:**
+- Keeps users informed about what's new without requiring them to follow GitHub releases.
+- Builds trust and transparency about the pace of development.
+- Doubles as marketing content — shareable, linkable updates.
+- Linear's changelog is the gold standard for visual quality and is frequently cited as inspiration.
+
+**Implementation approach:**
+- New page/section in the docs with a custom layout.
+- Content could be:
+  - Manually authored MDX entries (highest quality).
+  - Pulled from GitHub releases via API (automated but less polished).
+  - A hybrid: auto-pull releases with manual editorial pass.
+- RSS feed for the changelog specifically.
+- Filter UI with product and type toggles.
+
+**Effort:** Medium
+**Priority:** Next phase.
+
+**Reference sites:**
+- [Linear Changelog](https://linear.app/changelog) — visual storytelling, the gold standard
+- [Clerk Changelog](https://clerk.com/changelog) — clean, filterable
+- [Vercel Changelog](https://vercel.com/changelog) — product-categorized
+
+---
+
+#### 8. Personalized API Keys / Connection Strings in Examples
+
+**Who does it:** Stripe, ReadMe, Supabase, Clerk
+
+**What it is:**
+When a logged-in user views the docs, their actual Prisma Accelerate API key or database connection string is auto-populated in code examples. Eliminates the copy-paste-replace-placeholder workflow entirely.
+
+**Why it matters:**
+- This is the #1 friction reducer in Stripe's docs and is frequently cited as the feature that makes their docs best-in-class.
+- For Prisma, this would mean showing actual `DATABASE_URL` values, Accelerate API keys, or project IDs in getting-started guides.
+- Eliminates an entire class of "it doesn't work" support requests caused by users forgetting to replace placeholder values.
+
+**Implementation approach:**
+- Requires authentication integration with Prisma's platform/dashboard.
+- Code blocks need a placeholder syntax (e.g., `{{API_KEY}}`) that gets replaced client-side when the user is authenticated.
+- Unauthenticated users see the placeholder with a "Log in to see your API key" prompt.
+- Security consideration: keys should only be shown, never logged or cached.
+
+**Effort:** High (requires cross-team coordination with platform/auth)
+**Priority:** Ambitious phase.
+
+**Reference sites:**
+- [Stripe Docs](https://stripe.com/docs) — the original and best implementation
+- [Supabase Docs](https://supabase.com/docs) — project-specific keys in examples
+- [ReadMe](https://readme.com) — personalized API keys as a core feature
+
+---
+
+### Tier 3 — Differentiators & Nice-to-Haves
+
+---
+
+#### 9. Live Code Playground / Sandbox
+
+**Who does it:** Tailwind CSS, Docusaurus (react-live)
+
+**What it is:**
+Embedded code editors (via Sandpack, StackBlitz, or WebContainers) where users can write Prisma schema, see generated types, and run queries against a demo database — all in the browser.
+
+**Why it matters:**
+- "Try before you install" is a powerful acquisition tool for developer tools.
+- A Prisma Playground embedded in the docs would be a strong differentiator — very few ORMs offer this.
+- Could be scoped initially to just schema editing + type preview (no database needed).
+
+**Effort:** Very High (needs backend infrastructure for query execution, or scoped to client-side-only schema features)
+**Priority:** Ambitious phase — consider a standalone project.
+
+---
+
+#### 10. Learning Paths with Progress Tracking
+
+**Who does it:** Very few (emerging pattern)
+
+**What it is:**
+Curated sequences like "Prisma Beginner Path" → "Data Modeling" → "Querying" → "Migrations" → "Deployment." Track progress for authenticated users with completion indicators.
+
+**Why it matters:**
+- Differentiator — almost no one does this well yet in the developer tools space.
+- Would make Prisma docs feel like a structured course rather than a reference manual.
+- Particularly valuable for Prisma's target audience, which includes developers new to ORMs.
+
+**Effort:** High (needs auth + progress persistence)
+**Priority:** Ambitious phase.
+
+---
+
+#### 11. Troubleshooting Decision Trees
+
+**Who does it:** Custom implementations only
+
+**What it is:**
+Interactive "My query is slow → Are you using indexes? → Yes/No → ..." flows for common Prisma issues. Covers scenarios like:
+- Connection pooling problems
+- Migration failures
+- Query performance issues
+- Type generation errors
+
+**Why it matters:**
+- Common Prisma support questions could be self-served through guided troubleshooting rather than searching through docs or asking in Discord.
+- Reduces support burden and improves user satisfaction.
+
+**Effort:** Medium (custom MDX component + content authoring per decision tree)
+**Priority:** Ambitious phase.
+
+---
+
+#### 12. Status Page Integration
+
+**Who does it:** Various (via BetterStack, Instatus, etc.)
+
+**What it is:**
+Embed a live status indicator for Prisma Accelerate / Pulse / Optimize in the docs header or a dedicated banner. Developers can quickly see if an issue is on their end or Prisma's.
+
+**Why it matters:**
+- Reduces support burden — users check status before filing tickets.
+- Builds trust through transparency.
+- Simple visual cue: green dot = all systems operational.
+
+**Implementation approach:**
+- Small banner component or header indicator.
+- Pulls status from Prisma's status page API (if one exists) or a BetterStack/Instatus endpoint.
+- Shows a summary status with a link to the full status page.
+- Can include an optional "Subscribe to updates" link.
+
+**Effort:** Low
+**Priority:** Start here — quick win.
+
+---
+
+#### 13. Multi-Modal Content (Video, Animations)
+
+**Who does it:** Linear (changelog), Vercel
+
+**What it is:**
+Embedded short videos, animated diagrams (e.g., how connection pooling works, how Prisma Accelerate routes queries), and Rive/Lottie animations for complex concepts.
+
+**Why it matters:**
+- Some concepts (data flow, query execution, connection pooling architecture) are much clearer with animation than static text or diagrams.
+- Video walkthroughs for complex setup procedures reduce friction.
+- Animated changelogs (like Linear's) create shareable, engaging content.
+
+**Effort:** Medium per piece (content creation is the bottleneck, not engineering)
+**Priority:** Ongoing — add as content is created.
+
+---
+
+## Recommended Priority Order
+
+### Phase 1: Quick Wins (1–2 weeks each)
+
+| # | Feature | Effort | Impact |
+|---|---------|--------|--------|
+| 1 | "Was this helpful?" feedback widget | Low | High — direct content quality signal |
+| 2 | Failed search analytics | Low | High — identifies missing content |
+| 3 | Enable API Playground | Low–Med | High — infrastructure already exists |
+| 4 | Status page integration | Low | Medium — trust + support reduction |
+
+### Phase 2: Next Level (2–4 weeks each)
+
+| # | Feature | Effort | Impact |
+|---|---------|--------|--------|
+| 5 | Related content / "Next steps" | Medium | High — reduces bounce, aids discovery |
+| 6 | Global language switcher | Medium | High — persistent DX improvement |
+| 7 | Changelog page | Medium | Medium — trust + marketing value |
+
+### Phase 3: Ambitious (4+ weeks each)
+
+| # | Feature | Effort | Impact |
+|---|---------|--------|--------|
+| 8 | Interactive quickstart flows | High | Very High — first-time experience |
+| 9 | Personalized API keys | High | Very High — friction elimination |
+| 10 | Troubleshooting decision trees | Medium | Medium — support reduction |
+| 11 | Live code playground | Very High | High — differentiator |
+
+### Ongoing / As Resources Allow
+
+| # | Feature | Effort | Impact |
+|---|---------|--------|--------|
+| 12 | Learning paths with progress | High | Medium — differentiator |
+| 13 | Multi-modal content | Medium/piece | Medium — concept clarity |
+
+---
+
+## Reference: Best-in-Class Sites to Study
+
+| Site | URL | What to Study |
+|------|-----|---------------|
+| **Stripe** | stripe.com/docs | API explorer, personalized keys, language switcher, quickstarts, page feedback |
+| **Tailwind CSS** | tailwindcss.com/docs | Live previews, reference layout, search UX |
+| **Vercel / Next.js** | nextjs.org/docs | Framework toggle, related content, changelog |
+| **Clerk** | clerk.com/docs | Framework-specific quickstarts, clean DX, changelog |
+| **Linear** | linear.app/changelog | Changelog design, visual storytelling, animations |
+| **Supabase** | supabase.com/docs | AI integration, interactive SQL, API keys in examples |
+| **Scalar** | scalar.com | Modern OpenAPI viewer and playground |
+| **Mintlify** | mintlify.com | Feedback widgets, analytics, playground |
+| **ReadMe** | readme.com | API playground, personalized keys, analytics |
+| **Cloudflare** | developers.cloudflare.com | Page feedback, related content, search |
+
+---
+
+## Key Takeaways
+
+1. **You're already ahead of most.** The AI chat, vector search, "Use Prompt" buttons, and `llms.txt` put Prisma's docs in the top tier for AI-readiness.
+
+2. **The biggest gaps are in feedback loops.** Page-level feedback and failed search analytics are cheap to add and provide outsized value for content improvement.
+
+3. **The API Playground is low-hanging fruit.** The dependency is already installed — enabling it could be the highest-ROI single change.
+
+4. **Personalization is the next frontier.** Stripe's personalized API keys and framework-aware content are what separate "great docs" from "the best docs." This requires platform integration but is worth the investment.
+
+5. **Don't underestimate the changelog.** A well-designed changelog (Linear-quality) doubles as marketing, builds trust, and keeps users engaged with the product's evolution.