toga-ai 1.0.355 → 1.0.357

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

@@ -19,11 +19,15 @@ related:
   - 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`.
+> **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 commit `34a3910`),
+> and the 2026-07-16 session added phone prefill + mask, `submitOk` on Success, and GA4.
+> **§9.10 is RESOLVED by dissolution** (HubSpot holds no marketing content — content is
+> in-repo; see `web-funnel-content-model.md`) and **§9.11 is RESOLVED** (consent links →
+> togatech.com pages). Remaining work is decision-gated, not code (leadership copy, 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` (which got a §5.2 superseded banner + §9.2/
+> §9.10 re-resolution on 2026-07-16).
 
 # BDR: Multi-Campaign "AI BDR / Agent Studio" Web App — Implementation Plan
 
@@ -238,6 +242,13 @@ Port approach:
 > `NEXT_PUBLIC_` env.
 
 ### 5.2 Content provider — HubSpot is the source of truth
+> **SUPERSEDED (2026-07-16).** This section's premise — HubSpot as the content source —
+> was **dissolved** by the HubSpot instance owner (Rohan): HubSpot holds no marketing
+> content for this product. Content lives **in the repo** (`src/content/default.ts`); the
+> static `src/content/provider.ts` is permanent; the `hubspotProvider.ts` stub was deleted.
+> Read §9.2 / §9.10 (resolved) and `web-funnel-content-model.md` for the current model. The
+> text below is kept for historical context only.
+
 **Decision:** the content store is **HubSpot** (chosen over Contentful). The site's content shape is
 stable / not frequently restructured, so HubSpot's flatter modeling is acceptable, and a dedicated
 headless CMS (Contentful) would only pay off if the content model were rich and frequently
@@ -490,9 +501,12 @@ so fidelity should be near-exact.
 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. **Content store:** RESOLVED — **HubSpot** (over Contentful): content shape is stable, so HubSpot is
-   acceptable and the integration is trivial (§5.2). Content is HubSpot-owned from the start (no
-   hardcoding); the remaining detail is the HubSpot mechanism (§9.10).
+2. **Content store:** RE-RESOLVED (2026-07-16) — **content lives in the repo**
+   (`src/content/default.ts`), **not HubSpot.** The earlier "HubSpot-owned content" decision
+   was based on a misreading of how the team uses HubSpot; the HubSpot owner (Rohan) confirmed
+   HubSpot holds no marketing content for this product. The static `provider.ts` is permanent
+   (the `CampaignContentProvider` seam is kept only for a hypothetical future remote source).
+   See §9.10 and `web-funnel-content-model.md`.
 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
@@ -506,21 +520,24 @@ so fidelity should be near-exact.
 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 (gates the content layer, Phase 1) — the big one.** *How* campaign
-    content is 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 **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.
-11. **Privacy Policy & Terms links (§9.11, from the first design review).** The consent
-    footnotes on Call Now / Schedule link to **dead anchors** (`#privacy` / `#terms`,
-    ported verbatim from the mockup; the original `info` app had none). They need real
-    pages or links to `togatech` pages. Wiring is a **2-line content change** — the schema
-    already supports `[label](href)`, and HubSpot campaigns can override the href per
-    campaign.
+10. **HubSpot content mechanism — RESOLVED by dissolution (2026-07-16, decision by Rohan,
+    the HubSpot instance owner).** There is no HubSpot content mechanism because **HubSpot
+    holds no marketing content** for this product and never will — it is **contact-lookup
+    only** (the `?hsContactId=` fetch, exactly as the old `info` site). Campaign records are
+    added **manually to the Toga database** and reach the app only as the `?hsCampaignId=`
+    attribution UUID on entry URLs (same URL contract as `info`). Consequences: campaign
+    content lives **in-repo** (`src/content/default.ts` is the authoring surface; every slug
+    renders `DEFAULT`); the throwing `hubspotProvider.ts` was **deleted**; `provider.ts`'s
+    static provider is the **permanent** implementation; the `CampaignContentProvider` seam is
+    retained for a hypothetical future remote source. The prior "HubSpot-owned content"
+    assumption (HubDB / custom object / campaign properties) is **moot.**
+11. **Privacy Policy & Terms links (§9.11) — RESOLVED (2026-07-16).** The consent footnotes
+    on Call Now / Schedule now link to the existing **togatech.com** pages
+    (`https://togatech.com/privacy-policy`, `.../terms-and-conditions`) — decision was to link
+    the existing pages, not build in-app ones. `RichText.tsx` `MarkupText` renders real
+    `http(s)` hrefs as live anchors (`target=_blank`, `rel="noopener noreferrer"`, aria-label
+    "... (opens in new tab)"); bare `#hash` hrefs keep the mockup's inert `preventDefault`. A
+    regression test guards against dead anchors returning.
 12. **Share button is a mock (§9.12).** The Success summary-card Share popover validates
     the email and shows "Sent" but **sends nothing** (the Copy button IS a real clipboard
     write). A functional version needs an **email-send route** AND the **real call
