> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myfundingmachine.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ai overview rework

# AI Overview rework — domain model and build plan

Status: planned (Aug 2026). Decided in a grilling session with Kevin; supersedes the
original post-confirm design that was discussed in the same session (see Decision log).

## What the AI Overview is (final shape)

A **pre-selection strategy coach** for the operator. Generated on demand, after
underwriting completes and **before** product selection, from a card on the `/contact`
Overview tab placed directly above the Product Decisions panel. Its job is
cross-product strategy sequencing the engine does not do — e.g. "remove the inquiries
not tied to open accounts first, then use the term-loan proceeds to pay down these
three cards, which lifts utilization under 30% and materially improves the 0% card
outcome" — ending with an explicit handoff: *select these products in Product
Decisions and begin the funding workflow.*

Benchmark profile: high score, heavy encumbrance (many inquiries, large paydowns).
Golden test case: contact `RY9HEzVryPbYyMNbpmQW`, location `isqlsHX3ljyFgKYAxPTQ`
(Toan Nguyen) — great score/pre-approval, 10 inquiries in 12 months, \$20k+ paydowns.

## Trigger and billing contract

* **Manual generate button, available to every location. No settings.** The button is
  the consent for the charge; the tooltip states the price. No operator toggle, no
  admin kill-switch, no schema change. The admin `aiOverviewEnabled` flag stays
  retired-in-place (it gates nothing today and continues to gate nothing).
* Credit pull charges `creditPullPrice` ($5 default) at pull time. AI Overview charges `aiOverviewSurcharge` ($2 default) at click time, on cache miss only. These are and
  remain fully separate charges (`tests/billing.test.ts` locks this in). There is no
  combined \$7 charge.
* Cache hits are free; the \$2 buys the overview for that file's data-state
  permanently. Deliberate Regenerate clicks are each billed. Admin/internal locations
  (`creditPullPrice === 0`) generate free.
* **Never auto-generated.** Not at underwriting time, not on auto (webhook) pulls.
  Auto-generation would charge without operator intent and would resurrect the need
  for a per-location opt-in setting. If demand appears later, an opt-in
  "auto-generate on manual pulls" location setting is an additive follow-up.
* If the charge succeeds but the LLM fails, the charge is not auto-refunded (existing
  behavior); the card shows a non-blocking error with a retry.

## Roles and responsibilities at every step

| Step | Operator (closer) | Client | System |
| - | - | - | - |
| 1. Credit pull (manual) | Initiates pull from `/contact`; confirms client consent | Provides consent, SSN/address | Charges \$5 before the bureau call; reverses on failure; runs the underwriting engine; stores results |
| 2. Credit pull (auto, webhook) | Nobody — no operator present | Submitted the lead form | Charges $5 only. Never generates an AI Overview. (The dead $7 wallet pre-check is deleted in PR 1.) |
| 3. Report review | Reads engine decision, ranges, categories on the Overview tab | — | Presents engine outputs (decision, ranges, paydown recommendations) as the source of truth |
| 4. Generate AI Overview (optional, \$2) | Clicks Generate on the card above Product Decisions | — | Charges \$2 on cache miss, runs the strategy-coach prompt, renders the dual-section result; cache hits are free |
| 5. Strategy consumption | Reads the operator section; relays the client-safe summary; uses the recommended sequence to choose products | Executes their lane: inquiry disputes, paydowns with dollar amounts, document gathering, no new applications | Keeps the cached overview free to re-view |
| 6. Product selection + Confirm | Selects Creative / Revenue-Based products (informed by the overview) and clicks the plain **Confirm** button | Has expressed goals (amount, timeline) in prior conversation | `confirmFundingPlan` commits atomically and swaps the card to the Funding Workflow. Confirm never involves AI billing. |
| 7. Data changes | Sees the "Outdated" badge; decides whether to pay \$2 to regenerate | — | Marks the overview stale when underwriting data changes (dataHash mismatch); never auto-charges |
| 8. Pricing config | — | — | Admin sets `creditPullPrice` and `aiOverviewSurcharge` in Billing Config; no feature toggles |

