toga-ai 1.0.93 → 1.0.95

package/knowledge/2.0/apps/ai-bdr/INDEX.md

@@ -0,0 +1,8 @@
+# ai-bdr (AI-BDR) — 2.0 knowledge
+
+| Doc | Summary | Files |
+|-----|---------|-------|
+| [AI-BDR Architecture](architecture.md) | **AI-BDR** is TOGA's outbound AI sales-development representative. | ai-bdr/README.md, ai-bdr/requirements.txt, ai-bdr/.env.example, ai-bdr/docs/client-onboarding-sop.md, ai-bdr/docs/vapi-firstmessage-timing-fix.md, ai-bdr/docs/vapi-inbound-callback-assistant-request.md, ai-bdr/docs/vapi-voicemail-iphone-screening.md, ai-bdr/vapi/templates/system-prompt.template.md, ai-bdr/vapi/templates/assistant.template.json, ai-bdr/prompts/archive/prompt-may-15.txt, ai-bdr/prompts/campaigns/healthcare-2026-03-18.md, ai-bdr/prompts/campaigns/healthcare-v2-2026-03-25.md, ai-bdr/scripts/update_assistant.py, ai-bdr/scripts/update_system_prompt.py, ai-bdr/scripts/update_structured_output.py, ai-bdr/scripts/update_call_summary_context.py, ai-bdr/scripts/fix_booking_guardrails.py, ai-bdr/scripts/get_assistant.py |
+| [Call Orchestration — PHP Worker ↔ Vapi (the integration seam)](features/call-orchestration.md) | The **PHP worker** is the orchestrator; **Vapi** is the actor. | ai-bdr/docs/client-onboarding-sop.md, ai-bdr/docs/vapi-firstmessage-timing-fix.md, ai-bdr/docs/vapi-inbound-callback-assistant-request.md, ai-bdr/docs/vapi-voicemail-iphone-screening.md, ai-bdr/scripts/update_structured_output.py |
+| [Vapi Integration — Assistants, Tools, Structured Output](features/vapi-integration.md) | Everything inside Vapi: the three assistants, the three shared tools, the shared structured-output schema, the Liquid-templated system prompt, and the Python sc | ai-bdr/vapi/templates/assistant.template.json, ai-bdr/vapi/templates/system-prompt.template.md, ai-bdr/prompts/archive/prompt-may-15.txt, ai-bdr/prompts/campaigns/healthcare-2026-03-18.md, ai-bdr/prompts/campaigns/healthcare-v2-2026-03-25.md, ai-bdr/prompts/templates/campaign-template.md, ai-bdr/scripts/update_assistant.py, ai-bdr/scripts/update_system_prompt.py, ai-bdr/scripts/update_structured_output.py, ai-bdr/scripts/update_call_summary_context.py, ai-bdr/scripts/fix_booking_guardrails.py, ai-bdr/scripts/get_assistant.py, ai-bdr/docs/vapi-firstmessage-timing-fix.md, ai-bdr/docs/vapi-voicemail-iphone-screening.md |
+| [New-Campaign Onboarding (6-phase runbook)](workflows/new-campaign-onboarding.md) | The end-to-end procedure for launching a new outbound BDR campaign (industry, offer, target persona, geography). | ai-bdr/docs/client-onboarding-sop.md, ai-bdr/docs/calcom-new-campaign-event-guide.md, ai-bdr/prompts/templates/campaign-template.md, ai-bdr/scripts/update_assistant.py, ai-bdr/scripts/update_system_prompt.py |

package/knowledge/2.0/apps/ai-bdr/architecture.md

