toga-ai 1.0.476 → 1.0.478

package/knowledge/1.0/apps/tools/features/design-demo-admin.md

@@ -6,7 +6,7 @@ project: Tools
 client: shared
 type: feature
 status: active
-updated: 2026-07-24
+updated: 2026-07-30
 owners: [jcardinal]
 files:
   - tools/_/app/design/github.php
@@ -19,6 +19,7 @@ files:
   - tools/composer.json
 related:
   - ../architecture.md
+  - ../../../standards/frontend.md
   - ../features/persona-gated-navigation.md
   - ../features/saml-sso-auth.md
   - ../workflows/deploy-to-elastic-beanstalk-al2023.md
@@ -92,6 +93,29 @@ on the next write of that project.json. Tab management via a per-pill "⋯" menu
 - **Reorder** — a single-file `tabs.json` commit, validated as a **permutation** of the
   existing list.
 
+### Text-storage invariant: JSON holds plain text, escape once at display
+
+`tabs.json` tab names and `project.json` `title` values are stored as **plain text**. The
+single correct escape happens at display time in `assets/js/design.js` `esc()` (and in
+`buildStub()`, which `htmlspecialchars()` the title into the generated `index.html`).
+
+`App_Design_Github::decodeEntities()` (one pass of `html_entity_decode` with
+`ENT_QUOTES | UTF-8`) enforces that invariant at two chokepoints:
+
+- **On read out of storage** — `loadTabs()`, `normalizeTabs()` (including the legacy scalar
+  `tab`), and the project read's `title`.
+- **On names/titles read off a request** — `createTab()`, `renameTab()` (both old and new
+  name), `deleteTab()`, `reorderTabs()`, `filterKnownTabs()`, `createProject()`, and
+  `upload()` titles.
+
+Both sides are required: decoding only reads would make `renameTab()` compare a decoded
+`H&H` against a stored `H&H` and fail with *"No such tab."*; decoding only writes would
+leave already-bad stored data permanently double-escaped on screen.
+
+**Self-healing:** every tab write rewrites `tabs.json` and each affected `project.json` in
+full, so pre-encoded stored values are re-persisted as plain text on the next
+rename/delete/reorder. No manual repair of the `forward` repo is needed.
+
 ### Actions & UX
 
 - **Publish a version** — uploads a self-contained HTML export as the next `vN/index.html`,
@@ -147,10 +171,27 @@ None — internal/shared design-team tool.
   `curl_close()` calls. Audit ported code for other deprecated-in-8.x calls.
 - **Contents API inlines only ≤1 MB** — read exports with the raw media type (see above).
 - **Publishing pushes to `forward`'s `_main`** and triggers EB auto-deploy; no staging.
+- **Double-escaped names (`H&H` shown literally, rename fails with "No such tab.")** —
+  caused by values that arrived **already HTML-encoded** and were then correctly escaped once
+  more at display. The render path was never wrong; no current code path produces the
+  encoding (`createTab`/`createProject` and the JS transport `window.prompt` →
+  `URLSearchParams` → `$postField` trim/`mb_substr` are clean), so encoded values entered from
+  outside — a paste from rendered HTML, or a pre-fix build. Fixed defensively with
+  `decodeEntities()` on both the read and request sides (see above). Generated project stubs
+  were affected identically, because `buildStub()`'s single correct `htmlspecialchars()` was a
+  *second* escape on a pre-encoded title; storing titles plain fixes the stubs too.
 - Never hardcode the token in tracked source — a leaked `ghp_`/PAT must be rotated.
 
 ## Change history
 
+- 2026-07-30 — Fixed HTML-entity double-escaping of tab names and project titles (a tab named
+  `H&H` rendered as `H&H`, and renaming it failed with "No such tab."). Added
+  `App_Design_Github::decodeEntities()` and applied it on every read out of storage
+  (`loadTabs`, `normalizeTabs` incl. legacy scalar `tab`, project `title`) and on every
+  name/title read off a request (`createTab`, `renameTab`, `deleteTab`, `reorderTabs`,
+  `filterKnownTabs`, `createProject`, `upload`), so all comparisons are decoded-vs-decoded and
+  storage re-persists plain text. Defensive — no current code path produced the encoding.
+  Verified by the developer; not yet committed to `tools`. (jcardinal)
 - 2026-07-24 — Moved the Design Demo Admin from `forward` into the SSO-protected `tools` app
   (`App_Design_Github` + `/design` MVC route + namespaced assets + nav entry); still commits
   to `agilantsolutions/forward` `_main` and demos stay hosted at `demo.togatech.com`. Added

package/knowledge/1.0/standards/frontend.md

