toga-ai 1.0.476 → 1.0.477

package/knowledge/2.0/apps/_underscore/features/email-send-pipeline.md

@@ -6,13 +6,14 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-07-28
-owners: ["bala"]
+updated: 2026-07-29
+owners: ["bala", tcox]
 files:
   - _underscore/Email.php
   - worker2/Worker/Infrastructure/Email/Send.php
 related:
   - email-template-sending.md
+  - ../../ai-bdr/features/web-funnel-app.md
 ---
 
 ## Summary
@@ -60,8 +61,20 @@ SMTP** using PHPMailer, then flips each row to `SENT` or `FAILED`. So a 2.0 emai
   copy the values. Remediation: treat as compromised, rotate in AWS SES, and move them into
   `Config/[environment].ini` (read via `_Config`). Also tracked on
   [`email-template-sending.md`](email-template-sending.md).
+- **Rotation now has a NON-PHP consumer (2026-07-29).** The BDR web funnel (Node/Next, repo
+  `bdr`) sends its call-summary email with **nodemailer against the same SES SMTP settings**,
+  read from server-only env vars (`TOGA_SMTP_HOST/PORT/USER/PASS`, `TOGA_EMAIL_FROM`) in
+  `.env.local` and the Amplify console. Rotating the constants in `Email.php` **must** therefore
+  be paired with updating BDR's env, or BDR's Send button can only reach its *failed* state (it
+  has no mail-app fallback). Settings BDR mirrors: AWS SES **us-west-2**, port **587**, TLS;
+  `DevTeam@goagilant.com` is a known-good verified sender identity in worker2 config. See
+  [ai-bdr web-funnel-app.md](../../ai-bdr/features/web-funnel-app.md).
 
 ## Change history
+- 2026-07-29 — Noted that the SES SMTP credentials/settings now have a **non-PHP consumer**: the
+  BDR funnel sends via nodemailer against the same SES host (us-west-2, port 587, TLS) using
+  `TOGA_SMTP_*` env vars, so a rotation must be coordinated with BDR's `.env.local` + Amplify
+  vars or BDR's summary email goes dark. (tcox)
 - 2026-07-28 — Created: documented that `_Email::send()` **queues** (writes a `PENDING`
   `Logs_[Client].Email` row + attachment BLOBs) rather than transmitting, and that the worker2
   `Infrastructure/Email/Send` cron (`Core.CronJobs` `* * * * *`) does the actual SES SMTP send

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