@@ -573,6 +590,14 @@ so fidelity should be near-exact.
 - [ ] Pixel-perfect parity pass against the mockup screens + screenshots.
 
 ## Change history
+- 2026-07-16 — §9 resolutions mirrored from `BDR/PLAN.md`. §9.10 RESOLVED by dissolution
+  (decision by Rohan, HubSpot instance owner): HubSpot holds no marketing content — content
+  is in-repo (`default.ts`), `hubspotProvider.ts` deleted, static `provider.ts` permanent;
+  §9.2 re-resolved accordingly (content store is the repo, not HubSpot) and §5.2 marked
+  SUPERSEDED. §9.11 RESOLVED: consent links → togatech.com privacy/terms pages via live
+  `RichText` anchors. Execution-status banner updated: Phase 6 was mostly already built
+  (commit `34a3910`); session added phone prefill + mask, `submitOk` on Success, GA4. Built
+  detail in `web-funnel-app.md`; content model in `web-funnel-content-model.md`. (tcox)
 - 2026-07-15 — First UI design review: appended three future items to §9 open questions,
   mirroring `BDR/PLAN.md` §9.11–§9.13. §9.11 real Privacy/Terms pages (consent footnotes
   currently link to dead `#privacy`/`#terms` anchors; 2-line content fix). §9.12 Share

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

@@ -6,7 +6,7 @@ project: AI-BDR
 client: shared
 type: feature
 status: active
-updated: 2026-07-15
+updated: 2026-07-16
 owners: [tcox]
 files:
   - bdr/PLAN.md
@@ -15,9 +15,14 @@ files:
   - bdr/amplify.yml
   - bdr/src/app
   - bdr/src/app/layout.tsx
+  - bdr/src/app/page.tsx
   - bdr/src/app/studio.css
   - bdr/src/lib/resolveCampaignId.ts
   - bdr/src/lib/scheduleSlots.ts
+  - bdr/src/lib/formatPhone.ts
+  - bdr/src/lib/analytics.ts
+  - bdr/src/components/GoogleAnalytics.tsx
+  - bdr/src/components/RichText.tsx
   - bdr/src/content
   - bdr/src/components
   - bdr/src/flow
@@ -41,11 +46,15 @@ plan lives in `bdr-web-funnel-plan.md`; the config-driven content contract lives
 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").
+As of this writing **PLAN Phases 0–5 are BUILT and QA'd**, and the Phase 6 backend
+work turned out to be **mostly already built** (the `info` URL/backend contract was
+fully implemented at commit `34a3910`: `page.tsx primeLead` reads `?hsContactId=` +
+`?hsCampaignId=` → server-side HubSpot `getContact` → Toga `upsertContactByEmail` with
+campaign attribution → only `togaUuid` crosses to the client). The 2026-07-16 session
+added the deltas below (phone prefill + live input mask, `submitOk` on Success, GA4
+wiring) and resolved §9.10 (content mechanism — see `web-funnel-content-model.md`) and
+§9.11 (consent links). Developer QA verdict: the UI is "very close, minimal adjustments
+to be near exact" vs. the mockup. All checks green: tsc, eslint, 79/79 Vitest, `next build`.
 
 - **Repo:** `agilantsolutions/BDR` on GitHub, working branch `BDR-Development`. The
   machine-local `.claude/` harness is **gitignored** — committing it would snapshot
@@ -66,7 +75,8 @@ is **decision-gated, not code** (see "What is parked / not built").
 - **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
+- **Vitest** test suite: **79 tests, all green** (13 added in the 2026-07-16 session:
+  phone format/prefill/mask, live-anchor consent links, `submitOk` race). Every phase was
   verified with `tsc` + lint + build + a live SSR `curl` before commit.
 - **Deploy target:** AWS Amplify (SSR), `amplify.yml` present (Phase 8 not done).
 
@@ -116,24 +126,70 @@ is **decision-gated, not code** (see "What is parked / not built").
   (`src/server/toga.ts`) converts the picked slot to `America/Chicago` for Toga. If
   `Intl` is unavailable the note simply is not rendered (graceful, no crash). A design
   request to "make tz calculated" was already satisfied — do not re-implement.
