Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -267,7 +267,7 @@ src/
<feature>/ built so far: accounts, agent, alerts, auth, bills, budgets,
cashflow, categorization, imports, insights,
landing, messaging, plans, recurring,
synthetic, transactions, transfers
summary, synthetic, transactions, transfers
domain/ pure TypeScript logic, no I/O (most unit tests here)
server/ repositories, server actions ('server-only')
ui/ React components for this feature
Expand Down
14 changes: 10 additions & 4 deletions docs/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -153,6 +153,7 @@ have `updated_at`.
| `agent_pending_log` | identity_id (PK, FK to `messaging_identity`), workspace_id, amount_cents, description, day (`today`/`yesterday`), account_ids (text[]), asked_at, kind (`account`/`receipt`), category_id (FK to `category`, set null), message_id | Built in 0015 (ADR-065); `kind`, `category_id` and `message_id` added in 0017 for a receipt photo's proposal, which is not a transaction until the person says yes (ADR-067). The one "which account?" a phone has open; replaced by the next question and ignored 10 minutes after `asked_at`. Both FKs cascade |
| `notification_setting` | user_id (PK), quiet_start_minute, quiet_end_minute, previous_start_minute, previous_end_minute, changed_by_text_at, subscription_alerts, bill_reminders, updated_at | Built in 0016 (ADR-104). Per user, so it survives relinking; no row means 9 PM–9 AM and both alert types on. A check keeps both minutes in 0–1439 and different. The previous values let UNDO reverse a text change for 24 hours. The two switches arrived in 0018 (ADR-105) |
| `proactive_message` | id, user_id, identity_id, workspace_id, kind (`subscription_alert`, `bill_reminder`), subject_key, status (`queued`, `sent`, `cancelled`, `failed`), not_before, attempts, sent_at, created_at | Built in 0018 (ADR-105). Unique (workspace_id, kind, subject_key): one text per subscription (its payment key) or per bill cycle (payment key and scheduled date). No amounts and no text are stored. Cascades with the user, the phone link and the workspace |
| `summary_write` | id, workspace_id, user_id, written_on (the day in the app's time zone), draft (jsonb: a summary and suggestions with labels, never an amount; null when no model answered), created_at | Built in 0019 (ADR-068). One row for each request to have Gemini write the dashboard summary: the rows are each person's daily limit, and the newest draft is what the workspace sees that day. Rows from earlier days are removed at the next request |
| `nessie_link` | workspace_id (PK), nessie_customer_id, last_synced_at | One sandbox customer per workspace (ADR-033) |
| `outbound_message` | id, messaging_identity_id, kind (`subscription_alert`/`bill_reminder`/`weekly_recap`), dedupe_key, scheduled_for, sent_at, status | Unique dedupe_key; enforces quiet hours and daily cap (ADR-038) |
| `audit_event` | id, workspace_id (nullable), actor_user_id, action, target_type, target_id, created_at, ip_hash | No financial details |
Expand Down Expand Up @@ -273,7 +274,7 @@ preserving the balance line, including transfers posted on different days.

## ARCH-07: AI layer

Governed by: ADR-019, ADR-045, ADR-059
Governed by: ADR-019, ADR-045, ADR-059, ADR-068

- `src/lib/ai/google.ts`: the only file that imports the `@google/genai`
SDK. One stateless request (`store: false`) to Gemini's Interactions API.
Expand All @@ -298,9 +299,14 @@ Governed by: ADR-019, ADR-045, ADR-059
- "Ask Reeflect" exposes read-only tools (for example
`getCategorySpend(workspaceId, month, categoryId)`) that call the same
repository functions as the UI, with the same authorization.
- The website summary panel (ADR-045) sends code-computed aggregates to
Gemini, fills the placeholders in its reply, runs the digit scan, and falls
back to a fixed template with the same figures.
- The website summary panel (`src/features/summary`, ADR-045, ADR-068) is
on the dashboard. It opens with a summary built by code from the agent's
`getSummary`. On a click, `generateLongText` (the chain with 8 seconds for
each model) sends Gemini the labels and a JSON shape; code checks every
sentence as it checks a text reply, fills the labels in, and falls back to
the code-built panel with the same figures. Each person may ask five
times a day. The draft is kept in label form in `summary_write` and
filled again with current figures on each page load that day.

## ARCH-08: Security controls

Expand Down
69 changes: 69 additions & 0 deletions docs/DECISIONS.md
Original file line number Diff line number Diff line change
Expand Up @@ -92,6 +92,7 @@ Rules:
| ADR-064 | Logging spending by text: code decides, asks when unsure, never guesses (refines ADR-035, ADR-040) | Proposed |
| ADR-065 | The agent remembers one open question: which account a text's spending is for (refines ADR-064) | Proposed |
| ADR-067 | Receipt photos: the model reads, code checks, the person confirms (refines ADR-035, ADR-065) | Proposed |
| ADR-068 | The Gemini summary is on the dashboard, written on request, limited and kept for the day (refines ADR-045) | Proposed |
| ADR-082 | Sample years in the developers' own accounts (exception to ADR-049) | Accepted |
| ADR-083 | Ask the user to categorize large uncategorized payments (refines ADR-055, ADR-057) | Proposed |
| ADR-084 | Reserved ADR and handoff numbers for each developer | Accepted |
Expand Down Expand Up @@ -2035,6 +2036,74 @@ Rules:
- Deploy the app before the worker: an older app drops the photo and
answers the empty text with the summary.

### ADR-068: The Gemini summary is on the dashboard, written on request, limited and kept for the day (refines ADR-045)

- **Status:** Proposed (2026-10-11)
- **Owner to confirm:** Muhammad Tahub Khatri
Comment on lines +2041 to +2042

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Confirm the proposed schema decision before merging

This commit adds migration 0019 and the summary_write schema while its governing ADR is still explicitly Proposed and awaiting owner confirmation. Repository policy requires confirmation before starting an expensive-to-reverse database-schema change under a Proposed ADR, so obtain and record that confirmation before this change proceeds.

AGENTS.md reference: AGENTS.md:L83-L87

Useful? React with 👍 / 👎.

- **Context:** ADR-045 decided that the website has a panel where Gemini
writes a summary and suggestions from figures code computed. It did not
say where the panel is, when the model is called, or which figures the
suggestions use. The models that answer users have a small daily
allowance (ADR-059), and the dashboard re-renders after every change.
- **Decision** (the choices of place, trigger, figures, limit and what is
kept are Muhammad's, 2026-10-11):
- **On the dashboard,** under the headline, in its own feature
(`src/features/summary`). The agent already imports the calendar and
Insights code, so the panel cannot live in either without a cycle.
- **Written on request.** The panel opens with a summary built by code.
A button, "Write it with Gemini", makes one model call. Opening or
refreshing the page never calls a model.
- **Five a day for each person,** counted across their workspaces by the
day in the app's time zone. Every request counts, whether or not a
model answered, since a rejected draft spent a call too. Past five no
model is called, the button is off and the panel says they can ask
again tomorrow. The count and the new row are taken under one lock for
that person, so clicks at the same moment cannot pass the limit.
- **Kept for the rest of the day, in label form.** `summary_write` has
one row for each request, with the draft as the model wrote it:
sentences with labels, never an amount. On each page load the newest
draft written for the workspace that day is checked again and filled
with the figures as they are now, so it cannot disagree with the
headline, and every member sees it with the time it was written. If it
no longer passes the check (a figure it used is gone), the code-built
summary shows. The next day it is not shown, because its wording may
no longer be true, and the rows are removed at that person's or that
workspace's next request.
- **The same figures and rules as a text** (ADR-019, ADR-035). The panel
reads the agent's `getSummary`, so it cannot disagree with a text or
the calendar. The model is sent label names, their meanings and preset
category names: no amount, account nickname or payment name. Its answer
is JSON (a summary and up to three suggestions), and every sentence
passes the check a text reply passes. One sentence that fails rejects
the whole answer, and the code-built panel is shown with a line saying
Gemini did not answer.
- **Two more figures,** for ADR-045's suggestions: what subscriptions
come to over a year (the monthly average times twelve, and a reply must
say "a year"), and how many categories are past budget this month.
Texts can use them too.
- **The panel says who wrote it:** Gemini around figures the app worked
out, or the app alone.
- **A viewer may ask.** Nothing about the workspace's money changes;
the only thing written is the draft its own panel shows.
- **Each model gets 8 seconds** inside the same 14 in total, as for a
receipt photo (ADR-067): a paragraph took 2 to 6 seconds on the test
model, more than the 4 a text reply gets.
- **Alternatives considered:** writing on every page load (a model call for
each visit and each change on the calendar, and up to 14 seconds of
waiting); storing the finished text (amounts written by way of a model
kept at rest, and stale after a sync); keeping a summary until the next
one or for a week (its words drift from the facts); a limit for each
workspace (one member could use up another's); putting the panel on
Insights (one click further from the first screen).
- **Consequences:** a schema change (migration 0019). A draft's words can
go out of date within the day while its figures stay current: "nothing
is due" may stop being true after a sync. A model that names a category
in its own words leaves that name in the stored draft. A request that
got no answer still uses one of the five. Tone is asked for in the
instruction and cannot be checked by code; the figure rules can. "Where
spending rose" needs a comparison with an earlier period and is not
built.

### ADR-084: Reserved ADR and handoff numbers for each developer

- **Status:** Accepted (2026-10-11)
Expand Down
126 changes: 125 additions & 1 deletion docs/HANDOFF.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ Update this table when work is assigned or finished. Features are listed in
| F-33 Quiet hours settings | B + C | Simon Ormond | `feat/quiet-hours` | Built (HO-096, ADR-104 Proposed): Settings → Notifications and by text, with UNDO. The alerts tick honours them (HO-097) |
| F-32 Agent worker | C | Muhammad Tahub Khatri | `feat/agent-worker` | Done, replies only (HO-039, PR #17); live on Render (HO-049) |
| F-22 Bill reminders (P1) | A + C | Simon Ormond | `feat/proactive-alerts` | iMessage reminders built (HO-097, ADR-105 Proposed) on the web Bills cycles (ADR-063); DETAILS gives the amount and the low-balance line |
| F-15 Gemini summary on the website (P1, ADR-045) | C | Unassigned | — | Not started |
| F-15 Gemini summary on the website (P1, ADR-045) | C | Muhammad Tahub Khatri | `feat/gemini-summary` | Built (HO-121, HO-120, ADR-068 Proposed): a panel on the dashboard, code-built at first, written by Gemini on a click, five a day for each person, kept for the day. Not built: "where spending rose" |
| F-35 Compare with people like you (Later, ADR-056) | A + B | Jacob Heminway | `feat/insights` | Built: the Insights page, stored sample figures and `pnpm batch rollup` (HO-043); ADR-056 and ADR-057 Proposed |
| F-36 Retirement question (Later, ADR-055) | B | Jacob Heminway | `feat/insights` | Planned; generator models the answers (HO-041) |
| F-37 Planned transactions (P1, ADR-102) | B | Simon Ormond | `feat/planned-transactions` | Built: plan on later days from the day panel, confirm or remove once the day comes (HO-095); ADR-102 Proposed |
Expand Down Expand Up @@ -4402,3 +4402,127 @@ rows", transactions 2 "show more" in steps of 20, plus a view-only list.

### Open problems
- None
## HO-121: F-15, the Gemini summary panel on the dashboard (ADR-068)

- **Date:** 2026-10-11 (EDT)
- **Author:** Muhammad Tahub Khatri with Claude (Claude Code)
- **Branch / PR:** `feat/gemini-summary` / not opened; nothing committed

### What changed
- New feature `src/features/summary/` (F-15, ADR-045, ADR-068 Proposed):
- `domain/`: the instruction and request (`prompt.ts`), the JSON shape
and the check of a model's answer (`panel.ts`), and the panel code
builds by itself (`fallback.ts`).
- `server/`: `loadSummaryPanel` (code-built, no model) and
`writeSummary` / `writeSummaryAction` (one model call). Both check
workspace access at viewer and are in the isolation matrix.
- `ui/summary-panel.tsx`: "Where you stand", a "Worth a look" list, a
line saying who wrote it, and the "Write it with Gemini" button.
- The dashboard page passes the panel to `CashflowDashboard` through a new
`summaryPanel` prop, inside its own `Suspense`. Nothing shows without
accounts.
- The panel reuses the agent's brain, now exported for it:
- `getSummary` from the agent's `index.ts`.
- A new `src/features/agent/client.ts` with the pure parts
(`completeDraft`, `buildFacts`, `describeFacts`, `FIGURE_RULES`,
`MONEY_LIMITS`).
- `prompt.ts` was split into those pieces. The texting instruction is
byte-for-byte what it was (checked by hash before and after).
- Two new labels, which texts can use too: `subscription_yearly` (a reply
must say "a year") and `over_budget_count` ("1 category past budget").
- `src/lib/ai/client.ts`: `generateLongText`, the chain with 8 seconds for
each model. A paragraph took 2 to 6 seconds on the test model.
- The local Docker database was 3 migrations behind; I ran
`pnpm db:migrate:to local` (test database only).
- Docs updated: ADR-068, the F-15 row in PROJECT, ARCH-07, AGENTS.md
section 6, the demo step and Gemini row in PITCH, and this file's
assignments.
- `feat/transfer-review` (PR #44) already uses the next ADR number and
the next three handoff numbers, so this work took ADR-068 and HO-121.

### Verified
- `pnpm lint`, `typecheck`, `format:check`, `docs:check`, `build` and
`scan:bundle` pass.
- `pnpm test:unit`: 2614 pass. The 8 failures are the statement storage
tests, which need `.env.storage-tests`; this machine has none. Coverage
thresholds are not reported on a failed run.
- `pnpm test:e2e`: all 128 pass, including the three in `summary.spec.ts`.
They were run before `generateLongText` and the new wording of
`over_budget_count`; after those, `summary.spec.ts` and
`agent-questions.spec.ts` were run again and pass.
- With the real key and the test model, on made-up figures: six drafts
passed the checks and one call got a 503. No browser run with a real
key.

### What's next
- Muhammad confirms ADR-068.
- Click the button on the deployed app with the users' models, and read
what they write for a workspace with a payday and budgets.
- Rehearse the new 1:10 step in PITCH.

### Open problems
- There is no limit on clicks for each person; every click is one model
call against the daily allowance (ADR-059).
- A written summary is not kept: a refresh shows the code-built one.
- The dashboard now reads the agent's figures as well as the calendar's,
so some rows are read twice for each view.
- Code checks the figures in a suggestion, not its tone or usefulness.

## HO-120: F-15, a daily limit for each person and the written summary kept for the day

- **Date:** 2026-10-11 (EDT)
- **Author:** Muhammad Tahub Khatri with Claude (Claude Code)
- **Branch / PR:** `feat/gemini-summary` / not opened; HO-121's work is committed, this is not

### What changed
- Closes HO-121's first two open problems. ADR-068 (still Proposed) was
rewritten to say so; the choices are Muhammad's.
- **Schema change:** migration 0019 adds `summary_write`, one row for each
request to have Gemini write the summary: workspace, person, the day in
the app's time zone, and the draft. Applied to the local Docker database
only.
- **Five a day for each person** (`DAILY_WRITES`), across their workspaces.
Every request counts, whether or not a model answered. Past five no model
is called, the button is off and the panel says they can ask again
tomorrow. `reserveWrite` counts and inserts under one lock for that
person, so clicks at the same moment cannot pass the limit.
- **Kept for the rest of the day, in label form.** The draft is stored as
the model wrote it, with labels and never an amount. On each page load
the newest draft for the workspace is checked again (`checkPanel`) and
filled with the figures as they are now; every member sees it with the
time it was written. If it no longer passes, the code-built summary
shows. The next day it is not shown; earlier days' rows are removed at
the next request.
- `loadSummaryPanel` and `writeSummary` now return the panel with how many
requests are left; `writeSummary` also says what happened (`written`,
`no_answer`, `limit`). New `server/repository.ts`.
- The panel's last line says who wrote it and when, and how many are left
today.
- Docs updated: ADR-068, ARCH-07 and the `summary_write` row in ARCH-03,
the F-15 row in PROJECT, and this file's assignments.

### Verified
- `pnpm lint`, `typecheck`, `format:check`, `docs:check` and `build` pass.
- Vitest for `src/features/summary` and the isolation matrix: all pass,
including the limit, clicks at the same moment, the next day, a stored
draft filled with new figures, and other workspaces.
- `tests/e2e/summary.spec.ts`: all 5 pass.

### What's next
- Muhammad confirms ADR-068.
- After approval: `pnpm db:migrate:to branch` and `production` for 0019,
before deploying.
- Click the button on the deployed app with the users' models; refresh and
see the summary still there.
- `pnpm test:unit` after this change: 2628 pass; the 8 failures are the
statement storage tests, which need `.env.storage-tests`. The full
`pnpm test:e2e` run was started and its result not recorded; no browser
run with a real key.

### Open problems
- A request that got no answer still uses one of the five, so a bad minute
at Google can use up someone's day.
- A stored summary's words can go out of date within the day; only its
figures are refreshed.
- A model that names a category in its own words leaves that name in the
stored draft.
Loading
Loading