Phase 7A: Financial Profile + Merchant Intelligence

.claude/CLAUDE.md

@@ -66,6 +66,9 @@ Follow this exactly when starting any phase or feature work:
 1. **Phase plan first.** Write the phase plan in `Phase Plans/Phase_X_Name.md`, matching the
    existing convention (git branch tree, feature checklist, endpoints, schema, Definition of Done).
    List every feature branch the phase needs.
+   **No code in phase plans.** Plans describe what will be built — file names, what each thing does,
+   what endpoints return, what tables exist. Never include Python, SQL, TypeScript, or bash snippets.
+   Code lives in the codebase, not the plan.
 2. **One feature at a time.** Never start a second feature before the current one is fully closed out.
    Create each feature branch off the phase branch automatically — no need to ask.
 3. **Within a feature, one task at a time, TDD style** (`superpowers:test-driven-development`):

Argus Details/product-plan.md

@@ -90,7 +90,7 @@ LangGraph multi-agent pipeline (enrichment + analyst + memory nodes), pgvector R
 
 ---
 
-## Phase 5 — Argus Brain: Skeleton ⬜
+## Phase 5 — Argus Brain: Skeleton ✅
 *Weeks 11–12*
 
 **Goal:** Stand up Argus as living infrastructure early — alive with whatever tools exist today, built to grow as later phases add engines. This is the most important phase in the remaining roadmap; everything after this is Argus gaining new senses.
@@ -111,7 +111,7 @@ LangGraph multi-agent pipeline (enrichment + analyst + memory nodes), pgvector R
 
 ---
 
-## Phase 6 — Daily Intelligence ⬜
+## Phase 6 — Daily Intelligence ✅
 *Weeks 13–14*
 
 **Goal:** Safe to Spend Today and Smart Payment Calendar — the two features users open every morning. Both register as new Argus tools on completion.
@@ -151,33 +151,38 @@ Pages redesigned: login, signup, verify-email, transactions, bills, bills calend
 
 ---
 
-## Phase 7 — Financial Profile + Guardian ⬜
-*Weeks 15–16*
-
-**Goal:** Financial Profile Page with Merchant Intelligence, and Argus Guardian Chrome extension — Argus's first ambient surface.
-
-### Financial Profile Page
-1. Build `GET /profile/overview` — spending breakdown by category, habit streaks, subscription summary, utilization summary
-2. Build `GET /profile/merchants` — all user merchants ranked by total spend with transaction count and trend
-3. Build `GET /profile/merchants/{merchant_id}` — weekly/monthly/yearly spend, frequency heatmap data, cost trend, Argus insight for that merchant
-4. Build Financial Profile page `app/(app)/profile/page.tsx`:
-   - Level 1: spending ring, streaks grid (GitHub-style), subscription logo grid, utilization gauge, biggest spend day chart
-   - Level 2: category drill-down — merchants ranked by spend within category
-   - Level 3: Merchant Intelligence per merchant — charts, heatmap, cost trend, one specific insight. Dynamically generated — only exists for merchants the user actually uses.
-5. Register profile/merchant data as Argus tools
-
-### Argus Guardian (Chrome Extension)
-6. Scaffold Chrome extension — manifest v3, background service worker, content script
-7. Build checkout and product page detection — content script identifies checkout and product pages across major retailers
-8. Build Guardian verdict API — `POST /guardian/analyze` with page context (merchant, detected amount), routes through Argus, returns verdict, Safe to Spend, one-line reason
-9. Build slide-in verdict panel — compact, visual, brand logo, one reason, Safe to Spend, tap to expand
-10. Build native notification trigger — Mac/Windows native notification on checkout detection
-11. Build post-purchase Plaid webhook handler — fires within seconds of transaction, generates impact analysis + recovery options via Argus
-12. Build notification sensitivity settings in main app — quiet hours, minimum amount threshold, notification type controls
-13. Build Guardian status card on dashboard — current highest-priority signal, last updated, active status indicator
-14. Extension settings sync with main app account
-
-**Deliverable:** Financial Profile and Merchant Intelligence live, Argus Guardian intercepting checkout decisions in the browser.
+## Phase 7A — Financial Profile + Merchant Intelligence ⬜
+*Week 15*
+
+**Goal:** Deep spending map — where money goes, which merchants dominate, Argus insight per merchant. Three-level profile page: overview → category → merchant. All data registered as Argus tools.
+
+### Features
+1. `GET /profile/overview` — spending breakdown by category, habit streaks, subscription summary, utilization summary
+2. `GET /profile/merchants` — all merchants ranked by total spend with transaction count and 30-day trend
+3. `GET /profile/merchants/{merchant_id}` — weekly/monthly/yearly spend, frequency heatmap, cost trend, one Argus insight for that merchant + user combination
+4. Financial Profile page `app/(app)/profile/page.tsx` — three drill levels: spending ring + streaks grid + subscription logos + utilization gauge → category merchants list → per-merchant heatmap + trend + insight
+5. Register `get_profile_overview` and `get_merchant_history` as Argus tools
+
+**Deliverable:** Financial Profile live, Argus can answer spending pattern questions in chat.
+
+---
+
+## Phase 7B — Argus Guardian (Chrome Extension) ⬜
+*Week 16*
+
+**Goal:** Argus reaches the browser. Detects checkout and product pages, fires verdict panel within 2 seconds, reacts post-purchase when Plaid webhook fires. Same brain, new surface.
+
+### Features
+1. Chrome extension scaffold — manifest v3, service worker, content script, verdict panel, auth popup
+2. Checkout + product page detection across major retailers — extracts merchant name and amount
+3. `POST /guardian/analyze` — routes detection context through Argus supervisor, returns verdict + reason + recommended card
+4. Slide-in verdict panel injected into detected pages — copper design, one reason, Safe to Spend, expandable
+5. `POST /guardian/webhook/plaid` — post-purchase impact analysis + two recovery options via Argus within 10 seconds
+6. `analyze_purchase` registered as Argus tool — same reasoning callable from chat
+7. Guardian status card on dashboard — last verdict, active status
+8. Notification settings in main app — quiet hours, amount threshold, notification type; extension respects these
+
+**Deliverable:** Guardian intercepting checkout decisions in browser, post-purchase analysis firing automatically, dashboard showing Guardian status.
 
 ---
 