+- **Phone prefill (known leads).** `page.tsx` primeLead now also carries the contact's
+  phone: `ClientLeadRef` gained a `phone` field — the **one deliberate PII exception**
+  that crosses to the client (the visitor's own number, shown back to its owner, never
+  logged). `prefillPhone()` (`src/lib/formatPhone.ts`) normalizes CRM values, drops a US
+  `1` prefix, and returns `""` for junk / over-long / non-`+1`-country values (a `+45`
+  number next to the fixed `+1` country-code field would dial the wrong country). CallNow
+  + Schedule init their number fields from it. (The old `info` site exposed name + email +
+  phone the same way; BDR reduces the client-crossing PII to **phone only**.)
+- **Live phone input mask.** `formatPhoneInput()` (`src/lib/formatPhone.ts`) renders a
+  progressive `(555) 012-3456` as the user types: hard 10-digit cap (`maxLength=14` on the
+  inputs), strips non-digits on paste, idempotent, and backspace-safe by design (formatting
+  is always re-derived from the digits, with no trailing punctuation after the last digit,
+  so deleting a `)` or `-` never fights the formatter). Matches the bundle placeholder.
+- **`submitOk` surfaced on Success (known leads only).** When a KNOWN lead's
+  fire-and-forget backend submit resolves `false`, a **pre-mounted** `role="status"` live
+  region (mounted empty so screen readers reliably announce the change) shows
+  `success.submitFailed.{calling,scheduled}`. Anonymous visits always pass `null` and never
+  see it. A submission-generation counter (a ref in `useAgentFlow`) prevents a stale,
+  late-resolving submit from an abandoned attempt overwriting the current result.
+- **GA4 analytics (`react-ga4`).** `src/lib/analytics.ts` + `src/components/GoogleAnalytics.tsx`
+  (mounted in `layout.tsx`), env-driven via `NEXT_PUBLIC_GA_MEASUREMENT_ID` — a silent
+  no-op when unset (dev-only console warning). Typed event map: `screen_viewed`,
+  `build_started`, `early_access_opened`, `call_now_submitted{success}`,
+  `call_later_submitted{success}`. No PII in any param. See the page_location leak gotcha.
+- **Consent footnote links are live (§9.11 resolved).** They point at
+  `https://togatech.com/privacy-policy` and `.../terms-and-conditions` (decision: link the
+  existing togatech pages, not in-app pages). `RichText.tsx` `MarkupText` renders real
+  `http(s)` hrefs as live anchors (`target=_blank`, `rel="noopener noreferrer"`, aria-label
+  "... (opens in new tab)"); bare `#hash` hrefs keep the mockup's inert `preventDefault`.
 
 ## 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.