@@ -0,0 +1,197 @@
+---
+title: AI-BDR Architecture
+framework: "2.0"
+repo: ai-bdr
+project: AI-BDR
+client: shared
+type: architecture
+status: active
+updated: 2026-06-16
+owners: [akhokhani]
+files:
+  - ai-bdr/README.md
+  - ai-bdr/requirements.txt
+  - ai-bdr/.env.example
+  - ai-bdr/docs/client-onboarding-sop.md
+  - ai-bdr/docs/vapi-firstmessage-timing-fix.md
+  - ai-bdr/docs/vapi-inbound-callback-assistant-request.md
+  - ai-bdr/docs/vapi-voicemail-iphone-screening.md
+  - ai-bdr/vapi/templates/system-prompt.template.md
+  - ai-bdr/vapi/templates/assistant.template.json
+  - ai-bdr/prompts/archive/prompt-may-15.txt
+  - ai-bdr/prompts/campaigns/healthcare-2026-03-18.md
+  - ai-bdr/prompts/campaigns/healthcare-v2-2026-03-25.md
+  - ai-bdr/scripts/update_assistant.py
+  - ai-bdr/scripts/update_system_prompt.py
+  - ai-bdr/scripts/update_structured_output.py
+  - ai-bdr/scripts/update_call_summary_context.py
+  - ai-bdr/scripts/fix_booking_guardrails.py
+  - ai-bdr/scripts/get_assistant.py
+related:
+  - features/vapi-integration.md
+  - features/call-orchestration.md
+  - workflows/new-campaign-onboarding.md
+---
+
+## Summary
+
+**AI-BDR** is TOGA's outbound AI sales-development representative. **Vapi**
+runs the live phone conversation with the prospect; the **PHP worker**
+schedules calls, receives the end-of-call webhook, and acts on the
+structured output (book a Cal.com meeting, flag DNC, schedule a callback,
+queue nurture email, mark wrong-person, etc.). Success = a booked
+discovery call (or a qualified nurture / accurate compliance handling).
+
+The repo at `talos-backend/AI-BDR/` is **the Vapi side only** — assistants,
+prompts, structured-output schema, and Python automation scripts. The PHP
+worker side (call initiation + webhook handlers + campaign cadence) lives
+in a TOGA worker repo (`worker` for 1.0 / `worker2` for 2.0) and is **not
+checked into this repo** — its contract is documented here.
+
+## Top-level layout
+
+```
+AI-BDR/
+├── README.md
+├── requirements.txt              # Python deps for the scripts
+├── .env.example
+├── docs/                         # SOPs and integration specs
+│   ├── client-onboarding-sop.md  # 6-phase new-campaign runbook (canonical)
+│   ├── vapi-firstmessage-timing-fix.md
+│   ├── vapi-inbound-callback-assistant-request.md
+│   └── vapi-voicemail-iphone-screening.md
+├── prompts/
+│   ├── archive/                  # historical full prompts (prompt-may-15.txt etc.)
+│   ├── campaigns/                # active per-campaign prompts (healthcare-*.md)
+│   ├── templates/                # campaign-template.md (Liquid skeleton)
+│   └── reference/                # vapi_docs_urls.txt, sales-demo-questions.txt
+├── scripts/                      # Python automation against Vapi REST API
+│   ├── get_assistant.py
+│   ├── update_assistant.py       # core: firstMessage / prompt / structuredOutput
+│   ├── update_system_prompt.py
+│   ├── update_structured_output.py
+│   ├── update_call_summary_context.py
+│   └── fix_booking_guardrails.py
+└── vapi/                         # Vapi assistant + tool templates
+    └── templates/
+        ├── assistant.template.json
+        └── system-prompt.template.md
+```
+
+## Four moving parts
+
+1. **Vapi assistant(s)** — three active assistants on three numbers (IDs
+   from the SOP):
+   - **Primary BDR** — `+1 (216) 616-0067` — assistant id
+     `6663a81b-a173-4ffd-b297-1c17aa66dead`.
+   - **Healthcare campaign** — `+1 (331) 244-5958` — assistant id
+     `0c058f55-1610-413c-ae04-c71b30b33a43`.
+   - **Tech demo** — `+1 (331) 281-1679` — assistant id
+     `0505c46e-1150-4814-9a5c-60ad44287abf`.
+   - All share one **structured-output schema** id
+     `daaa4639-4143-4c3f-a71a-2a78ad3c163f`, three tools (`end_call_tool`,
+     `GetBookingSlots`, `kb_search`), GPT-4.1 @ temp 0.5, Elliot voice
+     @ 0.9 speed.
+2. **PHP worker** (in `worker` / `worker2` — not in this repo) — schedules
+   outbound calls (`POST https://api.vapi.ai/call/phone`), implements the
+   three webhook endpoints below, runs the campaign cadence loop.
+3. **Webhook surface** at `https://webhook.togahub.com/vapi`:
+   - `end-of-call-report` — after every call; carries the structured
+     output (`callOutcome`, `phpWorkerAction`, transcript, …).
+   - `assistant-request` — inbound callback; backend has 7.5 s to look up
+     the contact by phone and return the assistant config + variableValues
+     with `callType="callback"`.
+   - `status-update` — used for first-message timing (Option B).
+4. **External integrations:**
+   - **Cal.com** — `GetBookingSlots` tool hits `/v2/slots` with the
+     campaign's event-type slug + team slug + caller-confirmed time range.
+     The backend creates the actual meeting on `BOOK_CALCOM_MEETING`.
+   - **Gemini 2.0 Flash KB** — `kb_search` tool grounds the assistant in
+     ~12 TOGA service / compliance PDFs.
+   - **NetSuite** — backend creates a lead record on `BOOK_CALCOM_MEETING`
+     (sequence in `client-onboarding-sop.md §10.2`).
+
+## End-to-end call flow (mental model)
+
+```
+PHP worker cadence cron picks next prospect
+  → POST https://api.vapi.ai/call/phone
+       {assistantId, phoneNumberId,
+        customer.number,
+        assistantOverrides.variableValues: {
+            firstName, lastName, companyName, jobTitle,
+            phoneNumber, knownEmail, callType="immediate",
+            attemptNumber, previousCallSummary, …}}
+  → Vapi dials the prospect
+  → assistant runs the call (Liquid-templated system prompt branches on
+    attemptNumber + callType; collects email; uses GetBookingSlots and
+    kb_search; obeys two-turn closing protocol)
+  → call ends
+  → POST https://webhook.togahub.com/vapi  (end-of-call-report)
+       {message.endedReason, message.transcript,
+        message.analysis.structuredData: {
+            callOutcome, phpWorkerAction, dncRequested,
+            qualificationScore, callSummary, contactEmail,
+            meetingTime, callbackTime, callType,
+            nextCallOpeningContext, …}}
+  → PHP worker action handler dispatches on phpWorkerAction:
+       BOOK_CALCOM_MEETING            → Cal.com POST + NetSuite lead
+       SCHEDULE_CALLBACK              → update dtAgreedUponNextContact
+       FLAG_DNC_REMOVE_FROM_CAMPAIGNS → set isOkayToCall=0 + purge
+       SEND_NURTURE_EMAIL             → queue email + topic
+       MARK_*_RETRY                   → cadence rules
+       MARK_NOT_INTERESTED / MARK_WRONG_PERSON / NO_ACTION
+  → If callback agreed and prospect dials in later:
+       Vapi fires assistant-request (≤7.5 s SLA)
+       PHP worker looks up contact by phone, returns variableValues with
+       callType="callback" + previousCallSummary
+       → same assistant resumes with prior-call context
+```
+
+See `features/call-orchestration.md` for the wire-level shape of the three
+webhook payloads and the full `phpWorkerAction` enum.
+
+## Why this repo is Python (scripts) + JSON (templates) + Markdown (prompts)
+
+All conversation logic lives in **Vapi configuration**, not in TOGA code.
+The Python scripts only update that configuration via the Vapi REST API.
+Markdown prompts are the source of truth for assistant behavior — they are
+authored here, then pushed to Vapi by `scripts/update_system_prompt.py`.
+
+## Storage
+
+- **No primary DB in this repo.** Prospect / campaign state lives in the
+  TOGA database the PHP worker reads (tables include `contacts`,
+  `campaigns`, and implied `call_logs` per the SOP; exact schema lives in
+  the worker repo).
+- **Vapi platform** stores assistant configs, call recordings, transcripts.
+- **Cal.com** stores meeting bookings.
+- **NetSuite** stores leads from booked meetings.
+
+## Observability
+
+- **Vapi dashboard** — call logs, recordings, transcripts.
+- **CloudWatch / TOGa Hub backend logs** for the webhook handlers.
+- **No Langfuse / OTEL** — there is no TOGA-side LLM call to trace; the
+  LLM call happens inside Vapi.
+
+## Key decisions
+
+- **Single shared structured-output schema** across all assistants — keeps
+  the PHP webhook handler simple (one branch per `phpWorkerAction`,
+  campaign-agnostic).
+- **PHP is the orchestrator, Vapi is the actor.** Cadence, retry rules,
+  DNC compliance, NetSuite/Cal.com integration all live in PHP — Vapi
+  never makes business decisions, only conversation moves.
+- **Liquid-templated system prompts** keyed on `attemptNumber` and
+  `callType` — one prompt covers cold / warm-inbound / callback / followup
+  without forking assistants.
+- **Two-turn closing protocol** (in the end-call tool description) —
+  prevents the assistant from hanging up before the prospect's last word
+  has been acknowledged.
+- **DNC is non-negotiable.** `dncRequested` is evaluated independently of
+  `phpWorkerAction`; if true, the worker MUST run `FLAG_DNC` regardless of
+  the suggested action.
+
+## Change history
+- 2026-06-16 — Initial architecture doc for AI-BDR. (akhokhani)

