toga-ai 1.0.358 → 1.0.359

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

@@ -6,6 +6,6 @@
 | [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/components/GoogleAnalytics.tsx, bdr/src/components/RichText.tsx, bdr/src/content, bdr/src/components, bdr/src/flow, bdr/src/server, bdr/src/app/api, bdr/test, 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/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/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/app/api, bdr/test, 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 |

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

@@ -6,8 +6,8 @@ project: AI-BDR
 client: shared
 type: feature
 status: active
-updated: 2026-06-16
-owners: [akhokhani]
+updated: 2026-07-16
+owners: [akhokhani, tcox]
 files:
   - ai-bdr/docs/client-onboarding-sop.md
   - ai-bdr/docs/vapi-firstmessage-timing-fix.md
@@ -208,7 +208,11 @@ gracefully handles `"Information not available"`.
 **Now committed in `worker2`** as `_Worker_Vapi` (`worker2/Worker/Vapi.php`,
 the webhook) alongside the outbound dialer `_Worker_Ai_Bdr_Vapi`
 (`worker2/Worker/Ai/Bdr/Vapi.php`). Full detail:
-**`2.0/apps/worker2/features/vapi-webhook-handler.md`**.
+**`2.0/apps/worker2/features/vapi-webhook-handler.md`** — which now also documents the
+**dialer eligibility rules** (`getEligibleContactsForVapi()`: the exact ALL-of criteria that
+decide whether a contact is dialed, the `dtNextContactRequested <= NOW()` call-window/cadence
+bypass used by the website "call now/scheduled" path, and the phone-less-contact gotcha where a
+missing `primaryContactPhoneNumberId` silently excludes a contact).
 
 > **Corrections confirmed against the live `_Worker_Vapi` code (2026-06-24):**
 > 1. **Structured output is in `artifact.structuredOutputs`** (keyed by a random
@@ -263,4 +267,7 @@ feature doc in that repo's `features/` and link it from this file's
 - **`attemptNumber` is 1-indexed**, not 0-indexed. First call = 1.
 
 ## Change history
+- 2026-07-16 — Cross-referenced the newly documented dialer eligibility rules
+  (`getEligibleContactsForVapi`) in `worker2/features/vapi-webhook-handler.md` from the
+  "Where the PHP code lives" section. (tcox)
 - 2026-06-16 — Initial call-orchestration feature doc (PHP ↔ Vapi seam). (akhokhani)

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

@@ -21,6 +21,9 @@ files:
   - bdr/src/lib/scheduleSlots.ts
   - bdr/src/lib/formatPhone.ts
   - bdr/src/lib/analytics.ts
+  - bdr/src/lib/rateLimit.ts
+  - bdr/src/proxy.ts
+  - bdr/.env.example
   - bdr/src/components/GoogleAnalytics.tsx
   - bdr/src/components/RichText.tsx
   - bdr/src/content
@@ -53,8 +56,13 @@ fully implemented at commit `34a3910`: `page.tsx primeLead` reads `?hsContactId=
 campaign attribution → only `togaUuid` crosses to the client). The 2026-07-16 session
 added the deltas below (phone prefill + live input mask, `submitOk` on Success, GA4
 wiring) and resolved §9.10 (content mechanism — see `web-funnel-content-model.md`) and
-§9.11 (consent links). Developer QA verdict: the UI is "very close, minimal adjustments
-to be near exact" vs. the mockup. All checks green: tsc, eslint, 79/79 Vitest, `next build`.
+§9.11 (consent links). A later 2026-07-16 session added an **interim app-layer rate-limit
+mitigation** for the `?hsContactId=` enumeration risk (`src/proxy.ts` + `src/lib/rateLimit.ts`),
+documented the **fully server-side request-a-call seam**, the **outbound dialer eligibility
+rules** (see `../../worker2/features/vapi-webhook-handler.md`), the **phone-less-contact
+dialer bug**, and the **local dev env wiring**. Developer QA verdict: the UI is "very close,
+minimal adjustments to be near exact" vs. the mockup. All checks green: tsc, eslint,
+89/89 Vitest, `next build` (build output labels the proxy `ƒ Proxy (Middleware)`).
 
 - **Repo:** `agilantsolutions/BDR` on GitHub, working branch `BDR-Development`. The
   machine-local `.claude/` harness is **gitignored** — committing it would snapshot
@@ -75,9 +83,15 @@ to be near exact" vs. the mockup. All checks green: tsc, eslint, 79/79 Vitest, `
 - **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: **79 tests, all green** (13 added in the 2026-07-16 session:
-  phone format/prefill/mask, live-anchor consent links, `submitOk` race). Every phase was
-  verified with `tsc` + lint + build + a live SSR `curl` before commit.
+- **Vitest** test suite: **89 tests, all green** (13 added in the first 2026-07-16 session:
+  phone format/prefill/mask, live-anchor consent links, `submitOk` race; 10 more in the
+  later 2026-07-16 session for the rate limiter). Every phase was verified with `tsc` + lint
+  + build + a live SSR `curl` before commit.
+- **Edge proxy (Next 16 `proxy.ts`).** `src/proxy.ts` is the Next 16 request proxy (the
+  successor to the deprecated `middleware.ts` convention — see the Next 16 gotcha) carrying
+  the interim rate-limit mitigation. It uses `src/lib/rateLimit.ts`, a pure clock-injected
+  in-memory token-bucket limiter (no `server-only`, so it runs in the edge proxy and is
+  unit-testable in Node).
 - **Deploy target:** AWS Amplify (SSR), `amplify.yml` present (Phase 8 not done).
 
 ## Directory map (what got built)
@@ -99,7 +113,10 @@ to be near exact" vs. the mockup. All checks green: tsc, eslint, 79/79 Vitest, `
 - `src/server/*` — the real backend, ported from `info`'s `toga.ts` / `hubspot.ts`
   behind `LeadSink` + `CallbackService` adapters (detail in
   `web-funnel-content-model.md`).
-- `src/app/api/*` — route handlers `call-now`, `call-later`, `contact`.
+- `src/app/api/*` — route handlers `call-now`, `call-later`, `contact`. **These do NOT
+  place a call themselves** — see "Request-a-call is fully server-side" below.
+- `src/proxy.ts` — Next 16 edge proxy (rate limiting; see gotcha). `src/lib/rateLimit.ts` —
+  the token-bucket limiter it uses.
 - `public/*` — assets pruned to the **default campaign only**, **plus AutoBuild's
   FLOURISH characters** (Owl 1 `owl-02` + Robot 1 `robot-02`, art + talk videos) which
   the assembly cycle needs even though they are not the campaign agent. See the
@@ -156,6 +173,67 @@ to be near exact" vs. the mockup. All checks green: tsc, eslint, 79/79 Vitest, `
   `http(s)` hrefs as live anchors (`target=_blank`, `rel="noopener noreferrer"`, aria-label
   "... (opens in new tab)"); bare `#hash` hrefs keep the mockup's inert `preventDefault`.
 
+## Request-a-call is fully server-side ("no API call in my console" is expected)
+
+The "request a call" flow (Call Now / Schedule) is **entirely server-side** — this is by
+design, and repeatedly causes "there's no Toga API call in my network tab" confusion.
+
+- The **browser only POSTs to the Next route handler** (`/api/call-now`, `/api/call-later`).
+  A `200 POST /api/call-now` in the console **is** the success signal.
+- The **Toga calls happen inside that route handler**, server-side: `POST /auth/api` to get a
+  token, then `PUT /contacts/{uuid}` against production `api.togahub.com/v2`
+  (`src/server/toga.ts`, `src/server/callbackService.ts`, `src/flow/leadActions.ts`). So
+  Toga/api2 traffic **never appears in the browser network tab** — only the internal
+  `/api/*` hop does.
+- **BDR itself never places a call.** The `PUT /contacts/{uuid}` only flips flags on the
+  contact: `dtNextContactRequested` (literal `NOW()` for immediate, a CST-formatted datetime
+  for scheduled), `isOkayToCall=1`, `isActive=1`, and the `contactCallType {uuid}` (immediate
+  vs. scheduled `CONTACT_CALL_TYPE_UUID`). The actual Vapi call is placed later by the
+  **worker2 dialer cron** (`_Worker_Ai_Bdr_Vapi`) — see the eligibility rules below.
+
+## The outbound dialer decides whether the call ever happens (worker2)
+
+Setting `dtNextContactRequested` does **not** guarantee a call — the worker2 dialer's
+eligibility SQL (`getEligibleContactsForVapi()` in `worker2/Worker/Ai/Bdr/Vapi.php`) is the
+source of truth for "why isn't my contact being called." Full rules are documented in
+**`../../worker2/features/vapi-webhook-handler.md`**. Two consequences matter to the funnel:
+
+- The website "call me now / scheduled" path (`dtNextContactRequested <= NOW()`) **bypasses**
+  call windows and weekly cadence limits, but still requires an active campaign **with an
+  assigned assistant**, `isActive=1`, `isOkayToCall=1`, a live **primary** phone, and
+  `attemptCount < maxAttemptsPerContact`.
+- **BUG — a phone-less HubSpot contact can never receive a call (silent).** When the HubSpot
+  contact has no phone, BDR creates the Toga contact **without** a phone at page-prime; the
+  phone the visitor types arrives later via the Call Now `PUT`. api2 creates a
+  `ContactPhoneNumber` row on that update but does **not** set
+  `Contacts.primaryContactPhoneNumberId`. The dialer's eligibility SQL `INNER JOIN`s on
+  `primaryContactPhoneNumberId`, so the contact stays invisible to the dialer. **Re-submitting
+  does not fix it** (verified in production: the phone row exists but the primary pointer
+  stays null). The funnel still shows success and returns `200` — a silent failure. The old
+  `info` site never hit this because CRM-sourced contacts already had a phone at CREATE time
+  (api2 links the primary on create, not on a later update). Fix candidates: api2-side (set
+  the primary when a phone row is created during an update) or a BDR workaround (a follow-up
+  `PUT` linking the existing phone-row uuid as primary). Affects **any** phone-less HubSpot
+  contact and blocks live call testing.
+
+## Local dev setup (BDR)
+
+BDR local dev needs **5 server-side env vars** in `BDR/.env.local` (gitignored, never
+committed): `HUBSPOT_ACCESS_TOKEN`, `TOGA_API_BASE_URL`, `TOGA_CLIENT_ID`,
+`TOGA_CLIENT_API_UUID`, `TOGA_CLIENT_API_SECRET`. **Where the values live (not the values
+themselves):** source them from the **`info` repo's `.env.local`**, which carries the
+PRODUCTION credential set (`TOGA_API_BASE_URL = https://api.togahub.com/v2`).
+
+- **`info/.env.beta` is a DEAD file** — empty URLs and obsolete var names (e.g.
+  `TOGA_CLIENT_SECRET` vs. the current `TOGA_CLIENT_API_UUID` / `TOGA_CLIENT_API_SECRET`
+  pair). Production is the only working credential set `info` has.
+- **Consequence: local dev hits LIVE Toga** and can trigger **real calls** — treat local
+  submits accordingly.
+- **Leave `NEXT_PUBLIC_GA_MEASUREMENT_ID` unset locally** so dev traffic does not pollute the
+  production GA4 property (`analytics.ts` no-ops without it).
+- **Restart the dev server after creating `.env.local`** — Next reads env files only at
+  server startup. `.env.*` is gitignored in BDR.
+
 ## What is parked / not built
 
 - **Creator screen + `TweaksPanel` — deliberately NOT ported** (parked per plan
@@ -179,13 +257,39 @@ to be near exact" vs. the mockup. All checks green: tsc, eslint, 79/79 Vitest, `
   entry identifiers would ship to Google on every hit. Mitigation (in place): initialize
   with `gtagOptions {send_page_view:false}` and pin a **query-scrubbed** `page_location`
   via `ReactGA.set` before each pageview. Never send raw `location.href` to analytics here.
-- **HIGH / OPEN (security) — `?hsContactId=` is an enumerable capability token.** The entry
-  page is public and HubSpot contact ids are small integers; a bot walking ids can (a)
-  scrape each contact's phone from the server-rendered prefill, and (b) drive the page-prime
-  Toga upsert, polluting contacts/attribution. **Inherited from `info`'s CRM-link URL
-  contract — cannot be changed unilaterally.** Mitigation path before public launch: a
-  **per-IP WAF rate rule** on the Amplify distribution (Phase 8), and raise **opaque/signed
-  link tokens** with the CRM owner. Tracked in `BDR/PLAN.md` §10.
+- **HIGH (security) — `?hsContactId=` is an enumerable capability token (interim mitigation
+  in place, authoritative fix still deferred).** The entry page is public and HubSpot contact
+  ids are small integers; a bot walking ids can (a) scrape each contact's phone from the
+  server-rendered prefill, (b) scrape the **full** contact record via `GET /api/contact`
+  (see next gotcha), and (c) drive the page-prime Toga upsert, polluting contacts/attribution.
+  **Inherited from `info`'s CRM-link URL contract — cannot be changed unilaterally.**
+  **Interim app-layer mitigation (BUILT, 2026-07-16):** `src/proxy.ts` + `src/lib/rateLimit.ts`
+  rate-limit per client. Entry pages carrying `?hsContactId=` **soft-degrade** over the limit
+  (strip `hsContactId`, `NextResponse.rewrite` to render anonymously — a real shared-NAT user
+  keeps the funnel minus prefill; a scraper gets no PII and triggers no Toga upsert;
+  `hsCampaignId` is preserved). `/api/contact`, `/api/call-now`, `/api/call-later` return a
+  `429 {isSuccess:false,…}` envelope with `Retry-After` over the limit. **This is
+  defense-in-depth ONLY** — the limiter is per-runtime-instance in-memory (Amplify SSR may run
+  several instances), so it is not authoritative. The authoritative controls — a **per-IP edge
+  WAF rate rule** (Phase 8) and **opaque/signed CRM link tokens** (raise with the CRM owner) —
+  remain deferred. Tracked in `BDR/PLAN.md` §10/§11. (An independent `cso` review of this
+  mitigation was still running at capture time; treat it as "in place, pending final review".)
+- **HIGH (security) — `GET /api/contact?hsContactId=` returns the FULL contact record.** Name,
+  email, phone, company, and job title by id — a **more direct** PII scrape vector than the SSR
+  phone prefill. Now covered by the same rate limiter; **any change to
+  `src/app/api/contact/route.ts` must keep it rate-limited.**
+- **Next 16 — `middleware.ts` is DEPRECATED; use `proxy.ts`.** Next 16.2.3 warns "The
+  middleware file convention is deprecated. Please use proxy instead"
+  (nextjs.org/docs/messages/middleware-to-proxy). Correct convention: `src/proxy.ts` exporting
+  a function named `proxy` (or default) plus `export const config: ProxyConfig = { matcher:
+  [...] }`; import `NextRequest` / `NextResponse` / `ProxyConfig` from `"next/server"`;
+  `NextResponse.next()` / `.rewrite()` are unchanged. Build output labels it
+  `ƒ Proxy (Middleware)`. Write `proxy.ts` from the start on Next 16 — do not use `middleware.ts`.
+- **Request-a-call is server-side — expect NO Toga call in the browser network tab.** A
+  `200 POST /api/call-now` is the success signal; the `POST /auth/api` + `PUT /contacts/{uuid}`
+  happen inside the route handler. See "Request-a-call is fully server-side" above. And note
+  setting `dtNextContactRequested` does not guarantee a call — the worker2 dialer eligibility
+  SQL decides (a phone-less contact is silently never dialed; see that section).
 - **Standing rule: never add more PII fields to `ClientLeadRef`.** Phone is the one
   deliberate exception (visitor's own number, shown back to them, never logged). Every field
   on `ClientLeadRef` crosses to the public client and is exposed to the enumeration risk
@@ -218,6 +322,24 @@ to be near exact" vs. the mockup. All checks green: tsc, eslint, 79/79 Vitest, `
   harness; pull it with `npx toga-ai`.
 
 ## Change history
+- 2026-07-16 — Later same-day session. BUILT an interim app-layer rate-limit mitigation for the
+  `?hsContactId=` enumeration risk: `src/lib/rateLimit.ts` (pure clock-injected in-memory
+  token-bucket, idle-key eviction, no `server-only`) + `src/proxy.ts` (Next 16 proxy). Policy:
+  entry pages soft-degrade (strip `hsContactId`, rewrite anonymous, keep `hsCampaignId`);
+  `/api/{contact,call-now,call-later}` return `429` over the limit. Defense-in-depth only
+  (per-instance memory; edge WAF + signed CRM tokens still deferred to Phase 8); a `cso` review
+  was still running at capture. 10 new tests (89 total). DISCOVERED + documented: (1) the
+  request-a-call flow is fully server-side (`POST /auth/api` + `PUT /contacts/{uuid}` happen in
+  the route handler; browser only sees `/api/*`, so "no Toga call in my console" is expected;
+  the `PUT` only flips `dtNextContactRequested`/`isOkayToCall`/`isActive`/`contactCallType`, the
+  worker2 dialer places the call); (2) BUG — a phone-less HubSpot contact is silently never
+  dialed because api2 doesn't set `primaryContactPhoneNumberId` on a later update and the dialer
+  INNER JOINs on it (re-submit does not fix; verified in prod); (3) `GET /api/contact` returns
+  the full contact record (name/email/phone/company/title) — a direct PII scrape vector, now
+  rate-limited; (4) Next 16 `middleware.ts` is deprecated in favor of `proxy.ts`; (5) local dev
+  env wiring (5 server vars in `.env.local` sourced from `info`'s PRODUCTION `.env.local`;
+  `.env.beta` is dead; local dev hits LIVE Toga; leave GA id unset; restart to pick up env).
+  Dialer eligibility rules recorded in `../../worker2/features/vapi-webhook-handler.md`. (tcox)
 - 2026-07-16 — Phase 6 delta + §9.10/§9.11 resolutions. DISCOVERED the `info` URL/backend
   contract was already fully built at commit `34a3910` (primeLead: `?hsContactId=` +
   `?hsCampaignId=` → HubSpot `getContact` → Toga upsert + attribution → only `togaUuid` to

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

@@ -6,8 +6,8 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-06-24
-owners: [snaredla]
+updated: 2026-07-16
+owners: [snaredla, tcox]
 files:
   - worker2/Worker/Vapi.php
   - worker2/Worker/Ai/Bdr/Vapi.php
@@ -125,6 +125,46 @@ Therefore an `end-of-call-report` can legitimately arrive **without** a `contact
 job. `Contact Attempt not found` should be reserved for a report that *has* a
 `contactAttemptUuid` but no matching row (a real data-integrity anomaly).
 
+## Outbound dialer eligibility (`getEligibleContactsForVapi`)
+
+The outbound dialer `_Worker_Ai_Bdr_Vapi` (`worker2/Worker/Ai/Bdr/Vapi.php`) is the source of
+truth for **"why isn't my contact being called."** Confirmed against source
+`getEligibleContactsForVapi()` (~L197–306). A contact is dialed **only when ALL** hold:
+
+1. It is linked to an **active campaign that has an assigned assistant** —
+   `INNER JOIN CampaignAssistants ON Campaigns.campaignAssistantId`. A campaign with
+   `campaignAssistantId = null` is **never** dialed.
+2. `Contacts.isActive = 1`.
+3. `Contacts.isOkayToCall = 1`.
+4. A non-empty **PRIMARY** phone — `INNER JOIN ContactPhoneNumbers ON
+   Contacts.primaryContactPhoneNumberId` (the primary pointer, **not** just any phone row).
+5. `attemptCount < Campaigns.maxAttemptsPerContact`.
+6. **EITHER** `Contacts.dtNextContactRequested <= NOW()` — this path **BYPASSES call windows
+   AND weekly cadence limits**; it is the website "call me now / scheduled" path — **OR**
+   (`dtNextContactRequested IS NULL` AND within `CampaignCallWindows` for the campaign timezone
+   AND not a `CampaignCallWindowException` date AND under
+   `CampaignCadences.maxCallsPerContactPerWeek`).
+
+**Cron entry point:** `ProcessAllActiveCampaigns` (~L42) → `ProcessCampaignCalls` →
+`getEligibleContactsForVapi` → `processOutboundCalls`.
+
+**Single "Call Now" path:** `InitiateOutboundCall(contactPhoneNumberUuid)` (~L151–170) →
+`initiateCallForContact(…, CALL_TYPE__IMMEDIATE)`. It errors **"not assigned to any active
+campaign"** if no ACTIVE/PENDING campaign-contact link exists.
+
+### Gotcha — a phone-less contact is silently never dialed (BDR web funnel)
+
+Criterion 4's `INNER JOIN` on `primaryContactPhoneNumberId` is why a contact whose phone was
+added **after** creation can be invisible to the dialer: **api2 creates the
+`ContactPhoneNumber` row but does not set `Contacts.primaryContactPhoneNumberId` on an UPDATE**
+(it only links the primary on CREATE). The BDR web funnel hits this for any phone-less HubSpot
+contact — the visitor's typed phone arrives via a later `PUT /contacts/{uuid}`, so the row
+exists but the primary pointer stays null and the eligibility join excludes it. Re-submitting
+does not fix it (verified in production). See
+`../../ai-bdr/features/web-funnel-app.md` for the funnel side. Fix candidates: api2 sets the
+primary on phone-row create-during-update, or a caller-side `PUT` linking the existing
+phone-row uuid as primary.
+
 ## Data model
 
 Writes to `ContactAttempts` (via Toga 2.0 API) — `dtStarted`, `dtEnded`, `transcript`,
@@ -152,5 +192,11 @@ 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-16 — Documented the outbound dialer eligibility rules from source
+  `getEligibleContactsForVapi()` (the 6 ALL-of criteria, the `dtNextContactRequested <= NOW()`
+  window/cadence bypass = the website call-now/scheduled path, cron entry chain, and the single
+  "Call Now" `InitiateOutboundCall` path). Added the phone-less-contact gotcha: api2 does not
+  set `primaryContactPhoneNumberId` on an UPDATE, so the `INNER JOIN` on it silently excludes a
+  contact whose phone was added after create (blocks the BDR web funnel; verified in prod). (tcox)
 - 2026-06-24 — Initial doc: webhook handler, contactAttemptUuid write-back, message-type
   filtering bug, inbound/test vs outbound metadata. (snaredla)

package/package.json

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