Merge remote-tracking branch 'origin/main' into feat/user-onboarding

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

@@ -18,20 +18,10 @@ initial_context ──► Agent ──► gathered_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"
-  }
-}
-```
+- **[API trigger](/voice-agent/api-trigger)** — pass it in the request body when calling `POST /public/agent/{uuid}` or `POST /telephony/initiate-call`
+- **[Campaign CSV](/core-concepts/campaigns)** — columns beyond `phone_number` automatically become `initial_context` fields for each contact's call
+- **[Pre-call data fetch](/voice-agent/pre-call-data-fetch)** — enrich the context with data from your CRM or ERP via an HTTP call as the call starts, before the agent speaks
+- **[Agent Settings](/voice-agent/template-variables#using-template-variables-for-testing)** — set template context variables on the agent for testing; they're included in test calls from the workflow editor and ignored on production calls
 
 ### Template variables
 
@@ -103,7 +93,7 @@ Data the agent collects *during* the call. You configure what to extract in the
 
 <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.
+`gathered_context` is returned in the run record after the call completes and is available in [webhook payloads](/developer/webhooks) for downstream processing. It is **not** available as a template variable in Agent prompts — prompts can only reference `initial_context` fields.
 
 ## Data flow example
 

docs/deployment/docker.mdx

@@ -20,18 +20,27 @@ Watch the video tutorial below for a step-by-step walkthrough of setting up Dogr
   allowFullScreen
 ></iframe>
 
-For local development and testing, you can run Dograh AI directly on your machine using Docker with a single command.
+For local development and testing, you can run Dograh AI directly on your machine using Docker with a small startup script.
 
 ### Quick Start
 
-Run this single command to download and start Dograh AI:
+Download the compose file and starter script, then confirm the prompt to start Dograh AI:
 
-```bash
-curl -o docker-compose.yaml https://raw.githubusercontent.com/dograh-hq/dograh/main/docker-compose.yaml && REGISTRY=ghcr.io/dograh-hq ENABLE_TELEMETRY=true docker compose up --pull always
+<CodeGroup>
+```bash macOS/Linux
+curl -o docker-compose.yaml https://raw.githubusercontent.com/dograh-hq/dograh/main/docker-compose.yaml && curl -o start_docker.sh https://raw.githubusercontent.com/dograh-hq/dograh/main/scripts/start_docker.sh && chmod +x start_docker.sh && ./start_docker.sh
 ```
+```powershell Windows
+Invoke-WebRequest -OutFile docker-compose.yaml https://raw.githubusercontent.com/dograh-hq/dograh/main/docker-compose.yaml
+Invoke-WebRequest -OutFile start_docker.ps1 https://raw.githubusercontent.com/dograh-hq/dograh/main/scripts/start_docker.ps1
+.\start_docker.ps1
+```
+</CodeGroup>
 
-This command:
+This setup:
 - Downloads the latest docker-compose.yaml
+- Creates `OSS_JWT_SECRET` in `.env` if one does not already exist
+- Prompts before running Docker Compose
 - Starts all required services including PostgreSQL, Redis, MinIO, API, and UI
 - Pulls the latest images automatically
 
@@ -43,7 +52,7 @@ http://localhost:3010
 ```
 
 <Note>
-You can disable telemetry by setting `ENABLE_TELEMETRY=false` in the command above.
+You can disable telemetry by setting `ENABLE_TELEMETRY=false` before running `./start_docker.sh` or `.\start_docker.ps1`.
 </Note>
 
 ### Troubleshooting WebRTC Connectivity
@@ -72,7 +81,7 @@ The script will prompt you for:
 - The host browsers should use to reach TURN (press Enter for `127.0.0.1`; use your LAN IP if testing from another device on the same network)
 - A shared secret for the TURN server (press Enter to generate a random one)
 
-It creates `docker-compose.yaml`, a `.env` file with TURN credentials, and the small helper bundle that `dograh-init` uses to render coturn config at startup. Start the stack with the `local-turn` profile so coturn comes up alongside the other services:
+It creates `docker-compose.yaml`, a `.env` file with JWT and TURN credentials, and the small helper bundle that `dograh-init` uses to render coturn config at startup. Start the stack with the `local-turn` profile so coturn comes up alongside the other services:
 
 ```bash
 docker compose --profile local-turn up --pull always