package/knowledge/2.0/apps/ai-bdr/features/call-orchestration.md

@@ -0,0 +1,250 @@
+---
+title: Call Orchestration — PHP Worker ↔ Vapi (the integration seam)
+framework: "2.0"
+repo: ai-bdr
+project: AI-BDR
+client: shared
+type: feature
+status: active
+updated: 2026-06-16
+owners: [akhokhani]
+files:
+  - ai-bdr/docs/client-onboarding-sop.md
+  - ai-bdr/docs/vapi-firstmessage-timing-fix.md
+  - ai-bdr/docs/vapi-inbound-callback-assistant-request.md
+  - ai-bdr/docs/vapi-voicemail-iphone-screening.md
+  - ai-bdr/scripts/update_structured_output.py
+related:
+  - ../architecture.md
+  - vapi-integration.md
+---
+
+## Summary
+
+The **PHP worker** is the orchestrator; **Vapi** is the actor. This doc
+defines the exact wire shape of the three integration points so the PHP
+worker handler in `worker` / `worker2` (separate repo — see **Where the
+PHP code lives**) and the Vapi assistants stay in contract.
+
+Three integration points:
+
+1. **Outbound — `POST https://api.vapi.ai/call/phone`** — worker initiates
+   a call with all per-prospect variables.
+2. **Outbound webhook — `POST https://webhook.togahub.com/vapi`
+   (`end-of-call-report`)** — every call returns its structured analysis;
+   worker dispatches on `phpWorkerAction`.
+3. **Inbound webhook — `POST https://webhook.togahub.com/vapi`
+   (`assistant-request`)** — when a prospect dials back, Vapi asks the
+   worker which assistant + variableValues to use (7.5 s SLA).
+
+## 1) Outbound call initiation
+
+```http
+POST https://api.vapi.ai/call/phone
+Authorization: Bearer ${VAPI_API_KEY}
+Content-Type: application/json
+
+{
+  "assistantId": "6663a81b-a173-4ffd-b297-1c17aa66dead",
+  "phoneNumberId": "<vapi-pn-id>",
+  "customer":     { "number": "+15551234567" },
+  "assistantOverrides": {
+    "variableValues": {
+      "firstName":            "Jane",
+      "lastName":             "Doe",
+      "phoneNumber":          "+15551234567",
+      "knownEmail":           "jane@example.com",
+      "companyName":          "Example Corp",
+      "jobTitle":             "Director of IT",
+      "industry":             "Healthcare",
+      "campaignSlug":         "healthcare-2026-03",
+      "offer":                "AI Readiness Discovery Call",
+      "callType":             "immediate",
+      "attemptNumber":        1,
+      "previousCallSummary":  "",
+      "nextCallOpeningContext": ""
+    }
+  }
+}
+```
+
+- `callType` ∈ {`immediate`, `scheduled`, `callback`, `unknown`}.
+  - `immediate` — cold outbound (default for the cadence cron).
+  - `scheduled` — warm inbound from the website's "schedule a call" flow;
+    the prompt uses time-of-day context.
+  - `callback` — prospect dialed back after voicemail; **only set by the
+    `assistant-request` handler, never the outbound caller.**
+- `attemptNumber` — 1, 2, 3, … The prompt branches at 1 vs 2–3 vs final.
+- `previousCallSummary` — the `callSummary` field returned on the previous
+  attempt's `end-of-call-report`; backend stitches across attempts.
+- `nextCallOpeningContext` — one-sentence opener hint produced by the
+  prior call's structured output; pass it through so the next opener
+  sounds warm, not robotic.
+
+Response (excerpt):
+```json
+{ "id": "<call-id>", "status": "queued", "assistantId": "...", ... }
+```
+
+Persist `id` against the call attempt — it's the join key for the webhook.
+
+## 2) End-of-call webhook
+
+`POST https://webhook.togahub.com/vapi` with `message.type =
+"end-of-call-report"`. **Verify the Vapi signature with `VAPI_SERVER_SECRET`
+before processing — unsigned requests must 401.**
+
+Payload (excerpt):
+
+```json
+{
+  "message": {
+    "type": "end-of-call-report",
+    "endedReason": "customer-ended-call",
+    "call":     { "id": "...", "assistantId": "...", "customer": {...} },
+    "transcript": "Hi, this is Alex from TOGA... [full string]",
+    "messages":   [ {"role": "...", "message": "..."}, ... ],
+    "analysis": {
+      "summary":         "Prospect interested; meeting booked for...",
+      "structuredData": {
+        "callOutcome":              "meeting_booked",
+        "phpWorkerAction":          "BOOK_CALCOM_MEETING",
+        "dncRequested":             false,
+        "prospectSentiment":        "positive",
+        "qualificationScore":       4,
+        "callSummary":              "...",
+        "contactEmail":             "jane@example.com",
+        "emailMatchedKnown":        true,
+        "meetingTime":              "2026-06-18T15:00:00-05:00",
+        "callbackTime":             "",
+        "callbackContactPreference": "",
+        "callType":                 "immediate",
+        "nextCallOpeningContext":   "...",
+        "nurtureFollowUpTimeframe": "",
+        "nurtureTopic":             "",
+        "referralName":             "",
+        "referralTitle":            "",
+        "dncReason":                ""
+      }
+    }
+  }
+}
+```
+
+### `phpWorkerAction` dispatch table
+
+| Action | What the worker does |
+|---|---|
+| `BOOK_CALCOM_MEETING` | `POST /v2/bookings` to Cal.com with `meetingTime`; create NetSuite lead; mark contact `meetingBooked`; stop cadence. |
+| `SCHEDULE_CALLBACK` | Update `contacts.dtAgreedUponNextContact = callbackTime`; reschedule via cadence cron; record `callbackContactPreference`. |
+| `SEND_NURTURE_EMAIL` | Queue email with topic = `nurtureTopic`; schedule sentinel for `nurtureFollowUpTimeframe`. |
+| `FLAG_DNC_REMOVE_FROM_CAMPAIGNS` | **NON-NEGOTIABLE.** Set `isOkayToCall=0`; remove contact from every active campaign; log `dncReason`. |
+| `MARK_NOT_INTERESTED` | Set `lastCallOutcome`; apply campaign-level not-interested cadence (typically: no retry for 90 days). |
+| `MARK_WRONG_PERSON` | If `referralName` populated → create new contact + link to original; close the original attempt. |
+| `MARK_VOICEMAIL_RETRY` | Apply voicemail-retry cadence (e.g. retry in 24h, max 3 attempts). |
+| `MARK_NO_ANSWER_RETRY` | Apply no-answer retry cadence (typically tighter than voicemail). |
+| `MARK_GATEKEEPER_BLOCKED_RETRY` | Try a different day-of-week / time-of-day next attempt. |
+| `NO_ACTION` | Log only; cadence cron decides what to do (often used when the call ended ambiguously). |
+
+### DNC short-circuit
+
+```
+if structuredData.dncRequested == true:
+    run FLAG_DNC_REMOVE_FROM_CAMPAIGNS, regardless of phpWorkerAction
+    log dncReason
+    do NOT proceed to any other action
+```
+
+This is the only rule that overrides `phpWorkerAction`. Keep it.
+
+## 3) Inbound `assistant-request` webhook (callbacks)
+
+When a prospect dials the BDR number back (after a voicemail or because
+they were given the number), Vapi posts:
+
+```json
+POST https://webhook.togahub.com/vapi
+{
+  "message": {
+    "type": "assistant-request",
+    "call": { "id": "...", "customer": { "number": "+15551234567" } }
+  }
+}
+```
+
+**SLA: respond within 7.5 seconds** — Vapi falls back to a default
+assistant otherwise.
+
+Worker must:
+
+1. Look up `contacts` by phone (E.164 — store both `+1XXXXXXXXXX` and
+   10-digit forms in the index so lookup is one query).
+2. Read the most recent call attempt's `callSummary` and store-side
+   campaign config.
+3. Respond:
+
+```json
+{
+  "assistantId": "6663a81b-a173-4ffd-b297-1c17aa66dead",
+  "assistantOverrides": {
+    "variableValues": {
+      "firstName": "Jane",
+      "...":       "...",
+      "callType":            "callback",
+      "attemptNumber":       4,
+      "previousCallSummary": "<prior call's callSummary>"
+    }
+  }
+}
+```
+
+If no contact match: still respond (primary BDR assistant id + empty
+variableValues; `attemptNumber=1`, `callType="unknown"`). The prompt
+gracefully handles `"Information not available"`.
+
+## Where the PHP code lives
+
+**Not in this repo.** The handler lives in the TOGA worker repo (`worker`
+for 1.0 or `worker2` for 2.0). Likely class shape:
+
+- 1.0: an `App_Controller_*` for the webhook (under the framework's HTTP
+  surface), with an `App_Worker_*` or scheduled cron for cadence.
+- 2.0: a `_Controller_*` for the webhook + `_Worker_*` invoked from the
+  `_Queue` dispatcher for cadence.
+
+When the actual PHP code is committed to `worker` / `worker2`, add a
+feature doc in that repo's `features/` and link it from this file's
+`related:`.
+
+## Security
+
+- **Verify `Vapi-Signature` on every webhook** using
+  `VAPI_SERVER_SECRET`. Reject unsigned requests with 401.
+- **Idempotency:** dedupe webhooks by `message.call.id` — Vapi may retry
+  on transient failures.
+- **PII in the transcript** — treat at rest as PII (names, phone numbers,
+  emails, sometimes payment hints). Don't log full transcripts to
+  unredacted backends.
+- **DNC is auditable.** Persist `dncReason` + raw structured-output JSON
+  alongside the action so a future compliance review can reconstruct
+  intent.
+
+## Gotchas / known issues
+
+- **`assistant-request` SLA is 7.5 s.** Anything synchronous in the path
+  (NetSuite, slow joins) will trip Vapi's fallback. Cache contact lookups
+  by phone in Redis with a 60 s TTL if the DB hop is slow.
+- **`callType="callback"` must include `previousCallSummary`** — leaving
+  it empty makes the assistant open like a cold call. Empty is acceptable
+  only when the contact is genuinely unknown.
+- **Cal.com booking happens server-side**, not by the assistant. The
+  `GetBookingSlots` tool only *suggests* a slot to the prospect; the worker
+  is responsible for actually reserving it on `BOOK_CALCOM_MEETING`.
+- **Schema field additions need both sides.** Adding a field to the shared
+  structured-output schema without a corresponding handler branch in the
+  worker silently drops data. Coordinate via `update_structured_output.py`
+  dry-run + worker PR.
+- **`attemptNumber` is 1-indexed**, not 0-indexed. First call = 1.
+
+## Change history
+- 2026-06-16 — Initial call-orchestration feature doc (PHP ↔ Vapi seam). (akhokhani)