+- **Content is in-repo, not HubSpot (§9.10 RESOLVED by dissolution, 2026-07-16).** The
+  throwing `hubspotProvider.ts` was **DELETED**; `src/content/provider.ts`'s static
+  provider is the **permanent** implementation, and `DEFAULT_BUNDLE` carries the real
+  shipped copy (not interim). HubSpot is contact-lookup only; campaign records live in Toga.
+  Full detail in `web-funnel-content-model.md`. Do not reintroduce a remote content source.
 - **`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.
+- **Remaining work is decision-gated, not code:** leadership's first-campaign copy;
+  Phase 8 Amplify SSR (incl. a **per-IP WAF rate rule** — see the enumeration gotcha) +
+  `togatech` integration. GA4 (Phase 7) is now wired; §9.10 and §9.11 are resolved.
 
 ## Gotchas
 
+- **CRITICAL — GA4 leaks the entry identifiers unless you scrub `page_location`.** `gtag`
+  stamps `page_location = window.location.href` (which **includes** `?hsContactId=` &
+  `?hsCampaignId=`) on the auto `page_view` **and on every subsequent event** — so the
+  entry identifiers would ship to Google on every hit. Mitigation (in place): initialize
+  with `gtagOptions {send_page_view:false}` and pin a **query-scrubbed** `page_location`
+  via `ReactGA.set` before each pageview. Never send raw `location.href` to analytics here.
+- **HIGH / OPEN (security) — `?hsContactId=` is an enumerable capability token.** The entry
+  page is public and HubSpot contact ids are small integers; a bot walking ids can (a)
+  scrape each contact's phone from the server-rendered prefill, and (b) drive the page-prime
+  Toga upsert, polluting contacts/attribution. **Inherited from `info`'s CRM-link URL
+  contract — cannot be changed unilaterally.** Mitigation path before public launch: a
+  **per-IP WAF rate rule** on the Amplify distribution (Phase 8), and raise **opaque/signed
+  link tokens** with the CRM owner. Tracked in `BDR/PLAN.md` §10.
+- **Standing rule: never add more PII fields to `ClientLeadRef`.** Phone is the one
+  deliberate exception (visitor's own number, shown back to them, never logged). Every field
+  on `ClientLeadRef` crosses to the public client and is exposed to the enumeration risk
+  above — do not widen it.
 - **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
@@ -162,6 +218,22 @@ is **decision-gated, not code** (see "What is parked / not built").
   harness; pull it with `npx toga-ai`.
 
 ## Change history
+- 2026-07-16 — Phase 6 delta + §9.10/§9.11 resolutions. DISCOVERED the `info` URL/backend
+  contract was already fully built at commit `34a3910` (primeLead: `?hsContactId=` +
+  `?hsCampaignId=` → HubSpot `getContact` → Toga upsert + attribution → only `togaUuid` to
+  client). BUILT: phone prefill (`ClientLeadRef.phone`, the one deliberate client-crossing
+  PII field; `prefillPhone()` normalizes CRM values, drops US `1`, rejects non-`+1`-country
+  numbers); live phone input mask (`formatPhoneInput()`, 10-digit cap, paste-safe,
+  backspace-safe); `submitOk` surfaced on Success via a pre-mounted `role="status"` live
+  region for KNOWN leads, guarded by a submission-generation counter against stale late
+  resolves; GA4 via `react-ga4` (env-driven, silent no-op when unset). RESOLVED §9.10 (content
+  is in-repo, `hubspotProvider.ts` DELETED, static `provider.ts` permanent — see
+  `web-funnel-content-model.md`) and §9.11 (consent links now live togatech.com anchors via
+  `RichText`). Added CRITICAL GA4 `page_location` leak gotcha (scrub `?hsContactId=`/
+  `?hsCampaignId=` before every hit), HIGH/OPEN `?hsContactId=` enumeration gotcha (WAF rate
+  rule + signed tokens before launch), and the "never widen `ClientLeadRef` PII" standing
+  rule. 13 new tests (79 total); tsc/eslint/build all green. Work uncommitted at capture
+  time (branch `BDR-Phase-2`). (tcox)
 - 2026-07-15 — First UI design review pass. FIXED: site-wide font silently fell back to
   `system-ui` (mockup's `<head>` Google-Fonts link was never ported) — now Plus Jakarta
   Sans via `next/font/google` in `layout.tsx`, exposed as `--font-jakarta`, resolved

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

@@ -5,12 +5,12 @@ repo: ai-bdr
 project: AI-BDR
 client: shared
 type: feature
-status: draft
-updated: 2026-07-14
+status: active
+updated: 2026-07-16
 owners: [tcox]
 files:
   - bdr/src/content/schema.ts
-  - bdr/src/content/hubspotProvider.ts
+  - bdr/src/content/provider.ts
   - bdr/src/content/useCampaign.ts
   - bdr/src/content/default.ts
   - bdr/src/lib/resolveCampaignId.ts
@@ -25,11 +25,14 @@ related:
   - 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`.
+> **Status note (RESOLVED 2026-07-16):** the content **contract** below (schema,
+> provider seam, adapters) is BUILT and QA'd (PLAN Phases 0–5). The last open item —
+> *how* campaign content is sourced (§9.10) — is now **resolved by dissolution**
+> (decision by Rohan, the HubSpot instance owner): **HubSpot never holds marketing
+> content for this product.** Campaign content lives **in the repo** (`src/content/default.ts`
+> is the authoring surface); the static `src/content/provider.ts` is the **permanent**
+> implementation and the throwing `hubspotProvider.ts` stub was **deleted**. HubSpot is
+> contact-lookup only (see "How campaigns actually work" below). This doc is now `active`.
 
 ## What this is
 
@@ -55,41 +58,42 @@ routes through `var(--accent)` + derived `--accent-fill`; never hardcode an acce
 
 Full implementation plan: `BDR/PLAN.md`.
 
-## Config-driven campaign content (HubSpot-owned, fetched by slug at runtime)
+## How campaigns actually work (content in-repo; HubSpot is contact-lookup only)
+
+> **This section supersedes the earlier "HubSpot-owned content" model.** The prior plan
+> assumption — that marketing would author campaign content in HubSpot and the app would
+> fetch it by slug — was a **misreading** of how the team uses HubSpot. The HubSpot
+> instance owner (Rohan) confirmed on 2026-07-16 that **HubSpot holds no marketing content
+> and never will** for this product. §9.10 is resolved by dissolution.
 
 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. There is **no hardcoded/in-code interim**: content is HubSpot-owned and
