toga-ai 1.0.322 → 1.0.324

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

@@ -3,8 +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 |
+| [BDR Web Funnel — Full Implementation Plan](features/bdr-web-funnel-plan.md) | > **Status:** Draft 2 (needs one more 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 |
+| [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` — it is the front doo | 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,7 +6,7 @@ project: AI-BDR
 client: shared
 type: architecture
 status: active
-updated: 2026-07-08
+updated: 2026-07-13
 owners: [akhokhani, tcox]
 files:
   - ai-bdr/README.md
@@ -184,7 +184,10 @@ this system's existing calls** (HubSpot contact fetch, Toga upsert + campaign li
 `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,
+config-driven campaign content layer** (HubSpot chosen over Contentful — marketing already
+operates there, the campaign model already exists, and the read is a trivial server-side
+fetch; the stable content shape makes a dedicated headless CMS unnecessary): 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`**.
@@ -213,3 +216,5 @@ redeploy). Full detail: **`features/web-funnel-content-model.md`**.
   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)
+- 2026-07-13 — Additive: recorded the HubSpot-over-Contentful content-store decision for the
+  web funnel. (tcox)

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-08
+updated: 2026-07-13
 owners: [tcox]
 files:
   - bdr/PLAN.md
@@ -20,8 +20,8 @@ related:
 
 # 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.
+> **Status:** Draft 2 (needs one more review). Open items tracked in §9; final campaign direction /
+> verbiage still pending 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).
 >
@@ -65,22 +65,23 @@ mockup folder, and the `info` repo.
 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.
+**content authored by marketing in HubSpot** and fetched **by slug at runtime**, so adding or changing
+a campaign needs no code and no redeploy. 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
+   **each authored in HubSpot**, render differing only in **data** (copy, Q&A proof points, agent
+   identity, accent), with zero component-code differences. Adding/changing a campaign is a **HubSpot
+   edit** (no code, no redeploy).
+3. No user-facing string is inline 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.
+5. Content is fetched from **HubSpot at runtime** through the **`CampaignContentProvider` seam** (§5.2),
+   with a `DEFAULT` safety-net fallback, so marketing edits copy without a developer or a redeploy.
 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.
@@ -197,7 +198,7 @@ the bundle carries the UUID so a slug maps to the right campaign for logging.
 | 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. |
+| Content model | **Runtime, HubSpot-owned** | Content store = **HubSpot** (decided over Contentful: the site's content shape is stable / not frequently restructured, so HubSpot's flat-modeling limits are acceptable, and the API integration is trivial — confirmed in `info`, §5.2). Campaign content is authored by marketing in HubSpot and fetched **by slug at runtime**; **no campaign content in the repo, no redeploy to change copy**. Served behind the `CampaignContentProvider` seam with a `DEFAULT` fallback. 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. |
@@ -230,31 +231,52 @@ Port approach:
 > `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:
+**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
+restructured, which it is not.
+
+**Why HubSpot (rationale for the team):**
+- **Marketing already operates there.** The contact database, campaigns, outreach, lists, and workflows
+  all live in HubSpot. Content sits with the team that authors it, and we reuse the existing
+  go-to-market engine instead of standing up a parallel system.
+- **The campaign model already exists.** The old BDR site (`info`) already uses HubSpot for lead
+  sourcing, known-visitor personalization, and **campaign attribution** (`hsContactId` / `hsCampaignId`
+  → Toga). Campaign content keys naturally off that same campaign concept, and content + attribution
+  stay in one system rather than split across two.
+- **The API call is trivial.** Reading from HubSpot is a ~15-line server-side fetch proxied by a Next
+  route handler (proven in `info`; the token never reaches the browser). The same pattern serves any
+  HubSpot read, HubDB included. No new infrastructure.
+- **No new vendor.** HubSpot is already in the stack and paid for; Contentful would add a SaaS contract
+  and a second integration with no offsetting benefit given the stable content shape.
+- **Trade-off we are accepting:** HubSpot is not a purpose-built structured-content CMS, so richly
+  nested content and non-dev editor UX are weaker than Contentful — acceptable here because the content
+  shape is stable (§9.10 tracks how we model it).
+
+**Campaign content lives in HubSpot, authored by marketing, and is fetched by slug at runtime** — not
+in the repo, no redeploy to change copy. One seam makes this true:
 ```ts
 interface CampaignContentProvider {
-  resolve(slug: string | undefined): Promise<CampaignBundle>; // returns the safety-net fallback if unknown/unreachable
+  resolve(slug: string | undefined): Promise<CampaignBundle>; // always returns a valid bundle (DEFAULT if unknown)
   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.
+// Primary:  HubSpotContentProvider — runs server-side (page server component / route handler); reads
+//           content from HubSpot (§9.10 mechanism), maps it to a CampaignBundle, 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.
+`resolve(slug)` runs on the server during render (SSR), so the fetch + 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 page stays SEO-friendly). Components consume the resolved bundle via
+`useCampaign()`; they never see HubSpot or the provider.
 
 > **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.
+> "Campaigns" tool is built for attribution, not rich structured copy, so this 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 drives the fetch + the `CampaignBundle` mapping and needs confirmation with whoever
+> owns the HubSpot instance before the content layer (Phase 1) is built.
 
 ### 5.3 Campaign as data, components as renderers
 Follow the TOGA config-driven precedents (`toga25-supply` `useClientFields`; `toga2-commerce` Cart
@@ -289,13 +311,11 @@ safety-net `DEFAULT`.
 (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.
+**4. The slug drives a runtime fetch of the content from HubSpot:** 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 (SEO-friendly), and marketing edits appear on the next revalidation with no
+redeploy. An unknown/missing slug falls back to the `DEFAULT` bundle so the funnel never fails to render.
 
 **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
@@ -343,11 +363,10 @@ never blank. Prune unused slots per the campaigns actually shipped (the default
 ---
 
 ## 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.
+This is the shape the app consumes, and **the stable contract between HubSpot and the components** —
+components only ever read this. The server maps HubSpot fields into this shape (that mapping layer is
+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
@@ -403,7 +422,7 @@ bdr/
       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)
+      schema.ts                            # CampaignBundle types (the stable 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)
@@ -431,11 +450,11 @@ so fidelity should be near-exact.
   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 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` 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.
@@ -443,7 +462,8 @@ so fidelity should be near-exact.
   (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.
+  Call Now, Schedule, Success, Welcome/WelcomeStep2/EarlyAccess, StepRail. All copy comes from the
+  HubSpot-resolved bundle (no inline strings in components).
 - **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
@@ -459,12 +479,13 @@ so fidelity should be near-exact.
 
 ---
 
-## 9. Open questions (leadership + HubSpot owner). Most do not block early work; **§9.10 gates Phase 1**.
+## 9. Open questions (leadership + HubSpot owner). Most do not block early work; **§9.10 gates the content layer**.
 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).
+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).
 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
@@ -478,15 +499,15 @@ 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 (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. **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.
 
 ---
 
@@ -530,4 +551,5 @@ so fidelity should be near-exact.
 - [ ] Pixel-perfect parity pass against the mockup screens + screenshots.
 
 ## Change history
+- 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-content-model.md

@@ -6,7 +6,7 @@ project: AI-BDR
 client: shared
 type: feature
 status: draft
-updated: 2026-07-08
+updated: 2026-07-13
 owners: [tcox]
 files:
   - bdr/src/content/schema.ts
@@ -25,11 +25,16 @@ related:
 ## 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.
+AI-BDR product** documented in `../architecture.md` — it is the front door of that existing
+product, not a standalone system. It is a **Next.js (App Router) + TypeScript** app living
+in its own code repo, `bdr`. 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.
+
+**Framework:** Next.js (App Router) + TypeScript is the locked choice because the site is
+highly public — SSR + SEO matter, and Next's server (server components + route handlers)
+natively hosts the secret-bearing HubSpot/Toga calls (an earlier React/Vite SPA idea was
+dropped). It also matches the `info` repo, so `info`'s patterns port directly.
 
 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
@@ -47,7 +52,19 @@ Every campaign is a **serializable data bundle** (`CampaignBundle`) keyed by a s
 `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.
+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).
 
 Config-driven, per TOGA precedent (`toga25-supply`'s `useClientFields`,
 `toga2-commerce`'s Cart C1–C7): components are **pure renderers of a bundle**; there is
@@ -141,6 +158,12 @@ right campaign for logging.
   `var(--accent)` (+ derived `--accent-fill`); never hardcode an accent value.
 
 ## Change history
+- 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
+  API, no new vendor; stable-content-shape trade-off accepted); reinforced no-hardcoding
+  (HubSpot-owned, fetched by slug from the start); confirmed same-product / front-door framing
+  (not standalone). Still a draft. (tcox)
 - 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

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

@@ -7,6 +7,7 @@
 | [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 |
 | [Compass MITS PO → SO Item Linking](features/mits-po-to-so-item-linking.md) | 2.0 | MITS sends Compass inbound Purchase Orders (`POST /v2/purchase-orders`) against a Sales Order (`mitsSalesOrder`). | _underscore/Model/Compass/PurchaseOrder.php, worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php |
 | [Compass MITS PO Transmission to Vendors](features/mits-po-transmission-to-vendors.md) | 2.0 | The 1.0 worker cron `2_transmit_mits_purchase_orders_to_vendors.php` transmits Compass PurchaseOrders to their vendors (Office Depot, Strategic Systems, Compass | worker/crons/toga2/compass/workflow/2_transmit_mits_purchase_orders_to_vendors.php, library/app/client/compass.php |
+| [Compass MR/MA Order Auto-Approval & Status Gate](features/mr-ma-order-approval-and-status.md) | 2.0 | Compass **MR** and **MA** sales orders are system-generated from the MITS / Office Depot EDI pipeline (they do not originate as user-entered SA orders) and must | _underscore/Model/Compass/SalesOrder.php, _underscore/Model/Compass/PurchaseOrder.php, worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php |
 | [Compass USA](profile.md) | 2.0 | Compass USA is a TOGA client running a multi-tier supply-chain commerce operation. |  |
 | [Compass Cross-Kit Bundle Corruption — Detection & Repair](workflows/cross-kit-bundle-corruption.md) | 2.0 | A frontend regression in `toga2-commerce`'s edit-order bundle submission mis-attributed bundle (kit) line items and **fees/warranties** to the **wrong kit**, pe | src/api/syncSalesOrderItemsFromLocalStorageCartToApi.ts |
 | [Compass ODP Order Pipeline to NetSuite (numbered worker crons)](workflows/odp-order-pipeline-to-netsuite.md) | 1.0 | The end-to-end **Compass Office Depot (ODP) order → NetSuite** pipeline as it actually runs through the 1.0 `worker` crons under `worker/crons/toga2/compass/`, | worker/crons/toga2/compass/workflow/1_transmit_compass_sales_orders_to_mits.php, worker/crons/toga2/compass/workflow/2_transmit_mits_purchase_orders_to_vendors.php, worker/crons/toga2/compass/edi/1_download_edi_s3_create_po_toga.php, worker/crons/toga2/compass/workflow/5_create_netsuite_sales_orders_from_office_depot_purchase_orders.php, library/app/client/compass.php |

package/knowledge/clients/compass-usa/features/mits-po-to-so-item-linking.md

@@ -6,8 +6,8 @@ project: _Underscore
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-06-16
-owners: ["jcardinal"]
+updated: 2026-07-13
+owners: ["jcardinal", "rgirish"]
 files:
   - _underscore/Model/Compass/PurchaseOrder.php
   - worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php
@@ -40,6 +40,15 @@ production data-integrity bug.
   `createdFromSalesOrderItem`, and deliberately **aligns** SO and PO `lineNumber`s. It does
   NOT build the item bridge — so the `postPost` lineNumber-match pass is the **only** (and
   correct) MR linking mechanism.
+- **MA orders — item population in the ODP PO import cron:** the 3a cron
+  (`worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php`) parses ODP
+  EDI 850 POs. Its "Non-SA order handling" block creates the Compass **MA** sales order. Line
+  items are attached to the Compass SO **only in the new-SO branch**, from `$purchaseOrder['items']`
+  (`partNumber` + `UUID_ITEM_CATALOG` Compass catalog + `qtyOrdered` + `unitPrice`), mirroring the
+  ODP-facing SO item payload built lower in the same cron. The item-linking block that maps ODP
+  items back to the Compass side runs only `if (… == 'SA' || … == 'MR')` — MA is excluded there
+  because SA/MR originate in Compass (their Compass SO+items pre-exist) whereas MA is
+  ODP-originated, so nothing else would populate it.
 
 ## Data model
 - `SalesOrderItems_PurchaseOrderItems` (`Client_Compass`): `uuid`, `salesOrderItemId`,
@@ -115,7 +124,22 @@ USA and Canada share the parent handler unchanged.
   off-by-one bridge fingerprint (a `SalesOrderItems_PurchaseOrderItems` PO item linked to two
   adjacent SO items). Only SA132763 was remediated; a broader reviewed backfill is pending.
 
+- **Empty MA orders (fixed 2026-07-13 — forward only).** The 3a cron's new-SO branch created MA
+  Compass sales orders with **no** `salesOrderItems`, because item population lived only on the
+  ODP-facing SO and the back-linking block excludes MA (`if (… == 'SA' || … == 'MR')`). Empty MA
+  (and MR) shells then stick at "Pending Initial Approval" because Compass `_status` gates on
+  approvals first — see
+  [MR/MA Order Auto-Approval & Status Gate](mr-ma-order-approval-and-status.md). **Fix:** build a
+  `salesOrderItems` array from `$purchaseOrder['items']` in the new-SO branch (partNumber +
+  `UUID_ITEM_CATALOG` + qtyOrdered + unitPrice), mirroring the ODP SO item payload. Only the
+  new-SO branch changed; the SO-already-exists branch was intentionally left alone. `php -l`
+  passes. This stops NEW empty MA orders; it does **not** repair the 192 historical empties (which
+  need item backfill from the sibling ODP SO first).
+
 ## Change history
+- 2026-07-13 — Fixed empty MA orders: the 3a ODP-PO-import cron's new-SO branch now builds
+  `salesOrderItems` from the 850 PO items (the MA back-linking block excludes MA by design).
+  Forward-only; 192 historical empties still need item backfill. (rgirish)
 - 2026-06-16 — Found and fixed a SECOND source of cross-part bridge links: the Office Depot
   worker cron `3a_import_office_depot_purchase_orders.php` paired API-returned PO items to SO
   items by array index; now pairs by lineNumber. Remediated SA132763's spurious bridge +

package/knowledge/clients/compass-usa/features/mr-ma-order-approval-and-status.md

@@ -0,0 +1,124 @@
+---
+title: Compass MR/MA Order Auto-Approval & Status Gate
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: compass-usa
+type: client-feature
+status: active
+updated: 2026-07-13
+owners: ["rgirish"]
+files:
+  - _underscore/Model/Compass/SalesOrder.php
+  - _underscore/Model/Compass/PurchaseOrder.php
+  - worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php
+related:
+  - mits-po-to-so-item-linking.md
+  - ../workflows/odp-order-pipeline-to-netsuite.md
+  - ../workflows/order-lifecycle-and-data-integrity.md
+  - ../../../2.0/apps/_underscore/features/item-fulfillment-stage-lifecycle-and-order-status.md
+---
+
+## Summary
+Compass **MR** and **MA** sales orders are system-generated from the MITS / Office Depot EDI
+pipeline (they do not originate as user-entered SA orders) and must **skip human approval
+entirely**. Compass's `_status` calculated field gates on **approvals FIRST**: if any stage of
+the active `ApprovalTemplate` has no `ApprovalDecision`, `_status` returns the pending-stage slug
+(`pendingInitialApproval`) *before* it ever evaluates fulfillment. So an MR/MA order that has an
+`Approval` row but no decisions is stuck at "Pending Initial Approval" regardless of shipment.
+
+Two independent root causes produced the stuck-order population, and both are addressed at the
+source (auto-approval + item population), **not** in the status SQL.
+
+## Key files / entry points
+- **`_underscore/Model/Compass/SalesOrder.php`**
+  - `_status` calculated field — approval gate runs before the shipped-only fulfillment machine
+    (see [IF stage lifecycle & order status](../../../2.0/apps/_underscore/features/item-fulfillment-stage-lifecycle-and-order-status.md)
+    for the fulfillment half).
+  - `postPost` — the `if ($isMrOrder)` block loops `foreach ([1,2] as $step)` and issues two
+    `internalApiRequest('POST', '/approval-decisions', …)` with `isApproved=true`,
+    note `'Auto-approved: MR order'`. **Went live 2026-06-03.**
+- **`_underscore/Model/Compass/PurchaseOrder.php`** — MR handling (`handleMrOrder`); MR/MA order
+  detection.
+- **`worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php`** — the
+  hourly ODP 850 import that creates MA orders (see the item-population fix in
+  [MITS PO → SO Item Linking](mits-po-to-so-item-linking.md)).
+
+## How it works
+### The approval gate (why empty + un-decided orders stick)
+Prod `Client_Compass` has one active `ApprovalTemplate` (id 1, `salesOrders`) with two stages —
+stage 1 = `step1` = `pendingInitialApproval`, stage 2 = `step2` = `pendingApproval`;
+`APPROVAL_DECISION_TYPE = 1`. The base `_Model_Client_SalesOrder::postPost` creates an `Approval`
+row on **any** order whenever an active template exists. Compass `_status` then requires an
+`ApprovalDecision` for every active-template stage before it will look at fulfillment. No
+decision on a stage ⇒ `_status` short-circuits to that stage's slug.
+
+### Auto-approval (the intended MR path)
+`_Model_Compass_SalesOrder::postPost` auto-approves MR orders by POSTing an approval decision for
+each of the two stages (`isApproved=true`). `_status` only checks `isApproved` on the decision —
+never the `assignedToUserId` / `decidedByUserId` columns — so a system decision with NULL user
+columns is fully valid.
+
+## Client variations
+- **MR** orders originate in Compass; their Compass SO + items pre-exist. Auto-approval covers them
+  from 2026-06-03 onward.
+- **MA** orders are **Office-Depot-originated** (created by the 3a cron) and were **never**
+  auto-approved — the `isMrOrder` check only matches numbers starting `MR`, so MA falls through
+  the gate. MA orders were additionally created as **empty shells** (see below).
+
+## Gotchas / known issues
+- **The stuck orders are EMPTY (zero `SalesOrderItems`).** All stuck MR+MA orders (and their linked
+  Compass PO) have no line items — the real line items live on a sibling **Office-Depot-facing SO**
+  (`customerId = OfficeDepot`) reachable via `SalesOrders_PurchaseOrders → PurchaseOrders_SalesOrders`.
+  A fulfilled-short-circuit in `_status` therefore does **nothing** for them (nothing to fulfill).
+- **Do NOT "fix" this in `_status`.** A speculative fulfilled-short-circuit (plus an extracted
+  `_isFullyFulfilledSql` helper) was added and then **reverted** this session: because the stuck
+  orders are empty, the short-circuit never fires. The real fix is item population + approval
+  decisions at the source.
+- **MA is still creating stuck orders until the item-population cron fix ships** — see
+  [MITS PO → SO Item Linking](mits-po-to-so-item-linking.md). Auto-approval for MA is not yet
+  implemented (the `isMrOrder` check does not match `MA`).
+
+## Prod status buckets (2026-07-13)
+| Type | NO_APPROVAL (correct — pre-template, gate falls through) | APPROVAL_NO_DECISION (STUCK) | FULLY_APPROVED |
+|---|---|---|---|
+| MR | 5922 (Sep 2025–Jan 2026) | 2927 | 583 |
+| MA | 176 | 192 | 0 |
+
+- The 5922 MR + 176 MA `NO_APPROVAL` orders pre-date the active template; they have **no**
+  `Approval` row, so `_status` skips the gate and reads correctly. They must **NOT** get an
+  `Approval` created.
+- Total stuck: **3119** (2927 MR + 192 MA). A CSV of all 3119 (type, orderNumber, orderUuid,
+  dateCreated, compassPurchaseOrder, officeDepotSalesOrder_sourceOfItems) was handed to
+  ops/integration for remediation.
+
+## Historical MR remediation (approval-decision backfill)
+A one-off, idempotent, transaction-wrapped SQL backfill unsticks the 2927 historical MR orders by
+inserting the two auto-approval `ApprovalDecisions` (one per stage, mirroring `postPost`'s
+`foreach([1,2])`). Each row: `approvalTemplateStageId` 1/2, `approvalDecisionTypeId=1`,
+`isApproved=1`, `assignedToUserId`/`decidedByUserId` NULL, note
+`'Auto-approved: MR order (historical backfill)'`, `dtDecision NOW()`.
+
+Safe scoping baked in — **decisions only, never Approvals**:
+- **`INNER JOIN Approvals` (`recordId=14`)** so it can only add decisions to orders that *already*
+  have an `Approval`. Structurally it cannot touch the `NO_APPROVAL` orders (which are already
+  correct and must not get an Approval).
+- **Per-stage `NOT EXISTS`** ⇒ idempotent / re-runnable.
+- Includes a PREVIEW count query (prod: 2927 orders → 2927 step-1 + 2927 step-2 rows). Workflow:
+  run on beta, verify, COMMIT; then production.
+- Does **not** create Approvals; does **not** handle MA (MA orders are empty and need item backfill
+  from the sibling ODP SO first).
+
+## Change history
+- 2026-07-13 — Diagnosed the MR/MA "Pending Initial Approval" stuck-order bug: `_status` gates on
+  approvals before fulfillment; MR orders created 2026-02-04..2026-06-02 got an Approval but no
+  decisions (auto-approval only live from 2026-06-03), and MA orders were never auto-approved and
+  are empty shells. Reverted a speculative `_status` fulfilled-short-circuit (stuck orders are
+  empty, so it never fires). Built an idempotent, decisions-only MR approval-decision backfill
+  (2927 orders) scoped by `INNER JOIN Approvals` so it can never create an Approval, and a CSV of
+  all 3119 stuck orders for ops. MA item population fixed separately at the 3a cron. (rgirish)
+
+## Related docs
+- [Compass MITS PO → SO Item Linking](mits-po-to-so-item-linking.md) — the 3a cron item-population fix that stops NEW empty MA orders.
+- [Compass ODP Order Pipeline to NetSuite](../workflows/odp-order-pipeline-to-netsuite.md)
+- [IF Stage Lifecycle & Order Status](../../../2.0/apps/_underscore/features/item-fulfillment-stage-lifecycle-and-order-status.md) — the shipped-only fulfillment half of Compass `_status`.

package/package.json

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