docs/deployment/update.mdx

@@ -67,12 +67,20 @@ The script overwrites `docker-compose.yaml` and the remote helper bundle (`remot
 
 ## Local deployment
 
-For local Docker installs (the [Quick Start](/deployment/docker#quick-start) flow or `setup_local.sh` / `setup_local.ps1`), there are no host-side config files to refresh — pull new images and restart:
+For local Docker installs (the [Quick Start](/deployment/docker#quick-start) flow or `setup_local.sh` / `setup_local.ps1`), there are no host-side config files to refresh — stop the stack, then use the startup script to preserve `OSS_JWT_SECRET` and pull new images:
 
-```bash
+<CodeGroup>
+```bash macOS/Linux
+curl -o start_docker.sh https://raw.githubusercontent.com/dograh-hq/dograh/main/scripts/start_docker.sh && chmod +x start_docker.sh
 docker compose down
-docker compose up --pull always
+./start_docker.sh
 ```
+```powershell Windows
+Invoke-WebRequest -OutFile start_docker.ps1 https://raw.githubusercontent.com/dograh-hq/dograh/main/scripts/start_docker.ps1
+docker compose down
+.\start_docker.ps1
+```
+</CodeGroup>
 
 To pin a specific version instead of `latest`, edit `docker-compose.yaml` and change both `image:` lines for `api` and `ui` to the same tag (e.g. `:1.28.0` — Docker image tags use bare semver, no `v` prefix), then run the commands above.
 

docs/getting-started/index.mdx

@@ -24,16 +24,23 @@ Watch the following video to learn about Dograh’s capabilities.
 
 ## Setting up
 
-Get the platform up and running using Docker with a single command on your local computer. If you are looking to deploy the platform on a server different than your local machine, please check the [Deployment](deployment/introduction) section.
+Get the platform up and running using Docker with a small startup script on your local computer. If you are looking to deploy the platform on a server different than your local machine, please check the [Deployment](deployment/introduction) section.
 
-<Note>We collect anonymous usage data to improve the product. You can opt out by setting the `ENABLE_TELEMETRY` to `false` in the below command.</Note>
+<Note>We collect anonymous usage data to improve the product. You can opt out by setting `ENABLE_TELEMETRY=false` before running the startup script.</Note>
 
-```bash
-curl -o docker-compose.yaml https://raw.githubusercontent.com/dograh-hq/dograh/main/docker-compose.yaml && REGISTRY=ghcr.io/dograh-hq ENABLE_TELEMETRY=true docker compose up --pull always
+<CodeGroup>
+```bash macOS/Linux
+curl -o docker-compose.yaml https://raw.githubusercontent.com/dograh-hq/dograh/main/docker-compose.yaml && curl -o start_docker.sh https://raw.githubusercontent.com/dograh-hq/dograh/main/scripts/start_docker.sh && chmod +x start_docker.sh && ./start_docker.sh
 ```
+```powershell Windows
+Invoke-WebRequest -OutFile docker-compose.yaml https://raw.githubusercontent.com/dograh-hq/dograh/main/docker-compose.yaml
+Invoke-WebRequest -OutFile start_docker.ps1 https://raw.githubusercontent.com/dograh-hq/dograh/main/scripts/start_docker.ps1
+.\start_docker.ps1
+```
+</CodeGroup>
 
 Please check [Prerequisites](getting-started/prerequisites) for the system requirements and [Troubleshooting](getting-started/troubleshooting) for common issues.
 
 ## Next Steps
 
-You can see how to configure the inference provider in [Inference Provider](/configurations/inference-providers).
+You can see how to configure the inference provider in [Inference Provider](/configurations/inference-providers).

docs/getting-started/prerequisites.mdx

@@ -74,12 +74,23 @@ Dograh images are available from two registries:
 - **GitHub Container Registry (Default)**: `ghcr.io/dograh-hq` - Recommended for most users
 - **Docker Hub**: `dograhai` - Alternative registry
 
-To use a specific registry, set the `REGISTRY` environment variable:
+To use a specific registry, set the `REGISTRY` environment variable when running the startup script:
 
+<CodeGroup>
 ```bash
 # Using GitHub Container Registry (recommended)
-REGISTRY=ghcr.io/dograh-hq docker compose up --pull always
+REGISTRY=ghcr.io/dograh-hq ./start_docker.sh
 
 # Using Docker Hub
-REGISTRY=dograhai docker compose up --pull always
+REGISTRY=dograhai ./start_docker.sh
 ```
+```powershell Windows
+# Using GitHub Container Registry (recommended)
+$env:REGISTRY = 'ghcr.io/dograh-hq'
+.\start_docker.ps1
+
+# Using Docker Hub
+$env:REGISTRY = 'dograhai'
+.\start_docker.ps1
+```
+</CodeGroup>

docs/voice-agent/api-trigger.mdx

@@ -118,7 +118,7 @@ For example, if your request includes:
 }
 ```
 
-You can reference the user's name in your prompt as `{{initial_context.user.name}}`.
+You can reference the user's name in your agent prompt as `{{user.name}}` — in Agent prompts, `initial_context` fields are referenced directly by name (not prefixed with `initial_context.`). See [template variables](/voice-agent/template-variables) for the exact syntax in prompts versus webhook payloads.
 
 See [Context & Variables](/core-concepts/context-and-variables) for more on how data flows through a call.
 

docs/voice-agent/pre-call-data-fetch.mdx

@@ -11,7 +11,7 @@ Pre-Call Data Fetch allows you to enrich the call context with external data bef
 1. A call arrives (inbound) or is initiated (outbound).
 2. Dograh sends a **POST** request to your configured endpoint with a standardized payload.
 3. The caller hears a ring-back tone while waiting for the response.
-4. Your API responds with a JSON object containing `dynamic_variables`.
+4. Your API responds with a JSON object containing an `initial_context` object.
 5. The variables are merged into the call's initial context.
 6. The voice agent starts with full access to the fetched data via `{{variable_name}}` syntax.
 
@@ -50,12 +50,12 @@ The `Content-Type` header is set to `application/json`. If you configured a cred
 
 ## Expected Response Format
 
-Your API should return a **JSON object** with a `2xx` status code. The variables to inject into the call context should be placed inside the `dynamic_variables` key:
+Your API should return a **JSON object** with a `2xx` status code. The variables to inject into the call context should be placed inside the `initial_context` key:
 
 ```json
 {
   "call_inbound": {
-    "dynamic_variables": {
+    "initial_context": {
       "customer_name": "Jane Doe",
       "account_status": "active",
       "loyalty_tier": "gold",
@@ -65,34 +65,38 @@ Your API should return a **JSON object** with a `2xx` status code. The variables
 }
 ```
 
-You can also place `dynamic_variables` at the top level:
+You can also place `initial_context` at the top level:
 
 ```json
 {
-  "dynamic_variables": {
+  "initial_context": {
     "customer_name": "Jane Doe",
     "account_status": "active"
   }
 }
 ```
 
+<Note>
+The legacy `dynamic_variables` key is still accepted as a drop-in alias for `initial_context`, so existing integrations keep working without any changes. Use `initial_context` for new integrations. If a response contains both keys, `initial_context` takes precedence.
+</Note>
+
 After the response is received, you can reference these values anywhere template variables are supported:
 
 - **Greeting**: `Hello {{customer_name}}, thank you for calling!`
 - **Prompt**: `The customer is a {{loyalty_tier}} member with {{open_tickets}} open support tickets.`
 
 <Note>
-If the response is not a valid JSON object, does not contain `dynamic_variables`, or the request fails or times out, the call proceeds normally without the additional context. The pre-call fetch never blocks or fails a call.
+If the response is not a valid JSON object, does not contain `initial_context` (or the legacy `dynamic_variables`), or the request fails or times out, the call proceeds normally without the additional context. The pre-call fetch never blocks or fails a call.
 </Note>
 
 ## Nested Variables
 
-If your `dynamic_variables` contain nested objects, you can access them using dot notation:
+If your `initial_context` contains nested objects, you can access them using dot notation:
 
 ```json
 {
   "call_inbound": {
-    "dynamic_variables": {
+    "initial_context": {
       "customer": {
         "name": "Jane Doe",
         "address": {
@@ -153,7 +157,7 @@ app.post("/dograh/pre-call", async (req, res) => {
 
   res.json({
     call_inbound: {
-      dynamic_variables: {
+      initial_context: {
         customer_name: customer.name,
         account_status: customer.status,
         loyalty_tier: customer.tier,

docs/voice-agent/template-variables.mdx

@@ -4,13 +4,23 @@ description: "You can use Template Variables in your prompts for your Agent node
 ---
 
 ### Template Rendering
-You can reference template variables which is passed as [`initial_context`](/core-concepts/context-and-variables#initial_context) either using the [API Trigger](/voice-agent/api-trigger) or when uploading a Sheet for a [campaign](/core-concepts/campaigns). You can also use any extracted variable as [`gathered_context`](/core-concepts/context-and-variables#gathered_context)
 
-The template rendering can take nested values. 
+You reference template variables with `{{double_brace}}` syntax. The data comes from [`initial_context`](/core-concepts/context-and-variables#initial_context) — set via the [API Trigger](/voice-agent/api-trigger), a [campaign](/core-concepts/campaigns) sheet, or a [Pre-Call Data Fetch](/voice-agent/pre-call-data-fetch) that enriches the context when the call starts — and, in Webhook payloads only, from [`gathered_context`](/core-concepts/context-and-variables#gathered_context) (variables extracted during the call).
 
-Example: If the initial context is
+**The syntax depends on where you use it:**
 
-```
+| Where | `initial_context` | `gathered_context` |
+| --- | --- | --- |
+| Agent node prompts | `{{field_name}}` (referenced directly) | Not available |
+| Webhook Node payloads | `{{initial_context.field_name}}` | `{{gathered_context.field_name}}` |
+
+#### Agent node prompts
+
+In an Agent node prompt, reference each `initial_context` field **directly by name**. Nested values are supported with dot notation.
+
+Example: if the initial context is
+
+```json
 {
     "initial_context": {
         "user": {
@@ -20,14 +30,26 @@ Example: If the initial context is
 }
 ```
 
-You can write your prompt to access the user's name as below
+write your prompt to access the user's name as below:
 
-Prompt: `You are Alice, who is talking to {{initial_context.user.name}}.`
+Prompt: `You are Alice, who is talking to {{user.name}}.`
+
+<Note>
+Variables extracted during the call (`gathered_context`) are **not** available in Agent prompts — a prompt can only reference `initial_context` fields. To act on extracted data, send it to a [Webhook Node](/voice-agent/webhook).
+</Note>
+
+#### Webhook Node payloads
+
+When constructing a [Webhook Node](/voice-agent/webhook) payload, the context objects are nested under their names, so reference them with the `initial_context.` and `gathered_context.` prefixes:
+
+Payload value: `{{initial_context.user.name}}` or `{{gathered_context.call_disposition}}`
 
 ### Using Template Variables for Testing
 
 Template variables defined in your workflow **Settings > Context Variables** are included in test calls (both web and phone) made from the workflow editor. This is useful for simulating data that would normally come from telephony or an API trigger.
 
+<img src="../images/template-variables.png" alt="Template Variables panel in workflow Settings, showing a customer_name variable and fields to add new key/value pairs" style={{border: "1px solid #d1d5db", borderRadius: "8px", maxWidth: "100%"}} />
+
 For example, you can set `caller_number` and `called_number` as context variables to test [Pre-Call Data Fetch](/voice-agent/pre-call-data-fetch#testing-with-test-calls) without needing a real inbound call.
 
 <Note>