-fetched by slug from the start (an in-code interim was considered and rejected).
-
-**Content store decided: HubSpot (over Contentful).** Rationale: (a) marketing already
-operates in HubSpot; (b) the campaign model already exists there — the old BDR site (`info`)
-uses HubSpot for lead sourcing, personalization, and campaign **attribution**
-(`hsContactId` / `hsCampaignId` → Toga), so content keys off that same campaign concept and
-content + attribution stay in one system; (c) the API integration is trivial — a ~15-line
-server-side fetch proxied by a Next route handler (proven in `info`; same pattern serves
-HubDB); (d) no new vendor to contract. **Trade-off accepted:** HubSpot is not a
-purpose-built content CMS, so richly nested content and non-dev editor UX are weaker than
-Contentful — acceptable here because the content shape is **stable / not frequently
-restructured** (a headless CMS would only pay off if the model were rich and churning).
+`slug`. **Campaign content is authored in the repo** — `src/content/default.ts` is the
+authoring surface, and **every slug renders `DEFAULT`.** There is no remote content
+source. What HubSpot *does* provide is unchanged from the old `info` site: a **contact
+lookup** (`?hsContactId=` → server-side `getContact`), nothing more.
+
+**Campaign records are added MANUALLY to the Toga database** and reach the app only as the
+`?hsCampaignId=` attribution UUID on entry URLs (the exact same URL contract as `info`).
+The UUID is passed through to Toga (`addContactToCampaign`) for attribution; it does **not**
+select or fetch content.
+
+The `CampaignContentProvider` **seam is retained** (so a hypothetical future remote source
+could slot in), but the static `src/content/provider.ts` is the **permanent** implementation
+— not an interim. The throwing `hubspotProvider.ts` stub was **deleted**.
 
 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.
+**no `if (campaign === 'x')` branching** anywhere in the screens. The repo holds the
+**schema** (`CampaignBundle` types), the **static provider**, and the **`DEFAULT`** bundle
+that carries the real shipped content.
+
+- **Provider seam.** `CampaignContentProvider.resolve(slug)` returns a `CampaignBundle`.
+  The permanent `provider.ts` implementation returns `DEFAULT` for every slug (server-side,
+  during render). Client components receive the resolved bundle as props / via
+  `useCampaign()`.
 - **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.