## Output contract (PR 2)

Dual-section output, stored on `underwritingResults.aiOverview` (widened with optional
fields for backward compatibility with cached rows; cache namespace bumped so
old-format caches regenerate naturally — same pattern as `borderline-v1`):

1. **Operator section**: the strategy narrative — sequenced plan with per-account
   dollar amounts, which inquiries are plausibly removable, how term-loan proceeds
   interact with card-stacking outcomes, and the product-selection recommendation.
   Steps split by owner (client lane / operator lane).
2. **Client-safe summary**: relayable verbatim or via the funding plan email later.
   Says "CRM", never GHL; never mentions 7 Figures (existing sanitizer extended).

Prompt inputs to add (engine computes these but never sends them today):
per-account balances/limits, per-account `paydownRecommendations` dollar amounts,
the inquiry list with open-account association (may need a small deterministic
matching helper so the AI cites facts rather than guessing), decline/status codes,
and the estimated ranges per track. The engine remains the source of truth: the model
may only cite dollar amounts and thresholds present in its input.

The `computeDataHash` inputs must grow in lockstep with the prompt inputs, or stale
overviews will survive data changes.

Borderline files (`requiresManualReview`) keep their separate skeptical prompt.

## Build phases (one branch + PR each, cut from `origin/main`)

1. **PR 1 — cleanup**: delete the dead `$5 + $2` wallet pre-check in the new-lead
   webhook and `lib/webhooks/auto-credit-pull-core.ts` (it checks $7 while the system
   only ever charges $5); update billing tests; land this doc.
2. **PR 2 — strategy-coach prompt**: new system prompt + enriched inputs + dual
   output schema + cache-namespace bump + Toan Nguyen golden fixture (read-only data
   pull into a test fixture). Consider a model bump from `openai/gpt-4o-mini` and a
   higher token ceiling for the longer plan. Verifiable without UI: iterate against
   the golden fixture and the existing `/api/ai-overview/generate` route directly.
   Lands before the UI so the card is designed once, against the final output
   contract, instead of being built for the old shape and reworked.
3. **PR 3 — placement + generate flow**: AI Overview card on the `/contact` Overview
   tab above Product Decisions, with ungenerated (explains value + price),
   generating, error-with-retry, generated, and Outdated states. Renders the dual
   output contract from PR 2; reuses the existing `/api/ai-overview/generate` charge
   path unchanged. Note: `AiOverviewSection` currently renders only on surfaces that
   never receive `contactId`/`locationId` (why the feature is invisible today); the
   contact page uses `CreditReportsView`, which never included it.

Deferred (explicitly out of scope now): machine-readable action codes with one-click
buttons; closer talk-track; post-confirm divergence note ("selection contradicts
recommendation"); opt-in auto-generate setting.

## Decision log (grilling session, Aug 6 2026)

* Post-confirm trigger with "Confirm and generate AI Overview" button — **superseded**:
  the overview's job moved from execution plan to pre-selection strategy coach after
  the Toan Nguyen example showed the highest-value output is sequencing advice that
  informs product selection.
* Operator toggle in Settings + admin kill-switch — **superseded**: with a manual
  button, the click is the consent; no settings are needed.
* "AI Overview settings" letting operators choose generation timing — **rejected**:
  two prompts/caches/placements for one feature; pick one moment.
* Auto-generate at underwriting time — **rejected**: charges without operator intent,
  effectively the \$7-per-pull model; also bills dead/duplicate/webhook files.
* Confirm always succeeds independently of AI billing — **retained** (now trivially
  true since Confirm no longer touches AI).
* Dual output (operator + client-safe) — **retained**.
* Stale-on-data-change with paid regenerate, never auto-charge — **retained**.
* No AI Overview on auto pulls — **retained**.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.