From 2f42548e26ffe6bd39957c4239eebc0664b2525f Mon Sep 17 00:00:00 2001
From: Danny Neira <16809145+dannyneira@users.noreply.github.com>
Date: Wed, 12 Aug 2026 13:51:02 -0600
Subject: [PATCH 01/10] feat(docs): add Kapa support handoff

Co-Authored-By: Warp Agent <agent@warp.dev>
---
 .env.example                              |  23 +-
 astro.config.mjs                          |  36 +-
 package-lock.json                         |  34 +-
 src/components/CustomSidebar.astro        |  12 +-
 src/components/KapaChatLauncher.css       | 403 ++++++++++++-
 src/components/KapaChatLauncher.mount.tsx |   0
 src/components/KapaChatLauncher.tsx       | 660 +++++++++++++++++++++-
 src/components/KapaLauncher.astro         |  10 +
 src/pages/api/support-handoff.ts          | 231 ++++++++
 src/styles/warp-components.css            |  12 +
 vercel.json                               |  21 +-
 11 files changed, 1366 insertions(+), 76 deletions(-)
 delete mode 100644 src/components/KapaChatLauncher.mount.tsx
 create mode 100644 src/pages/api/support-handoff.ts

diff --git a/.env.example b/.env.example
index 02af3a50d..cd78fae27 100644
--- a/.env.example
+++ b/.env.example
@@ -4,11 +4,19 @@
 # Values below are PUBLIC (they're shipped to the browser by Astro's
 # `envField`, and live behind rate limiting / allow-lists on the vendor side).
 
-# Kapa Custom Frontend integration ID for the "Ask AI" button in the header.
-# If unset, the Ask AI button is hidden and the site still runs normally.
-# Get yours at: https://app.kapa.ai/admin
+# Kapa Website Widget integration ID for the "Ask AI" button in the sidebar.
+# If unset, docs falls back to the shared widget integration ID used in preview/prod.
+# Get yours at: https://app.kapa.ai/admin (Integrations → Widget → Copy integration ID).
+# The same value is passed to the widget as `data-website-id`.
+# PUBLIC_KAPA_INTEGRATION_ID=f31c5644-dd65-4f49-9762-bf580062afa8
 PUBLIC_KAPA_INTEGRATION_ID=
 
+# Optional Kapa project ID used to build internal conversation links in
+# "Create ticket" email drafts:
+#   https://app.kapa.ai/<PROJECT_ID>/conversations/<THREAD_ID>
+# You can find this in the Kapa dashboard URL while viewing the project.
+PUBLIC_KAPA_PROJECT_ID=
+
 # RudderStack analytics — required for docs_404 event tracking and page analytics.
 # Without these, no analytics events are sent and the weekly 404 monitor will
 # report zero data. Set both in the Vercel project environment (all environments).
@@ -21,3 +29,12 @@ PUBLIC_KAPA_INTEGRATION_ID=
 #   directive in vercel.json (a mismatch silently blocks all events in the browser).
 PUBLIC_RUDDERSTACK_WRITE_KEY=
 PUBLIC_RUDDERSTACK_DATA_PLANE_URL=
+
+# Server-side handoff forwarding endpoint used by /api/support-handoff.
+# This should point at the DevX service endpoint that creates Front
+# conversations from docs chat handoff requests.
+SUPPORT_HANDOFF_ENDPOINT_URL=
+
+# Optional shared secret sent as an authorization bearer token when
+# forwarding to SUPPORT_HANDOFF_ENDPOINT_URL.
+SUPPORT_HANDOFF_SHARED_SECRET=
diff --git a/astro.config.mjs b/astro.config.mjs
index 12462c7b4..cfad50019 100644
--- a/astro.config.mjs
+++ b/astro.config.mjs
@@ -28,6 +28,11 @@ export default defineConfig({
 				access: 'public',
 				optional: true,
 			}),
