toga-ai 1.0.330 → 1.0.331

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

@@ -6,7 +6,7 @@ project: "AI-BDR"
 client: shared
 type: feature
 status: draft
-updated: 2026-07-13
+updated: 2026-07-14
 owners: [tcox]
 files:
   - bdr/PLAN.md
@@ -16,8 +16,15 @@ files:
 related:
   - architecture.md
   - web-funnel-content-model.md
+  - web-funnel-app.md
 ---
 
+> **Execution status (2026-07-14):** PLAN **Phases 0–5 are BUILT and QA'd** — the web
+> app engine, full mockup port, and real backend are done. Remaining work is
+> decision-gated, not code (§9.10 HubSpot mechanism, leadership copy, Phase 7 polish,
+> Phase 8 deploy). The built codebase is documented in `web-funnel-app.md`; this doc
+> stays a plan mirror. This body still mirrors `BDR/PLAN.md`.
+
 # BDR: Multi-Campaign "AI BDR / Agent Studio" Web App — Implementation Plan
 
 > **Status:** Draft 2 (needs one more review). Open items tracked in §9; final campaign direction /
@@ -194,7 +201,7 @@ 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. |
+| Repo name | **`bdr`** | Greenfield repo, registered in the TOGA registry (`agilantsolutions/BDR`). |
 | 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). |
@@ -551,5 +558,11 @@ so fidelity should be near-exact.
 - [ ] Pixel-perfect parity pass against the mockup screens + screenshots.
 
 ## Change history
+- 2026-07-14 — Phases 0–5 executed and QA'd (engine + full mockup port + real backend);
+  built codebase now documented in `web-funnel-app.md`. `BDR/PLAN.md` itself corrected:
+  absolute local paths genericized, and the stale "not yet in TOGA registry" note fixed
+  (bdr IS registered). Repo now lives at `agilantsolutions/BDR` (branch `BDR-Development`);
+  the local `.claude/` harness is gitignored (devs pull it via `npx toga-ai`). Body still
+  mirrors PLAN.md. (tcox)
 - 2026-07-13 — Draft 2 resync: re-mirrored the body from the current `BDR/PLAN.md`. Framework locked to Next.js App Router (earlier React/Vite SPA idea dropped); content store decided HubSpot over Contentful (rationale in §4/§5.2); no-hardcoding (HubSpot-owned, fetched by slug from the start); same-product framing confirmed (front door of the existing AI-BDR backend, "backend relationship" open question resolved); meeting-specific dates/cadence removed. Still a draft. (tcox)
 - 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-app.md

