docs: fix dead entry points, add first-agent tutorial, explain unexplained features (#489)

* docs: fix dead entry points, add first-agent tutorial, explain gathered_context, VAD, E.164, Langfuse, Pipecat

* docs: fix broken anchors, correct HTTPS/VAD wording per review

* docs: tighten HTTPS wording and soften single-node claims per bot review

docs/integrations/telephony/cloudonix.mdx

@@ -50,7 +50,7 @@ Watch this step-by-step guide to set up Cloudonix with Dograh AI:
    - Domain ID
    - Application Name — *optional*. Leave blank and Dograh will auto-create a Voice Application on save (with the application `url` and CXML runtime already configured) and store its name on this configuration.
 5. Click **Save Configuration**
-6. Open the configuration you just created and add at least one **phone number** (with country code in E.164 format, e.g. `+1234567890`). The default caller ID is used for outbound calls.
+6. Open the configuration you just created and add at least one **phone number** (with country code, in [E.164](https://en.wikipedia.org/wiki/E.164) format — `+` then country code then number, no spaces or dashes, e.g. `+1234567890`). The default caller ID is used for outbound calls.
 
    <Note>
      If Dograh auto-created the Voice Application for you, you still need to

docs/integrations/telephony/custom.mdx

@@ -3,6 +3,15 @@ title: "Custom Telephony Provider"
 description: "Build your own telephony provider integration for Dograh AI"
 ---
 
+## Prerequisites
+
+This guide assumes familiarity with two libraries the provider interface is built on:
+
+- **[Pipecat](https://docs.pipecat.ai)** — the open-source real-time voice/multimodal pipeline framework Dograh's call pipeline is built on. Its [`FastAPIWebsocketTransport`](https://docs.pipecat.ai/server/services/transport/fastapi-websocket) is what streams audio between the telephony provider and Dograh's pipeline — you'll be constructing one of these in your transport factory. If you haven't built a Pipecat transport or frame serializer before, skim their [transports guide](https://docs.pipecat.ai/server/base-classes/transport) first.
+- **[Pydantic](https://docs.pydantic.dev)** — used for the request/response schemas that define a provider's stored credentials (`config.py` below). If you're new to Pydantic, its [models documentation](https://docs.pydantic.dev/latest/concepts/models/) covers everything used here (`BaseModel`, `Field`, `Literal` discriminators).
+
+You don't need deep expertise in either — enough to read a `BaseModel` and a Pipecat transport class is sufficient to follow this guide.
+
 ## Overview
 
 A telephony provider is implemented as a **self-registering package** under `api/services/telephony/providers/<name>/`. The package contributes everything Dograh needs to wire the provider in — the provider class, transport factory, audio config, request/response schemas, optional HTTP routes, and the form metadata used to render its configuration UI — through a single `ProviderSpec` registered at import time.
@@ -350,7 +359,7 @@ Each provider declares its wire format through its `AudioConfig`. Common shapes:
 - **Vonage**: 16 kHz Linear PCM as binary frames
 - **Asterisk ARI**: 8 kHz Linear PCM via externalMedia
 
-The pipeline sample rate is capped at 16 kHz to satisfy VAD; transports handle resampling between the wire format and the pipeline's internal rate.
+The pipeline sample rate is capped at 16 kHz to satisfy [VAD](/configurations/interruption#what-is-vad), which only accepts 8000 Hz or 16000 Hz; transports handle resampling between the wire format and the pipeline's internal rate.
 
 ## Testing
 

docs/integrations/telephony/overview.mdx

@@ -79,7 +79,7 @@ Dograh resolves the org from the webhook's account credentials and the agent fro
 <AccordionGroup>
   <Accordion title="Calls not connecting">
     - Verify credentials are correctly configured
-    - Check phone number format (E.164 with country code, e.g. `+1234567890`)
+    - Check phone number format ([E.164](https://en.wikipedia.org/wiki/E.164) — the international standard: a `+`, then country code, then the number, no spaces or dashes, e.g. `+1234567890`)
     - Ensure webhook URLs are publicly accessible
     - Review provider-specific error logs
   </Accordion>

docs/integrations/telephony/plivo.mdx

@@ -35,7 +35,7 @@ Before setting up Plivo integration, you'll need:
    - Auth Token
    - Application ID — *optional*. Leave blank and Dograh will auto-create a Plivo Application on save (with the `answer_url` already configured) and store its Application ID on this configuration.
 4. Click **Save Configuration**
-5. Open the configuration you just created and add at least one **phone number** (with country code in E.164 format, e.g. `+1234567890`). The default caller ID is used for outbound calls.
+5. Open the configuration you just created and add at least one **phone number** (with country code, in [E.164](https://en.wikipedia.org/wiki/E.164) format — `+` then country code then number, no spaces or dashes, e.g. `+1234567890`). The default caller ID is used for outbound calls.
 
    <Note>
      If Dograh auto-created the Plivo Application for you, you still need to

docs/integrations/telephony/telnyx.mdx

@@ -34,7 +34,7 @@ Before setting up Telnyx integration, you'll need:
    - API Key
    - Call Control App ID (Connection ID) — *optional*. Leave blank and Dograh will auto-create a Call Control Application on save (with the inbound webhook URL already configured) and store its Connection ID on this configuration.
 4. Click **Save Configuration**
-5. Open the configuration you just created and add at least one **phone number** (with country code in E.164 format, e.g. `+1234567890`). The default caller ID is used for outbound calls.
+5. Open the configuration you just created and add at least one **phone number** (with country code, in [E.164](https://en.wikipedia.org/wiki/E.164) format — `+` then country code then number, no spaces or dashes, e.g. `+1234567890`). The default caller ID is used for outbound calls.
 
    <Note>
      If Dograh auto-created the Call Control Application for you, you still

docs/integrations/telephony/twilio.mdx

@@ -33,7 +33,7 @@ Before setting up Twilio integration, you'll need:
    - Account SID
    - Auth Token
 4. Click **Save Configuration**
-5. Open the configuration you just created and add at least one **phone number** (with country code in E.164 format, e.g. `+1234567890`). The default caller ID is used for outbound calls.
+5. Open the configuration you just created and add at least one **phone number** (with country code, in [E.164](https://en.wikipedia.org/wiki/E.164) format — `+` then country code then number, no spaces or dashes, e.g. `+1234567890`). The default caller ID is used for outbound calls.
 
 ### Step 3: Test Your Configuration
 

docs/integrations/telephony/vobiz.mdx

@@ -35,7 +35,7 @@ Before setting up Vobiz integration, you'll need:
    - Auth Token
    - Application ID — *optional*. Leave blank and Dograh will auto-create a Vobiz Application on save (with the `answer_url` already configured) and store its Application ID on this configuration.
 4. Click **Save Configuration**
-5. Open the configuration you just created and add at least one **phone number** (with country code in E.164 format, e.g. `+1234567890`). The default caller ID is used for outbound calls.
+5. Open the configuration you just created and add at least one **phone number** (with country code, in [E.164](https://en.wikipedia.org/wiki/E.164) format — `+` then country code then number, no spaces or dashes, e.g. `+1234567890`). The default caller ID is used for outbound calls.
 
    <Note>
      If Dograh auto-created the Vobiz Application for you, you still need to

docs/integrations/telephony/vonage.mdx

@@ -148,7 +148,7 @@ Vonage uses higher quality audio (16kHz) which provides:
   
   <Accordion title="Invalid phone number error">
     - Remove the '+' prefix for Vonage (use `14155551234` not `+14155551234`)
-    - Ensure numbers are in E.164 format without the '+'
+    - Ensure numbers are in [E.164](https://en.wikipedia.org/wiki/E.164) format (country code + number, no spaces or dashes) without the '+'
     - Verify numbers are active in your Vonage account
   </Accordion>
   
@@ -156,7 +156,7 @@ Vonage uses higher quality audio (16kHz) which provides:
     - Verify WebSocket connection is established
     - Check audio pipeline is configured for 16kHz PCM
     - Monitor WebSocket for binary audio frames
-    - Review VAD (Voice Activity Detection) settings
+    - Review [VAD (Voice Activity Detection)](/configurations/interruption#what-is-vad) behavior — this is what detects when the caller starts and stops speaking
   </Accordion>
   
   <Accordion title="Calls disconnecting early">
@@ -209,6 +209,6 @@ Check [Vonage pricing](https://www.vonage.com/communications-apis/voice/pricing/
 ## Next Steps
 
 - Test your Vonage integration with a simple workflow
-- Configure VAD settings for optimal voice detection
+- Review [VAD and interruption behavior](/configurations/interruption) for your workflow's nodes
 - Set up monitoring and alerts
 - Explore advanced features like call recording