docs: add developer and api reference tabs (#190)

* docs: add developer and api reference tabs

* fix: remove duplicate image

docs/core-concepts/calls-and-runs.mdx

@@ -0,0 +1,55 @@
+---
+title: "Calls & Runs"
+description: "The lifecycle of a call and how runs capture its results"
+---
+
+Every time a workflow executes, Dograh creates a **run**. The run is the record of that execution: what was said, what data was collected, how long it took, and what it cost.
+
+## Calls vs runs
+
+A **call** is the audio connection — whether over the phone via a telephony provider, or through the browser via Web Call.
+
+A **run** is the Dograh record of the workflow execution. Every call — outbound, inbound, web, or campaign — creates a run with the same contents: transcript, recording, gathered context, usage, and cost. Campaign runs are additionally linked to their parent campaign.
+
+## Call lifecycle
+
+The call lifecycle tracks the telephony connection — from the moment a number is dialed to when the line drops.
+
+```mermaid
+stateDiagram-v2
+    [*] --> Ringing: Number dialed
+    Ringing --> Connected: Caller answers
+    Ringing --> Ended: No answer / voicemail
+    Connected --> Ended: Conversation completes
+    Connected --> Ended: Error or disconnect
+    Ended --> [*]
+```
+
+For inbound calls, the flow starts when the caller dials in and the telephony provider routes the call to Dograh.
+
+
+## Inbound vs outbound
+
+**Outbound calls** are initiated by Dograh — you trigger them via the API or dashboard with a phone number and agent. Used for proactive outreach, reminders, and campaigns.
+
+**Inbound calls** are initiated by the caller — your telephony provider routes incoming calls to a Dograh agent via a webhook URL. Used for support lines, hotlines, and IVR replacement.
+
+## Web Calls
+
+Web Call lets you talk to your agent directly from the browser — no phone number or telephony setup required. It runs the full pipeline: STT, LLM, TTS, recording, and transcript, exactly the same as a phone call.
+
+Use it to try out your agent before going live. The run view shows the live transcript as the conversation progresses, node transitions as the workflow moves through the graph, and any tool or function calls the agent makes in real time.
+
+## What a run contains
+
+After a call completes, the run record includes:
+
+| Field | Description |
+|---|---|
+| `status` | Final run state |
+| `recording_url` | Download URL for the call audio |
+| `transcript_url` | Download URL for the conversation transcript |
+| `gathered_context` | Structured data extracted by the agent during the call |
+| `initial_context` | The data passed in when the call was triggered |
+| `usage_info` | Duration in seconds, token count |
+| `cost_info` | Cost in USD |

docs/core-concepts/campaigns.mdx

@@ -0,0 +1,100 @@
+---
+title: "Campaigns"
+sidebarTitle: "Campaigns (Bulk Outbound Calls)"
+description: "Running a voice agent against a list of contacts at scale"
+---
+
+A campaign is how you run a workflow against many contacts automatically. Instead of triggering calls one by one via the API, you upload a list of phone numbers and Dograh dials them for you — respecting scheduling windows, concurrency limits, and retry rules.
+
+## How a campaign works
+
+```mermaid
+flowchart LR
+    CSV[Contacts CSV] --> Upload[Upload to Dograh]
+    Upload --> Campaign[Create Campaign]
+    Campaign --> Schedule[Scheduling & Concurrency]
+    Schedule --> Calls[Outbound Calls]
+    Calls --> Runs[Run Records]
+    Runs --> Results[Progress & Reports]
+```
+
+1. **Upload a contacts CSV** — must have a `phone_number` column; any extra columns become `initial_context` for each call
+2. **Create the campaign** — link it to a workflow, set concurrency, time slots, and retry behaviour
+3. **Start it** — Dograh begins dialing contacts up to your concurrency limit
+4. **Monitor progress** — track processed, completed, failed, and pending counts in real time
+5. **Pause and resume** — stop and restart at any point without losing progress
+
+## The contacts CSV
+
+The CSV drives the campaign. Each row is one contact.
+
+```csv
+phone_number,customer_name,account_id,plan
++14155550100,Jane Smith,acc_001,premium
++14155550101,Bob Jones,acc_002,basic
+```
+
+Columns beyond `phone_number` are automatically passed as `initial_context` to each call, making them available as template variables in your agent's prompt — so each call can feel personalised at scale.
+
+## Scheduling and concurrency
+
+**Concurrency** controls how many calls run simultaneously. It's capped by your telephony plan. Set it conservatively to start.
+
+**Time slots** restrict when Dograh is allowed to dial — useful for respecting business hours or regulations:
+
+```json
+{
+  "timezone": "America/New_York",
+  "time_slots": [
+    { "day": "monday", "start": "09:00", "end": "17:00" },
+    { "day": "tuesday", "start": "09:00", "end": "17:00" }
+  ]
+}
+```
+
+If no time slots are set, Dograh dials continuously once the campaign is started.
+
+## Retry behaviour
+
+Dograh can automatically retry contacts who didn't answer, were busy, or went to voicemail:
+
+```json
+{
+  "retry_config": {
+    "max_attempts": 3,
+    "retry_interval_minutes": 60
+  }
+}
+```
+
+## Circuit breaker
+
+The circuit breaker automatically pauses a campaign when the call failure rate gets too high — protecting against wasted spend and telephony reputation issues caused by a misconfigured agent or a bad contact list.
+
+When enabled, Dograh monitors the failure rate within a rolling time window. If it exceeds the threshold, the campaign is paused automatically and must be manually resumed after the issue is investigated.
+
+| Setting | Default | Description |
+|---|---|---|
+| Failure Threshold (%) | `50` | Pause when the failure rate within the window exceeds this percentage |
+| Window (seconds) | `120` | Rolling time window over which the failure rate is calculated |
+| Min Calls in Window | `5` | Minimum number of calls required before the circuit breaker can trip — prevents false positives on small samples |
+
+A campaign paused by the circuit breaker behaves the same as a manually paused campaign — in-flight calls complete normally, and it can be resumed once the underlying issue is resolved.
+
+## Campaign lifecycle
+
+| Status | Meaning |
+|---|---|
+| `draft` | Created but not started |
+| `running` | Actively dialing |
+| `paused` | Stopped; resumes from where it left off |
+| `completed` | All contacts processed |
+| `failed` | Encountered a fatal error |
+
+You can pause and resume a campaign at any time. In-flight calls complete normally before a pause takes effect.
+
+## Results
+
+Each contact's call creates a run record with the full transcript, recording, and gathered context — same as a manually triggered call. Use the [Get Campaign Runs](/api-reference/campaigns/runs) endpoint to retrieve them all.
+
+See the [Campaigns API reference](/api-reference/campaigns) to get started.

docs/core-concepts/context-and-variables.mdx

@@ -0,0 +1,80 @@
+---
+title: "Context & Variables"
+description: "How data flows into, through, and out of a conversation"
+---
+
+Dograh has a simple data model for passing information through a call. Understanding it is key to building agents that feel personalised and to extracting useful results after a call.
+
+## The three context objects
+
+```
+initial_context ──► Agent ──► gathered_context
+                       │
+                 [template variables](/voice-agent/template-variables)
+                 (used in prompts)
+```
+
+### initial_context
+
+Data available to the agent before the call starts — the contact's name, account details, appointment information, anything the agent should know upfront. It can be set from several places:
+
+- **API trigger** — pass it in the request body when calling `POST /public/agent/{uuid}` or `POST /telephony/initiate-call`
+- **Campaign CSV** — columns beyond `phone_number` automatically become `initial_context` fields for each contact's call
+- **Dashboard** — set default template context variables on the agent, used when no external context is provided
+
+```json
+{
+  "phone_number": "+14155550100",
+  "initial_context": {
+    "customer_name": "Jane Smith",
+    "plan": "premium",
+    "renewal_date": "April 1"
+  }
+}
+```
+
+### Template variables
+
+Values from `initial_context` are available in your agent's prompt using `{{double_brace}}` syntax.
+
+```
+You are calling {{customer_name}} about their {{plan}} plan,
+which renews on {{renewal_date}}. Be friendly and confirm
+whether they'd like to continue.
+```
+
+When the call starts, Dograh substitutes the values before sending the prompt to the LLM — so the agent speaks naturally as if it already knows the contact.
+
+### gathered_context
+
+Data the agent collects *during* the call. You configure what to extract in the agent node's extraction settings — each variable has a name, type, and a prompt that tells the LLM what to look for.
+
+<img src="../images/extracted_variables.png" alt="Extracted variables" style={{border: "1px solid #d1d5db", borderRadius: "8px", maxWidth: "100%"}} />
+
+`gathered_context` is returned in the run record after the call completes and is available in [webhook payloads](/developer/webhooks) for downstream processing.
+
+## Data flow example
+
+```mermaid
+sequenceDiagram
+    participant App as Your System
+    participant Dog as Dograh
+    participant LLM as LLM
+
+    App->>Dog: initial_context: {customer_name: "Jane", plan: "premium"}
+    Dog->>LLM: Prompt with {{customer_name}} and {{plan}} substituted
+    LLM-->>Dog: Conversation response
+    Note over Dog,LLM: Call progresses...
+    Dog->>LLM: Extract: did the customer confirm renewal?
+    LLM-->>Dog: gathered_context: {renewal_confirmed: true}
+    Dog-->>App: Run record with gathered_context
+```
+
+## Where variables are available
+
+| Location | Variables available |
+|---|---|
+| Agent node prompts | `initial_context` fields via `{{variable_name}}` |
+| Edge conditions | Evaluated against the live conversation — no explicit variable syntax needed |
+| Webhook payload templates | All context objects via `{{initial_context.field}}`, `{{gathered_context.field}}` etc. |
+| Campaign CSV columns | CSV columns beyond `phone_number` become `initial_context` fields automatically |

docs/core-concepts/how-dograh-works.mdx

@@ -0,0 +1,87 @@
+---
+title: "How Dograh Works"
+description: "The big picture — from API call to phone conversation to transcript"
+---
+
+Dograh is a platform for building and running voice AI agents. You define a conversation flow, connect a phone number, and Dograh handles the rest — transcribing the caller's speech (STT), generating intelligent responses (LLM), speaking them back in a natural voice (TTS), and returning structured results when the call ends.
+
+## The core loop
+
+```mermaid
+sequenceDiagram
+    participant U as Dashboard / Your App
+    participant API as Dograh API
+    participant STT as Transcriber (STT)
+    participant LLM as LLM Provider
+    participant TTS as Voice Synthesizer (TTS)
+    participant Tel as Telephony Provider
+    participant Cal as Caller / Contact
+
+    U->>API: Trigger call (dashboard or API)
+    API->>Tel: Initiate outbound call
+    Tel->>Cal: Phone rings
+    Cal-->>Tel: Answers
+    Tel-->>API: Raw audio stream
+    loop Conversation
+        API->>STT: Caller audio
+        STT-->>API: Transcribed text
+        API->>LLM: Transcript + agent prompt + context
+        LLM-->>API: Agent response text
+        API->>TTS: Response text
+        TTS-->>API: Synthesized audio
+        API->>Tel: Audio stream
+        Tel->>Cal: Agent speaks
+    end
+    API->>API: Extract context, run webhooks
+    API-->>U: Run record (transcript, recording, gathered data)
+```
+
+## Key components
+
+**Workflows (Agents)**
+The conversation logic. A workflow is a graph of nodes (conversation steps) connected by edges (conditional transitions). You define what the agent says, when it moves on, and what data it collects.
+
+**Runs**
+Every execution of a workflow creates a run. The run record holds the transcript, recording, extracted data, and cost information.
+
+**Telephony**
+The phone infrastructure. Dograh connects to your telephony provider (Twilio, Vonage, etc.) to place and receive calls. The audio streams between the caller and Dograh in real time.
+
+**Transcriber (STT)**
+Converts the caller's speech to text in real time. Dograh sends the audio stream to your configured speech-to-text provider and uses the transcript to drive both the LLM and the final run record.
+
+**LLM Provider**
+Processes the transcript and the active node's prompt to generate the agent's next response. It also evaluates edge conditions to decide when to move the conversation forward.
+
+**Voice Synthesizer (TTS)**
+Converts the LLM's text response to audio and streams it back to the caller. The choice of TTS provider and voice is configurable per agent.
+
+## How it fits together
+
+When you trigger a call:
+
+1. Dograh instructs your telephony provider to dial the number
+2. When the caller answers, a real-time audio pipeline opens
+3. The caller's speech is transcribed by the STT provider
+4. The transcript is sent to the LLM with the active node's prompt and conversation history
+5. The LLM responds — the response is synthesized to audio by the TTS provider and streamed to the caller
+6. When an edge condition is met, Dograh transitions to the next node
+7. When an end node is reached, the call ends
+8. Post-call: context is extracted, webhooks fire, the run record is saved
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Workflows & Agents" href="/core-concepts/workflows-and-agents">
+    How the conversation graph works
+  </Card>
+  <Card title="Calls & Runs" href="/core-concepts/calls-and-runs">
+    The lifecycle of a call
+  </Card>
+  <Card title="Context & Variables" href="/core-concepts/context-and-variables">
+    How data flows through a conversation
+  </Card>
+  <Card title="Campaigns" href="/core-concepts/campaigns">
+    Running agents at scale
+  </Card>
+</CardGroup>

docs/core-concepts/workflows-and-agents.mdx

@@ -0,0 +1,60 @@
+---
+title: "Workflows & Agents"
+description: "How conversation flows are defined in Dograh"
+---
+
+In Dograh, what you see as an **agent** in the dashboard is called a **workflow** in the API. They are the same thing — a workflow is the underlying definition, agent is the product name for it.
+
+<Note>
+Anywhere the API says `workflow`, think "agent". Anywhere the API says `workflow_definition`, think "the conversation logic inside your agent".
+</Note>
+
+## The graph model
+
+A workflow is a **directed graph** — a set of nodes connected by edges.
+
+```mermaid
+graph LR
+    A[Start Call] -->|Caller greets| B[Qualify Intent]
+    B -->|Wants support| C[Support Agent]
+    B -->|Wants sales| D[Sales Agent]
+    C -->|Issue resolved| E[End Call]
+    D -->|Demo booked| E
+```
+
+**Nodes** are the steps in the conversation. Each node has a prompt that tells the LLM what to say and do at that point.
+
+**Edges** are the transitions between nodes. Each edge has a condition — a natural language description of when to move on. The LLM evaluates whether the condition has been met based on the conversation so far.
+
+## Node types
+
+| Type | What it does |
+|---|---|
+| `startCall` | Entry point for telephony calls. The first thing the agent says when a call connects |
+| `agentNode` | An LLM-powered conversation step. The core building block |
+| `globalNode` | Defines instructions that apply across all agent nodes (e.g. tone, language, fallback behaviour) |
+| `endCall` | Terminates the call |
+| `trigger` | Entry point for API-triggered runs (non-telephony) |
+| `webhook` | Fires an HTTP request when reached — use for CRM updates, notifications, etc. |
+| `qa` | Runs automated quality analysis on the completed call |
+
+## Edges and transitions
+
+An edge connects two nodes and fires when its condition is satisfied:
+
+<img src="../images/edge.png" alt="Edge configuration" style={{border: "1px solid #d1d5db", borderRadius: "8px", maxWidth: "100%"}} />
+
+`transition_speech` is optional — if set, the agent speaks it before moving to the next node.
+
+## Versioning
+
+Every time you update a workflow's `workflow_definition`, Dograh saves a new version while keeping the history. The current version is always what runs. Old versions are retained for auditing.
+
+## Creating workflows
+
+There are two ways to create a workflow via the API:
+
+- **From a definition** — provide the full node/edge graph yourself. Best for programmatic generation.
+- **From a template** — describe the use case in natural language and Dograh generates the initial graph using an LLM. Best for getting started quickly.
+
+See the [Workflow Definition Schema](/developer/workflow-schema) for the full field reference.