toga-ai 1.0.395 → 1.0.397

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

@@ -6,7 +6,7 @@
 | [BDR Web Funnel — Full Implementation Plan](features/bdr-web-funnel-plan.md) | > **Execution status (2026-07-16):** PLAN **Phases 0–5 are BUILT and QA'd**, Phase 6 > was **mostly already built** (the `info` contract was implemented at comm | bdr/PLAN.md, bdr/mockup/app.jsx, bdr/mockup/screens.jsx, bdr/mockup/components.jsx |
 | [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 |
-| [Web Funnel — Built Next.js App (structure, stack, how to run)](features/web-funnel-app.md) | The **built** state of the BDR web funnel — the Next.js UI / lead-capture front door of the existing AI-BDR product (see `../architecture.md`). | bdr/PLAN.md, bdr/.gitignore, bdr/eslint.config.mjs, bdr/amplify.yml, bdr/src/app, bdr/src/app/layout.tsx, bdr/src/app/page.tsx, bdr/src/app/studio.css, bdr/src/lib/resolveCampaignId.ts, bdr/src/lib/scheduleSlots.ts, bdr/src/lib/formatPhone.ts, bdr/src/lib/analytics.ts, bdr/src/lib/rateLimit.ts, bdr/src/lib/clientIp.ts, bdr/src/proxy.ts, bdr/.env.example, bdr/src/components/GoogleAnalytics.tsx, bdr/src/components/RichText.tsx, bdr/src/content, bdr/src/components, bdr/src/flow, bdr/src/server, bdr/src/server/toga.ts, bdr/src/app/api, bdr/test, bdr/test/togaPrimaryPhone.test.ts, bdr/public, bdr/mockup/styles.css |
+| [Web Funnel — Built Next.js App (structure, stack, how to run)](features/web-funnel-app.md) | The **built** state of the BDR web funnel — the Next.js UI / lead-capture front door of the existing AI-BDR product (see `../architecture.md`). | bdr/PLAN.md, bdr/.gitignore, bdr/src/server/hubspot.ts, bdr/src/server/leadSink.ts, bdr/src/server/callbackService.ts, bdr/src/server/workerDialer.ts, bdr/src/lib/shareMailto.ts, bdr/src/flow/screens/CallNow.tsx, bdr/src/flow/screens/Schedule.tsx, bdr/src/flow/screens/CallSummary.tsx, bdr/src/content/schema.ts, bdr/src/content/default.ts, bdr/test/togaEnrichment.test.ts, bdr/test/fastDial.test.ts, bdr/test/shareMailto.test.ts, bdr/eslint.config.mjs, bdr/amplify.yml, bdr/src/app, bdr/src/app/layout.tsx, bdr/src/app/page.tsx, bdr/src/app/studio.css, bdr/src/lib/resolveCampaignId.ts, bdr/src/lib/scheduleSlots.ts, bdr/src/lib/formatPhone.ts, bdr/src/lib/analytics.ts, bdr/src/lib/rateLimit.ts, bdr/src/lib/clientIp.ts, bdr/src/proxy.ts, bdr/.env.example, bdr/src/components/GoogleAnalytics.tsx, bdr/src/components/RichText.tsx, bdr/src/content, bdr/src/components, bdr/src/flow, bdr/src/server, bdr/src/server/toga.ts, bdr/src/app/api, bdr/test, bdr/test/togaPrimaryPhone.test.ts, bdr/public, bdr/mockup/styles.css |
 | [Web Funnel — Next.js UI + Config-Driven Campaign Content](features/web-funnel-content-model.md) | > **Status note (RESOLVED 2026-07-16):** the content **contract** below (schema, > provider seam, adapters) is BUILT and QA'd (PLAN Phases 0–5). | bdr/src/content/schema.ts, bdr/src/content/provider.ts, bdr/src/content/useCampaign.ts, bdr/src/content/default.ts, bdr/src/lib/resolveCampaignId.ts, bdr/src/server/leadSink.ts, bdr/src/server/callbackService.ts, bdr/src/app/api/call-now/route.ts, bdr/src/app/api/call-later/route.ts, bdr/src/app/api/contact/route.ts |
 | [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 |
-| [Safe AI-BDR Call-Loop Testing (isolated test-campaign runbook)](workflows/safe-call-loop-testing.md) | How to prove the AI-BDR **dialer → Vapi → end-of-call webhook** loop end-to-end **without dialing real prospects**. | dbchanges2/Client_True/2026-07-20a - AiBdrTcoxTestCampaign.sql, worker2/Worker/Ai/Bdr/Vapi.php, worker2/Config/beta.ini |
+| [Safe AI-BDR Call-Loop Testing (isolated test-campaign runbook)](workflows/safe-call-loop-testing.md) | How to prove the AI-BDR **dialer → Vapi → end-of-call webhook** loop end-to-end **without dialing real prospects**. | dbchanges2/Client_True/2026-07-20a - AiBdrTcoxTestCampaign.sql, worker2/Worker/Ai/Bdr/Vapi.php, worker2/Worker/Ai/Bdr/ZoomInfo.php, worker2/Config/beta.ini |

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

@@ -6,8 +6,8 @@ project: AI-BDR
 client: shared
 type: feature
 status: active
-updated: 2026-06-16
-owners: [akhokhani]
+updated: 2026-07-21
+owners: [akhokhani, tcox]
 files:
   - ai-bdr/vapi/templates/assistant.template.json
   - ai-bdr/vapi/templates/system-prompt.template.md
@@ -71,6 +71,14 @@ firstMessage, system prompt, and the phone number wired to them.
 - Healthcare — `+1 (331) 244-5958` — `0c058f55-1610-413c-ae04-c71b30b33a43`
 - Tech demo — `+1 (331) 281-1679` — `0505c46e-1150-4814-9a5c-60ad44287abf`
 
+**A campaign's caller ID is its `Campaigns.c_fromPhoneNumberIdentifier`, not "the primary BDR
+number."** Live example: campaign 2 (`26.05 - AI BDR - Ryan Nitti`) carries
+`c_fromPhoneNumberIdentifier = a5d6cbe1-073b-4288-95e8-853ec6782a96`, which maps to the
+**Healthcare** number `+1 (331) 244-5958` — so that campaign dials from the healthcare caller ID,
+not the primary BDR line. `buildVapiPayload` (worker2 dialer) **hard-requires** this field — a
+campaign created without it cannot place a call (see
+`../workflows/safe-call-loop-testing.md`).
+
 ## Tools (3, shared across assistants)
 
 | Tool | Id | Purpose |
@@ -114,7 +122,7 @@ Returned in `message.analysis.structuredData` on every `end-of-call-report`:
 | `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 |
+| `callbackTime` | ISO 8601 | Present if `callOutcome=callback_scheduled`; backend converts a spoken time to ISO. **BUG (2026-07-21): the model frequently emits natural language with spelled-out numbers (e.g. `"in ten minutes"`) which the PHP parser cannot handle — the callback is then silently dropped. See the convertDateTime gotcha in [worker2 vapi-webhook-handler.md](../../worker2/features/vapi-webhook-handler.md). Fix candidate on this side: constrain this field's schema to ISO 8601 or a numeric-relative format so the model never spells the number out.** |
 | `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 |
@@ -153,10 +161,15 @@ ensure UA spoofing is preserved or you'll see 403s with no body.
 - **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.
+- **First-message timing (Option B) — TESTERS MUST SPEAK FIRST.** The healthcare assistant
+  (`Campaign - HealthCare`, `0c058f55-1610-413c-ae04-c71b30b33a43`) is configured
+  `firstMessageMode = "assistant-waits-for-user"`: it will **not** utter a word until the callee
+  speaks. This is the documented voicemail/iPhone-screening workaround (Option B), but it means a
+  **silent answerer gets silence** — confirmed live 2026-07-21 with an 8-second mutual-silence call
+  that Vapi ended with `endedReason = customer-ended-call`. When manually testing this campaign,
+  **say "Hello?" after answering** or the call dies silently. The assistant waits for the human's
+  first phoneme 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
@@ -168,4 +181,11 @@ ensure UA spoofing is preserved or you'll see 403s with no body.
   `callSummary` over a schema fork.
 
 ## Change history
+- 2026-07-21 — Live go-live findings. Recorded that the healthcare assistant runs
+  `firstMessageMode = "assistant-waits-for-user"` (Option B) so a silent answerer gets silence
+  (confirmed: 8s mutual-silence call, `endedReason=customer-ended-call`) — testers must speak first.
+  Documented that a campaign's caller ID is its `c_fromPhoneNumberIdentifier` (campaign 2's
+  `a5d6cbe1-…` → the Healthcare number, not the primary BDR line) and that `buildVapiPayload`
+  hard-requires that field. Flagged the `callbackTime` spelled-out-number parse bug (schema-side fix
+  candidate: constrain to ISO/numeric-relative) — full detail on the worker2 webhook doc. (tcox)
 - 2026-06-16 — Initial Vapi integration feature doc. (akhokhani)

package/knowledge/2.0/apps/ai-bdr/features/web-funnel-app.md

@@ -6,11 +6,24 @@ project: AI-BDR
 client: shared
 type: feature
 status: active
-updated: 2026-07-20
+updated: 2026-07-21
 owners: [tcox]
 files:
   - bdr/PLAN.md
   - bdr/.gitignore
+  - bdr/src/server/hubspot.ts
+  - bdr/src/server/leadSink.ts
+  - bdr/src/server/callbackService.ts
+  - bdr/src/server/workerDialer.ts
+  - bdr/src/lib/shareMailto.ts
+  - bdr/src/flow/screens/CallNow.tsx
+  - bdr/src/flow/screens/Schedule.tsx
+  - bdr/src/flow/screens/CallSummary.tsx
+  - bdr/src/content/schema.ts
+  - bdr/src/content/default.ts
+  - bdr/test/togaEnrichment.test.ts
+  - bdr/test/fastDial.test.ts
+  - bdr/test/shareMailto.test.ts
   - bdr/eslint.config.mjs
   - bdr/amplify.yml
   - bdr/src/app
@@ -93,7 +106,9 @@ to its ship state (trusted-IP position for X-Forwarded-For; O(1) LRU-capped limi
 - **ESLint flat config** carries a **no-em-dash rule** on shipped strings
   (`Literal` / `TemplateElement` / `JSXText` selectors) — enforces the mockup copy
   rule on in-repo strings (`eslint.config.mjs`).
-- **Vitest** test suite: **114 tests, all green** (10 added 2026-07-20 for the primary-phone
+- **Vitest** test suite: **131 tests, all green** (2026-07-21 added `togaEnrichment.test.ts`,
+  `fastDial.test.ts`, `shareMailto.test.ts` for the enrichment / fast-dial / share features below;
+  10 added 2026-07-20 for the primary-phone
   self-heal — null-pointer re-link, changed-number re-link, create-as-last-resort, strict
   `requestCall` vs. absorbing `upsertContactByEmail`; 13 added in the first 2026-07-16 session:
   phone format/prefill/mask, live-anchor consent links, `submitOk` race; the later 2026-07-16
@@ -168,6 +183,10 @@ to its ship state (trusted-IP position for X-Forwarded-For; O(1) LRU-capped limi
   number next to the fixed `+1` country-code field would dial the wrong country). CallNow
   + Schedule init their number fields from it. (The old `info` site exposed name + email +
   phone the same way; BDR reduces the client-crossing PII to **phone only**.)
+  **Fallback (2026-07-21):** when HubSpot has no phone for the contact, primeLead now falls back to
+  the **Toga contact's existing primary phone** (`LeadRef` gained an optional `phone`) — the one
+  real parity gap the info-vs-BDR audit found (info's `defaultPhone` behavior). So a known lead
+  whose CRM record carries no phone but whose Toga record does still sees their number pre-filled.
 - **Live phone input mask.** `formatPhoneInput()` (`src/lib/formatPhone.ts`) renders a
   progressive `(555) 012-3456` as the user types: hard 10-digit cap (`maxLength=14` on the
   inputs), strips non-digits on paste, idempotent, and backspace-safe by design (formatting
@@ -247,6 +266,93 @@ source of truth for "why isn't my contact being called." Full rules are document
     injection to true reverse/has-many relations). The self-heal covers the funnel meanwhile; the
     same api2 bug likely affects `primaryContactEmailAddress` / `primaryContactAddress` on update.
 
+## Contact enrichment (funnel-side, feeds the Vapi opener)
+
+The funnel enriches the Toga contact at page-prime so the AI-BDR call opener has real context
+(`src/server/hubspot.ts`, `src/server/toga.ts`, `src/server/leadSink.ts`, `src/app/page.tsx`; tests
+`test/togaEnrichment.test.ts`). The HubSpot fetch was extended to pull **industry / city / state /
+website** on top of the existing properties and maps them two ways:
+
+- **Direct Toga columns (worker2's dialer reads these with NO callContext fallback):**
+  `jobtitle → Contacts.title`, `company → Contacts.doingBusinessAs`, `industry → Contacts.industry`.
+  `buildVapiPayload` reads `title` / `companyName` / `companyIndustry` **directly from these columns**
+  and does **not** fall back to `callContext` for them — so if they aren't on the contact row, the
+  opener has nothing.
+- **`callContext` JSON keys (the dialer DOES read these as fallback):** `city → personCity`,
+  `state → personState`, `website → companyWebsite`.
+
+Rules that keep enrichment safe:
+- **Fill-if-empty only** — ZoomInfo CSV import data always wins; enrichment never overwrites a
+  populated field (ZoomInfo is how outbound-list contacts get these fields in the first place — see
+  the parity audit below).
+- **`callContext` merges** with any existing keys winning.
+- **Enrichment ships as a separate absorbed `PUT`** so that an ACL-rejected field can never break
+  core lead capture — the enrichment write is best-effort; the lead-capture write is not.
+- **Live-verified 2026-07-21:** contact 248's first real funnel pass set `title = INTERN` and
+  `doingBusinessAs = "Agilant Solutions, Inc."`, and the Vapi opener used them.
+
+## Fast dial (skip the up-to-60s cron wait)
+
+After a successful **Call Now** write, BDR optionally POSTs the worker's single-contact entry point
+so the call fires in **seconds** instead of waiting up to 60s for the dialer cron
+(`src/server/workerDialer.ts` NEW, `src/server/callbackService.ts`; test `test/fastDial.test.ts`).
+
+- Calls the worker action `Ai/Bdr/Vapi/InitiateOutboundCall` with the contact's **primary
+  phone-row uuid**.
+- **Gated by optional env `TOGA_WORKER_URL`** — unset ⇒ cron-only (no behavior change).
+- **Strictly best-effort:** 5s timeout, all failures absorbed + logged; the cron remains the
+  fallback, and the dialer's own in-progress check prevents a double-dial.
+- **Scheduled calls are deliberately excluded** — they wait for their slot.
+- **Motivation:** the Success screen's "Connecting" animation is scripted theater (~5s) while the
+  cron could take 60s; fast dial makes the theater roughly honest.
+- **SECURITY note / ticket:** the worker's direct-action endpoint accepts **unauthenticated** POSTs
+  (a pre-existing exposure — now load-bearing for a product feature). Flag for hardening; it is not
+  introduced by BDR but BDR now depends on it.
+
+## Anonymous-visit guard (no lead reference ⇒ disabled submit)
+
+With **no** lead reference (the page was opened without `?hsContactId=`), both submit screens now
+**disable the button** and show a content-driven notice ("We couldn't find your contact reference…
+open this page from the link in your email"), replacing the previous silent no-op that faked success
+(`src/flow/screens/CallNow.tsx`, `src/flow/screens/Schedule.tsx`, `src/content/schema.ts`,
+`src/content/default.ts`). This matches info's "Missing contact reference" behavior. Production links
+come from HubSpot personalization tokens —
+`?campaign=slug&hsContactId={{contact.hs_object_id}}&hsCampaignId=uuid` — or, when the campaign
+bundle pins `togaCampaignUuid`, links need only the slug + contact token.
+
+## Share button is a real mailto: (no server-send path)
+
+The CallSummary "Send" button now builds a **`mailto:` URL** (recipient, subject, the displayed
+summary as body) and opens the visitor's own mail client — a real share with **no server-side send
+path**, which deliberately avoids the spam-relay surface of server-sending client-supplied text
+(`src/lib/shareMailto.ts` NEW, `src/flow/screens/CallSummary.tsx`, `src/content/default.ts`; test
+`test/shareMailto.test.ts`). Confirmation copy is honest ("Opening your email app").
+
+- **LIMITATION:** the summary **content** is still the **simulated rotation** — the real
+  `c_callSummary` can't reach the frontend because the BDR API client gets **403 on
+  `ContactAttempts`**.
+- **Pending backend ask (DB ACL config, no deploy):** a read-only grant for the BDR API client on
+  `ContactAttempts` fields `uuid` / `contactId` / `dtStarted` / `dtEnded` / `c_callSummary` /
+  `c_callOutcome`. **One grant unlocks three features:** the real summary in the card, the real
+  summary in Copy/Share, and a live call-status indicator.
+
+## Parity audit — `info` (original) vs `bdr` (new) (§ closed 2026-07-21)
+
+A full audit of the original `info` funnel vs the new BDR funnel closed the open "did we port
+everything?" question in this doc:
+
+- **All API work is ported** — routes, the identical 6-property HubSpot fetch, the Toga payloads.
+- **The `c_*` / title / industry enrichment was populated by NEITHER repo** — it is **net-new**
+  work (see Contact enrichment above), **not** a port miss. Outbound-list contacts normally get
+  those fields from the **ZoomInfo CSV import**.
+- **The `visit` route was intentionally dropped** per PLAN.md (dead 501, no caller).
+- **The only real parity gap was phone prefill fallback** to the Toga contact's existing phone —
+  now shipped (see the phone-prefill fallback note above).
+- **Dead env vars:** `TOGA_PUBLIC_TOKEN_URL` and `NEXT_PUBLIC_ENV` were declared but **never read**
+  even in info's own code — do not carry them into BDR.
+- **BDR deploy env vars = 7 total:** the 5 server-side ones + `NEXT_PUBLIC_GA_MEASUREMENT_ID` +
+  (new 2026-07-21) **`TOGA_WORKER_URL`** (the fast-dial gate; unset ⇒ cron-only).
+
 ## Local dev setup (BDR)
 
 BDR local dev needs **5 server-side env vars** in `BDR/.env.local` (gitignored, never
@@ -281,7 +387,9 @@ up — ClickUp is stale, confirm the real owner before assuming.)
 - **5 server-side env vars are required** (same set as local dev): `TOGA_API_BASE_URL`,
   `TOGA_CLIENT_ID`, `TOGA_CLIENT_API_UUID`, `TOGA_CLIENT_API_SECRET`, `HUBSPOT_ACCESS_TOKEN`.
   **Where the values live (never the values):** the `info` repo's `.env.local` (production
-  credential set). Add them in the Amplify console environment config — never commit them.
+  credential set). Add them in the Amplify console environment config — never commit them. Two
+  optional vars beyond the 5: `NEXT_PUBLIC_GA_MEASUREMENT_ID` (GA4) and **`TOGA_WORKER_URL`** (the
+  fast-dial gate — unset ⇒ cron-only). See the parity audit for the full 7-var accounting.
 - **Phase 8 WAF pairing.** `BDR/PLAN.md` Phase 8 specifies a **per-IP rate rule on the CloudFront
   distribution / WAF** that pairs with the in-app token-bucket limiter (the app limiter is
   defense-in-depth only; the edge WAF rule is the authoritative control — see the enumeration
@@ -416,6 +524,26 @@ up — ClickUp is stale, confirm the real owner before assuming.)
   harness; pull it with `npx toga-ai`.
 
 ## Change history
+- 2026-07-21 — Go-live continuation. **The full AI-BDR call loop was proven end-to-end in
+  production** (campaign 2, `26.05 - AI BDR - Ryan Nitti`): UI submit → funnel API → dialer → Vapi
+  call → webhook write-back (test method now in `../workflows/safe-call-loop-testing.md`). BUILT:
+  (1) **funnel-side contact enrichment** — HubSpot fetch extended with industry/city/state/website,
+  mapping title/company/industry to the Toga columns the dialer reads with NO fallback and
+  city/state/website into `callContext` (fill-if-empty, ZoomInfo wins, absorbed separate PUT;
+  live-verified on contact 248); (2) **phone-prefill fallback** to the Toga contact's existing
+  primary phone when HubSpot has none (the one real parity gap); (3) **fast dial** —
+  `src/server/workerDialer.ts` POSTs the worker's `InitiateOutboundCall` after a Call Now write so
+  the call fires in seconds not up to 60s, gated by optional `TOGA_WORKER_URL`, best-effort,
+  scheduled calls excluded (NOTE: the worker direct-action endpoint is unauthenticated — pre-existing
+  exposure now load-bearing); (4) **anonymous-visit guard** — no lead ref disables both submit
+  buttons with a content-driven notice instead of faking success; (5) **share button** made a real
+  `mailto:` (no server send path). Closed the **info-vs-BDR parity audit** (all API work ported; the
+  `c_*`/enrichment fields are net-new not a port miss; `visit` route intentionally dropped;
+  `TOGA_PUBLIC_TOKEN_URL`/`NEXT_PUBLIC_ENV` are dead; deploy = 7 env vars). LIMITATION recorded: the
+  share/card summary is still the simulated rotation because the BDR API client gets 403 on
+  `ContactAttempts` — pending a read-only ACL grant (one grant unlocks three features). Suite at
+  **131 green**. All of today's BDR work was **uncommitted at capture** (commits go to
+  `BDR-Phase-2` → `_dev-sandbox`). (tcox)
 - 2026-07-20 — FIXED the phone-less-contact dialer bug on the funnel side: shipped a primary-phone
   **self-heal** in `src/server/toga.ts` (commit `4ac579e`) — after any contact write carrying a
   phone, if the echoed `primaryContactPhoneNumber` is null or its last-10 digits mismatch, find/create

package/knowledge/2.0/apps/ai-bdr/workflows/safe-call-loop-testing.md

@@ -6,11 +6,12 @@ project: AI-BDR
 client: shared
 type: workflow
 status: active
-updated: 2026-07-20
+updated: 2026-07-21
 owners: [tcox]
 files:
   - dbchanges2/Client_True/2026-07-20a - AiBdrTcoxTestCampaign.sql
   - worker2/Worker/Ai/Bdr/Vapi.php
+  - worker2/Worker/Ai/Bdr/ZoomInfo.php
   - worker2/Config/beta.ini
 related:
   - new-campaign-onboarding.md
@@ -24,9 +25,16 @@ How to prove the AI-BDR **dialer → Vapi → end-of-call webhook** loop end-to-
 dialing real prospects**. The production dialer cron (`Core.CronJobs` "AI BDR",
 `ProcessAllActiveCampaigns`, schedule `* * * * *`) fires **every minute**, so any campaign that
 becomes eligible starts dialing live prospects **within 60 seconds** — a test must be built so
-that the *only* contact that can ever be dialed is a deliberate test contact. The safe technique
-is an **isolated one-contact test campaign with no call windows**. Eligibility mechanics that make
-this work are in [worker2 vapi-webhook-handler.md](../../worker2/features/vapi-webhook-handler.md).
+that the *only* contact that can ever be dialed is a deliberate test contact. There are **two safe
+vehicles**, both proven live:
+
+- **Approach A — reuse an EXISTING campaign, DNC-zero everyone first (Rule 2).** The go-live
+  approach; use it when you must prove the *real* campaign works end-to-end.
+- **Approach B — an isolated one-contact test campaign with no call windows (Rule 2b).** Use it
+  when you only need to rehearse the loop mechanics with zero real prospects linked.
+
+Eligibility mechanics that make both work are in
+[worker2 vapi-webhook-handler.md](../../worker2/features/vapi-webhook-handler.md).
 
 ## Rule 1 — NEVER revive an ended campaign that has linked prospects
 
@@ -39,7 +47,47 @@ dialed real prospects in one cron tick.) Likewise, do **not** blanket-flip `isOk
 real list: it is two mass writes plus a restore burden, and it silently un-blocks any contact
 that was intentionally set `isOkayToCall=0`.
 
-## Rule 2 — Use an isolated one-contact test campaign with NO call windows
+**The safe exception — flip everyone to `isOkayToCall = 0` FIRST, then revive.** Reviving an ended
+campaign is only dangerous because its contacts are dialable. If you first mass-flip
+`isOkayToCall = 0` for **every** contact on the campaign, then extending `dateEnd` re-activates a
+campaign on which **no one is dialable** — and the funnel's Call Now submit re-arms only the single
+tester (`isOkayToCall = 1` + `dtNextContactRequested`). This is exactly Approach A (Rule 2). The
+direction matters: flipping to `0` is the safe direction; the warning above is about flipping to
+`1`.
+
+## Rule 2 (Approach A, PREFERRED for go-live) — reuse an existing campaign, DNC-zero everyone first
+
+This is the approach used to prove campaign 2 (`26.05 - AI BDR - Ryan Nitti`) live on 2026-07-21,
+and it **supersedes** the one-contact test campaign (Rule 2b) whenever the goal is to prove the
+**real** campaign works, not just the loop mechanics. It is "Rohan's existing-campaign pattern":
+
+1. **Record the pre-existing DNC set FIRST (non-negotiable).** Before touching anything, list every
+   contact on the campaign that is *already* `isOkayToCall = 0` for a real reason. For campaign 2
+   those are contact ids **120, 132, 134, 146, 155** (all with DNC evidence in `ContactAttempts`).
+   The restore statement at the end **must exclude these ids forever** — re-enabling a genuine DNC
+   is a compliance incident, not a test-cleanup slip.
+2. **Mass-flip `Contacts.isOkayToCall = 0` for ALL contacts on the campaign** (including the
+   tester). Now no one on the campaign is dialable.
+3. **Extend `Campaigns.dateEnd`** to revive the campaign. Because step 2 made everyone
+   non-dialable, revival dials **no one**.
+4. **The tester arms themselves through the funnel.** The UI "Call Now" submit sets
+   `isOkayToCall = 1` + `dtNextContactRequested` on the tester's contact — re-arming **only** the
+   tester. That single requested contact is the only thing that can be dialed.
+5. **Restore** at the end: set `isOkayToCall = 1` back for the contacts that were dialable before
+   the test, **excluding the pre-existing DNC ids from step 1** (and excluding the tester if the
+   tester should not be re-armed). No snapshot table is needed **provided** the step-1 DNC ids were
+   recorded — that list is the whole safety margin.
+
+**Do NOT create the campaign via a dbchanges2 migration.** That approach was tried and **withdrawn**
+— the migration missed `Campaigns.c_fromPhoneNumberIdentifier`, which `buildVapiPayload` (worker2
+dialer) **hard-requires**, so a campaign built that way cannot place a call. The **sanctioned
+programmatic campaign creator is `_Worker_Ai_Bdr_ZoomInfo::SetupCampaign`**
+(`worker2/Worker/Ai/Bdr/ZoomInfo.php`): it creates the campaign type + assistant + the campaign
+itself (including all `c_*` fields such as `c_fromPhoneNumberIdentifier`) + call windows + booking
+windows + cadences + meet-with contacts + exceptions in one consistent pass. Use it, not raw SQL,
+to stand up a new campaign.
+
+## Rule 2b (Approach B) — isolated one-contact test campaign with NO call windows
 
 The safe posture exploits the eligibility split (see vapi-webhook-handler.md): the normal
 (non-requested) dial path requires a `CampaignCallWindows` row for the current day/time, but the
@@ -100,6 +148,17 @@ Sequence the cleanup into a later, separately-executed window. (See dbchanges2 a
 `YYYY-MM-DD<letter>` ordering contract.)
 
 ## Change history
+- 2026-07-21 — Added **Approach A** (now preferred for go-live), used to prove campaign 2
+  (`26.05 - AI BDR - Ryan Nitti`) live end-to-end: reuse an existing campaign by recording its
+  pre-existing DNC set first (campaign 2 = contact ids 120/132/134/146/155, which the restore must
+  exclude forever), mass-flipping `isOkayToCall = 0` on ALL its contacts, then extending `dateEnd`
+  to revive a campaign on which no one is dialable, and letting the funnel Call Now re-arm only the
+  tester. Reframed Rule 1's "never blanket-flip isOkayToCall" as direction-specific (flipping to `0`
+  first is the safe exception that makes revival safe). Recorded that the **dbchanges2 campaign-
+  creation migration was withdrawn** (it missed `c_fromPhoneNumberIdentifier`, which
+  `buildVapiPayload` hard-requires) and that **`_Worker_Ai_Bdr_ZoomInfo::SetupCampaign` is the
+  sanctioned programmatic campaign creator**. The old one-contact test campaign is retained as
+  Approach B (Rule 2b). (tcox)
 - 2026-07-20 — Initial runbook. Captured the safe AI-BDR call-loop test procedure: never revive an
   ended campaign with linked prospects (every-minute cron dials within 60s); use an isolated
   one-contact test campaign with NO `CampaignCallWindows` (only requested `dtNextContactRequested`

package/knowledge/2.0/apps/worker2/features/vapi-webhook-handler.md

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-07-20
+updated: 2026-07-21
 owners: [snaredla, tcox]
 files:
   - worker2/Worker/Vapi.php
@@ -218,6 +218,28 @@ character — a 37-char value) **passes** the readiness gate and the campaign is
 Vapi `POST /call/phone` **400s** at call time. Validate the assistant identifier's shape before
 assigning an assistant to any campaign.
 
+### Gotcha (HIGH — call quality) — a spoken callback time with a SPELLED-OUT number is silently dropped
+
+`actionScheduleCallback` (`Worker/Vapi.php` ~L387–431) parses the assistant's
+`structured.callbackTime` through `convertDateTime` (~L609–635), which relies on PHP's date
+parser. PHP handles relative phrasings like `"10 minutes"` and `"tomorrow at 3pm"` — but **NOT
+spelled-out numbers**. When the model emits `c_callbackTime = "in ten minutes"` (natural language,
+number as a word), `convertDateTime` returns **null**, `actionScheduleCallback` `error_log`s
+`"Cannot parse callbackTime"` and **aborts** — `dtNextContactRequested` is never set and `callType`
+is never flipped to `CALLBACK`, so the promised callback **never happens** and nothing surfaces the
+failure. Reproduced live 2026-07-21 (attempt 183, contact 248). Two recommended fixes (do both):
+(a) constrain the Vapi structured-output `callbackTime` schema to ISO 8601 / numeric-relative so the
+model can't spell the number out (see `../../ai-bdr/features/vapi-integration.md`); (b) defensively
+normalize spelled-out numbers (`one`..`sixty`) in `convertDateTime` before parsing.
+
+### Gotcha (SECURITY) — the Vapi API bearer token is hardcoded in source
+
+The outbound dialer `Worker/Ai/Bdr/Vapi.php` (**line 6**) declares the Vapi API bearer token as a
+`const` in source — so it is **committed to git**. Treat any committed secret as **compromised and
+rotate it**, and move it into the `[vapi]` section of the worker2 `Config/*.ini` files alongside the
+other Vapi secrets (the pattern the rest of the integration already uses). Config, never source, is
+the home for this credential. (Token value is deliberately not recorded here — location only.)
+
 ## Data model
 
 Writes to `ContactAttempts` (via Toga 2.0 API) — `dtStarted`, `dtEnded`, `transcript`,
@@ -245,6 +267,17 @@ status. See the `ai-bdr` skill / `_Model_True_ContactAttempt` for the full field
 - [VAPI Integration — assistants, tools, structured output](../../ai-bdr/features/vapi-integration.md)
 
 ## Change history
+- 2026-07-21 — Full call loop **proven end-to-end in production** on the real campaign 2
+  (`26.05 - AI BDR - Ryan Nitti`): UI submit → funnel API → dialer → Vapi call → webhook write-back.
+  Live-verified the documented behavior: the `SCHEDULE_CALLBACK` → `c_callOutcome=CALLBACK_SCHEDULED`
+  / `c_actionToTake=SCHEDULE_CALLBACK` mapping, plus `c_prospectSentiment` + `c_qualificationScore`,
+  are all written by the webhook; and the CST timestamp conversion is correct (a scheduled call for
+  an 11:30 slot fired at 11:30:50 — `formatCstDateTime` verified live). Added two gotchas: (1) HIGH —
+  a spoken `callbackTime` with a **spelled-out** number (`"in ten minutes"`) makes `convertDateTime`
+  return null, so `actionScheduleCallback` aborts and the callback silently never happens (repro
+  attempt 183 / contact 248; fix both the Vapi schema and `convertDateTime`); (2) SECURITY — the Vapi
+  API bearer token is hardcoded as a `const` in `Worker/Ai/Bdr/Vapi.php` line 6 (committed to git) —
+  rotate it and move it to the `[vapi]` config section. (tcox)
 - 2026-07-20 — Source-verified corrections/extensions to the dialer eligibility rules: the campaign
   gate is split (`getActiveCampaignsForDialing` L177–193 = isActive+assistant, NO date; date range +
   non-empty `assistantIdentifier` in `validateCampaignReady` L759–789); `Campaigns_Contacts.status

package/knowledge/sessions/2026-07-21-bdr-vapi-golive-tcox.md

@@ -0,0 +1,73 @@
+---
+type: session
+slug: bdr-vapi-golive
+title: BDR VAPI go-live day 2 — loop verified live, four funnel features shipped
+author: tcox
+repos: [bdr, ai-bdr, worker2]
+framework: "2.0"
+client: shared
+status: active
+created: 2026-07-21
+updated: 2026-07-21
+---
+
+# Session: bdr-vapi-golive
+**Date:** 2026-07-21 (continues 2026-07-20-bdr-vapi-golive-tcox)
+**Project/Repo:** bdr + worker2 (2.0)
+**Task:** Verify the AI-BDR call loop end-to-end live on the real campaign and finish the BDR funnel for go-live (enrichment, fast dial, anonymous guard, real share).
+
+---
+
+## What WORKED
+- **Full call loop verified live on campaign 2** using Rohan's existing-campaign approach: flip ALL campaign-2 contacts `isOkayToCall=0` (tester included), extend `Campaigns.dateEnd`, then the tester's UI Call Now submit re-arms ONLY them (`isOkayToCall=1` + `dtNextContactRequested`). Call arrived from the healthcare number +1 (331) 244-5958 (campaign 2's `c_fromPhoneNumberIdentifier` maps there); webhook write-back confirmed (dtEnded set, dtNext cleared).
+- **Scheduled-call path + CST conversion verified**: an 11:30 slot dialed at 11:30:50 (attempt 183).
+- **Outcome mapping verified**: "call me back..." conversation wrote `c_callOutcome=CALLBACK_SCHEDULED`, `c_actionToTake=SCHEDULE_CALLBACK`, sentiment, qualification score.
+- **Enrichment shipped and live-proven** (bdr: src/server/hubspot.ts, toga.ts, leadSink.ts, app/page.tsx): HubSpot jobtitle/company/industry → Contacts.title/doingBusinessAs/industry (the three no-fallback dialer fields), city/state/website → callContext keys. Contact 248 got title=INTERN, doingBusinessAs="Agilant Solutions, Inc." on its first funnel pass and the Vapi opener used them. Committed by tcox this morning (with the phone-prefill fallback).
+- **Fast dial built** (src/server/workerDialer.ts + callbackService.ts, env TOGA_WORKER_URL): Call Now triggers the worker's `Ai/Bdr/Vapi/InitiateOutboundCall` with the primary phone-row uuid — seconds instead of the 0-60s cron wait; best-effort with cron fallback; scheduled calls excluded. NOT yet live-tested.
+- **Anonymous-visit guard built** (CallNow.tsx, Schedule.tsx, content schema/default): no lead ref → submit disabled + notice, matching info's "Missing contact reference" (replaces silent fake success).
+- **Share button made real** (src/lib/shareMailto.ts, CallSummary.tsx): Send opens the visitor's mail client via mailto: with recipient/subject/summary body. BDR suite 131 tests green, tsc + eslint clean.
+- **Parity audit (info → BDR)**: everything ported; enrichment was net-new in BOTH repos; visit route intentionally dropped; TOGA_PUBLIC_TOKEN_URL and NEXT_PUBLIC_ENV are dead even in info.
+- **Vapi API diagnostics work** with the bearer const at worker2/Worker/Ai/Bdr/Vapi.php:6 (GET /call/{id} endedReason, GET /assistant/{id} config).
+- /capture published 4 doc updates (web-funnel-app, safe-call-loop-testing, vapi-webhook-handler, vapi-integration).
+
+## What did NOT work — DO NOT RETRY THESE
+- **Answering the test call silently** → 8 seconds of mutual silence, Vapi `endedReason=customer-ended-call`, empty transcript. The healthcare assistant uses `firstMessageMode=assistant-waits-for-user` (deliberate: first-phoneme timing for voicemail/iPhone screening). **Testers must say "Hello?" first.**
+- **Telling the assistant "call me back in ten minutes"** → structured output stored `c_callbackTime="in ten minutes"` (spelled-out number); worker2 `convertDateTime` (Worker/Vapi.php ~L609) returns null (PHP parses "10 minutes" but not "ten minutes") → `actionScheduleCallback` aborts after error_log "Cannot parse callbackTime" → `dtNextContactRequested` never set, **the promised callback silently never happens**. Open HIGH bug; until fixed, spoken-word callback times are dropped.
+- **The dbchanges2 test-campaign migration** (withdrawn, PR to close unmerged): its INSERT...SELECT missed `c_fromPhoneNumberIdentifier`, which `buildVapiPayload` hard-requires (throws) — the SQL-created campaign would have failed at call time. Raw SQL campaign creation is the wrong vehicle; `_Worker_Ai_Bdr_ZoomInfo::SetupCampaign` is the sanctioned creator.
+- **Vapi API auth with worker2 Config [vapi] api_secret** → `unauthorized`. The working credential is the const at Worker/Ai/Bdr/Vapi.php:6 (itself a security finding — rotate + move to config; value not recorded here).
+- **BDR API client reading /contact-attempts** → 403 (EZ-1). Blocks real call summaries + live call status until the backend grants read ACL.
+
+## Not tried yet (candidates for next session)
+- **Fast-dial live test** — restart the dev server (TOGA_WORKER_URL loads at startup), submit Call Now, phone should ring in seconds. First live use of the worker's direct-action endpoint as a product feature.
+- **Self-heal changed-number live test** — Call Now with a different owned number; dialer should ring the new number.
+- **Real summary + live call status** — blocked on the ContactAttempts ACL grant (read-only: uuid, contactId, dtStarted, dtEnded, c_callSummary, c_callOutcome for BDR API client ead1d6ad-04a5-41f9-9a87-669d66ad49a2). One grant unlocks: real summary card content, real Copy/Share body, live status timer.
+- **Callback-time parse fix** (worker2 + Vapi schema): constrain schema callbackTime format AND normalize spelled-out numbers in convertDateTime.
+- **Booking path live test** (Cal.com — campaign 2's eventIdentifier is real).
+- **Restore SQL** = business go-live switch for the ~70 prospects: `UPDATE Contacts c INNER JOIN Campaigns_Contacts cc ON cc.contactId=c.id SET c.isOkayToCall=1 WHERE cc.campaignId=2 AND c.id NOT IN (120,132,134,146,155);` — **never restore those 5 ids (pre-existing DNC)**.
+
+## Current file state
+| File | Status | Notes |
+|------|--------|-------|
+| BDR enrichment + prefill (hubspot/toga/leadSink/page + tests) | committed by tcox (BDR-Phase-2), merge state to _dev-sandbox unverified | live-proven on contact 248 |
+| BDR fast-dial + anon guard + share (workerDialer, callbackService, CallNow, Schedule, schema, default, shareMailto, CallSummary, .env.example + 3 test files) | UNCOMMITTED in C:\WWW\BDR | 131 tests green; suggested msg: "feat: fast dial, anonymous submit guard, real share via mailto" |
+| BDR/.env.local | TOGA_WORKER_URL added (local only) | dev server restart needed to load |
+| dbchanges2 feature/ai-bdr-test-campaign (e99a367) | pushed; PR must be CLOSED UNMERGED | superseded + buggy (see above) |
+| Prod Client_True data | campaign 2 dateEnd=2026-07-28; all campaign-2 contacts isOkayToCall=0 EXCEPT 248 | restore = go-live switch; exclude ids 120/132/134/146/155 |
+| Team knowledge | 4 docs updated + pushed today | web-funnel-app, safe-call-loop-testing, vapi-webhook-handler, vapi-integration |
+
+## Decisions made
+- **Existing campaign + flip-everyone over a new test campaign** (Rohan): zero campaign-config risk, the UI submit is the only re-arm, and the real Cal.com event stays testable. Rejected: SetupCampaign-created test campaign (viable, kept as Approach B in the runbook), raw SQL (buggy + wrong vehicle).
+- **Share via mailto:, not server-side send**: server-sending client-supplied text through TOGA infra is a spam relay; the visitor's own mail client is honest and zero-backend. Real summary content deferred to the ACL grant.
+- **Fast dial is best-effort**: absorbed failures + cron fallback + in-progress dedupe; env-gated (TOGA_WORKER_URL) so deploys without the var behave exactly as before.
+- **Anonymous submits blocked with notice** (matches info) per tcox's directive that anything diverging from info needs correcting.
+
+## Blockers
+- **Amplify app still doesn't exist** (ClickUp 868kdf4tj, Jeff) — 7 env vars now: the 5 server-side + NEXT_PUBLIC_GA_MEASUREMENT_ID + TOGA_WORKER_URL.
+- **ContactAttempts ACL grant** (backend, DB config only) — gates real summaries + live status.
+- **Business decision on the restore SQL** (resumes cold-calling ~70 prospects).
+
+## Exact next step
+> In `C:\WWW\BDR`: commit the uncommitted batch ("feat: fast dial, anonymous submit guard, real share via mailto"), push to BDR-Phase-2, merge to _dev-sandbox. Then restart the dev server (`npm run dev`) and submit Call Now — the phone should ring within seconds (fast-dial's first live test). If it takes ~a minute instead, check the dev console for a `[workerDialer]` warning: that means the worker's direct-action endpoint rejected the trigger and the cron fallback placed the call.
+
+---
+_Saved by /session-save on 2026-07-21_

package/package.json

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