package/knowledge/2.0/apps/ai-bdr/features/vapi-integration.md

@@ -0,0 +1,171 @@
+---
+title: Vapi Integration — Assistants, Tools, Structured Output
+framework: "2.0"
+repo: ai-bdr
+project: AI-BDR
+client: shared
+type: feature
+status: active
+updated: 2026-06-16
+owners: [akhokhani]
+files:
+  - ai-bdr/vapi/templates/assistant.template.json
+  - ai-bdr/vapi/templates/system-prompt.template.md
+  - ai-bdr/prompts/archive/prompt-may-15.txt
+  - ai-bdr/prompts/campaigns/healthcare-2026-03-18.md
+  - ai-bdr/prompts/campaigns/healthcare-v2-2026-03-25.md
+  - ai-bdr/prompts/templates/campaign-template.md
+  - ai-bdr/scripts/update_assistant.py
+  - ai-bdr/scripts/update_system_prompt.py
+  - ai-bdr/scripts/update_structured_output.py
+  - ai-bdr/scripts/update_call_summary_context.py
+  - ai-bdr/scripts/fix_booking_guardrails.py
+  - ai-bdr/scripts/get_assistant.py
+  - ai-bdr/docs/vapi-firstmessage-timing-fix.md
+  - ai-bdr/docs/vapi-voicemail-iphone-screening.md
+related:
+  - ../architecture.md
+  - call-orchestration.md
+  - ../workflows/new-campaign-onboarding.md
+---
+
+## Summary
+
+Everything inside Vapi: the three assistants, the three shared tools, the
+shared structured-output schema, the Liquid-templated system prompt, and
+the Python scripts that author them. PHP never touches Vapi config — all
+changes go through the scripts in this repo.
+
+## Key files / entry points
+
+| File | Purpose |
+|---|---|
+| `vapi/templates/assistant.template.json` | Reference shape of a Vapi assistant (model, voice, transcriber, tools, server-message subscriptions) |
+| `vapi/templates/system-prompt.template.md` | Liquid skeleton for the system prompt |
+| `prompts/archive/prompt-may-15.txt` | Canonical reference prompt — Phases 1–6, persistence rules, email verification, objection handling, DNC compliance |
+| `prompts/campaigns/healthcare-*.md` | Active per-campaign prompts |
+| `scripts/get_assistant.py` | Fetch a live assistant JSON (read-only) |
+| `scripts/update_assistant.py` | **Core** — patch firstMessage / system prompt / structured-output fields. Dry-run by default; `--apply` writes |
+| `scripts/update_system_prompt.py` | Push a prompt file to a live assistant |
+| `scripts/update_structured_output.py` | Modify the shared schema (add a field, change an enum) |
+| `scripts/update_call_summary_context.py` | Inject `previousCallSummary` into the prompt for follow-up attempts |
+| `scripts/fix_booking_guardrails.py` | Guardrails for `GetBookingSlots` (e.g. don't span Friday→Monday) |
+
+## Assistants
+
+All three assistants share the same skeleton; they differ only in
+firstMessage, system prompt, and the phone number wired to them.
+
+| Field | Value |
+|---|---|
+| Model | OpenAI `gpt-4.1`, `temperature=0.5`, `maxTokens=250` |
+| Voice | Vapi "Elliot" @ speed 0.9; fallback "Neil" |
+| Transcriber | Deepgram Nova-3 (confidence threshold 0.4) |
+| VAD / endpointing | Vapi defaults; voicemail detection 6 retries, 5 s initial + 5 s frequency backoff |
+| Server messages | `end-of-call-report` (all); `status-update` (when first-message-timing live); `assistant-request` (on inbound callbacks) |
+| Server URL | `https://webhook.togahub.com/vapi` |
+
+### Phone numbers + assistant IDs
+
+- Primary BDR — `+1 (216) 616-0067` — `6663a81b-a173-4ffd-b297-1c17aa66dead`
+- Healthcare — `+1 (331) 244-5958` — `0c058f55-1610-413c-ae04-c71b30b33a43`
+- Tech demo — `+1 (331) 281-1679` — `0505c46e-1150-4814-9a5c-60ad44287abf`
+
+## Tools (3, shared across assistants)
+
+| Tool | Id | Purpose |
+|---|---|---|
+| `end_call_tool` | `2c7e5ce6-d3ef-4239-85e1-e8da489a9229` | Closes the call with a two-turn closing protocol; never invoked before the prospect's last word is acknowledged |
+| `GetBookingSlots` (api_request_tool) | `a51209dc-bd08-441c-ba20-dc87b0fc163b` | `GET https://cal.com/api/v2/slots?eventTypeSlug=<campaign>&teamSlug=toga-technology&start={{start}}&end={{end}}&timeZone=America/Chicago` |
+| `kb_search` | `0b2b7a85-6111-4fea-86cd-3b1696ec5ae8` | Gemini 2.0 Flash retrieval over ~12 TOGA service / compliance PDFs |
+
+The assistant is **not** allowed to invent meeting times — it must call
+`GetBookingSlots`, name the slot to the prospect, and let the prospect
+confirm. The actual booking happens in the PHP worker after the call.
+
+## Liquid-templated system prompt
+
+The prompt branches on:
+
+- `{{attemptNumber}}` — `1` (cold opener) vs `2-3` (follow-up with prior
+  context) vs `final` (last-attempt heuristics).
+- `{{callType}}` — `immediate` (cold outbound) / `scheduled` (warm
+  inbound, time-of-day matters) / `callback` (prospect dialed back; use
+  `previousCallSummary` to resume) / `unknown` (fall-back path).
+- Missing fields render as `"Information not available"` — never as an
+  empty string (which would silently break openers).
+
+`scripts/update_assistant.py` reads the prompt markdown, fills the Liquid
+template, and PATCHes the live assistant. `--apply` is required to write —
+default is dry-run with a diff.
+
+## Structured output schema (shared, id `daaa4639-4143-4c3f-a71a-2a78ad3c163f`)
+
+Returned in `message.analysis.structuredData` on every `end-of-call-report`:
+
+| Field | Type | Notes |
+|---|---|---|
+| `callOutcome` | string enum | `meeting_booked`, `callback_scheduled`, `nurture_requested`, `not_interested`, `dnc_requested`, `voicemail`, `wrong_person`, `gatekeeper_blocked`, `no_answer` |
+| `phpWorkerAction` | string enum | The action the PHP worker should perform — see `call-orchestration.md` for the full enum |
+| `dncRequested` | boolean | Independent of `phpWorkerAction`. **If true, the worker MUST run `FLAG_DNC` regardless of the suggested action.** |
+| `prospectSentiment` | string enum | `positive` / `neutral` / `negative` / `hostile` |
+| `qualificationScore` | int | 1 (cold) – 5 (hot); cold outreach mostly lands at 2–3 |
+| `callSummary` | string | One paragraph; reused as `previousCallSummary` on next attempt |
+| `contactEmail` | string | Email the prospect confirmed; empty if not collected |
+| `emailMatchedKnown` | boolean | True if confirmed email matches `knownEmail` from variableValues |
+| `meetingTime` | ISO 8601 | Present if `callOutcome=meeting_booked` |
+| `callbackTime` | ISO 8601 | Present if `callOutcome=callback_scheduled`; backend converts a spoken time to ISO |
+| `callbackContactPreference` | string | `phone` / `email` / `sms` |
+| `callType` | string | Mirrors the `callType` variable injected on this call |
+| `nextCallOpeningContext` | string | One-sentence coaching note for the next attempt's opener |
+| `nurtureFollowUpTimeframe` | string | e.g. `"2 days"` |
+| `nurtureTopic` | string | e.g. `"AI Readiness Whitepaper"` |
+| `referralName`, `referralTitle` | strings | If `callOutcome=wrong_person`, the contact the prospect referred you to |
+| `dncReason` | string | e.g. `"prospect_request"` / `"regulatory"` |
+
+To change the schema: `python scripts/update_structured_output.py` (dry
+run by default; pass `--apply` to write). Adding a field needs a paired
+PHP worker handler change — coordinate before deploying.
+
+## Environment variables (`.env.example`)
+
+```
+VAPI_API_KEY=                        # Vapi private API key
+VAPI_SERVER_SECRET=                  # Vapi webhook secret (verify signature)
+VAPI_ASSISTANT_ID=6663a81b-...       # default target for scripts
+VAPI_STRUCTURED_OUTPUT_ID=daaa...    # shared schema id
+VAPI_END_CALL_TOOL_ID=2c7e5ce6-...
+VAPI_BOOKING_TOOL_ID=a51209dc-...
+VAPI_BASE_URL=https://api.vapi.ai    # optional override
+```
+
+Secret values live only in `.env` (gitignored) and in the deployment
+runtime — never in the repo.
+
+## Why scripts use raw HTTP (`requests` + curl-style headers) instead of the Vapi SDK
+
+Cloudflare in front of `api.vapi.ai` blocks default `python-requests`
+user-agents. The scripts spoof a curl-like UA. If you swap to an SDK,
+ensure UA spoofing is preserved or you'll see 403s with no body.
+
+## Gotchas / known issues
+
+- **Voicemail detection isn't perfect on iPhone "Silence Unknown Callers".**
+  See `docs/vapi-voicemail-iphone-screening.md` for the screening
+  workaround.
+- **First-message timing (Option B)** — the assistant waits for the human's
+  first phoneme before speaking, via the `status-update` server message.
+  Don't unsubscribe from `status-update` without re-checking the prompt's
+  opener logic.
+- **`GetBookingSlots` can span a weekend.** `fix_booking_guardrails.py`
+  enforces a Mon–Fri 9–5 default; relax it cautiously.
+- **`previousCallSummary` is regenerated per call** — don't try to persist
+  one paragraph as the long-running CRM note; that's `callSummary` plus
+  PHP-side aggregation.
+- **One structured-output schema, all assistants.** Adding a campaign-
+  specific field forces every other assistant to declare it (Vapi resolves
+  by id). Prefer a generic field with campaign-level meaning encoded in
+  `callSummary` over a schema fork.
+
+## Change history
+- 2026-06-16 — Initial Vapi integration feature doc. (akhokhani)

package/knowledge/2.0/apps/ai-bdr/workflows/new-campaign-onboarding.md

@@ -0,0 +1,148 @@
+---
+title: New-Campaign Onboarding (6-phase runbook)
+framework: "2.0"
+repo: ai-bdr
+project: AI-BDR
+client: shared
+type: workflow
+status: active
+updated: 2026-06-16
+owners: [akhokhani]
+files:
+  - ai-bdr/docs/client-onboarding-sop.md
+  - ai-bdr/docs/calcom-new-campaign-event-guide.md
+  - ai-bdr/prompts/templates/campaign-template.md
+  - ai-bdr/scripts/update_assistant.py
+  - ai-bdr/scripts/update_system_prompt.py
+related:
+  - ../architecture.md
+  - ../features/vapi-integration.md
+  - ../features/call-orchestration.md
+---
+
+## Summary
+
+The end-to-end procedure for launching a new outbound BDR campaign
+(industry, offer, target persona, geography). Six phases, spans marketing
++ backend + Vapi config + Cal.com + QA + go-live. Source of truth is
+`docs/client-onboarding-sop.md`; this doc captures the operational shape
+so a future Claude session can drive it.
+
+## Phase 1 — Marketing brief
+
+Inputs needed before any code or config changes:
+
+- Campaign slug — kebab-case, used everywhere (`campaignSlug` variable,
+  Cal.com event-type slug, prompt filename).
+- Industry + persona — target title/seniority.
+- Offer — the one-line value prop the assistant pitches.
+- Geography + time zone for cadence.
+- Meeting contact info — who the booked meeting is *with* (name, email,
+  Cal.com handle).
+- Compliance posture — DNC handling defaults are non-negotiable; capture
+  any campaign-specific addenda (e.g. healthcare HIPAA mentions).
+
+Owner: marketing / sales. Hand off written + signed.
+
+## Phase 2 — Backend setup (PHP worker side)
+
+In `worker` / `worker2`:
+
+1. Insert a `campaigns` row with the slug, offer, persona, cadence rules,
+   and the meeting contact's Cal.com handle.
+2. Add a contact import job for the prospect list (CSV → `contacts`),
+   tagged with the campaign slug.
+3. Confirm the cadence cron picks up the new campaign (typical interval:
+   every N minutes scan for `dtAgreedUponNextContact <= now AND
+   isOkayToCall=1`).
+
+## Phase 3 — Vapi config
+
+Two paths:
+
+**A. Reuse the primary BDR assistant** (preferred for early campaigns):
+
+1. Copy `prompts/templates/campaign-template.md` → `prompts/campaigns/<slug>.md`.
+2. Fill the Liquid placeholders (offer, persona, KB topics).
+3. `python scripts/update_system_prompt.py --assistant-id <primary> --prompt prompts/campaigns/<slug>.md`
+   — dry-run first, review diff, then `--apply`.
+4. The shared structured-output schema needs no change unless the
+   campaign requires a new field (very rare — see `vapi-integration.md`
+   §gotchas).
+
+**B. Provision a new dedicated assistant** (only when the campaign needs a
+different voice / phone number / model):
+
+1. Provision a Vapi phone number; capture `phoneNumberId`.
+2. Create a new assistant from `vapi/templates/assistant.template.json`
+   with the new firstMessage + the per-campaign prompt.
+3. Wire it to the **same** structured-output schema id and the same three
+   tool ids — never fork the schema.
+4. Add the assistant id + phone number id to the `campaigns` row in PHP.
+
+## Phase 4 — Cal.com event
+
+Per `docs/calcom-new-campaign-event-guide.md` (≈5 minutes):
+
+1. Create an event type with slug = campaign slug, team =
+   `toga-technology`, default duration 30 min, time zone matching the
+   campaign target.
+2. Set the meeting contact as the host.
+3. Verify the slug returns slots at
+   `https://cal.com/api/v2/slots?eventTypeSlug=<slug>&teamSlug=toga-technology&start=YYYY-MM-DD&end=YYYY-MM-DD&timeZone=America/Chicago`.
+
+## Phase 5 — Integration testing
+
+Drive end-to-end through a personal phone:
+
+1. From PHP, `POST /call/phone` to your own number with full
+   variableValues + `attemptNumber=1`, `callType=immediate`.
+2. Verify the assistant answers, runs the flow, books a real Cal.com slot
+   via `GetBookingSlots`, ends gracefully (two-turn closing protocol).
+3. Verify the `end-of-call-report` webhook arrives at
+   `webhook.togahub.com/vapi` with the expected `phpWorkerAction`.
+4. Verify the worker handler dispatches correctly (DNC, booking, callback,
+   nurture, retry).
+5. Verify the `assistant-request` flow by calling the BDR number back from
+   your test phone within the same hour — confirm `callType=callback` and
+   `previousCallSummary` populates the next call.
+
+## Phase 6 — Go-live
+
+- Move campaign status to `active` in `campaigns`.
+- Confirm cadence cron is consuming.
+- Spot-check the first 10 call recordings in the Vapi dashboard.
+- Set up CloudWatch / TOGa Hub log alerts on:
+  - `phpWorkerAction` distribution shift (sudden DNC spike, sudden
+    NO_ACTION surge).
+  - Webhook signature failures (auth misconfig).
+  - `assistant-request` SLA breaches (P95 > 5 s).
+
+## Rollback
+
+Per-phase reversibility:
+
+- Phase 1–2 — pause cadence in `campaigns` (`status=paused`).
+- Phase 3 — re-run `update_system_prompt.py` with the prior prompt; the
+  diff log is your audit trail.
+- Phase 4 — disable the Cal.com event type (slots return empty; the
+  assistant gracefully tells the prospect "no times available, I'll email
+  options").
+- Phase 5–6 — flip `isOkayToCall` for the campaign's contact set;
+  cadence stops within one cron tick.
+
+## Common failure modes
+
+- **First call sounds robotic.** Cause: `attemptNumber=1` + empty
+  `previousCallSummary` is fine, but **empty `companyName` / `jobTitle`
+  also renders as "Information not available"** which spooks the opener.
+  Fix at the import job, not the prompt.
+- **DNC requests not honored.** Cause: handler reads `phpWorkerAction`
+  before `dncRequested`. Always evaluate `dncRequested` first.
+- **Cal.com returns weekend slots.** Cause: `fix_booking_guardrails.py`
+  not applied on the new event type. Re-run after creating each event.
+- **`assistant-request` 7.5 s SLA breach.** Cause: NetSuite synchronous
+  lookup in the handler. Move NetSuite out of the hot path.
+
+## Change history
+- 2026-06-16 — Initial new-campaign onboarding workflow doc. (akhokhani)

package/knowledge/INDEX.md

@@ -24,6 +24,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **toga2-hub** (TOGa Hub) — 2 doc(s) → [2.0/apps/toga2-hub/INDEX.md](2.0/apps/toga2-hub/INDEX.md)
 - **talos** (TOGa IQ) — 6 doc(s) → [2.0/apps/talos/INDEX.md](2.0/apps/talos/INDEX.md)
 - **voice-to-voice** (TOGa Voice) — 4 doc(s) → [2.0/apps/voice-to-voice/INDEX.md](2.0/apps/voice-to-voice/INDEX.md)
+- **ai-bdr** (AI-BDR) — 4 doc(s) → [2.0/apps/ai-bdr/INDEX.md](2.0/apps/ai-bdr/INDEX.md)
 
 ## standalone framework
 

package/knowledge/clients/compass-usa/INDEX.md

@@ -4,6 +4,6 @@
 |-----|-----------|---------|-------|
 | [Compass ASN → ItemFulfillment Auto-Creation](features/asn-to-item-fulfillment.md) | 2.0 | For Compass USA, posting an AdvanceShippingNotice (ASN) auto-creates the ItemFulfillment (IF) on the upstream SalesOrder. | _underscore/Model/Compass/AdvanceShippingNotice.php, api2/Component/Api/Cxml/Cxml.php, dbchanges2/Client_Compass/2026-06-11 - AsnItemTrackingNumberAcl.sql, dbchanges2/Client_Compass/2026-06-15b - BackfillSA132781ItemFulfillmentTracking.sql |
 | [Compass: Item-Fulfillment TableViews (for-sales-order-items & for-sales-orders, tracking via bridge)](features/item-fulfillment-tracking-tableview.md) | 2.0 | Two sibling Compass TableViews in `Client_Compass` display fulfilled items in toga2-supply, both driven by `TableViews` / `TableViewJoins` / `TableViewFields` c | dbchanges2/Client_Compass/2026-06-10 - ItemFulfillmentsForSalesOrderItemsTableView.sql, dbchanges2/Client_Compass/2026-06-11 - ItemFulfillmentsForSalesOrdersTableView.sql, dbchanges2/Client_Compass/2026-06-15a - FixItemFulfillmentTrackingNumberJoins.sql |
-| [Compass MITS PO → SO Item Linking](features/mits-po-to-so-item-linking.md) | 2.0 | MITS sends Compass inbound Purchase Orders (`POST /v2/purchase-orders`) against a Sales Order (`mitsSalesOrder`). | _underscore/Model/Compass/PurchaseOrder.php |
+| [Compass MITS PO → SO Item Linking](features/mits-po-to-so-item-linking.md) | 2.0 | MITS sends Compass inbound Purchase Orders (`POST /v2/purchase-orders`) against a Sales Order (`mitsSalesOrder`). | _underscore/Model/Compass/PurchaseOrder.php, worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php |
 | [Compass USA](profile.md) | 2.0 | Compass USA is a TOGA client running a multi-tier supply-chain commerce operation. |  |
 | [Compass Order Lifecycle & Data-Integrity Invariants](workflows/order-lifecycle-and-data-integrity.md) | 2.0 | End-to-end map of how a Compass order flows through the `Client_Compass` (2.0) database and the **expected raw-data shape** at each link/ASN/IF level. |  |

package/knowledge/clients/compass-usa/features/mits-po-to-so-item-linking.md

@@ -6,10 +6,11 @@ project: _Underscore
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-06-11
+updated: 2026-06-16
 owners: ["jcardinal"]
 files:
   - _underscore/Model/Compass/PurchaseOrder.php
+  - worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php
 related:
   - asn-to-item-fulfillment.md
 ---
@@ -90,7 +91,34 @@ USA and Canada share the parent handler unchanged.
     other orders (e.g. SA114091 25→125) do not fit the split-PO 2× pattern and are a separate,
     uninvestigated cause.
 
+- **SECOND, INDEPENDENT source of the same cross-part links — the Office Depot worker cron
+  (fixed 2026-06-16).** The 2026-06-11 fix above only covered the `_underscore`
+  `_Model_Compass_PurchaseOrder` path. Office-Depot-originated POs are imported by the **1.0
+  worker** cron `worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php`,
+  which had its **own** off-by-one. It creates the bridge twice: (A) correctly, inline in the
+  `/purchase-orders` POST payload via `$lookupSalesOrderItemUuidFromPurchaseOrderLine` (keyed by
+  the PO item's lineNumber); then (B) a redundant second loop that paired the **API-returned**
+  PO items to queued SO links **by array index** (`$queuedSoiPoiLinks[$indPurchaseOrderItem]`),
+  assuming the response lists PO items in submission order. When the SO carries a config-parent
+  line (line 1), the returned order is offset, so path B inserted an extra bridge row pointing
+  each PO item at the SO line **one above** its real line — the same wrong-part scramble, and
+  the same downstream tracking misattribution. **Confirmed on SA132763:** each part (9X3V1UT,
+  920-012059) received its own tracking number plus a neighbor's, surfacing as duplicate IF
+  lines in NetSuite. **Fix:** path B now resolves each returned PO item's SOI by its own
+  `lineNumber` via the same `$lookupSalesOrderItemUuidFromPurchaseOrderLine`, and the dead
+  `$queuedSoiPoiLinks` is removed. The cleanup predicate is unchanged (`soi.itemId <> vi.itemId`
+  via `VendorItems`); for tracking, an item-level `ItemFulfillmentItems_TrackingNumbers` row is
+  spurious unless some ASN item carrying that tracking number maps (by actual item) to the IFI's
+  SOI — see `dbchanges2/Client_Compass/2026-06-16 - CleanupSA132763CrossLineTracking.sql`.
+- **Scope still open:** ~116 PO items across other Compass orders still carry the consecutive
+  off-by-one bridge fingerprint (a `SalesOrderItems_PurchaseOrderItems` PO item linked to two
+  adjacent SO items). Only SA132763 was remediated; a broader reviewed backfill is pending.
+
 ## Change history
+- 2026-06-16 — Found and fixed a SECOND source of cross-part bridge links: the Office Depot
+  worker cron `3a_import_office_depot_purchase_orders.php` paired API-returned PO items to SO
+  items by array index; now pairs by lineNumber. Remediated SA132763's spurious bridge +
+  cross-line tracking (dated dbchanges2 file). ~116 other orders still pending. (jcardinal)
 - 2026-06-11 — Documented the over-fulfillment symptom and the phantom-IFI cleanup predicate;
   remediated SA132657 and SA132641 (one dated dbchanges2 file each). (jcardinal)
 - 2026-06-11 — Guarded `postPost` SO↔PO item linking to MR orders only; SA links come solely

package/knowledge/registry.json

@@ -16,5 +16,6 @@
   { "repo": "walmarttechservices", "project": "Walmart Tech Services", "framework": "1.0", "role": "app", "dependsOn": ["library"] },
   { "repo": "talos",       "project": "TOGa IQ",      "framework": "2.0", "role": "app", "dependsOn": [] },
   { "repo": "test",        "project": "Test",        "framework": "1.0", "role": "app",  "dependsOn": ["library"] },
-  { "repo": "voice-to-voice", "project": "TOGa Voice", "framework": "2.0", "role": "app", "dependsOn": [] }
+  { "repo": "voice-to-voice", "project": "TOGa Voice", "framework": "2.0", "role": "app", "dependsOn": [] },
+  { "repo": "ai-bdr",      "project": "AI-BDR",      "framework": "2.0", "role": "app", "dependsOn": [] }
 ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.93",
+  "version": "1.0.95",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",