Phase Plans/Phase_6_DailyIntelligence.md

@@ -0,0 +1,160 @@
+# Phase 6: Daily Intelligence
+
+> Weeks 13–14. Goal: ship Safe to Spend (how much money is safe to use today) and Smart Payment Calendar (when to pay what) — the two screens users open every morning.
+
+---
+
+## What This Phase Covers
+
+| Layer | Goal |
+|---|---|
+| Backend engines | Pure Python math — no AI-invented numbers |
+| Celery | Nightly Safe to Spend recompute |
+| API | `/insights/safe-to-spend`, `/insights/pay-timing`, `/calendar` |
+| Argus tools | Register both engines so Argus can answer questions about them in chat |
+| Frontend | Smart Payment Calendar page, Safe to Spend hero on dashboard |
+| Service | Merchant logo fetch + DB cache (Clearbit) |
+
+---
+
+## Git Branch Structure
+
+```
+develop
+└── phase/6-daily-intelligence
+      ├── feature/safe-to-spend
+      ├── feature/pay-timing
+      ├── feature/merchant-logos
+      └── feature/smart-calendar
+```
+
+---
+
+## Global Constraints
+
+- All financial math in plain Python — no AI-invented numbers
+- Every new endpoint requires `get_current_user` auth dependency
+- New tables need RLS enabled + user-scoped policy
+- New Celery tasks must be added to `include` list in `backend/celery_app.py`
+- New routers must be registered in `backend/main.py`
+- Frontend uses design tokens only — no raw Tailwind color utilities
+- Tests mock Supabase via `unittest.mock.patch`; never hit real DB
+
+---
+
+## Execution Checklist
+
+### `feature/safe-to-spend` ✅
+
+**Migration**
+- [x] `backend/migrations/016_safe_to_spend_cache.sql` — `safe_to_spend_cache` table: `user_id UUID PK`, `safe_amount DECIMAL`, `breakdown JSONB`, `computed_at TIMESTAMPTZ`. RLS enabled, user-scoped policy.
+
+**Engine**
+- [x] `backend/engines/safe_to_spend.py` — `compute_safe_to_spend(balance, bills, pay_schedule, buffer_reserve) -> dict`. Logic: balance minus bills due before next payday window (derived from pay_schedule) minus buffer reserve. Clamps to zero minimum. Returns `safe_amount` + `breakdown`.
+- [x] `backend/tests/test_safe_to_spend_engine.py`
+
+**Celery task**
+- [x] `backend/tasks/recompute_safe_to_spend.py` — fetches accounts, bills, pay_schedule for a user, runs engine, upserts result to `safe_to_spend_cache`
+- [x] Added to `celery_app.py` include list + nightly beat schedule (2am UTC)
+- [x] `backend/tests/test_recompute_safe_to_spend.py`
+
+**Endpoint**
+- [x] `GET /insights/safe-to-spend` added to `backend/routers/insights.py` — returns cached row if exists, falls back to live compute if not
+- [x] `backend/tests/test_safe_to_spend_endpoint.py`
+
+**Argus tool**
+- [x] `get_safe_to_spend` registered in `backend/agents/tools.py` — reads from cache, returns safe amount + breakdown
+- [x] `backend/tests/test_safe_to_spend_tool.py`
+
+- [x] Merge → `phase/6-daily-intelligence`
+
+---
+
+### `feature/pay-timing` ✅
+
+**Engine**
+- [x] `backend/engines/pay_timing.py` — two functions:
+  - `compute_pay_timing(accounts, bills, balance) -> dict` — for each credit account, computes pay_amount to reach 8% utilization. Detects 3-day bill stacking windows where total_due exceeds balance.
+  - `infer_closing_date(transactions)` — finds most common transaction day from history
+  - `bills_in_window(bills, window_days)` — filters bills due within window
+- [x] `backend/tests/test_pay_timing_engine.py`
+
+**Endpoint + Argus tool**
+- [x] `backend/routers/pay_timing.py` — `GET /insights/pay-timing` — fetches accounts + bills, runs engine, returns `{ card_recommendations, stacked_windows }`
+- [x] Registered in `backend/main.py`
+- [x] `get_pay_timing` registered in `backend/agents/tools.py`
+- [x] `backend/tests/test_pay_timing_endpoint.py`
+
+- [x] Merge → `phase/6-daily-intelligence`
+
+---
+
+### `feature/merchant-logos` ✅
+
+**Migration**
+- [x] `backend/migrations/017_merchant_logos.sql` — `merchant_logos` table: `merchant TEXT PK`, `logo_url TEXT`, `fetched_at TIMESTAMPTZ`. No RLS — logos are not user data.
+
+**Service**
+- [x] `backend/services/merchant_logos.py` — `get_logo_url(merchant, supabase) -> str | None`. Checks DB cache first. On miss: fetches from Clearbit (`logo.clearbit.com/{slug}.com`), stores result (including None on 404). Returns URL or None.
+- [x] `backend/tests/test_merchant_logos.py`
+
+- [x] Merge → `phase/6-daily-intelligence`
+
+---
+
+### `feature/smart-calendar` ✅
+
+**Endpoint**
+- [x] `backend/routers/calendar.py` — `GET /calendar` — fetches bills + active subscriptions, adds logo via merchant logo service, assigns urgency (high ≤3 days, medium ≤7 days, low otherwise), sorts by due date ascending, returns `{ entries: list }`
+- [x] Registered in `backend/main.py`
+- [x] `backend/tests/test_calendar_endpoint.py`
+
+**Frontend**
+- [x] `frontend/app/(app)/calendar/page.tsx` — Smart Payment Calendar page:
+  - Filter chips: all / bills / subscriptions
+  - Logo tile per entry (Clearbit image or copper initial fallback)
+  - Urgency color on left border (red / amber / grey)
+  - Stacking warning banner when pay timing detects bill stack
+  - Sorted by due date
+- [x] Calendar nav item added to sidebar in `frontend/app/(app)/layout.tsx`
+- [x] `frontend/app/(app)/dashboard/_components/SafeToSpendHero.tsx` — tappable hero number at top of dashboard; tap expands breakdown (balance → bills → buffer → safe amount)
+- [x] Wired into `frontend/app/(app)/dashboard/page.tsx`
+
+- [x] Merge → `phase/6-daily-intelligence`
+
+---
+
+### Phase 6 Close
+- [x] Merge `phase/6-daily-intelligence` → `develop`
+- [x] Open PR `develop` → `main`, wait for CI, merge
+- [x] Delete all feature branches + `phase/6-daily-intelligence`
+- [x] Mark Phase 6 as ✅ Complete in `Argus Details/product-plan.md`
+
+---
+
+## New Endpoints
+
+| Method | Path | Description |
+|---|---|---|
+| `GET` | `/insights/safe-to-spend` | Safe amount + breakdown (cached or live) |
+| `GET` | `/insights/pay-timing` | Card pay recommendations + bill stacking windows |
+| `GET` | `/calendar` | Unified bills + subscriptions feed, sorted by due date |
+
+---
+
+## New Database Tables
+
+```
+safe_to_spend_cache — user_id, safe_amount, breakdown, computed_at
+merchant_logos      — merchant, logo_url, fetched_at
+```
+
+---
+
+## Definition of Done
+
+- [x] Safe to Spend hero visible on dashboard with correct number
+- [x] Calendar page loads bills + subscriptions sorted by date, urgency-coded
+- [x] Pay timing returns correct card pay amounts (8% utilization target)
+- [x] Both engines registered as Argus tools
+- [x] CI green on main

