+
+`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 |
diff --git a/docs/core-concepts/how-dograh-works.mdx b/docs/core-concepts/how-dograh-works.mdx
new file mode 100644
index 0000000..2b5eba1
--- /dev/null
+++ b/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
+
+
+
+`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.
diff --git a/docs/developer/environment-variables.mdx b/docs/developer/environment-variables.mdx
new file mode 100644
index 0000000..f39d3b0
--- /dev/null
+++ b/docs/developer/environment-variables.mdx
@@ -0,0 +1,144 @@
+---
+title: "Environment Variables"
+description: "Complete reference for all environment variables used by the Dograh backend"
+---
+
+Core environment variables are centralized in `api/constants.py`. Variables marked **Required** in the description must be explicitly set — the application will either fail to boot or behave insecurely without them.
+
+## Deployment Modes
+
+Dograh supports two deployment modes, set via `DEPLOYMENT_MODE`:
+
+- **OSS**: The default mode. Designed for self-hosted deployments using [Docker Compose](/deployment/docker) — the fastest way to get Dograh running. Uses local JWT authentication and MinIO for storage.
+- **SaaS**: Intended for customised deployments outside of Docker. Authentication and API key management are handled through Dograh Managed Platform Services (MPS), allowing greater flexibility in how the platform is hosted and integrated.
+
+The relevant required variables for each mode are noted in the descriptions below.
+
+---
+
+## Application
+
+| Variable | Default | Description |
+|---|---|---|
+| `ENVIRONMENT` | `local` | Runtime environment. Affects logging and behaviour. One of `local`, `production`, `test` |
+| `DEPLOYMENT_MODE` | `oss` | Deployment mode. Use `oss` for self-hosted |
+| `AUTH_PROVIDER` | `local` | Authentication provider. Use `local` for OSS |
+| `ENABLE_TRACING` | `false` | Enable distributed tracing via [Langfuse](/configurations/tracing) |
+
+---
+
+## Database
+
+| Variable | Default | Description |
+|---|---|---|
+| `DATABASE_URL` | N/A | **Required.** PostgreSQL connection string. e.g. `postgresql+asyncpg://user:pass@host:5432/dbname` |
+| `REDIS_URL` | N/A | **Required.** Redis connection string. e.g. `redis://localhost:6379` |
+
+---
+
+## Authentication (OSS)
+
+| Variable | Default | Description |
+|---|---|---|
+| `OSS_JWT_SECRET` | N/A | **Required for OSS deployments.** Secret used to sign JWT tokens. Must be set to a strong random value in production |
+| `OSS_JWT_EXPIRY_HOURS` | `720` | JWT token lifetime in hours (default: 30 days) |
+
+)S%19@E@{eLOw+kvy3^gyZXy_*
z$+D<;gx*iw+(wurck!2u#^^;G