Summary

After two scope iterations, the final shape: the "Archera Insurance" CTA appears in the Purchase modal and the Plan-creation modal — the two high-intent moments where the user is about to commit money — and links through to education pages explaining what Archera Insurance is, why it might be useful, and how the integration works. Those pages carry the actual signup link.

Trail of previous direction changes (for context)

• Original (feat(iac): add Archera integration permissions to AWS / Azure / GCP bundles #305): bundle Archera IAM resources into CUDly-generated federation IaC. PR feat(iac): scaffolding for Archera integration perms across AWS/Azure/GCP (closes #305) #310 implemented; closed without merging.
• Second pivot (feat(frontend): Archera Insurance CTA in Purchase + Plan-creation modals + education pages #314 v1/v2, PR feat(iac): shared Archera module + 'Provision Archera Insurance permissions?' bundle checkbox (closes #314) #315): shared Terraform module + scope YAMLs + "Provision Archera Insurance permissions?" checkbox in Settings → Federation Setup. PR feat(iac): shared Archera module + 'Provision Archera Insurance permissions?' bundle checkbox (closes #314) #315 implemented; closed without merging after Archera-side review surfaced three problems with bundling IAM:
  1. External ID in the trust policy is derived from the customer's Archera org ID, which only exists post-signup → bundles can't serve the new-user conversion path.
  2. Archera's Azure integration is an OAuth enterprise-app consent flow, not a custom RBAC role → the Azure piece wouldn't work end-to-end.
  3. Archera already ships pre-filled IaC through their own onboarding → CUDly duplication is a drift surface with no clear owner.
• Third pivot (Settings-checkbox + signup link): rejected before implementation — the Settings panel is the wrong moment; the educational/conversion opportunity is at purchase-time.
• Current (this version of feat(frontend): Archera Insurance CTA in Purchase + Plan-creation modals + education pages #314): modal-level CTA + dedicated education pages.

Scope

1. CTA in the Purchase modal (frontend/src/recommendations.ts — openPurchaseModal flow)

Add a soft, non-blocking CTA inside the existing purchase modal:

💡 Worried about committing? Archera Insurance underwrites commitment-overuse — learn how it works →

(exact copy is at the agent's judgment; keep it brief and non-pushy). Click → opens the Archera-insurance education page (see §3) in a new route or overlay. Doesn't block / interrupt the existing purchase flow.

2. CTA in the Plan-creation modal (frontend/src/plans.ts — openCreatePlanModal / openNewPlanModal)

Same CTA, same target, same copy. The plan-creation flow is also a high-intent moment (user is queueing up multiple purchases).

Both CTAs are unobtrusive (small text + arrow, not a button competing with the primary action), shown by default — no "Provision Archera permissions?" checkbox anywhere; the Settings checkbox direction (from earlier #314 iterations) is dropped.

3. Education pages

A couple of pages that educate users on Archera Insurance:

• Page A — "What is Archera Insurance?" — plain-language explainer: commitment-overuse insurance, when it makes sense, how Archera makes money (referral / sharing-of-savings, whatever the actual model is), why CUDly surfaces this option at all. Short, scannable, 1–2 screens of content.
• Page B — "How the CUDly ↔ Archera integration works" — sequence diagram or step list: user clicks "Sign up" → Archera signup flow → Archera generates pre-filled IaC for AWS/GCP (or runs OAuth consent for Azure) → user applies → Archera starts ingesting cost data. Disclaimers: Archera is a third-party platform, CUDly doesn't generate or hold credentials, etc.

Both pages carry the canonical signup link: https://archera.ai/signup?mode=cudly (referral-tagged for attribution; final URL parameters TBD with Archera).

Routes / surfacing — use whatever pattern the existing CUDly frontend uses for help/info pages. If routing is hash-based (#/archera-insurance), use that; if it's full SPA routes, add /archera-insurance and /archera-insurance/how-it-works (or similar). A pre-existing pattern in the codebase wins over inventing a new one.

Acceptance criteria

• Purchase modal renders the CTA next to / under the existing primary action; click navigates to Page A.
• Plan-creation modal (both openCreatePlanModal and openNewPlanModal paths) renders the same CTA; same navigation target.
• Page A explains what Archera Insurance is, in plain language, with a clear "Sign up at Archera →" link at the bottom.
• Page B explains the integration flow, with the same signup link.
• Both pages link to each other (so a user landing on A can drill into B and vice-versa).
• All new copy is reviewable by @cristim before publication — leave clearly-marked TODO(@cristim): final copy comments where the exact wording matters.
• Frontend tests: render assertions for the CTAs in both modals, navigation behaviour, page content presence, signup-link target=_blank + rel="noopener noreferrer".
• Accessibility: CTAs are real <a> (or <button> if navigating in-app) elements with discernible names; education pages have proper heading hierarchy + skip-to-content link if the pattern exists.

Explicitly NOT in scope

• Settings → Federation Setup checkbox (dropped; was earlier iteration's direction).
• Backend / API / handler changes — none.
• Bundle template changes — none (internal/iacfiles/templates/, iac/federation/, iac/modules/, terraform/environments/<cloud>/archera.tf, scripts/generate-federation-iac.go, scripts/check-archera-parity.sh — none of these get touched).
• Authentication / payment integration — none (signup happens on Archera's side).

Superseded

• feat(iac): add Archera integration permissions to AWS / Azure / GCP bundles #305 (closed as not-planned)
• PR feat(iac): scaffolding for Archera integration perms across AWS/Azure/GCP (closes #305) #310 (closed without merging)
• PR feat(iac): shared Archera module + 'Provision Archera Insurance permissions?' bundle checkbox (closes #314) #315 (closed without merging)

Addendum (2026-05-11) — email surfaces

The CTA mention also lands in two email surfaces, with the same 7-day enrollment window:

Pre-purchase approval email

internal/email/templates.go → purchaseApprovalRequestTemplate (plain text) + purchaseApprovalRequestHTMLTemplate (HTML). Add a brief Archera Insurance mention near the bottom of both, noting that after approval the buyer will have 7 days to enroll if they want commitment-overuse coverage. Link to the education page (Page A).

Post-purchase confirmation email

internal/email/templates.go → purchaseConfirmationTemplate. Add a more prominent mention here — the customer has just purchased, the 7-day enrollment window is now active. Include the signup link directly: https://archera.ai/signup?mode=cudly.

Copy guidance (both templates)

Plain language, no jargon. Something like:

Archera Insurance is available for the commitments above. You have 7 days from each purchase to enroll and cover yourself if usage drops. Learn more: . Sign up: .

Leave TODO(@cristim): final copy review markers.

Test coverage

• internal/email/template_renderers_test.go (or templates_test.go) — render assertions confirming both templates contain the Archera mention + signup-link string.
• Don't break existing snapshot tests; if email templates have golden-output tests, update goldens together.

NOT in scope

• purchaseFailedTemplate — no insurance pitch on a failed purchase.
• scheduledPurchaseTemplate — the pre-purchase scheduled notification is too early to mention the 7-day window (the clock starts at purchase, not at scheduling). Skip.
• riExchangeCompletedTemplate / riExchangePendingApprovalTemplate — RI exchanges are net-neutral on commitment exposure (one RI replaced by another). Skip unless @cristim says otherwise.

Addendum (2026-05-11) — transparency disclosures on education pages

Both Page A and Page B must clearly state two facts so users see the relationship up front:

1. CUDly is fully functional regardless of whether the user purchases Archera Insurance. Nothing in CUDly is gated behind it — recommendations, scheduler, plans, dashboard, history, settings all work identically whether the user enrolls or not.
2. Archera sponsors CUDly's development with a fraction of their insurance revenue. Sharing this is the honest framing for why CUDly surfaces the option at all.

Copy guidance

Lead Page A with a short "Why is CUDly telling me about this?" section that captures both facts in plain language, e.g.:

CUDly works fully without Archera Insurance. Every feature — recommendations, scheduling, plans, the dashboard — operates identically whether or not you enroll.

Why surface this at all? Archera sponsors CUDly's development with a share of their insurance revenue. We surface the option because we think commitment-overuse insurance is genuinely useful for some users, but you should know the financial relationship.

Page B can include a shorter version of the same — one sentence each — under a "Disclosure" subheading, so a user landing on B (without reading A) still sees both facts.

Both blocks need TODO(@cristim): final disclosure copy markers — wording is provisional but the substance (no-gating + sponsorship) must stay.