From 7c3a686981e591db6e728ecd9252182b49ade268 Mon Sep 17 00:00:00 2001
From: Todd Geist <todd.geist@proofgeist.com>
Date: Wed, 6 May 2026 14:08:15 -0700
Subject: [PATCH 1/3] docs: add installer walkthrough video

---
 .../content/docs/ai/install-and-connect.mdx   | 13 ++---
 apps/docs/src/components/YouTubeVideo.tsx     | 47 +++++++++++++++++++
 apps/docs/src/mdx-components.tsx              |  2 +
 3 files changed, 54 insertions(+), 8 deletions(-)
 create mode 100644 apps/docs/src/components/YouTubeVideo.tsx

diff --git a/apps/docs/content/docs/ai/install-and-connect.mdx b/apps/docs/content/docs/ai/install-and-connect.mdx
index 97ad8452..e331b236 100644
--- a/apps/docs/content/docs/ai/install-and-connect.mdx
+++ b/apps/docs/content/docs/ai/install-and-connect.mdx
@@ -3,16 +3,13 @@ title: Install and Connect
 description: Install ProofKit and confirm your agent can see your FileMaker file.
 ---
 
-import { Callout } from "fumadocs-ui/components/callout";
 import { Step, Steps } from "fumadocs-ui/components/steps";
 
 The first milestone is simple: your coding agent should be able to communicate with an open FileMaker file through ProofKit.
 
 ProofKit installs several pieces that work together: a FileMaker add-on, a FileMaker plug-in, a connector script, an MCP server, and agent integrations.
 
-<Callout title="TODO: Screenshot - ProofKit installer">
-  Capture the installer screen for macOS, including any step where the agent integrations are selected or confirmed.
-</Callout>
+<YouTubeVideo title="ProofKit installer walkthrough" url="https://youtu.be/w6SyH5RYx5I" />
 
 ## Install ProofKit
 
@@ -36,15 +33,15 @@ ProofKit installs several pieces that work together: a FileMaker add-on, a FileM
   </Step>
 
   <Step>
-    **Run the Connect to MCP script.**
+    **Enable the ProofKit plug-in.**
 
-    In FileMaker Pro, run the **Connect to MCP** script installed by the add-on. It opens the connector Web Viewer that registers your file with the local MCP server.
+    In FileMaker Pro, open the Plug-Ins settings and confirm the ProofKit plug-in is enabled. The **Connect to MCP** script needs this plug-in to communicate with the local MCP server.
   </Step>
 
   <Step>
-    **Keep the connector open and enable the plug-in if asked.**
+    **Run the Connect to MCP script.**
 
-    Leave the connector Web Viewer open in Browse mode while you work. The plug-in provides the local API used by the MCP server and the Web Viewer proxy used for verification.
+    In FileMaker Pro, run the **Connect to MCP** script installed by the add-on. It opens the connector Web Viewer that registers your file with the local MCP server. Leave the connector Web Viewer open in Browse mode while you work.
   </Step>
 </Steps>
 
