From 36b84294b44802ccd9caca40fbd7cfe8b3e8eda5 Mon Sep 17 00:00:00 2001
From: Ajax Davis <thomasalwyndavis@gmail.com>
Date: Fri, 12 Dec 2025 10:04:46 +1000
Subject: [PATCH] docs(sdk): improve diagram tooltips and fix GitHub button
 labels

- Make tooltips more verbose with detailed explanations for each node
- Add tooltip for 'Your Tools' node
- Change GitHub button labels from 'GitHub' to 'Source'
- Fix missing </p> closing tags
---
 apps/web/src/app/sdk/page.tsx              |  4 +-
 apps/web/src/components/SDKFlowDiagram.tsx | 56 +++++++++++++++-------
 2 files changed, 41 insertions(+), 19 deletions(-)

diff --git a/apps/web/src/app/sdk/page.tsx b/apps/web/src/app/sdk/page.tsx
index 9233d8f..429d1e3 100644
--- a/apps/web/src/app/sdk/page.tsx
+++ b/apps/web/src/app/sdk/page.tsx
@@ -197,7 +197,7 @@ Use registrySearch to find tools, then registryExecute to run them.\`,
                   <svg className="w-4 h-4" viewBox="0 0 24 24" fill="currentColor">
                     <path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z" />
                   </svg>
-                  GitHub
+                  Source
                 </a>
               </div>
             </div>
@@ -323,7 +323,7 @@ Use registrySearch to find tools, then registryExecute to run them.\`,
                   <svg className="w-4 h-4" viewBox="0 0 24 24" fill="currentColor">
                     <path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z" />
                   </svg>
-                  GitHub
+                  Source
                 </a>
               </div>
             </div>
diff --git a/apps/web/src/components/SDKFlowDiagram.tsx b/apps/web/src/components/SDKFlowDiagram.tsx
index b5ad8c5..ae75bc1 100644
--- a/apps/web/src/components/SDKFlowDiagram.tsx
+++ b/apps/web/src/components/SDKFlowDiagram.tsx
@@ -525,34 +525,56 @@ export function SDKFlowDiagram(): React.ReactElement {
 
         {/* Tooltip for hovered node */}
         {hoveredNode && (
-          <div className="absolute bottom-4 left-1/2 -translate-x-1/2 px-4 py-2 bg-background border border-border rounded-lg shadow-lg text-sm">
+          <div className="absolute bottom-4 left-1/2 -translate-x-1/2 px-4 py-3 bg-background border border-border rounded-lg shadow-lg text-sm max-w-md">
+            {hoveredNode === 'your-tools' && (
+              <div className="text-foreground-secondary">
+                <span className="font-semibold text-foreground">Your existing tools</span> — Any AI
+                SDK tools you've already built or installed. These work alongside the registry tools
+                seamlessly.
+              </div>
+            )}
             {hoveredNode === 'registry-search' && (
-              <span className="text-foreground-secondary">
-                Search the registry for tools matching your needs
-              </span>
+              <div className="text-foreground-secondary">
+                <span className="font-semibold text-foreground">registrySearchTool</span> — Query
+                the TPMJS registry by keyword, category, or description. Returns tool metadata
+                including the toolId needed for execution.
+              </div>
             )}
             {hoveredNode === 'registry-execute' && (
-              <span className="text-foreground-secondary">
-                Execute any tool in a secure sandbox
-              </span>
+              <div className="text-foreground-secondary">
+                <span className="font-semibold text-foreground">registryExecuteTool</span> — Execute
+                any tool from the registry by its toolId. Pass parameters and API keys per-request.
+                Results are returned directly to your agent.
+              </div>
             )}
             {hoveredNode === 'registry' && (
-              <span className="text-foreground-secondary">1000+ verified AI SDK tools</span>
+              <div className="text-foreground-secondary">
+                <span className="font-semibold text-foreground">TPMJS Registry API</span> — Central
+                repository of 1000+ AI SDK tools. Each tool is validated, health-checked, and
+                includes schema definitions for type-safe execution.
+              </div>
             )}
             {hoveredNode === 'executor' && (
-              <span className="text-foreground-secondary">
-                Isolated Deno runtime for safe execution
-              </span>
+              <div className="text-foreground-secondary">
+                <span className="font-semibold text-foreground">Sandbox Executor</span> — Remote
+                execution environment hosted on Railway. Tools run in isolated Deno containers with
+                no access to your local system.
+              </div>
             )}
             {hoveredNode === 'metadata' && (
-              <span className="text-foreground-secondary">
-                Tool schemas, descriptions, and health status
-              </span>
+              <div className="text-foreground-secondary">
+                <span className="font-semibold text-foreground">Tool Metadata</span> — Complete tool
+                information including name, description, parameter schemas, required environment
+                variables, health status, and quality scores.
+              </div>
             )}
             {hoveredNode === 'runtime' && (
-              <span className="text-foreground-secondary">
-                Sandboxed execution with API key isolation
-              </span>
+              <div className="text-foreground-secondary">
+                <span className="font-semibold text-foreground">Secure Deno Runtime</span> — Each
+                tool execution runs in a fresh, isolated Deno sandbox. API keys are passed
+                per-request and never stored. Network access is restricted to the tool's
+                requirements.
+              </div>
             )}
           </div>
         )}