Add videos to guide for debugging voice agents (#476)

* feat(debugging): add videos, update provider status links and wording

* fix(introduction): simplify structure, address layout issues, add link icons

* fix(debugging): formatting issues

* chore(debugging): add extra bullet point on top card group

* fix(debugging): cta for assistants and workflows

* chore(debugging): add link icons

Author: goosewin

fern/debugging.mdx

@@ -8,12 +8,20 @@ slug: debugging
 
 Voice agents involve multiple AI systems working together—speech recognition, language models, and voice synthesis. When something goes wrong, systematic debugging helps you quickly identify and fix the root cause.
 
-**Common debugging scenarios:**
-- Agent doesn't understand user input correctly
-- Responses are inappropriate or inconsistent  
-- Call quality issues or audio problems
-- Tool integrations failing or returning errors
-- Workflow logic not executing as expected
+**Most common issues fall into these categories:**
+
+<CardGroup cols={2}>
+  <Card title="Speech & Understanding" icon="microphone">
+    * Agent doesn't understand user input correctly
+    * Responses are inappropriate or inconsistent
+    * Agent sounds robotic or unnatural
+  </Card>
+  <Card title="Technical & Integration" icon="gear">
+    * Call quality issues or audio problems
+    * Tool integrations failing or returning errors
+    * Workflow logic not executing as expected
+  </Card>
+</CardGroup>
 
 ## Quick diagnostics
 
@@ -23,31 +31,59 @@ Start with these immediate checks before diving deeper:
   <Step title="Test in dashboard">
     Test your voice agent directly in the [dashboard](https://dashboard.vapi.ai/):
 
-    - **Assistants**: `Dashboard > Assistants > [Select Assistant] > Talk to Assistant`
-    - **Workflows**: `Dashboard > Workflows > [Select Workflow] > Call`
+    <CardGroup cols={2}>
+      <Card title="Assistants" icon="robot">
+        Click "Talk to Assistant" to test
+      </Card>
+      <Card title="Workflows" icon="diagram-project">
+        Click "Call" to test workflow
+      </Card>
+    </CardGroup>
+    
+    **Benefits:**
     - Eliminates phone network variables
-    - Provides real-time transcript view
+    - Provides real-time transcript view  
     - Shows tool execution results immediately
   </Step>
   <Step title="Check logs">
     Navigate to the `Observe` section in your [dashboard](https://dashboard.vapi.ai/) sidebar:
 
-    - **Call Logs**: Review call transcripts, durations, and error messages
-    - **API Logs**: Check API requests and responses for integration issues  
-    - **Webhook Logs**: Verify webhook deliveries and server responses
+    <CardGroup cols={3}>
+      <Card title="Call Logs" icon="phone">
+        Review call transcripts, durations, and error messages
+      </Card>
+      <Card title="API Logs" icon="code">
+        Check API requests and responses for integration issues
+      </Card>
+      <Card title="Webhook Logs" icon="webhook">
+        Verify webhook deliveries and server responses
+      </Card>
+    </CardGroup>
   </Step>
   <Step title="Test individual components">
     Use [dashboard](https://dashboard.vapi.ai/) testing features:
 
-    - **Voice Test Suites**: `Test > Voice Test Suites` (assistants only)
-    - **Tool Testing**: `Tools > [Select Tool] > Test` with sample payloads
+    <CardGroup cols={2}>
+      <Card title="Voice Test Suites" icon="vial">
+        Automated testing for assistants
+      </Card>
+      <Card title="Tool Testing" icon="wrench">
+        Test tools with sample data
+      </Card>
+    </CardGroup>
   </Step>
   <Step title="Verify provider status">
     Check if AI service providers are experiencing issues:
 
-    - Visit [Vapi Status Page](https://status.vapi.ai/) for real-time provider status
-    - Review speech-to-text, language model, and voice synthesis availability
-    - Check for ongoing maintenance or outages
+    **Core Services:**
+    - Visit [Vapi Status Page](https://status.vapi.ai/) for Vapi service status
+    
+    **Provider Status Pages:**
+    - [OpenAI Status](https://status.openai.com/) for OpenAI language models
+    - [Anthropic Status](https://status.anthropic.com/) for Anthropic language models  
+    - [ElevenLabs Status](https://status.elevenlabs.io/) for ElevenLabs voice synthesis
+    - [Deepgram Status](https://status.deepgram.com/) for Deepgram speech-to-text
+    - And other providers' status pages as needed
   </Step>
 </Steps>
 
@@ -64,6 +100,8 @@ Navigate to `Observe > Call Logs` to:
 - See tool execution results and errors
 - Analyze conversation flow in workflows
 
+<video autoPlay loop muted src="./static/videos/debugging/call-logs.mp4" type="video/mp4" style={{ aspectRatio: '16 / 9', width: '100%' }} />
+
 ### API Logs
 
 Navigate to `Observe > API Logs` to:
@@ -72,6 +110,8 @@ Navigate to `Observe > API Logs` to:
 - Verify request payloads and response codes
 - Debug integration issues with external services
 
+<video autoPlay loop muted src="./static/videos/debugging/api-logs.mp4" type="video/mp4" style={{ aspectRatio: '16 / 9', width: '100%' }} />
+
 ### Webhook Logs
 
 Navigate to `Observe > Webhook Logs` to:
@@ -80,6 +120,8 @@ Navigate to `Observe > Webhook Logs` to:
 - Debug webhook authentication issues
 - Monitor event delivery failures
 
+<video autoPlay loop muted src="./static/videos/debugging/webhook-logs.mp4" type="video/mp4" style={{ aspectRatio: '16 / 9', width: '100%' }} />
+
 ### Voice Test Suites
 
 Navigate to `Test > Voice Test Suites` to:
@@ -88,6 +130,8 @@ Navigate to `Test > Voice Test Suites` to:
 - Verify assistant behavior across different inputs
 - Monitor performance over time
 
+<video autoPlay loop muted src="./static/videos/debugging/voice-test-suites.mp4" type="video/mp4" style={{ aspectRatio: '16 / 9', width: '100%' }} />
+
 ### Tool Testing
 
 For any tool in your `Tools` section:
@@ -96,6 +140,8 @@ For any tool in your `Tools` section:
 - Verify tool responses and error handling
 - Debug parameter extraction and API calls
 
+<video autoPlay loop muted src="./static/videos/debugging/tool-testing.mp4" type="video/mp4" style={{ aspectRatio: '16 / 9', width: '100%' }} />
+
 ## Speech and language issues
 
 | Problem | Symptoms | Solution |
@@ -138,7 +184,7 @@ For any tool in your `Tools` section:
 
 | Error Pattern | Likely Cause | Quick Fix |
 |---------------|--------------|-----------|
-| **"I didn't understand"** | Speech recognition issue | Check transcriber model, add custom keyterms |
+| **Agent misinterpreting speech** | Speech recognition issue | Check transcriber model, add custom keyterms |
 | **Irrelevant responses** | Poor prompt engineering | Be more specific in system prompt |
 | **Call drops immediately** | Configuration error | Check all required fields in assistant/workflow settings |
 | **Tool errors** | API integration issue | Test tools individually, verify endpoint URLs |
@@ -153,6 +199,9 @@ When you're stuck:
   icon="user-group"
   href="https://discord.com/invite/pUFNcf2WmH"
 >
+  <div className='absolute top-4 right-4'>
+    <Icon icon="arrow-up-right-from-square" />
+  </div>
   Join the Vapi Discord for real-time help from the community and team
 </Card>
 
@@ -161,6 +210,9 @@ When you're stuck:
   icon="book"
   href="/api-reference"
 >
+  <div className='absolute top-4 right-4'>
+    <Icon icon="arrow-up-right-from-square" />
+  </div>
   Check the API reference for detailed configuration options
 </Card>
 
@@ -169,6 +221,9 @@ When you're stuck:
   icon="fa-light fa-heartbeat"
   href="https://status.vapi.ai/"
 >
+  <div className='absolute top-4 right-4'>
+    <Icon icon="arrow-up-right-from-square" />
+  </div>
   Check real-time status of Vapi services and AI providers
 </Card>
 

fern/quickstart/introduction.mdx

@@ -43,29 +43,31 @@ Vapi offers two main primitives for building voice agents, each designed for dif
     iconType="solid"
     href="/assistants/dynamic-variables"
   >
-    **Best for:** Quick kickstart and straightforward conversations
-    
+    <div className='absolute top-4 right-4'>
+      <Icon icon="arrow-up-right-from-square" />
+    </div>
+    **Best for:** Quick kickstart for simple conversations
+    <br />
     Assistants use a single system prompt to control behavior. Perfect for:
     - Customer support chatbots
     - Simple question-answering agents
     - Getting started quickly with minimal setup
-    
-    *Control everything from one place with natural language instructions.*
   </Card>
   <Card 
     title="Workflows" 
     icon="diagram-project" 
     iconType="solid"
     href="/workflows/quickstart"
   >
+    <div className='absolute top-4 right-4'>
+      <Icon icon="arrow-up-right-from-square" />
+    </div>
     **Best for:** Complex logic and multi-step processes
-    
+    <br />
     Workflows use visual decision trees and conditional logic. Perfect for:
     - Appointment scheduling with availability checks
     - Lead qualification with branching questions
-    - Complex customer service flows with escalation paths
-    
-    *Build sophisticated branching logic without code.*
+    - Complex customer service flows with escalation
   </Card>
 </CardGroup>
 
@@ -86,8 +88,10 @@ Vapi offers two main primitives for building voice agents, each designed for dif
     iconType="solid"
     href="/quickstart/phone"
   >
-    **Start here if you want to:**
-    - Create a voice agent that can make and receive phone calls
+    <div className='absolute top-4 right-4'>
+      <Icon icon="arrow-up-right-from-square" />
+    </div>
+    - Create a voice agent for inbound/outbound calls
     - Build customer support or sales automation
     - Get started with no coding required
 
@@ -99,7 +103,9 @@ Vapi offers two main primitives for building voice agents, each designed for dif
     iconType="solid"
     href="/quickstart/web"
   >
-    **Start here if you want to:**
+    <div className='absolute top-4 right-4'>
+      <Icon icon="arrow-up-right-from-square" />
+    </div>
     - Add voice capabilities to your web application
     - Integrate voice chat into your existing product
     - Build with code and SDKs
@@ -117,35 +123,38 @@ Vapi offers two main primitives for building voice agents, each designed for dif
     iconType="solid"
     href="/examples/inbound-support"
   >
+    <div className='absolute top-4 right-4'>
+      <Icon icon="arrow-up-right-from-square" />
+    </div>
     <div class="vapi-badge vapi-badge-assistant">Built with Assistants</div>
 
     Automate inbound support calls with agents that can access your knowledge base and escalate to humans when needed.
-    
-    *View example →*
   </Card>
   <Card 
     title="Sales & Lead Qualification" 
     icon="phone-office" 
     iconType="solid"
     href="/workflows/examples/lead-qualification"
   >
+    <div className='absolute top-4 right-4'>
+      <Icon icon="arrow-up-right-from-square" />
+    </div>
     <div class="vapi-badge vapi-badge-workflow">Built with Workflows</div>
 
     Make outbound sales calls, qualify leads, and schedule appointments with sophisticated branching logic.
-    
-    *View example →*
   </Card>
   <Card 
     title="Appointment Scheduling" 
     icon="calendar-check" 
     iconType="solid"
     href="/workflows/examples/appointment-scheduling"
   >
+    <div className='absolute top-4 right-4'>
+      <Icon icon="arrow-up-right-from-square" />
+    </div>
     <div class="vapi-badge vapi-badge-workflow">Built with Workflows</div>
 
     Handle booking requests, check availability, and confirm appointments with conditional routing.
-    
-    *View example →*
   </Card>
 </CardGroup>
 
@@ -156,6 +165,9 @@ Vapi offers two main primitives for building voice agents, each designed for dif
     iconType="solid"
     href="/workflows/examples/clinic-triage-scheduling"
   >
+    <div className='absolute top-4 right-4'>
+      <Icon icon="arrow-up-right-from-square" />
+    </div>
     <div class="vapi-badge vapi-badge-workflow">Built with Workflows</div>
 
     Emergency routing and appointment scheduling for healthcare.
@@ -166,21 +178,11 @@ Vapi offers two main primitives for building voice agents, each designed for dif
     iconType="solid"
     href="/workflows/examples/ecommerce-order-management"
   >
+    <div className='absolute top-4 right-4'>
+      <Icon icon="arrow-up-right-from-square" />
+    </div>
     <div class="vapi-badge vapi-badge-workflow">Built with Workflows</div>
 
     Order tracking, returns, and customer support workflows.
   </Card>
 </CardGroup>
-
-## Ready to get started?
-
-Most users start with **phone calls** since it's the easiest way to see Vapi in action. You can create and test a working voice agent in under 5 minutes without writing any code.
-
-<Card
-  title="Start with Phone Calls →"
-  icon="phone"
-  iconType="solid"
-  href="/quickstart/phone"
->
-  Create your first voice agent and make your first call
-</Card>