diff --git a/apps/docs/src/components/YouTubeVideo.tsx b/apps/docs/src/components/YouTubeVideo.tsx
new file mode 100644
index 00000000..ff8581b3
--- /dev/null
+++ b/apps/docs/src/components/YouTubeVideo.tsx
@@ -0,0 +1,47 @@
+interface YouTubeVideoProps {
+  title: string;
+  videoId?: string;
+  url?: string;
+}
+
+function getYouTubeVideoId({ url, videoId }: Pick<YouTubeVideoProps, "url" | "videoId">): string {
+  if (videoId) {
+    return videoId;
+  }
+
+  if (!url) {
+    throw new Error("YouTubeVideo requires either a url or videoId.");
+  }
+
+  const parsedUrl = new URL(url);
+
+  if (parsedUrl.hostname === "youtu.be") {
+    return parsedUrl.pathname.slice(1);
+  }
+
+  if (parsedUrl.pathname.startsWith("/embed/")) {
+    return parsedUrl.pathname.split("/")[2] ?? "";
+  }
+
+  return parsedUrl.searchParams.get("v") ?? "";
+}
+
+export function YouTubeVideo(props: YouTubeVideoProps) {
+  const videoId = getYouTubeVideoId(props);
+  const src = `https://www.youtube-nocookie.com/embed/${videoId}`;
+
+  return (
+    <div className="my-6 overflow-hidden rounded-xl border bg-fd-card shadow-md">
+      <div className="relative aspect-video">
+        <iframe
+          allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
+          allowFullScreen
+          className="absolute inset-0 h-full w-full"
+          referrerPolicy="strict-origin-when-cross-origin"
+          src={src}
+          title={props.title}
+        />
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/mdx-components.tsx b/apps/docs/src/mdx-components.tsx
index 42a9c86f..d08ad112 100644
--- a/apps/docs/src/mdx-components.tsx
+++ b/apps/docs/src/mdx-components.tsx
@@ -6,6 +6,7 @@ import { Tab, Tabs } from "fumadocs-ui/components/tabs";
 import defaultComponents from "fumadocs-ui/mdx";
 import type { MDXComponents } from "mdx/types";
 import { Mermaid } from "@/components/Mermaid";
+import { YouTubeVideo } from "@/components/YouTubeVideo";
 
 const generator = createGenerator();
 
@@ -16,6 +17,7 @@ export function getMDXComponents(components?: MDXComponents): MDXComponents {
     Mermaid,
     Tab,
     Tabs,
+    YouTubeVideo,
     ...Twoslash,
     ...components,
   };

From 2a9af3c874819e3037e643fafd042c69065e6dd7 Mon Sep 17 00:00:00 2001
From: Todd Geist <todd.geist@proofgeist.com>
Date: Wed, 6 May 2026 14:12:46 -0700
Subject: [PATCH 2/3] docs: fail fast for invalid YouTube URLs

---
 apps/docs/src/components/YouTubeVideo.tsx | 17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)

diff --git a/apps/docs/src/components/YouTubeVideo.tsx b/apps/docs/src/components/YouTubeVideo.tsx
index ff8581b3..74b8b7a2 100644
--- a/apps/docs/src/components/YouTubeVideo.tsx
+++ b/apps/docs/src/components/YouTubeVideo.tsx
@@ -16,14 +16,25 @@ function getYouTubeVideoId({ url, videoId }: Pick<YouTubeVideoProps, "url" | "vi
   const parsedUrl = new URL(url);
 
   if (parsedUrl.hostname === "youtu.be") {
-    return parsedUrl.pathname.slice(1);
+    const idFromShortUrl = parsedUrl.pathname.slice(1);
+    if (idFromShortUrl) {
+      return idFromShortUrl;
+    }
   }
 
   if (parsedUrl.pathname.startsWith("/embed/")) {
-    return parsedUrl.pathname.split("/")[2] ?? "";
+    const idFromEmbedPath = parsedUrl.pathname.split("/")[2];
+    if (idFromEmbedPath) {
+      return idFromEmbedPath;
+    }
   }
 
-  return parsedUrl.searchParams.get("v") ?? "";
+  const idFromQuery = parsedUrl.searchParams.get("v");
+  if (idFromQuery) {
+    return idFromQuery;
+  }
+
+  throw new Error(`Unable to extract YouTube video ID from URL: ${parsedUrl.href}`);
 }
 
 export function YouTubeVideo(props: YouTubeVideoProps) {

From 8287db501ed19c146ee5c6de93a095f1861fb6ee Mon Sep 17 00:00:00 2001
From: Todd Geist <todd.geist@proofgeist.com>
Date: Wed, 6 May 2026 14:17:21 -0700
Subject: [PATCH 3/3] docs: validate YouTube embed IDs

---
 apps/docs/src/components/YouTubeVideo.tsx | 35 +++++++++++++++++++----
 1 file changed, 29 insertions(+), 6 deletions(-)

diff --git a/apps/docs/src/components/YouTubeVideo.tsx b/apps/docs/src/components/YouTubeVideo.tsx
index 74b8b7a2..cb017d98 100644
--- a/apps/docs/src/components/YouTubeVideo.tsx
+++ b/apps/docs/src/components/YouTubeVideo.tsx
@@ -4,9 +4,27 @@ interface YouTubeVideoProps {
   url?: string;
 }
 
+const YOUTUBE_HOSTS = new Set([
+  "youtube.com",
+  "www.youtube.com",
+  "m.youtube.com",
+  "youtu.be",
+  "youtube-nocookie.com",
+  "www.youtube-nocookie.com",
+]);
+const YOUTUBE_VIDEO_ID_PATTERN = /^[A-Za-z0-9_-]{11}$/;
+
+function validateYouTubeVideoId(videoId: string, source: string): string {
+  if (YOUTUBE_VIDEO_ID_PATTERN.test(videoId)) {
+    return videoId;
+  }
+
+  throw new Error(`Invalid YouTube video ID from ${source}: ${videoId}`);
+}
+
 function getYouTubeVideoId({ url, videoId }: Pick<YouTubeVideoProps, "url" | "videoId">): string {
   if (videoId) {
-    return videoId;
+    return validateYouTubeVideoId(videoId, "videoId");
   }
 
   if (!url) {
@@ -14,24 +32,29 @@ function getYouTubeVideoId({ url, videoId }: Pick<YouTubeVideoProps, "url" | "vi
   }
 
   const parsedUrl = new URL(url);
+  const hostname = parsedUrl.hostname.toLowerCase();
+
+  if (!YOUTUBE_HOSTS.has(hostname)) {
+    throw new Error(`Unsupported YouTube URL host: ${parsedUrl.hostname}`);
+  }
 
-  if (parsedUrl.hostname === "youtu.be") {
-    const idFromShortUrl = parsedUrl.pathname.slice(1);
+  if (hostname === "youtu.be") {
+    const idFromShortUrl = parsedUrl.pathname.split("/").filter(Boolean)[0];
     if (idFromShortUrl) {
-      return idFromShortUrl;
+      return validateYouTubeVideoId(idFromShortUrl, parsedUrl.href);
     }
   }
 
   if (parsedUrl.pathname.startsWith("/embed/")) {
     const idFromEmbedPath = parsedUrl.pathname.split("/")[2];
     if (idFromEmbedPath) {
-      return idFromEmbedPath;
+      return validateYouTubeVideoId(idFromEmbedPath, parsedUrl.href);
     }
   }
 
   const idFromQuery = parsedUrl.searchParams.get("v");
   if (idFromQuery) {
-    return idFromQuery;
+    return validateYouTubeVideoId(idFromQuery, parsedUrl.href);
   }
 
   throw new Error(`Unable to extract YouTube video ID from URL: ${parsedUrl.href}`);