toga-ai 1.0.286 → 1.0.288

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

@@ -3,6 +3,8 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [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) | > **Status:** First iteration (for Alex's review). | 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 — Next.js UI + Config-Driven Campaign Content](features/web-funnel-content-model.md) | The **public-facing web funnel** is the new UI / lead-capture front door of the **same AI-BDR product** documented in `../architecture.md`. | bdr/src/content/schema.ts, bdr/src/content/hubspotProvider.ts, bdr/src/content/useCampaign.ts, bdr/src/content/default.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 |
 | [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/architecture.md

@@ -6,8 +6,8 @@ project: AI-BDR
 client: shared
 type: architecture
 status: active
-updated: 2026-06-16
-owners: [akhokhani]
+updated: 2026-07-08
+owners: [akhokhani, tcox]
 files:
   - ai-bdr/README.md
   - ai-bdr/requirements.txt
@@ -30,6 +30,7 @@ files:
 related:
   - features/vapi-integration.md
   - features/call-orchestration.md
+  - features/web-funnel-content-model.md
   - workflows/new-campaign-onboarding.md
 ---
 
@@ -175,6 +176,19 @@ authored here, then pushed to Vapi by `scripts/update_system_prompt.py`.
 - **No Langfuse / OTEL** — there is no TOGA-side LLM call to trace; the
   LLM call happens inside Vapi.
 
+## Public web funnel (UI / lead-capture front door)
+
+The AI-BDR product now has a **public-facing web funnel** — a **Next.js (App Router)**
+app in its own code repo, **`bdr`** — as its UI and lead-capture front door. It **reuses
+this system's existing calls** (HubSpot contact fetch, Toga upsert + campaign link,
+`requestCall` callback — see *End-to-end call flow* and `features/call-orchestration.md`),
+ported from the external `info` repo behind `LeadSink` / `CallbackService` adapters so all
+secret-bearing calls stay server-side. On top of that reuse it adds a **HubSpot-owned,
+config-driven campaign content layer**: marketing authors campaign content in HubSpot,
+fetched by slug at runtime and mapped to a serializable `CampaignBundle` (config-driven
+components, `DEFAULT` fallback — no `if(campaign===x)`; a copy change ships with no
+redeploy). Full detail: **`features/web-funnel-content-model.md`**.
+
 ## Key decisions
 
 - **Single shared structured-output schema** across all assistants — keeps
@@ -195,3 +209,7 @@ authored here, then pushed to Vapi by `scripts/update_system_prompt.py`.
 
 ## Change history
 - 2026-06-16 — Initial architecture doc for AI-BDR. (akhokhani)
+- 2026-07-08 — Additive: recorded the public Next.js web funnel (code repo `bdr`) as the
+  product's UI / lead-capture front door — reuses this system's existing HubSpot/Toga/callback
+  calls and adds a HubSpot-owned, config-driven campaign content layer. See
+  `features/web-funnel-content-model.md`. (tcox)

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

@@ -0,0 +1,533 @@
+---
+title: "BDR Web Funnel — Full Implementation Plan"
+framework: "2.0"
+repo: ai-bdr
+project: "AI-BDR"
+client: shared
+type: feature
+status: draft
+updated: 2026-07-08
+owners: [tcox]
+files:
+  - bdr/PLAN.md
+  - bdr/mockup/app.jsx
+  - bdr/mockup/screens.jsx
+  - bdr/mockup/components.jsx
+related:
+  - architecture.md
+  - web-funnel-content-model.md
+---
+
+# BDR: Multi-Campaign "AI BDR / Agent Studio" Web App — Implementation Plan
+
+> **Status:** First iteration (for Alex's review). Draft, pending sign-off on the open questions
+> in §9 and final campaign direction / verbiage from leadership.
+> **Author:** tcox · **Stack:** TOGA 2.0 front-end · Next.js (App Router) · **Client scope:** shared / internal (TOGA)
+> **Repo (new):** `bdr` · **Two source inputs:** the **mockup** (real UI) + **`info`** (backend to reuse).
+>
+> Product-copy rules the built site must follow (from the mockup's `CLAUDE.md`): **no em dashes** in any
+> shipped string; **one accent source** drives every accent. (This internal planning doc itself uses em
+> dashes for readability; the rule governs what the site ships, not this file.)
+
+---
+
+## 0. Provenance & required inputs
+
+This plan comes from the **AI BDR Development Handoff** meeting plus a full read of two codebases.
+`bdr` is the new public **UI / lead-capture front door of TOGA's existing AI-BDR product** (that
+product's backend is documented at `2.0/apps/ai-bdr/`) — only the UI is new. It is an **entirely new
+code repo**, built by combining:
+
+1. **The mockup (the real target UI)** in the `bdr` repo's `mockup/` folder — a finished, high-fidelity
+   prototype of an "AI BDR / Agent Studio" single-page flow. This is the pixel-perfect blueprint.
+   - Source of truth: `app.jsx` (shell/routing/state), `screens.jsx` (the screens), `components.jsx`
+     (shared component + data library), `styles.css` (~97 KB of styling), `CLAUDE.md` (copy rules).
+   - Prototype tech: React 18 via UMD + in-browser Babel (no build step). Assets under
+     `media/ uploads/ agents/ voices/ screens/`. There is also a 14.5 MB single-file
+     `AI BDR (standalone).html` export (do not hand-edit; it is a build artifact).
+2. **`info`** — the external `info` repo (github.com/agilantsolutions/info) — a Next.js app whose `/bdr`
+   route already implements the **production backend calls we will reuse**: HubSpot contact fetch, Toga
+   contact upsert + campaign linking, and callback (call-now / call-later) requests. (BDR is **also
+   Next.js**, so we reuse `info`'s framework patterns and its server-side call logic directly; see §5.6.)
+   This is where the real integrations live; its marketing UI is a *different, older* funnel we are
+   **not** copying.
+
+**Attach when handing this plan to Claude for execution:** this file, the meeting transcript, the
+mockup folder, and the `info` repo.
+
+**Still pending (does not block the build):** final campaign direction and copy from leadership.
+
+---
+
+## 1. Goal & done-condition
+
+**Goal:** Rebuild the mockup's Agent Studio flow as a production **Next.js app** (App Router +
+TypeScript, matching `info`). Next.js is the chosen framework because the site is **highly public**,
+so server-side rendering + SEO matter, and its server (server components + route handlers) is where
+the secret-bearing HubSpot/Toga/content calls run natively (§5.6). Every campaign is defined by
+content authored in HubSpot, so a new campaign launches with **no code changes**, multiple campaigns
+run side by side, and the real HubSpot / Toga / callback backend from `info` is reused directly.
+
+**Done when:**
+1. The full flow (Welcome, Build, Capabilities, Call Now, Schedule, Success) renders in Next.js
+   with visual parity to the mockup (pixel-perfect pass against the mockup screens).
+2. Two distinct campaigns (for example a generic **BDR-as-a-service** and a **healthcare** variant),
+   **each authored in HubSpot**, render differing only in data (copy, Q&A proof points, agent identity,
+   accent), with zero component-code differences. Adding a campaign requires **only HubSpot edits** (no
+   code, no redeploy).
+3. No user-facing string is hardcoded in a component (grep-verified); all copy comes from the HubSpot
+   campaign content, fetched by slug at runtime and resolved through one hook.
+4. The simulated call/schedule actions are wired to the **real backend** (Toga `requestCall`,
+   HubSpot/Toga contact upsert) behind a `CallbackService` / `LeadSink` adapter ported from `info`.
+5. Campaign content is fetched from **HubSpot at runtime** via the backend, behind the
+   `CampaignContentProvider` seam (§5.2), so marketing edits copy without a developer or a deploy.
+6. Copy honors the mockup rules: no em dashes; a single `--accent` source drives all accents.
+7. No PII in logs; the `info` debug logging is not carried over.
+8. Deploys (AWS Amplify) with documented env vars.
+
+---
+
+## 2. What the mockup actually is (the real UI to rebuild)
+
+### 2.1 Screen / state map
+The shell (`app.jsx`) is a screen router with a 3-step rail (Create · Abilities · Connect) plus
+modals. Default flow in **bold**; parked screens are reachable only via hidden dev triggers today.
+
+| Screen (`screen` key) | Step | Role | Notes |
+|---|---|---|---|
+| `landing` | (rail hidden) | Service selection ("AI BDR" featured + "Talos" coming soon) | Parked; reached via a hidden corner door. |
+| `creator` | 0 Create | Manual agent builder (form tabs, 9-slot grid, live preview, name, color, voice) | **Parked / dev-only** ("Build it myself" is "coming soon"). |
+| **`building`** | 0 Create | **AutoBuild**: theatrical assembly, always lands on Alex / Human / Cobalt | ~5.5 s, then advances to capabilities. |
+| **`capabilities`** | 1 Abilities | **"Meet your agent"**: avatar, 3 skill cards, Q&A pill bank, CTAs | The content-heavy screen. |
+| **`call`** | 2 Connect | **Call Now**: agent recap + phone entry | Submits phone. |
+| **`schedule`** | 2 Connect | **Schedule**: calendar + 30-min slots + phone | 24/7, 12-month window. |
+| **`calling`** | 2 Connect | **Success (calling)**: connecting → connected → ended + call summary + share | Currently a timed simulation. |
+| **`scheduled`** | 2 Connect | **Success (scheduled)**: confirmation | Calendar-invite copy. |
+
+**Modals (`app.jsx`):** `Welcome` (first load: "Meet the rep who never sleeps.", primary
+"Build my agent for me"), `WelcomeStep2` (how-it-works, 3 tiles, shown once on first reaching
+capabilities), `EarlyAccess` ("Build it myself" / customization, coming-soon, with walkthrough video).
+
+**Default happy path:** `Welcome → (Build my agent) → building → capabilities → call | schedule → calling | scheduled`.
+
+### 2.2 Agent identity model (core state)
+`state = { form, sel, color, voice, voiceGender, name }`:
+- **form**: `Human | Owl | Robot`; **sel**: chosen slot index per form (0..8, 9 slots each).
+- **color**: one of 5 TOGA accents (`#FF6AB0` Fuchsia, `#CF9AFF` Lilac, `#4571DD` Cobalt,
+  `#FFA071` Peach, `#A2AAE1` Indigo); drives the global `--accent` (+ derived `--accent-fill`).
+- **voice**: `voiceGender` (Female/Male) + index into `VOICE_GROUPS`.
+- **name**: free text, falls back to a per-form sample name (`AGENT_NAMES`, for example Human ->
+  Maya/Alex/Zoe...). Default auto-build result is **Alex** (Human slot 1, Cobalt, Female voice 0).
+- Persisted to `localStorage` (`aibdr.v2`); only voice survives a refresh, flow restarts at Welcome.
+
+> Design implication: in the default flow the user does **not** pick the agent (the builder is
+> parked); AutoBuild fixes it to Alex/Cobalt. So **agent identity is effectively campaign config**
+> today (which art, accent, voice, name a campaign presents). See §6.
+
+### 2.3 Shared component + data library (`components.jsx`)
+Reusable pieces to port (heavy reuse is exactly why "build one screen cleanly, the rest are fast"):
+- **Structural/UI:** `Wordmark`, `StepRail`, `BackBtn`, `SynapseButton`, `CtlHead`, `IqMark`, `Ico`
+  (full inline SVG icon set), `Silhouette`.
+- **Agent visuals:** `AgentArt` / `SmoothImg` / `agentArt` + `AGENT_ART`, `TalkingPreview` +
+  `AGENT_TALK` (per-form talking video), `AgentSlot`, `ColorSelector` + `AGENT_COLORS`,
+  `VoiceDial` + `VOICE_GROUPS` + `VoiceAudio` + `voiceName`, `AGENT_NAMES` + `sampleName`.
+- **Motion/system:** `SwapFade` (the one page/tab transition), `Particles` (ambient motes),
+  plus app-level cursor-hover tracking and scroll-state tinting (in `app.jsx`).
+- **Asset resolution:** `ASSET(path)` maps a logical path to `window.__resources` (embedded assets
+  in the standalone export) or to a real URL. `preloadAgentAssets(form, sel)` warms art + video.
+- **Dev tuning:** `TweaksPanel` / `TweakSection` / `TweakColor` / `TweakSlider` (synapse glow,
+  radius). Likely dev-only; decide whether to keep in production (§9).
+
+### 2.4 Content inventory (everything that must become campaign config)
+This is the "verbiage" the meeting wants swappable. Current hardcoded copy lives in these surfaces:
+- **Welcome / WelcomeStep2 / EarlyAccess** (headlines, value bullets, how-it-works tiles, CTA labels).
+- **Landing** (headline, lede, the two service tiles).
+- **Capabilities**: `CAPS` (3 skill cards), `Q_ANCHOR` + `Q_POOL` (anchor + a 10-entry Q&A pool, 11
+  total) and `Q_SETS` (rotation A/B/C), lede, CTA labels, "avg connect time" line.
+- **Call Now / Schedule**: prompts, phone-field labels, privacy footnotes, durations.
+- **Success**: `CALL_SUMMARIES` (short/medium/large recaps), status strings, calendar-invite copy,
+  `AmbientQuestions` (reuses the Q pool).
+- **AutoBuild**: build-step labels ("Selecting your rep / Tuning the voice / Setting the style").
+
+> Note: the `Q_POOL` answers already contain **healthcare/pharma proof points** ("cut inventory
+> costs 32%", "recovered $167K in 90 days", "response times dropped 44%") alongside generic BDR
+> answers. This is direct evidence that campaign copy (BDR-as-a-service vs. healthcare) must be
+> bundle-swappable, and gives us real content for the two example bundles in the done-condition.
+
+---
+
+## 3. What `info` provides (backend to reuse, not its UI)
+**Many of the API calls the new BDR needs already exist and work in `info` — reuse them, do not
+rebuild.** The `info/bdr` route is a live implementation of the lead + callback backend; port these
+modules into `bdr` (behind the §5.6 adapters, minus the debug logging) rather than writing them from
+scratch. From the external `info` repo's `src` folder:
+- **HubSpot** (`lib/hubspot.ts`): `getContact(hsContactId)`, env `HUBSPOT_ACCESS_TOKEN`.
+- **Toga / api2** (`lib/toga.ts`, envelope `{isSuccess,status,error,messages,data}`):
+  cached-token auth; `upsertContactByEmail` (find/create/update) + `addContactToCampaign`;
+  `requestCall(uuid, dtNextContactRequested, phone, IMMEDIATE|SCHEDULED)` which drives the actual
+  voice callback; `CONTACT_CALL_TYPE_UUID` immediate/scheduled; CST datetime formatting.
+  Env: `TOGA_API_BASE_URL`, `TOGA_CLIENT_ID`, `TOGA_CLIENT_API_UUID`, `TOGA_CLIENT_API_SECRET`.
+- **Entry params**: `?hsContactId=…&hsCampaignId=…` (a server component prefetches the contact +
+  upserts on request; BDR keeps this same Next.js server-component pattern).
+- **API routes**: `call-now`, `call-later`, `contact` (and a `visit` 501 stub).
+- **GA4** (`lib/analytics.ts`): typed `EventMap`, env `NEXT_PUBLIC_GA_MEASUREMENT_ID`.
+- **Do not port**: the extensive debug `console.log`s (several log PII: email/phone), and `info`'s
+  hero/curiosity marketing UI.
+
+**Reconciliation:** the mockup's Call Now / Schedule screens are the front-end; `info`'s
+`requestCall` / upsert are the backend those screens should call (replacing the mockup's timed
+simulation in `Success`). The mockup already models immediate vs. scheduled, matching
+`CONTACT_CALL_TYPE_UUID`.
+
+**How `info` uses "campaign" (verified by reading the source):** it is **attribution-only**. HubSpot is
+used solely to fetch the *contact* (`getContact(hsContactId)`); the `hsCampaignId` from the URL is
+passed to **Toga** as a campaign UUID (`addContactToCampaign` → `POST /campaigns-contacts`), linking
+the contact to a campaign on the Toga/api2 side. **`info` does not fetch any marketing content from
+HubSpot** — its copy is hardcoded. So we reuse `info`'s contact fetch + Toga campaign-link + callback,
+but **fetching campaign *content* by slug from HubSpot is net-new** (no `info` pattern to copy; see
+§9.10). Note the slug (content key) and the campaign UUID (attribution key) are related but distinct;
+the bundle carries the UUID so a slug maps to the right campaign for logging.
+
+---
+
+## 4. Decisions locked at kickoff
+| Decision | Choice | Consequence |
+|---|---|---|
+| Repo name | **`bdr`** | New greenfield repo. Not yet in the TOGA registry. |
+| Framework | **Next.js (App Router) + TypeScript** | Chosen because the site is highly public: SSR + SEO, and a built-in server for the secret-bearing HubSpot/Toga/content calls. Matches `info`, so its patterns port directly. |
+| UI source | **The mockup** | Rebuild its Agent Studio flow faithfully (pixel-perfect). The mockup is React, so components port cleanly into Next.js client components. |
+| Backend source | **`info`** | Reuse HubSpot/Toga/callback logic directly (same framework). |
+| Content model | **Runtime, HubSpot-owned** | Campaign content is authored by the **marketing team in HubSpot** and fetched **by slug at runtime** via the backend. **No campaign content in the repo; no developer or redeploy to change copy.** (Supersedes the earlier "static bundles now" idea.) See §5.2 / §5.5. |
+| Backend relationship | **Same product; reuses the AI-BDR backend** | This funnel is the new UI / front door of TOGA's existing **AI-BDR** product; it reuses that system's HubSpot/Toga/callback calls (documented at `2.0/apps/ai-bdr/`). Lead/callback handoff still goes behind `LeadSink`/`CallbackService` adapters for a clean seam. |
+| Campaign entry | **Plan recommends** | See §5.5. |
+| Copy rules | **No em dashes; one accent source** | Accent enforced in code. No-em-dash cannot be linted on HubSpot-authored copy: enforce via author guidance + a normalization pass in the backend mapping. |
+| Client | Shared / internal | No per-client theming/entitlement logic. |
+
+---
+
+## 5. Target architecture
+
+### 5.1 Prototype → production porting strategy
+The mockup is already **React** (React 18 via UMD + in-browser Babel, no build step). Production is a
+**Next.js (App Router) + TypeScript** app, matching `info` (note `info/AGENTS.md`: Next has breaking
+changes vs. older versions; read the bundled docs in `node_modules/next/dist/docs/` before coding).
+Port approach:
+- Move `styles.css` in as the base stylesheet (Tailwind optional; the mockup is hand-authored CSS
+  with CSS variables, so keep it and layer Tailwind only if desired). Preserve the CSS-variable
+  accent system verbatim.
+- Convert each `components.jsx` / `screens.jsx` unit into a real module. The interactive Agent Studio
+  screens are **client components** (`"use client"`, they use state/effects/animation); the top-level
+  page is a **server component** that resolves the campaign + primes the lead server-side, then hands
+  data to the client flow. Replace UMD globals / `window.*` with imports. Keep `SwapFade` / `Particles`.
+- Replace `ASSET`/`window.__resources` with the Next asset pipeline (files in `public/`, imported URLs).
+  Migrate agent art / talking videos / walkthrough video / particles.
+- Replace `localStorage` boot logic with the same behavior in a client provider/hook.
+
+> **Server = built in (this is why Next.js helps here).** `info`'s HubSpot/Toga calls use **secrets**
+> (`HUBSPOT_ACCESS_TOKEN`, `TOGA_CLIENT_API_SECRET`, ...) that must never ship to the browser. In
+> Next.js those calls live in **server components + route handlers**, so there is no separate backend
+> or service to stand up. Keep secret-bearing code out of client components and never expose it via
+> `NEXT_PUBLIC_` env.
+
+### 5.2 Content provider — HubSpot is the source of truth
+**Campaign content lives in HubSpot, authored by marketing, and is fetched by slug at runtime.**
+It is **not** stored in the repo, and changing copy requires **no developer and no redeploy**. The
+provider is the seam that makes this true:
+```ts
+interface CampaignContentProvider {
+  resolve(slug: string | undefined): Promise<CampaignBundle>; // returns the safety-net fallback if unknown/unreachable
+  list?(): Promise<CampaignSummary[]>;
+}
+// Primary:  HubSpotContentProvider — runs server-side (in the page's server component / a route
+//           handler). Reads the campaign content from HubSpot (see §9.10 for the exact HubSpot
+//           mechanism), maps it to a CampaignBundle, and caches it. Secrets stay server-side.
+// Fallback: a minimal built-in DEFAULT bundle (engineering safety net only, NOT authored marketing
+//           copy) so the funnel still renders if a slug is unknown or HubSpot is briefly unreachable.
+```
+`resolve(slug)` runs on the server during render (SSR), so the HubSpot fetch + field mapping to the
+`CampaignBundle` shape (§6) happens before the page is sent, with Next caching / revalidation so
+marketing edits appear quickly without a deploy (and the public site stays SEO-friendly). The client
+components receive the resolved bundle as props / via `useCampaign()`; they never see HubSpot.
+
+> **Key sub-decision (open, §9.10):** *how* campaign content is represented in HubSpot. HubSpot's
+> "Campaigns" tool is built for attribution, not rich structured copy, so this depth of content
+> (headlines, a ~10-entry Q&A pool, agent identity, call summaries) needs a deliberate home. Likely
+> **HubDB** (a CMS-Hub table: one row per campaign, a `slug` column + content columns, API-fetchable)
+> or a **custom object**. This choice drives the fetch + the field mapping and needs confirmation with
+> whoever owns the HubSpot instance.
+
+### 5.3 Campaign as data, components as renderers
+Follow the TOGA config-driven precedents (`toga25-supply` `useClientFields`; `toga2-commerce` Cart
+C1..C7): resolve a bundle keyed by campaign, always with a `DEFAULT` fallback; render through the
+components; never branch `if (campaign === 'x')` in JSX. Non-serializable behavior (a CTA action,
+an icon) is referenced by an **enum key** hydrated via a `Record<key, fn|Component>` registry at the
+view-model layer, so bundles stay pure data (so HubSpot only ever stores plain strings/values).
+
+### 5.4 Flow state machine
+A `useAgentFlow(campaign)` hook owns `screen` + transitions (the `go()` / `back` map from `app.jsx`),
+the modal gates (`welcome`, `welcome2`, `earlyAccess`), and step derivation (`stepFor`). Screens are
+presentational and receive copy from the bundle + handlers from the hook. This mirrors the existing
+shell but makes the copy and agent identity injected rather than inlined.
+
+### 5.5 How the front end knows which campaign to display (URL-driven, slug-keyed)
+**Short answer: yes, it is URL-driven. Every campaign has a stable `slug`; the server reads the slug
+from the request URL and loads that campaign's data through the provider (at render time).** End to end:
+
+**1. Each campaign has a slug.** A short, stable identifier, for example `bdr-service`, `healthcare`.
+The slug is the key marketing's HubSpot campaign is looked up by. It lives **in HubSpot, not the
+repo** (§5.2); the repo only holds the type/schema, the HubSpot->bundle mapping, and a minimal
+safety-net `DEFAULT`.
+
+**2. The URL carries the slug.** Two supported shapes (both resolved by one `resolveCampaignId()`):
+- **Query param (recommended to ship first):** `bdr.togatech.com/?campaign=bdr-service`. Matches how
+  leads actually arrive: HubSpot outreach links are query-based, and `info` already reads a
+  `?hsCampaignId=` param, so this slots into existing outreach with no new infrastructure.
+- **Path (add later, optional):** `bdr.togatech.com/c/bdr-service`. Cleaner shareable URLs; added via
+  the client router without touching components once the query path exists.
+
+**3. Resolution order** (first match wins): explicit `?campaign=<slug>` -> mapped `?hsCampaignId=<id>`
+(id -> slug lookup, so CRM links keep working) -> `DEFAULT`. An unknown or missing slug always falls
+back to the `DEFAULT` bundle, so the funnel never fails to render.
+
+**4. The slug drives a runtime fetch of the content from HubSpot** (this is the confirmed requirement):
+the page's server component calls `provider.resolve(slug)`, which reads that campaign's content from
+**HubSpot** (§9.10), maps it to a `CampaignBundle`, and caches it (Next revalidation). Because this is
+server-side, the fully-populated page is rendered and sent (good for the public site's SEO). Marketing
+edits in HubSpot show up on the next revalidation. **No repo content, no redeploy, no developer** to
+change copy. If the slug is unknown or HubSpot is briefly unreachable, the minimal `DEFAULT` safety net
+renders so the funnel never breaks.
+
+**5. Multiple campaigns run simultaneously by construction.** Selection is per-visitor, derived from
+their URL each load; there is no global "current campaign" state. Any number of campaigns are live at
+once, each just a different slug.
+
+**6. CRM/analytics linkage travels in the bundle.** The resolved bundle carries `hsCampaignId` /
+`togaCampaignUuid`, used when the lead is upserted/linked (§5.6) and for per-campaign GA4, so every
+lead and event is attributed to the right campaign.
+
+**Recommendation:** ship **query-param entry + the HubSpot content provider** from the start (that is
+the confirmed requirement); add **path-based routing** as a nicety later. Keep all of this behind
+`resolveCampaignId()` + `useCampaign()` so none of it is visible to the screens. The one thing that
+must be pinned down before Phase 1 is **how the content is modeled in HubSpot** (§9.10).
+
+### 5.6 Backend adapters (run in the Next.js server)
+The client screens call two interfaces; both run **server-side** (in route handlers / server actions),
+so secrets never reach the browser:
+```ts
+interface LeadSink        { upsertLead(input): Promise<LeadRef>; }              // today: Toga upsert + HubSpot
+interface CallbackService { requestCall(ref, whenOrNow, phone): Promise<void>; } // today: Toga requestCall
+```
+Because BDR is Next.js, these live in the app's own server layer (route handlers such as
+`app/api/call-now/route.ts`, mirroring `info`), so **there is no separate backend to host**.
+Implementation is `info`'s existing logic (`lib/toga.ts`,
+`lib/hubspot.ts`, and its `call-now` / `call-later` route handlers): it **already exists and works**,
+we port it directly, minus the PII logging. The mockup's `Success` simulation is replaced by a real
+`CallbackService` call (immediate vs. scheduled maps to `CONTACT_CALL_TYPE_UUID`).
+
+This funnel is the front door of the existing **AI-BDR** product, so `CallbackService` is implemented
+with that system's callback path (the `info`-ported Toga `requestCall`). The adapter seam keeps the
+client and interfaces stable if that backend path changes.
+
+### 5.7 `togatech` website integration (eventual)
+The site will ultimately be surfaced through the TOGA Technology website (`togatech` repo). Design for
+it now: keep the funnel self-contained and embeddable, prefer a linkable per-campaign URL so
+`togatech` CTAs deep-link into a campaign, and express shared branding as tokens. Integration
+mechanism (subdomain / linked Amplify app vs. iframe vs. absorption into `togatech`) is an open
+question (§9), needed before deploy, not before building.
+
+### 5.8 Asset pipeline
+Migrate agent art (Human/Owl/Robot × up-to-9 slots), talking videos, the customization walkthrough
+video, and particle/Lottie assets into `public/`. Keep `preloadAgentAssets` behavior so screen swaps
+never blank. Prune unused slots per the campaigns actually shipped (the default flow uses one agent).
+
+---
+
+## 6. Campaign bundle schema (concrete sketch)
+This is the shape the app consumes. It is **produced server-side by mapping the HubSpot campaign
+content (§5.2) into this structure** — it is the contract between "how marketing's content is stored
+in HubSpot" and "what the components render," and the mapping layer is where HubSpot fields become
+these fields (and where the no-em-dash normalization runs). Serializable data only; behavior/icons by
+key. Covers the real content surfaces from §2.4.
+
+> The richer fields here (the nested `pool: QA[]` + `sets`, `callSummaries`, `RichLine` accent spans)
+> are the parts hardest to represent in a marketing-friendly way in HubSpot — a direct input to the
+> §9.10 modeling decision. Flat columns handle the simple strings; nested arrays likely need child
+> rows or a structured (JSON) field.
+```ts
+interface AgentIdentity {
+  form: "Human" | "Owl" | "Robot";
+  slot: number;                 // 0..8
+  accent: string;               // one of the 5 TOGA accents -> --accent
+  voiceGender: "Female" | "Male";
+  voiceIndex: number;
+  name: string;                 // e.g. "Alex"
+}
+
+interface QA { id: string; q: [string, string, string]; a: string; } // a: first-person, no em dashes
+
+interface CampaignBundle {
+  id: string;                   // slug
+  hsCampaignId?: string;        // HubSpot linkage
+  togaCampaignUuid?: string;    // Toga addContactToCampaign linkage
+  agent: AgentIdentity;         // who the campaign presents (default flow does not let user pick)
+  welcome:   { eyebrow: string; heading: string; body: string; values: string[]; primaryCta: string; };
+  landing?:  { heading: RichLine; lede: string; tiles: ServiceTile[]; };   // if the service picker is used
+  capabilities: {
+    step2Intro: { heading: string; body: string; values: string[]; tiles: HowTile[]; };
+    heading: RichLine; lede: string;
+    skills: { icon: string; title: string; desc: string }[];               // CAPS
+    anchor: QA; pool: QA[]; sets: string[][];                              // Q&A bank + rotation
+    ctas: { callNow: string; schedule: string; connectNote: string; };
+  };
+  call:     { heading: string; body: string; footnote: string; };
+  schedule: { heading: string; footnote: string; durationLabel: string; };
+  success:  { callSummaries: { key: string[]; next: string[] }[]; scheduledNote: string; };
+  build?:   { steps: { label: string; value?: string }[]; };              // AutoBuild beats
+  analytics?: { measurementId?: string; eventPrefix?: string };
+  features?: string[];          // capability flags (e.g. "showServicePicker", "allowManualBuilder")
+}
+```
+`RichLine` supports the mockup's accent-inked span (for example `"<agent> is ready to work."`).
+The provider must always return a valid bundle: on an unknown slug or a HubSpot hiccup it falls back
+to a minimal built-in `DEFAULT` (a safety net, not authored marketing copy) so the funnel still renders.
+
+---
+
+## 7. Proposed repo structure (Next.js App Router + TypeScript)
+```
+bdr/
+  src/
+    app/
+      layout.tsx  globals.css              # shell + ported styles.css / CSS variables
+      page.tsx                             # SERVER component: resolve slug -> campaign, prime lead, render flow
+      c/[slug]/page.tsx                    # optional path-based campaign entry (later)
+      api/{lead,call-now,call-later}/route.ts   # SERVER: secret-bearing Toga/HubSpot calls (ported from info)
+    content/
+      schema.ts                            # CampaignBundle types (the contract)
+      hubspotProvider.ts                   # SERVER: reads campaign content from HubSpot + maps to bundle (§5.2/§6)
+      useCampaign.ts                       # client hook to read the resolved bundle
+      default.ts                           # minimal safety-net fallback ONLY (not authored copy)
+      # NOTE: no per-campaign content files here — campaign copy lives in HubSpot, not the repo
+    flow/
+      useAgentFlow.ts                      # screen state machine + modal gates + step rail (client)
+      screens/{Landing,AutoBuild,Capabilities,CallNow,Schedule,Success}.tsx   # "use client"
+      modals/{Welcome,WelcomeStep2,EarlyAccess}.tsx
+    components/                            # ported shared lib (SwapFade, Particles, AgentArt, VoiceDial, ColorSelector, SynapseButton, StepRail, Wordmark, Ico, ...)
+    server/                                # secret-bearing modules, ported from info (PII logging removed)
+      toga.ts  hubspot.ts  leadSink.ts  callbackService.ts
+    lib/ analytics.ts assetPath.ts formatPhone.ts agentData.ts  # AGENT_ART/NAMES/COLORS/VOICES
+  public/                                  # migrated agent art, talking videos, walkthrough, particles
+  amplify.yml  next.config.ts  tsconfig.json  eslint (no-em-dash copy rule on in-repo strings)
+```
+
+---
+
+## 8. Phased execution plan
+Sizing note (from the meeting): once one screen is built cleanly the rest go fast (heavy component
+reuse); the long pole is pixel-perfect UI parity, not logic. We hand Claude the actual mockup source,
+so fidelity should be near-exact.
+
+- **Phase 0 — Bootstrap `bdr`.** New Next.js (App Router) + TypeScript app (mirror `info`'s config;
+  Amplify SSR hosting). Port `styles.css` and the CSS-variable accent system. Set up campaign routing
+  (query param now, `/c/[slug]` later) and ESLint incl. a no-em-dash check on in-repo strings. Read
+  `node_modules/next/dist/docs/` first (Next breaking changes per `info/AGENTS.md`).
+- **Phase 1 — Content layer.** Depends on the §9.10 HubSpot-modeling decision. Define `schema.ts`
+  (the `CampaignBundle` contract), the server-side `hubspotProvider` (`resolve(slug)` reads HubSpot +
+  maps to a bundle, with caching/revalidation + no-em-dash normalization), the `useCampaign` client
+  hook, and a minimal safety-net `DEFAULT`. Seed HubSpot with one real campaign (extract the mockup's
+  current copy into HubSpot, not the repo) to develop against. Unit-test mapping + fallback.
+- **Phase 2 — Port the component library.** Bring `components.jsx` across as real modules (SwapFade,
+  Particles, AgentArt + data, VoiceDial, ColorSelector, SynapseButton, StepRail, Wordmark, Ico,
+  asset/preload). Migrate assets to `public/`. This unblocks every screen.
+- **Phase 3 — Build one screen end to end (Capabilities), config-driven.** It is the richest
+  (skills + Q&A bank + CTAs), so building it first calibrates the real estimate and proves the bundle
+  schema before the remaining screens.
+- **Phase 4 — Remaining screens + modals from config.** AutoBuild, Landing (behind a feature flag),
+  Call Now, Schedule, Success, Welcome/WelcomeStep2/EarlyAccess, StepRail. Remove all hardcoded copy.
+- **Phase 5 — Wire the real backend.** Port `info`'s `lib/toga.ts` / `lib/hubspot.ts` + its call
+  route handlers into BDR's `app/api/*` (server-side); wire the `LeadSink` / `CallbackService`
+  adapters; replace the `Success` simulation with real immediate/scheduled `requestCall`; remove PII
+  logging; resolve the `visit` route (implement or drop).
+- **Phase 6 — Second campaign + multi-campaign.** Author a second campaign **in HubSpot** (for example
+  a `healthcare` variant using the healthcare proof points) alongside `bdr-service`; prove that adding a
+  campaign needs only HubSpot edits (no code, no deploy) and zero component diffs; validate slug
+  resolution and simultaneous campaigns.
+- **Phase 7 — Analytics + polish.** Per-campaign GA4, pixel-perfect pass vs. the mockup, motion/timing
+  parity, accessibility check.
+- **Phase 8 — Deploy.** Amplify env vars, README, "how to add a campaign" doc; confirm `togatech`
+  integration mechanism.
+
+---
+
+## 9. Open questions (leadership + HubSpot owner). Most do not block early work; **§9.10 gates Phase 1**.
+1. **Backend relationship:** RESOLVED — `bdr` is the new UI / front door of TOGA's existing **AI-BDR**
+   product (not standalone); it reuses that system's backend calls, and its knowledge is filed under
+   `2.0/apps/ai-bdr/`. `CallbackService` uses that system's callback path.
+2. **Runtime editability:** RESOLVED — content is authored by marketing **in HubSpot** and fetched by
+   slug at runtime; no repo content, no redeploy. The remaining question is the HubSpot mechanism (§9.10).
+3. **Agent choice:** Stay with a campaign-fixed agent (auto-build to a preset), or ship the manual
+   Creator (currently parked / "coming soon")? Determines whether `Creator` + full slot art ship now.
+4. **Service picker:** Is the `Landing` service-selection screen (AI BDR + "Talos coming soon") in
+   scope for launch, or parked like in the mockup?
+5. **Campaign catalog:** How many campaigns at launch and who authors copy? Confirms entry UX (§5.5).
+6. **`togatech` integration mechanism:** subdomain / linked Amplify app vs. iframe/embed vs. absorption
+   into `togatech`. Needed before Phase 8.
+7. **Tweaks panel:** keep the dev tuning panel (synapse/radius/accent) in production or strip it?
+8. **First campaign direction + verbiage** (BDR-as-a-service vs. healthcare): needed only to fill the
+   first bundle, not to build the engine.
+9. **Backend hosting:** RESOLVED by the Next.js choice — the secret-bearing HubSpot/Toga calls run in
+   BDR's own server components / route handlers; no separate backend to host. Only remaining item is
+   confirming the Amplify **SSR** hosting target (not static) at deploy.
+10. **HubSpot content mechanism (blocks Phase 1) — the big one.** *How* is campaign content stored in
+    HubSpot so it is marketing-editable and fetchable by slug? `info` gives no precedent (it only reads
+    contacts). Options: **HubDB** (CMS-Hub table, one row per campaign, `slug` column + content columns,
+    API-fetchable — the likely fit) vs. a **custom object** vs. properties on the Campaigns object. This
+    determines the fetch + the HubSpot->`CampaignBundle` mapping. Sub-parts to settle with the HubSpot
+    owner: which mechanism; how the **nested content** (Q&A pool + rotation sets, call summaries, accent
+    `RichLine`s) is represented (flat columns can't hold arrays cleanly — child rows or a JSON field);
+    who authors/owns the schema; and how the slug relates to the existing `hsCampaignId`/Toga campaign
+    UUID used for attribution.
+
+---
+
+## 10. Risks & gotchas
+- **Next breaking changes** (per `info/AGENTS.md`): read the bundled `node_modules/next/dist/docs/`
+  before coding; do not assume older-Next APIs.
+- **Keep secrets in server code.** `HUBSPOT_ACCESS_TOKEN` / `TOGA_CLIENT_API_SECRET` and the
+  token-exchange must live in server components / route handlers, never in a `"use client"` component
+  or a `NEXT_PUBLIC_` env var (those ship to the browser). The interactive screens are client
+  components, so the boundary matters: secret-bearing calls stay in `app/api/*` + server modules.
+- **No `2.0/standards/frontend.md`** exists; `toga2-view` conventions are the de-facto standard
+  (single axios/api client, `use*ViewModel` hooks, presentational views). Keep the viewmodel-vs-view
+  split in spirit.
+- **PII in logs** (existing `info` debt): log ids only, never email/phone/tokens.
+- **HubSpot as content store is net-new** (no `info` precedent). Biggest unknown is fitting the mockup's
+  rich, nested content (Q&A pool + sets, call summaries, accent `RichLine`s) into something marketing can
+  edit (§9.10). Flat strings are easy; nested arrays are the hard part.
+- **Runtime fetch = latency + availability**: the content now depends on a HubSpot call on load. Cache
+  in the backend with short revalidation, and keep the `DEFAULT` safety net so a HubSpot hiccup or an
+  unknown slug never breaks the funnel. Mind HubSpot API rate limits.
+- **Serializable content only**: the bundle stays pure data (no JSX/functions); behavior/icons are enum
+  keys hydrated in code, so HubSpot only ever needs to store strings/values.
+- **No-em-dash cannot be linted on HubSpot copy**: enforce via marketing author guidance + a
+  normalization pass in the backend mapping.
+- **DEFAULT must always render**: an unknown/absent slug (or HubSpot down) falls back cleanly, never a
+  404 funnel.
+- **Single accent source**: every accent-tinted element routes through `var(--accent)` /
+  `color-mix`; never hardcode an accent (mockup `CLAUDE.md` rule).
+- **Motion fidelity**: the mockup hardens transitions against stalled animation clocks (settle guards,
+  effect-owned timers). Preserve these when porting; do not "simplify" them away.
+- **Asset weight**: full slot art/video for 3 forms × 9 slots is large; ship only what the launched
+  campaigns use.
+
+## 11. Cleanup / fidelity checklist
+- [ ] No hardcoded marketing copy in any component (grep-verified).
+- [ ] No `if (campaign === …)` branches in components.
+- [ ] No em dashes in any shipped string; single `--accent` source respected.
+- [ ] `info` debug logging dropped; no PII in logs.
+- [ ] `visit` route resolved (implemented or removed).
+- [ ] Env vars documented; no secrets committed.
+- [ ] Pixel-perfect parity pass against the mockup screens + screenshots.
+
+## Change history
+- 2026-07-08 — Captured the full BDR web-funnel implementation plan verbatim into the knowledge repo as a companion to the distilled `web-funnel-content-model.md` feature doc (redundancy intentional). (tcox)

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

@@ -0,0 +1,148 @@
+---
+title: Web Funnel — Next.js UI + Config-Driven Campaign Content
+framework: "2.0"
+repo: ai-bdr
+project: AI-BDR
+client: shared
+type: feature
+status: draft
+updated: 2026-07-08
+owners: [tcox]
+files:
+  - bdr/src/content/schema.ts
+  - bdr/src/content/hubspotProvider.ts
+  - bdr/src/content/useCampaign.ts
+  - bdr/src/content/default.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
+related:
+  - ../architecture.md
+  - call-orchestration.md
+---
+
+## What this is
+
+The **public-facing web funnel** is the new UI / lead-capture front door of the **same
+AI-BDR product** documented in `../architecture.md`. It is a **Next.js (App Router) +
+TypeScript** app living in its own code repo, `bdr` (registered separately because it is a
+distinct codebase). Only the UI/content layer is new — the funnel **reuses this AI-BDR
+system's existing backend calls** (see "Backend reuse" below); the API/backend contracts
+are already documented and are **not** restated here.
+
+The UI is built pixel-perfect from the mockup at `BDR/mockup`: a **7-screen "Agent Studio"
+flow** — Welcome → AutoBuild → Capabilities → Call Now / Schedule → Success. The
+agent-identity model is **form × slot × accent × voice × name** (form Human/Owl/Robot ×
+slot 0–8 × one of 5 TOGA accents → `--accent` × voice × name). Two shipped-copy rules from
+the mockup are load-bearing: a **single `--accent` source** (every accent-tinted element
+routes through `var(--accent)` + derived `--accent-fill`; never hardcode an accent) and
+**no em dashes** in any shipped copy.
+
+Full implementation plan: `BDR/PLAN.md`.
+
+## Config-driven campaign content (HubSpot-owned, fetched by slug at runtime)
+
+Every campaign is a **serializable data bundle** (`CampaignBundle`) keyed by a stable
+`slug`. **Campaign content is authored by the marketing team in HubSpot** and fetched **by
+slug at runtime, server-side**, then mapped to a `CampaignBundle`. Content is **not** stored
+in the repo — a new campaign or a copy edit ships with **no developer and no redeploy**,
+only a HubSpot edit.
+
+Config-driven, per TOGA precedent (`toga25-supply`'s `useClientFields`,
+`toga2-commerce`'s Cart C1–C7): components are **pure renderers of a bundle**; there is
+**no `if (campaign === 'x')` branching** anywhere in the screens. The repo holds only the
+**schema** (`CampaignBundle` types), the **HubSpot→bundle mapping** (provider), and a
+minimal safety-net **`DEFAULT`** bundle (an engineering fallback, not authored copy).
+
+- **Provider seam.** `CampaignContentProvider.resolve(slug)` returns a `CampaignBundle` (or
+  `DEFAULT` on an unknown/unreachable slug). `HubSpotContentProvider` runs **server-side**
+  (page server component / route handler), maps HubSpot content to a `CampaignBundle`,
+  caches it (Next revalidation), and applies the no-em-dash normalization pass. Client
+  components receive the resolved bundle as props / via `useCampaign()` and never see
+  HubSpot.
+- **Serializable-only bundles.** Non-serializable behavior (a CTA action, an icon) is
+  referenced by an **enum key** and hydrated at the view-model layer through a
+  `Record<key, fn|Component>` registry — HubSpot only ever stores plain strings/values.
+- **Campaign selection is URL-driven, per-request.** `resolveCampaignId()`, first match
+  wins: `?campaign=<slug>` → mapped `?hsCampaignId=<id>` (id→slug lookup so existing
+  outreach/CRM links keep working) → `DEFAULT`. Query-param entry ships first (matches how
+  leads arrive and how the ported backend already reads `?hsCampaignId=`); optional
+  `/c/[slug]` path later. No global "current campaign" state — selection is derived from
+  each visitor's URL, so any number of campaigns run **simultaneously**.
+- **Attribution travels in the bundle.** The resolved bundle carries `hsCampaignId` and
+  `togaCampaignUuid`, used when the lead is upserted/linked and for per-campaign GA4.
+
+### CampaignBundle shape (contract)
+
+Keyed by `slug` (`id`). Carries `agent: AgentIdentity` (form × slot × accent → `--accent` ×
+voice × name; the default flow does not let the user pick, so agent identity is effectively
+campaign config), plus `welcome`, optional `landing`, `capabilities` (skill cards +
+`anchor`/`pool`/`sets` Q&A bank + CTAs), `call`, `schedule`, `success` (`callSummaries`),
+optional `build` (AutoBuild beats), `analytics`, and `features[]` capability flags.
+`RichLine` supports the accent-inked span the mockup uses (e.g. `"<agent> is ready to
+work."`). The mapping layer is the seam between HubSpot storage and this contract.
+
+## Backend reuse (from the `info` repo; existing AI-BDR calls)
+
+The funnel's Call Now / Schedule screens submit to a real backend **ported from the
+external `info` repo** (github.com/agilantsolutions/info — a Next.js app whose `/bdr` route
+already runs these calls in production). `info` is an **external reference repo, not a TOGA
+registry repo** — port its logic, do not register or rebuild it. The ported logic drives
+**this AI-BDR system's existing backend calls** (HubSpot contact fetch, Toga upsert +
+campaign link, `requestCall` callback) — those contracts are already documented in
+`call-orchestration.md` and `../architecture.md`; do **not** restate them.
+
+Because BDR is Next.js there is no separate backend to host — all secret-bearing calls run
+server-side (route handlers / server actions in `app/api/*`), wrapped behind two adapters
+so only the impl changes later:
+
+- `LeadSink.upsertLead(input)` → Toga upsert-by-email + campaign link + HubSpot.
+- `CallbackService.requestCall(ref, whenOrNow, phone)` → Toga `requestCall`, immediate vs.
+  scheduled mapped to `CONTACT_CALL_TYPE_UUID`.
+
+Note on "campaign": `info` uses HubSpot **only to fetch the contact**; the URL's
+`hsCampaignId` is passed to Toga as the attribution campaign UUID
+(`addContactToCampaign`) — attribution-only in `info`. **Fetching marketing content by
+slug from HubSpot is net-new** to this funnel (above). The content slug and the attribution
+UUID are related but distinct; the `CampaignBundle` carries the UUID so a slug maps to the
+right campaign for logging.
+
+### Environment (values live in env / Amplify config, never in the repo)
+
+- `HUBSPOT_ACCESS_TOKEN`
+- `TOGA_API_BASE_URL`, `TOGA_CLIENT_ID`, `TOGA_CLIENT_API_UUID`, `TOGA_CLIENT_API_SECRET`
+- `NEXT_PUBLIC_GA_MEASUREMENT_ID`
+
+## Gotchas
+
+- **HubSpot content mechanism is an OPEN question that gates the content-layer phase.**
+  `info` gives no precedent (it only *reads contacts*). Candidate homes: **HubDB** (CMS-Hub
+  table — one row per campaign, `slug` column + content columns, API-fetchable; likely fit)
+  vs. a **custom object** vs. properties on the Campaigns object. The hard part is the
+  **nested content** — Q&A pool + rotation sets, call summaries, accent `RichLine`s — which
+  flat columns can't hold cleanly, so it needs child rows or a structured (JSON) field.
+  Settle with the HubSpot owner before building the content layer.
+- **Keep secrets server-side.** `TOGA_CLIENT_API_SECRET` / `HUBSPOT_ACCESS_TOKEN` and the
+  token exchange must live in server components / route handlers, never in a `"use client"`
+  component or a `NEXT_PUBLIC_` env var (those ship to the browser). The interactive Agent
+  Studio screens are client components, so this boundary is load-bearing.
+- **Do NOT port `info`'s debug `console.log`s** — several log PII (email/phone). Log
+  identifiers only.
+- **Do not port `info`'s hero/curiosity marketing UI** — it is a different, older funnel.
+- **`DEFAULT` must always render.** An unknown/absent slug or a brief HubSpot outage falls
+  back to the built-in safety net — never a 404 funnel.
+- **Runtime fetch adds latency + an availability dependency.** Cache server-side with short
+  revalidation; mind HubSpot API rate limits.
+- **No em dashes in any shipped copy** (mockup rule) — can't be linted on HubSpot-authored
+  copy, so enforce via marketing author guidance + the normalization pass; in-repo strings
+  get an ESLint no-em-dash check.
+- **Single accent source** (mockup rule): every accent-tinted element routes through
+  `var(--accent)` (+ derived `--accent-fill`); never hardcode an accent value.
+
+## Change history
+- 2026-07-08 — Initial doc: Next.js App Router web funnel as the AI-BDR product's UI /
+  lead-capture front door; config-driven campaign bundle authored in HubSpot and fetched by
+  slug server-side at runtime (`DEFAULT` fallback, URL-driven per-request selection); backend
+  ported from the external `info` repo behind LeadSink/CallbackService adapters, reusing this
+  AI-BDR system's existing calls. HubSpot content mechanism still open. (tcox)

package/knowledge/INDEX.md

@@ -27,10 +27,11 @@ _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) — 4 doc(s) → [2.0/apps/ai-bdr/INDEX.md](2.0/apps/ai-bdr/INDEX.md)
+- **ai-bdr** (AI-BDR) — 6 doc(s) → [2.0/apps/ai-bdr/INDEX.md](2.0/apps/ai-bdr/INDEX.md)
 - **toga2-commerce** (TOGa Commerce) — 7 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
 - **toga25-supply** (TOGa 2.5 Supply) — 8 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
 - **toga-blox** (TOGa Blox) — 7 doc(s) → [2.0/apps/toga-blox/INDEX.md](2.0/apps/toga-blox/INDEX.md)
+- **bdr** (BDR) — 0 doc(s) → [2.0/apps/bdr/INDEX.md](2.0/apps/bdr/INDEX.md)
 
 ## standalone framework
 

package/knowledge/registry.json

@@ -210,5 +210,14 @@
     "dependsOn": [
       "library"
     ]
+  },
+  {
+    "repo": "bdr",
+    "project": "BDR",
+    "framework": "2.0",
+    "role": "app",
+    "dependsOn": [
+      "api2"
+    ]
   }
 ]

package/package.json

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