Restore custom Kapa chat with trigger-based support handoff

.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=

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: [