toga-ai 1.0.394 → 1.0.396

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/toga2-supply/INDEX.md

@@ -3,5 +3,5 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [TOGa Supply (toga2-supply) Architecture](architecture.md) | `toga2-supply` is the **React + Vite frontend** for TOGa Supply — warehouse fulfillment tooling (shipment selection, fulfill & ship against carrier APIs, NetSui | toga2-supply/src/api/toga.ts, toga2-supply/src/pages/ShipmentItems/view/ShipmentItemsPage.tsx, toga2-supply/src/pages/EditShipment/view/EditShipmentPage.tsx, toga2-supply/src/pages/EditShipment/api/UpdateShipmentApi.ts, toga2-supply/src/pages/Shipments/view/components/ShipmentsCardTableForm/ShipmentsCardTableForm.tsx |
-| [Fulfill & Ship](features/fulfill-and-ship.md) | Fulfill & Ship lets a warehouse user select sales-order line items, enter serials, pick a carrier/method, and in one action: create the Item Fulfillment records | toga2-supply/src/components/ui/Tables/BasicTable/BasicTable.tsx, toga2-supply/src/pages/ShipmentItems/view/forms/ShipmentItemsTable.tsx, toga2-supply/src/pages/EditShipment/view/components/forms/EditShipmentForm.tsx, toga2-supply/src/components/ui/BaseInput/UnitSelect.tsx, toga2-supply/src/pages/EditShipment/view/modals/SerialNumbersModal.tsx, toga2-supply/src/pages/ShipmentItems/view/ShipmentItemsPage.tsx, toga2-supply/src/pages/EditShipment/view/EditShipmentPage.tsx, toga2-supply/src/pages/EditShipment/view/components/forms/EditShipmentForm.tsx, toga2-supply/src/pages/EditShipment/view/components/SelectedShipmentItemsTable.tsx, toga2-supply/src/pages/EditShipment/view/helpers/ShipmentDetailsForm/renderEditShipmentFormInput.tsx, toga2-supply/src/pages/EditShipment/viewModel/FIELDS/DUMMYUPDATESHIPMENTFIELDS.json, toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/renderEditShipmentFormInput.tsx, toga2-supply/tailwind.config.cjs, toga2-supply/src/pages/EditShipment/view/modals/ReturnShippingModal.tsx, toga2-supply/src/styles/index.scss, toga2-supply/src/components/ui/BaseInput/BaseInput.tsx, toga2-supply/src/pages/EditShipment/api/UpdateShipmentApi.ts, toga2-supply/src/pages/EditShipment/viewModel/signatureTypes.ts, toga2-supply/src/pages/EditShipment/view/modals/SelectReturnAddressModal.tsx, toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/formatShipmentData.ts, toga2-supply/src/pages/EditShipment/types.ts, toga2-supply/src/pages/Shipments/view/ShipmentsPage.tsx, toga2-supply/src/pages/Shipments/view/components/ShipmentsCardTableForm/ShipmentsCardTableForm.tsx, toga2-supply/src/pages/Shipments/api/ShipmentsApi.ts, toga2-supply/src/pages/Shipments/types.ts, toga2-supply/src/pages/FulfilledShipments/view/FulfilledShipmentsPage.tsx, toga2-supply/src/components/ui/CardTable/CardTable.tsx, toga2-supply/src/components/ui/CardTable/types.ts, toga2-supply/src/assets/pen-line.svg, _underscore/Model/Client/ItemFulfillment.php, _underscore/Trait/Netsuite/ItemFulfillment.php, _underscore/Component/Library/Carriers/Ups/Ups.php |
+| [Fulfill & Ship](features/fulfill-and-ship.md) | Fulfill & Ship lets a warehouse user select sales-order line items, enter serials, pick a carrier/method, and in one action: create the Item Fulfillment records | toga2-supply/src/components/ui/Tables/BasicTable/BasicTable.tsx, toga2-supply/src/pages/ShipmentItems/view/forms/ShipmentItemsTable.tsx, toga2-supply/src/pages/ShipmentItems/api/ShipmentItemsApi.ts, toga2-supply/src/pages/ShipmentItems/types.ts, toga2-supply/src/pages/EditShipment/viewModel/FIELDS/RETURNLABELFIELDS.json, toga2-supply/src/pages/EditShipment/view/components/forms/EditShipmentForm.tsx, toga2-supply/src/components/ui/BaseInput/UnitSelect.tsx, toga2-supply/src/pages/EditShipment/view/modals/SerialNumbersModal.tsx, toga2-supply/src/pages/ShipmentItems/view/ShipmentItemsPage.tsx, toga2-supply/src/pages/EditShipment/view/EditShipmentPage.tsx, toga2-supply/src/pages/EditShipment/view/components/forms/EditShipmentForm.tsx, toga2-supply/src/pages/EditShipment/view/components/SelectedShipmentItemsTable.tsx, toga2-supply/src/pages/EditShipment/view/helpers/ShipmentDetailsForm/renderEditShipmentFormInput.tsx, toga2-supply/src/pages/EditShipment/viewModel/FIELDS/DUMMYUPDATESHIPMENTFIELDS.json, toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/renderEditShipmentFormInput.tsx, toga2-supply/tailwind.config.cjs, toga2-supply/src/pages/EditShipment/view/modals/ReturnShippingModal.tsx, toga2-supply/src/styles/index.scss, toga2-supply/src/components/ui/BaseInput/BaseInput.tsx, toga2-supply/src/pages/EditShipment/api/UpdateShipmentApi.ts, toga2-supply/src/pages/EditShipment/viewModel/signatureTypes.ts, toga2-supply/src/pages/EditShipment/view/modals/SelectReturnAddressModal.tsx, toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/formatShipmentData.ts, toga2-supply/src/pages/EditShipment/types.ts, toga2-supply/src/pages/Shipments/view/ShipmentsPage.tsx, toga2-supply/src/pages/Shipments/view/components/ShipmentsCardTableForm/ShipmentsCardTableForm.tsx, toga2-supply/src/pages/Shipments/api/ShipmentsApi.ts, toga2-supply/src/pages/Shipments/types.ts, toga2-supply/src/pages/FulfilledShipments/view/FulfilledShipmentsPage.tsx, toga2-supply/src/components/ui/CardTable/CardTable.tsx, toga2-supply/src/components/ui/CardTable/types.ts, toga2-supply/src/assets/pen-line.svg, _underscore/Model/Client/ItemFulfillment.php, _underscore/Trait/Netsuite/ItemFulfillment.php, _underscore/Component/Library/Carriers/Ups/Ups.php |
 | [AWS Amplify Build & Deploy (non-prod environments)](workflows/amplify-build-and-deploy.md) | How `toga2-supply` (React + Vite) builds and deploys on **AWS Amplify**. | toga2-supply/amplify.yml, toga2-supply/.gitattributes, toga2-supply/.github/workflows/sync-stage-environments.yml, toga2-supply/.env.qc-security |

package/knowledge/2.0/apps/toga2-supply/features/fulfill-and-ship.md

@@ -11,6 +11,9 @@ owners: [mhammontree]
 files:
   - toga2-supply/src/components/ui/Tables/BasicTable/BasicTable.tsx
   - toga2-supply/src/pages/ShipmentItems/view/forms/ShipmentItemsTable.tsx
+  - toga2-supply/src/pages/ShipmentItems/api/ShipmentItemsApi.ts
+  - toga2-supply/src/pages/ShipmentItems/types.ts
+  - toga2-supply/src/pages/EditShipment/viewModel/FIELDS/RETURNLABELFIELDS.json
   - toga2-supply/src/pages/EditShipment/view/components/forms/EditShipmentForm.tsx
   - toga2-supply/src/components/ui/BaseInput/UnitSelect.tsx
   - toga2-supply/src/pages/EditShipment/view/modals/SerialNumbersModal.tsx
@@ -309,6 +312,33 @@ the call 403s and returns no label.
 
 ## Gotchas / known issues
 
+- **⚠ The item-image tables hardcoded the placeholder and never requested the image.** The Select
+  Items (`ShipmentItemsTable`), Update Info, and Add-Serial (`SelectedShipmentItemsTable`) tables
+  rendered `imageUrl={placeholderImage}` as a **constant**, so a real item image could never appear.
+  The item image is exposed via **two computed SQL fields on the `_underscore` Item model** (referenced,
+  not modified this commit) — request **both** in the V2 field selectors and render
+  **`item._imageUrl || item._thumbnailImageUrl || placeholder`**:
+  - **`_imageUrl`** — resolves `Items.imageId` → `Images.sourceUrl` (the single **primary** image).
+  - **`_thumbnailImageUrl`** — resolves from **`ItemImages`** (per-item thumbnail/low/medium/high
+    resolutions) via `thumbnailImageId`, ordered `isDefault DESC`, **excluding** `sourceUrl LIKE
+    '%Manufacturer%'`.
+
+  Two distinct DB paths back an item image — `Items.imageId → Images` (one primary) and the `ItemImages`
+  table (multi-resolution, `isDefault` flag) — and in both cases the URL lives in `Images.sourceUrl`.
+  The `_imageUrl || _thumbnailImageUrl || placeholder` fallback covers imageId-only, ItemImages-only, or
+  neither. Wiring an image anywhere in the tool: request **both** computed fields (add to the API field
+  selectors + response types), don't hardcode the placeholder. Verified end-to-end against a client DB
+  with rolled-back test data. Files: `ShipmentItems/api/ShipmentItemsApi.ts`, `ShipmentItemsTable.tsx`,
+  `ShipmentItems/types.ts`, `EditShipment/api/UpdateShipmentApi.ts`, `EditShipmentForm.tsx`,
+  `SelectedShipmentItemsTable.tsx`, `EditShipment/types.ts`.
+- **⚠ The shared `ExpandableCellContent` truncates by a FIXED CHARACTER COUNT, not by width — so it
+  can't be responsive.** `ExpandableCellContent` cuts a cell at `columnDataLength` characters
+  (e.g. 55), so a column truncates early regardless of available width and **does not react to
+  window/page resize**. For width-responsive truncation, render the cell as a plain
+  `<div className="truncate max-w-[NNvw]" title={full}>` — CSS overflow-ellipsis with a
+  viewport-relative max-width so the ellipsis point tracks the page size, and the native `title`
+  shows the full text on hover. (Applied to the Description column in `ShipmentItemsTable.tsx` /
+  `SelectedShipmentItemsTable.tsx`.)
 - **⚠ A portaled react-select menu loses the control's inherited font size.** `BaseInput`'s
   react-select menus now portal to `<body>` (`menuPortalTarget={document.body}` +
   `styles.menuPortal` `zIndex 9999`, on both single- and multi-select) so the menu can't be
@@ -588,6 +618,18 @@ not the base `_Model_Client_ItemFulfillment`. Tested with GroWrk; UPS support wa
 for Compass and is not yet in prod.
 
 ## Change history
+- 2026-07-21 — TRUE-79191 (commit `dc900ea4e`, toga2-supply item-image + table polish): fixed the
+  **item image never rendering** — the Select Items / Update Info / Add-Serial tables hardcoded
+  `imageUrl={placeholderImage}` and never requested the image; now request the two `_underscore` Item
+  computed fields **`_imageUrl`** (`Items.imageId → Images.sourceUrl`) and **`_thumbnailImageUrl`**
+  (from `ItemImages` via `thumbnailImageId`, `isDefault DESC`, excluding `%Manufacturer%`) and render
+  `item._imageUrl || item._thumbnailImageUrl || placeholder` — documented the two-path Images/ItemImages
+  data model as a gotcha. Documented the **`ExpandableCellContent` fixed-char-count vs width** gotcha
+  (truncates at `columnDataLength` chars, not responsive; use `truncate max-w-[NNvw]` + native `title`
+  for width-responsive truncation, applied to the Description column). Added Reference 1/2 placeholder
+  hint text to the Edit Return Label modal (`RETURNLABELFIELDS.json`) to match Update Info
+  ("e.g. NetSuite Sales Order #" / "…Purchase Order #") — cosmetic, Ref 1/2 semantics already recorded.
+  (mhammontree)
 - 2026-07-21 — TRUE-79191 (toga2-supply UI fixes + Figma polish): documented three durable, reusable
   gotchas — (1) **`BasicTable` header/value misalignment** (daisyUI base `:where(th,td)` ~16px padding;
   always pass a horizontal `headerCellPadding` matching `cellPadding`, box-shadow-only seam for sticky

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/package.json

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