@@ -0,0 +1,143 @@
+---
+title: Web Funnel — Built Next.js App (structure, stack, how to run)
+framework: "2.0"
+repo: ai-bdr
+project: AI-BDR
+client: shared
+type: feature
+status: active
+updated: 2026-07-14
+owners: [tcox]
+files:
+  - bdr/PLAN.md
+  - bdr/.gitignore
+  - bdr/eslint.config.mjs
+  - bdr/amplify.yml
+  - bdr/src/app
+  - bdr/src/lib/resolveCampaignId.ts
+  - bdr/src/content
+  - bdr/src/components
+  - bdr/src/flow
+  - bdr/src/server
+  - bdr/src/app/api
+  - bdr/test
+  - bdr/public
+  - bdr/mockup/styles.css
+related:
+  - web-funnel-content-model.md
+  - bdr-web-funnel-plan.md
+  - ../architecture.md
+---
+
+## What this is
+
+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`). The forward-looking
+plan lives in `bdr-web-funnel-plan.md`; the config-driven content contract lives in
+`web-funnel-content-model.md`. **This doc covers the actual shipped codebase: the
+stack, the directory map, what was ported vs. parked, the test suite, and the
+decisions that are load-bearing for anyone touching the repo.**
+
+As of this writing **PLAN Phases 0–5 are BUILT and QA'd** — the web app engine and
+full mockup port are complete, all screens/modals render config-driven from a
+bundle, and the real backend is wired behind adapters. Developer QA verdict: the UI
+is "very close, minimal adjustments to be near exact" vs. the mockup. Remaining work
+is **decision-gated, not code** (see "What is parked / not built").
+
+- **Repo:** `agilantsolutions/BDR` on GitHub, working branch `BDR-Development`. The
+  machine-local `.claude/` harness is **gitignored** — committing it would snapshot
+  the whole KB stale; devs get the harness via `npx toga-ai`, not from this repo.
+
+## Stack
+
+- **Next.js 16.2.3, App Router + TypeScript**, mirroring the `info` repo's config.
+- **No Tailwind (deliberate).** Tailwind 4's preflight reset would fight the mockup's
+  hand-authored CSS (ported verbatim as `src/app/studio.css`) and threaten pixel
+  parity. Do **not** add Tailwind to this repo — the styling is intentionally the
+  mockup's own CSS-variable system. See the styles.css escape-sequence gotcha below.
+- **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: **67 tests across 7 files, all green.** Every phase was
+  verified with `tsc` + lint + build + a live SSR `curl` before commit.
+- **Deploy target:** AWS Amplify (SSR), `amplify.yml` present (Phase 8 not done).
+
+## Directory map (what got built)
+
+- `src/app/*` — App Router shell + pages; `page.tsx` is a server component that
+  resolves the campaign and primes the lead server-side (from `?hsContactId`) and
+  **never fails rendering**. `src/app/studio.css` is the mockup CSS ported verbatim.
+- `src/lib/resolveCampaignId.ts` — campaign entry resolution: `?campaign=<slug>` →
+  `?hsCampaignId=` mapped → `DEFAULT`. Slug regex `^[a-z0-9][a-z0-9-]{0,63}$`.
+- `src/content/*` — the content layer (schema/provider/default/hook). See
+  `web-funnel-content-model.md` for the contract; the schema is now THE contract.
+- `src/components/*` — full mockup component library port: `Ico` (27-icon registry
+  hydrating bundle icon keys), `SwapFade`, `TalkingPreview`, `VoiceDial`, etc., with
+  the mockup's motion hardening ported **verbatim** (do not "simplify" the settle
+  guards / effect-owned timers away).
+- `src/flow/*` — `useAgentFlow` state machine (the `go()` / `back` map, modal gates)
+  plus the screens. Persists to `localStorage` (`aibdr.v2`) where **only voice
+  survives a refresh**; the flow restarts at Welcome.
+- `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`.
+- `public/*` — assets pruned to the **default campaign only** (~6.2 MB).
+- `test/*` — the 67-test Vitest suite.
+
+## How the built app behaves (key runtime facts)
+
+- **Agent identity is campaign config.** AutoBuild lands on the campaign's
+  `bundle.agent`, **not** a hardcoded "Alex" — the presented agent (art, accent,
+  voice, name) comes from the resolved bundle. The manual Creator is parked, so the
+  user does not pick the agent in the default flow.
+- **Template tokens** `<agent>` / `<date>` / `<tz>` / `<time>` / `<detail>` in bundle
+  strings are substituted at render by an `agentize()` helper.
+- **Funnel always renders.** `resolveCampaign` never throws — an unknown slug or a
+  provider failure returns the `DEFAULT` bundle. The server page primes the lead but
+  never fails rendering on a bad/absent contact.
+- **Boundary validation on every route handler.** 16 KB body cap; phone / UUID / ISO
+  checks; all handlers return the `{isSuccess, status, error, messages, data}`
+  envelope (same contract as `info`/Toga).
+
+## What is parked / not built
+
+- **Creator screen + `TweaksPanel` — deliberately NOT ported** (parked per plan
+  §9.3 / §9.7).
+- **`hubspotProvider` is a throwing stub**, gated on the §9.10 HubSpot content-
+  modeling decision. Until HubSpot is seeded, `DEFAULT_BUNDLE` carries the mockup's
+  copy verbatim as documented **interim dev content**; it slims to a bare
+  engineering fallback once HubSpot is seeded.
+- **`info`'s dead 501 `visit` route was dropped** on purpose (attack surface, no
+  caller).
+- **Remaining work is decision-gated, not code:** §9.10 HubSpot content mechanism
+  (HubDB likely — gates the provider + campaign seeding, Phase 6); leadership's
+  first-campaign copy; Phase 7 pixel/GA4/accessibility polish; Phase 8 Amplify SSR +
+  `togatech` integration.
+
+## Gotchas
+
+- **The mockup's `mockup/styles.css` contains literal `\n` and `\"` escape sequences**
+  (JS-string generation artifacts, around lines ~759 / ~840) that break real CSS
+  parsers. This was **fixed in the ported `src/app/studio.css`**, but
+  `mockup/styles.css` was intentionally left pristine — so **anyone re-porting the
+  mockup CSS must re-apply this fix.**
+- **No PII in logs.** All of `info`'s PII-logging was stripped on port (identifier-
+  only logs); the Toga error paths **strip query strings** because the contact
+  lookup carries the email in the query. Do not reintroduce value logging.
+- **No Tailwind** — see Stack. The mockup CSS is the styling system; adding Tailwind
+  risks pixel parity.
+- **`.claude/` is gitignored** in the BDR repo on purpose — do not commit the
+  harness; pull it with `npx toga-ai`.
+
+## Change history
+- 2026-07-14 — Initial doc: recorded the BUILT state of the BDR web funnel (PLAN
+  Phases 0–5 executed + QA'd). Next.js 16.2.3 App Router/TS, deliberate no-Tailwind,
+  ESLint no-em-dash rule, `resolveCampaignId`, full mockup component/flow port
+  (`useAgentFlow`, Ico registry, motion hardening verbatim), agent identity as
+  campaign config, real backend behind LeadSink/CallbackService with PII logging
+  stripped and boundary-validated route handlers, 67 green Vitest tests. Recorded the
+  parked items (Creator/TweaksPanel, throwing hubspotProvider, dropped `visit` route)
+  and the `mockup/styles.css` escape-sequence re-port gotcha. (tcox)
+</content>
+</invoke>

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

@@ -6,22 +6,31 @@ project: AI-BDR
 client: shared
 type: feature
 status: draft
-updated: 2026-07-13
+updated: 2026-07-14
 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/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
 related:
   - ../architecture.md
   - call-orchestration.md
+  - web-funnel-app.md
 ---
 
+> **Status note:** the content **contract** below (schema, provider seam, adapters)
+> is now BUILT and QA'd (PLAN Phases 0–5). The built codebase — structure, stack,
+> how to run — is documented in `web-funnel-app.md`. The one part still **not** built
+> is the HubSpot content *sourcing* (`hubspotProvider` is a throwing stub gated on the
+> §9.10 mechanism decision), which is why this doc stays `draft`.
+
 ## What this is
 
 The **public-facing web funnel** is the new UI / lead-capture front door of the **same
@@ -100,6 +109,24 @@ optional `build` (AutoBuild beats), `analytics`, and `features[]` capability fla
 `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.
 
+**Schema calibrated by building (the §6 plan sketch was a sketch; `src/content/schema.ts`
+is now THE contract).** Additions made while building the real screens: `chrome`
+(wordmark / rail labels); capabilities `eyebrows` + qbank strings + `howLink`;
+`connectNote` split to `{label, value}`; `earlyAccess` / `phone` / `recap` groups;
+`build` made **required**. Bundle template tokens `<agent>` / `<date>` / `<tz>` /
+`<time>` / `<detail>` are substituted **at render** by an `agentize()` helper (they are
+plain strings in the bundle, so HubSpot only ever stores strings).
+
+**`resolveCampaign` never throws** (built): an unknown slug or a provider failure
+returns the `DEFAULT` bundle, so the funnel always renders. Entry resolution lives in
+`src/lib/resolveCampaignId.ts` (`?campaign=<slug>` → mapped `?hsCampaignId=` →
+`DEFAULT`; slug regex `^[a-z0-9][a-z0-9-]{0,63}$`).
+
+**`hubspotProvider` is a throwing stub** explicitly gated on the §9.10 HubSpot-modeling
+decision — it is not wired yet. Until HubSpot is seeded, **`DEFAULT_BUNDLE` carries the
+mockup's copy verbatim as documented interim dev content**; once HubSpot is seeded it
+slims to a bare engineering safety-net fallback (not authored marketing copy).
+
 ## 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
@@ -118,6 +145,16 @@ so only the impl changes later:
 - `CallbackService.requestCall(ref, whenOrNow, phone)` → Toga `requestCall`, immediate vs.
   scheduled mapped to `CONTACT_CALL_TYPE_UUID`.
 
+**Built (PLAN Phase 5):** `info`'s `toga.ts` / `hubspot.ts` are ported into `src/server/`
+behind those adapters with **all of `info`'s PII logging stripped** (identifier-only
+logs; the Toga error paths **strip query strings** because the contact lookup carries
+the email in the query). Route handlers `/api/call-now`, `/api/call-later`, `/api/contact`
+**validate at the boundary** (16 KB body cap; phone / uuid / ISO checks) and always
+return the `{isSuccess, status, error, messages, data}` envelope. The page primes the
+lead server-side from `?hsContactId` and never fails rendering. `info`'s dead 501
+`visit` route was deliberately dropped (attack surface, no caller). Verified by 67 green
+Vitest tests. See `web-funnel-app.md` for the full built structure.
+
 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
@@ -158,6 +195,16 @@ right campaign for logging.
   `var(--accent)` (+ derived `--accent-fill`); never hardcode an accent value.
 
 ## Change history
+- 2026-07-14 — Content contract BUILT + QA'd (PLAN Phases 0–5): schema calibrated by
+  building the real screens (`src/content/schema.ts` is now THE contract — chrome,
+  capabilities eyebrows/qbank/howLink, `connectNote` {label,value}, earlyAccess/phone/
+  recap groups, `build` required, `agentize()` token substitution); `resolveCampaign`
+  never throws (unknown slug/provider failure → DEFAULT); `hubspotProvider` is a throwing
+  stub gated on §9.10; `DEFAULT_BUNDLE` carries the mockup copy as interim dev content.
+  Backend ported from `info` behind LeadSink/CallbackService with PII logging stripped,
+  boundary-validated route handlers, dead `visit` route dropped; 67 green Vitest tests.
+  Built structure split out to `web-funnel-app.md`. Kept `draft` because HubSpot content
+  sourcing (§9.10) is still open. (tcox)
 - 2026-07-13 — Draft 2 resync to the current plan: framework locked to Next.js App Router
   (earlier React/Vite SPA idea dropped); recorded the **HubSpot-over-Contentful** content-store
   decision + rationale (marketing already in HubSpot, campaign model already exists, trivial

package/package.json

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