@@ -5,8 +5,9 @@
 | [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 |
 | [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 |
+| [Live Call Status — Vapi call API → funnel Success screen lifecycle](features/live-call-status.md) | The BDR funnel's Success screen shows the **real** state of the call it just requested — dialing / ringing / answered-and-talking / ended / not-answered — inste | bdr/src/server/vapiCall.ts, bdr/src/server/callStatus.ts, bdr/src/server/statusToken.ts, bdr/src/server/callbackService.ts, bdr/src/server/workerDialer.ts, bdr/src/lib/callStatus.ts, bdr/src/app/api/call-status/route.ts, bdr/src/app/api/call-now/route.ts, bdr/src/flow/useCallStatusViewModel.ts, bdr/src/flow/callStatusApi.ts, bdr/src/flow/screens/Success.tsx, bdr/src/content/schema.ts, bdr/src/content/default.ts, bdr/src/proxy.ts |
 | [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/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 — 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/server/mailer.ts, bdr/src/server/statusToken.ts, bdr/src/server/vapiCall.ts, bdr/src/server/callStatus.ts, bdr/src/lib/summaryText.ts, bdr/src/lib/emailFormat.ts, bdr/src/lib/callStatus.ts, bdr/src/app/api/share-summary/route.ts, bdr/src/app/api/call-status/route.ts, bdr/src/flow/shareSummaryApi.ts, bdr/src/flow/callStatusApi.ts, bdr/src/flow/useCallStatusViewModel.ts, bdr/src/flow/screens/Success.tsx, 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/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/Worker/Ai/Bdr/ZoomInfo.php, worker2/Config/beta.ini |

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

@@ -0,0 +1,156 @@
+---
+title: Live Call Status — Vapi call API → funnel Success screen lifecycle
+framework: "2.0"
+repo: ai-bdr
+project: AI-BDR
+client: shared
+type: feature
+status: active
+updated: 2026-07-29
+owners: [tcox]
+files:
+  - bdr/src/server/vapiCall.ts
+  - bdr/src/server/callStatus.ts
+  - bdr/src/server/statusToken.ts
+  - bdr/src/server/callbackService.ts
+  - bdr/src/server/workerDialer.ts
+  - bdr/src/lib/callStatus.ts
+  - bdr/src/app/api/call-status/route.ts
+  - bdr/src/app/api/call-now/route.ts
+  - bdr/src/flow/useCallStatusViewModel.ts
+  - bdr/src/flow/callStatusApi.ts
+  - bdr/src/flow/screens/Success.tsx
+  - bdr/src/content/schema.ts
+  - bdr/src/content/default.ts
+  - bdr/src/proxy.ts
+related:
+  - web-funnel-app.md
+  - vapi-integration.md
+  - call-orchestration.md
+  - ../../worker2/features/vapi-webhook-handler.md
+  - ../../api2/features/v2-rest-query-contract.md
+---
+
+## Summary
+
+The BDR funnel's Success screen shows the **real** state of the call it just requested —
+dialing / ringing / answered-and-talking / ended / not-answered — instead of the old ~5s
+scripted "Connecting" theater. The status source is **Vapi's own call API**
+(`GET https://api.vapi.ai/call/{id}`), **not** Toga `ContactAttempts`, because the BDR API
+client is still hard-blocked (`EZ-1`) on `ContactAttempts` — and because Vapi is strictly
+better data even after that ACL grant lands (see "Why Vapi, not ContactAttempts").
+
+## How it works
+
+1. **Call Now** writes the contact (`src/server/callbackService.ts`), then fast-dials the
+   worker action `Ai/Bdr/Vapi/InitiateOutboundCall` (`src/server/workerDialer.ts`). The
+   worker's reply carries the **Vapi call id** — see the response-prefix gotcha below and
+   [worker2 vapi-webhook-handler.md](../../worker2/features/vapi-webhook-handler.md) for the
+   full return shape.
+2. `/api/call-now` mints a **purpose-scoped, signed status token** (`src/server/statusToken.ts`)
+   whose claims carry the Vapi call id. The call id itself **never crosses to the client and is
+   never accepted as a client parameter** (see Security).
+3. The Success screen polls `/api/call-status` (`src/flow/callStatusApi.ts` →
+   `src/flow/useCallStatusViewModel.ts`), passing the token in the **`x-status-token` header**.
+4. The route reads Vapi server-side (`src/server/vapiCall.ts`), normalizes to the funnel's own
+   state machine (`src/lib/callStatus.ts`), and returns it with `Cache-Control: no-store, private`.
+
+### State mapping (`src/lib/callStatus.ts`)
+
+| Vapi `status` | Condition | Funnel state | Talk timer |
+|---|---|---|---|
+| `queued`, `ringing` | — (or `startedAt` absent) | **dialing** | none |
+| `in-progress`, `forwarding` | `startedAt` present | **active** | counts from the **answer** time, corrected by a server-clock offset |
+| `ended` | `startedAt` present | **ended** | frozen at the true talk duration (`endedAt - startedAt`) |
+| `ended` | no `startedAt`, **or** `endedReason` matches voicemail / no-answer / did-not-answer / busy | **not answered** | none; the recap card is **suppressed** |
+
+The "not answered" state exists specifically so the screen never shows an authored sample
+conversation to someone whose call nobody took.
+
+- **Post-hangup grace polling:** after `ended`, the client keeps polling every **2s for a
+  bounded 30s** — purely because Vapi writes `summary` asynchronously (below).
+- **Simulation is the graceful fallback**, not the default: it runs whenever status is
+  unavailable (no handle, anonymous visit, missing `TOGA_VAPI_TOKEN`, upstream failure).
+- **Scheduled-mode submits never poll** — there is nothing live to watch.
+
+## The Vapi call read (`GET https://api.vapi.ai/call/{id}`)
+
+Authenticated with the **same Vapi bearer credential worker2 dials with** (BDR reads it from
+the server-only env var `TOGA_VAPI_TOKEN`; see web-funnel-app.md for where the value lives).
+Verified live response fields: `id`, `status`, `type`, `createdAt`, `startedAt`, `endedAt`,
+`endedReason`, `summary`, `transcript`, `recordingUrl`, `customer`, `analysis`, `messages`,
+`cost`, `twilioCallSid`.
+
+**Status enum:** `queued` → `ringing` → `in-progress` (`forwarding`) → `ended`.
+
+**Timestamp semantics — the load-bearing insight:**
+
+- `createdAt` = the call was **placed**.
+- `startedAt` = the call was **ANSWERED**.
+- `endedAt` = hangup.
+- `createdAt → startedAt` is therefore **ring time** (observed 10s on a real call). Any talk
+  timer must count from `startedAt`, never `createdAt`.
+
+**Timestamps are ISO-8601 UTC with a `Z`** — parse them directly. Do **NOT** apply the
+Central-time conversion that `ContactAttempts` datetimes need (api2 serializes with a Central
+offset because it runs `America/Chicago`; Vapi does not).
+
+## Why Vapi, not ContactAttempts
+
+- **ContactAttempts is hard-blocked for the BDR API client (still open as of 2026-07-29).**
+  Re-verified live against `api.togahub.com`: `EZ-1` on **every** variant — nested
+  `/contacts/{uuid}/contact-attempts`, flat `/contact-attempts`, with and without an explicit
+  `fields=` list. It is a **record-level** block (`data.contactAttempts: null`), not
+  field-level. Separately `/contacts/{uuid}?fields=id` returns `EZ-2` denying `Contacts.id`.
+  The read-only ACL grant asked for on 2026-07-21 is **still pending**. This supersedes the
+  older "not tried yet" note.
+- **Even after the grant lands, Vapi wins for live UI.** `ContactAttempts.dtStarted` is the
+  **dial** time — it cannot distinguish "ringing" from "talking," so it can never drive an
+  honest talk timer or an answered/not-answered distinction. Vapi's `startedAt` can.
+- ContactAttempts remains the right source for **durable, post-call** reporting (it is what the
+  end-of-call webhook writes back to).
+
+## Security
+
+The full security model for these public unauthenticated endpoints is documented in
+[web-funnel-app.md](web-funnel-app.md#public-unauthenticated-endpoint-security-model). The two
+rules that are specific to this feature:
+
+- **The Vapi call id travels only inside signed token claims.** It is never accepted as a
+  client parameter — otherwise anyone could read **any** call in the org's Vapi account,
+  including transcripts and recordings.
+- **Tokens are purpose-scoped** (`status` vs `share`) so a status-poll capability is not
+  silently also a send-an-email capability.
+
+## Gotchas / known issues
+
+- **`summary` is written ASYNCHRONOUSLY, a few seconds AFTER hangup.** It is commonly `null`
+  on the first read that shows `status: "ended"`. `endedReason`, by contrast, is set
+  immediately. This is the entire reason for the bounded 30s post-hangup grace polling, and
+  why the share-summary send **re-reads Vapi at send time** rather than trusting what the
+  screen had.
+- **Never `JSON.parse` a worker dispatcher reply directly.** The worker wraps **every** reply
+  as `[<requestId>] Successfully Executed (<n> seconds): <json>`, so `response.json()` always
+  throws. BDR previously logged "immediate dial not placed" on every **successful** dial and
+  silently discarded the response body (which is where the Vapi call id lives). Strip the
+  prefix with a regex before parsing — see
+  [creating-worker-actions.md](../../worker2/features/creating-worker-actions.md).
+- **`vapiCallId` may be the literal string `'unknown'`.** Treat it as "no handle" and fall
+  back to the simulation rather than polling for a call that cannot be read.
+- **Do not convert Vapi timestamps to Central.** They are already UTC `Z`. The Central
+  conversion belongs only on ContactAttempts/api2 datetimes.
+- **Without `TOGA_VAPI_TOKEN` the whole feature silently degrades to the simulation.** That is
+  deliberate (the funnel must never fail on a missing credential) — but it means "the timer
+  looks fake in this environment" is an **env** symptom, not a code bug.
+
+## Change history
+- 2026-07-29 — Created. BUILT the live call-status pipeline: `src/server/vapiCall.ts` reads
+  `GET https://api.vapi.ai/call/{id}` with the worker's Vapi bearer credential and drives a real
+  dialing / active / ended / not-answered lifecycle on the Success screen (replacing the ~5s
+  scripted simulation, which is now only the fallback). DECIDED Vapi is the live-status source
+  instead of Toga `ContactAttempts` — re-verified 2026-07-29 that ContactAttempts is still
+  `EZ-1` record-level blocked on every route variant (grant still pending), **and** that
+  `dtStarted` is dial time so Vapi's `startedAt` (= ANSWER time) is strictly better for live UI
+  regardless. Recorded the timestamp semantics (`createdAt` placed → `startedAt` answered →
+  `endedAt` hangup; the gap is ring time, 10s observed), the UTC-`Z` no-conversion rule, and the
+  asynchronous `summary` write that forces the bounded 30s post-hangup grace poll. (tcox)

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

@@ -6,7 +6,7 @@ project: AI-BDR
 client: shared
 type: feature
 status: active
-updated: 2026-07-23
+updated: 2026-07-29
 owners: [tcox]
 files:
   - bdr/PLAN.md
@@ -15,7 +15,19 @@ files:
   - bdr/src/server/leadSink.ts
   - bdr/src/server/callbackService.ts
   - bdr/src/server/workerDialer.ts
-  - bdr/src/lib/shareMailto.ts
+  - bdr/src/server/mailer.ts
+  - bdr/src/server/statusToken.ts
+  - bdr/src/server/vapiCall.ts
+  - bdr/src/server/callStatus.ts
+  - bdr/src/lib/summaryText.ts
+  - bdr/src/lib/emailFormat.ts
+  - bdr/src/lib/callStatus.ts
+  - bdr/src/app/api/share-summary/route.ts
+  - bdr/src/app/api/call-status/route.ts
+  - bdr/src/flow/shareSummaryApi.ts
+  - bdr/src/flow/callStatusApi.ts
+  - bdr/src/flow/useCallStatusViewModel.ts
+  - bdr/src/flow/screens/Success.tsx
   - bdr/src/flow/screens/CallNow.tsx
   - bdr/src/flow/screens/Schedule.tsx
   - bdr/src/flow/screens/CallSummary.tsx
@@ -23,7 +35,6 @@ files:
   - 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
@@ -53,10 +64,14 @@ files:
 related:
   - web-funnel-content-model.md
   - bdr-web-funnel-plan.md
+  - live-call-status.md
   - ../architecture.md
   - ../workflows/safe-call-loop-testing.md
   - ../../worker2/features/vapi-webhook-handler.md
+  - ../../worker2/features/creating-worker-actions.md
   - ../../api2/features/nested-relationship-writes.md
+  - ../../api2/features/v2-rest-query-contract.md
+  - ../../_underscore/features/email-send-pipeline.md
 ---
 
 ## What this is
@@ -109,7 +124,12 @@ 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: **131 tests, all green** (2026-07-21 added `togaEnrichment.test.ts`,
+- **Runtime dep added 2026-07-29: `nodemailer`** (+ `@types/nodemailer` dev) — the first
+  outbound-transport dependency in the repo, for the server-side summary send.
+- **Vitest** test suite: **306 tests across 20 files, all green** (2026-07-29 — the live
+  call-status, status/share token, mailer, summary-renderer and anonymous-submit suites;
+  `shareMailto.test.ts` was **deleted** with the mailto: path). Historical detail:
+  **131 tests** (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
@@ -306,38 +326,112 @@ so the call fires in **seconds** instead of waiting up to 60s for the dialer cro
 - **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.
+- **Motivation:** the Success screen's "Connecting" animation was scripted theater (~5s) while
+  the cron could take 60s; fast dial made the theater roughly honest. As of 2026-07-29 the
+  screen shows the **real** lifecycle instead (see [live-call-status.md](live-call-status.md)),
+  and fast dial is what makes the dial happen soon enough to be worth watching.
+- **FIXED 2026-07-29 — the reply was never parseable.** The worker dispatcher wraps **every**
+  reply as `[<requestId>] Successfully Executed (<n> seconds): <json>`, so BDR's
+  `response.json()` **always** threw: it logged "immediate dial not placed" on every
+  **successful** dial and silently discarded the response body. `workerDialer.ts` now strips the
+  prefix with a regex before parsing and returns a typed `DialResult`. That body matters — it
+  carries `vapiCallId`, the handle the live-status feature needs (full return shape in
+  [worker2 vapi-webhook-handler.md](../../worker2/features/vapi-webhook-handler.md); the general
+  rule for any HTTP consumer of the worker endpoint is in
+  [creating-worker-actions.md](../../worker2/features/creating-worker-actions.md)).
 - **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.
+## Anonymous phone entry (the contact-reference gate was REMOVED 2026-07-29)
+
+**Anyone can now enter a phone number and submit**, with or without a lead reference. The
+2026-07-16 "Missing contact reference" behavior — the `hasLead` submit-block plus the
+`phone.missingContactNotice` copy key — was **removed entirely** (`src/flow/screens/CallNow.tsx`,
+`src/flow/screens/Schedule.tsx`, `src/content/schema.ts`, `src/content/default.ts`). The notice
+key is gone from the schema, so do not re-reference it.
+
+- **The backend was deliberately left unchanged.** An anonymous submit is still a **client-side
+  no-op** — no POST is made without a `togaUuid` — so a **real call still only ever fires for a
+  campaign-linked contact**. The gate's protective effect is intact; only the dead-end UX was
+  removed.
+- **Analytics submit events now carry `simulated: true/false`** so funnel metrics can separate
+  real submits from anonymous no-ops. Read that flag before trusting a submit count.
+- Production links still come from HubSpot personalization tokens —
+  `?campaign=slug&hsContactId={{contact.hs_object_id}}&hsCampaignId=uuid` — or, when the campaign
+  bundle pins `togaCampaignUuid`, just the slug + contact token.
+- **Diagnostic consequence:** the guard notice is no longer the terminal symptom of "no lead
+  reference" (see the deployed-site triage gotcha, which now has one fewer signal). Probe
+  `GET /api/contact?hsContactId=<id>` directly instead.
+
+## Live call status on the Success screen
+
+The Success screen shows the **real** call lifecycle (dialing → answered/talking → ended, or a
+distinct "not answered" state) driven by **Vapi's own call API**, replacing the ~5s scripted
+simulation — which survives only as the graceful fallback. Full detail, including the
+`createdAt`/`startedAt`/`endedAt` semantics and why Vapi beats `ContactAttempts`, is in
+**[live-call-status.md](live-call-status.md)**.
+
+## Share summary = a real server-side email (the mailto: fallback was REMOVED)
+
+The CallSummary "Send" button now **actually sends the email** from the server
+(`src/app/api/share-summary/route.ts` NEW, `src/server/mailer.ts` NEW — nodemailer,
+`src/lib/summaryText.ts` NEW, `src/lib/emailFormat.ts` NEW, `src/flow/shareSummaryApi.ts` NEW,
+`src/flow/screens/CallSummary.tsx`). **`src/lib/shareMailto.ts` and its test were DELETED** —
+the 2026-07-21 mailto: approach is gone; do not reintroduce it.
+
+- **The body is built 100% server-side and rendered through the SAME shared renderer the Copy
+  button uses**, so Copy and the emailed text are byte-identical *by construction* rather than by
+  two implementations agreeing. Change the renderer, both change together.
+- **The client may only supply**: a recipient, a campaign id, a bounded variant index, and a
+  signed token. **Never body or subject text** — that is what keeps this from being an open
+  spam relay (see the security model below).
+- **The send re-reads Vapi at send time**, so it can pick up a `summary` that landed *after* the
+  on-screen 30s grace window closed — bounded by the share token's **30-minute TTL**.
+- **CONSEQUENCE of dropping the mail-app fallback:** the button can only ever reach
+  *sending → sent* or *failed-with-retry*. **Without SMTP configured it can only reach `failed`**,
+  so credential provisioning is now **required** for the feature to do anything at all (it is no
+  longer a nice-to-have that degrades to opening a mail client).
+
+## Public unauthenticated endpoint security model
+
+`/api/call-status` and `/api/share-summary` are **public and unauthenticated**. The initial
+design (an unauthenticated arbitrary-recipient mailer sending from the client's DKIM-signed
+identity) was **BLOCKed by a `cso` audit**; these are the fixes that were applied, and they are
+load-bearing — do not relax one without re-reviewing:
+
+- **Purpose-scoped HMAC-SHA256 tokens** (`status` vs `share`), so one capability is never
+  silently also the other. **Future-dated token issuance is rejected.**
+- **The token travels in an `x-status-token` HEADER, not the URL query string.** A 30-minute
+  bearer capability over a named individual's call summary must not land in access logs.
+- **A valid share token is REQUIRED for every send** — the mailer is provably never invoked
+  without one.
+- **Content-Type and `sec-fetch-site` checks** to blunt cross-origin IP-spreading.
+- **Strict recipient validation:** rejects display-name / angle-bracket form, commas, and all
+  non-ASCII (header injection and bidi tricks), and the address is passed to nodemailer in
+  **object form**, never as a raw string.
+- **SMTP `requireTLS` + TLS 1.2 minimum + connection timeouts**; upstream reads carry
+  `AbortSignal` timeouts.
+- **`Cache-Control: no-store, private`** on every API envelope.
+- **EXACT ACL error-code matching that fails CLOSED on an unknown 403** — a substring match would
+  classify `EZ-25` as `EZ-2` and read data out of a 403 (see
+  [api2 v2-api-error-codes.md](../../api2/features/v2-api-error-codes.md)).
+- **The Vapi call id is never a client parameter** — it travels only inside signed token claims.
+  Otherwise anyone could read **any** call in the org's Vapi account, transcripts and recordings
+  included.
+- **Residual ACCEPTED risk:** a token holder can email the summary to any address they type
+  (that *is* the share-with-a-colleague use case). The stricter alternative — binding the
+  recipient to the contact's on-file address — was considered and not taken.
+
+## ContactAttempts is still 403-blocked (re-verified 2026-07-29)
+
+The read-only ACL grant asked for on 2026-07-21 is **still pending**, and the block is
+**record-level `EZ-1`** on every route variant tried — see
+[live-call-status.md](live-call-status.md) for the full verification and for why the funnel no
+longer needs it for live status. The still-open 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` — note `c_*` fields are granted via
+**`AclCustomFieldPermissions`**, not `AclFieldPermissions`.
 
 ## Parity audit — `info` (original) vs `bdr` (new) (§ closed 2026-07-21)
 
@@ -374,6 +468,24 @@ PRODUCTION credential set (`TOGA_API_BASE_URL = https://api.togahub.com/v2`).
 - **Restart the dev server after creating `.env.local`** — Next reads env files only at
   server startup. `.env.*` is gitignored in BDR.
 
+### Email + Vapi credentials (2026-07-29) — WHERE they live, never the values
+
+The two new server-only credential groups BDR needs, and where the platform keeps them:
+
+| BDR env var(s) | Source of truth in the platform |
+|---|---|
+| `TOGA_SMTP_HOST` / `PORT` / `USER` / `PASS`, `TOGA_EMAIL_FROM` | The 2.0 framework's SMTP settings are **hardcoded as class constants in `_underscore/Email.php`** (AWS SES, `us-west-2`, port 587, TLS; PHPMailer under the hood) — see [email-send-pipeline.md](../../_underscore/features/email-send-pipeline.md) |
+| `TOGA_VAPI_TOKEN` | The Vapi bearer is **hardcoded as a class constant in `worker2/Worker/Ai/Bdr/Vapi.php`** — see [vapi-webhook-handler.md](../../worker2/features/vapi-webhook-handler.md) |
+
+- All are declared in `.env.example`, with real values only in the gitignored `.env.local` and
+  in the **Amplify console** for the deployed site (same build-time recipe as the other vars —
+  the `env | grep -E '^(HUBSPOT_|TOGA_|NEXT_PUBLIC_|RATE_LIMIT_)'` line already covers `TOGA_*`).
+- **`DevTeam@goagilant.com` is a known-good sender identity** in worker2 config — use it rather
+  than inventing a From address that SES has not verified.
+- **SECURITY FLAG:** both platform credentials are **committed literals in repo source**, which
+  the team's own security rules treat as **compromised → rotate**. See the rotation-coupling
+  gotcha below.
+
 ## Deploy status (AWS Amplify — LIVE + verified 2026-07-23)
 
 **The BDR site is LIVE and verified (2026-07-23):** branch `_dev-sandbox` (Amplify default
@@ -402,10 +514,11 @@ up — confirm the real owner before assuming.)
   miss), and secrets stay in the Amplify console, never in git. The same broken `cp` pattern would
   have bitten the `_production` launch too.
 - **Symptom chain when the env vars are missing (what "no vars" looks like end-to-end):**
-  page-prime's HubSpot fetch throws → lead ref comes back empty → the **anonymous-visit guard
-  notice shows even with a valid `?hsContactId`** → `GET /api/contact` returns
-  `500 {"error":"Failed to fetch contact"}`. If you see the guard notice on a deployed URL that
-  has a real entry link, suspect missing server-side env before anything else.
+  page-prime's HubSpot fetch throws → lead ref comes back empty → the visit behaves as
+  **anonymous even with a valid `?hsContactId`** (before 2026-07-29 this surfaced as the
+  guard notice; now it is silent) → `GET /api/contact` returns
+  `500 {"error":"Failed to fetch contact"}`. If a real entry link behaves anonymously on a
+  deployed URL, suspect missing server-side env before anything else.
 - **OPERATIONAL — env vars saved AFTER a build starts do NOT reach that build.** They are baked in
   at build time, so after adding/changing console vars you must **"Redeploy this version"** for
   them to take effect — a fresh save alone does nothing for an in-flight or already-built deploy.
@@ -472,6 +585,19 @@ up — confirm the real owner before assuming.)
 
 ## Gotchas
 
+- **HIGH (security + availability) — rotating the platform credentials takes BDR dark unless
+  BDR's env is updated in the SAME change.** BDR consumes two credentials that are **committed
+  literals** elsewhere in the platform: the SES SMTP settings in `_underscore/Email.php` and the
+  Vapi bearer in `worker2/Worker/Ai/Bdr/Vapi.php`. Both should be rotated on the team's own
+  security rules — but BDR reads copies of them as `TOGA_SMTP_*` / `TOGA_VAPI_TOKEN`, in
+  `.env.local` **and** the Amplify console. Rotate without updating those and BDR's email send
+  starts failing and live call status silently degrades to the simulation. Coordinate the two.
+- **Never `JSON.parse` a worker dispatcher reply.** Every reply is prefixed
+  `[<requestId>] Successfully Executed (<n> seconds): ` — strip it first. See the fast-dial
+  section; this cost a full session of "the dial isn't firing" when it always was.
+- **The Send button has no non-SMTP path any more.** With the mailto: fallback deleted, an
+  unprovisioned environment can only produce the *failed* state — that is an env symptom, not a
+  bug in the share flow.
 - **CRITICAL — GA4 leaks the entry identifiers unless you scrub `page_location`.** `gtag`
   stamps `page_location = window.location.href` (which **includes** `?hsContactId=` &
   `?hsCampaignId=`) on the auto `page_view` **and on every subsequent event** — so the
@@ -577,9 +703,10 @@ up — confirm the real owner before assuming.)
   lookup carries the email in the query. Do not reintroduce value logging.
 - **No Tailwind** — see Stack. The mockup CSS is the styling system; adding Tailwind
   risks pixel parity.
-- **Deployed-site triage — "guard notice shows despite a valid entry link."** The
-  anonymous-visit guard notice is always the **terminal** symptom of "no lead reference,"
-  regardless of the underlying cause, so probe the layer directly:
+- **Deployed-site triage — "a known lead is being treated as anonymous."** Since the guard
+  notice was removed (2026-07-29) there is **no longer a visible terminal symptom** for "no lead
+  reference" — the funnel just quietly behaves anonymously (submit becomes a no-op; analytics
+  marks it `simulated: true`). So probe the layer directly:
   `GET /api/contact?hsContactId=<id>` on the deployed URL. **`500 "Failed to fetch contact"`**
   ⇒ HubSpot env missing server-side (see the Deploy status env-var bug). **`400`** ⇒ the id
   value/format. **Contact JSON returned** ⇒ env is fine — suspect the rate-limit proxy's
@@ -589,6 +716,31 @@ up — confirm the real owner before assuming.)
   harness; pull it with `npx toga-ai`.
 
 ## Change history
+- 2026-07-29 — Four behavior changes plus a security model. (1) **Anonymous phone entry** — the
+  `hasLead` submit-block and the `phone.missingContactNotice` copy key were **removed entirely**,
+  reversing the 2026-07-16 "Missing contact reference" behavior; the backend is deliberately
+  unchanged, so an anonymous submit stays a client-side no-op and real calls still fire only for
+  campaign-linked contacts. Analytics submit events now carry `simulated: true/false`.
+  (2) **Live call status** replaces the ~5s simulation on Success, sourced from Vapi's call API —
+  new doc [live-call-status.md](live-call-status.md). (3) **FIXED fast dial's response parsing** —
+  the worker prefixes every reply `[<requestId>] Successfully Executed (<n> seconds): `, so
+  `response.json()` always threw and BDR logged "immediate dial not placed" on every **successful**
+  dial while discarding the body that carries `vapiCallId`; now stripped with a regex and returned
+  as a typed `DialResult`. (4) **Real server-side summary email** (`nodemailer`) replaces the
+  `mailto:` link — `src/lib/shareMailto.ts` **DELETED**; the body is rendered server-side through
+  the same renderer Copy uses (byte-identical by construction), the client may supply only
+  recipient/campaign/variant/token, and the send re-reads Vapi so a late `summary` still lands
+  (30-min token TTL). Consequence: **no mail-app fallback**, so SMTP provisioning is now required.
+  Recorded the **public-endpoint security model** applied after a `cso` audit returned BLOCK
+  (purpose-scoped HMAC tokens, token in the `x-status-token` header not the URL, share token
+  required for every send, Content-Type + `sec-fetch-site` checks, strict ASCII recipient
+  validation in object form, `requireTLS`/TLS1.2/timeouts, `no-store, private`, exact ACL-code
+  matching that fails closed, call id only inside token claims; accepted residual: a token holder
+  can email any address they type). Recorded **where the SMTP and Vapi credentials live**
+  (`_underscore/Email.php` and `worker2/Worker/Ai/Bdr/Vapi.php` class constants; BDR reads copies
+  as `TOGA_SMTP_*` / `TOGA_VAPI_TOKEN`) with the rotation-coupling gotcha. Re-verified
+  `ContactAttempts` is still `EZ-1` blocked. Suite **306/306 across 20 files**; tsc + lint clean.
+  All work uncommitted on branch `TRUE-80435` at capture. (tcox)
 - 2026-07-23 — **BDR site is LIVE + verified** (day 3 of go-live). RESOLVED the deployed 500
   "Failed to fetch contact" (missing server env at runtime): confirmed the full root cause with git
   evidence — the inherited `amplify.yml` (from the old `info` repo, which COMMITS its real `.env`

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

@@ -6,7 +6,7 @@ project: AI-BDR
 client: shared
 type: workflow
 status: active
-updated: 2026-07-21
+updated: 2026-07-29
 owners: [tcox]
 files:
   - dbchanges2/Client_True/2026-07-20a - AiBdrTcoxTestCampaign.sql
@@ -16,6 +16,7 @@ files:
 related:
   - new-campaign-onboarding.md
   - ../architecture.md
+  - ../features/live-call-status.md
   - ../../worker2/features/vapi-webhook-handler.md
 ---
 
@@ -109,6 +110,38 @@ Reference implementation: `dbchanges2/Client_True/2026-07-20a - AiBdrTcoxTestCam
 (idempotent `NOT EXISTS` guards keyed to the real UNIQUE constraints; passed `sql-reviewer`). This
 proves the loop with **zero prospect exposure** instead of mass-writing flags on real contacts.
 
+## "No calls are happening" — check the campaign's `dateEnd` FIRST (recurring fuse)
+
+The recurring "the AI-BDR loop stopped working" symptom traces, every time so far, to campaign
+**2 — `26.05 - AI BDR - Ryan Nitti`** (uuid `15d0c02f-501e-e081-2ead-61b78c854223`) having a
+**lapsed `dateEnd`**. It was set to **2026-07-28** during the 2026-07-21 go-live test and simply
+expired, which **silently stops all dialing** (`validateCampaignReady` rejects the campaign every
+run with "Campaign has ended" — no funnel-side symptom at all; the submit still returns 200).
+
+**Treat `dateEnd` as a fuse to extend, not a bug to re-debug.** Re-activation triage order:
+
+1. **Wedge-check the tester FIRST.** Look for an open `ContactAttempts` row on the tester
+   (`dtEnded IS NULL`) — an open attempt excludes the contact from dialing **forever**. Unwedge:
+   `UPDATE ContactAttempts SET dtEnded = NOW() WHERE contactId = ? AND dtEnded IS NULL`.
+2. Then follow **Approach A order exactly**: flip every campaign-2 contact **except the tester
+   (contact 248)** to `isOkayToCall = 0` **first**, *then* extend `dateEnd`, *then* have the
+   tester re-arm through the funnel's Call Now.
+3. **The 5 pre-existing genuine DNC contact ids — 120, 132, 134, 146, 155 — must never be
+   restored.** (Same non-negotiable as Rule 2 step 1.)
+
+## Environment constraint — you cannot reach the client DB from a dev laptop
+
+The production client database is **not reachable without VPN**: TCP 3306 to the
+`*.client.database.togahub.com` host times out from a stock dev machine, and that machine may
+also have **no `mysql` client, no PHP, and no Python**. Consequences for anyone (or any agent)
+running this runbook:
+
+- **Do not assume direct DB access.** Either the developer runs the SQL in their own DB session,
+  or the change goes through **api2**.
+- **Hand over ready-to-run SQL** — pre-flight `SELECT`s first, then the writes, with explicit
+  **stop conditions** ("if this returns more than 1 row, stop"). A blind `UPDATE` handed to
+  someone else to paste is how a DNC contact gets re-enabled.
+
 ## Rule 3 — NEVER dry-run against production
 
 `dryRun` in the dialer is **not** write-free: `createContactAttempt` runs **before** the dryRun
@@ -148,6 +181,15 @@ Sequence the cleanup into a later, separately-executed window. (See dbchanges2 a
 `YYYY-MM-DD<letter>` ordering contract.)
 
 ## Change history
+- 2026-07-29 — Added the **"no calls are happening" triage section**: campaign 2's `dateEnd`
+  (set to 2026-07-28 during the go-live test) is a **recurring fuse** whose lapse silently stops
+  all dialing with no funnel-side symptom — extend it rather than re-debugging, after
+  wedge-checking the tester for an open `ContactAttempts` row (`dtEnded IS NULL`) and following
+  the Approach A order (zero everyone but contact 248 → extend `dateEnd` → re-arm via Call Now;
+  never restore DNC ids 120/132/134/146/155). Also recorded the **environment constraint**: the
+  production client DB is unreachable from a dev laptop without VPN (3306 times out) and a stock
+  machine may have no mysql/PHP/Python, so DB changes must be run by the developer or go through
+  api2 — hand over ready-to-run SQL with pre-flight reads and stop conditions. (tcox)
 - 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

package/knowledge/2.0/apps/api2/INDEX.md

@@ -18,6 +18,7 @@
 | [TableView field/column metadata (TableViewFields, hidden projected columns)](features/tableview-field-metadata.md) | The columns of a 2.0 table view are defined by DB metadata, not code. | _underscore/Model/Client/TableView.php, api2/Component/Api/V2/V2.php, dbchanges2/Client/2026-07-20 - ItemsUuidForPurchaseOrderItemsTableView.sql |
 | [Tickets API (/v2/tickets)](features/tickets-api.md) | The generic ticket endpoint of the 2.0 REST API. | Component/Api/V2/V2.php |
 | [V2 API error/message codes (EV/EZ troubleshooting map)](features/v2-api-error-codes.md) | The V2 JSON engine (`Component/Api/V2/V2.php`) returns short **message codes** in the response `error` field, grouped by family: `EN-*` authentication, `EZ-*` a | api2/Component/Api/V2/V2.php, _underscore/Model/Client/TrackingNumber.php |
+| [V2 REST query contract (params, where grammar, encoding, ACL behavior)](features/v2-rest-query-contract.md) | What an **HTTP client** has to get right to query the Toga v2 REST API: which query params are recognized, the exact `where` grammar, how the query string is (n | api2/Component/Api/V2/V2.php |
 | [V2 reverse hasMany collections must be named in the fetch fields whitelist](features/v2-reverse-hasmany-fields-whitelist.md) | In the V2 JSON engine, a **reverse hasMany** relationship — the collection of child records that foreign-key back to a parent (e.g. | api2/Component/Api/V2/V2.php |
 | [AWS CodePipeline Deployment via CodeConnections (GitHub → Elastic Beanstalk)](workflows/codepipeline-codeconnections-deploy.md) | 2.0 apps (`api2`, `_underscore`) are deployed through **AWS CodePipeline**. | api2/.platform/hooks/postdeploy/060_register_instance_to_shared_application_load_balancer.sh, api2/ebs/register_instance_to_shared_application_load_balancer.php |
 | [New Environment Configuration & Provisioning (api2)](workflows/environment-configuration-and-provisioning.md) | What it takes for a 2.0 API environment (e.g. | api2/Config/<environment>.ini, api2/Controller/Index.php, dbchanges2/Core/2026-06-16a - DatabaseHosts for new QA QC stage demo environments.sql, dbchanges2/Logs/, _underscore/Route.php |

package/knowledge/2.0/apps/api2/features/v2-api-error-codes.md

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-07-24
+updated: 2026-07-29
 owners: [mhammontree, tcox, jcardinal]
 files:
   - api2/Component/Api/V2/V2.php
@@ -14,6 +14,7 @@ files:
 related:
   - ../../_underscore/features/acl-permission-chain.md
   - scripted-api-post-body-args.md
+  - v2-rest-query-contract.md
   - ../architecture.md
 ---
 
@@ -39,6 +40,7 @@ migration instead of re-deriving it. All field/script ACL rows live in the **CLI
 | **EZ-1** | Unauthorized record/script dispatch | Missing **`AclRecordScripts`** (scripted APIs) or the **`AclRecordPermissions`** four-table chain (records) for the caller's role | Grant `AclRecordScripts` (scripts) or complete the record-CRUD chain |
 | **EZ-2** | Field-level authorization denied (READ) | The field is registered (`Core.RecordFields` present → no `EV-8`) but the caller's role has no **`AclFieldPermissions`** grant to **read** it. The read-side counterpart of `EV-9` (write). **This applies to the `id` field too:** fetching a record by its numeric `id` (`GET /v2/<record>?fields=id,...`) 403s `EZ-2` if `id` has no read grant — the `id` field is ACL-gated like any other, not implicitly readable | Add the `AclFieldPermissions` row for the role (`isWritable=0` if the field is server-written). For a **custom** `c_` field use `AclCustomFieldPermissions` instead — see the ACL doc's standard-vs-custom table |
 | **EV-5** | Duplicate `transactionId` | The globally-unique `transactionId` was reused | Send a fresh unique `transactionId` per request |
+| **EV-13** | Validation — page size too large | `recordsPerPage` exceeds the **10000** max | Lower `recordsPerPage` and paginate with `page` |
 | **EV-12** | Record's parent not synced | (Fulfill & Ship) POST `/item-fulfillments` when the Sales Order isn't synced into Toga yet | `GET /sales-orders/syncNetsuiteSalesOrder?netsuiteInternalSalesOrderId=<id>` first |
 
 ## How to diagnose
@@ -64,6 +66,23 @@ migration instead of re-deriving it. All field/script ACL rows live in the **CLI
    **before** the interceptor/logging layer, and initialize loop-locals so no branch leaves a
    variable undefined.
 
+6. **What a denial looks like from the CLIENT side (EZ-1 vs EZ-2, and the silent case).**
+   Severity differs by request shape, and one shape hides the denial entirely:
+   - **EZ-1 is a record-level block** — `data.<route>` comes back **`null`**; nothing is usable.
+     Note a bare `allowRead = 1` grant row is **not** sufficient: without a logic group behind it
+     the route still returns `EZ-1`.
+   - **EZ-2 is field-level** — on a **LIST** it is *degraded but usable* (the permitted fields
+     still populate alongside the 403), but on a **by-uuid READ** it is **fatal**.
+   - **Omit `fields=` and a denied field is SILENTLY omitted** from the JSON: HTTP 200, no
+     warning, undetectable from the envelope. Name the field in `fields=` and you instead get
+     `EZ-2` with a machine-readable **`identifiers.fields`** list. **Always send an explicit
+     `fields=` list** so denials are visible.
+   - **`meta.prohibitedRecordCount`** (populated only when `totalRecordCount` is 0) tells you
+     "ACL hid every row" vs. "there genuinely are none."
+   - **Match these codes EXACTLY when branching on them in a client.** A substring match
+     classifies a future `EZ-25` as `EZ-2` — i.e. it would read data out of a 403. Fail **closed**
+     on an unrecognized 403 code.
+
 4. **EO-1 ("no field called 'X' in the model") is NOT a DB problem.** EV-8 means the Core
    `RecordFields` registration is missing; EO-1 means the DB column and RecordFields are both
    present but the **generated PHP model class** lacks the field. Before touching migrations,
@@ -77,10 +96,22 @@ migration instead of re-deriving it. All field/script ACL rows live in the **CLI
 - **Add a writable field to a V2 record (3-file migration)** and **expose a scripted API**
   (RecordScript + AclRecordScripts): see
   [ACL Permission Chain](../../_underscore/features/acl-permission-chain.md).
+- **Query-side contract an HTTP client must obey** (recognized params, `where` grammar,
+  encoding, pagination, and the unrecognized-param LIST→READ flip that 404s a valid route):
+  see [V2 REST query contract](v2-rest-query-contract.md).
 - The response-envelope shape and code families: see [api2 architecture](../architecture.md).
 
 ## Change history
 
+- 2026-07-29 — Added **EV-13** (`recordsPerPage` over the 10000 max) and **diagnosis note 6**:
+  what a denial looks like from the client side — `EZ-1` = record-level (`data.<route>` null,
+  and a bare `allowRead=1` with no logic group still returns it); `EZ-2` = field-level,
+  degraded-but-usable on a LIST and fatal on a by-uuid READ; **omitting `fields=` makes a denial
+  SILENT** (200 with the field quietly absent) while naming it yields `EZ-2` +
+  `identifiers.fields`; `meta.prohibitedRecordCount` distinguishes ACL-hidden from genuinely
+  none; and **match codes exactly / fail closed** (a substring match reads `EZ-25` as `EZ-2` and
+  would parse data out of a 403). Surfaced re-verifying the BDR API client's ContactAttempts
+  block. Linked the new [V2 REST query contract](v2-rest-query-contract.md). (tcox)
 - 2026-07-27 — TRUE-79533: noted the **`id`-field** case of `EZ-2` — fetching a record by its numeric
   `id` (`GET /v2/addresses?fields=id,...`) 403s `EZ-2` when `id` has no `AclFieldPermissions` read
   grant; the `id` field is ACL-gated like any field. Found fixing Rate's service-card address fetch

package/knowledge/2.0/apps/api2/features/v2-rest-query-contract.md

@@ -0,0 +1,138 @@
+---
+title: V2 REST query contract (params, where grammar, encoding, ACL behavior)
+framework: "2.0"
+repo: api2
+project: API
+client: shared
+type: feature
+status: active
+updated: 2026-07-29
+owners: [tcox]
+files:
+  - api2/Component/Api/V2/V2.php
+related:
+  - ../architecture.md
+  - v2-api-error-codes.md
+  - tableview-apiwhereclause-row-filtering.md
+  - nested-fk-acl-embedding.md
+---
+
+## Summary
+
+What an **HTTP client** has to get right to query the Toga v2 REST API: which query params are
+recognized, the exact `where` grammar, how the query string is (not) decoded, how pagination
+works, and — the part that costs the most time — how ACL denials actually manifest per request
+shape. Source-verified against `api2/Component/Api/V2/V2.php`. The tableview-side view of the
+same `where` parser is in
+[tableview-apiwhereclause-row-filtering.md](tableview-apiwhereclause-row-filtering.md); the
+code-by-code troubleshooting map is in [v2-api-error-codes.md](v2-api-error-codes.md).
+
+## Routes are DATA, not code
+
+Routes are rows in `Core.Records`, keyed by the **exact kebab route string**, lowercased before
+lookup. The envelope key is the kebab route converted to camel:
+
+```
+GET /v2/contact-attempts   →   data.contactAttempts
+```
+
+So "the endpoint doesn't exist" is usually a missing/misnamed `Core.Records` row, not a missing
+controller.
+
+## Recognized query params
+
+`fields`, `where`, `join` / `ojoin`, `sort`, `group`, `distinct`, `page`, `recordsPerPage`,
+`depth`, `calcDepth` (or one base64(JSON) `_` blob).
+
+- **Pagination is `page` + `recordsPerPage`. There is no `limit`/`offset`.** Defaults:
+  `recordsPerPage` **25**, `depth` **3**. Max `recordsPerPage` **10000** — exceeding it returns
+  **`EV-13`** (HTTP 400).
+- **Sort:** `-field` = DESC, bare `field` = ASC. **Do not send `+`** for ascending.
+
+### CRITICAL — an unrecognized param silently flips LIST → READ
+
+Any query param the engine does not recognize switches the request onto a **different code
+path** — the by-uuid READ path, which expects a uuid. The symptom is a confusing **HTTP 404**
+on a route that plainly exists. This is the likely cause of the previously recorded
+`with=...` → 404. **Send only recognized params — no cache-busters, no ad-hoc flags.**
+
+## `where` grammar
+
+```
+where=(field:op:value,LOGIC,field:op:value,(nested,OR,nested))
+```
+
+- Conditions are comma-separated; **parentheses are REQUIRED to switch between AND and OR**.
+- Operators: `eq`, `ne`, `gt`, **`ge`**, `lt`, **`le`**, `not`, `like`, `contains`, `starts`,
+  `ends`, `excludes`, `in`, `notin`, `between`. **It is `ge`/`le`, not `gte`/`lte`.**
+- `in` / `notin` / `between` take **colon-separated** values.
+- **NULL has no operator.** Use the literal value `null`: `field:eq:null` → `IS NULL`,
+  `field:ne:null` → `IS NOT NULL`.
+
+## Encoding rules (the query string is never urldecoded at parse time)
+
+- Encode a literal `%` in a LIKE pattern as **`%25`**.
+- Encode the space in a datetime as **`%20`**.
+- Use **MySQL datetime** `YYYY-MM-DD HH:MM:SS` — **not** ISO-8601 with a `T`.
+- Values must not contain **raw commas or parentheses** (they are grammar).
+
+## ACL behavior (what a denial actually looks like)
+
+- **`where` and `join` are NOT ACL-checked — only `fields` is.** You can therefore **filter** on
+  `Contacts.uuid` with no read grant on `Contacts`, as long as you never **select** a
+  `Contacts.*` field. Useful when you have a child grant but not the parent's fields.
+- **Referencing a table in `where` that you did not `join`** produces invalid SQL, which is
+  uncaught → **`EO-1` 500**.
+- **Nested route `/contacts/{uuid}/contact-attempts`** auto-filters by the child's FK
+  (discovered by **model class**, not field name) and requires **record-level READ on the
+  parent** but **no field grant** on it.
+- **Field-denial behavior differs by request shape:**
+  - **Omit `fields=`** → denied fields are **silently omitted** from the JSON. HTTP 200, no
+    warning, and the omission is **undetectable from the envelope**.
+  - **Name them in `fields=`** → **`EZ-2` 403** with a machine-readable `identifiers.fields`
+    list, **and the permitted data still populated**.
+  - **Recommendation: always send an explicit `fields=` list.** Silent omission is how a
+    consumer ends up "working" against data it never actually received.
+- **`EZ-1` vs `EZ-2` for a consumer:** `EZ-1` = record-level block (`data.<route>` is `null`) —
+  hard blocked, nothing usable. `EZ-2` = field-level — on a **LIST** it is
+  *degraded-but-usable*; on a **by-uuid READ** it is **fatal**.
+- **A bare `allowRead = 1` grant row is not enough** — it needs a logic group behind it or the
+  route still returns `EZ-1`.
+- **`meta.prohibitedRecordCount`** (set only when `totalRecordCount` is 0) distinguishes
+  "ACL hid every row" from "there genuinely are none."
+
+## Serialization quirks
+
+- **Datetimes on a primary table** serialize as ISO-8601 with a **Central offset** (no
+  conversion is applied — api2 runs `America/Chicago`).
+- **Datetimes pulled through a `join`** come back as **raw, offset-less** strings. A client that
+  parses both paths with one function will be wrong on one of them.
+- **Custom `c_` fields are returned FLAT** alongside standard fields (sorted last, `c_` prefix
+  retained) and are filterable like normal columns — but they are granted through a **separate**
+  table, **`AclCustomFieldPermissions`**, not `AclFieldPermissions`. State that explicitly when
+  requesting a grant, or the grant gets written to the wrong table and changes nothing.
+
+## Gotchas / known issues
+
+- **A 404 on a route you know exists ⇒ suspect an unrecognized query param** (LIST → READ flip)
+  before suspecting the route.
+- **A 500 (`EO-1`) on a filter ⇒ suspect a `where` reference to an unjoined table.**
+- **`gte`/`lte` silently are not operators** — use `ge`/`le`.
+- **Do not trust a 200 with missing fields.** Without an explicit `fields=` list, ACL removal is
+  invisible; re-request with `fields=` to force `EZ-2` and see the denied list.
+
+## Change history
+- 2026-07-29 — Created from a source read of `api2/Component/Api/V2/V2.php` while building the
+  BDR funnel's call-status reads. Recorded: routes-as-data (`Core.Records`, kebab → camel
+  envelope key); the recognized-param list and the **unrecognized-param LIST→READ flip** that
+  surfaces as a bogus 404 (explains the old `with=...` → 404); the full `where` grammar
+  (parens required to switch AND/OR, `ge`/`le` not `gte`/`lte`, `null` as a literal value);
+  `page`/`recordsPerPage` only (max 10000 → `EV-13`) and `-`/bare sort prefixes; the
+  no-urldecode encoding rules (`%25`, `%20`, MySQL datetime, no raw commas/parens); the ACL
+  subtleties (`where`/`join` unchecked but `fields` checked; unjoined table in `where` →
+  `EO-1` 500; nested-route parent record grant with no field grant; **silent field omission
+  without `fields=` vs. `EZ-2` + `identifiers.fields` with it**; `EZ-1` hard vs `EZ-2`
+  degraded-on-LIST/fatal-on-READ; bare `allowRead=1` still `EZ-1`;
+  `meta.prohibitedRecordCount`); and the serialization quirks (Central offset on primary-table
+  datetimes vs. raw offset-less through a join; flat `c_` fields granted via
+  `AclCustomFieldPermissions`). (tcox)

package/knowledge/2.0/apps/worker2/INDEX.md

@@ -32,7 +32,7 @@
 | [Talos Transcript Ingestion Pipeline (worker2 → AWS Bedrock KBs)](features/talos-transcript-ingestion.md) | > **DB-DRIVEN AI-MODEL ROUTING (2026-07-29).** Which knowledge base a transcript is cleaned > into is now decided by the **meeting organizer's "home" AI model** | worker2/Worker/Team/Transcripts.php, worker2/bin/sync-knowledge-bases.php, worker2/Config/production.ini, worker2/Database/TeamsTranscriptExports.sql, dbchanges2/Client_True/2026-07-27a - TranscriptAiModelRoutingColumns.sql, dbchanges2/Client_True/2026-07-27b - TranscriptAiModelRoutingData.sql, dbchanges2/Team/2026-07-27a - TranscriptVocabularyAiModelScope.sql, dbchanges2/Team/2026-07-29a - TranscriptVocabularyBackfillAllModels.sql, dbchanges2/Team/2026-06-30a, dbchanges2/Team/2026-06-30b, dbchanges2/Team/2026-06-30c, dbchanges2/Team/2026-06-30d, dbchanges2/Team/2026-06-30e, dbchanges2/Core/2026-06-30a, dbchanges2/Core/2026-07-02a, dbchanges2/Team/2026-07-02a, dbchanges2/Team/2026-07-08a, dbchanges2/Team/2026-07-09a, dbchanges2/Team/2026-07-10a, dbchanges2/Team/2026-07-28a - TranscriptProcessingRetryAttempts.sql, dbchanges2/Team/2026-07-28b - TranscriptPromptTemplateConverseModel.sql, dbchanges2/Core/2026-07-28a - TeamsTranscriptRetryCron.sql |
 | [Team Sprint Management & Reporting](features/team-sprint-management.md) | `_Worker_Team_Sprint` (file `Worker/Team/Sprint.php`) is the engine behind TOGA's internal **development-sprint process and reporting**. | worker2/Worker/Team/Sprint.php, _underscore/Model/Team/Sprint.php, dbchanges2/Core/CronJobs (SprintLockScheduled seed) |
 | [Teams Meeting Transcript Export](features/teams-transcript-export.md) | > **SUPERSEDED (2026-07-09) — the S3-staging model below is history.** `Export` is now a thin > **GRAPH-DIRECT** cron poller: it no longer archives raw VTT to ` | worker2/Worker/Team/Transcripts.php, worker2/Config/production.ini, worker2/Database/TeamsTranscriptExports.sql, dbchanges2/Core/2026-06-18a - Teams Transcript Export schedule.sql |
-| [VAPI Webhook Handler (worker2 — AI-BDR end-of-call processing)](features/vapi-webhook-handler.md) | `_Worker_Vapi` ([worker2/Worker/Vapi.php](worker2/Worker/Vapi.php)) is the **PHP side of the AI-BDR call loop** — the webhook that receives VAPI's end-of-call r | worker2/Worker/Vapi.php, worker2/Worker/Ai/Bdr/Vapi.php |
+| [VAPI Webhook Handler (worker2 — AI-BDR end-of-call processing)](features/vapi-webhook-handler.md) | `_Worker_Vapi` ([worker2/Worker/Vapi.php](worker2/Worker/Vapi.php)) is the **PHP side of the AI-BDR call loop** — the webhook that receives VAPI's end-of-call r | worker2/Worker/Vapi.php, worker2/Worker/Ai/Bdr/Vapi.php, worker2/Controller/Index.php |
 | [WJE Freshservice Sync (worker2)](features/wje-freshservice-sync.md) | WJE ("WJE IT", helpdesk `wje.freshservice.com`) is a **Freshservice**-based help-desk client whose tickets, contacts, assets, groups, categories, and canned res | worker2/Worker/Wje.php, _underscore/Component/Api/Wje/Wje.php, _underscore/Model/Wje/Ticket.php, _underscore/Model/Wje/TicketNote.php, _underscore/Model/Wje/Contact.php, _underscore/Model/Wje/Unit.php, _underscore/Model/Wje/TicketTeam.php, _underscore/Model/Wje/TicketCategory.php, _underscore/Model/Wje/AssetType.php, _underscore/Model/Wje/PredefinedReply.php, library/app/api/wje.php, worker/crons/toga2/wje/import_supporting_records.php, worker/crons/toga2/wje/sync_togasupply_wje.php, worker/crons/notifications/reports/wje/wje_common.php, library/app/systemmonitor/wje.php, dbchanges2/Client_Wje/2024-10-04 - WjeOnboarding.sql |
 | [PHP Runtime Upgrade on Elastic Beanstalk (worker2 8.3 → 8.5 + PhpSpreadsheet 1.x → 3.x)](workflows/php-runtime-upgrade-dependency-audit.md) | The procedure used to move worker2 from **PHP 8.3 to PHP 8.5** on Elastic Beanstalk, and the dependency work that had to land first. | worker2/composer.json, worker2/composer.lock, worker2/Worker/Team/Sprint.php, worker2/Worker/Client/TowFoundation/ProcessReceipts.php, worker2/Worker/Forecast/Import.php |
 | [Ticket → ClickUp Pseudocode Planning (Talos-grounded)](workflows/ticket-to-pseudocode-planning.md) | A repeatable procedure for turning a ClickUp ticket into a reviewed, formatted implementation plan posted back to the ticket's `📝 Pseudocode` custom field. | test/@dave/clickup_md2delta.js |

package/knowledge/2.0/apps/worker2/features/creating-worker-actions.md

@@ -6,8 +6,8 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-07-28
-owners: [jcardinal, dfranks, mhammontree]
+updated: 2026-07-29
+owners: [jcardinal, dfranks, mhammontree, tcox]
 files:
   - worker2/Worker/
   - worker2/Controller/Index.php
@@ -147,6 +147,25 @@ curl -X POST https://worker.togahub.com/ \
 
 Use realistic placeholder values, not empty strings/nulls.
 
+### The HTTP reply is PREFIXED — never `JSON.parse` it raw
+
+The dispatcher returns your action's return value **wrapped in the same composed success
+string it writes to `WorkerJobs.output`**, over HTTP too:
+
+```
+[<requestId>] Successfully Executed (<n> seconds): <your json>
+```
+
+So any HTTP consumer that calls `response.json()` (or `json_decode()`) on the raw body
+**always** fails, even on a completely successful run — and typically logs a misleading
+"the job didn't run" while silently discarding a useful response body. **Strip the prefix
+before parsing** (a regex up to the first `: ` after the `Successfully Executed (…)` segment).
+
+This bit BDR's fast-dial caller (`bdr/src/server/workerDialer.ts`): it logged "immediate dial
+not placed" on **every successful dial** and threw away `InitiateOutboundCall`'s response —
+which is where the Vapi call id lives. If you write an action whose return value matters to
+an HTTP caller, say so in its doc, because the caller has to unwrap it.
+
 ## How exceptions & retries work
 
 The EB worker dispatcher (`Controller/Index.php::worker()`) wraps your action call in
@@ -207,6 +226,12 @@ be reattempted.
   commit-before-SQS transaction pattern that the worker relies on.
 
 ## Change history
+- 2026-07-29 — Documented that the dispatcher's **HTTP reply carries the same
+  `[<requestId>] Successfully Executed (<n> seconds): <json>` prefix** it writes to
+  `WorkerJobs.output`, so a direct-POST consumer must strip it before parsing — calling
+  `response.json()` raw always throws on a successful run and silently discards the body.
+  Surfaced fixing BDR's fast-dial caller, which logged "immediate dial not placed" on every
+  successful dial and lost the Vapi call id. (tcox)
 - 2026-07-28 — Added the **`_ApiRequest` logging / `DB_CLIENT_LOGS` gotcha**: api-log rows are
   written via `_Model_Client_Logs_Api` (`DATABASE = DB_CLIENT_LOGS`), so a worker must either
   register the Logs DB under that alias in `initialize()` or pass `setLogging(false)`

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

@@ -6,16 +6,19 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-07-23
+updated: 2026-07-29
 owners: [snaredla, tcox]
 files:
   - worker2/Worker/Vapi.php
   - worker2/Worker/Ai/Bdr/Vapi.php
+  - worker2/Controller/Index.php
 related:
   - ../../ai-bdr/features/call-orchestration.md
   - ../../ai-bdr/features/vapi-integration.md
+  - ../../ai-bdr/features/live-call-status.md
   - ../../ai-bdr/workflows/safe-call-loop-testing.md
   - ../../api2/features/nested-relationship-writes.md
+  - creating-worker-actions.md
 ---
 
 ## Summary
@@ -154,6 +157,24 @@ truth for **"why isn't my contact being called."** Confirmed against source
 `initiateCallForContact(…, CALL_TYPE__IMMEDIATE)`. It errors **"not assigned to any active
 campaign"** if no ACTIVE/PENDING campaign-contact link exists.
 
+**`InitiateOutboundCall` return shape (a real contract — BDR's fast dial depends on it).** On
+success it returns:
+
+```json
+{"success": true, "contactId": 0, "contactUuid": "", "campaignId": 0, "campaignUuid": "",
+ "phoneNumber": "", "attemptNumber": 1, "attemptId": 0, "vapiCallId": "", "remainingSlots": 0}
+```
+
+- **`vapiCallId` may be the literal string `'unknown'`** — a caller using it as a handle must
+  treat that as "no handle," not as an id.
+- **An HTTP caller must strip the dispatcher's reply prefix first.** The direct-POST endpoint
+  wraps every reply as `[<requestId>] Successfully Executed (<n> seconds): <json>`
+  (`Controller/Index.php` ~L498, action at `Worker/Ai/Bdr/Vapi.php` ~L503), so
+  `response.json()` on the raw body always throws — see
+  [creating-worker-actions.md](creating-worker-actions.md). BDR consumes `vapiCallId` from this
+  body to drive its live call-status UI
+  ([live-call-status.md](../../ai-bdr/features/live-call-status.md)).
+
 ### Finer detail (source-verified 2026-07-20)
 
 Where each gate actually lives in `Worker/Ai/Bdr/Vapi.php`, and where the eligibility summary
@@ -243,6 +264,10 @@ the home for this credential. (Token value is deliberately not recorded here —
 **HubSpot access token** and **Toga API client secret** that are committed to git in the old `info`
 repo's tracked `.env.*` files — see the security gotcha in
 [ai-bdr web-funnel-app.md](../../ai-bdr/features/web-funnel-app.md).
+**Rotation now has a second consumer (2026-07-29):** BDR reads the **same** Vapi bearer as the
+server-only env var `TOGA_VAPI_TOKEN` to drive its live call-status UI. Rotating this token
+without updating BDR's `.env.local` **and** the Amplify console vars takes BDR's live status
+dark (it silently degrades to the scripted simulation) — coordinate the two changes.
 
 ## Data model
 
@@ -287,6 +312,15 @@ status. See the `ai-bdr` skill / `_Model_True_ContactAttempt` for the full field
   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-29 — Recorded **`InitiateOutboundCall`'s success return shape** (`success`,
+  `contactId`, `contactUuid`, `campaignId`, `campaignUuid`, `phoneNumber`, `attemptNumber`,
+  `attemptId`, `vapiCallId`, `remainingSlots`) — now a real contract because BDR's fast dial
+  reads `vapiCallId` from it to drive live call status. Two caveats: `vapiCallId` can be the
+  literal `'unknown'`, and an HTTP caller must **strip the dispatcher's
+  `[<requestId>] Successfully Executed (…): ` prefix** before parsing (BDR was calling
+  `response.json()` raw and logging a false "dial not placed" on every success). Also noted that
+  rotating the hardcoded Vapi bearer now requires updating BDR's env + Amplify vars in the same
+  change or BDR's live status goes dark. (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/INDEX.md

@@ -20,7 +20,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 - **_underscore** (_Underscore) _(framework core)_ — 40 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 35 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
-- **api2** (API) — 19 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
+- **api2** (API) — 20 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 3 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 3 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)
 - **saml** (SAML SSO Gateway) — 3 doc(s) → [2.0/apps/saml/INDEX.md](2.0/apps/saml/INDEX.md)
@@ -28,7 +28,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) — 7 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) — 8 doc(s) → [2.0/apps/ai-bdr/INDEX.md](2.0/apps/ai-bdr/INDEX.md)
+- **ai-bdr** (AI-BDR) — 9 doc(s) → [2.0/apps/ai-bdr/INDEX.md](2.0/apps/ai-bdr/INDEX.md)
 - **toga2-commerce** (TOGa Commerce) — 11 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
 - **toga25-supply** (TOGa 2.5 Supply) — 11 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
 - **toga-blox** (TOGa Blox) — 8 doc(s) → [2.0/apps/toga-blox/INDEX.md](2.0/apps/toga-blox/INDEX.md)

package/knowledge/registry.json

@@ -224,7 +224,8 @@
     "framework": "2.0",
     "role": "app",
     "dependsOn": [
-      "api2"
+      "api2",
+      "worker2"
     ]
   }
 ]

package/package.json

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