docs: sanitize learnings for customer-facing use

Remove internal feature flag names, infrastructure references (E2B,
Temporal), internal class/function names (TurnTakingBuffer,
squadTransferMessagesApply, evaluationPlanPassedCheck), and jargon
(normalization, cork/uncork). Replace with customer-safe descriptions
of observable platform behavior.

Author: dhruva-vapi

docs/learnings/README.md

@@ -1,6 +1,6 @@
 # Gotchas & Best Practices
 
-Non-obvious behaviors, silent defaults, and foot-guns in the Vapi backend that affect how your YAML/JSON resources behave at runtime. This is a companion to the API reference — it covers what the docs _don't_ tell you.
+Non-obvious behaviors, silent defaults, and foot-guns in the Vapi platform that affect how your YAML/JSON resources behave at runtime. This is a companion to the API reference — it covers what the docs _don't_ tell you.
 
 Each file in this directory covers a specific resource type so you can load only the context you need:
 

docs/learnings/assistants.md

@@ -8,7 +8,7 @@ Non-obvious behaviors and silent defaults for Vapi assistant settings.
 
 ### `temperature` defaults to 0, `maxTokens` defaults to 250
 
-If omitted, the backend fills `temperature: 0` and `maxTokens: 250`. This can cause unexpectedly short responses.
+If omitted, Vapi defaults to `temperature: 0` and `maxTokens: 250`. This can cause unexpectedly short responses.
 
 **Recommendation:** Set `maxTokens` explicitly (e.g., 1000–4000) for assistants that need longer responses.
 
@@ -22,7 +22,7 @@ If omitted, the backend fills `temperature: 0` and `maxTokens: 250`. This can ca
 
 ### `emotionRecognitionEnabled` has no runtime effect
 
-Despite being a configurable field, the endpointing buffer has an explicit no-op branch for this flag. Don't rely on it for behavior changes.
+Despite being a configurable field, this setting currently has **no effect** on call behavior. Don't rely on it.
 
 ---
 
