AI Pipeline

No inputs. The tool always works on the signed-in user.

1. Loads the user and profile on the read-only connection (tool_executor.ts queryUserProfile).
2. Computes account age in days from users.created_at.

• name, accountCreated, accountAgeDays

• No phone, address or other contact PII by design.

No inputs. The tool always works on the signed-in user.

1. Reads bank_accounts where is_active, with the owning bank_connection (queryBankAccounts).
2. Returns the official account name when the bank provides one, otherwise the display name.

• per account: id, name, accountType (depository / credit / loan), accountSubtype, institutionName, currentBalance, availableBalance, currency

• For credit and loan accounts currentBalance is what is OWED, not cash. The Coach has to read accountType to tell them apart.
• Balances are as of the last Plaid sync, not live.
• No asset values (home, car), so it cannot support a true net-worth figure.

1. Reads transactions for the user, newest first, with merchant, category and account (queryTransactions).
2. Hides a pending row once its posted twin exists (excludeSupersededPending, the same rule as the app's transaction list), so each real charge appears once (5c, 2026-10-04).
3. Applies whichever filters are given: account id, start/end date, category id, merchant name (case-insensitive contains), min/max amount, debit/credit.
4. Returns at most limit rows: default 50, never more than 100.

• per transaction: id, amount, description, transactionDate, transactionType, isPending (true = not posted yet, never a duplicate), merchant, category, accountName, institution

• Capped at 50 rows by default (100 max) with NO total count, so a "total" summed from the list can silently miss older rows.
• Pending rows with no posted twin yet are still listed (isPending=true); they are real charges awaiting settlement.
• Filtering by category needs a numeric categoryId, and no tool lists category ids.

1. Window: today to today + daysAhead (default 30), in the user's timezone (queryBillsPredictions).
2. bills[]: active bill/subscription recurring_streams paid from checking (isMoneyMathEligible), expanded to every occurrence inside the window by cadence (occurrencesWithin).
3. cardPayments[]: each card's statement amount due inside the window, from computeSafeToSpend's ccObligations — the same ladder Home's Recurring Expenses merges in (5c fixes finding #1).
4. subscriptionsBilledToCards[]: subscriptions charged to a card. Real subscriptions, but already inside that card's payment, so excluded from totalDue.
5. totalDue = bills + cardPayments.

• window {from, to, timezone}
• bills[] {id, predictedAmount, predictedDate, confidence (0–1), merchant, recurrencePattern, streamType}
• cardPayments[] {card, amountDue, dueDate, basis, minimumPayment}
• subscriptionsBilledToCards[] (same shape as bills), totalDue, note

• unpaidOnly is declared but ignored.
• A subscription whose predicted date has already passed is not listed (it may have lapsed); recurring_charges flags those as likelyEnded.

1. Resolves the authoritative next payday with resolvePayday (the same helper Home uses): the user's payday setting wins on cadence, the income stream wins on amount.
2. paydays[]: every payday in the window, walking the same schedule forward with resolvePayday (5e, 2026-10-04: "what comes in next month?" saw one deposit).
3. upcoming[]: every occurrence of each active income stream in the window (occurrencesWithin), excluding transfer-ins, refunds and card "payment received" credits; partOfPaycheck marks user-confirmed slices already inside a payday amount.

• resolved: nextPayday, predictedAmount, frequency, source, confidence, band (low/medium/high), isFallback, amountBasis, daysUntilPayday, isPaydayToday
• paydays[]: date, predictedAmount, amountBasis
• upcoming[]: id, source, predictedAmount, predictedDate, confidence, frequency, partOfPaycheck
• window {from, to, timezone}, note

• A low-confidence or fallback payday is an ESTIMATE. The Coach must not state it as fact (red line 10).

No inputs. The tool always works on the signed-in user.

1. Calls computeSafeToSpend (safe_to_spend_service.ts) in the user's timezone, the single engine shared with GET /predictions/safe-to-spend.
2. The engine projects the checking balance day by day: L(d) = cash + income landing on or before d − obligations on or before d. Obligations are bills, loans, card payments due, essentials and estimated everyday "habits".
3. Horizon = the latest of: the day before the runway payday, month end, week end (v5.6). The runway payday is the next payday, except ON payday, when it is the following one, so payday never collapses the runway to one day.
4. Daily pace = the lowest L(d) ÷ (d+1) across the horizon, so spending at that pace never dips below zero on any day.
5. Each window (today, this week, until payday, this month) = pace × the days in that window. If the pace is negative (a shortfall), every window equals the deficit instead.
6. projectSafeToSpendForCoach reshapes the result so every number Home shows is reachable from one tool call.

• today / thisWeek / untilPayday / thisMonth: amount, daysInWindow, perDayInWindow, moneyOut {billsUtilsSubs, loans, plannedSavings, ccDue, essentials, habits, total}, bills[], income[], cardPaymentsHeldBack[] and cardPaymentsAfterWindow[] {card, amount, dueDate} (round-2 fix: computed by splitCardPayments so the Coach quotes which payments a window already covers instead of comparing dates)
• dailyBudget, daysUntilPayday, isPaydayToday, nextPayday, runwayPayday, spendableBalance
• floor {date, value, bindingBill}, shortfall {isShortfall, shortfallAmount, earliestShortfallDate}
• ccObligations[] per card {amountDue, basis, dueDate, minimumPayment, purchaseApr, totalBalance}, ccNextCycleWarning, creditCardDebt (display only)
• essentials, typicalDiscretionary, accountsIncluded, setAsideAccounts, loansExcluded, lastSyncedAt

• A card payment is subtracted only once its due date falls inside the window, so "already accounted for" is wrong for a window that ends before the due date. On payday the runway reaches the day before the next paycheck; statements due after that are left to that paycheck (owner decision 5f).
• creditCardDebt is the full revolving balance for display. It is NOT subtracted; only the statement amount due is.

1. Resolves the window in the user's timezone: today, last 7 days rolling, or month to date (default). A custom start/end overrides it; an end without a start looks back 30 days (getSpendingByCategory).
2. Fetches posted rows only (pending excluded) with the Spending tab's shared SQL (fetchSpendingDetailRows).
3. projectSpendingForCoach partitions income, transfers and card-bill payments out of spending, nets refunds per category, and sums positive categories into totalSpent.

• window {timeframe, startDate, endDate, timezone}, totalSpent, transactionCount
• categories[] {category, total, pctOfTotal, transactionCount, subcategories[]}
• excluded {income, transfersIn, transfersOut, ccPayments}, uncategorized {total, transactionCount}

• Month to date is a partial month. Comparing it with a full previous month needs saying so.
• Finding #5. A NEGATIVE uncategorized bucket is money coming in, not refunds and not "hidden spending". Before 2026-10-03 every paycheck and Zelle/Venmo transfer landed there because Plaid v2 codes were missing from Tide's categories, so income read $0. That root cause is fixed; any rows still uncategorized carry the deliberately unmapped OTHER_OTHER code.

1. insightType picks the analysis (default spending_trends). months is capped at 12, default 3 (getFinancialInsights).
2. spending_trends: the same true-spending monthly totals as the Home chart, calendar months in the user's timezone.
3. The other three read the same rows: transactions in the window with superseded pendings hidden, shaped for the pure rules in coach_insights.ts (5c, 2026-10-04).
4. largest_expenses: the 10 biggest real expenses (isExpense: no transfers, income or credit-card payments).
5. recurring_charges: billsAndSubscriptions[] and income[] (billedToCard, likelyEnded = expected charge over 7 days overdue) plus repeatedTransfers[] — the same transfer amount to the same counterparty 2+ times, grouped by normalized description because the merchant normalizer mints a new merchant per transfer row.
6. anomalies: candidates from the last 30 days judged against the window's history. Non-habitual charges above category mean + 2σ (unusually_large); a habitual merchant (3+ charges) only when over 3× its median AND over 1.5× its previous highest (large_for_this_merchant); more charges at one merchant within two days than usual — 3+, or double its busiest earlier two days for a habitual merchant (rapid_repeat); two identical posted charges at one merchant on one day (identical_same_day, to ask about).

• spending_trends: months[] {month, total, transactionCount}
• largest_expenses: window, excludes, transactions[] {amount, description, date, merchant, category}
• anomalies: window {historyFrom, candidatesFrom}, transactions[] {amount, description, date, merchant, category, reason, detail}, note
• recurring_charges: window, billsAndSubscriptions[], income[], repeatedTransfers[] {direction, counterparty, amount, count, dates, typicalGapDays}, notes

• Anomaly rules are heuristics, not fraud detection: none of these flags means fraud on its own.
• Repeated transfers need the same amount to the cent; a transfer that varies in amount is not grouped.