@@ -0,0 +1,75 @@
+---
+title: Front-End Standards
+framework: "1.0"
+project: Library
+client: shared
+type: standard
+status: active
+updated: 2026-07-30
+owners: [jcardinal]
+files: []
+related:
+  - ./backend-php.md
+  - ./framework-rules.md
+  - ../apps/tools/features/design-demo-admin.md
+  - ../apps/tools/features/talos-kb-documents-admin.md
+---
+
+# Front-End Standards (1.0 Legacy — `Browser_` / server-rendered UI)
+
+> **Scope.** Server-rendered UI and browser assets for the legacy **1.0** framework
+> (`Browser_` classes, `mvc/` get/post handlers, `assets/js`, `assets/css`). 1.0 is in
+> maintenance mode and historically inconsistent — match the file you are editing, and
+> prefer the cleaner pattern for new code. Do not retrofit 2.0 front-end conventions.
+
+## Output escaping: storage holds plain text, escape exactly once at display
+
+**Rule.** Persisted values — database columns, JSON manifests, config — hold **plain,
+unescaped text**. HTML escaping happens **exactly once**, at the moment the value is
+written into an HTML context (`htmlspecialchars($v, ENT_QUOTES, 'UTF-8')` server-side, or
+the view's `esc()` helper client-side).
+
+**Never** escape on the way *in* to storage. An escaped value in storage is a latent bug:
+the display layer escapes it a second time, and the user sees `H&H` instead of `H&H`.
+
+### Why it recurs
+
+The failure mode is a **round trip**, not a bad escape function:
+
+1. A value is rendered into an edit form / prompt already escaped for HTML.
+2. The user submits that form unchanged.
+3. The escaped string is stored verbatim — storage now holds `H&H`.
+4. Display escapes correctly once more → `H&H` on screen.
+
+Each round trip adds a level. Equality comparisons then fail too, because a freshly typed
+`H&H` no longer matches the stored `H&H` — which surfaces as a confusing
+"record not found" rather than as a display bug.
+
+### Required practice
+
+- Pre-fill form inputs and JS prompts with the **plain** value; let the templating layer
+  do the one escape it owns.
+- When a store may already contain encoded data, **decode on both sides** of the boundary:
+  a single `html_entity_decode($v, ENT_QUOTES, 'UTF-8')` on every read out of storage
+  **and** on every value read off a request. Decoding only one side leaves either broken
+  comparisons or undisplayable legacy rows.
+- Prefer stores that **rewrite records in full** on update, so the decode-on-write is
+  self-healing and no manual data repair is needed.
+- Escape for the **right context**: `htmlspecialchars` for HTML text/attributes,
+  `json_encode` (with `JSON_HEX_*` for inline `<script>`) for JavaScript. Never
+  hand-build JSON or rely on `htmlspecialchars` inside a JS context.
+
+### Precedents in the codebase
+
+- `tools/mvc/talos/vocabulary/post.php:74-80` — inline comment recording the rule after
+  form inputs pre-filled with `htmlspecialchars()` output accumulated encoding.
+- `tools/_/app/design/github.php` — `App_Design_Github::decodeEntities()` applied to tab
+  names and project titles on both the storage-read and request-read sides.
+
+## Change history
+
+- 2026-07-30 — Created. Establishes the escape-once/plain-text-storage invariant after a
+  second independent occurrence in `tools` (Design Demo Admin, following the Talos
+  vocabulary tool). (jcardinal)
+</content>
+</invoke>

package/knowledge/2.0/apps/_underscore/architecture.md

@@ -194,6 +194,23 @@ All non-production environments are **all-in-one**: a single cluster per environ
 holds `Core`, `Client_<Tenant>`, `Archive_<Tenant>`, and `Logs_<Tenant>` together
 (no family split). Region/reader routing still applies per cluster.
 
+> **⚠ Consequence — never write a query that spans two database families.** Because
+> production splits the families across the four dedicated clusters above, a single SQL
+> statement that joins or sub-selects across them (e.g. `Client_Towfoundation` ↔ `Core`,
+> or `Client_<Tenant>` ↔ `Archive_<Tenant>`) **cannot resolve in production** — the foreign
+> schema is not on that server. And because **every non-production environment is all-in-one,
+> such a query runs perfectly in local/dev/QA/stage**, so the failure surfaces only after
+> release. Treat a successful non-prod run as **no evidence** that a query is cluster-safe.
+> Cross-family data must be assembled in **PHP across two connections** (`_Database` named
+> connections, one per family), never in one statement. Note the corollary that platform
+> databases `Core`, `Forecast`, and `Team` **do** share `prod-core`, so those are same-cluster
+> — but a cross-*database* query is still discouraged, and in `dbchanges2` it is forbidden
+> outright.
+>
+> For **`dbchanges2` migrations this is a hard, mechanically-enforced rule**: a `.sql` file may
+> only reference tables in the one database its folder targets. See
+> [dbchanges2 → Database isolation](../dbchanges2/architecture.md).
+
 | Environment (aliases) | Host |
 |---|---|
 | `dev-sandbox` / `sandbox-dev` / developer sandbox | `dev.sandbox.database.togahub.com` |

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)