+			PUBLIC_KAPA_PROJECT_ID: envField.string({
+				context: 'client',
+				access: 'public',
+				optional: true,
+			}),
 			PUBLIC_RUDDERSTACK_WRITE_KEY: envField.string({
 				context: 'client',
 				access: 'public',
@@ -43,6 +48,16 @@ export default defineConfig({
 				access: 'public',
 				optional: true,
 			}),
+			SUPPORT_HANDOFF_ENDPOINT_URL: envField.string({
+				context: 'server',
+				access: 'secret',
+				optional: true,
+			}),
+			SUPPORT_HANDOFF_SHARED_SECRET: envField.string({
+				context: 'server',
+				access: 'secret',
+				optional: true,
+			}),
 		},
 	},
 	integrations: [
@@ -61,15 +76,24 @@ export default defineConfig({
 				baseUrl: 'https://github.com/warpdotdev/docs/edit/main/',
 			},
 			lastUpdated: true,
-			// Soft-wrap long lines by default. Expressive Code defaults to
-			// `overflow-x: auto` for `<pre>`, which combined with macOS's
-			// auto-hidden scrollbars made wide lines silently truncate.
-			// `wrap: true` adds the `.wrap` class so EC's `white-space: pre-wrap`
-			// kicks in; leading indents are preserved via its `span.indent` rule.
+			// Keep long lines unwrapped so code blocks use horizontal scrolling.
+			// This aligns docs behavior with the side chat renderer and preserves
+			// exact line shape for commands and snippets.
 			expressiveCode: {
 				defaultProps: {
-					wrap: true,
+					wrap: false,
 				},
+				// IMPORTANT: Expressive Code's Vite plugin rewrites Shiki's bundled
+				// theme registry (shiki/dist/themes.mjs) and strips every theme not
+				// listed as a *string* in its `themes` config. Starlight passes its
+				// themes as objects, so the registry is emptied for the entire Vite
+				// module graph — including the Kapa side-chat island, whose runtime
+				// createHighlighter(['github-light', 'github-dark']) then throws
+				// "theme is not included in this bundle" and falls back to plaintext.
+				// Keeping the registry intact restores chat code block highlighting.
+				// Only the requested themes are ever fetched at runtime (lazy chunks),
+				// so this does not bloat the pages served to visitors.
+				removeUnusedThemes: false,
 				// Map languages Shiki doesn't bundle to a safe fallback. PromQL
 				// blocks live in platform/self-hosting/monitoring.mdx;
 				// without this alias every build emits noisy "language could not be
diff --git a/package-lock.json b/package-lock.json
index fc8163d9c..91002c48f 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -2713,14 +2713,14 @@
       }
     },
     "node_modules/@kapaai/react-sdk": {
-      "version": "0.9.2",
-      "resolved": "https://registry.npmjs.org/@kapaai/react-sdk/-/react-sdk-0.9.2.tgz",
-      "integrity": "sha512-PeqgKL6d0yIkkmPn+1O8TBjH7KGx5HNiH7fhGl0FEV2MfJZBzWNvAOdOm/34VLdpb2Nawe3H1gSURdJ0DG6z7Q==",
+      "version": "0.9.10",
+      "resolved": "https://registry.npmjs.org/@kapaai/react-sdk/-/react-sdk-0.9.10.tgz",
+      "integrity": "sha512-osQyFgBJmhNM207MpB0aZbjs2kjNHjEJbNc5YEReJuyFE72Iydn9CoZGxox2GYRgMIlQ7wljHCzgQqkvR8lXqA==",
       "license": "MIT",
       "dependencies": {
         "@fingerprintjs/fingerprintjs-pro-react": "^2.7.0",
+        "@fingerprintjs/fingerprintjs-pro-spa": "^1.3.0",
         "@hcaptcha/react-hcaptcha": "^1.12.0",
-        "@tanstack/react-query": "^5.74.3",
         "js-cookie": "^3.0.5",
         "tldts": "^7.0.7"
       },
@@ -3778,32 +3778,6 @@
       "integrity": "sha512-83yeghZ2xxin3Nj8z1NMd/NCuca+gsYXswywDy5bHvwlWL8tpTQmzGeUuHd9FC3E/SBEMvzJRwWEOz5gGes9Qg==",
       "license": "MIT"
     },
-    "node_modules/@tanstack/query-core": {
-      "version": "5.90.20",
-      "resolved": "https://registry.npmjs.org/@tanstack/query-core/-/query-core-5.90.20.tgz",
-      "integrity": "sha512-OMD2HLpNouXEfZJWcKeVKUgQ5n+n3A2JFmBaScpNDUqSrQSjiveC7dKMe53uJUg1nDG16ttFPz2xfilz6i2uVg==",
-      "license": "MIT",
-      "funding": {
-        "type": "github",
-        "url": "https://github.com/sponsors/tannerlinsley"
-      }
-    },
-    "node_modules/@tanstack/react-query": {
-      "version": "5.90.21",
-      "resolved": "https://registry.npmjs.org/@tanstack/react-query/-/react-query-5.90.21.tgz",
-      "integrity": "sha512-0Lu6y5t+tvlTJMTO7oh5NSpJfpg/5D41LlThfepTixPYkJ0sE2Jj0m0f6yYqujBwIXlId87e234+MxG3D3g7kg==",
-      "license": "MIT",
-      "dependencies": {
-        "@tanstack/query-core": "5.90.20"
-      },
-      "funding": {
-        "type": "github",
-        "url": "https://github.com/sponsors/tannerlinsley"
-      },
-      "peerDependencies": {
-        "react": "^18 || ^19"
-      }
-    },
     "node_modules/@tybys/wasm-util": {
       "version": "0.10.3",
       "resolved": "https://registry.npmjs.org/@tybys/wasm-util/-/wasm-util-0.10.3.tgz",
diff --git a/src/components/CustomSidebar.astro b/src/components/CustomSidebar.astro
index 6ab218ca8..954f822f7 100644
--- a/src/components/CustomSidebar.astro
+++ b/src/components/CustomSidebar.astro
@@ -77,9 +77,9 @@ import KapaLauncher from './KapaLauncher.astro';
 			'api': 'API',
 		};
 
-		// Detect Apple platforms once so the Ask AI kbd reads ⌘+I on Macs and
-		// Ctrl+I elsewhere. Mirrors KapaChatLauncher.tsx which binds the same
-		// shortcut via keymatch's `CmdOrCtrl+I`.
+// Detect Apple platforms once so the Ask AI kbd reads ⌘+I on Macs and
+		// Ctrl+I elsewhere. Mirrors KapaLauncher.astro which binds the same
+		// shortcut for opening the Kapa Website Widget.
 		var isMac = /(Mac|iPhone|iPod|iPad)/i.test(navigator.platform || '');
 		var modKey = isMac ? '\u2318' : 'Ctrl';
 
@@ -143,9 +143,9 @@ import KapaLauncher from './KapaLauncher.astro';
 				+ '</svg>'
 				+ '<span class="warp-search-ask-ai-row__label">Ask AI</span>'
 				+ '<kbd class="warp-search-ask-ai-row__kbd" aria-hidden="true">' + modKey + '<span class="warp-search-ask-ai-row__kbd-plus">+</span>I</kbd>';
-			askAi.addEventListener('click', function () {
-				// openPanel() in KapaChatLauncher reads the live search input and
-				// closes the search dialog itself, so we just route the click.
+askAi.addEventListener('click', function () {
+				// KapaLauncher reads the live search input and closes the search
+				// dialog itself, then opens the widget with that query prefilled.
 				var kapaBtn = document.querySelector('.warp-kapa-button');
 				if (kapaBtn) kapaBtn.click();
 			});
diff --git a/src/components/KapaChatLauncher.css b/src/components/KapaChatLauncher.css
index 3aca6dc6c..d810c5b08 100644
--- a/src/components/KapaChatLauncher.css
+++ b/src/components/KapaChatLauncher.css
@@ -200,6 +200,126 @@
 	padding: 0.1rem 0.3rem;
 }
 
+.sl-kapa-codeblock {
+	position: relative;
+	margin: 0.85rem 0;
+	max-width: 100%;
+}
+
+/* Chat-only copy control. Deliberately avoids EC's `.copy` class so EC CSS
+   (`button::after` mask) and EC JS never attach a second icon/handler. Visual
+   tokens match docs frosted-glass copy buttons in warp-components.css §2. */
+.sl-kapa-codeblock__copy-wrap {
+	position: absolute;
+	inset-block-start: 0.5rem;
+	inset-inline-end: 0.5rem;
+	z-index: 2;
+	display: flex;
+	align-items: center;
+	gap: 0.25rem;
+	pointer-events: none;
+}
+
+.sl-kapa-codeblock__copy {
+	pointer-events: auto;
+	position: relative;
+	box-sizing: border-box;
+	width: 2rem;
+	height: 2rem;
+	margin: 0;
+	padding: 0;
+	border-radius: var(--sl-radius-sm);
+	border: 1px solid rgba(255, 255, 255, 0.1);
+	background: rgba(255, 255, 255, 0.08);
+	backdrop-filter: blur(8px);
+	cursor: pointer;
+	opacity: 0.4;
+	transition:
+		opacity 0.15s ease,
+		background-color 0.15s ease,
+		border-color 0.15s ease;
+}
+
+.sl-kapa-codeblock:hover .sl-kapa-codeblock__copy,
+.sl-kapa-codeblock:focus-within .sl-kapa-codeblock__copy {
+	opacity: 0.75;
+}
+
+.sl-kapa-codeblock__copy:hover,
+.sl-kapa-codeblock__copy:focus-visible {
+	opacity: 1;
+	background: rgba(255, 255, 255, 0.16);
+	border-color: rgba(255, 255, 255, 0.18);
+}
+
+.sl-kapa-codeblock__copy:focus-visible {
+	outline: 2px solid var(--sl-color-accent-high);
+	outline-offset: 2px;
+}
+
+.sl-kapa-codeblock__copy-icon {
+	position: absolute;
+	inset: 0.475rem;
+	background-color: var(--sl-color-white, #f9f8f6);
+	-webkit-mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='1.75'%3E%3Cpath d='M3 19a2 2 0 0 1-1-2V2a2 2 0 0 1 1-1h13a2 2 0 0 1 2 1'/%3E%3Crect x='6' y='5' width='16' height='18' rx='1.5' ry='1.5'/%3E%3C/svg%3E");
+	mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='1.75'%3E%3Cpath d='M3 19a2 2 0 0 1-1-2V2a2 2 0 0 1 1-1h13a2 2 0 0 1 2 1'/%3E%3Crect x='6' y='5' width='16' height='18' rx='1.5' ry='1.5'/%3E%3C/svg%3E");
+	-webkit-mask-repeat: no-repeat;
+	mask-repeat: no-repeat;
+	-webkit-mask-position: center;
+	mask-position: center;
+	-webkit-mask-size: contain;
+	mask-size: contain;
+}
+
+.sl-kapa-codeblock__copy-feedback {
+	pointer-events: none;
+	user-select: none;
+	font-size: var(--sl-text-2xs);
+	line-height: 1.2;
+	padding: 0.2rem 0.4rem;
+	border-radius: var(--sl-radius-sm);
+	background: color-mix(in srgb, var(--sl-color-accent) 85%, black);
+	color: var(--sl-color-white);
+	white-space: nowrap;
+}
+
+:root[data-theme='light'] .sl-kapa-codeblock__copy {
+	background: rgba(0, 0, 0, 0.04);
+	border: 1px solid rgba(0, 0, 0, 0.08);
+	opacity: 0.6;
+}
+
+:root[data-theme='light'] .sl-kapa-codeblock__copy:hover,
+:root[data-theme='light'] .sl-kapa-codeblock__copy:focus-visible {
+	background: rgba(0, 0, 0, 0.08);
+	border-color: rgba(0, 0, 0, 0.12);
+	opacity: 1;
+}
+
+:root[data-theme='light'] .sl-kapa-codeblock__copy-icon {
+	background-color: var(--sl-color-white, #0a0d12);
+}
+
+.sl-kapa-codeblock pre {
+	margin: 0;
+	padding: var(--ec-codePadBlk) var(--ec-codePadInl);
+	overflow-x: auto;
+	overflow-y: hidden;
+	white-space: pre;
+}
+
+.sl-kapa-codeblock code {
+	font-family: var(--__sl-font-mono, 'JetBrains Mono', 'SFMono-Regular', monospace);
+	display: block;
+	min-width: max-content;
+}
+
+/* Shiki separates `.line` spans with literal newline characters, which
+   `white-space: pre` (set on the pre above) already renders as line
+   breaks. The spans must stay inline — giving them `display: block`
+   would add a second break per line and double-space the code. */
+
+
 .sl-kapa-thinking {
 	display: flex;
 	align-items: center;
@@ -249,18 +369,73 @@
 
 .sl-kapa-feedback {
 	display: flex;
+	flex-wrap: wrap;
+	align-items: center;
 	gap: 0.5rem;
 	margin-top: 0.875rem;
 }
+.sl-kapa-feedback__handoff {
+	display: inline-flex;
+	align-items: center;
+	justify-content: center;
+	height: 2.25rem;
+	padding: 0 0.75rem;
+	border: 1px solid var(--sl-color-gray-5);
+	border-radius: var(--sl-radius-sm);
+	background: var(--sl-color-black);
+	color: var(--sl-color-gray-1);
+	font: inherit;
+	font-size: var(--sl-text-xs);
+	font-weight: 500;
+	cursor: pointer;
+	transition:
+		border-color 0.15s ease,
+		background-color 0.15s ease,
+		color 0.15s ease;
+}
+
+.sl-kapa-feedback__handoff:hover {
+	border-color: var(--warp-control-border-hover);
+	background: var(--warp-control-bg-hover);
+	color: var(--sl-color-white);
+}
+
+.sl-kapa-feedback__handoff:focus-visible {
+	outline: 2px solid var(--sl-color-accent-high);
+	outline-offset: 2px;
+}
+.sl-kapa-feedback__handoff--submit {
+	background: var(--sl-color-text-accent);
+	border-color: var(--sl-color-text-accent);
+	color: var(--sl-color-black);
+}
+
+.sl-kapa-feedback__handoff--submit:hover:not(:disabled) {
+	border-color: color-mix(in srgb, var(--sl-color-text-accent), var(--sl-color-white) 18%);
+	background: color-mix(in srgb, var(--sl-color-text-accent), var(--sl-color-white) 8%);
+	color: var(--sl-color-black);
+}
+
+.sl-kapa-feedback__handoff--ghost {
+	background: transparent;
+}
 
 .sl-kapa-error {
-	border: 1px solid color-mix(in srgb, #ef4444, var(--sl-color-black) 35%);
-	background: rgb(127 29 29 / 0.2);
-	color: #fecaca;
+	border: 1px solid rgb(248 113 113 / 0.8);
+	background: rgb(254 226 226 / 0.9);
+	color: #991b1b;
 	border-radius: var(--sl-radius-lg);
 	padding: 0.875rem 1rem;
 }
 
+@media (prefers-color-scheme: dark) {
+	.sl-kapa-error {
+		border: 1px solid color-mix(in srgb, #ef4444, var(--sl-color-black) 35%);
+		background: rgb(127 29 29 / 0.2);
+		color: #fecaca;
+	}
+}
+
 .sl-kapa-panel__footer {
 	position: relative;
 	padding: 1rem;
@@ -337,6 +512,228 @@
 	opacity: 0.5;
 	cursor: not-allowed;
 }
+.sl-kapa-handoff-inline {
+	margin-top: 0.75rem;
+	padding-top: 0.75rem;
+	border-top: 1px solid var(--sl-color-gray-5);
+	display: flex;
+	flex-direction: column;
+	gap: 0.5rem;
+}
+
+.sl-kapa-handoff-inline label {
+	font-size: var(--sl-text-xs);
+	font-weight: 600;
+	color: var(--sl-color-gray-2);
+}
+
+.sl-kapa-handoff-inline__row {
+	display: grid;
+	grid-template-columns: minmax(0, 1fr) auto auto;
+	gap: 0.5rem;
+}
+
+.sl-kapa-handoff-inline input {
+	width: 100%;
+	min-width: 0;
+	height: 2.25rem;
+	border: 1px solid var(--sl-color-gray-5);
+	border-radius: var(--sl-radius-sm);
+	background: var(--sl-color-black);
+	color: var(--sl-color-white);
+	padding: 0 0.625rem;
+	font: inherit;
+	font-size: var(--sl-text-sm);
+}
+
+.sl-kapa-handoff-inline input::placeholder {
+	color: var(--sl-color-gray-3);
+}
+
+.sl-kapa-handoff-inline input:focus-visible {
+	outline: 2px solid var(--sl-color-accent-high);
+	outline-offset: 2px;
+}
+
+.sl-kapa-handoff-inline__status {
+	margin: 0;
+	font-size: var(--sl-text-xs);
+	line-height: 1.4;
+}
+
+.sl-kapa-handoff-inline__status--success {
+	color: #14532d;
+	background: rgb(220 252 231 / 0.9);
+	border: 1px solid rgb(74 222 128 / 0.7);
+	padding: 0.375rem 0.5rem;
+	border-radius: var(--sl-radius-sm);
+}
+
+.sl-kapa-handoff-inline__status--error {
+	color: #b91c1c;
+	background: rgb(254 226 226 / 0.9);
+	border: 1px solid rgb(248 113 113 / 0.8);
+	padding: 0.375rem 0.5rem;
+	border-radius: var(--sl-radius-sm);
+}
+
+.sl-kapa-handoff-inline__status a {
+	color: inherit;
+	text-decoration: underline;
+}
+
+@media (prefers-color-scheme: dark) {
+	.sl-kapa-handoff-inline__status--success {
+		color: #86efac;
+		background: rgb(20 83 45 / 0.35);
+		border-color: rgb(74 222 128 / 0.45);
+	}
+	.sl-kapa-handoff-inline__status--error {
+		color: #fecaca;
+		background: rgb(127 29 29 / 0.3);
+		border-color: rgb(248 113 113 / 0.5);
+	}
+}
+
+.sl-kapa-handoff {
+	margin-top: 0.75rem;
+	display: flex;
+	flex-direction: column;
+	gap: 0.625rem;
+}
+
+.sl-kapa-handoff__toggle {
+	display: inline-flex;
+	align-items: center;
+	justify-content: center;
+	gap: 0.5rem;
+	width: 100%;
+	height: 2.5rem;
+	padding: 0 0.875rem;
+	border: 1px solid var(--sl-color-gray-5);
+	border-radius: var(--sl-radius-sm);
+	background: var(--sl-color-black);
+	color: var(--sl-color-gray-1);
+	font: inherit;
+	font-size: var(--sl-text-sm);
+	font-weight: 500;
+	cursor: pointer;
+	transition:
+		border-color 0.15s ease,
+		background-color 0.15s ease,
+		color 0.15s ease;
+}
+
+.sl-kapa-handoff__toggle svg {
+	width: 0.95rem;
+	height: 0.95rem;
+	flex: none;
+}
+
+.sl-kapa-handoff__toggle:hover {
+	border-color: var(--warp-control-border-hover);
+	background: var(--warp-control-bg-hover);
+	color: var(--sl-color-white);
+}
+
+.sl-kapa-handoff__toggle:focus-visible {
+	outline: 2px solid var(--sl-color-accent-high);
+	outline-offset: 2px;
+}
+
+.sl-kapa-handoff__form {
+	display: flex;
+	flex-direction: column;
+	gap: 0.5rem;
+	padding: 0.75rem;
+	border: 1px solid var(--sl-color-gray-5);
+	border-radius: var(--sl-radius-lg);
+	background: color-mix(in srgb, var(--sl-color-black), var(--sl-color-gray-6) 28%);
+}
+
+.sl-kapa-handoff__form label {
+	display: flex;
+	flex-direction: column;
+	gap: 0.25rem;
+}
+
+.sl-kapa-handoff__form label span {
+	font-size: var(--sl-text-2xs);
+	color: var(--sl-color-gray-3);
+}
+
+.sl-kapa-handoff__form input,
+.sl-kapa-handoff__form textarea {
+	width: 100%;
+	border: 1px solid var(--sl-color-gray-5);
+	border-radius: var(--sl-radius-sm);
+	background: var(--sl-color-black);
+	color: var(--sl-color-white);
+	padding: 0.5rem 0.625rem;
+	font: inherit;
+	font-size: var(--sl-text-sm);
+}
+
+.sl-kapa-handoff__form textarea {
+	resize: vertical;
+	min-height: 4rem;
+}
+
+.sl-kapa-handoff__form input::placeholder,
+.sl-kapa-handoff__form textarea::placeholder {
+	color: var(--sl-color-gray-3);
+}
+
+.sl-kapa-handoff__form input:focus-visible,
+.sl-kapa-handoff__form textarea:focus-visible {
+	outline: 2px solid var(--sl-color-accent-high);
+	outline-offset: 2px;
+}
+
+.sl-kapa-handoff__submit {
+	margin-top: 0.25rem;
+	height: 2.5rem;
+	border: 1px solid var(--sl-color-text-accent);
+	border-radius: var(--sl-radius-sm);
+	background: var(--sl-color-text-accent);
+	color: var(--sl-color-black);
+	font: inherit;
+	font-size: var(--sl-text-sm);
+	font-weight: 600;
+	cursor: pointer;
+	transition:
+		border-color 0.15s ease,
+		background-color 0.15s ease;
+}
+
+.sl-kapa-handoff__submit:hover:not(:disabled) {
+	border-color: color-mix(in srgb, var(--sl-color-text-accent), var(--sl-color-white) 18%);
+	background: color-mix(in srgb, var(--sl-color-text-accent), var(--sl-color-white) 8%);
+}
+
+.sl-kapa-handoff__submit:focus-visible {
+	outline: 2px solid var(--sl-color-accent-high);
+	outline-offset: 2px;
+}
+
+.sl-kapa-handoff__submit:disabled {
+	opacity: 0.55;
+	cursor: not-allowed;
+}
+
+.sl-kapa-handoff__status {
+	margin: 0;
+	font-size: var(--sl-text-xs);
+	line-height: 1.4;
+}
+
+.sl-kapa-handoff__status--success {
+	color: #86efac;
+}
+
+.sl-kapa-handoff__status--error {
+	color: #fecaca;
+}
 
 /* Hide the reCAPTCHA badge */
 .grecaptcha-badge {
diff --git a/src/components/KapaChatLauncher.mount.tsx b/src/components/KapaChatLauncher.mount.tsx
deleted file mode 100644
index e69de29bb..000000000
diff --git a/src/components/KapaChatLauncher.tsx b/src/components/KapaChatLauncher.tsx
index d4e1bcb9b..dcc0b2e55 100644
--- a/src/components/KapaChatLauncher.tsx
+++ b/src/components/KapaChatLauncher.tsx
@@ -1,8 +1,8 @@
-import type { FormEvent, MouseEvent } from 'react';
+import type { FormEvent, MouseEvent, ReactElement, ReactNode } from 'react';
 import * as Popover from '@radix-ui/react-popover';
-import { useEffect, useMemo, useRef, useState } from 'react';
-import { KapaProvider, useChat } from '@kapaai/react-sdk';
-import { PUBLIC_KAPA_INTEGRATION_ID } from 'astro:env/client';
+import { isValidElement, useEffect, useMemo, useRef, useState } from 'react';
+import { CaptchaAction, KapaProvider, useCaptcha, useChat } from '@kapaai/react-sdk';
+import { PUBLIC_KAPA_INTEGRATION_ID, PUBLIC_KAPA_PROJECT_ID } from 'astro:env/client';
 import { isMac, keymatch } from 'keymatch';
 import ReactMarkdown from 'react-markdown';
 import {
@@ -18,10 +18,395 @@ import {
 import './KapaChatLauncher.css';
 
 const integrationId = PUBLIC_KAPA_INTEGRATION_ID;
+const projectId = PUBLIC_KAPA_PROJECT_ID?.trim() || '';
 const title = 'Ask Warp';
 const welcomeMessage = 'What do you want to know about Warp?';
+const uncertaintyThreshold = 0.15;
+const conversationLengthThreshold = 3;
+const emailPattern = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
 
 type FeedbackReaction = 'upvote' | 'downvote';
+type GenericRecord = Record<string, unknown>;
+type HandoffApiSuccess = {
+	message?: string;
+};
+
+function isObject(value: unknown): value is GenericRecord {
+	return typeof value === 'object' && value !== null;
+}
+
+function readNumberField(record: GenericRecord, key: string) {
+	const value = record[key];
+	if (typeof value === 'number' && Number.isFinite(value)) return value;
+	if (typeof value === 'string') {
+		const parsed = Number(value);
+		if (Number.isFinite(parsed)) return parsed;
+	}
+	return null;
+}
+
+function readBooleanField(record: GenericRecord, key: string) {
+	const value = record[key];
+	if (typeof value === 'boolean') return value;
+	if (typeof value === 'string') {
+		const normalized = value.trim().toLowerCase();
+		if (normalized === 'true') return true;
+		if (normalized === 'false') return false;
+	}
+	return null;
+}
+
+function getUncertaintyScore(metadata: unknown) {
+	if (!isObject(metadata)) return null;
+	return (
+		readNumberField(metadata, 'uncertainty') ??
+		readNumberField(metadata, 'uncertainty_score') ??
+		readNumberField(metadata, 'uncertaintyScore')
+	);
+}
+
+function isAnswerUncertain(metadata: unknown) {
+	if (!isObject(metadata)) return false;
+	const flag =
+		readBooleanField(metadata, 'is_uncertain') ??
+		readBooleanField(metadata, 'isUncertain');
+	if (flag === true) return true;
+	const score = getUncertaintyScore(metadata);
+	return score !== null ? score >= uncertaintyThreshold : false;
+}
+
+function isValidEmailAddress(value: string) {
+	return emailPattern.test(value.trim());
+}
+function getChatErrorMessage(error: unknown) {
+	const message = typeof error === 'string' ? error : String(error ?? '');
+	const normalized = message.toLowerCase();
+	const looksLikeBlockedNetworkError =
+		normalized.includes('network error while fetching answer') ||
+		normalized.includes('failed to fetch') ||
+		normalized.includes('err_blocked_by_client');
+	if (looksLikeBlockedNetworkError) {
+		return "Couldn't reach the chat service. If you use an ad blocker or privacy extension, allow kapa.ai and proxy.kapa.ai, then try again.";
+	}
+	return message;
+}
+
+const CHAT_LANGUAGE_ALIASES: Record<string, string> = {
+	shell: 'bash',
+	zsh: 'bash',
+	pwsh: 'powershell',
+	plaintext: 'text',
+};
+
+function normalizeChatLanguage(language: string): string {
+	return CHAT_LANGUAGE_ALIASES[language.toLowerCase()] ?? language.toLowerCase();
+}
+
+function inferLanguageFromCode(codeText: string, fallbackLanguage: string): string {
+	if (fallbackLanguage !== 'text') return fallbackLanguage;
+	const sample = codeText.trim();
+	if (!sample) return fallbackLanguage;
+	const commandLikePattern =
+		/^(sudo|apt|apt-get|dnf|yum|zypper|pacman|curl|wget|git|npm|pnpm|yarn|cargo|python|node|brew|sh|bash)\b/m;
+	if (commandLikePattern.test(sample)) return 'bash';
+	return fallbackLanguage;
+}
+
+function escapeHtml(value: string): string {
+	return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+async function copyTextToClipboard(text: string): Promise<boolean> {
+	try {
+		if (navigator.clipboard?.writeText) {
+			await navigator.clipboard.writeText(text);
+			return true;
+		}
+	} catch {
+		// Fall through to execCommand fallback.
+	}
+	try {
+		const pre = document.createElement('pre');
+		Object.assign(pre.style, {
+			opacity: '0',
+			pointerEvents: 'none',
+			position: 'absolute',
+			overflow: 'hidden',
+			left: '0',
+			top: '0',
+			width: '20px',
+			height: '20px',
+			webkitUserSelect: 'auto',
+			userSelect: 'all',
+		});
+		pre.setAttribute('aria-hidden', 'true');
+		pre.textContent = text;
+		document.body.appendChild(pre);
+		const range = document.createRange();
+		range.selectNode(pre);
+		const selection = window.getSelection();
+		if (!selection) {
+			document.body.removeChild(pre);
+			return false;
+		}
+		selection.removeAllRanges();
+		selection.addRange(range);
+		const ok = document.execCommand('copy');
+		selection.removeAllRanges();
+		document.body.removeChild(pre);
+		return ok;
+	} catch {
+		return false;
+	}
+}
+
+type MarkdownCodeProps = { className?: string; children?: ReactNode };
+
+// react-markdown v9+ no longer passes an `inline` flag to the `code`
+// component. The reliable way to tell fenced blocks apart from inline
+// code is nesting: fenced blocks are always rendered as <pre><code>, so
+// we intercept `pre` (block) and leave bare `code` (inline) untouched.
+function extractCodeElement(children: ReactNode): ReactElement<MarkdownCodeProps> | null {
+	const items = Array.isArray(children) ? children : [children];
+	for (const item of items) {
+		if (isValidElement<MarkdownCodeProps>(item)) return item;
+	}
+	return null;
+}
+
+function markdownChildrenToText(children: ReactNode): string {
+	return (Array.isArray(children) ? children.join('') : String(children ?? '')).replace(/\n$/, '');
+}
+
+const highlightCache = new Map<string, string | null>();
+const highlightInFlight = new Map<string, Promise<string | null>>();
+let highlightRequestQueue: Promise<void> = Promise.resolve();
+type ShikiModule = typeof import('shiki');
+type ShikiHighlighter = Awaited<ReturnType<ShikiModule['createHighlighter']>>;
+let shikiHighlighterPromise: Promise<ShikiHighlighter> | null = null;
+const SHIKI_LANGUAGES = new Set([
+	'bash',
+	'powershell',
+	'json',
+	'javascript',
+	'typescript',
+	'tsx',
+	'jsx',
+	'python',
+	'go',
+	'rust',
+	'yaml',
+	'markdown',
+	'html',
+	'css',
+	'text',
+]);
+
+async function getShikiHighlighter(): Promise<ShikiHighlighter> {
+	if (!shikiHighlighterPromise) {
+		shikiHighlighterPromise = import('shiki/bundle/full').then(({ createHighlighter }) =>
+			createHighlighter({
+				themes: ['github-light', 'github-dark'],
+				langs: [...SHIKI_LANGUAGES],
+			})
+		);
+	}
+	return shikiHighlighterPromise;
+}
+
+async function requestHighlightedPre({
+	code,
+	language,
+	theme,
+}: {
+	code: string;
+	language: string;
+	theme: 'dark' | 'light';
+}): Promise<string | null> {
+	const cacheKey = `${theme}:${language}:${code}`;
+	if (highlightCache.has(cacheKey)) {
+		return highlightCache.get(cacheKey) ?? null;
+	}
+	const existing = highlightInFlight.get(cacheKey);
+	if (existing) return existing;
+
+	const requestPromise = new Promise<string | null>((resolve, reject) => {
+		const run = async () => {
+			try {
+				const highlighter = await getShikiHighlighter();
+				const shikiLanguage = SHIKI_LANGUAGES.has(language) ? language : 'text';
+				const html = highlighter.codeToHtml(code, {
+					lang: shikiLanguage,
+					theme: theme === 'light' ? 'github-light' : 'github-dark',
+				});
+				const preMatch = html.match(/<pre[^>]*>[\s\S]*?<\/pre>/i);
+				const preHtml = preMatch?.[0] ?? null;
+				highlightCache.set(cacheKey, preHtml);
+				resolve(preHtml);
+			} catch (error) {
+				reject(error);
+			}
+		};
+
+		highlightRequestQueue = highlightRequestQueue
+			.then(run)
+			.catch(() => run())
+			.then(() => undefined, () => undefined);
+	});
+
+	highlightInFlight.set(cacheKey, requestPromise);
+	requestPromise.then(
+		() => {
+			highlightInFlight.delete(cacheKey);
+		},
+		() => {
+			highlightInFlight.delete(cacheKey);
+		}
+	);
+	return requestPromise;
+}
+
+function ChatCodeBlock({
+	className,
+	codeText,
+	deferHighlight,
+}: {
+	className?: string;
+	codeText: string;
+	deferHighlight?: boolean;
+}) {
+	const language = className?.replace('language-', '') ?? 'text';
+	const normalizedLanguage = inferLanguageFromCode(
+		codeText,
+		normalizeChatLanguage(language)
+	);
+	const isTerminalLanguage = ['bash', 'sh', 'shell', 'zsh', 'powershell'].includes(normalizedLanguage);
+	const [highlighted, setHighlighted] = useState<{ key: string; preHtml: string } | null>(null);
+	const [isDarkTheme, setIsDarkTheme] = useState(true);
+	const [isCopied, setIsCopied] = useState(false);
+	const copiedResetRef = useRef<number | null>(null);
+
+	useEffect(() => {
+		const root = document.documentElement;
+		const updateTheme = () => {
+			const explicitTheme = root.dataset.theme;
+			if (explicitTheme === 'light') {
+				setIsDarkTheme(false);
+				return;
+			}
+			if (explicitTheme === 'dark') {
+				setIsDarkTheme(true);
+				return;
+			}
+			setIsDarkTheme(window.matchMedia('(prefers-color-scheme: dark)').matches);
+		};
+
+		updateTheme();
+		const observer = new MutationObserver(updateTheme);
+		observer.observe(root, { attributes: true, attributeFilter: ['data-theme'] });
+		return () => observer.disconnect();
+	}, []);
+
+	useEffect(() => {
+		return () => {
+			if (copiedResetRef.current !== null) {
+				window.clearTimeout(copiedResetRef.current);
+			}
+		};
+	}, []);
+
+	const theme = isDarkTheme ? 'dark' : 'light';
+	const highlightKey = `${theme}:${normalizedLanguage}:${codeText}`;
+
+	useEffect(() => {
+		// While the answer is still streaming, the code text changes on every
+		// token. Requesting a highlight per token causes the block to churn
+		// between plaintext and highlighted DOM (visible flicker), so wait
+		// until streaming settles and highlight the final text once.
+		if (deferHighlight) return;
+		const controller = new AbortController();
+		(async (): Promise<void> => {
+			try {
+				const preHtml = await requestHighlightedPre({
+					code: codeText,
+					language: normalizedLanguage,
+					theme,
+				});
+				if (!controller.signal.aborted && preHtml) {
+					setHighlighted({ key: `${theme}:${normalizedLanguage}:${codeText}`, preHtml });
+				}
+			} catch (error) {
+				if (!controller.signal.aborted) {
+					console.warn('[kapa-chat] code highlighting failed; using plaintext fallback', error);
+				}
+			}
+		})();
+
+		return () => {
+			controller.abort();
+		};
+	}, [codeText, deferHighlight, theme, normalizedLanguage]);
+
+	// Only use highlighted HTML that matches the *current* code text and
+	// theme; otherwise render the plaintext fallback. This prevents stale
+	// highlighted content from flashing while new text is streaming in.
+	const highlightedPreHtml = highlighted?.key === highlightKey ? highlighted.preHtml : null;
+
+	const onCopy = async () => {
+		const ok = await copyTextToClipboard(codeText);
+		if (!ok) return;
+		setIsCopied(true);
+		if (copiedResetRef.current !== null) {
+			window.clearTimeout(copiedResetRef.current);
+		}
+		copiedResetRef.current = window.setTimeout(() => {
+			setIsCopied(false);
+			copiedResetRef.current = null;
+		}, 1500);
+	};
+
+	return (
+		<div className="expressive-code sl-kapa-codeblock">
+			<figure className={`frame not-content${isTerminalLanguage ? ' is-terminal' : ''}`}>
+				<figcaption className="header">
+					<span className="title" />
+					{isTerminalLanguage ? <span className="sr-only">Terminal window</span> : null}
+				</figcaption>
+				{highlightedPreHtml ? (
+					<div
+						className="sl-kapa-codeblock__shiki"
+						dangerouslySetInnerHTML={{ __html: highlightedPreHtml }}
+					/>
+				) : (
+					<pre data-language={language}>
+						<code className={className} dangerouslySetInnerHTML={{ __html: escapeHtml(codeText) }} />
+					</pre>
+				)}
+				{/* Dedicated chat copy control — intentionally NOT EC's `.copy`
+				    class. Reusing EC markup stacked EC's CSS mask icon on top of
+				    any residual SVG and produced a double clipboard. One button,
+				    one icon (CSS mask), one click handler. */}
+				<div className="sl-kapa-codeblock__copy-wrap">
+					<span className="sr-only" aria-live="polite">
+						{isCopied ? 'Copied!' : ''}
+					</span>
+					{isCopied ? <span className="sl-kapa-codeblock__copy-feedback">Copied!</span> : null}
+					<button
+						type="button"
+						className="sl-kapa-codeblock__copy"
+						onClick={() => {
+							void onCopy();
+						}}
+						title={isCopied ? 'Copied!' : 'Copy to clipboard'}
+						aria-label={isCopied ? 'Code copied' : 'Copy code block'}
+					>
+						<span className="sl-kapa-codeblock__copy-icon" aria-hidden="true" />
+					</button>
+				</div>
+			</figure>
+		</div>
+	);
+}
 
 function ChatSurface({ title, welcomeMessage, autoOpen = false, onNewConversation }: {
 	title: string;
@@ -33,6 +418,13 @@ function ChatSurface({ title, welcomeMessage, autoOpen = false, onNewConversatio
 	const [query, setQuery] = useState('');
 	const [hasStartedConversation, setHasStartedConversation] = useState(false);
 	const [isAppleDevice, setIsAppleDevice] = useState(false);
+	const [storedThreadId, setStoredThreadId] = useState<string | null>(null);
+	const [downvotedAnswerIds, setDownvotedAnswerIds] = useState<Record<string, true>>({});
+	const [handoffEmailInput, setHandoffEmailInput] = useState('');
+	const [handoffQaId, setHandoffQaId] = useState<string | null>(null);
+	const [handoffErrorMessage, setHandoffErrorMessage] = useState<string | null>(null);
+	const [handoffSuccessMessage, setHandoffSuccessMessage] = useState<string | null>(null);
+	const [isSubmittingHandoff, setIsSubmittingHandoff] = useState(false);
 	const messagesRef = useRef<HTMLDivElement | null>(null);
 	const dialogRef = useRef<HTMLDialogElement | null>(null);
 	const triggerRef = useRef<HTMLButtonElement | null>(null);
@@ -45,16 +437,55 @@ function ChatSurface({ title, welcomeMessage, autoOpen = false, onNewConversatio
 		isGeneratingAnswer,
 		isPreparingAnswer,
 		submitQuery,
+		threadId,
 	} = useChat();
+	const { executeCaptcha } = useCaptcha();
+
 	useEffect(() => {
 		setIsAppleDevice(isMac());
 	}, []);
 
+	useEffect(() => {
+		const savedThreadId = localStorage.getItem('warp_docs_kapa_thread_id');
+		if (savedThreadId) {
+			setStoredThreadId(savedThreadId);
+		}
+	}, []);
+
+	useEffect(() => {
+		if (!threadId) return;
+		setStoredThreadId(threadId);
+		localStorage.setItem('warp_docs_kapa_thread_id', threadId);
+	}, [threadId]);
+
 	useEffect(() => {
 		if (!isOpen || !messagesRef.current) return;
 		messagesRef.current.scrollTop = messagesRef.current.scrollHeight;
 	}, [conversation.length, isOpen]);
 
+	useEffect(() => {
+		if (!isOpen || !messagesRef.current) return;
+		if (!isGeneratingAnswer && !isPreparingAnswer) return;
+		messagesRef.current.scrollTop = messagesRef.current.scrollHeight;
+	}, [conversation, isGeneratingAnswer, isOpen, isPreparingAnswer]);
+
+	useEffect(() => {
+		if (!handoffQaId || !isOpen) return;
+		const frame = window.requestAnimationFrame(() => {
+			const inlineForm = document.getElementById(`sl-kapa-handoff-inline-${handoffQaId}`);
+			if (!inlineForm) return;
+			inlineForm.scrollIntoView({
+				behavior: 'smooth',
+				block: 'nearest',
+			});
+			const emailInput = inlineForm.querySelector<HTMLInputElement>('input[type="email"]');
+			emailInput?.focus();
+		});
+		return () => {
+			window.cancelAnimationFrame(frame);
+		};
+	}, [handoffQaId, isOpen, conversation.length]);
+
 	useEffect(() => {
 		const dialog = dialogRef.current;
 		if (!dialog) return;
@@ -107,6 +538,7 @@ function ChatSurface({ title, welcomeMessage, autoOpen = false, onNewConversatio
 	const submit = () => {
 		const value = query.trim();
 		if (!value || isBusy) return;
+		closeHandoffForm();
 		submitQuery(value);
 		setHasStartedConversation(true);
 		setQuery('');
@@ -119,6 +551,116 @@ function ChatSurface({ title, welcomeMessage, autoOpen = false, onNewConversatio
 
 	const feedback = (questionAnswerId: string, reaction: FeedbackReaction) => {
 		addFeedback(questionAnswerId, reaction);
+		if (reaction === 'downvote') {
+			setDownvotedAnswerIds((current) => ({ ...current, [questionAnswerId]: true }));
+		}
+	};
+
+	const isDownvoted = (qaId: string | null | undefined, reaction: string | null | undefined) => {
+		if (!qaId) return false;
+		return reaction === 'downvote' || downvotedAnswerIds[qaId] === true;
+	};
+
+	const shouldShowHandoffForAnswer = (qa: {
+		id?: string | null;
+		answer?: string | null;
+		metadata?: unknown;
+		reaction?: string | null;
+	}) => {
+		if (!qa.answer?.trim()) return false;
+		const conversationLengthTriggered = conversation.length >= conversationLengthThreshold;
+		const downvoteTriggered = isDownvoted(qa.id ?? null, qa.reaction ?? null);
+		const uncertaintyTriggered = isAnswerUncertain(qa.metadata);
+		return conversationLengthTriggered || downvoteTriggered || uncertaintyTriggered;
+	};
+
+	const buildConversationTranscript = () => {
+		if (!conversation.length) return 'No conversation history yet.';
+		return conversation
+			.map((qa, index) => {
+				const sources = qa.sources?.length
+					? `\nSources:\n${qa.sources.map((source) => `- ${source.title}: ${source.source_url}`).join('\n')}`
+					: '';
+				return `Q${index + 1}: ${qa.question}\nA${index + 1}: ${qa.answer || '(no answer generated yet)'}${sources}`;
+			})
+			.join('\n\n');
+	};
+
+	const buildConversationLink = (currentThreadId: string | null) => {
+		if (!projectId || !currentThreadId) return null;
+		return `https://app.kapa.ai/${projectId}/conversations/${currentThreadId}`;
+	};
+
+	const openHandoffForm = (qaId: string) => {
+		setHandoffQaId(qaId);
+		setHandoffErrorMessage(null);
+		setHandoffSuccessMessage(null);
+	};
+
+	const closeHandoffForm = () => {
+		setHandoffQaId(null);
+		setHandoffErrorMessage(null);
+		setHandoffSuccessMessage(null);
+	};
+
+	const submitSupportHandoff = async (qa: { id?: string | null; question?: string }) => {
+		const userEmail = handoffEmailInput.trim().toLowerCase();
+		if (!isValidEmailAddress(userEmail)) {
+			setHandoffErrorMessage('Enter a valid email address to continue.');
+			return;
+		}
+		const localStorageThreadId = localStorage.getItem('warp_docs_kapa_thread_id');
+		const activeThreadId = threadId || storedThreadId || localStorageThreadId;
+		if (!activeThreadId) {
+			setHandoffErrorMessage('Missing Kapa thread context; please send another message and try again.');
+			return;
+		}
+
+		const question = qa.question?.trim();
+		if (!question) {
+			setHandoffErrorMessage('Missing question context for handoff.');
+			return;
+		}
+
+		const conversationLink = buildConversationLink(activeThreadId);
+		const captcha = await executeCaptcha(CaptchaAction.FeedbackSubmit);
+		if (!captcha?.token || !captcha?.key) {
+			setHandoffErrorMessage('Captcha verification failed. Please try again.');
+			return;
+		}
+
+		setIsSubmittingHandoff(true);
+		setHandoffErrorMessage(null);
+		setHandoffSuccessMessage(null);
+		try {
+			const response = await fetch('/api/support-handoff', {
+				method: 'POST',
+				headers: {
+					'content-type': 'application/json',
+				},
+				body: JSON.stringify({
+					user_email: userEmail,
+					question,
+					page_url: window.location.href,
+					conversation_transcript: buildConversationTranscript(),
+					kapa_project_id: projectId || null,
+					kapa_thread_id: activeThreadId,
+					kapa_conversation_url: conversationLink || null,
+					captcha_token: captcha.token,
+					captcha_header: captcha.key,
+				}),
+			});
+			const payload: HandoffApiSuccess & { message?: string } = await response.json().catch(() => ({}));
+			if (!response.ok) {
+				setHandoffErrorMessage(payload.message || 'Could not create support ticket. Please try again.');
+				return;
+			}
+			setHandoffSuccessMessage(payload.message || 'Support ticket created successfully.');
+		} catch {
+			setHandoffErrorMessage('Could not reach support handoff service. Please try again.');
+		} finally {
+			setIsSubmittingHandoff(false);
+		}
 	};
 
 	const openPanel = () => {
@@ -137,9 +679,10 @@ function ChatSurface({ title, welcomeMessage, autoOpen = false, onNewConversatio
 		// Legacy fallback: earlier callers stashed the query on window before
 		// triggering us. Kept as a belt-and-braces guard in case any path
 		// still uses it.
-		if (!pendingQuery && (window as any).__warpAskAiQuery) {
-			pendingQuery = (window as any).__warpAskAiQuery;
-			delete (window as any).__warpAskAiQuery;
+		const windowWithAskQuery = window as Window & { __warpAskAiQuery?: string };
+		if (!pendingQuery && windowWithAskQuery.__warpAskAiQuery) {
+			pendingQuery = windowWithAskQuery.__warpAskAiQuery;
+			delete windowWithAskQuery.__warpAskAiQuery;
 		}
 
 		setIsOpen(true);
@@ -236,7 +779,38 @@ function ChatSurface({ title, welcomeMessage, autoOpen = false, onNewConversatio
 								<div className="sl-kapa-message sl-kapa-message--user">{qa.question}</div>
 								<div className="sl-kapa-message sl-kapa-message--assistant">
 									{qa.answer ? (
-										<ReactMarkdown>{qa.answer}</ReactMarkdown>
+										<ReactMarkdown
+											components={{
+												// Fenced code blocks arrive as <pre><code>; inline code
+												// arrives as a bare <code>. react-markdown v9+ removed the
+												// `inline` prop, so nesting is the only reliable signal.
+												pre({ children }) {
+													const codeElement = extractCodeElement(children);
+													if (!codeElement) {
+														return <pre>{children}</pre>;
+													}
+													const codeClassName =
+														typeof codeElement.props.className === 'string'
+															? codeElement.props.className
+															: undefined;
+													const codeText = markdownChildrenToText(codeElement.props.children);
+													const isStreamingAnswer =
+														isBusy && conversation[conversation.length - 1]?.id === qa.id;
+													return (
+														<ChatCodeBlock
+															className={codeClassName}
+															codeText={codeText}
+															deferHighlight={isStreamingAnswer}
+														/>
+													);
+												},
+												code({ className, children }) {
+													return <code className={className}>{children}</code>;
+												},
+											}}
+										>
+											{qa.answer}
+										</ReactMarkdown>
 									) : (
 										<div className="sl-kapa-thinking">
 											<LuLoaderCircle className="sl-kapa-spinner" aria-hidden="true" />
@@ -278,13 +852,73 @@ function ChatSurface({ title, welcomeMessage, autoOpen = false, onNewConversatio
 											>
 												<LuThumbsDown aria-hidden="true" />
 											</button>
+											{shouldShowHandoffForAnswer(qa) ? (
+												<button
+													type="button"
+													className="sl-kapa-feedback__handoff"
+													onClick={() => openHandoffForm(qa.id as string)}
+												>
+													Create ticket
+												</button>
+											) : null}
+										</div>
+									) : null}
+									{handoffQaId === qa.id && !isBusy && shouldShowHandoffForAnswer(qa) ? (
+										<div
+											className="sl-kapa-handoff-inline"
+											id={`sl-kapa-handoff-inline-${qa.id}`}
+										>
+											<label htmlFor={`sl-kapa-handoff-email-${qa.id}`}>
+												Your Warp account email
+											</label>
+											<form
+												className="sl-kapa-handoff-inline__row"
+												onSubmit={(event) => {
+													event.preventDefault();
+													void submitSupportHandoff(qa);
+												}}
+											>
+												<input
+													id={`sl-kapa-handoff-email-${qa.id}`}
+													type="email"
+													placeholder="you@company.com"
+													value={handoffEmailInput}
+													onChange={(event) => setHandoffEmailInput(event.target.value)}
+													required
+												/>
+												<button
+													type="submit"
+													className="sl-kapa-feedback__handoff sl-kapa-feedback__handoff--submit"
+													disabled={isSubmittingHandoff}
+												>
+													{isSubmittingHandoff ? 'Submitting…' : 'Submit'}
+												</button>
+												<button
+													type="button"
+													className="sl-kapa-feedback__handoff sl-kapa-feedback__handoff--ghost"
+													onClick={closeHandoffForm}
+													disabled={isSubmittingHandoff}
+												>
+													Cancel
+												</button>
+											</form>
+											{handoffErrorMessage ? (
+												<p className="sl-kapa-handoff-inline__status sl-kapa-handoff-inline__status--error">
+													{handoffErrorMessage}
+												</p>
+											) : null}
+											{handoffSuccessMessage ? (
+												<p className="sl-kapa-handoff-inline__status sl-kapa-handoff-inline__status--success">
+													{handoffSuccessMessage}
+												</p>
+											) : null}
 										</div>
 									) : null}
 								</div>
 							</div>
 						))}
 
-						{error ? <div className="sl-kapa-error">{error}</div> : null}
+						{error ? <div className="sl-kapa-error">{getChatErrorMessage(error)}</div> : null}
 					</div>
 					<footer className="sl-kapa-panel__footer">
 						<form className="sl-kapa-form" onSubmit={onSubmit}>
@@ -353,7 +987,13 @@ export default function KapaChatLauncher({ autoOpen = false }: { autoOpen?: bool
 	const [sessionAutoOpen, setSessionAutoOpen] = useState(autoOpen);
 	const callbacks = useMemo(
 		() => ({
-			askAI: {},
+			askAI: {
+				onAnswerGenerationCompleted: (data: { threadId?: string | null }) => {
+					if (data.threadId) {
+						localStorage.setItem('warp_docs_kapa_thread_id', data.threadId);
+					}
+				},
+			},
 		}),
 		[]
 	);
diff --git a/src/components/KapaLauncher.astro b/src/components/KapaLauncher.astro
index 028bc96f5..a978012c4 100644
--- a/src/components/KapaLauncher.astro
+++ b/src/components/KapaLauncher.astro
@@ -2,7 +2,17 @@
 // The button sits to the right of the sidebar search pill (see
 // CustomSidebar.astro), rendering as `[icon] Ask` at one type-scale step
 // smaller than search so it reads as the secondary affordance.
+import { Code } from 'astro-expressive-code/components';
 import KapaChatLauncher from './KapaChatLauncher';
 ---
 
 <KapaChatLauncher client:idle />
+
+{/*
+	Hidden Expressive Code block so EC frame CSS variables/assets exist on
+	every page. Chat copy buttons are owned by KapaChatLauncher (not EC's
+	`.copy` markup) to avoid double icons.
+*/}
+<div hidden aria-hidden="true">
+	<Code code="# Preloads Expressive Code assets for the Kapa chat panel" lang="text" />
+</div>
diff --git a/src/pages/api/support-handoff.ts b/src/pages/api/support-handoff.ts
new file mode 100644
index 000000000..31f981eaf
--- /dev/null
+++ b/src/pages/api/support-handoff.ts
@@ -0,0 +1,231 @@
+import type { APIRoute } from 'astro';
+import { SUPPORT_HANDOFF_ENDPOINT_URL, SUPPORT_HANDOFF_SHARED_SECRET } from 'astro:env/server';
+
+export const prerender = false;
+
+type HandoffPayload = {
+	user_email?: unknown;
+	question?: unknown;
+	page_url?: unknown;
+	conversation_transcript?: unknown;
+	kapa_project_id?: unknown;
+	kapa_thread_id?: unknown;
+	kapa_conversation_url?: unknown;
+	captcha_token?: unknown;
+	captcha_header?: unknown;
+};
+
+const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const KAPA_ID_PATTERN = /^[a-zA-Z0-9_-]{1,128}$/;
+const MAX_QUESTION_LENGTH = 4_000;
+const MAX_TRANSCRIPT_LENGTH = 50_000;
+const MAX_PAGE_URL_LENGTH = 2_048;
+const MAX_CAPTCHA_TOKEN_LENGTH = 4_096;
+const ALLOWED_PAGE_URL_HOSTS = new Set(['docs.warp.dev', 'localhost']);
+const ALLOWED_PAGE_URL_SUFFIXES = ['.vercel.app'];
+const ALLOWED_CAPTCHA_HEADERS = new Set(['X-RECAPTCHA-ENTERPRISE-TOKEN', 'X-HCAPTCHA-TOKEN']);
+const RATE_LIMIT_WINDOW_MS = 10 * 60 * 1000;
+const RATE_LIMIT_MAX_REQUESTS = 5;
+const rateLimitStore = new Map<string, { count: number; resetAt: number }>();
+
+function asTrimmedString(value: unknown) {
+	return typeof value === 'string' ? value.trim() : '';
+}
+
+function jsonError(message: string, status = 400) {
+	return new Response(JSON.stringify({ message }), {
+		status,
+		headers: { 'content-type': 'application/json' },
+	});
+}
+
+function buildKapaConversationUrl(kapaProjectId: string, kapaThreadId: string) {
+	return `https://app.kapa.ai/${kapaProjectId}/conversations/${kapaThreadId}`;
+}
+
+function isAllowedPageUrl(url: string) {
+	if (url.length > MAX_PAGE_URL_LENGTH) return false;
+	try {
+		const parsed = new URL(url);
+		if (!['http:', 'https:'].includes(parsed.protocol)) return false;
+		const hostname = parsed.hostname.toLowerCase();
+		if (ALLOWED_PAGE_URL_HOSTS.has(hostname)) return true;
+		return ALLOWED_PAGE_URL_SUFFIXES.some((suffix) => hostname.endsWith(suffix));
+	} catch {
+		return false;
+	}
+}
+
+function isAllowedHostname(hostname: string) {
+	const lowercasedHostname = hostname.toLowerCase();
+	if (ALLOWED_PAGE_URL_HOSTS.has(lowercasedHostname)) return true;
+	return ALLOWED_PAGE_URL_SUFFIXES.some((suffix) => lowercasedHostname.endsWith(suffix));
+}
+
+function isAllowedRequestOrigin(request: Request) {
+	const originHeader = request.headers.get('origin');
+	if (!originHeader) return false;
+	try {
+		const parsedOrigin = new URL(originHeader);
+		if (!['http:', 'https:'].includes(parsedOrigin.protocol)) return false;
+		return isAllowedHostname(parsedOrigin.hostname);
+	} catch {
+		return false;
+	}
+}
+
+function getClientIp(request: Request) {
+	const forwardedFor = request.headers.get('x-forwarded-for');
+	if (forwardedFor) {
+		const firstIp = forwardedFor.split(',')[0]?.trim();
+		if (firstIp) return firstIp;
+	}
+	const connectingIp = request.headers.get('cf-connecting-ip')?.trim();
+	if (connectingIp) return connectingIp;
+	const realIp = request.headers.get('x-real-ip')?.trim();
+	if (realIp) return realIp;
+	return 'unknown';
+}
+
+function isRateLimited(clientIp: string) {
+	const now = Date.now();
+	const existing = rateLimitStore.get(clientIp);
+	if (!existing || existing.resetAt <= now) {
+		rateLimitStore.set(clientIp, { count: 1, resetAt: now + RATE_LIMIT_WINDOW_MS });
+		return false;
+	}
+	existing.count += 1;
+	if (existing.count > RATE_LIMIT_MAX_REQUESTS) {
+		return true;
+	}
+	rateLimitStore.set(clientIp, existing);
+	return false;
+}
+
+export const POST: APIRoute = async ({ request }) => {
+	const supportHandoffEndpointUrl = SUPPORT_HANDOFF_ENDPOINT_URL?.trim() || '';
+	const supportHandoffSharedSecret = SUPPORT_HANDOFF_SHARED_SECRET?.trim() || '';
+	if (!supportHandoffEndpointUrl || !supportHandoffSharedSecret) {
+		return jsonError('Support handoff is not configured.', 503);
+	}
+	if (!isAllowedRequestOrigin(request)) {
+		return jsonError('Request origin is not allowed.', 403);
+	}
+	const clientIp = getClientIp(request);
+	if (isRateLimited(clientIp)) {
+		return jsonError('Too many support handoff attempts. Please try again later.', 429);
+	}
+
+	let payload: HandoffPayload;
+	try {
+		payload = (await request.json()) as HandoffPayload;
+	} catch {
+		return jsonError('Invalid JSON payload.');
+	}
+
+	const userEmail = asTrimmedString(payload.user_email).toLowerCase();
+	if (!EMAIL_PATTERN.test(userEmail)) {
+		return jsonError('Please enter a valid email address.');
+	}
+
+	const question = asTrimmedString(payload.question);
+	const pageUrl = asTrimmedString(payload.page_url);
+	const conversationTranscript = asTrimmedString(payload.conversation_transcript);
+	const kapaProjectId = asTrimmedString(payload.kapa_project_id);
+	const kapaThreadId = asTrimmedString(payload.kapa_thread_id);
+	const suppliedKapaConversationUrl = asTrimmedString(payload.kapa_conversation_url);
+	const captchaToken = asTrimmedString(payload.captcha_token);
+	const captchaHeader = asTrimmedString(payload.captcha_header);
+
+	if (!question) return jsonError('A question is required.');
+	if (question.length > MAX_QUESTION_LENGTH) return jsonError('Question is too long.');
+	if (!pageUrl) return jsonError('The current page URL is required.');
+	if (!isAllowedPageUrl(pageUrl)) return jsonError('Page URL is invalid or not allowed.');
+	if (!conversationTranscript) return jsonError('Conversation transcript is required.');
+	if (conversationTranscript.length > MAX_TRANSCRIPT_LENGTH) {
+		return jsonError('Conversation transcript is too long.');
+	}
+	if (!kapaThreadId) return jsonError('Kapa thread ID is required.');
+	if (!KAPA_ID_PATTERN.test(kapaThreadId)) return jsonError('Kapa thread ID is invalid.');
+	if (!captchaToken) return jsonError('Captcha verification is required.');
+	if (captchaToken.length > MAX_CAPTCHA_TOKEN_LENGTH) return jsonError('Captcha token is invalid.');
+	if (!ALLOWED_CAPTCHA_HEADERS.has(captchaHeader)) return jsonError('Captcha token header is invalid.');
+	if (kapaProjectId && !KAPA_ID_PATTERN.test(kapaProjectId)) {
+		return jsonError('Kapa project ID is invalid.');
+	}
+	const derivedKapaConversationUrl =
+		kapaProjectId && kapaThreadId
+			? buildKapaConversationUrl(kapaProjectId, kapaThreadId)
+			: '';
+	if (kapaProjectId) {
+		if (
+			suppliedKapaConversationUrl &&
+			suppliedKapaConversationUrl !== derivedKapaConversationUrl
+		) {
+			return jsonError('Kapa conversation URL does not match project/thread values.');
+		}
+	} else if (suppliedKapaConversationUrl) {
+		return jsonError('Kapa project ID is required when a Kapa conversation URL is supplied.');
+	}
+
+	const forwardPayload = {
+		user_email: userEmail,
+		question,
+		page_url: pageUrl,
+		conversation_transcript: conversationTranscript,
+		kapa_project_id: kapaProjectId || null,
+		kapa_thread_id: kapaThreadId,
+		kapa_conversation_url: derivedKapaConversationUrl || null,
+		source: 'docs-kapa-custom-chat',
+	};
+
+	// DevX `gcp_front_docs_handoff` validates the shared secret the same way
+	// Front webhooks do: as a `?secret=` query param (see
+	// helper_flask.validate_front_webhook_secret). Bearer alone is ignored.
+	const upstreamUrl = new URL(supportHandoffEndpointUrl);
+	upstreamUrl.searchParams.set('secret', supportHandoffSharedSecret);
+
+	const forwardHeaders: HeadersInit = {
+		'content-type': 'application/json',
+		[captchaHeader]: captchaToken,
+	};
+
+	let upstreamResponse: Response;
+	try {
+		upstreamResponse = await fetch(upstreamUrl.toString(), {
+			method: 'POST',
+			headers: forwardHeaders,
+			body: JSON.stringify(forwardPayload),
+		});
+	} catch {
+		return jsonError('Failed to reach support handoff service.', 502);
+	}
+
+	let upstreamData: unknown = null;
+	try {
+		upstreamData = await upstreamResponse.json();
+	} catch {
+		upstreamData = null;
+	}
+
+	if (!upstreamResponse.ok) {
+		const upstreamMessage =
+			upstreamData &&
+			typeof upstreamData === 'object' &&
+			'message' in upstreamData &&
+			typeof upstreamData.message === 'string'
+				? upstreamData.message
+				: 'Support handoff failed.';
+		return jsonError(upstreamMessage, upstreamResponse.status);
+	}
+
+	return new Response(
+		JSON.stringify({
+			message: 'Message sent to Warp Support.',
+		}),
+		{
+			status: 200,
+			headers: { 'content-type': 'application/json' },
+		}
+	);
+};
diff --git a/src/styles/warp-components.css b/src/styles/warp-components.css
index 38e3ce3e5..2169c61c0 100644
--- a/src/styles/warp-components.css
+++ b/src/styles/warp-components.css
@@ -179,6 +179,18 @@
 pre.astro-code,
 .sl-markdown-content pre {
   overflow-x: auto;
+  overflow-y: hidden;
+  white-space: pre;
+}
+
+.expressive-code pre code,
+.sl-kapa-codeblock pre code {
+  display: block;
+  min-width: max-content;
+}
+
+.expressive-code pre {
+  scrollbar-width: thin;
 }
 
 /* Code block copy button — frosted glass effect (Scalar pattern) */
diff --git a/vercel.json b/vercel.json
index e8c2eeefd..b3462d7b6 100644
--- a/vercel.json
+++ b/vercel.json
@@ -29,7 +29,7 @@
         },
         {
           "key": "Content-Security-Policy",
-          "value": "default-src 'self'; base-uri 'self'; form-action 'self'; object-src 'none'; script-src 'self' 'unsafe-inline' 'wasm-unsafe-eval' https://va.vercel-scripts.com https://vitals.vercel-insights.com https://www.google.com https://www.gstatic.com https://cdn.jsdelivr.net https://cdn.rudderlabs.com https://polyfill-fastly.io; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com https://cdn.jsdelivr.net; font-src 'self' https://fonts.gstatic.com https://cdn.jsdelivr.net; img-src 'self' data: https:; frame-src https://www.youtube-nocookie.com https://www.loom.com https://drive.google.com https://www.google.com; connect-src 'self' https://va.vercel-scripts.com https://vitals.vercel-insights.com https://*.kapa.ai https://www.google.com https://app.warp.dev https://api.rudderstack.com; frame-ancestors 'none'"
+          "value": "default-src 'self'; base-uri 'self'; form-action 'self'; object-src 'none'; script-src 'self' 'unsafe-inline' 'wasm-unsafe-eval' https://va.vercel-scripts.com https://vitals.vercel-insights.com https://www.google.com https://www.gstatic.com https://cdn.jsdelivr.net https://cdn.rudderlabs.com https://polyfill-fastly.io https://widget.kapa.ai https://hcaptcha.com https://*.hcaptcha.com https://js.hcaptcha.com; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com https://cdn.jsdelivr.net; font-src 'self' https://fonts.gstatic.com https://cdn.jsdelivr.net; img-src 'self' data: https:; frame-src https://www.youtube-nocookie.com https://www.loom.com https://drive.google.com https://www.google.com https://hcaptcha.com https://*.hcaptcha.com; connect-src 'self' https://va.vercel-scripts.com https://vitals.vercel-insights.com https://*.kapa.ai https://kapa-widget-proxy-la7dkmplpq-uc.a.run.app https://www.google.com https://app.warp.dev https://api.rudderstack.com https://cdn.rudderlabs.com https://hcaptcha.com https://*.hcaptcha.com; frame-ancestors 'none'"
         }
       ]
     },
@@ -38,7 +38,7 @@
       "headers": [
         {
           "key": "Content-Security-Policy",
-          "value": "default-src 'self'; base-uri 'self'; form-action 'self'; object-src 'none'; script-src 'self' 'unsafe-inline' 'unsafe-eval' https://va.vercel-scripts.com https://vitals.vercel-insights.com https://www.google.com https://www.gstatic.com https://cdn.jsdelivr.net https://cdn.rudderlabs.com https://polyfill-fastly.io; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com https://cdn.jsdelivr.net; font-src 'self' https://fonts.gstatic.com https://cdn.jsdelivr.net; img-src 'self' data: https:; frame-src https://www.youtube-nocookie.com https://www.loom.com https://drive.google.com https://www.google.com; connect-src 'self' https://va.vercel-scripts.com https://vitals.vercel-insights.com https://*.kapa.ai https://www.google.com https://app.warp.dev https://api.rudderstack.com; frame-ancestors 'none'"
+          "value": "default-src 'self'; base-uri 'self'; form-action 'self'; object-src 'none'; script-src 'self' 'unsafe-inline' 'unsafe-eval' https://va.vercel-scripts.com https://vitals.vercel-insights.com https://www.google.com https://www.gstatic.com https://cdn.jsdelivr.net https://cdn.rudderlabs.com https://polyfill-fastly.io https://widget.kapa.ai https://hcaptcha.com https://*.hcaptcha.com https://js.hcaptcha.com; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com https://cdn.jsdelivr.net; font-src 'self' https://fonts.gstatic.com https://cdn.jsdelivr.net; img-src 'self' data: https:; frame-src https://www.youtube-nocookie.com https://www.loom.com https://drive.google.com https://www.google.com https://hcaptcha.com https://*.hcaptcha.com; connect-src 'self' https://va.vercel-scripts.com https://vitals.vercel-insights.com https://*.kapa.ai https://kapa-widget-proxy-la7dkmplpq-uc.a.run.app https://www.google.com https://app.warp.dev https://api.rudderstack.com https://cdn.rudderlabs.com https://hcaptcha.com https://*.hcaptcha.com; frame-ancestors 'none'"
         }
       ]
     },
@@ -47,7 +47,7 @@
       "headers": [
         {
           "key": "Content-Security-Policy",
-          "value": "default-src 'self'; base-uri 'self'; form-action 'self'; object-src 'none'; script-src 'self' 'unsafe-inline' 'unsafe-eval' https://va.vercel-scripts.com https://vitals.vercel-insights.com https://www.google.com https://www.gstatic.com https://cdn.jsdelivr.net https://cdn.rudderlabs.com https://polyfill-fastly.io; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com https://cdn.jsdelivr.net; font-src 'self' https://fonts.gstatic.com https://cdn.jsdelivr.net; img-src 'self' data: https:; frame-src https://www.youtube-nocookie.com https://www.loom.com https://drive.google.com https://www.google.com; connect-src 'self' https://va.vercel-scripts.com https://vitals.vercel-insights.com https://*.kapa.ai https://www.google.com https://app.warp.dev https://api.rudderstack.com; frame-ancestors 'none'"
+          "value": "default-src 'self'; base-uri 'self'; form-action 'self'; object-src 'none'; script-src 'self' 'unsafe-inline' 'unsafe-eval' https://va.vercel-scripts.com https://vitals.vercel-insights.com https://www.google.com https://www.gstatic.com https://cdn.jsdelivr.net https://cdn.rudderlabs.com https://polyfill-fastly.io https://widget.kapa.ai https://hcaptcha.com https://*.hcaptcha.com https://js.hcaptcha.com; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com https://cdn.jsdelivr.net; font-src 'self' https://fonts.gstatic.com https://cdn.jsdelivr.net; img-src 'self' data: https:; frame-src https://www.youtube-nocookie.com https://www.loom.com https://drive.google.com https://www.google.com https://hcaptcha.com https://*.hcaptcha.com; connect-src 'self' https://va.vercel-scripts.com https://vitals.vercel-insights.com https://*.kapa.ai https://kapa-widget-proxy-la7dkmplpq-uc.a.run.app https://www.google.com https://app.warp.dev https://api.rudderstack.com https://cdn.rudderlabs.com https://hcaptcha.com https://*.hcaptcha.com; frame-ancestors 'none'"
         }
       ]
     },
@@ -390,11 +390,6 @@
       "destination": "/guides/devops/how-to-analyze-cloud-run-logs-gcloud/",
       "statusCode": 308
     },
-    {
-      "source": "/knowledge-and-collaboration/session-sharingentials1",
-      "destination": "/knowledge-and-collaboration/session-sharing/",
-      "statusCode": 308
-    },
     {
       "source": "/advanced/command-line-flags",
       "destination": "/terminal/sessions/launch-configurations/",
@@ -1390,11 +1385,6 @@
       "destination": "/agent-platform/local-agents/interacting-with-agents/",
       "statusCode": 308
     },
-    {
-      "source": "/agent-platform/features/warp-ai/agent-modea",
-      "destination": "/agent-platform/local-agents/interacting-with-agents/",
-      "statusCode": 308
-    },
     {
       "source": "/agent-platform/features/warp-ai/ai-command-search",
       "destination": "/agent-platform/local-agents/overview/",
@@ -5680,11 +5670,6 @@
       "destination": "/agent-platform/local-agents/interacting-with-agents/",
       "statusCode": 308
     },
-    {
-      "source": "/agent-platform/features/warp-ai/agent-modea/",
-      "destination": "/agent-platform/local-agents/interacting-with-agents/",
-      "statusCode": 308
-    },
     {
       "source": "/agent-platform/features/warp-ai/ai-command-search/",
       "destination": "/agent-platform/local-agents/overview/",

From 86f1d61bb7d35e8d270d14f82fbec1f49c7d58d0 Mon Sep 17 00:00:00 2001
From: Danny Neira <16809145+dannyneira@users.noreply.github.com>
Date: Wed, 12 Aug 2026 14:31:04 -0600
Subject: [PATCH 02/10] fix(docs): harden support handoff

Co-Authored-By: Warp Agent <agent@warp.dev>
---
 .env.example                        |  4 ++--
 src/components/KapaChatLauncher.tsx | 17 ++++++++++++-----
 src/pages/api/support-handoff.ts    | 10 +++++-----
 vercel.json                         | 15 +++++++++++++++
 4 files changed, 34 insertions(+), 12 deletions(-)

diff --git a/.env.example b/.env.example
index cd78fae27..ed587847d 100644
--- a/.env.example
+++ b/.env.example
@@ -35,6 +35,6 @@ PUBLIC_RUDDERSTACK_DATA_PLANE_URL=
 # conversations from docs chat handoff requests.
 SUPPORT_HANDOFF_ENDPOINT_URL=
 
-# Optional shared secret sent as an authorization bearer token when
-# forwarding to SUPPORT_HANDOFF_ENDPOINT_URL.
+# Required when SUPPORT_HANDOFF_ENDPOINT_URL is set. Docs forwards this only
+# to the DevX service as the `?secret=` query parameter, not as a bearer token.
 SUPPORT_HANDOFF_SHARED_SECRET=
diff --git a/src/components/KapaChatLauncher.tsx b/src/components/KapaChatLauncher.tsx
index dcc0b2e55..d1ccc5314 100644
--- a/src/components/KapaChatLauncher.tsx
+++ b/src/components/KapaChatLauncher.tsx
@@ -604,6 +604,7 @@ function ChatSurface({ title, welcomeMessage, autoOpen = false, onNewConversatio
 	};
 
 	const submitSupportHandoff = async (qa: { id?: string | null; question?: string }) => {
+		if (isSubmittingHandoff) return;
 		const userEmail = handoffEmailInput.trim().toLowerCase();
 		if (!isValidEmailAddress(userEmail)) {
 			setHandoffErrorMessage('Enter a valid email address to continue.');
@@ -623,16 +624,22 @@ function ChatSurface({ title, welcomeMessage, autoOpen = false, onNewConversatio
 		}
 
 		const conversationLink = buildConversationLink(activeThreadId);
-		const captcha = await executeCaptcha(CaptchaAction.FeedbackSubmit);
-		if (!captcha?.token || !captcha?.key) {
-			setHandoffErrorMessage('Captcha verification failed. Please try again.');
-			return;
-		}
 
 		setIsSubmittingHandoff(true);
 		setHandoffErrorMessage(null);
 		setHandoffSuccessMessage(null);
 		try {
+			let captcha;
+			try {
+				captcha = await executeCaptcha(CaptchaAction.FeedbackSubmit);
+			} catch {
+				setHandoffErrorMessage('Captcha verification could not be completed. Please try again.');
+				return;
+			}
+			if (!captcha?.token || !captcha?.key) {
+				setHandoffErrorMessage('Captcha verification did not return a token. Please try again.');
+				return;
+			}
 			const response = await fetch('/api/support-handoff', {
 				method: 'POST',
 				headers: {
diff --git a/src/pages/api/support-handoff.ts b/src/pages/api/support-handoff.ts
index 31f981eaf..89ecba92a 100644
--- a/src/pages/api/support-handoff.ts
+++ b/src/pages/api/support-handoff.ts
@@ -22,7 +22,7 @@ const MAX_TRANSCRIPT_LENGTH = 50_000;
 const MAX_PAGE_URL_LENGTH = 2_048;
 const MAX_CAPTCHA_TOKEN_LENGTH = 4_096;
 const ALLOWED_PAGE_URL_HOSTS = new Set(['docs.warp.dev', 'localhost']);
-const ALLOWED_PAGE_URL_SUFFIXES = ['.vercel.app'];
+const DOCS_PREVIEW_HOSTNAME_PATTERN = /^docs-[a-z0-9]+(?:-[a-z0-9]+)*-warpdotdev\.vercel\.app$/;
 const ALLOWED_CAPTCHA_HEADERS = new Set(['X-RECAPTCHA-ENTERPRISE-TOKEN', 'X-HCAPTCHA-TOKEN']);
 const RATE_LIMIT_WINDOW_MS = 10 * 60 * 1000;
 const RATE_LIMIT_MAX_REQUESTS = 5;
@@ -48,9 +48,7 @@ function isAllowedPageUrl(url: string) {
 	try {
 		const parsed = new URL(url);
 		if (!['http:', 'https:'].includes(parsed.protocol)) return false;
-		const hostname = parsed.hostname.toLowerCase();
-		if (ALLOWED_PAGE_URL_HOSTS.has(hostname)) return true;
-		return ALLOWED_PAGE_URL_SUFFIXES.some((suffix) => hostname.endsWith(suffix));
+		return isAllowedHostname(parsed.hostname);
 	} catch {
 		return false;
 	}
@@ -59,7 +57,7 @@ function isAllowedPageUrl(url: string) {
 function isAllowedHostname(hostname: string) {
 	const lowercasedHostname = hostname.toLowerCase();
 	if (ALLOWED_PAGE_URL_HOSTS.has(lowercasedHostname)) return true;
-	return ALLOWED_PAGE_URL_SUFFIXES.some((suffix) => lowercasedHostname.endsWith(suffix));
+	return DOCS_PREVIEW_HOSTNAME_PATTERN.test(lowercasedHostname);
 }
 
 function isAllowedRequestOrigin(request: Request) {
@@ -75,6 +73,8 @@ function isAllowedRequestOrigin(request: Request) {
 }
 
 function getClientIp(request: Request) {
+	// Vercel overwrites `x-forwarded-for` and strips external values to prevent
+	// spoofing: https://vercel.com/docs/headers/request-headers#x-forwarded-for
 	const forwardedFor = request.headers.get('x-forwarded-for');
 	if (forwardedFor) {
 		const firstIp = forwardedFor.split(',')[0]?.trim();
diff --git a/vercel.json b/vercel.json
index b3462d7b6..ea16be4aa 100644
--- a/vercel.json
+++ b/vercel.json
@@ -390,6 +390,11 @@
       "destination": "/guides/devops/how-to-analyze-cloud-run-logs-gcloud/",
       "statusCode": 308
     },
+    {
+      "source": "/knowledge-and-collaboration/session-sharingentials1",
+      "destination": "/knowledge-and-collaboration/session-sharing/",
+      "statusCode": 308
+    },
     {
       "source": "/advanced/command-line-flags",
       "destination": "/terminal/sessions/launch-configurations/",
@@ -1385,6 +1390,11 @@
       "destination": "/agent-platform/local-agents/interacting-with-agents/",
       "statusCode": 308
     },
+    {
+      "source": "/agent-platform/features/warp-ai/agent-modea",
+      "destination": "/agent-platform/local-agents/interacting-with-agents/",
+      "statusCode": 308
+    },
     {
       "source": "/agent-platform/features/warp-ai/ai-command-search",
       "destination": "/agent-platform/local-agents/overview/",
@@ -5670,6 +5680,11 @@
       "destination": "/agent-platform/local-agents/interacting-with-agents/",
       "statusCode": 308
     },
+    {
+      "source": "/agent-platform/features/warp-ai/agent-modea/",
+      "destination": "/agent-platform/local-agents/interacting-with-agents/",
+      "statusCode": 308
+    },
     {
       "source": "/agent-platform/features/warp-ai/ai-command-search/",
       "destination": "/agent-platform/local-agents/overview/",

From 991c864c64d75aaa6145cb4db4b9ddab92f9a18c Mon Sep 17 00:00:00 2001
From: Danny Neira <16809145+dannyneira@users.noreply.github.com>
Date: Wed, 12 Aug 2026 15:31:05 -0600
Subject: [PATCH 03/10] fix(docs): consolidate Vercel header routes

Co-Authored-By: Warp Agent <agent@warp.dev>
---
 vercel.json | 22 ++--------------------
 1 file changed, 2 insertions(+), 20 deletions(-)

diff --git a/vercel.json b/vercel.json
index ea16be4aa..fbfc579ee 100644
--- a/vercel.json
+++ b/vercel.json
@@ -34,7 +34,7 @@
       ]
     },
     {
-      "source": "/api",
+      "source": "/api/:path*",
       "headers": [
         {
           "key": "Content-Security-Policy",
@@ -43,25 +43,7 @@
       ]
     },
     {
-      "source": "/api/(.*)",
-      "headers": [
-        {
-          "key": "Content-Security-Policy",
-          "value": "default-src 'self'; base-uri 'self'; form-action 'self'; object-src 'none'; script-src 'self' 'unsafe-inline' 'unsafe-eval' https://va.vercel-scripts.com https://vitals.vercel-insights.com https://www.google.com https://www.gstatic.com https://cdn.jsdelivr.net https://cdn.rudderlabs.com https://polyfill-fastly.io https://widget.kapa.ai https://hcaptcha.com https://*.hcaptcha.com https://js.hcaptcha.com; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com https://cdn.jsdelivr.net; font-src 'self' https://fonts.gstatic.com https://cdn.jsdelivr.net; img-src 'self' data: https:; frame-src https://www.youtube-nocookie.com https://www.loom.com https://drive.google.com https://www.google.com https://hcaptcha.com https://*.hcaptcha.com; connect-src 'self' https://va.vercel-scripts.com https://vitals.vercel-insights.com https://*.kapa.ai https://kapa-widget-proxy-la7dkmplpq-uc.a.run.app https://www.google.com https://app.warp.dev https://api.rudderstack.com https://cdn.rudderlabs.com https://hcaptcha.com https://*.hcaptcha.com; frame-ancestors 'none'"
-        }
-      ]
-    },
-    {
-      "source": "/_astro/(.*)",
-      "headers": [
-        {
-          "key": "Cache-Control",
-          "value": "public, max-age=31536000, immutable"
-        }
-      ]
-    },
-    {
-      "source": "/assets/(.*)",
+      "source": "/:directory(_astro|assets)/:path(.*)",
       "headers": [
         {
           "key": "Cache-Control",

From b5f8ba2b10caf8bd4f2929b3774409b7a797d745 Mon Sep 17 00:00:00 2001
From: Danny Neira <16809145+dannyneira@users.noreply.github.com>
Date: Thu, 13 Aug 2026 13:19:35 -0600
Subject: [PATCH 04/10] feat(docs): render Kapa answer images

Co-Authored-By: Warp Agent <agent@warp.dev>
---
 src/components/KapaChatLauncher.css | 41 +++++++++++++++++++++++++++
 src/components/KapaChatLauncher.tsx | 43 +++++++++++++++++++++++++++++
 2 files changed, 84 insertions(+)

diff --git a/src/components/KapaChatLauncher.css b/src/components/KapaChatLauncher.css
index d810c5b08..c79899bd0 100644
--- a/src/components/KapaChatLauncher.css
+++ b/src/components/KapaChatLauncher.css
@@ -199,6 +199,47 @@
 	border-radius: var(--sl-radius-sm);
 	padding: 0.1rem 0.3rem;
 }
+.sl-kapa-answer-image {
+	display: block;
+	box-sizing: border-box;
+	max-width: 100%;
+	height: auto;
+	margin: 0.875rem 0;
+	border: 1px solid var(--sl-color-gray-5);
+	border-radius: var(--sl-radius-md);
+	background: var(--sl-color-black);
+	object-fit: contain;
+	box-shadow: 0 0.25rem 0.75rem rgb(0 0 0 / 0.18);
+}
+
+.sl-kapa-answer-image-fallback {
+	display: flex;
+	box-sizing: border-box;
+	align-items: center;
+	min-height: 3rem;
+	max-width: 100%;
+	margin: 0.875rem 0;
+	padding: 0.625rem 0.75rem;
+	border: 1px dashed var(--sl-color-gray-4);
+	border-radius: var(--sl-radius-md);
+	background: color-mix(in srgb, var(--sl-color-black), var(--sl-color-gray-6) 30%);
+	color: var(--sl-color-gray-3);
+	font-size: var(--sl-text-xs);
+	line-height: 1.4;
+	overflow-wrap: anywhere;
+}
+
+:root[data-theme='light'] .sl-kapa-answer-image {
+	border-color: color-mix(in srgb, var(--sl-color-gray-5), var(--sl-color-black) 15%);
+	background: var(--sl-color-white);
+	box-shadow: 0 0.25rem 0.75rem rgb(0 0 0 / 0.1);
+}
+
+:root[data-theme='light'] .sl-kapa-answer-image-fallback {
+	border-color: color-mix(in srgb, var(--sl-color-gray-4), var(--sl-color-black) 25%);
+	background: color-mix(in srgb, var(--sl-color-white), var(--sl-color-gray-6) 10%);
+	color: var(--sl-color-gray-3);
+}
 
 .sl-kapa-codeblock {
 	position: relative;
diff --git a/src/components/KapaChatLauncher.tsx b/src/components/KapaChatLauncher.tsx
index d1ccc5314..1eac0896c 100644
--- a/src/components/KapaChatLauncher.tsx
+++ b/src/components/KapaChatLauncher.tsx
@@ -177,6 +177,48 @@ function extractCodeElement(children: ReactNode): ReactElement<MarkdownCodeProps
 function markdownChildrenToText(children: ReactNode): string {
 	return (Array.isArray(children) ? children.join('') : String(children ?? '')).replace(/\n$/, '');
 }
+type ChatMarkdownImageProps = {
+	alt?: string;
+	src?: string;
+	title?: string;
+};
+
+function ChatMarkdownImage({ alt, src, title }: ChatMarkdownImageProps) {
+	const [hasFailed, setHasFailed] = useState(false);
+	const imageAlt = alt?.trim() || 'Image from Kapa answer';
+
+	useEffect(() => {
+		setHasFailed(false);
+	}, [src]);
+
+	if (!src || hasFailed) {
+		return (
+			<span
+				className="sl-kapa-answer-image-fallback"
+				role="img"
+				aria-label={`${imageAlt} unavailable`}
+			>
+				Image unavailable
+			</span>
+		);
+	}
+
+	// `src` has already passed react-markdown's default safe URL transformation.
+	// Do not wrap this image in an anchor because Markdown links provide that wrapper.
+	return (
+		<img
+			className="sl-kapa-answer-image"
+			src={src}
+			alt={imageAlt}
+			title={title}
+			loading="lazy"
+			decoding="async"
+			referrerPolicy="no-referrer"
+			style={{ maxWidth: '100%', height: 'auto' }}
+			onError={() => setHasFailed(true)}
+		/>
+	);
+}
 
 const highlightCache = new Map<string, string | null>();
 const highlightInFlight = new Map<string, Promise<string | null>>();
@@ -788,6 +830,7 @@ function ChatSurface({ title, welcomeMessage, autoOpen = false, onNewConversatio
 									{qa.answer ? (
 										<ReactMarkdown
 											components={{
+												img: ChatMarkdownImage,
 												// Fenced code blocks arrive as <pre><code>; inline code
 												// arrives as a bare <code>. react-markdown v9+ removed the
 												// `inline` prop, so nesting is the only reliable signal.

From e73373a028cb93e87a60e2d55bb129f4c71f08fb Mon Sep 17 00:00:00 2001
From: Danny Neira <16809145+dannyneira@users.noreply.github.com>
Date: Thu, 13 Aug 2026 14:01:21 -0600
Subject: [PATCH 05/10] feat(docs): add accessible image lightboxes

Co-Authored-By: Warp Agent <agent@warp.dev>
---
 src/components/ArticleImageLightbox.astro | 215 +++++++++++++++++
 src/components/CustomHead.astro           |   2 +
 src/components/KapaChatLauncher.css       | 150 +++++++++++-
 src/components/KapaChatLauncher.tsx       | 280 ++++++++++++++++++++--
 src/styles/custom.css                     | 130 ++++++++++
 5 files changed, 752 insertions(+), 25 deletions(-)
 create mode 100644 src/components/ArticleImageLightbox.astro

diff --git a/src/components/ArticleImageLightbox.astro b/src/components/ArticleImageLightbox.astro
new file mode 100644
index 000000000..63f97dbe7
--- /dev/null
+++ b/src/components/ArticleImageLightbox.astro
@@ -0,0 +1,215 @@
+---
+// A singleton, delegated article-image lightbox. Event delegation keeps it
+// active for future Starlight client-side swaps without wrapping images in
+// buttons or changing their documentation layout.
+---
+
+<script>
+	const cleanupKey = '__warpDocsArticleImageLightboxCleanup';
+	type LightboxWindow = Window & {
+		__warpDocsArticleImageLightboxCleanup?: () => void;
+	};
+
+	function installArticleImageLightbox() {
+		const lightboxWindow = window as LightboxWindow;
+		lightboxWindow[cleanupKey]?.();
+
+		const lightbox = document.createElement('div');
+		lightbox.className = 'docs-image-lightbox';
+		lightbox.hidden = true;
+		lightbox.setAttribute('role', 'dialog');
+		lightbox.setAttribute('aria-modal', 'true');
+		lightbox.setAttribute('aria-labelledby', 'docs-image-lightbox-title');
+
+		const content = document.createElement('div');
+		content.className = 'docs-image-lightbox__content';
+		const title = document.createElement('span');
+		title.id = 'docs-image-lightbox-title';
+		title.className = 'sr-only';
+		const closeButton = document.createElement('button');
+		closeButton.type = 'button';
+		closeButton.className = 'docs-image-lightbox__close';
+		closeButton.setAttribute('aria-label', 'Close expanded image');
+		closeButton.innerHTML =
+			'<svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m6 6 12 12M18 6 6 18"/></svg>';
+		const expandedImage = document.createElement('img');
+		expandedImage.className = 'docs-image-lightbox__image';
+		expandedImage.decoding = 'async';
+		expandedImage.loading = 'eager';
+		expandedImage.referrerPolicy = 'no-referrer';
+		const fallback = document.createElement('span');
+		fallback.className = 'docs-image-lightbox__fallback';
+		fallback.setAttribute('role', 'img');
+		fallback.textContent = 'Image unavailable';
+		fallback.hidden = true;
+
+		content.append(title, closeButton, expandedImage, fallback);
+		lightbox.append(content);
+		document.body.append(lightbox);
+
+		let activeTrigger: HTMLElement | null = null;
+
+		const isEligibleImage = (image: HTMLImageElement) =>
+			image.matches('main .sl-markdown-content img') &&
+			!image.closest('.not-content, #sl-kapa-panel, [data-no-lightbox]');
+
+		const isImageOnlyLink = (link: HTMLAnchorElement, image: HTMLImageElement) =>
+			link.textContent?.trim() === '' &&
+			link.children.length === 1 &&
+			link.firstElementChild?.contains(image);
+
+		const getImageTarget = (target: EventTarget | null) => {
+			if (!(target instanceof Element)) return null;
+			const image = target.closest('img');
+			if (image instanceof HTMLImageElement && isEligibleImage(image)) {
+				const link = image.closest('a');
+				if (link instanceof HTMLAnchorElement) {
+					return isImageOnlyLink(link, image) ? { image, trigger: link } : null;
+				}
+				return { image, trigger: image };
+			}
+
+			const trigger = target.closest<HTMLElement>('[data-docs-image-lightbox-trigger="true"]');
+			if (!(trigger instanceof HTMLAnchorElement)) return null;
+			const linkedImage = trigger.querySelector('img');
+			return linkedImage instanceof HTMLImageElement && isEligibleImage(linkedImage)
+				? { image: linkedImage, trigger }
+				: null;
+		};
+
+		const imageLabel = (image: HTMLImageElement) =>
+			image.alt.trim() || 'Documentation image';
+
+		const enhanceImages = () => {
+			document
+				.querySelectorAll<HTMLImageElement>('main .sl-markdown-content img')
+				.forEach((image) => {
+					if (!isEligibleImage(image)) return;
+					const link = image.closest('a');
+					if (link instanceof HTMLAnchorElement) {
+						if (!isImageOnlyLink(link, image)) return;
+						image.dataset.docsImageLightboxImage = 'true';
+						link.dataset.docsImageLightboxTrigger = 'true';
+						link.setAttribute('role', 'button');
+						link.setAttribute('aria-haspopup', 'dialog');
+						link.setAttribute('aria-label', `Expand image: ${imageLabel(image)}`);
+						return;
+					}
+
+					image.dataset.docsImageLightboxImage = 'true';
+					image.dataset.docsImageLightboxTrigger = 'true';
+					image.tabIndex = 0;
+					image.setAttribute('role', 'button');
+					image.setAttribute('aria-haspopup', 'dialog');
+					image.setAttribute('aria-label', `Expand image: ${imageLabel(image)}`);
+				});
+		};
+
+		const close = ({ restoreFocus = true } = {}) => {
+			if (lightbox.hidden) return;
+			lightbox.hidden = true;
+			expandedImage.removeAttribute('src');
+			document.documentElement.classList.remove('docs-image-lightbox-open');
+			document.body.classList.remove('docs-image-lightbox-open');
+			const trigger = activeTrigger;
+			activeTrigger = null;
+			if (restoreFocus) {
+				window.requestAnimationFrame(() => trigger?.focus());
+			}
+		};
+
+		const open = (image: HTMLImageElement, trigger: HTMLElement) => {
+			const source = image.currentSrc || image.src;
+			if (!source) return;
+
+			const label = imageLabel(image);
+			activeTrigger = trigger;
+			title.textContent = `Expanded image: ${label}`;
+			expandedImage.alt = label;
+			expandedImage.src = source;
+			expandedImage.hidden = false;
+			fallback.hidden = true;
+			fallback.setAttribute('aria-label', `${label} unavailable`);
+			lightbox.hidden = false;
+			document.documentElement.classList.add('docs-image-lightbox-open');
+			document.body.classList.add('docs-image-lightbox-open');
+			window.requestAnimationFrame(() => closeButton.focus());
+		};
+
+		const onDocumentClick = (event: MouseEvent) => {
+			const target = getImageTarget(event.target);
+			if (!target) return;
+			event.preventDefault();
+			event.stopPropagation();
+			open(target.image, target.trigger);
+		};
+
+		const onDocumentKeyDown = (event: KeyboardEvent) => {
+			if (!lightbox.hidden) {
+				if (event.key === 'Escape') {
+					event.preventDefault();
+					event.stopPropagation();
+					close();
+					return;
+				}
+				if (event.key === 'Tab') {
+					event.preventDefault();
+					closeButton.focus();
+				}
+				return;
+			}
+
+			if (event.key !== 'Enter' && event.key !== ' ') return;
+			const target = getImageTarget(event.target);
+			if (!target) return;
+			event.preventDefault();
+			open(target.image, target.trigger);
+		};
+
+		const onLightboxClick = (event: MouseEvent) => {
+			if (event.target === lightbox) close();
+		};
+
+		const onImageError = () => {
+			expandedImage.hidden = true;
+			fallback.hidden = false;
+		};
+
+		const onPageSwap = () => {
+			close({ restoreFocus: false });
+			if (!document.body.contains(lightbox)) {
+				document.body.append(lightbox);
+			}
+			enhanceImages();
+		};
+
+		const onCloseButtonClick = () => close();
+		closeButton.addEventListener('click', onCloseButtonClick);
+		expandedImage.addEventListener('error', onImageError);
+		lightbox.addEventListener('click', onLightboxClick);
+		document.addEventListener('click', onDocumentClick);
+		document.addEventListener('keydown', onDocumentKeyDown, true);
+		document.addEventListener('astro:after-swap', onPageSwap);
+		document.addEventListener('astro:page-load', onPageSwap);
+		enhanceImages();
+
+		lightboxWindow[cleanupKey] = () => {
+			close({ restoreFocus: false });
+			closeButton.removeEventListener('click', onCloseButtonClick);
+			expandedImage.removeEventListener('error', onImageError);
+			lightbox.removeEventListener('click', onLightboxClick);
+			document.removeEventListener('click', onDocumentClick);
+			document.removeEventListener('keydown', onDocumentKeyDown, true);
+			document.removeEventListener('astro:after-swap', onPageSwap);
+			document.removeEventListener('astro:page-load', onPageSwap);
+			lightbox.remove();
+			delete lightboxWindow[cleanupKey];
+		};
+	}
+
+	if (document.readyState === 'loading') {
+		document.addEventListener('DOMContentLoaded', installArticleImageLightbox, { once: true });
+	} else {
+		installArticleImageLightbox();
+	}
+</script>
diff --git a/src/components/CustomHead.astro b/src/components/CustomHead.astro
index e8bd21f19..3f52967cf 100644
--- a/src/components/CustomHead.astro
+++ b/src/components/CustomHead.astro
@@ -3,6 +3,7 @@ import Default from '@astrojs/starlight/components/Head.astro';
 import Analytics from '@vercel/analytics/astro';
 import SpeedInsights from '@vercel/speed-insights/astro';
 import RudderStackAnalytics from './RudderStackAnalytics.astro';
+import ArticleImageLightbox from './ArticleImageLightbox.astro';
 
 // Note: `<ClientRouter />` (Astro View Transitions) is intentionally NOT
 // enabled here. Starlight's sidebar scroll persistence relies on the browser
@@ -154,6 +155,7 @@ const fontsHref =
   onload="this.media='all'"
 />
 <RudderStackAnalytics />
+<ArticleImageLightbox />
 
 <Analytics />
 <SpeedInsights />
diff --git a/src/components/KapaChatLauncher.css b/src/components/KapaChatLauncher.css
index c79899bd0..f7287c8ca 100644
--- a/src/components/KapaChatLauncher.css
+++ b/src/components/KapaChatLauncher.css
@@ -23,6 +23,7 @@
 
 .sl-kapa-panel {
 	margin-left: auto;
+	position: relative;
 	display: flex;
 	flex-direction: column;
 	width: min(28rem, 100vw);
@@ -30,6 +31,7 @@
 	background: var(--sl-color-black);
 	border-left: 1px solid var(--sl-color-gray-5);
 	box-shadow: var(--sl-shadow-xl);
+	overflow: hidden;
 }
 
 
@@ -199,18 +201,56 @@
 	border-radius: var(--sl-radius-sm);
 	padding: 0.1rem 0.3rem;
 }
-.sl-kapa-answer-image {
+.sl-kapa-answer-image-button {
+	position: relative;
 	display: block;
 	box-sizing: border-box;
 	max-width: 100%;
-	height: auto;
 	margin: 0.875rem 0;
+	padding: 0;
 	border: 1px solid var(--sl-color-gray-5);
 	border-radius: var(--sl-radius-md);
 	background: var(--sl-color-black);
+	cursor: zoom-in;
+	overflow: hidden;
+}
+
+.sl-kapa-answer-image {
+	display: block;
+	box-sizing: border-box;
+	max-width: 100%;
+	height: auto;
+	background: var(--sl-color-black);
 	object-fit: contain;
 	box-shadow: 0 0.25rem 0.75rem rgb(0 0 0 / 0.18);
 }
+.sl-kapa-answer-image-button__overlay {
+	position: absolute;
+	inset: auto 0 0;
+	padding: 1.25rem 0.75rem 0.5rem;
+	background: linear-gradient(transparent, rgb(0 0 0 / 0.7));
+	color: var(--sl-color-white);
+	font-size: var(--sl-text-xs);
+	font-weight: 600;
+	line-height: 1.2;
+	opacity: 0;
+	transform: translateY(0.25rem);
+	transition:
+		opacity 0.15s ease,
+		transform 0.15s ease;
+	pointer-events: none;
+}
+
+.sl-kapa-answer-image-button:hover .sl-kapa-answer-image-button__overlay,
+.sl-kapa-answer-image-button:focus-visible .sl-kapa-answer-image-button__overlay {
+	opacity: 1;
+	transform: translateY(0);
+}
+
+.sl-kapa-answer-image-button:focus-visible {
+	outline: 2px solid var(--sl-color-accent-high);
+	outline-offset: 2px;
+}
 
 .sl-kapa-answer-image-fallback {
 	display: flex;
@@ -230,16 +270,120 @@
 }
 
 :root[data-theme='light'] .sl-kapa-answer-image {
-	border-color: color-mix(in srgb, var(--sl-color-gray-5), var(--sl-color-black) 15%);
 	background: var(--sl-color-white);
 	box-shadow: 0 0.25rem 0.75rem rgb(0 0 0 / 0.1);
 }
+:root[data-theme='light'] .sl-kapa-answer-image-button {
+	border-color: color-mix(in srgb, var(--sl-color-gray-5), var(--sl-color-black) 15%);
+	background: var(--sl-color-white);
+}
 
 :root[data-theme='light'] .sl-kapa-answer-image-fallback {
 	border-color: color-mix(in srgb, var(--sl-color-gray-4), var(--sl-color-black) 25%);
 	background: color-mix(in srgb, var(--sl-color-white), var(--sl-color-gray-6) 10%);
 	color: var(--sl-color-gray-3);
 }
+.sl-kapa-image-lightbox {
+	position: absolute;
+	inset: 0;
+	z-index: 20;
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	box-sizing: border-box;
+	padding: 1rem;
+	background: rgb(0 0 0 / 0.72);
+	backdrop-filter: blur(8px);
+	overscroll-behavior: contain;
+}
+
+.sl-kapa-image-lightbox__content {
+	position: relative;
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	box-sizing: border-box;
+	width: 100%;
+	height: 100%;
+	min-width: 0;
+	min-height: 0;
+	padding: 2.75rem 0 0;
+}
+
+.sl-kapa-image-lightbox__image {
+	display: block;
+	max-width: 100%;
+	max-height: 100%;
+	width: auto;
+	height: auto;
+	border: 1px solid rgb(255 255 255 / 0.2);
+	border-radius: var(--sl-radius-md);
+	background: var(--sl-color-black);
+	object-fit: contain;
+	box-shadow: 0 1rem 2.5rem rgb(0 0 0 / 0.4);
+}
+
+.sl-kapa-image-lightbox__close {
+	position: absolute;
+	top: 0;
+	right: 0;
+	z-index: 1;
+	display: inline-flex;
+	align-items: center;
+	justify-content: center;
+	width: 2.5rem;
+	height: 2.5rem;
+	padding: 0;
+	border: 1px solid rgb(255 255 255 / 0.25);
+	border-radius: var(--sl-radius-sm);
+	background: rgb(0 0 0 / 0.45);
+	color: var(--sl-color-white);
+	cursor: pointer;
+	transition:
+		border-color 0.15s ease,
+		background-color 0.15s ease;
+}
+
+.sl-kapa-image-lightbox__close:hover {
+	border-color: rgb(255 255 255 / 0.5);
+	background: rgb(0 0 0 / 0.7);
+}
+
+.sl-kapa-image-lightbox__close:focus-visible {
+	outline: 2px solid var(--sl-color-accent-high);
+	outline-offset: 2px;
+}
+
+.sl-kapa-image-lightbox__close svg {
+	width: 1.125rem;
+	height: 1.125rem;
+}
+
+.sl-kapa-image-lightbox__fallback {
+	width: min(100%, 20rem);
+	margin: 0;
+}
+
+:root[data-theme='light'] .sl-kapa-image-lightbox {
+	background: rgb(241 245 249 / 0.78);
+}
+
+:root[data-theme='light'] .sl-kapa-image-lightbox__image {
+	border-color: rgb(15 23 42 / 0.2);
+	background: var(--sl-color-white);
+	box-shadow: 0 1rem 2.5rem rgb(15 23 42 / 0.22);
+}
+
+:root[data-theme='light'] .sl-kapa-image-lightbox__close {
+	border-color: rgb(15 23 42 / 0.2);
+	background: rgb(255 255 255 / 0.78);
+	color: var(--sl-color-black);
+}
+
+:root[data-theme='light'] .sl-kapa-image-lightbox__close:hover {
+	border-color: rgb(15 23 42 / 0.4);
+	background: var(--sl-color-white);
+}
 
 .sl-kapa-codeblock {
 	position: relative;
diff --git a/src/components/KapaChatLauncher.tsx b/src/components/KapaChatLauncher.tsx
index 1eac0896c..839abe307 100644
--- a/src/components/KapaChatLauncher.tsx
+++ b/src/components/KapaChatLauncher.tsx
@@ -1,6 +1,16 @@
 import type { FormEvent, MouseEvent, ReactElement, ReactNode } from 'react';
 import * as Popover from '@radix-ui/react-popover';
-import { isValidElement, useEffect, useMemo, useRef, useState } from 'react';
+import {
+	Children,
+	createContext,
+	isValidElement,
+	useCallback,
+	useContext,
+	useEffect,
+	useMemo,
+	useRef,
+	useState,
+} from 'react';
 import { CaptchaAction, KapaProvider, useCaptcha, useChat } from '@kapaai/react-sdk';
 import { PUBLIC_KAPA_INTEGRATION_ID, PUBLIC_KAPA_PROJECT_ID } from 'astro:env/client';
 import { isMac, keymatch } from 'keymatch';
@@ -182,9 +192,55 @@ type ChatMarkdownImageProps = {
 	src?: string;
 	title?: string;
 };
+type ChatImageLightboxImage = {
+	alt: string;
+	src: string;
+	title?: string;
+};
+
+type ChatImageLightboxController = {
+	openImageLightbox: (image: ChatImageLightboxImage, trigger: HTMLButtonElement) => void;
+};
+
+const ChatImageLightboxContext = createContext<ChatImageLightboxController | null>(null);
+
+function isImageOnlyMarkdownLink(children: ReactNode) {
+	const items = Children.toArray(children).filter(
+		(child) => typeof child !== 'string' || child.trim().length > 0
+	);
+	return (
+		items.length === 1 &&
+		isValidElement(items[0]) &&
+		items[0].type === ChatMarkdownImage
+	);
+}
+
+function ChatMarkdownLink({
+	children,
+	href,
+	title,
+}: {
+	children?: ReactNode;
+	href?: string;
+	title?: string;
+}) {
+	// Kapa sometimes wraps an image in its source link. Keep ordinary links,
+	// but remove the image-only wrapper so the thumbnail can be a real button.
+	if (isImageOnlyMarkdownLink(children)) {
+		return <>{children}</>;
+	}
+
+	return (
+		<a href={href} title={title}>
+			{children}
+		</a>
+	);
+}
 
 function ChatMarkdownImage({ alt, src, title }: ChatMarkdownImageProps) {
 	const [hasFailed, setHasFailed] = useState(false);
+	const lightbox = useContext(ChatImageLightboxContext);
+	const triggerRef = useRef<HTMLButtonElement | null>(null);
 	const imageAlt = alt?.trim() || 'Image from Kapa answer';
 
 	useEffect(() => {
@@ -204,8 +260,9 @@ function ChatMarkdownImage({ alt, src, title }: ChatMarkdownImageProps) {
 	}
 
 	// `src` has already passed react-markdown's default safe URL transformation.
-	// Do not wrap this image in an anchor because Markdown links provide that wrapper.
-	return (
+	// Image-only Markdown links are unwrapped above to avoid nesting this button
+	// inside an anchor. Ordinary text links retain their original behavior.
+	const image = (
 		<img
 			className="sl-kapa-answer-image"
 			src={src}
@@ -218,8 +275,97 @@ function ChatMarkdownImage({ alt, src, title }: ChatMarkdownImageProps) {
 			onError={() => setHasFailed(true)}
 		/>
 	);
+
+	if (!lightbox) {
+		return image;
+	}
+	return (
+		<button
+			type="button"
+			ref={triggerRef}
+			className="sl-kapa-answer-image-button"
+			onClick={() => {
+				if (!triggerRef.current) return;
+				lightbox.openImageLightbox({ alt: imageAlt, src, title }, triggerRef.current);
+			}}
+			aria-label={`Expand image: ${imageAlt}`}
+			aria-haspopup="dialog"
+		>
+			{image}
+			<span className="sl-kapa-answer-image-button__overlay" aria-hidden="true">
+				Expand image
+			</span>
+		</button>
+	);
 }
 
+function ChatImageLightbox({
+	image,
+	onClose,
+	closeButtonRef,
+	lightboxRef,
+}: {
+	image: ChatImageLightboxImage;
+	onClose: () => void;
+	closeButtonRef: React.RefObject<HTMLButtonElement | null>;
+	lightboxRef: React.RefObject<HTMLDivElement | null>;
+}) {
+	const [hasFailed, setHasFailed] = useState(false);
+
+	useEffect(() => {
+		setHasFailed(false);
+	}, [image.src]);
+
+	return (
+		<div
+			ref={lightboxRef}
+			className="sl-kapa-image-lightbox"
+			role="dialog"
+			aria-modal="true"
+			aria-labelledby="sl-kapa-image-lightbox-title"
+			onClick={(event) => {
+				if (event.target === event.currentTarget) {
+					onClose();
+				}
+			}}
+		>
+			<div className="sl-kapa-image-lightbox__content">
+				<span id="sl-kapa-image-lightbox-title" className="sr-only">
+					Expanded image: {image.alt}
+				</span>
+				<button
+					type="button"
+					ref={closeButtonRef}
+					className="sl-kapa-image-lightbox__close"
+					onClick={onClose}
+					aria-label="Close expanded image"
+				>
+					<LuX aria-hidden="true" />
+				</button>
+				{hasFailed ? (
+					<span
+						className="sl-kapa-answer-image-fallback sl-kapa-image-lightbox__fallback"
+						role="img"
+						aria-label={`${image.alt} unavailable`}
+					>
+						Image unavailable
+					</span>
+				) : (
+					<img
+						className="sl-kapa-image-lightbox__image"
+						src={image.src}
+						alt={image.alt}
+						title={image.title}
+						loading="lazy"
+						decoding="async"
+						referrerPolicy="no-referrer"
+						onError={() => setHasFailed(true)}
+					/>
+				)}
+			</div>
+		</div>
+	);
+}
 const highlightCache = new Map<string, string | null>();
 const highlightInFlight = new Map<string, Promise<string | null>>();
 let highlightRequestQueue: Promise<void> = Promise.resolve();
@@ -467,11 +613,15 @@ function ChatSurface({ title, welcomeMessage, autoOpen = false, onNewConversatio
 	const [handoffErrorMessage, setHandoffErrorMessage] = useState<string | null>(null);
 	const [handoffSuccessMessage, setHandoffSuccessMessage] = useState<string | null>(null);
 	const [isSubmittingHandoff, setIsSubmittingHandoff] = useState(false);
+	const [imageLightbox, setImageLightbox] = useState<ChatImageLightboxImage | null>(null);
 	const messagesRef = useRef<HTMLDivElement | null>(null);
 	const dialogRef = useRef<HTMLDialogElement | null>(null);
 	const triggerRef = useRef<HTMLButtonElement | null>(null);
 	const closeButtonRef = useRef<HTMLButtonElement | null>(null);
 	const inputRef = useRef<HTMLInputElement | null>(null);
+	const imageLightboxRef = useRef<HTMLDivElement | null>(null);
+	const imageLightboxCloseButtonRef = useRef<HTMLButtonElement | null>(null);
+	const imageLightboxTriggerRef = useRef<HTMLButtonElement | null>(null);
 	const {
 		addFeedback,
 		conversation,
@@ -555,12 +705,76 @@ function ChatSurface({ title, welcomeMessage, autoOpen = false, onNewConversatio
 			dialog.close();
 		}
 	}, [isOpen]);
+	const closeImageLightbox = useCallback(() => {
+		setImageLightbox(null);
+		window.requestAnimationFrame(() => {
+			imageLightboxTriggerRef.current?.focus();
+		});
+	}, []);
+
+	const openImageLightbox = useCallback(
+		(image: ChatImageLightboxImage, trigger: HTMLButtonElement) => {
+			imageLightboxTriggerRef.current = trigger;
+			setImageLightbox(image);
+		},
+		[]
+	);
+
+	const imageLightboxController = useMemo(
+		() => ({ openImageLightbox }),
+		[openImageLightbox]
+	);
+
+	useEffect(() => {
+		if (!imageLightbox) return;
+
+		const frame = window.requestAnimationFrame(() => {
+			imageLightboxCloseButtonRef.current?.focus();
+		});
+		const onKeyDown = (event: KeyboardEvent) => {
+			if (event.key === 'Escape') {
+				event.preventDefault();
+				event.stopPropagation();
+				closeImageLightbox();
+				return;
+			}
+			if (event.key !== 'Tab') return;
+
+			const focusable = imageLightboxRef.current?.querySelectorAll<HTMLElement>(
+				'button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])'
+			);
+			if (!focusable?.length) {
+				event.preventDefault();
+				return;
+			}
+
+			const first = focusable[0];
+			const last = focusable[focusable.length - 1];
+			if (event.shiftKey && document.activeElement === first) {
+				event.preventDefault();
+				last.focus();
+			} else if (!event.shiftKey && document.activeElement === last) {
+				event.preventDefault();
+				first.focus();
+			}
+		};
+
+		window.addEventListener('keydown', onKeyDown, true);
+		return () => {
+			window.cancelAnimationFrame(frame);
+			window.removeEventListener('keydown', onKeyDown, true);
+		};
+	}, [closeImageLightbox, imageLightbox]);
 
 	useEffect(() => {
 		const onKeyDown = (event: KeyboardEvent) => {
 			if (keymatch(event, 'CmdOrCtrl+I')) {
 				if (dialogRef.current?.open) {
-					closePanel();
+					if (imageLightbox) {
+						closeImageLightbox();
+					} else {
+						closePanel();
+					}
 				} else {
 					openPanel();
 				}
@@ -572,7 +786,7 @@ function ChatSurface({ title, welcomeMessage, autoOpen = false, onNewConversatio
 		return () => {
 			window.removeEventListener('keydown', onKeyDown);
 		};
-	}, []);
+	}, [closeImageLightbox, imageLightbox]);
 
 	const hasConversation = conversation.length > 0;
 	const isBusy = isGeneratingAnswer || isPreparingAnswer;
@@ -755,6 +969,7 @@ function ChatSurface({ title, welcomeMessage, autoOpen = false, onNewConversatio
 	};
 
 	const onDialogClose = () => {
+		setImageLightbox(null);
 		setIsOpen(false);
 		restoreFocus();
 	};
@@ -782,16 +997,23 @@ function ChatSurface({ title, welcomeMessage, autoOpen = false, onNewConversatio
 				<LuMessageSquare aria-hidden="true" />
 				<span className="warp-kapa-button__label">Ask</span>
 			</button>
-			<dialog
-				ref={dialogRef}
-				id="sl-kapa-panel"
-				className="sl-kapa-dialog"
-				aria-label={title}
-				onClose={onDialogClose}
-				onClick={onDialogClick}
-			>
-				<div className="sl-kapa-panel">
-					<header className="sl-kapa-panel__header">
+			<ChatImageLightboxContext.Provider value={imageLightboxController}>
+				<dialog
+					ref={dialogRef}
+					id="sl-kapa-panel"
+					className="sl-kapa-dialog"
+					aria-label={title}
+					onClose={onDialogClose}
+					onCancel={(event) => {
+						if (imageLightbox) {
+							event.preventDefault();
+							closeImageLightbox();
+						}
+					}}
+					onClick={onDialogClick}
+				>
+					<div className="sl-kapa-panel">
+						<header className="sl-kapa-panel__header" aria-hidden={imageLightbox ? true : undefined}>
 						<button
 							type="button"
 							className="sl-kapa-icon-button sl-kapa-icon-button--ghost"
@@ -813,9 +1035,13 @@ function ChatSurface({ title, welcomeMessage, autoOpen = false, onNewConversatio
 								<LuX aria-hidden="true" />
 							</button>
 						</div>
-					</header>
+						</header>
 
-					<div className="sl-kapa-panel__body" ref={messagesRef}>
+						<div
+							className="sl-kapa-panel__body"
+							ref={messagesRef}
+							aria-hidden={imageLightbox ? true : undefined}
+						>
 						{!hasConversation && (
 							<div className="sl-kapa-empty-state">
 								<p className="sl-kapa-empty-state__title">Ask a question</p>
@@ -830,6 +1056,7 @@ function ChatSurface({ title, welcomeMessage, autoOpen = false, onNewConversatio
 									{qa.answer ? (
 										<ReactMarkdown
 											components={{
+												a: ChatMarkdownLink,
 												img: ChatMarkdownImage,
 												// Fenced code blocks arrive as <pre><code>; inline code
 												// arrives as a bare <code>. react-markdown v9+ removed the
@@ -969,8 +1196,8 @@ function ChatSurface({ title, welcomeMessage, autoOpen = false, onNewConversatio
 						))}
 
 						{error ? <div className="sl-kapa-error">{getChatErrorMessage(error)}</div> : null}
-					</div>
-					<footer className="sl-kapa-panel__footer">
+						</div>
+						<footer className="sl-kapa-panel__footer" aria-hidden={imageLightbox ? true : undefined}>
 						<form className="sl-kapa-form" onSubmit={onSubmit}>
 							<input
 								ref={inputRef}
@@ -1025,9 +1252,18 @@ function ChatSurface({ title, welcomeMessage, autoOpen = false, onNewConversatio
 								</Popover.Content>
 							</Popover.Root>
 						</div>
-					</footer>
-				</div>
-			</dialog>
+						</footer>
+						{imageLightbox ? (
+							<ChatImageLightbox
+								image={imageLightbox}
+								onClose={closeImageLightbox}
+								closeButtonRef={imageLightboxCloseButtonRef}
+								lightboxRef={imageLightboxRef}
+							/>
+						) : null}
+					</div>
+				</dialog>
+			</ChatImageLightboxContext.Provider>
 		</div>
 	);
 }
diff --git a/src/styles/custom.css b/src/styles/custom.css
index 8afdcb559..645dd1ecd 100644
--- a/src/styles/custom.css
+++ b/src/styles/custom.css
@@ -315,6 +315,136 @@ body {
   margin-left: auto;
   margin-right: auto;
 }
+/* Article images are enhanced by ArticleImageLightbox.astro with keyboard
+   dialog controls while this class adds a layout-neutral zoom affordance.
+   The script scopes enhancement to main docs content and honors
+   `data-no-lightbox` on the image or any ancestor. */
+.sl-markdown-content img[data-docs-image-lightbox-image] {
+  cursor: zoom-in;
+  transition: box-shadow 0.15s ease;
+}
+
+@media (hover: hover) {
+  .sl-markdown-content img[data-docs-image-lightbox-image]:hover {
+    box-shadow: 0 0 0 2px var(--sl-color-accent-high);
+  }
+}
+.sl-markdown-content img[data-docs-image-lightbox-trigger]:focus-visible,
+.sl-markdown-content a[data-docs-image-lightbox-trigger]:focus-visible img {
+  outline: 2px solid var(--sl-color-accent-high);
+  outline-offset: 3px;
+}
+
+html.docs-image-lightbox-open,
+body.docs-image-lightbox-open {
+  overflow: hidden;
+}
+
+.docs-image-lightbox {
+  position: fixed;
+  inset: 0;
+  z-index: 100;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  box-sizing: border-box;
+  padding: 1.5rem;
+  background: rgb(0 0 0 / 0.76);
+  backdrop-filter: blur(8px);
+}
+
+.docs-image-lightbox[hidden] {
+  display: none;
+}
+
+.docs-image-lightbox__content {
+  position: relative;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  box-sizing: border-box;
+  width: min(100%, 90rem);
+  height: 100%;
+  min-width: 0;
+  min-height: 0;
+  padding: 3.25rem 0 0;
+}
+
+.docs-image-lightbox__image {
+  display: block;
+  max-width: 100%;
+  max-height: 100%;
+  width: auto;
+  height: auto;
+  border: 1px solid rgb(255 255 255 / 0.22);
+  border-radius: var(--sl-radius-md);
+  background: var(--sl-color-black);
+  object-fit: contain;
+  box-shadow: 0 1rem 2.5rem rgb(0 0 0 / 0.45);
+}
+
+.docs-image-lightbox__close {
+  position: absolute;
+  top: 0;
+  right: 0;
+  z-index: 1;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 2.75rem;
+  height: 2.75rem;
+  padding: 0;
+  border: 1px solid rgb(255 255 255 / 0.25);
+  border-radius: var(--sl-radius-sm);
+  background: rgb(0 0 0 / 0.45);
+  color: var(--sl-color-white);
+  cursor: pointer;
+}
+
+.docs-image-lightbox__close:hover {
+  border-color: rgb(255 255 255 / 0.5);
+  background: rgb(0 0 0 / 0.7);
+}
+
+.docs-image-lightbox__close:focus-visible {
+  outline: 2px solid var(--sl-color-accent-high);
+  outline-offset: 2px;
+}
+
+.docs-image-lightbox__close svg {
+  width: 1.25rem;
+  height: 1.25rem;
+}
+
+.docs-image-lightbox__fallback {
+  max-width: min(100%, 24rem);
+  padding: 0.75rem 1rem;
+  border: 1px dashed var(--sl-color-gray-4);
+  border-radius: var(--sl-radius-md);
+  background: color-mix(in srgb, var(--sl-color-black), var(--sl-color-gray-6) 30%);
+  color: var(--sl-color-gray-3);
+}
+
+:root[data-theme='light'] .docs-image-lightbox {
+  background: rgb(241 245 249 / 0.8);
+}
+
+:root[data-theme='light'] .docs-image-lightbox__image {
+  border-color: rgb(15 23 42 / 0.2);
+  background: var(--sl-color-black);
+  box-shadow: 0 1rem 2.5rem rgb(15 23 42 / 0.24);
+}
+
+:root[data-theme='light'] .docs-image-lightbox__close {
+  border-color: rgb(15 23 42 / 0.2);
+  background: rgb(255 255 255 / 0.8);
+  color: var(--sl-color-white);
+}
+
+:root[data-theme='light'] .docs-image-lightbox__close:hover {
+  border-color: rgb(15 23 42 / 0.4);
+  background: var(--sl-color-black);
+}
 
 .sl-markdown-content figcaption {
   margin-top: 0.5rem;

From 39203501b94309e12cd66d8914f1094ed9a26cd5 Mon Sep 17 00:00:00 2001
From: Danny Neira <16809145+dannyneira@users.noreply.github.com>
Date: Thu, 13 Aug 2026 14:41:02 -0600
Subject: [PATCH 06/10] refactor(docs): share image lightbox

Co-Authored-By: Warp Agent <agent@warp.dev>
---
 src/components/ArticleImageLightbox.astro |  55 +++---
 src/components/KapaChatLauncher.css       | 103 -----------
 src/components/KapaChatLauncher.tsx       | 210 ++--------------------
 src/styles/custom.css                     |  14 +-
 4 files changed, 60 insertions(+), 322 deletions(-)

diff --git a/src/components/ArticleImageLightbox.astro b/src/components/ArticleImageLightbox.astro
index 63f97dbe7..596861616 100644
--- a/src/components/ArticleImageLightbox.astro
+++ b/src/components/ArticleImageLightbox.astro
@@ -1,7 +1,7 @@
 ---
-// A singleton, delegated article-image lightbox. Event delegation keeps it
-// active for future Starlight client-side swaps without wrapping images in
-// buttons or changing their documentation layout.
+// A singleton, delegated lightbox for article content and explicit chat image
+// triggers. Event delegation keeps it active for future Starlight client-side
+// swaps without wrapping article images in buttons or changing their layout.
 ---
 
 <script>
@@ -14,7 +14,7 @@
 		const lightboxWindow = window as LightboxWindow;
 		lightboxWindow[cleanupKey]?.();
 
-		const lightbox = document.createElement('div');
+		const lightbox = document.createElement('dialog');
 		lightbox.className = 'docs-image-lightbox';
 		lightbox.hidden = true;
 		lightbox.setAttribute('role', 'dialog');
@@ -49,9 +49,13 @@
 
 		let activeTrigger: HTMLElement | null = null;
 
-		const isEligibleImage = (image: HTMLImageElement) =>
+		const isEligibleArticleImage = (image: HTMLImageElement) =>
 			image.matches('main .sl-markdown-content img') &&
 			!image.closest('.not-content, #sl-kapa-panel, [data-no-lightbox]');
+		const isEligibleKapaImage = (image: HTMLImageElement, trigger: HTMLElement) =>
+			trigger.matches('.sl-kapa-answer-image-button') &&
+			image.matches('.sl-kapa-answer-image') &&
+			image.closest('#sl-kapa-panel') !== null;
 
 		const isImageOnlyLink = (link: HTMLAnchorElement, image: HTMLImageElement) =>
 			link.textContent?.trim() === '' &&
@@ -60,20 +64,14 @@
 
 		const getImageTarget = (target: EventTarget | null) => {
 			if (!(target instanceof Element)) return null;
-			const image = target.closest('img');
-			if (image instanceof HTMLImageElement && isEligibleImage(image)) {
-				const link = image.closest('a');
-				if (link instanceof HTMLAnchorElement) {
-					return isImageOnlyLink(link, image) ? { image, trigger: link } : null;
-				}
-				return { image, trigger: image };
-			}
-
-			const trigger = target.closest<HTMLElement>('[data-docs-image-lightbox-trigger="true"]');
-			if (!(trigger instanceof HTMLAnchorElement)) return null;
-			const linkedImage = trigger.querySelector('img');
-			return linkedImage instanceof HTMLImageElement && isEligibleImage(linkedImage)
-				? { image: linkedImage, trigger }
+			const trigger = target.closest<HTMLElement>('[data-warp-image-lightbox-trigger="true"]');
+			if (!trigger) return null;
+			const image =
+				trigger instanceof HTMLImageElement ? trigger : trigger.querySelector('img');
+			if (!(image instanceof HTMLImageElement)) return null;
+
+			return isEligibleArticleImage(image) || isEligibleKapaImage(image, trigger)
+				? { image, trigger }
 				: null;
 		};
 
@@ -84,12 +82,12 @@
 			document
 				.querySelectorAll<HTMLImageElement>('main .sl-markdown-content img')
 				.forEach((image) => {
-					if (!isEligibleImage(image)) return;
+					if (!isEligibleArticleImage(image)) return;
 					const link = image.closest('a');
 					if (link instanceof HTMLAnchorElement) {
 						if (!isImageOnlyLink(link, image)) return;
 						image.dataset.docsImageLightboxImage = 'true';
-						link.dataset.docsImageLightboxTrigger = 'true';
+						link.dataset.warpImageLightboxTrigger = 'true';
 						link.setAttribute('role', 'button');
 						link.setAttribute('aria-haspopup', 'dialog');
 						link.setAttribute('aria-label', `Expand image: ${imageLabel(image)}`);
@@ -97,7 +95,7 @@
 					}
 
 					image.dataset.docsImageLightboxImage = 'true';
-					image.dataset.docsImageLightboxTrigger = 'true';
+					image.dataset.warpImageLightboxTrigger = 'true';
 					image.tabIndex = 0;
 					image.setAttribute('role', 'button');
 					image.setAttribute('aria-haspopup', 'dialog');
@@ -107,6 +105,9 @@
 
 		const close = ({ restoreFocus = true } = {}) => {
 			if (lightbox.hidden) return;
+			if (lightbox.open) {
+				lightbox.close();
+			}
 			lightbox.hidden = true;
 			expandedImage.removeAttribute('src');
 			document.documentElement.classList.remove('docs-image-lightbox-open');
@@ -131,6 +132,9 @@
 			fallback.hidden = true;
 			fallback.setAttribute('aria-label', `${label} unavailable`);
 			lightbox.hidden = false;
+			if (!lightbox.open) {
+				lightbox.showModal();
+			}
 			document.documentElement.classList.add('docs-image-lightbox-open');
 			document.body.classList.add('docs-image-lightbox-open');
 			window.requestAnimationFrame(() => closeButton.focus());
@@ -146,6 +150,7 @@
 
 		const onDocumentKeyDown = (event: KeyboardEvent) => {
 			if (!lightbox.hidden) {
+				event.stopPropagation();
 				if (event.key === 'Escape') {
 					event.preventDefault();
 					event.stopPropagation();
@@ -169,6 +174,10 @@
 		const onLightboxClick = (event: MouseEvent) => {
 			if (event.target === lightbox) close();
 		};
+		const onLightboxCancel = (event: Event) => {
+			event.preventDefault();
+			close();
+		};
 
 		const onImageError = () => {
 			expandedImage.hidden = true;
@@ -187,6 +196,7 @@
 		closeButton.addEventListener('click', onCloseButtonClick);
 		expandedImage.addEventListener('error', onImageError);
 		lightbox.addEventListener('click', onLightboxClick);
+		lightbox.addEventListener('cancel', onLightboxCancel);
 		document.addEventListener('click', onDocumentClick);
 		document.addEventListener('keydown', onDocumentKeyDown, true);
 		document.addEventListener('astro:after-swap', onPageSwap);
@@ -198,6 +208,7 @@
 			closeButton.removeEventListener('click', onCloseButtonClick);
 			expandedImage.removeEventListener('error', onImageError);
 			lightbox.removeEventListener('click', onLightboxClick);
+			lightbox.removeEventListener('cancel', onLightboxCancel);
 			document.removeEventListener('click', onDocumentClick);
 			document.removeEventListener('keydown', onDocumentKeyDown, true);
 			document.removeEventListener('astro:after-swap', onPageSwap);
diff --git a/src/components/KapaChatLauncher.css b/src/components/KapaChatLauncher.css
index f7287c8ca..db785ed12 100644
--- a/src/components/KapaChatLauncher.css
+++ b/src/components/KapaChatLauncher.css
@@ -23,7 +23,6 @@
 
 .sl-kapa-panel {
 	margin-left: auto;
-	position: relative;
 	display: flex;
 	flex-direction: column;
 	width: min(28rem, 100vw);
@@ -31,7 +30,6 @@
 	background: var(--sl-color-black);
 	border-left: 1px solid var(--sl-color-gray-5);
 	box-shadow: var(--sl-shadow-xl);
-	overflow: hidden;
 }
 
 
@@ -283,107 +281,6 @@
 	background: color-mix(in srgb, var(--sl-color-white), var(--sl-color-gray-6) 10%);
 	color: var(--sl-color-gray-3);
 }
-.sl-kapa-image-lightbox {
-	position: absolute;
-	inset: 0;
-	z-index: 20;
-	display: flex;
-	align-items: center;
-	justify-content: center;
-	box-sizing: border-box;
-	padding: 1rem;
-	background: rgb(0 0 0 / 0.72);
-	backdrop-filter: blur(8px);
-	overscroll-behavior: contain;
-}
-
-.sl-kapa-image-lightbox__content {
-	position: relative;
-	display: flex;
-	align-items: center;
-	justify-content: center;
-	box-sizing: border-box;
-	width: 100%;
-	height: 100%;
-	min-width: 0;
-	min-height: 0;
-	padding: 2.75rem 0 0;
-}
-
-.sl-kapa-image-lightbox__image {
-	display: block;
-	max-width: 100%;
-	max-height: 100%;
-	width: auto;
-	height: auto;
-	border: 1px solid rgb(255 255 255 / 0.2);
-	border-radius: var(--sl-radius-md);
-	background: var(--sl-color-black);
-	object-fit: contain;
-	box-shadow: 0 1rem 2.5rem rgb(0 0 0 / 0.4);
-}
-
-.sl-kapa-image-lightbox__close {
-	position: absolute;
-	top: 0;
-	right: 0;
-	z-index: 1;
-	display: inline-flex;
-	align-items: center;
-	justify-content: center;
-	width: 2.5rem;
-	height: 2.5rem;
-	padding: 0;
-	border: 1px solid rgb(255 255 255 / 0.25);
-	border-radius: var(--sl-radius-sm);
-	background: rgb(0 0 0 / 0.45);
-	color: var(--sl-color-white);
-	cursor: pointer;
-	transition:
-		border-color 0.15s ease,
-		background-color 0.15s ease;
-}
-
-.sl-kapa-image-lightbox__close:hover {
-	border-color: rgb(255 255 255 / 0.5);
-	background: rgb(0 0 0 / 0.7);
-}
-
-.sl-kapa-image-lightbox__close:focus-visible {
-	outline: 2px solid var(--sl-color-accent-high);
-	outline-offset: 2px;
-}
-
-.sl-kapa-image-lightbox__close svg {
-	width: 1.125rem;
-	height: 1.125rem;
-}
-
-.sl-kapa-image-lightbox__fallback {
-	width: min(100%, 20rem);
-	margin: 0;
-}
-
-:root[data-theme='light'] .sl-kapa-image-lightbox {
-	background: rgb(241 245 249 / 0.78);
-}
-
-:root[data-theme='light'] .sl-kapa-image-lightbox__image {
-	border-color: rgb(15 23 42 / 0.2);
-	background: var(--sl-color-white);
-	box-shadow: 0 1rem 2.5rem rgb(15 23 42 / 0.22);
-}
-
-:root[data-theme='light'] .sl-kapa-image-lightbox__close {
-	border-color: rgb(15 23 42 / 0.2);
-	background: rgb(255 255 255 / 0.78);
-	color: var(--sl-color-black);
-}
-
-:root[data-theme='light'] .sl-kapa-image-lightbox__close:hover {
-	border-color: rgb(15 23 42 / 0.4);
-	background: var(--sl-color-white);
-}
 
 .sl-kapa-codeblock {
 	position: relative;
diff --git a/src/components/KapaChatLauncher.tsx b/src/components/KapaChatLauncher.tsx
index 839abe307..8dc01c617 100644
--- a/src/components/KapaChatLauncher.tsx
+++ b/src/components/KapaChatLauncher.tsx
@@ -2,10 +2,7 @@ import type { FormEvent, MouseEvent, ReactElement, ReactNode } from 'react';
 import * as Popover from '@radix-ui/react-popover';
 import {
 	Children,
-	createContext,
 	isValidElement,
-	useCallback,
-	useContext,
 	useEffect,
 	useMemo,
 	useRef,
@@ -192,17 +189,6 @@ type ChatMarkdownImageProps = {
 	src?: string;
 	title?: string;
 };
-type ChatImageLightboxImage = {
-	alt: string;
-	src: string;
-	title?: string;
-};
-
-type ChatImageLightboxController = {
-	openImageLightbox: (image: ChatImageLightboxImage, trigger: HTMLButtonElement) => void;
-};
-
-const ChatImageLightboxContext = createContext<ChatImageLightboxController | null>(null);
 
 function isImageOnlyMarkdownLink(children: ReactNode) {
 	const items = Children.toArray(children).filter(
@@ -239,8 +225,6 @@ function ChatMarkdownLink({
 
 function ChatMarkdownImage({ alt, src, title }: ChatMarkdownImageProps) {
 	const [hasFailed, setHasFailed] = useState(false);
-	const lightbox = useContext(ChatImageLightboxContext);
-	const triggerRef = useRef<HTMLButtonElement | null>(null);
 	const imageAlt = alt?.trim() || 'Image from Kapa answer';
 
 	useEffect(() => {
@@ -276,18 +260,11 @@ function ChatMarkdownImage({ alt, src, title }: ChatMarkdownImageProps) {
 		/>
 	);
 
-	if (!lightbox) {
-		return image;
-	}
 	return (
 		<button
 			type="button"
-			ref={triggerRef}
 			className="sl-kapa-answer-image-button"
-			onClick={() => {
-				if (!triggerRef.current) return;
-				lightbox.openImageLightbox({ alt: imageAlt, src, title }, triggerRef.current);
-			}}
+			data-warp-image-lightbox-trigger="true"
 			aria-label={`Expand image: ${imageAlt}`}
 			aria-haspopup="dialog"
 		>
@@ -298,74 +275,6 @@ function ChatMarkdownImage({ alt, src, title }: ChatMarkdownImageProps) {
 		</button>
 	);
 }
-
-function ChatImageLightbox({
-	image,
-	onClose,
-	closeButtonRef,
-	lightboxRef,
-}: {
-	image: ChatImageLightboxImage;
-	onClose: () => void;
-	closeButtonRef: React.RefObject<HTMLButtonElement | null>;
-	lightboxRef: React.RefObject<HTMLDivElement | null>;
-}) {
-	const [hasFailed, setHasFailed] = useState(false);
-
-	useEffect(() => {
-		setHasFailed(false);
-	}, [image.src]);
-
-	return (
-		<div
-			ref={lightboxRef}
-			className="sl-kapa-image-lightbox"
-			role="dialog"
-			aria-modal="true"
-			aria-labelledby="sl-kapa-image-lightbox-title"
-			onClick={(event) => {
-				if (event.target === event.currentTarget) {
-					onClose();
-				}
-			}}
-		>
-			<div className="sl-kapa-image-lightbox__content">
-				<span id="sl-kapa-image-lightbox-title" className="sr-only">
-					Expanded image: {image.alt}
-				</span>
-				<button
-					type="button"
-					ref={closeButtonRef}
-					className="sl-kapa-image-lightbox__close"
-					onClick={onClose}
-					aria-label="Close expanded image"
-				>
-					<LuX aria-hidden="true" />
-				</button>
-				{hasFailed ? (
-					<span
-						className="sl-kapa-answer-image-fallback sl-kapa-image-lightbox__fallback"
-						role="img"
-						aria-label={`${image.alt} unavailable`}
-					>
-						Image unavailable
-					</span>
-				) : (
-					<img
-						className="sl-kapa-image-lightbox__image"
-						src={image.src}
-						alt={image.alt}
-						title={image.title}
-						loading="lazy"
-						decoding="async"
-						referrerPolicy="no-referrer"
-						onError={() => setHasFailed(true)}
-					/>
-				)}
-			</div>
-		</div>
-	);
-}
 const highlightCache = new Map<string, string | null>();
 const highlightInFlight = new Map<string, Promise<string | null>>();
 let highlightRequestQueue: Promise<void> = Promise.resolve();
@@ -613,15 +522,11 @@ function ChatSurface({ title, welcomeMessage, autoOpen = false, onNewConversatio
 	const [handoffErrorMessage, setHandoffErrorMessage] = useState<string | null>(null);
 	const [handoffSuccessMessage, setHandoffSuccessMessage] = useState<string | null>(null);
 	const [isSubmittingHandoff, setIsSubmittingHandoff] = useState(false);
-	const [imageLightbox, setImageLightbox] = useState<ChatImageLightboxImage | null>(null);
 	const messagesRef = useRef<HTMLDivElement | null>(null);
 	const dialogRef = useRef<HTMLDialogElement | null>(null);
 	const triggerRef = useRef<HTMLButtonElement | null>(null);
 	const closeButtonRef = useRef<HTMLButtonElement | null>(null);
 	const inputRef = useRef<HTMLInputElement | null>(null);
-	const imageLightboxRef = useRef<HTMLDivElement | null>(null);
-	const imageLightboxCloseButtonRef = useRef<HTMLButtonElement | null>(null);
-	const imageLightboxTriggerRef = useRef<HTMLButtonElement | null>(null);
 	const {
 		addFeedback,
 		conversation,
@@ -705,76 +610,12 @@ function ChatSurface({ title, welcomeMessage, autoOpen = false, onNewConversatio
 			dialog.close();
 		}
 	}, [isOpen]);
-	const closeImageLightbox = useCallback(() => {
-		setImageLightbox(null);
-		window.requestAnimationFrame(() => {
-			imageLightboxTriggerRef.current?.focus();
-		});
-	}, []);
-
-	const openImageLightbox = useCallback(
-		(image: ChatImageLightboxImage, trigger: HTMLButtonElement) => {
-			imageLightboxTriggerRef.current = trigger;
-			setImageLightbox(image);
-		},
-		[]
-	);
-
-	const imageLightboxController = useMemo(
-		() => ({ openImageLightbox }),
-		[openImageLightbox]
-	);
-
-	useEffect(() => {
-		if (!imageLightbox) return;
-
-		const frame = window.requestAnimationFrame(() => {
-			imageLightboxCloseButtonRef.current?.focus();
-		});
-		const onKeyDown = (event: KeyboardEvent) => {
-			if (event.key === 'Escape') {
-				event.preventDefault();
-				event.stopPropagation();
-				closeImageLightbox();
-				return;
-			}
-			if (event.key !== 'Tab') return;
-
-			const focusable = imageLightboxRef.current?.querySelectorAll<HTMLElement>(
-				'button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])'
-			);
-			if (!focusable?.length) {
-				event.preventDefault();
-				return;
-			}
-
-			const first = focusable[0];
-			const last = focusable[focusable.length - 1];
-			if (event.shiftKey && document.activeElement === first) {
-				event.preventDefault();
-				last.focus();
-			} else if (!event.shiftKey && document.activeElement === last) {
-				event.preventDefault();
-				first.focus();
-			}
-		};
-
-		window.addEventListener('keydown', onKeyDown, true);
-		return () => {
-			window.cancelAnimationFrame(frame);
-			window.removeEventListener('keydown', onKeyDown, true);
-		};
-	}, [closeImageLightbox, imageLightbox]);
 
 	useEffect(() => {
 		const onKeyDown = (event: KeyboardEvent) => {
 			if (keymatch(event, 'CmdOrCtrl+I')) {
 				if (dialogRef.current?.open) {
-					if (imageLightbox) {
-						closeImageLightbox();
-					} else {
-						closePanel();
-					}
+					closePanel();
 				} else {
 					openPanel();
 				}
@@ -786,7 +627,7 @@ function ChatSurface({ title, welcomeMessage, autoOpen = false, onNewConversatio
 		return () => {
 			window.removeEventListener('keydown', onKeyDown);
 		};
-	}, [closeImageLightbox, imageLightbox]);
+	}, []);
 
 	const hasConversation = conversation.length > 0;
 	const isBusy = isGeneratingAnswer || isPreparingAnswer;
@@ -969,7 +810,6 @@ function ChatSurface({ title, welcomeMessage, autoOpen = false, onNewConversatio
 	};
 
 	const onDialogClose = () => {
-		setImageLightbox(null);
 		setIsOpen(false);
 		restoreFocus();
 	};
@@ -997,23 +837,16 @@ function ChatSurface({ title, welcomeMessage, autoOpen = false, onNewConversatio
 				<LuMessageSquare aria-hidden="true" />
 				<span className="warp-kapa-button__label">Ask</span>
 			</button>
-			<ChatImageLightboxContext.Provider value={imageLightboxController}>
-				<dialog
-					ref={dialogRef}
-					id="sl-kapa-panel"
-					className="sl-kapa-dialog"
-					aria-label={title}
-					onClose={onDialogClose}
-					onCancel={(event) => {
-						if (imageLightbox) {
-							event.preventDefault();
-							closeImageLightbox();
-						}
-					}}
-					onClick={onDialogClick}
-				>
+			<dialog
+				ref={dialogRef}
+				id="sl-kapa-panel"
+				className="sl-kapa-dialog"
+				aria-label={title}
+				onClose={onDialogClose}
+				onClick={onDialogClick}
+			>
 					<div className="sl-kapa-panel">
-						<header className="sl-kapa-panel__header" aria-hidden={imageLightbox ? true : undefined}>
+						<header className="sl-kapa-panel__header">
 						<button
 							type="button"
 							className="sl-kapa-icon-button sl-kapa-icon-button--ghost"
@@ -1037,11 +870,7 @@ function ChatSurface({ title, welcomeMessage, autoOpen = false, onNewConversatio
 						</div>
 						</header>
 
-						<div
-							className="sl-kapa-panel__body"
-							ref={messagesRef}
-							aria-hidden={imageLightbox ? true : undefined}
-						>
+						<div className="sl-kapa-panel__body" ref={messagesRef}>
 						{!hasConversation && (
 							<div className="sl-kapa-empty-state">
 								<p className="sl-kapa-empty-state__title">Ask a question</p>
@@ -1197,7 +1026,7 @@ function ChatSurface({ title, welcomeMessage, autoOpen = false, onNewConversatio
 
 						{error ? <div className="sl-kapa-error">{getChatErrorMessage(error)}</div> : null}
 						</div>
-						<footer className="sl-kapa-panel__footer" aria-hidden={imageLightbox ? true : undefined}>
+						<footer className="sl-kapa-panel__footer">
 						<form className="sl-kapa-form" onSubmit={onSubmit}>
 							<input
 								ref={inputRef}
@@ -1253,17 +1082,8 @@ function ChatSurface({ title, welcomeMessage, autoOpen = false, onNewConversatio
 							</Popover.Root>
 						</div>
 						</footer>
-						{imageLightbox ? (
-							<ChatImageLightbox
-								image={imageLightbox}
-								onClose={closeImageLightbox}
-								closeButtonRef={imageLightboxCloseButtonRef}
-								lightboxRef={imageLightboxRef}
-							/>
-						) : null}
 					</div>
-				</dialog>
-			</ChatImageLightboxContext.Provider>
+			</dialog>
 		</div>
 	);
 }
diff --git a/src/styles/custom.css b/src/styles/custom.css
index 645dd1ecd..bafecc856 100644
--- a/src/styles/custom.css
+++ b/src/styles/custom.css
@@ -329,8 +329,8 @@ body {
     box-shadow: 0 0 0 2px var(--sl-color-accent-high);
   }
 }
-.sl-markdown-content img[data-docs-image-lightbox-trigger]:focus-visible,
-.sl-markdown-content a[data-docs-image-lightbox-trigger]:focus-visible img {
+.sl-markdown-content img[data-warp-image-lightbox-trigger]:focus-visible,
+.sl-markdown-content a[data-warp-image-lightbox-trigger]:focus-visible img {
   outline: 2px solid var(--sl-color-accent-high);
   outline-offset: 3px;
 }
@@ -348,14 +348,24 @@ body.docs-image-lightbox-open {
   align-items: center;
   justify-content: center;
   box-sizing: border-box;
+  width: 100%;
+  max-width: none;
+  height: 100%;
+  max-height: none;
+  margin: 0;
   padding: 1.5rem;
+  border: 0;
   background: rgb(0 0 0 / 0.76);
   backdrop-filter: blur(8px);
+  overflow: hidden;
 }
 
 .docs-image-lightbox[hidden] {
   display: none;
 }
+.docs-image-lightbox::backdrop {
+  background: transparent;
+}
 
 .docs-image-lightbox__content {
   position: relative;

From bb0fc9263cd2bf04fe8d609f17c164f051f939c3 Mon Sep 17 00:00:00 2001
From: Danny Neira <16809145+dannyneira@users.noreply.github.com>
Date: Thu, 13 Aug 2026 14:58:01 -0600
Subject: [PATCH 07/10] fix(docs): close image lightbox from empty space

Co-Authored-By: Warp Agent <agent@warp.dev>
---
 src/components/ArticleImageLightbox.astro | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/src/components/ArticleImageLightbox.astro b/src/components/ArticleImageLightbox.astro
index 596861616..8f96660e8 100644
--- a/src/components/ArticleImageLightbox.astro
+++ b/src/components/ArticleImageLightbox.astro
@@ -172,7 +172,16 @@
 		};
 
 		const onLightboxClick = (event: MouseEvent) => {
-			if (event.target === lightbox) close();
+			// The content wrapper fills the dialog, so its empty top and bottom
+			// areas are visually backdrop even though they are not the dialog
+			// element itself. Only the image, close control, and fallback count
+			// as lightbox content that must not dismiss the dialog.
+			const path = event.composedPath();
+			const clickedLightboxContent = path.some(
+				(target) =>
+					target === expandedImage || target === closeButton || target === fallback
+			);
+			if (!clickedLightboxContent) close();
 		};
 		const onLightboxCancel = (event: Event) => {
 			event.preventDefault();

From 8813c7ba6410efb6a3f45a53e9fd42e7bea8c1bb Mon Sep 17 00:00:00 2001
From: Danny Neira <16809145+dannyneira@users.noreply.github.com>
Date: Thu, 13 Aug 2026 15:29:17 -0600
Subject: [PATCH 08/10] Add Warp Docs MCP connect UI

Co-Authored-By: Warp Agent <agent@warp.dev>
---
 src/components/KapaChatLauncher.css | 234 ++++++++++++++++++++++++++++
 src/components/KapaChatLauncher.tsx | 135 ++++++++++++++++
 2 files changed, 369 insertions(+)

diff --git a/src/components/KapaChatLauncher.css b/src/components/KapaChatLauncher.css
index db785ed12..178cf6cba 100644
--- a/src/components/KapaChatLauncher.css
+++ b/src/components/KapaChatLauncher.css
@@ -47,6 +47,209 @@
 	align-items: center;
 	gap: 0.5rem;
 }
+.sl-kapa-mcp-connect__trigger {
+	display: inline-flex;
+	align-items: center;
+	justify-content: center;
+	gap: 0.375rem;
+	min-height: 2rem;
+	padding: 0.375rem 0.625rem;
+	border: 1px solid color-mix(in srgb, var(--sl-color-text-accent), var(--warp-control-border) 48%);
+	border-radius: var(--sl-radius-sm);
+	background: color-mix(in srgb, var(--sl-color-text-accent), var(--warp-control-bg) 88%);
+	color: var(--sl-color-text-accent);
+	font: inherit;
+	font-size: var(--sl-text-xs);
+	font-weight: 600;
+	line-height: 1.2;
+	white-space: nowrap;
+	cursor: pointer;
+	transition:
+		border-color 0.15s ease,
+		background-color 0.15s ease,
+		color 0.15s ease;
+}
+
+.sl-kapa-mcp-connect__trigger svg {
+	width: 0.875rem;
+	height: 0.875rem;
+	flex: none;
+}
+
+.sl-kapa-mcp-connect__trigger:hover,
+.sl-kapa-mcp-connect__trigger[data-state='open'] {
+	border-color: var(--sl-color-text-accent);
+	background: color-mix(in srgb, var(--sl-color-text-accent), var(--warp-control-bg) 78%);
+	color: var(--sl-color-white);
+}
+
+.sl-kapa-mcp-connect__trigger:focus-visible,
+.sl-kapa-mcp-connect__action:focus-visible,
+.sl-kapa-mcp-connect__url:focus-visible {
+	outline: 2px solid var(--sl-color-accent-high);
+	outline-offset: 2px;
+}
+
+.sl-kapa-mcp-connect {
+	width: min(24rem, calc(100vw - 1.5rem));
+	max-width: var(--radix-popover-content-available-width);
+	max-height: var(--radix-popover-content-available-height);
+	padding: 0.875rem;
+	border: 1px solid var(--sl-color-gray-5);
+	border-radius: var(--sl-radius-lg);
+	background: color-mix(in srgb, var(--sl-color-black), var(--sl-color-gray-6) 18%);
+	box-shadow: var(--sl-shadow-lg);
+	color: var(--sl-color-gray-2);
+	overflow-y: auto;
+	z-index: 20;
+}
+
+.sl-kapa-mcp-connect__header {
+	display: flex;
+	align-items: flex-start;
+	gap: 0.625rem;
+}
+
+.sl-kapa-mcp-connect__header > svg {
+	width: 1.125rem;
+	height: 1.125rem;
+	margin-top: 0.125rem;
+	color: var(--sl-color-text-accent);
+	flex: none;
+}
+
+.sl-kapa-mcp-connect__title,
+.sl-kapa-mcp-connect__description,
+.sl-kapa-mcp-connect__eyebrow,
+.sl-kapa-mcp-connect__instructions {
+	margin: 0;
+}
+
+.sl-kapa-mcp-connect__title {
+	color: var(--sl-color-white);
+	font-size: var(--sl-text-sm);
+	font-weight: 700;
+	line-height: 1.35;
+}
+
+.sl-kapa-mcp-connect__description,
+.sl-kapa-mcp-connect__instructions {
+	margin-top: 0.25rem;
+	font-size: var(--sl-text-xs);
+	line-height: 1.45;
+}
+
+.sl-kapa-mcp-connect__section {
+	display: flex;
+	flex-direction: column;
+	align-items: stretch;
+	gap: 0.5rem;
+	margin-top: 0.875rem;
+	padding-top: 0.875rem;
+	border-top: 1px solid var(--sl-color-gray-5);
+}
+
+.sl-kapa-mcp-connect__eyebrow {
+	color: var(--sl-color-gray-3);
+	font-size: var(--sl-text-2xs);
+	font-weight: 700;
+	letter-spacing: 0.08em;
+	line-height: 1.2;
+	text-transform: uppercase;
+}
+
+.sl-kapa-mcp-connect__instructions strong {
+	color: var(--sl-color-gray-1);
+}
+
+.sl-kapa-mcp-connect__config,
+.sl-kapa-mcp-connect__url {
+	box-sizing: border-box;
+	width: 100%;
+	padding: 0.5rem 0.625rem;
+	border: 1px solid var(--sl-color-gray-5);
+	border-radius: var(--sl-radius-sm);
+	background: color-mix(in srgb, var(--sl-color-black), var(--sl-color-gray-6) 32%);
+	color: var(--sl-color-gray-1);
+	font-family: var(--__sl-font-mono, 'JetBrains Mono', 'SFMono-Regular', monospace);
+	font-size: var(--sl-text-2xs);
+	line-height: 1.5;
+	overflow-wrap: anywhere;
+}
+
+.sl-kapa-mcp-connect__config {
+	white-space: pre-wrap;
+}
+
+.sl-kapa-mcp-connect__url {
+	display: flex;
+	align-items: flex-start;
+	gap: 0.5rem;
+	color: var(--sl-color-text-accent);
+	text-decoration: none;
+}
+
+.sl-kapa-mcp-connect__url:hover {
+	border-color: var(--warp-control-border-hover);
+	color: var(--sl-color-white);
+}
+
+.sl-kapa-mcp-connect__url svg {
+	width: 0.75rem;
+	height: 0.75rem;
+	margin-top: 0.15rem;
+	flex: none;
+}
+
+.sl-kapa-mcp-connect__action {
+	display: inline-flex;
+	align-items: center;
+	justify-content: center;
+	gap: 0.375rem;
+	min-height: 2rem;
+	padding: 0.375rem 0.625rem;
+	border: 1px solid var(--warp-control-border);
+	border-radius: var(--sl-radius-sm);
+	background: var(--warp-control-bg);
+	color: var(--warp-control-text-hover);
+	font: inherit;
+	font-size: var(--sl-text-xs);
+	font-weight: 600;
+	line-height: 1.2;
+	cursor: pointer;
+	transition:
+		border-color 0.15s ease,
+		background-color 0.15s ease,
+		color 0.15s ease;
+}
+
+.sl-kapa-mcp-connect__action:hover {
+	border-color: var(--warp-control-border-hover);
+	background: var(--warp-control-bg-hover);
+	color: var(--sl-color-white);
+}
+
+.sl-kapa-mcp-connect__action--primary {
+	border-color: var(--sl-color-text-accent);
+	background: var(--sl-color-text-accent);
+	color: var(--sl-color-black);
+}
+
+.sl-kapa-mcp-connect__action--primary:hover {
+	border-color: color-mix(in srgb, var(--sl-color-text-accent), var(--sl-color-white) 18%);
+	background: color-mix(in srgb, var(--sl-color-text-accent), var(--sl-color-white) 8%);
+	color: var(--sl-color-black);
+}
+
+.sl-kapa-mcp-connect__action svg {
+	width: 0.875rem;
+	height: 0.875rem;
+	flex: none;
+}
+
+.sl-kapa-mcp-connect__arrow {
+	fill: color-mix(in srgb, var(--sl-color-black), var(--sl-color-gray-6) 18%);
+}
 
 .sl-kapa-icon-button,
 .sl-kapa-feedback__button {
@@ -910,6 +1113,37 @@
 		flex-direction: column;
 		align-items: flex-start;
 	}
+
+	.sl-kapa-panel__header {
+		padding-inline: 0.75rem;
+	}
+
+	.sl-kapa-panel__header-actions {
+		gap: 0.25rem;
+	}
+
+	.sl-kapa-mcp-connect__trigger {
+		padding-inline: 0.5rem;
+	}
+}
+
+@media (max-width: 22rem) {
+	.sl-kapa-mcp-connect__trigger span {
+		position: absolute;
+		width: 1px;
+		height: 1px;
+		padding: 0;
+		margin: -1px;
+		overflow: hidden;
+		clip: rect(0, 0, 0, 0);
+		white-space: nowrap;
+		border: 0;
+	}
+
+	.sl-kapa-mcp-connect__trigger {
+		width: 2rem;
+		padding: 0;
+	}
 }
 
 @keyframes sl-kapa-spin {
diff --git a/src/components/KapaChatLauncher.tsx b/src/components/KapaChatLauncher.tsx
index 8dc01c617..a27c181d3 100644
--- a/src/components/KapaChatLauncher.tsx
+++ b/src/components/KapaChatLauncher.tsx
@@ -14,8 +14,11 @@ import { isMac, keymatch } from 'keymatch';
 import ReactMarkdown from 'react-markdown';
 import {
 	LuExternalLink,
+	LuCheck,
+	LuCopy,
 	LuLoaderCircle,
 	LuMessageSquare,
+	LuPlug,
 	LuSend,
 	LuSquarePen,
 	LuThumbsDown,
@@ -31,8 +34,19 @@ const welcomeMessage = 'What do you want to know about Warp?';
 const uncertaintyThreshold = 0.15;
 const conversationLengthThreshold = 3;
 const emailPattern = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const warpDocsMcpUrl = 'https://warp.mcp.kapa.ai';
+const warpDocsMcpConfig = JSON.stringify(
+	{
+		'Warp Docs': {
+			url: warpDocsMcpUrl,
+		},
+	},
+	null,
+	2
+);
 
 type FeedbackReaction = 'upvote' | 'downvote';
+type McpCopyTarget = 'config' | 'url';
 type GenericRecord = Record<string, unknown>;
 type HandoffApiSuccess = {
 	message?: string;
@@ -522,11 +536,13 @@ function ChatSurface({ title, welcomeMessage, autoOpen = false, onNewConversatio
 	const [handoffErrorMessage, setHandoffErrorMessage] = useState<string | null>(null);
 	const [handoffSuccessMessage, setHandoffSuccessMessage] = useState<string | null>(null);
 	const [isSubmittingHandoff, setIsSubmittingHandoff] = useState(false);
+	const [copiedMcpValue, setCopiedMcpValue] = useState<McpCopyTarget | null>(null);
 	const messagesRef = useRef<HTMLDivElement | null>(null);
 	const dialogRef = useRef<HTMLDialogElement | null>(null);
 	const triggerRef = useRef<HTMLButtonElement | null>(null);
 	const closeButtonRef = useRef<HTMLButtonElement | null>(null);
 	const inputRef = useRef<HTMLInputElement | null>(null);
+	const mcpCopyResetRef = useRef<number | null>(null);
 	const {
 		addFeedback,
 		conversation,
@@ -541,6 +557,13 @@ function ChatSurface({ title, welcomeMessage, autoOpen = false, onNewConversatio
 	useEffect(() => {
 		setIsAppleDevice(isMac());
 	}, []);
+	useEffect(() => {
+		return () => {
+			if (mcpCopyResetRef.current !== null) {
+				window.clearTimeout(mcpCopyResetRef.current);
+			}
+		};
+	}, []);
 
 	useEffect(() => {
 		const savedThreadId = localStorage.getItem('warp_docs_kapa_thread_id');
@@ -802,6 +825,19 @@ function ChatSurface({ title, welcomeMessage, autoOpen = false, onNewConversatio
 	const closePanel = () => {
 		dialogRef.current?.close();
 	};
+	const copyMcpValue = async (target: McpCopyTarget) => {
+		const value = target === 'config' ? warpDocsMcpConfig : warpDocsMcpUrl;
+		const copied = await copyTextToClipboard(value);
+		if (!copied) return;
+		setCopiedMcpValue(target);
+		if (mcpCopyResetRef.current !== null) {
+			window.clearTimeout(mcpCopyResetRef.current);
+		}
+		mcpCopyResetRef.current = window.setTimeout(() => {
+			setCopiedMcpValue(null);
+			mcpCopyResetRef.current = null;
+		}, 1500);
+	};
 
 	const restoreFocus = () => {
 		window.requestAnimationFrame(() => {
@@ -858,6 +894,105 @@ function ChatSurface({ title, welcomeMessage, autoOpen = false, onNewConversatio
 							<LuSquarePen aria-hidden="true" />
 						</button>
 						<div className="sl-kapa-panel__header-actions">
+							<Popover.Root>
+								<Popover.Trigger asChild>
+									<button
+										type="button"
+										className="sl-kapa-mcp-connect__trigger"
+										aria-label="Connect to Warp Docs with MCP"
+									>
+										<LuPlug aria-hidden="true" />
+										<span>Connect with MCP</span>
+									</button>
+								</Popover.Trigger>
+								<Popover.Content
+									className="sl-kapa-mcp-connect"
+									side="bottom"
+									align="end"
+									sideOffset={8}
+									collisionPadding={12}
+								>
+									<div className="sl-kapa-mcp-connect__header">
+										<LuPlug aria-hidden="true" />
+										<div>
+											<p className="sl-kapa-mcp-connect__title">Connect to Warp Docs</p>
+											<p className="sl-kapa-mcp-connect__description">
+												Give agents direct access to Warp&apos;s official documentation through MCP.
+											</p>
+										</div>
+									</div>
+									<div className="sl-kapa-mcp-connect__section">
+										<p className="sl-kapa-mcp-connect__eyebrow">Use in Warp</p>
+										<p className="sl-kapa-mcp-connect__instructions">
+											In Warp, go to <strong>Settings</strong> &gt; <strong>Agents</strong> &gt;{' '}
+											<strong>MCP servers</strong>, click <strong>+ Add</strong>, and paste the
+											configuration.
+										</p>
+										<code className="sl-kapa-mcp-connect__config">{warpDocsMcpConfig}</code>
+										<button
+											type="button"
+											className="sl-kapa-mcp-connect__action sl-kapa-mcp-connect__action--primary"
+											onClick={() => {
+												void copyMcpValue('config');
+											}}
+											aria-label={
+												copiedMcpValue === 'config'
+													? 'Warp Docs MCP configuration copied'
+													: 'Copy Warp Docs MCP configuration'
+											}
+										>
+											{copiedMcpValue === 'config' ? (
+												<LuCheck aria-hidden="true" />
+											) : (
+												<LuCopy aria-hidden="true" />
+											)}
+											<span>{copiedMcpValue === 'config' ? 'Copied' : 'Copy Warp config'}</span>
+										</button>
+									</div>
+									<div className="sl-kapa-mcp-connect__section">
+										<p className="sl-kapa-mcp-connect__eyebrow">Use in another MCP client</p>
+										<p className="sl-kapa-mcp-connect__instructions">
+											Copy the official MCP URL for Claude, ChatGPT, and other compatible clients.
+										</p>
+										<a
+											className="sl-kapa-mcp-connect__url"
+											href={warpDocsMcpUrl}
+											target="_blank"
+											rel="noreferrer"
+										>
+											{warpDocsMcpUrl}
+											<LuExternalLink aria-hidden="true" />
+										</a>
+										<button
+											type="button"
+											className="sl-kapa-mcp-connect__action"
+											onClick={() => {
+												void copyMcpValue('url');
+											}}
+											aria-label={
+												copiedMcpValue === 'url'
+													? 'Warp Docs MCP URL copied'
+													: 'Copy Warp Docs MCP URL'
+											}
+										>
+											{copiedMcpValue === 'url' ? (
+												<LuCheck aria-hidden="true" />
+											) : (
+												<LuCopy aria-hidden="true" />
+											)}
+											<span>{copiedMcpValue === 'url' ? 'Copied' : 'Copy MCP URL'}</span>
+										</button>
+									</div>
+									<span className="sr-only" aria-live="polite">
+										{copiedMcpValue === 'config'
+											? 'Warp Docs MCP configuration copied to clipboard.'
+											: copiedMcpValue === 'url'
+												? 'Warp Docs MCP URL copied to clipboard.'
+												: ''}
+									</span>
+									<Popover.Arrow className="sl-kapa-mcp-connect__arrow" />
+								</Popover.Content>
+							</Popover.Root>
 							<button
 								type="button"
 								ref={closeButtonRef}

From 2003c379d2246fd16a6721de2afc33a32eb7e101 Mon Sep 17 00:00:00 2001
From: Danny Neira <16809145+dannyneira@users.noreply.github.com>
Date: Thu, 13 Aug 2026 16:19:32 -0600
Subject: [PATCH 09/10] fix(docs): make MCP endpoint copy-only

Co-Authored-By: Warp Agent <agent@warp.dev>
---
 src/components/KapaChatLauncher.css | 22 +---------------------
 src/components/KapaChatLauncher.tsx | 10 +---------
 2 files changed, 2 insertions(+), 30 deletions(-)

diff --git a/src/components/KapaChatLauncher.css b/src/components/KapaChatLauncher.css
index 178cf6cba..e617879df 100644
--- a/src/components/KapaChatLauncher.css
+++ b/src/components/KapaChatLauncher.css
@@ -84,8 +84,7 @@
 }
 
 .sl-kapa-mcp-connect__trigger:focus-visible,
-.sl-kapa-mcp-connect__action:focus-visible,
-.sl-kapa-mcp-connect__url:focus-visible {
+.sl-kapa-mcp-connect__action:focus-visible {
 	outline: 2px solid var(--sl-color-accent-high);
 	outline-offset: 2px;
 }
@@ -181,25 +180,6 @@
 	white-space: pre-wrap;
 }
 
-.sl-kapa-mcp-connect__url {
-	display: flex;
-	align-items: flex-start;
-	gap: 0.5rem;
-	color: var(--sl-color-text-accent);
-	text-decoration: none;
-}
-
-.sl-kapa-mcp-connect__url:hover {
-	border-color: var(--warp-control-border-hover);
-	color: var(--sl-color-white);
-}
-
-.sl-kapa-mcp-connect__url svg {
-	width: 0.75rem;
-	height: 0.75rem;
-	margin-top: 0.15rem;
-	flex: none;
-}
 
 .sl-kapa-mcp-connect__action {
 	display: inline-flex;
diff --git a/src/components/KapaChatLauncher.tsx b/src/components/KapaChatLauncher.tsx
index a27c181d3..0b2fc53ed 100644
--- a/src/components/KapaChatLauncher.tsx
+++ b/src/components/KapaChatLauncher.tsx
@@ -954,15 +954,7 @@ function ChatSurface({ title, welcomeMessage, autoOpen = false, onNewConversatio
 										<p className="sl-kapa-mcp-connect__instructions">
 											Copy the official MCP URL for Claude, ChatGPT, and other compatible clients.
 										</p>
-										<a
-											className="sl-kapa-mcp-connect__url"
-											href={warpDocsMcpUrl}
-											target="_blank"
-											rel="noreferrer"
-										>
-											{warpDocsMcpUrl}
-											<LuExternalLink aria-hidden="true" />
-										</a>
+										<code className="sl-kapa-mcp-connect__url">{warpDocsMcpUrl}</code>
 										<button
 											type="button"
 											className="sl-kapa-mcp-connect__action"

From b162e2ade7e340767aaccb88734c2b9fe0d99662 Mon Sep 17 00:00:00 2001
From: Danny Neira <16809145+dannyneira@users.noreply.github.com>
Date: Thu, 13 Aug 2026 16:26:28 -0600
Subject: [PATCH 10/10] fix(docs): hide MCP endpoint text

Co-Authored-By: Warp Agent <agent@warp.dev>
---
 src/components/KapaChatLauncher.css | 3 +--
 src/components/KapaChatLauncher.tsx | 1 -
 2 files changed, 1 insertion(+), 3 deletions(-)

diff --git a/src/components/KapaChatLauncher.css b/src/components/KapaChatLauncher.css
index e617879df..fd70b9fd4 100644
--- a/src/components/KapaChatLauncher.css
+++ b/src/components/KapaChatLauncher.css
@@ -161,8 +161,7 @@
 	color: var(--sl-color-gray-1);
 }
 
-.sl-kapa-mcp-connect__config,
-.sl-kapa-mcp-connect__url {
+.sl-kapa-mcp-connect__config {
 	box-sizing: border-box;
 	width: 100%;
 	padding: 0.5rem 0.625rem;
diff --git a/src/components/KapaChatLauncher.tsx b/src/components/KapaChatLauncher.tsx
index 0b2fc53ed..e395acf80 100644
--- a/src/components/KapaChatLauncher.tsx
+++ b/src/components/KapaChatLauncher.tsx
@@ -954,7 +954,6 @@ function ChatSurface({ title, welcomeMessage, autoOpen = false, onNewConversatio
 										<p className="sl-kapa-mcp-connect__instructions">
 											Copy the official MCP URL for Claude, ChatGPT, and other compatible clients.
 										</p>
-										<code className="sl-kapa-mcp-connect__url">{warpDocsMcpUrl}</code>
 										<button
 											type="button"
 											className="sl-kapa-mcp-connect__action"