Phase Plans/Phase_7A_FinancialProfile.md

@@ -0,0 +1,120 @@
+# Phase 7A: Financial Profile + Merchant Intelligence
+
+> Goal: give users a deep map of their own spending behavior — where money goes, which merchants dominate, and what Argus thinks about each one. All data registered as Argus tools so chat can answer profile questions.
+
+---
+
+## What This Phase Covers
+
+| Layer | Goal |
+|---|---|
+| Backend endpoints | Profile overview, merchant rankings, per-merchant intelligence |
+| Argus tools | Register profile + merchant data so Argus can reason over it |
+| Frontend | Three-level profile page: overview → category → merchant |
+
+---
+
+## Git Branch Structure
+
+```
+develop
+└── phase/7A-financial-profile
+      ├── feature/profile-endpoints
+      ├── feature/profile-argus-tools
+      └── feature/profile-frontend
+```
+
+---
+
+## Global Constraints
+
+- No financial number invented by AI — all figures computed from transaction history
+- Every new endpoint requires `get_current_user` auth dependency
+- New routers registered in `backend/main.py`
+- Frontend uses design tokens only — no raw Tailwind color utilities
+- Tests mock Supabase via `unittest.mock.patch`; never hit real DB
+- Merchant Intelligence insight generated by Argus reasoning over computed data — not hardcoded
+
+---
+
+## Execution Checklist
+
+### `feature/profile-endpoints`
+
+**Overview endpoint**
+- [x] `GET /profile/overview` — spending breakdown by category (computed from transactions), habit streaks (consecutive weeks under budget per category), subscription count + total monthly cost, credit utilization summary across all cards
+- [x] `backend/routers/profile.py` — new router, registered in `main.py`
+- [x] `backend/tests/test_profile_overview.py`
+
+**Merchant endpoints**
+- [x] `GET /profile/merchants` — all merchants user has transacted with, ranked by total spend descending, each entry includes merchant name, total spend, transaction count, 30-day trend (up/down/flat)
+- [x] `GET /profile/merchants/{merchant_id}` — single merchant detail: weekly/monthly/yearly spend breakdown, transaction frequency heatmap data (day-of-week × week-of-month grid), cost trend over last 6 months, one Argus-generated insight specific to that merchant and that user
+- [x] `backend/tests/test_profile_merchants.py`
+
+- [x] Merge → `phase/7A-financial-profile`
+
+---
+
+### `feature/profile-argus-tools`
+
+- [x] `get_profile_overview` registered in `backend/agents/tools.py` — returns spending breakdown, streaks, utilization summary
+- [x] `get_merchant_history` registered in `backend/agents/tools.py` — takes merchant name, returns full history + trend for that user
+- [x] `backend/tests/test_profile_tools.py`
+
+- [x] Merge → `phase/7A-financial-profile`
+
+---
+
+### `feature/profile-frontend`
+
+**Level 1 — Overview**
+- [x] `frontend/app/(app)/profile/page.tsx` — top level shows:
+  - Spending ring: category breakdown as proportional arc chart
+  - Streaks grid: GitHub contribution-style grid, one cell per week, colored by whether user stayed under budget that week per category
+  - Subscription logo grid: logos of all active subscriptions with total monthly cost
+  - Utilization gauge: overall credit utilization across all cards
+  - Biggest spend day chart: bar chart of spend by day of week
+
+**Level 2 — Category drill-down**
+- [x] Tapping a category segment on spending ring opens category view — lists all merchants within that category ranked by spend, each with logo, total, transaction count
+
+**Level 3 — Merchant Intelligence**
+- [x] Tapping a merchant opens merchant detail page/drawer — shows:
+  - Weekly/monthly/yearly spend tabs
+  - Frequency heatmap (day-of-week grid)
+  - Cost trend sparkline (6 months)
+  - One Argus insight for that specific merchant — dynamically generated, specific to that user's pattern with that merchant
+- [x] Merchant Intelligence pages only exist for merchants user actually transacts with — no empty shells
+
+**Nav**
+- [x] Profile nav item added to sidebar in `frontend/app/(app)/layout.tsx`
+
+- [x] Merge → `phase/7A-financial-profile`
+
+---
+
+### Phase 7A Close
+- [x] Merge `phase/7A-financial-profile` → `develop`
+- [x] Open PR `develop` → `main`, wait for CI, merge
+- [x] Delete all feature branches + `phase/7A-financial-profile`
+- [x] Mark Phase 7A as ✅ Complete in `Argus Details/product-plan.md`
+
+---
+
+## New Endpoints
+
+| Method | Path | Description |
+|---|---|---|
+| `GET` | `/profile/overview` | Spending breakdown, streaks, subscription summary, utilization |
+| `GET` | `/profile/merchants` | All merchants ranked by total spend |
+| `GET` | `/profile/merchants/{merchant_id}` | Per-merchant history, heatmap, trend, Argus insight |
+
+---
+
+## Definition of Done
+
+- [ ] Profile page loads with spending ring, streaks, subscription grid, utilization gauge
+- [ ] Category drill-down shows correct merchants ranked by spend
+- [ ] Merchant detail shows heatmap + trend + one Argus insight
+- [ ] Both tools registered and callable by Argus in chat
+- [ ] CI green on main