+  `Record<key, fn|Component>` registry — the bundle stays pure 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
@@ -122,10 +126,10 @@ returns the `DEFAULT` bundle, so the funnel always renders. Entry resolution liv
 `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).
+**`DEFAULT_BUNDLE` (`src/content/default.ts`) is the shipped content**, not interim dev
+copy — it carries the mockup's real copy and is what every slug renders. The throwing
+`hubspotProvider.ts` stub was **deleted** (§9.10 dissolution); do not reintroduce a remote
+provider without a new decision.
 
 ## Backend reuse (from the `info` repo; existing AI-BDR calls)
 
@@ -157,10 +161,10 @@ 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
-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.
+(`addContactToCampaign`) — attribution-only. **BDR keeps this exact contract** — HubSpot
+is contact-lookup only, campaign records are added manually to Toga, and the app never
+fetches marketing content from anywhere (see "How campaigns actually work" above). The
+`CampaignBundle` still carries the UUID so a slug maps to the right campaign for logging.
 
 ### Environment (values live in env / Amplify config, never in the repo)
 
@@ -170,13 +174,11 @@ right campaign for logging.
 
 ## 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.
+- **Do NOT reintroduce a HubSpot (or any remote) content source.** §9.10 is resolved by
+  dissolution (2026-07-16, HubSpot owner): HubSpot holds no marketing content for this
+  product. Content lives in `src/content/default.ts`; the static `provider.ts` is permanent.
+  The `CampaignContentProvider` seam is kept only for a *hypothetical* future remote source
+  and needs a fresh decision before anyone wires one.
 - **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
@@ -184,17 +186,26 @@ right campaign for logging.
 - **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.
+- **`DEFAULT` is what always renders.** Every slug resolves to the in-repo `DEFAULT`
+  bundle — an unknown/absent slug is not a special case, it's the norm; never a 404 funnel.
+- **No em dashes in any shipped copy** (mockup rule). Because content is now in-repo, this
+  is fully enforced by the ESLint no-em-dash check on in-repo strings — no author-guidance
+  or normalization-pass gap.
 - **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-16 — §9.10 RESOLVED by dissolution (decision by Rohan, HubSpot instance owner):
+  HubSpot holds NO marketing content for this product and never will — it is contact-lookup
+  only (`?hsContactId=`, exactly as `info`). Campaign content lives in-repo (`default.ts` is
+  the authoring surface; every slug renders `DEFAULT`); campaign records are added MANUALLY
+  to Toga and reach the app only as the `?hsCampaignId=` attribution UUID. Rewrote the
+  content section (was "HubSpot-owned, fetched by slug"), removed the HubSpot-over-Contentful
+  framing, the throwing `hubspotProvider.ts` was DELETED, and the static `provider.ts` is now
+  the permanent implementation (the `CampaignContentProvider` seam is kept only for a
+  hypothetical future remote source). Dropped the now-moot runtime-fetch latency / HubSpot
+  content-mechanism gotchas. Flipped `draft`→`active` (the reason it was draft is resolved).
+  (tcox)
 - 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/

package/knowledge/INDEX.md

@@ -17,7 +17,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 32 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 33 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 30 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 11 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 3 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)

package/knowledge/clients/compass-canada/profile.md

@@ -14,11 +14,12 @@ project: _Underscore
 client: compass-canada
 type: profile
 status: active
-updated: 2026-06-30
+updated: 2026-07-16
 owners: [jcardinal, bala, tcox, apeterson]
 files: []
 related:
   - ../compass-usa/profile.md
+  - ../compass-usa/features/approval-decision-flow.md
   - ../../2.0/apps/toga2-commerce/features/expedited-shipping-gating.md
   - ../../2.0/apps/_underscore/features/item-fulfillment-stage-lifecycle-and-order-status.md
   - ../../2.0/apps/_underscore/features/surface-resolver.md
@@ -59,6 +60,12 @@ to but distinct from Compass USA. Like Compass USA it spans the **2.0** commerce
   Compass USA's 1/3/4. See [Surface Resolver](../../2.0/apps/_underscore/features/surface-resolver.md).
 - Customer language preference: `UserGlobalSettings.settingId = 2` (`en` / `fr-CA`); customer-
   facing emails are sent in EN or FR accordingly.
+- **Approval decisions use the shared Compass parent.** `_Model_Compass_Canada_ApprovalDecision`
+  is an empty subclass of `_Model_Compass_ApprovalDecision`; the entire approval/notification/
+  manager-reassignment/VIP-auto-approve flow lives in the parent and branches at runtime on
+  `clientIdentifier === 'Compass_Canada'` (email-template UUID + EN/FR localization). Fixes to the
+  parent cover Canada automatically — no per-tenant change. See
+  [Approval-Decision Flow](../compass-usa/features/approval-decision-flow.md).
 - Assortment (product-grouping) names are served in fr-CA via the `AssortmentTranslations` sidecar
   (16 rows seeded). French was extracted from the old bilingual `"English/French"` `Assortments.name`
   values, which were then cleaned to English-only. See

package/knowledge/clients/compass-usa/INDEX.md

@@ -2,6 +2,7 @@
 
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
+| [Compass Approval-Decision Flow (Notifications & Manager Reassignment)](features/approval-decision-flow.md) | 2.0 | Compass's sales-order approval flow — approval/notification email lists, **manager reassignment**, VIP auto-approve, and EN/FR localization — lives **entirely i | _underscore/Model/Compass/ApprovalDecision.php, _underscore/Model/Compass/Usa/ApprovalDecision.php, _underscore/Model/Compass/Canada/ApprovalDecision.php |
 | [Compass ASN → ItemFulfillment Auto-Creation](features/asn-to-item-fulfillment.md) | 2.0 | For Compass USA, posting an AdvanceShippingNotice (ASN) auto-creates the ItemFulfillment (IF) on the upstream SalesOrder. | _underscore/Model/Compass/AdvanceShippingNotice.php, _underscore/Model/Compass/PurchaseOrder.php, api2/Component/Api/Cxml/Cxml.php, dbchanges2/Client_Compass/2026-06-11 - AsnItemTrackingNumberAcl.sql, dbchanges2/Client_Compass/2026-06-15b - BackfillSA132781ItemFulfillmentTracking.sql, dbchanges2/Client_Compass/2026-06-16 - CleanupSA132763CrossLineTracking.sql, dbchanges2/Client_Compass/2026-06-16b - CleanupSA132743CrossLineTracking.sql, dbchanges2/Client_Compass/2026-06-16c - BackfillSA132763C40QYUCTracking.sql, dbchanges2/Client_Compass/2026-06-18a - CleanupSA132898DuplicateTracking.sql, dbchanges2/Client_Compass/2026-06-18b - CleanupSA132881DuplicateTracking.sql, dbchanges2/Client_Compass/2026-07-02a - FixSA133377TrackingSerialAndDuplicateIF.sql |
 | [Cost Centers — Unit Locations, numeric-only policy](features/cost-centers.md) | 2.0 | A Compass "cost center" — the value a user picks in commerce and that lands on an order — is **not** a `CostCenters` row. | toga2-commerce/src/pages/Cart/api/CartApi.ts, worker1.5/crons/toga2/compass/import_locations.php, _underscore/Model/Compass/SalesOrder.php, api2/Component/Api/V2/V2.php, dbchanges2/Client_Compass/2026-07-06 - RemoveNonNumericCostCenters.sql |
 | [Compass: Item-Fulfillment TableViews (for-sales-order-items & for-sales-orders, tracking via bridge)](features/item-fulfillment-tracking-tableview.md) | 2.0 | Two sibling Compass TableViews in `Client_Compass` display fulfilled items in toga2-supply, both driven by `TableViews` / `TableViewJoins` / `TableViewFields` c | dbchanges2/Client_Compass/2026-06-10 - ItemFulfillmentsForSalesOrderItemsTableView.sql, dbchanges2/Client_Compass/2026-06-11 - ItemFulfillmentsForSalesOrdersTableView.sql, dbchanges2/Client_Compass/2026-06-15a - FixItemFulfillmentTrackingNumberJoins.sql, dbchanges2/Client/2026-07-15a - ExcludeFeeItemsFromItemFulfillmentsForSalesOrdersView.sql |

package/knowledge/clients/compass-usa/features/approval-decision-flow.md

@@ -0,0 +1,100 @@
+---
+title: Compass Approval-Decision Flow (Notifications & Manager Reassignment)
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: compass-usa
+type: client-feature
+status: active
+updated: 2026-07-16
+owners: ["apeterson"]
+files:
+  - _underscore/Model/Compass/ApprovalDecision.php
+  - _underscore/Model/Compass/Usa/ApprovalDecision.php
+  - _underscore/Model/Compass/Canada/ApprovalDecision.php
+related:
+  - mr-ma-order-approval-and-status.md
+  - ../../compass-canada/profile.md
+  - ../../../2.0/apps/_underscore/features/email-template-sending.md
+---
+
+## Summary
+Compass's sales-order approval flow — approval/notification email lists, **manager reassignment**,
+VIP auto-approve, and EN/FR localization — lives **entirely in the shared parent
+`_Model_Compass_ApprovalDecision`**. Both tenant subclasses,
+`_Model_Compass_Usa_ApprovalDecision` and `_Model_Compass_Canada_ApprovalDecision`, are **empty**
+(`extends _Model_Compass_ApprovalDecision {}`, no overrides). Client- and language-specific
+behavior is **not** subclassed; it branches at runtime inside the parent on
+`$api->client->clientIdentifier` (`Compass_Usa` vs `Compass_Canada`). Practical consequence: a fix
+to a parent method applies to **both** Compass US and Compass Canada automatically — there is no
+per-client code change to make.
+
+This doc covers the **approval-decision / notification** half of Compass approvals. The separate
+auto-approval + `_status` gating on the order itself is in
+[Compass MR/MA Order Auto-Approval & Status Gate](mr-ma-order-approval-and-status.md).
+
+## Key files / entry points
+- **`_underscore/Model/Compass/ApprovalDecision.php`** — the shared parent that owns the whole
+  flow (notification-list maintenance, `_swapManagerEmailAddress()`, VIP auto-approve, email-template
+  UUID resolution, localization).
+- **`_underscore/Model/Compass/Usa/ApprovalDecision.php`** — empty subclass, no overrides.
+- **`_underscore/Model/Compass/Canada/ApprovalDecision.php`** — empty subclass, no overrides.
+
+## How it works
+### One shared parent, runtime client branch (not subclass overrides)
+Compass US and Compass Canada resolve to different model classes at request time
+(`_Model_Compass_Usa_ApprovalDecision` / `_Model_Compass_Canada_ApprovalDecision`), but both are
+empty shells extending `_Model_Compass_ApprovalDecision`. All behavior is inherited. Where the two
+tenants differ, the **parent** branches on `$api->client->clientIdentifier === 'Compass_Canada'`:
+- **Email-template resolution** — `resolveEmailTemplateUuid()` picks the tenant's template UUID.
+- **EN/FR localization** — user language is read from `UserGlobalSettings` (`settingId = 2`;
+  `en` / `fr-CA`) so Canadian notifications go out in the recipient's language.
+
+Because the divergence is a runtime branch and not an override, do **not** add per-client logic to
+the empty subclasses — extend the shared parent and branch there if a genuine tenant difference is
+needed.
+
+### Manager reassignment and the notification list
+When a step-2 (Manager) approval decision is **reassigned** to a new manager,
+`_swapManagerEmailAddress()` updates the order's CC/notification list in `SalesOrderEmailAddresses`:
+it removes the outgoing manager's email and adds the incoming manager's. The one email that must
+**never** be dropped is the **order requester's** — the person the order is for, resolved via
+`SalesOrders.contactId → Users` (the requester's email is looked up with a parameterized
+`SELECT Users.email FROM SalesOrders INNER JOIN Users ON Users.contactId = SalesOrders.contactId
+WHERE SalesOrders.id = ?`). Before deleting the old-manager email, the method compares it against
+both the new-manager email and the requester email and **skips the delete when it matches the
+requester**. All of these comparisons are case-insensitive (`strcasecmp()`), matching
+`getFilteredCcEmails()`.
+
+## Gotchas / known issues
+- **Never drop the order requester from notifications on manager reassignment.** If the outgoing
+  manager happens to also be the order requester (same email), deleting the old-manager address
+  from `SalesOrderEmailAddresses` would silently remove the requester from all order notifications.
+  `_swapManagerEmailAddress()` guards against this by comparing the old-manager email to the
+  requester's email (looked up via `SalesOrders.contactId → Users`) and skipping the delete when
+  they match. This was a live bug (fixed 2026-07-16).
+- **Email comparisons must be case-insensitive.** Use `strcasecmp()`, not `!==` — the notification
+  list can hold the same address in different casing, and `getFilteredCcEmails()` already compares
+  case-insensitively. A strict `!==` comparison here previously let a casing mismatch defeat the
+  requester/new-manager guards.
+- **Don't put tenant behavior in the empty subclasses.** `Usa`/`Canada` `ApprovalDecision` are
+  intentionally empty; the tenant branch lives in the parent on `clientIdentifier`.
+
+## Change history
+- 2026-07-16 — Fixed `_swapManagerEmailAddress()` dropping the order requester from the order's
+  notification list (`SalesOrderEmailAddresses`) when a step-2 manager was reassigned and the
+  outgoing manager's email also belonged to the requester: now looks up the requester email via
+  `SalesOrders.contactId → Users` and skips the delete when they match; also switched the
+  old-vs-new and old-vs-requester comparisons to case-insensitive `strcasecmp()` (was `!==`) to
+  match `getFilteredCcEmails()`. Documented that the flow is the shared parent
+  `_Model_Compass_ApprovalDecision` (empty `Usa`/`Canada` subclasses, runtime `clientIdentifier`
+  branch), so the fix covers Compass Canada automatically. Shipped on branch TRUE-80244 (pushed;
+  not yet merged to `_beta`). (apeterson)
+
+## Related docs
+- [Compass MR/MA Order Auto-Approval & Status Gate](mr-ma-order-approval-and-status.md) — the
+  auto-approval + `_status` gating half of Compass approvals (on `_Model_Compass_SalesOrder`).
+- [Compass Canada](../../compass-canada/profile.md) — uses this identical flow; the runtime
+  `Compass_Canada` branch drives its EN/FR notification localization.
+- [Email Template Sending](../../../2.0/apps/_underscore/features/email-template-sending.md) — the
+  shared engine the resolved approval-notification templates are sent through.

package/knowledge/clients/compass-usa/profile.md

@@ -15,12 +15,13 @@ project: _Underscore
 client: compass-usa
 type: profile
 status: active
-updated: 2026-07-15
+updated: 2026-07-16
 owners: [jcardinal, bala, tcox, apeterson]
 files: []
 related:
   - features/asn-to-item-fulfillment.md
   - features/cost-centers.md
+  - features/approval-decision-flow.md
   - workflows/cross-kit-bundle-corruption.md
   - ../../2.0/apps/worker2/features/compass-vip-support-importer.md
   - ../../2.0/apps/toga2-commerce/features/expedited-shipping-gating.md
@@ -75,6 +76,10 @@ separate, related client (see its own profile).
 - [VIP Support Importer (worker2)](../../2.0/apps/worker2/features/compass-vip-support-importer.md)
   — manual (Postman) worker2 action that reads Compass's quarterly VIP spreadsheet and sets
   `Users.c_supportedByUserId` (assigned support tech) per VIP.
+- [Approval-Decision Flow (Notifications & Manager Reassignment)](features/approval-decision-flow.md) —
+  the shared `_Model_Compass_ApprovalDecision` parent (empty `Usa`/`Canada` subclasses; runtime
+  `clientIdentifier` branch) that owns approval notifications, manager reassignment, VIP
+  auto-approve, and EN/FR localization.
 
 ## Notes
 - **Order status is shipped-only (2026-06-30).** Compass imports all IF stages

package/package.json

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