@@ -50,7 +50,7 @@ If omitted, transcripts with confidence below 0.4 may be **ignored** entirely (n
 
 ### `smartEndpointingPlan` **owns** turn detection when set
 
-If you configure `startSpeakingPlan.smartEndpointingPlan`, the transcriber's own `endpointing` settings (VAD timeouts, etc.) are **not used** for turn detection. Smart endpointing takes full control.
+If you configure `startSpeakingPlan.smartEndpointingPlan`, the transcriber's own `endpointing` settings (voice activity detection timeouts, etc.) are **not used** for turn detection. Smart endpointing takes full control.
 
 **Recommendation:** Don't set both and expect them to combine. Choose one approach.
 
@@ -76,7 +76,7 @@ Hooks that fail validation are dropped without error. Your call will proceed wit
 
 ### Missing hook `toolId` is a warning, not an error
 
-If a hook references a `toolId` that doesn't exist, the backend logs a warning and continues. This is different from `model.toolIds` where a missing ID **errors the call**.
+If a hook references a `toolId` that doesn't exist, Vapi logs a warning and continues. This is different from `model.toolIds` where a missing ID **errors the call**.
 
 ### Hook events are independent from timeout settings
 
@@ -123,8 +123,8 @@ If not set, there's a 0.4-second pause after the user stops speaking before the
 
 ### `waitSeconds` and `smartEndpointingPlan` control different things
 
-- `waitSeconds` drives the **TurnTakingBuffer**: it corks assistant audio output for that duration after VAD detects speech.
-- `smartEndpointingPlan` drives the **EndpointingBuffer**: it determines when the user has finished their turn using an AI model or heuristic.
+- `waitSeconds` controls a short pause on assistant audio after voice activity is detected — it delays the assistant's response by that duration.
+- `smartEndpointingPlan` controls how end-of-turn is detected — it determines when the user has finished speaking using an AI model or heuristic.
 
 These are complementary, not alternatives.
 
@@ -152,7 +152,7 @@ Unless you explicitly set `analysisPlan.summaryPlan.enabled: false`, post-call s
 
 ### Recording is enabled by default
 
-Unless you set `artifactPlan.recordingEnabled: false`, calls are recorded. The backend falls back to `assistant.recordingEnabled` (deprecated), then defaults to `true`.
+Unless you set `artifactPlan.recordingEnabled: false`, calls are recorded. Vapi also checks `assistant.recordingEnabled` (deprecated) before defaulting to `true`.
 
 ### Default transcript labels are "AI" and "User"
 
@@ -198,7 +198,7 @@ Omitting `serverMessages` does **not** mean "no webhooks." It means "all default
 
 ## HIPAA / Compliance
 
-When HIPAA is enabled (on org or assistant) **and** the `ENABLE_ASSISTANT_PROVIDER_HIPAA_VALIDATION` feature flag is active, the model, voice, and transcriber providers must be on an approved allowlist. Non-compliant providers will **fail validation** on create/update.
+When HIPAA is enabled (on org or assistant) and HIPAA provider validation is enforced for your org, the model, voice, and transcriber providers must be on Vapi's approved allowlist. Non-compliant providers will **fail validation** on create/update.
 
 ---
 
@@ -209,7 +209,7 @@ When HIPAA is enabled (on org or assistant) **and** the `ENABLE_ASSISTANT_PROVID
 1. Inline `model.tools` are processed first
 2. Each `toolId` is resolved from the org's saved tools — **a missing ID errors the call**
 3. Results are merged: `[...inline tools, ...resolved toolIds]`
-4. MCP tools are expanded from parent tool metadata
+4. MCP tools are expanded from configured integrations
 
 ### `toolIds` and inline `tools` can coexist
 

docs/learnings/simulations.md

@@ -39,14 +39,14 @@ Simulation evaluations support these comparators:
 
 Evaluations that require audio (`target: messages-with-audio`) are **skipped** in chat-mode simulations with `passed: false` and `isSkipped: true`.
 
-**Critical:** If **all** required evaluations are audio-dependent and the simulation runs in chat mode, they're all skipped — and `evaluationPlanPassedCheck` returns **`true`** (0 required results = pass). This means your test suite can silently pass with no actual evaluation.
+**Critical:** If **all** required evaluations are audio-dependent and the simulation runs in chat mode, they're all skipped — and the run is treated as **passed** (0 required results = pass). This means your test suite can silently pass with no actual evaluation.
 
 **Recommendation:** Include at least one text-based (`target: messages`) evaluation in every simulation that runs in chat mode.
 
 ---
 
 ## Missing References
 
-- **At run creation (API):** Missing scenario or personality IDs throw `BadRequestException` immediately.
-- **At execution (Temporal worker):** Missing references throw `ApplicationFailure` — behavior depends on Temporal retry config.
-- **Inline runs:** Require snapshots in metadata or fail with "no inline config" error.
+- **At run creation (API):** Missing scenario or personality IDs fail the API request immediately with a validation error.
+- **At execution:** Missing references fail the run. Retries depend on platform configuration.
+- **Inline runs:** Require snapshots in metadata or fail with a "no inline config" error.

docs/learnings/squads.md

@@ -40,7 +40,7 @@ assistantOverrides:
 
 ## assistantDestinations vs Inline Tools
 
-`member.assistantDestinations` is **sugar** that the backend converts into real tools:
+`member.assistantDestinations` is **shorthand** that Vapi converts into real tools:
 
 - Destinations with `assistantId`, `contextEngineeringPlan`, or `variableExtractionPlan` → **handoff tools**
 - All other destinations → merged into a **transferCall tool** (creating one if needed)
@@ -51,20 +51,18 @@ Both mechanisms can coexist on the same member. If you use both `assistantDestin
 
 ## Context During Handoffs
 
-After a handoff, the new assistant does NOT get a raw copy of all prior messages. The backend applies `squadTransferMessagesApply` which may summarize, filter, or restructure the conversation history. If `handoffMessages` are provided on the destination, they **replace** the active message context entirely.
+After a handoff, the new assistant does NOT get a raw copy of all prior messages. Vapi may summarize, filter, or restructure the conversation history during the transfer. If `handoffMessages` are provided on the destination, they **replace** the active message context entirely.
 
 ---
 
 ## Override Merge Order
 
-```
-Final = deepMerge(
-  assistant,
-  member.assistantOverrides,
-  squad.membersOverrides,
-  call.squadOverrides
-)
-```
+The final assistant configuration is built by merging these layers in order:
+
+1. Base assistant
+2. `member.assistantOverrides`
+3. `squad.membersOverrides`
+4. `call.squadOverrides`
 
 Later layers win on conflicts. `variableValues` from all layers are merged separately.
 

docs/learnings/structured-outputs.md

@@ -8,11 +8,11 @@ Non-obvious behaviors and silent defaults for Vapi structured output extraction.
 
 ### Use single `type` values, not arrays
 
-**Bad:** `type: [string, "null"]` — this can cause `TypeError: .toLowerCase is not a function` in the dashboard, and the backend uses only the **first** element of the array for extraction.
+**Bad:** `type: [string, "null"]` — using an array for `type` is not supported and may cause errors in the dashboard and extraction pipeline. Vapi uses only the **first** element of the array.
 
 **Good:** `type: string` — express nullability in the `description` instead (e.g., "Return null if not applicable").
 
-### `wrapIfPrimitive` behavior
+### Primitive schemas are auto-wrapped
 
 Primitive schemas (`string`, `boolean`, `number`) are automatically wrapped in an object for OpenAI structured output mode:
 ```json
@@ -33,7 +33,7 @@ Structured outputs require `assistant_ids` as **Vapi UUIDs** (v4 format). Assist
 
 ## Default Extraction Model
 
-If you omit `model` on a structured output, the default is:
+If you omit `model` on a structured output, the default (as of this writing) is:
 ```yaml
 model:
   provider: openai
@@ -42,9 +42,9 @@ model:
   maxTokens: 4000
 ```
 
-Fallback sequence: your configured model → `gpt-4.1` → `gemini-2.5-flash`.
+Fallback sequence: your configured model → `gpt-4.1` → `gemini-2.5-flash`. These defaults may change over time — check the API reference for the current default.
 
-For multimodal extraction (`messages-with-audio`), the default is **Gemini 2.5 Pro**.
+For multimodal extraction (`messages-with-audio`), the default is **Gemini 2.5 Pro** (as of this writing).
 
 ---
 

docs/learnings/tools.md

@@ -10,7 +10,7 @@ Non-obvious behaviors and silent defaults for Vapi tool types.
 
 **What you might expect:** `function.parameters` and `body` are two independent schemas — one for the LLM, one for the HTTP request.
 
-**What actually happens:** The backend **overwrites** `function.parameters` with a copy of `body` during normalization. Whatever you define in `body.properties` becomes the tool schema the LLM sees. Any `function.parameters` you set on an apiRequest tool is **silently ignored**.
+**What actually happens:** Vapi **overwrites** `function.parameters` with a copy of `body` when the tool is processed. Whatever you define in `body.properties` becomes the tool schema the LLM sees. Any `function.parameters` you set on an apiRequest tool is **silently ignored**.
 
 **Recommendation:** Only define your schema in `body`. Do not set `function.parameters` on apiRequest tools.
 
@@ -28,19 +28,19 @@ If you omit `method`, it defaults to `POST` — not `GET`.
 
 ### API response must be JSON
 
-On a successful HTTP response (2xx), the backend calls `response.json()`. If your API returns non-JSON (plain text, HTML, XML), the tool call will error.
+On a successful HTTP response (2xx), Vapi expects a JSON body. If your API returns non-JSON (plain text, HTML, XML), the tool call will error.
 
 ### `function.strict` is always cleared
 
-The backend sets `strict: undefined` on apiRequest tools during normalization. If you need strict schema enforcement from the LLM provider, use a `function` type tool instead.
+Vapi removes `strict` from apiRequest tools when they are processed. If you need strict schema enforcement from the LLM provider, use a `function` type tool instead.
 
 ### `async` has no effect
 
-The backend forces `async: undefined` on apiRequest tools. They always execute synchronously (HTTP call → wait for response → return to LLM).
+Vapi ignores `async` on apiRequest tools. They always execute synchronously (HTTP call → wait for response → return to LLM).
 
 ### Credential fallback behavior
 
-If `credentialId` is set on the tool, that specific credential is used. If omitted, the backend uses the **first** `webhook` or `custom-credential` it finds on the call's credential list. If you have multiple webhook credentials, always set `credentialId` explicitly.
+If `credentialId` is set on the tool, that specific credential is used. If omitted, Vapi picks one from the call's available credentials automatically. If you have multiple webhook credentials, always set `credentialId` explicitly to avoid ambiguity.
 
 ---
 
@@ -50,7 +50,7 @@ If `credentialId` is set on the tool, that specific credential is used. If omitt
 
 **What you might expect:** A function tool without `server.url` fails at runtime.
 
-**What actually happens:** The backend falls back through a hierarchy: tool `server.url` → assistant `server.url` → phone number `server.url` → org `server.url`. Omitting `server` on the tool is valid if the assistant or org has a server URL configured.
+**What actually happens:** Vapi falls back through a hierarchy: tool `server.url` → assistant `server.url` → phone number `server.url` → org `server.url`. Omitting `server` on the tool is valid if the assistant or org has a server URL configured.
 
 **Recommendation:** Set `server.url` on the tool for clarity, or document which level provides the webhook URL.
 
@@ -66,9 +66,9 @@ If `credentialId` is set on the tool, that specific credential is used. If omitt
 When `strict: true` is set on a function tool:
 - Every `object` node must have `additionalProperties: false`
 - Every property must be listed in `required`
-- The org must have the `ENABLE_TOOL_STRICT_MODE` feature flag enabled
+- Strict mode must be enabled for your organization
 
-If the schema doesn't meet these requirements, `strict` is silently stripped and a warning is logged.
+If the schema doesn't meet these requirements, `strict` may be silently disabled for that tool.
 
 ---
 
@@ -131,7 +131,7 @@ If you don't set `function.name`:
 
 ### Destination resolution is fuzzy
 
-The backend tries multiple matching strategies for the model's destination argument:
+Vapi tries multiple matching strategies for the model's destination argument:
 1. Match by UUID (`assistantId`, `squadId`)
 2. Match by name (`assistantName`, squad `name`)
 3. Fall back to first destination if argument is `"dynamic"` or missing
@@ -145,15 +145,15 @@ The backend tries multiple matching strategies for the model's destination argum
 
 ### Execution timeout is capped at 30 seconds
 
-Even if you set `timeoutSeconds: 60`, the backend caps it at `Math.min(timeoutSeconds ?? 30, 30)`.
+Even if you set `timeoutSeconds: 60`, the effective timeout is capped at **30 seconds**.
 
 ### Code must be valid top-level async JavaScript
 
-Code runs in an E2B sandbox as `node /tmp/code.js`. The code receives `args` (tool arguments) and `env` (environment variables) as globals. Return values are captured from the resolved promise.
+Code runs in a managed sandbox as Node.js. The code receives `args` (tool arguments) and `env` (environment variables) as globals. Return values are captured from the resolved promise.
 
 ### Static validation checks `args.*` and `env.*` references
 
-When saving a code tool, the backend parses your code and validates that every `args.foo` reference has a matching property in `function.parameters.properties`, and every `env.BAR` reference has a matching key in `environmentVariables`. Mismatches are rejected.
+When saving a code tool, Vapi parses your code and validates that every `args.foo` reference has a matching property in `function.parameters.properties`, and every `env.BAR` reference has a matching key in `environmentVariables`. Mismatches are rejected.
 
 ### `function.strict` is cleared (like apiRequest)
 
@@ -195,11 +195,11 @@ After one delayed message plays, another won't play for at least 2.5 seconds —
 
 | Tool type | `strict` behavior |
 |-----------|-------------------|
-| `function` | **Preserved** — passed to LLM provider if org has `ENABLE_TOOL_STRICT_MODE` |
-| `apiRequest` | **Cleared** to `undefined` during normalization |
-| `code` | **Cleared** to `undefined` during normalization |
-| `transferCall` | **Cleared** to `undefined` during normalization |
-| `endCall` | **Cleared** to `undefined` during normalization |
-| `handoff` | **Cleared** to `undefined` during normalization |
+| `function` | **Preserved** — passed to LLM provider if strict mode is enabled for your org |
+| `apiRequest` | **Removed** when the tool is processed |
+| `code` | **Removed** when the tool is processed |
+| `transferCall` | **Removed** when the tool is processed |
+| `endCall` | **Removed** when the tool is processed |
+| `handoff` | **Removed** when the tool is processed |
 
 Only `function` tools support `strict` mode.

docs/learnings/webhooks.md

@@ -24,33 +24,26 @@ These are **two independent settings**:
 
 | Setting | Controls | Default |
 |---------|----------|---------|
-| `server.timeoutSeconds` | Webhook delivery timeout (status-update, end-of-call-report, etc.) | `DEFAULT_TIMEOUT_SECOND` |
-| `tool.timeoutSeconds` (apiRequest) | Individual tool HTTP call timeout | `DEFAULT_TIMEOUT_SECOND` |
+| `server.timeoutSeconds` | Webhook delivery timeout (status-update, end-of-call-report, etc.) | Platform default (see API reference) |
+| `tool.timeoutSeconds` (apiRequest) | Individual tool HTTP call timeout | Platform default (see API reference) |
 
 They don't inherit from each other.
 
 ---
 
 ## Unreachable Server Behavior
 
-- **Missing `server.url`:** Returns empty object, no network call. No error.
-- **Server returns error:** Error is logged and returned. For `tool-calls` message type, the backend **still attempts to parse** the error response body for tool results.
-- **High failure rate:** A circuit breaker kicks in — "noisy" message types (frequent events like `speech-update`) are aborted when the error rate exceeds a threshold. Critical messages like `end-of-call-report` continue attempting.
+- **Missing `server.url`:** No network call is made. No error is raised.
+- **Server returns error:** The error is logged and returned to the platform. For `tool-calls` events, Vapi still attempts to parse the error response body for tool results.
+- **High failure rate:** Under sustained delivery failures, Vapi may reduce delivery of high-frequency events (like `speech-update`) while still attempting critical events (like `end-of-call-report`).
 
 ---
 
 ## Credential Resolution
 
-For server webhooks:
-1. If `server.credentialId` is set → use that specific credential
-2. Else → use the first `custom-credential` on the call
-3. Else → use the first `webhook` credential on the call
+If `credentialId` is set on the server or tool, that specific credential is used. If omitted, Vapi picks one from the call's available credentials automatically.
 
-For apiRequest tools:
-1. If `tool.credentialId` is set → use that specific credential
-2. Else → use the first `webhook` or `custom-credential` on the call
-
-**Recommendation:** Always set `credentialId` explicitly when multiple credentials exist to avoid ambiguous fallback.
+**Recommendation:** Always set `credentialId` explicitly when multiple credentials exist to avoid ambiguous selection.
 
 ---