docs: capture server and squad config learnings

Author: dhruva-vapi

docs/learnings/squads.md

@@ -140,6 +140,18 @@ destinations:
 
 Within a single assistant there is no equivalent. `request-complete` is a speech lever, `variableExtractionPlan` aliases give determinism but not invisibility, and tool responses are always in the next-completion conversation history. If the model must not see a value, your tool server must not place it in the response body in the first place. See [tools.md → Every tool result is in conversation history](tools.md#every-tool-result-is-in-conversation-history).
 
+### Enabling PCI for every squad member
+
+Squads do not have a first-class `squad.compliancePlan` field. To enable PCI mode for all members, set it through `membersOverrides`, which is applied to every resolved assistant before the call-level compliance plan is computed.
+
+```yaml
+membersOverrides:
+  compliancePlan:
+    pciEnabled: true
+```
+
+For a one-off call using an existing `squadId`, the same shape can be passed as `squadOverrides.compliancePlan.pciEnabled`. Org-level `org.compliancePlan.pciEnabled` also applies globally. The squad builder UI currently exposes model, voice, and transcriber overrides, but not a PCI toggle, so use API/gitops JSON for squad-level PCI.
+
 ---
 
 ## Override Merge Order

docs/learnings/tools.md

@@ -99,6 +99,19 @@ Vapi ignores `async` on apiRequest tools. They always execute synchronously (HTT
 
 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.
 
+### Timeout is top-level, not under `server`
+
+For apiRequest tools, set `timeoutSeconds` directly on the tool. Do not put it under `server.timeoutSeconds` — apiRequest tools execute their own HTTP request path.
+
+```yaml
+type: apiRequest
+url: https://your-api-endpoint.example.com/search
+method: POST
+timeoutSeconds: 45
+```
+
+**Dashboard gotcha:** the current API Request tool form does not expose this field. Configure it through API/gitops JSON if you need a non-default timeout.
+
 ---
 
 ## function Tools
@@ -111,6 +124,19 @@ If `credentialId` is set on the tool, that specific credential is used. If omitt
 
 **Recommendation:** Set `server.url` on the tool for clarity, or document which level provides the webhook URL.
 
+### Timeout lives under `server.timeoutSeconds`
+
+Function tools use the Server URL webhook path, so their per-tool timeout is configured on the tool's `server` block:
+
+```yaml
+type: function
+server:
+  url: https://your-webhook-endpoint.example.com/tool
+  timeoutSeconds: 45
+```
+
+This is separate from apiRequest's top-level `timeoutSeconds`.
+
 ### `async: true` changes execution flow significantly
 
 - `async: false` (default): The LLM waits for the tool result before continuing. The user hears `request-start`, `request-response-delayed` messages while waiting.

docs/learnings/webhooks.md

@@ -24,8 +24,9 @@ These are **two independent settings**:
 
 | Setting | Controls | Default |
 |---------|----------|---------|
-| `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) |
+| `server.timeoutSeconds` | Webhook delivery timeout (status-update, end-of-call-report, function tools using `server.url`, etc.) | Platform default (see API reference) |
+| `timeoutSeconds` (apiRequest tool) | Individual API request tool HTTP call timeout | Platform default (see API reference) |
+| `timeoutSeconds` (code tool) | Code tool execution timeout | Platform default, capped at 30s |
 
 They don't inherit from each other.
 
@@ -75,6 +76,12 @@ If `credentialId` is set on the server or tool, that specific credential is used
 
 **Recommendation:** Always set `credentialId` explicitly when multiple credentials exist to avoid ambiguous selection.
 
+### `X-Vapi-Secret` is legacy shared-secret auth
+
+`server.secret` (or legacy `serverUrlSecret`) is sent to your server as the `X-Vapi-Secret` header. This is a simple shared-secret comparison, not an HMAC signature.
+
+**Recommendation:** Prefer `server.credentialId` / webhook credentials for new integrations when you need OAuth2, Bearer, or HMAC auth. Keep `server.secret` for simple endpoints that only need a shared-secret check. Do not also set `X-Vapi-Secret` manually in `server.headers` unless you intentionally want to override the generated value.
+
 ---
 
 ## Webhook Payload Shape