The Trilogy Times

Linear: [SURTR-23](https://linear.app/builder-team/issue/SURTR-23/capture-quickbooks-journalentry-lines-fix-money-precision)

## Why

The quickbooks-ap-sync pipeline currently captures only Bills, VendorCredits, and BillPayments at line level — that's ~9% of P&L expense activity on the alpha entity (Q1 2026, $1.27M of $14.28M). The other ~91% is invisible at transaction level despite the monthly aggregate (quickbooks_pl_monthly) reconciling correctly with QuickBooks.

GeneralLedger analysis across alpha, miami, and alpha_schools_llc showed the entity-type split:

| TxnType | alpha % of P&L | miami % of P&L | alpha_schools_llc % of P&L |

|---|---|---|---|

| Journal Entry | 65.3% | 8.0% | 18.4% |

| Expense (Purchase) | 24.8% | 5.9% | 12.5% |

| Bill | 8.7% | 84.5% | 67.4% |

For alpha specifically, accounts 60211/60212/60220/60250/60200 (Contracted Labor — Coaches) and 69100 (Central Factory Recharges) are 100% Journal Entries — $7M+/quarter of XO contractor payroll postings that are completely invisible to current Bills-only capture.

Adding JournalEntry capture takes overall P&L coverage from 9% → 75%. Adding Purchase (the follow-up Phase 2) gets to 99.5%.

## What this PR delivers (Phase 1)

Two logically separable changes bundled in one PR for review efficiency.

### Phase 0 — money-precision fix (prerequisite)

- New src/money.py helper: parse_money(value) -> Decimal with HALF_UP rounding at 4dp.

- Wired through every existing money field in the 3 transformers (Bills / AP / BillPayments).

- New JSON encoder in redshift_handler.py emitting Decimals as JSON numbers (via float(), safe since values are pre-quantized).

Root cause this fixes: QB sometimes returns amounts with float-representation drift (e.g. 28.879999... for $28.88). The old code passed the raw float through json.dumps → S3 → COPY, where Redshift NUMERIC(18,2) truncates the excess precision instead of rounding. Result: bills booked at $28.88 in QB stored as $28.87. Verified against Cristy Cunningham HR Expense bills where the QB report total differed by exactly 6¢ from our Redshift sum across 7 affected lines.

No column migration needed. parse_money() already quantizes to 4dp via Decimal then serializes back to a clean 2dp-friendly JSON number (28.879999... → 28.88 exactly). Redshift COPY into the existing NUMERIC(18,2) columns receives the clean value and stores it without truncation. Widening columns to NUMERIC(18,4) was over-engineering; Redshift also doesn't support inline ALTER COLUMN TYPE for numeric here, so the add/update/drop/rename dance wouldn't be worth the disruption for a non-essential safety margin.

### Phase 1 — JournalEntry pipeline extension

- New query_journal_entries() in qb_client.py using the same paginated _query_qb path as Bills/VendorCredits/BillPayments.

- New _transform_to_je_records() in handler.py emitting one row per JE line (header repeated). Captures posting_type, debit_amount/credit_amount/net_amount, account refs, class/department refs, optional entity ref, and per-line description (which carries the contractor name in XO payroll JEs).

- Integration into the per-entity loop as a fourth table_writes step.

- TABLE_CONFIGS entry for quickbooks_journal_entries.

- ddl/create_quickbooks_journal_entries.sql — new table with NUMERIC(18,4) money columns (free since it's a fresh table), DISTKEY(company_id), SORTKEY(txn_date, account_id).

- 9 new transformer tests against real QB JE shapes (balanced 2-line, XO multi-credit payroll, adjustment, entity ref, money rounding, optional fields, empty lines, non-JE-detail skip, multi-JE concat).

- Updated 5 existing handler tests to mock the new fetch + assert the 4th delete_and_insert call.

### Tooling

- New run_local.py — Level 1 dry-run driver. Mirrors the quickbooks-pl-monthly/run_local.py pattern. Calls handler() with dry_run=True by default; fetches from real QB but skips Redshift writes. Sensible env defaults including ENVIRONMENT=prod. Live-validated across all 9 entities (see Test Plan).

## Out of scope (deliberate, follow-up tickets)

- Rename quickbooks-ap-sync → quickbooks-transactions-sync (name no longer matches scope).

- Phase 2 — Capture Purchase entity (Cash/Check/CreditCard expenses; closes another ~25% of alpha P&L).

- Phase 3 — Capture Deposit / CreditCardCredit (last 0.5%).

- Downstream quickbooks-core-tables update to UNION the new JE staging table into fct_pl / fct_expense.

- Apply the same parse_money helper to quickbooks-pl-monthly and quickbooks-expense-sync (requires shared-code infrastructure since each pipeline bundles independently).

## Test plan

- [x] Unit tests: 85 pass (was 76; +9 JE + 17 money). ruff check clean, ruff format applied.

- [x] Level 1 — dry-run against real QB, all 9 entities (Q1 2026): 9/9 succeeded, 2,601 Bills + 27 VendorCredits + 2,371 BillPayments + 625 JournalEntries fetched with zero errors. Alpha alone returned 358 JE headers (~6,300 line-level rows after transformation), matching prior GL analysis.

  cd pipelines/runners/quickbooks-ap-sync
python3 run_local.py --quiet                   # miami, default
python3 run_local.py --quiet --company alpha   # large entity, ~30s

- [ ] Level 2 — SQL deploy:

- Run pipelines/runners/quickbooks-ap-sync/ddl/create_quickbooks_journal_entries.sql once. Single CREATE TABLE IF NOT EXISTS — idempotent, no impact on existing tables.

- [ ] Level 3 — post-deploy smoke test (manual Lambda invoke):

  aws lambda invoke \
--function-name pipeline-quickbooks-ap-sync-prod \
--cli-binary-format raw-in-base64-out \
--payload '{"run_id":"post-deploy-smoke","params":{"company_ids":["miami"],"start_date":"2026-05-01","end_date":"2026-05-15"}}' \
/tmp/out.json

- [ ] Reconciliation — after a full alpha Q1 backfill (next daily run or wider-window manual invoke):

  SELECT SUM(debit_amount) - SUM(credit_amount) AS net
FROM staging_education.quickbooks_journal_entries
WHERE company_id = 'alpha'
AND account_id = '211'
AND txn_date BETWEEN '2026-01-01' AND '2026-03-31';
-- Expected: 2088610.84 (matches QB GL exactly)

## Risk + rollback

| Change | Reversible? | Notes |

|---|---|---|

| create_quickbooks_journal_entries.sql | Yes — DROP TABLE | Empty new table, zero impact on existing data |

| Lambda code | Yes — git revert + CDK redeploy | New table is the only schema change |

## Deploy ordering

SQL must land before the Lambda's first run against the new code path. Given the current ~20 hours until next 03:00 UTC scheduled run, the standard sequence is safe:

1. Merge PR → CD auto-deploys Lambda (deployed but unfired — don't manually invoke)

2. Run create_quickbooks_journal_entries.sql

3. Manual Lambda invoke for smoke test

4. Reconciliation query

5. Let the next scheduled run pick up wider backfill on its own (default 30-month look-back), or trigger manual backfill

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Linear: SURTR-24 (Phase 2) — follows [SURTR-23 / PR #88](https://github.com/AI-Builder-Team/Surtr/pull/88) (Phase 1: JournalEntry capture)

## Why

Phase 2 of the QB pipeline extension. Phase 1 captured JournalEntries — ~65% of alpha's P&L expense activity. Phase 2 closes the next ~25% by capturing the Purchase entity: direct credit-card / check / cash spend that doesn't flow through the AP cycle (no Bill, no BillPayment).

Combined Phase 1 + Phase 2 takes the alpha operating entity from 9% → ~99.5% P&L expense coverage at line level. Facility entities reach ~99-100% with the same code path.

Live dry-run capture for Q1 2026 across all 9 entities:

| Entity | Purchase headers |

|---|---|

| alpha | 19,671 |

| alpha_schools_llc | 219 |

| miami | 42 |

| sports_academy_78734_llc | 36 |

| sports_academy_75010_llc | 24 |

| gtschool_78626_llc | 16 |

| esports_academy_llc | 12 |

| alpha_school_28269_llc | 12 |

| alpha_school_93101_llc | 10 |

| Total | 20,042 |

alpha's 19,671 is dominated by Ramp Card spend — the same pattern that produced the original HR-Expenses 6¢ rounding observation that kicked off this whole work.

## What this PR delivers

### New table: staging_education.quickbooks_purchases

One row per Purchase line. Captures both the funding side (payment_account_id = Ramp Card / bank / etc.) and the expense side (account_id = the GL expense account being debited). Money columns are NUMERIC(18,4), picking up parse_money's precision pipeline.

credit_flag (sourced from the Purchase header's Credit bool) flips net_amount sign for refunds, so SUM(net_amount) gives the correct P&L contribution.

### Code changes

- qb_client.py — new query_purchases() using the same paginated _query_qb path as Bills/JEs

- handler.py — new _transform_to_purchase_records() with the same Phase-1 validation discipline:

- PaymentType validated against {CreditCard, Check, Cash}; invalid → log+skip whole purchase

- Header AccountRef.value (funding) validated; missing → log+skip whole purchase

- Per-line AccountRef.value (expense) validated; missing → log+skip line, others survive

- _parse_line_amount shared helper for Amount parsing (consistent with Bills/JEs)

- enumerate fallback for line_id (PK safety)

- Non-expense DetailTypes logged before skip (schema-drift visibility)

- handler.py — integrated as the 5th table_writes step

- redshift_handler.py — TABLE_CONFIGS["quickbooks_purchases"] entry matching DDL column order

- ddl/create_quickbooks_purchases.sql — DISTKEY(company_id), SORTKEY(txn_date, account_id), strict PK on (company_id, transaction_id, line_id)

- run_local.py — surfaces Purchase counts in the summary + adds a reconciliation hint for alpha Q1 2026 grouped by payment_type

- Updated module docstring at top of handler.py — the pipeline now syncs 5 tables, not 3

### Tests

- test_purchase_transform.py — 13 new tests (simple CC purchase, Credit: true refund sign-flip, Check, multi-line, ItemBasedExpenseLineDetail parity, invalid PaymentType skip, missing header AccountRef skip, missing line AccountRef skip, line_id enumerate, missing Amount → 0, optional header fields, empty Line[] skip, unparseable Amount → 0)

- test_handler.py — 5 existing TestHandler tests updated for the new 5th delete_and_insert call + query_purchases mock

## Out of scope (deliberate follow-ups — likely next tickets)

- Rename quickbooks-ap-sync → quickbooks-transactions-sync — the name is now actively misleading

- Phase 3 — Deposit / CreditCardCredit (covers the last 0.5%)

- Downstream quickbooks-core-tables UNION — makes Phase 1 + Phase 2 data visible to dashboards via fct_pl / fct_expense. This is the value-realization step.

- parse_money defensive replication to quickbooks-pl-monthly and quickbooks-expense-sync (needs shared-code infra)

## Test plan

- [x] Unit tests: 111 pass (was 98; +13 Purchase + 5 mock updates). ruff check clean, ruff format applied.

- [x] Level 1 — dry-run, all 9 entities, Q1 2026: 9/9 succeeded, 20,042 purchases captured with zero errors.

  cd pipelines/runners/quickbooks-ap-sync
python3 run_local.py --quiet --start 2026-01-01 --end 2026-03-31 \
--company alpha --company alpha_schools_llc --company alpha_school_28269_llc \
--company alpha_school_93101_llc --company esports_academy_llc --company gtschool_78626_llc \
--company miami --company sports_academy_75010_llc --company sports_academy_78734_llc

- [x] Level 2 — SQL deploy: create_quickbooks_purchases.sql ran cleanly in production via renewals-pipeline/scripts/run_ddl.py.

- [x] Level 3 — smoke test (alpha 2026-05-20..21, --no-dry-run): 55 purchases / 56 lines written. Real vendors (Delta, DoorDash, CitizenM, Mason Security, Alo Yoga). By payment_type: 54 CreditCard ($168,342.87) + 1 Cash ($9,539.53). All money cols 4dp. credit_flag captured. No errors. No skipped lines.

-- Verified Level 3 query:
SELECT payment_type, COUNT(*) AS lines, SUM(net_amount) AS net
FROM staging_education.quickbooks_purchases
WHERE company_id='alpha' AND txn_date BETWEEN '2026-05-20' AND '2026-05-21'
GROUP BY payment_type;
-- CreditCard  55  168342.87
-- Cash         1    9539.53

## Risk + rollback

| Change | Reversible? | Notes |

|---|---|---|

| create_quickbooks_purchases.sql | Yes — DROP TABLE staging_education.quickbooks_purchases | Empty new table at deploy, zero impact on existing data |

| Lambda code | Yes — git revert + CDK redeploy | Schema change is purely additive |

## Deploy ordering

Same as Phase 1: SQL must land before the Lambda's first run with the new code. SQL is already deployed (via the L2 step above). Once this PR merges and reaches production, CD redeploys the Lambda; the next scheduled run (or a manual invoke) starts populating quickbooks_purchases automatically via the default 30-month look-back.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

## Summary

Tightens the Rhodes note + chat surfaces against stale or non-site IDs.

The /api/chat route drops a redundant Clerk users.getUser call and

reuses a single Rhodes Convex client for both auth and chat context,

with cleaner 429/503 mapping for Clerk and rate-limit errors. The note

APIs (listNotes, listNotesPage, addNote) now accept either a

siteId or a siteSlug and normalize to a site ID inside Convex, so

agents passing a stale or non-site ID get a clear "resolve current

site" error instead of a Convex validator failure. MCP and Aerie tool

descriptions are updated to steer agents toward resolveSite first.

### Changes

- web/src/app/api/chat/route.ts — Drop the extra

clerkClient.users.getUser round-trip. Build the Rhodes Convex

client once and reuse the resolved actor for chat context. Map

Clerk auth/rate-limit/service errors to 401/429/503 responses with

consistent shapes.

- web/src/lib/rhodes-web-convex.ts — Expose the actor alongside

the client and surface typed error classes for the route to switch

on.

- convex/notes.ts — listNotes, listNotesPage, and addNote

now take an optional siteSlug and normalize siteId server-side.

Stale or non-site IDs yield a "resolve current site" error rather

than a validator crash.

- convex/sites.ts — Helper used by notes to resolve a slug or

validate that a passed ID is actually a site.

- convex/lib/mutationAuthorization.ts — addNote authorization

resolves the site first, then checks canManageSchoolFields and

P1/P2 DRI access against the resolved site.

- mcp-server/tools/notes.ts — Tool descriptions and input

schemas updated to allow siteSlug and instruct agents to call

resolveSite first when IDs may be stale.

- lib/mcp-instructions.ts — Aerie note tool instructions updated

with the same guidance.

### Design Decisions

- Normalize site identity inside Convex, not at the call site.

Agents and the chat client both pass site identifiers from

different sources (slugs, resolved IDs, sometimes stale cached

IDs). Doing the resolve + validation in Convex gives one

authoritative error path and avoids duplicating the logic across

every caller.

- One Convex client per request. The previous flow created a

client for auth and another for chat context. Reusing the same

client (and resolved actor) removes a Clerk round-trip from the

hot path and keeps auth and tool calls consistent.

## Test Plan

- [x] Typecheck + lint pass locally.

- [ ] Hit /api/chat while signed out and confirm a clean 401.

- [ ] Trigger Clerk rate-limit / service errors and confirm 429/503

responses.

- [ ] Call addNote / listNotes with a siteSlug and confirm it

resolves correctly.

- [ ] Call addNote with a stale or non-site ID and confirm the

"resolve current site" error surfaces (not a Convex validator

error).

- [ ] Confirm P1/P2 DRI auth on addNote still works after the

resolve-first change.

## Demo

<img width="2624" height="1636" alt="image" src="https://github.com/user-attachments/assets/08d51abb-666c-42cf-9ee0-792348066c7b" />

## Summary

Adds a dedicated financials viewer role to the RBAC system so finance/leadership stakeholders can be granted access to Dashboards → Financials without being made full admins.

- New financials seeded role (only canViewFinancials: true)

- Extends canGrantRoles on superadmin and admin so the role is assignable from the existing admin UI

- One-shot patchFinancialsGrantCeiling internal mutation to bring already-seeded environments up to the new grant ceiling (since seedDefaults is insert-only)

## Linear

[AERIE-261 — Add financials role for granular Financials dashboard access](https://linear.app/builder-team/issue/AERIE-261/add-financials-role-for-granular-financials-dashboard-access)

## Spec

[features/user-management/rbac-admin/specs/05-add-financials-viewer-role/spec.md](features/user-management/rbac-admin/specs/05-add-financials-viewer-role/spec.md)

## Implementation summary

- chat/convex/roles.ts

- New role: appended financials to DEFAULT_ROLES with slug: "financials", name: "Financials Viewer", sortOrder: 2.5, isProtected: true, canGrantRoles: [], and every permission false except canViewFinancials: true. Placed between moderator (2) and user (3) so no existing sortOrder is renumbered.

- canGrantRoles extension: added "financials" to superadmin.canGrantRoles and admin.canGrantRoles, so listAssignableRoles surfaces the new role to both tiers automatically.

- patchFinancialsGrantCeiling internal mutation: idempotent, one-shot patch that brings superadmin and admin rows on already-seeded environments up to the new grant arrays. Missing slugs are reported, not thrown. Patterned on the existing patchCanViewFinancials mutation.

- JSDoc fix: corrected stale "four built-in roles" reference to "built-in" so the comment no longer drifts as roles are added.

- FEATURE.md + spec status updates: marked spec 05 Completed in the changelog and in the spec metadata; bumped Last Updated to 2026-05-22.

## Tests

- chat/convex/roles.test.ts — 70/70 passing. 7 stale fixtures updated for the 5-role baseline; 12 new tests added (4 covering the role shape, 8 covering the patch mutation).

- chat/convex/admin.test.ts — 3 fixture updates in the FR2: listAssignableRoles suite to reflect the new assignable role for superadmin / admin.

- All 7 CI checks green on run 26277232720: Build, Test, Typecheck, Lint+Boundaries, Secret Scan, Docker Chat, Docker Worker.

## Self-review

- 1 MINOR fix applied — stale JSDoc said "four built-in roles"; updated to "built-in" to avoid future drift.

- 2 MINOR skipped with rationale — both surfaced during self-review but were judged not worth landing in this PR (they are not regressions, just future cleanups).

## Out of scope

- Migrating existing users to the new role — no auto-migration. Admins assign Financials Viewer manually as the need arises. The existing assignRolesToExistingUsers mutation is intentionally untouched (it hard-codes the original three slugs).

## Manual verification needed before merge

- [ ] Confirm seedDefaults picks up the new role on next deploy (fresh row appears in roles with slug === "financials" and canViewFinancials: true)

- [ ] Confirm patchFinancialsGrantCeiling runs cleanly against the prod-equivalent env (one-shot; idempotent — safe to re-run)

- [ ] Spot-check the admin UI shows Financials Viewer as an assignable role for admins/superadmins (dropdown order: admin, moderator, financials, user)

## Rollout

After merging to main:

1. Wait for the auto-deploy to push the new Convex functions to your target environment.

2. Run the two commands below — from the chat/ directory, not the repo root (the convex dependency lives in chat/package.json, so npx convex only resolves there):

   cd chat
# 1. Seed the new role (idempotent — safe to re-run; { created: 1, skipped: 4 } the first time)
npx convex run roles:seedDefaults
# 2. One-shot patch to extend canGrantRoles on existing superadmin + admin rows
#    (seedDefaults is insert-only, so it does NOT touch existing rows — this step is required
#    or the new role will be invisible in the admin role-picker)
npx convex run roles:patchFinancialsGrantCeiling

For prod, append --prod:

   npx convex run roles:seedDefaults --prod
npx convex run roles:patchFinancialsGrantCeiling --prod

3. Sanity checks after running:

- seedDefaults should print { created: 1, skipped: 4 } on first run (zero on subsequent runs).

- patchFinancialsGrantCeiling should report { superadminUpdated: true, adminUpdated: true, missing: [] } on first run, then { superadminUpdated: false, adminUpdated: false, missing: [] } on re-runs.

- In the admin UI, opening any user's role picker should now list Financials Viewer for admins and superadmins (not for moderators).

4. Assign the role to whoever needs Financials access via /admin/users (the existing assignRole mutation handles the rest — no further code action needed).

### Common gotcha

If seedDefaults prints { created: 0, skipped: 4 }, the deployed Convex code is still on the old 4-role version — re-deploy the latest main (npx convex deploy from chat/, or wait for CI auto-deploy) and re-run.

### Summary

Adds a budget-column drill-down to the Monthly Financial Reporting feature. Clicking a budget cell on the Income Statement, EBITDA Reconciliation, or Cash Flow tables (and the Education memo's vertical P&L tables) opens a side panel showing a (type → department → account_name) breakdown sourced from core_budgets.consolidated_budgets_and_actuals. The panel reuses the existing detail-panel shell, with a new 2-level nested accordion component (NestedAccordionGroup). The Cash Flow path is wired end-to-end but returns not_populated=true until upstream CF budget data is loaded — when it lands, the panel will start showing data with no client change.

### Business Value

Finance can now audit any budget figure in the monthly report by drilling from the displayed cell down to the underlying budget rows, instead of cross-referencing the source spreadsheet. This shortens variance-investigation cycles during month-end close and gives leadership a self-service way to interrogate plan composition (by type, department, and account) directly inside Klair.

### Changes

- Backend: new endpoints /income-statement-budget-detail, /ebitda-reconciliation-budget-detail, and /cash-flow-budget-detail returning BudgetDimensionDetailResponse.

- Backend: fetch_income_statement_budget_dimension_detail and fetch_ebitda_budget_dimension_detail services with sign-flip / bu_addback / category-BU-exclusion logic that mirrors the actuals detail path; CF dispatcher reuses the EBITDA and IS rollups (Net Income, D&A, Mgmt+Import) with CF sign convention.

- Backend: extended build_pnl_resolved_cte with data_source and bad_debt_routing knobs; budget queries also restrict to the latest budget_cycle_start per reporting period so panel totals reconcile to the displayed cell.

- Frontend: new [BudgetDimensionDetailPanel.tsx](vscode-webview://15qdonnjjcq9q3pcmufmg5fa0asnqc6qnceup60m8cm6igoedkcj/klair-client/src/features/monthly-financial-reporting/components/detail-panels/BudgetDimensionDetailPanel.tsx), [NestedAccordionGroup.tsx](vscode-webview://15qdonnjjcq9q3pcmufmg5fa0asnqc6qnceup60m8cm6igoedkcj/klair-client/src/features/monthly-financial-reporting/components/detail-panels/NestedAccordionGroup.tsx), and [useEducationVerticalBudgetDetailPanel.tsx](vscode-webview://15qdonnjjcq9q3pcmufmg5fa0asnqc6qnceup60m8cm6igoedkcj/klair-client/src/features/monthly-financial-reporting/hooks/useEducationVerticalBudgetDetailPanel.tsx) hook; wired into IS/EBITDA/CF detail-panel hooks and [EducationMemoView.tsx](vscode-webview://15qdonnjjcq9q3pcmufmg5fa0asnqc6qnceup60m8cm6igoedkcj/klair-client/src/features/monthly-financial-reporting/components/EducationMemoView.tsx) (vertical tables, col-index 4).

- Frontend: new API adapter methods fetchIncomeStatementBudgetDetail / fetchEBITDABudgetDetail / fetchCashFlowBudgetDetail and shared BudgetDimensionDetailResponse types.

- Tests: new unit suites for the three backend services (resolver, sign convention, budget-cycle filter, placeholder behavior) and for the new frontend components/hooks; existing useCashFlowDetailPanel / useEBITDADetailPanel specs updated for the budget-column routing.

- transformCashFlows: set dataKey on the Adjustments row so its budget cell dispatches correctly.

### Testing

- [ ] cd klair-api && pytest tests/mfr/ — backend unit suite (resolver, IS/EBITDA/CF budget detail).

- [ ] cd klair-client && pnpm test src/features/monthly-financial-reporting/ — frontend unit suite.

- [ ] cd klair-client && pnpm tsc --noEmit && pnpm lint:pr — type check + lint.

- [ ] Manual: open MFR for a recent period; click a budget cell on Group / Software / Education IS, EBITDA, and a CF row, and on Education vertical tables — confirm panel totals match the cell value and the CF placeholder note renders.

http://localhost:3001/monthly-financial-reporting

https://github.com/user-attachments/assets/12faed17-fb20-4d11-9569-1f1485b20571

## Summary

New top-level page in Klair surfacing AI spend through the TrueFoundry gateway plus Max20x savings, list-vs-negotiated savings, and per-user footprint. Built for the budget cycle starting 2026-05-26.

Linear: [KLAIR-2766](https://linear.app/builder-team/issue/KLAIR-2766/truefoundry-dashboard-truefoundry-ai-gateway-spend-max20x-savings-per)

Driven by Jamie Sidey's brief (transcript at TrueFoundry/Keval _ Jamie - TrueFoundry Transcript.txt) and the leadership PDF report at TrueFoundry/AI Spend & Savings.pdf. The dashboard surfaces three things budget owners need:

1. Where AI spend is happening — by BU, by user, by provider/model.

2. What we've already saved — via Max20x seat conversions and the 10% Anthropic negotiated discount.

3. What we can still save — concrete Max20x migration candidates ranked by projected monthly savings.

Real-data smoke shows 41 candidates totalling $104k/month opportunity, with central-engineering as the top BU.

## What's in this PR

### Backend (klair-api)

New router at /api/truefoundry/* with 7 GET endpoints:

- /summary — 4 KPI tiles + per-BU multi-bar (actual + realized via Max20x + potential)

- /spend-per-user — per-person spend across claude.ai + Max20x + metered API

- /gateway — daily by provider, provider×model breakdown, top subjects, token mix

- /max20x — monthly net savings + ranked migration candidates with token detail

- /negotiated — list vs actual savings by source + daily trend

- /claude-ai — kept for parity (not currently surfaced by the FE)

- /diagnostics — super-admin only: reconciliation, untagged virtual keys, TF provider key map

All read from existing core_finance.ai_spend_* tables and views — no pipeline changes required.

BU filter slug-normalizes display-form names ("Central Engineering" → "central-engineering") so the FE filter shell composes correctly with TF and the candidates view (both store BUs in slug form). 23 pytest tests cover filter behavior, null handling, slug normalization, and shape contracts.

### Frontend (klair-client)

- New /truefoundry route with permissionPath: 'ai-adoption'.

- Executive summary: 4 KPI tiles + by-BU multi-bar chart (actual / realized / potential, two bars per BU).

- Tabs: Spend per user (default) · Gateway detail · Max20x · Negotiated savings · Diagnostics (super-admin only).

- All 5 tabs prefetch on initial page load (parallel debounced fetches); tabs stay mounted across switches so navigation is instant after first load.

- Distinct chart palette so series are visually separable on the dark theme.

- Skeleton loaders sized to each tab's content.

- Max20x table: orange "set up now" pill on top 4 candidates, BU sub-label, quarterly savings column, cursor-following hover tooltip with 30-day token mix + top model.

- Spend-per-user table merges claude.ai chat (user_email + display_name) and TF subjects (bridged via ai_spend_subject_identity for VAT slugs) into one canonical user identity.

### Design artifacts (in this PR)

- docs/superpowers/specs/2026-05-22-truefoundry-dashboard-design.md — design spec

- docs/superpowers/plans/2026-05-22-truefoundry-dashboard.md — implementation plan

## Test plan

- [ ] cd klair-api && uv run pytest tests/truefoundry/ -v → 23/23 passing

- [ ] cd klair-api && uv run ruff format … && uv run ruff check … && uv run pyright services/truefoundry_service.py models/truefoundry_models.py routers/truefoundry_router.py → clean

- [ ] cd klair-client && pnpm tsc --noEmit && pnpm lint:pr → clean

- [ ] cd klair-client && pnpm vitest run src/screens/TrueFoundry/ → 5/5 passing

- [ ] Visit /truefoundry with a date range covering Apr 2026 onwards: hero chart, all 5 tabs render with real data, BU filter narrows results, hover tooltips position correctly with cursor.

- [ ] As super-admin, confirm Diagnostics tab shows the yellow "FR5 pending" reconciliation banner + untagged-subjects table + provider key map.

## Open follow-ups (tracked in KLAIR-2766, not blocking)

1. ai_spend_claude_ai_chat_usage.bu is universally NULL — BU filter skipped on claude.ai queries. Pipeline-side backfill needed in Surtr.

2. VAT-slug users render as Davidschwartz — populate ai_spend_subject_identity to surface display names from claude.ai chat.

3. Realized savings per BU is a proxy (Max20x usage value). A proper per-BU realized view from Surtr would replace it.

4. is_truefoundry_routed flag is missing on OpenAI / Cursor direct-API tables — required before a portfolio-wide cross-pipeline deduped widget.

5. flagged_setup_now is currently auto-top-4; can switch to an admin-curated list if needed.

## Screenshots

<img width="1874" height="876" alt="image" src="https://github.com/user-attachments/assets/ff2a7b35-b6d6-4cfe-9092-5aa81d120f35" />

<img width="1676" height="729" alt="image" src="https://github.com/user-attachments/assets/ad5387e5-fb28-4f33-823c-e2171b694adc" />

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- CURSOR_AGENT_PR_BODY_BEGIN -->

## Summary

- Adds an opt-in addresses_finding_ids: list[str] field to Claire's regenerate_section and rewrite_section tool inputs so a single proposal can advertise which Review Agent findings it closes.

- Extends the existing PATCH /findings/{id}/status endpoint with optional provenance (addressed_via, tool_use_id, addressed_at) plus a telemetry INFO log when Claire's auto-resolve fires.

- Wires the FE Accept handler so that after a successful regenerate_section / rewrite_section, the scorecard flips the listed findings to addressed optimistically (with rollback on PATCH failure) — closes the review → chat → review loop without re-running /review.

## Why it's needed

Today, clicking Accept on a Claire proposal that addresses a finding updates the section but leaves the finding status="open" until the user manually re-runs review. Two real costs:

1. Scorecard staleness. The user has no immediate signal that their action moved the needle — they have to wait 30–60s for a fresh review run to find out.

2. Claire ambiguity. On the next chat turn, Claire still sees the finding as open and may helpfully suggest re-addressing what was just resolved.

This PR closes the loop: Claire tags her proposal with the finding IDs she's addressing, the FE auto-PATCHes them to addressed on Accept with a provenance trail, and operators get an INFO log they can count.

## Changes

### Backend (klair-api/)

- budget_bot/board_doc/claire_tools.py: add addresses_finding_ids: list[str] = Field(default_factory=list, ...) to RegenerateSectionInput and RewriteSectionInput. Surfaced in the Anthropic-facing CLAIRE_TOOLS JSON schema as an array<string> and called out in the Pydantic docstrings so Claire knows when to populate it.

- routers/board_doc_router.py: extend UpdateFindingStatusRequest with optional addressed_via: Literal["claire_regenerate", "claire_rewrite"], tool_use_id: str | None, addressed_at: str | None. Purely additive — existing {status}-only callers (scorecard manual triage) keep working unchanged. Emit a single INFO line on the PATCH endpoint when addressed_via is populated so production logs can count auto-resolve frequency distinctly from manual triage.

### Frontend (klair-client/)

- services/boardDocApi.ts: mirror addresses_finding_ids?: readonly string[] on RegenerateSectionToolInput / RewriteSectionToolInput, parse it in the TOOL_VALIDATORS registry, and extend updateFindingStatus with an optional provenance arg that adds the four-field shape to the PATCH body. Exports FindingAddressedVia and FindingStatusProvenance.

- hooks/useReviewAgent.ts: setFindingStatus now accepts an optional 5th provenance arg and forwards it to updateFindingStatus. Optimistic update + rollback semantics are unchanged.

- components/ChatToolProposal.tsx: new optional onAddressFindings prop. After a successful rewrite_section / regenerate_section Accept, fire it once with the proposal's addresses_finding_ids, the matching addressed_via literal, and the tool_use_id. No-op when the field is absent or the prop isn't wired.

- components/ChatPanel.tsx: forward onAddressFindings from the parent.

- DocumentEditorPage.tsx: implement the callback — for each finding ID, call reviewAgent.setFindingStatus(sessionId, findingId, 'addressed', provenance) so the scorecard optimistic-flips and rolls back on PATCH failure (matches the B3.15 comment-status pattern).

### Tests

- tests/board_doc/test_claire_tools.py: defaults / single-ID / multi-ID validation for both inputs, end-to-end round-trip through parse_tool_calls, CLAIRE_TOOLS schema shape assertions (field present + not required).

- tests/board_doc/test_finding_status_endpoint.py: full provenance payload accepted (200 + persistence + INFO log fires with claire_regenerate / claire_rewrite), invalid addressed_via rejected with 422, legacy single-field callers still work AND don't trigger the auto-resolve telemetry log, oversized tool_use_id rejected with 422.

- components/__tests__/ChatToolProposal.spec.tsx: 7 new tests covering 0-ID / single-ID / multi-ID invocation counts, Accept failure on both tools suppresses auto-resolve, omitted callback graceful no-op.

- hooks/__tests__/useReviewAgent.spec.ts: hook-level test confirming the provenance arg threads through to updateFindingStatus; existing manual-triage path updated to assert undefined is passed for back-compat.

### Verification artifact — proposal + PATCH payloads

A regenerate_section proposal carrying populated addresses_finding_ids:

{
"tool_use_id": "toolu_01ABCxyz",
"name": "regenerate_section",
"input": {
"section_id": "financials",
"feedback": "Refresh with Q2 walk-back, address C2.1 and C2.3.",
"addresses_finding_ids": ["finding-c21-001", "finding-c23-002"]
}
}

The resulting PATCH request body the FE fires (one per finding ID):

{
"status": "addressed",
"addressed_via": "claire_regenerate",
"tool_use_id": "toolu_01ABCxyz",
"addressed_at": "2026-05-22T15:30:00.000Z"
}

## Breaking changes

None. Both the Pydantic input field and the PATCH body extensions are opt-in with default-empty / None defaults. Existing Claire proposals continue to parse cleanly; the scorecard manual-triage path keeps sending plain {status} bodies.

## Test plan

Backend:

- [x] cd klair-api && uv run pytest tests/board_doc/test_claire_tools.py -v — 59 passed

- [x] cd klair-api && uv run pytest tests/board_doc/test_finding_status_endpoint.py -v — 21 passed

- [x] cd klair-api && uv run pytest tests/board_doc/test_review_findings.py -q — 30 passed

- [x] cd klair-api && uv run ruff format + uv run ruff check — clean

- [x] cd klair-api && uv run pyright budget_bot/board_doc/claire_tools.py routers/board_doc_router.py — 0 errors

- [x] cd klair-api && uv run pytest tests/board_doc/ -q — 1738 passed, 8 failed (the pre-existing C3.x family flakes; same set fails on main)

Frontend:

- [x] cd klair-client && pnpm test src/screens/BoardDoc/ — 287 passed

- [x] cd klair-client && pnpm tsc --noEmit — clean

- [x] cd klair-client && pnpm exec eslint --max-warnings 0 on changed files — clean

Manual validation still needed:

- [ ] In dev, accept a real Claire regenerate_section proposal that lists a finding in addresses_finding_ids and confirm the scorecard finding flips to addressed immediately + the BE log line fires.

- [ ] Simulate a PATCH failure (e.g. force a 500 on /findings/{id}/status) and confirm the scorecard rolls back + the error chip surfaces.

## Out of scope (per the drone spec)

- No changes to the other 5 Claire tools (add_comment / add_section / remove_section / rename_section / update_table_cell) — they don't semantically resolve findings.

- No system-prompt changes to encourage Claire to populate addresses_finding_ids more aggressively — the tool description nudge here is the only steering for now; prompt-tuning is a future iteration.

- No retroactive PATCHes against findings closed by prior Claire proposals — purely forward-looking from this merge.

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a href="https://cursor.com/agents/bc-f72bd0ac-aa11-4e6d-bf3c-5af1414413ee"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-web-light.png"><img alt="Open in Web" width="114" height="28" src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a>&nbsp;<a href="https://cursor.com/background-agent?bcId=bc-f72bd0ac-aa11-4e6d-bf3c-5af1414413ee"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-cursor-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-cursor-light.png"><img alt="Open in Cursor" width="131" height="28" src="https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a>&nbsp;</div>

### Summary

Swaps the middle grouping dimension of the budget-column drill-down (PR #2853) from department to business_unit. The drill-down now displays type → business_unit → account_name end-to-end (SQL, response shape, accordion UI, CSV export). The 2-level accordion shell is unchanged — only the field name, label, and grouping key swap. The "single-level" mode used by the Education vertical drill-down is renamed from departments-only to business-units-only.

### Business Value

Finance asked for BU instead of department as the audit dimension on the budget panel. BU is the cut they reason about for plan ownership and variance review, so seeing it directly (rather than the finer department slice) shortens variance investigations during month-end close.

### Changes

- Backend: fetch_income_statement_budget_dimension_detail / _ebitda_gaap_budget_query / _ebitda_other_net_budget_query / _ebitda_bu_budget_query now SELECT/GROUP BY/ORDER BY (type, business_unit, account_name). The resolver CTE projects t1.business_unit unconditionally for budget queries (was opt-in via extra_columns only when an Education vertical filter was supplied).

- Backend: _df_to_budget_rows returns business_unit keys; _ebitda_total_budget_breakdown and the Software reconciliation rows updated to match.

- Backend: cash_flow_service._cf_mgmt_restructuring_budget_breakdown swaps the row-merge key from department to business_unit; two not-populated note strings updated.

- Backend: Pydantic BudgetDimensionDetailRow.department → business_unit; endpoint URLs unchanged.

- Frontend: TS BudgetDimensionDetailRow.department → business_unit; DepartmentGroup → BusinessUnitGroup; mode: 'departments-only' → 'business-units-only'; table header strings Department / Account → BU / Account and Type / Department / Account → Type / BU / Account; CSV column updated.

- Tests: 4 backend test suites + 2 frontend spec files updated to the new field names and SQL substring.

### Education vertical note

The Education vertical drill-down already filters by business_unit to scope to a single vertical's BU set. After this swap it now also groups by BU, so an Education panel typically shows a single BU heading with all accounts beneath. Behavior is functional but flatter than before; verify with Finance that this is acceptable for that path.

### Testing

- [x] cd klair-api && uv run pytest tests/mfr/budget_drilldown/ — 76 passed

- [x] cd klair-client && pnpm test src/features/monthly-financial-reporting/ --run — 613 passed

- [x] cd klair-client && pnpm tsc --noEmit — clean

- [x] cd klair-client && pnpm exec eslint --max-warnings 0 on changed files — clean

- [x] cd klair-api && uv run ruff format / ruff check — clean

- [ ] Manual: open MFR for a recent period; click a budget cell on Group / Software IS, EBITDA, a CF row, and an Education vertical row — confirm the panel shows BU headings (not Department) and totals still tie to the displayed cell.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

http://localhost:3001/monthly-financial-reporting

https://github.com/user-attachments/assets/250b4555-c48e-4c19-8b39-2bdfe165c6f2

## Summary

- Add an on-demand Aerie Operating details endpoint for recent notes and dated/statused work-unit/task context

- Keep the existing quality-bar score endpoint lean for top-level Operating views

- Document the new read-only Aerie route and note-window contract

## Why

Aerie needs richer details only after users open the Operating detail panel. Returning all nested notes and task/work-unit context from the summary endpoint would make the baseline payload heavier and less predictable.

## Business Value

Keeps the main Operating dashboard fast while giving Aerie enough scoped detail to render expanded rows and generate note roll-up summaries on demand.

## Test plan

- [x] node --test --experimental-strip-types convex/qualityBars.test.ts

- [x] npm exec --package typescript -- tsc -p convex/tsconfig.json --noEmit

- [x] git diff --check

- [x] Queried Alpha Miami dev data and locally sized the projected details payload

- [ ] Deploy to dev and verify GET /sync/aerie/getOperatingDetails after cleaning the existing dev schema mismatch (documents.docType = "loi")

## Summary

- New top-level Financials tab in the Dashboards sidebar.

- Renders a QuickBooks-sourced Revenue Breakdown table by quarter + YTD: Net Tuition, Discounts, Stripe fees, *Net Tuition calculated*, Lunch, Other Revenue, Total Revenue.

- School dropdown filtered to Miami for this POC (default-selected).

- Backend: new Convex queries getRevenueBreakdown (aggregates plRecords with a school-agnostic line-item classifier) and getPlSchools (distinct school names from plRecords).

## Test plan

- [ ] Visit /dashboards?tab=financials and confirm the Financials tab renders without console errors.

- [ ] Confirm the school dropdown shows only Miami and is pre-selected.

- [ ] Cross-check Miami Q1/Q2 values against QuickBooks for Net Tuition, Discounts, Stripe fees, Lunch, Other Revenue.

- [ ] Verify Net Tuition calculated = Net Tuition − Discounts − Stripe fees and Total Revenue sums match.

- [ ] Click Export CSV and confirm rows match the rendered table (sign-flipped for Discounts/Stripe).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

## Summary

- Materialize cleared Due Diligence fields as explicit null values for Rhodes while preserving REBL3 strict-replace behavior.

- Convert expected missing-status DD validation into a structured failure and show friendly save-dialog guidance instead of raw Convex errors.

- Raise the theme picker popover above forecast dashboard controls.

## Why

A Due Diligence removal from the Aerie UI could update REBL3 while Rhodes preserved the old value, leaving the paired systems out of sync. During follow-up testing, the missing-status path also surfaced raw Convex errors to users, which made actionable validation look like a broken system. The forecast dashboard theme picker also rendered behind nearby controls.

## Business Value

Keeps REBL3 and Rhodes aligned when operators clear Due Diligence fields, makes expected validation failures understandable to end users, and removes a visible dashboard polish issue from the hotfix.

## Test plan

- [x] pnpm --filter @bran/contracts test -- due-diligence

- [x] pnpm --filter chat exec vitest run convex/dueDiligence.test.ts

- [x] pnpm --filter chat exec vitest run components/dashboards/portfolio/fields/__tests__/portfolio-fields-provider.test.tsx components/site-fields/__tests__/save-confirm-dialog.test.tsx

- [x] pnpm --filter chat exec vitest run components/dashboards/portfolio/cards/__tests__/due-diligence-editor.test.tsx components/dashboards/portfolio/fields/__tests__/portfolio-fields-provider.test.tsx components/dashboards/portfolio/__tests__/portfolio-view.test.tsx

- [x] pnpm --filter chat exec vitest run components/shell/__tests__/theme-picker-popover.test.tsx

- [x] pnpm --filter @bran/contracts typecheck

- [x] pnpm --filter chat typecheck

- [x] pnpm biome check on touched files

<!-- CURSOR_AGENT_PR_BODY_BEGIN -->

## Summary

- Added C3.1 (check_margin_per_product_benchmark) — the first floor check in the C3.x per-product benchmark family. Absorbs the original backlog's C3.1 (sub-50% margin shutdown analysis) and C3.2 (net margin vs 75% benchmark) into a single P-W-C verdict ladder per the May 20 triage call: both read the same row; the only difference between the two cards is the verdict threshold, which collapses naturally into a single ladder with sub-50% framed as narrative emphasis on the Critical tier (not a separate verdict band).

- Reused the sibling C3.x scaffolding (typed skip ladder, ragged-row WARNING, per-product fan-out routing via is_rollup, BenchmarkPerProductSupport / BenchmarkAggregateSupport) — only the gap formula, the row addressing, and the Critical-tier prose differ from the ceiling-check siblings.

- Added a dedicated C3.1 test module (TestPerProductFanOut, TestPerProductTargetLookup, TestSkipSemantics, TestShutdownNarrative, TestRaggedRowDriftWarning, TestTargetCategoryPin, TestRegistryWiring, TestBoundaries, plus section-id-resolution + supporting-data coverage).

- Updated test_review_endpoint.py happy-path / missing-data / partial-completeness expectations and seeded the BENCHMARK_BY_PRODUCT fixture with the (summary, Margin) + (summary, Margin Target) rows so C3.1 emits its BU-level pass finding (no skip) under the populated path.

## Why it's needed

- C3.1 is the family's first floor check (C3.3 → C3.9 are all cost-ratio ceilings). Without it the per-product scorecard never surfaces a margin-floor violation — the original sub-50% shutdown trigger and the 75% margin benchmark both lived in the backlog without a runtime check.

- Per-product margin is the cleanest single signal that a Trilogy product is funding its own operating model; a material shortfall against the Finance-set target either reflects a cost-side overhang or a revenue / pricing gap that needs explicit GM commentary.

- Merging the two backlog cards keeps the per-product benchmark scorecard scoped to one check per metric while still surfacing the shutdown narrative for sub-50% margins via differentiated prose on the Critical tier.

## Changes

- Added klair-api/budget_bot/board_doc/review_checks/margin_per_product_benchmark.py:

- CHECK_ID = "C3.1", CHECK_AREA = "Per-Product Benchmarks".

- _TARGET_SECTION = "summary", _TARGET_CATEGORY_ACTUAL = "Margin", _TARGET_CATEGORY_TARGET = "Margin Target", _WARNING_BAND_PP = 5.0, _SHUTDOWN_THRESHOLD_PCT = 50.0.

- @register(... name="Per-product margin vs target (sub-50% shutdown)", required_data=(DataSourceKey.BENCHMARK_BY_PRODUCT,)).

- Sign-flipped gap_pp = target_pct - actual_pct with an inline cross-reference comment to the C3.3 ceiling pattern this inverts.

- Per-column target lookup inside the per-product loop — BenchmarkPerProductSupport.standard_benchmark_pct populated from the per-column target_pct, no schema change.

- Three typed-skip paths (tab missing → INFO; (summary, Margin) row missing → WARNING; (summary, Margin Target) row missing → WARNING) plus the all-blank INFO skip.

- Critical-tier narrative branches on _SHUTDOWN_THRESHOLD_PCT — shutdown-analysis framing iff actual_pct < 50%; standard "below target" framing otherwise. Severity stays "critical" in both cases.

- Added klair-api/tests/board_doc/test_margin_per_product_benchmark.py covering:

- Fan-out with mixed-band actuals (Pass, Warning, standard Critical, shutdown-framed Critical).

- Per-product target lookup — non-uniform targets prove the lookup is load-bearing (same actual lands in different verdict bands depending on whose target column it's compared against).

- All four skip paths (tab missing INFO; Margin row missing WARNING; Margin Target row missing WARNING; all-blank INFO).

- Shutdown-framing boundary pinned at 50% — 49.99% shutdown framing, 50% / 50.01% standard framing.

- Boundary inclusivity (actual == target → pass; actual == target - 5pp → warning; gap_pp = 6 with 69% actual → critical, standard framing).

- Ragged-row WARNING on BOTH the Margin row and the Margin Target row.

- Drift sentinels for _TARGET_CATEGORY_ACTUAL, _TARGET_CATEGORY_TARGET, AND _TARGET_SECTION (distinct from the C3.3 → C3.9 "total").

- Registry wiring pin (id, area, name, required_data).

- Updated klair-api/tests/board_doc/test_review_endpoint.py:

- Added "C3.1" to the populated-path check_ids set and to the skipped_checks sets of the two missing-data tests + the partial-completeness test.

- Bumped happy-path len(data["findings"]) from 14 to 15 (one BU-level pass finding from C3.1).

- Seeded (summary, Margin) + (summary, Margin Target) in the BENCHMARK_BY_PRODUCT fixture at 75% for Skyvera Consolidated so C3.1's rollup passes silently and the aggregate-pass fires.

## Breaking changes

None.

## Test plan

- [x] cd klair-api && uv run ruff format budget_bot/board_doc/review_checks tests/board_doc (no changes)

- [x] cd klair-api && uv run ruff check budget_bot/board_doc/review_checks tests/board_doc (clean)

- [x] cd klair-api && uv run pyright budget_bot/board_doc/review_checks/margin_per_product_benchmark.py tests/board_doc/test_margin_per_product_benchmark.py (0 errors)

- [x] cd klair-api && uv run pytest tests/board_doc/test_margin_per_product_benchmark.py tests/board_doc/test_review_endpoint.py -q (49 passed)

- [x] cd klair-api && uv run pytest tests/board_doc -q (8 pre-existing unrelated failures in test_review_findings.py, test_saas_it_ops_benchmark.py, test_sales_marketing_benchmark.py, test_section_crud_endpoints.py, test_support_benchmark.py — same set already noted in C3.9's PR #2837; no C3.1-related failures; my changes resolve the 4 prior test_review_endpoint.py failures that fell out of adding C3.1 to the registry)

## Verification artifact

Two C3.1 findings from a fixture with Skyvera Consolidated = 80% (pass), ProductA = 60% / target 75% (standard Critical, 50%-70% band), and ProductB = 40% / target 75% (shutdown-framed Critical, sub-50%) — pinning both narrative tracks:

{
"check_id": "C3.1",
"severity": "critical",
"section_id": "product_detail_producta",
"what": "ProductA margin (60.0%) is 15.0pp below its 75.0% target.",
"supporting_data": {
"product": "ProductA",
"is_rollup": false,
"actual_pct": 60.0,
"benchmark_pct": 75.0,
"gap_pp": 15.0,
"warning_band_pp": 5.0,
"standard_benchmark_pct_in_sheet": 75.0
}
}

{
"check_id": "C3.1",
"severity": "critical",
"section_id": "product_detail_productb",
"what": "ProductB margin (40.0%) is 35.0pp below its 75.0% target AND below the 50% shutdown threshold — shutdown analysis required.",
"supporting_data": {
"product": "ProductB",
"is_rollup": false,
"actual_pct": 40.0,
"benchmark_pct": 75.0,
"gap_pp": 35.0,
"warning_band_pp": 5.0,
"standard_benchmark_pct_in_sheet": 75.0
}
}

Closes KLAIR-2676

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a href="https://cursor.com/agents/bc-1095d644-356d-4ea5-9c7a-9ebf17eb2283"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-web-light.png"><img alt="Open in Web" width="114" height="28" src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a>&nbsp;<a href="https://cursor.com/background-agent?bcId=bc-1095d644-356d-4ea5-9c7a-9ebf17eb2283"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-cursor-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-cursor-light.png"><img alt="Open in Cursor" width="131" height="28" src="https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a>&nbsp;</div>

## Demo

<img width="2624" height="1636" alt="image" src="https://github.com/user-attachments/assets/971b515d-068f-420b-8bb3-fd0ab1c9fb4e" />

## Summary

Linear: [KLAIR-2765](https://linear.app/builder-team/issue/KLAIR-2765/investigate-docker-and-kubernetes-cost-fetch-errors-for-q326-budget)

Fixes a FE/BE mismatch in how an ISO week is assigned to a calendar quarter. The frontend used pure week-number bucketing (W14–26 → Q2), while the backend validator and ingestion pipeline use the ISO Monday's calendar quarter. Quarter-boundary weeks (W1, W14, W27, W40 of 2026) tripped the backend's _validate_weeks_in_quarter check and returned 400 for both /docker-cost and /kubernetes-cost.

Single point of fix: TS port of klair-api/utils/quarter_math.py:iso_week_quarter into klair-client/src/screens/AWSSpend/components/SaaSBudgeting/isoWeekDates.ts. No backend or ingestion changes.

## Spec

- 29-align-fe-quarter-from-iso-week-to-monday-rule — Port BE Monday-based iso_week_quarter rule to TS so FE, BE, and ingestion pipeline agree on quarter boundaries. Rewrites the misleading inline comment. Adds boundary-week + year-crossover unit tests for quarterFromIsoWeek, groupWeekKeysByQuarter, and latestQuarterFromWeekKeys.

## Files changed

- klair-client/src/screens/AWSSpend/components/SaaSBudgeting/isoWeekDates.ts — quarterFromIsoWeek body + inline comment block

- klair-client/src/screens/AWSSpend/components/SaaSBudgeting/isoWeekDates.spec.ts — updated stale assertions and added boundary coverage

- features/aws-spend/saas-budgeting/FEATURE.md + spec 29 — doc/changelog updates

## Test coverage

- 35 it(...) blocks across 7 describe blocks in isoWeekDates.spec.ts (was 21). All pass.

- Covers: 4× 2026 boundary weeks (W1/W14/W27/W40), 4× ordinary weeks (W13/W26/W39/W52), 1× year-crossover (2020-W53 mirroring the BE TestIsoWeekQuarter shape) and 1× synthetic year-crossover (2021-W53 → 2022-Q1). Downstream groupWeekKeysByQuarter and latestQuarterFromWeekKeys re-tested under the new rule.

## Self-review

No issues found (Phase 7 self-review subagent). Port arithmetic verified against three known mappings.

## CI

- build ✓ pass

- lint ✓ pass

- ruff-check ✓ pass

- test, review, auto-merge — skipped (no backend changes; gated workflows)

- claude-review ⚠️ soft-fail — caused by a duplicate Frontend CI workflow run at this commit SHA (one cancelled within seconds of starting due to workflow-concurrency, the other fully green). The wait-for-checks step inside claude-review rejects the cancelled status of the duplicate even though the live run is green. Not a code defect; reverifiable from the workflow logs.

## Test plan

- [ ] pnpm vitest run for isoWeekDates.spec.ts — green

- [ ] pnpm tsc --noEmit — clean

- [ ] Manual: /docker-cost?quarter=2026-Q2&weeks=14,... no longer returns 400; W14 now groups under 2026-Q1 (matches BE)

<!-- CURSOR_AGENT_PR_BODY_BEGIN -->

Refs KLAIR-2716.

## Summary

Converts generate_mips from a deterministic read of spec.bu_mips to an LLM-first generator whose source of truth is the section's current content (cloned-doc body, wizard-bridged MIPs, or operator-edited draft) plus DataPackage signals plus open review findings. Joins the same SectionRefreshContext contract as the five B9.1-B9.5 siblings shipped in PR #2851.

## Why it's needed

spec.bu_mips is a wizard-coupled mirror of state that also lives in generated_sections["mips"]. The pre-B9 deterministic generate_mips reads the mirror; the user edits the section body. Those two stores drift, and a regenerate from a clone-imported doc that never went through the MIPs wizard returns "" — exactly the dual-store read/write reconciliation bug B9 exists to fix. B9.6 collapses MIPs onto the same single source of truth the other five B9 generators already use, with a producer→consumer bridge at publish time so wizard-approved MIPs flow into the LLM-first refresh path.

## Changes

- budget_bot/board_doc/section_generators.py

- Adds _MIPS_SYSTEM next to the four existing B9 inline system prompts. MIP-specific in-scope / not-in-scope framing on top of the shared _B9_DISPOSITION / B9_SCOPE_DISCIPLINE / B9_OUTPUT_RULES / SHARED_SUFFIX_WITH_CITATIONS blocks, plus an explicit output template (### MIP <n>: <statement> + paragraph + bulleted actions) so per-MIP heading shape stays stable across refreshes.

- Rewrites generate_mips to the canonical B9 shape: 3 positional args + *, context: SectionRefreshContext | None = None. Builds a BU-wide data block via build_key_metrics_block, runs through _build_b9_user_message + _strip_cite_tags + _resolve_system_prompt, and one-shots _llm_generate. Cold-start path logs a warning with BU / quarter provenance when both the metrics digest and ctx anchors are empty, so a broken DataPackage shows up in monitoring instead of silently producing a brainlift-only draft.

- Adds SectionType.MIPS to _B9_CONTEXT_AWARE so _regenerate_section builds and threads the context.

- Trims the now-stale "(financials, exec summary, mips, custom)" comment in generate_section's dispatcher.

- budget_bot/board_doc/wizard_orchestrator.py

- Producer→consumer bridge. _regenerate_all now writes _render_mips_markdown(spec.bu_mips, heading="") into session.generated_sections[<mips section id>] after the bulk generate_all_sections call, so wizard-approved MIPs survive first publish and are available as SectionRefreshContext.current_content on subsequent operator-driven refreshes. Tracked for migration to a no-op under B9.8 (KLAIR-2718).

- Refreshes two stale comment blocks in _regenerate_section (the empty-result fallback to generate_custom_section and the belt-and-suspenders guard at the section-result tail) to reflect that post-B9.6 no in-tree LLM-first generator legitimately returns success=True with empty markdown — _EmptyLLMResult short-circuits inside the retry loop. Operator-facing log message no longer misattributes unexpected emptiness to "a deterministic generator (MIPs) lacking the wizard-step input".

- budget_bot/board_doc/models.py

- Expands the inline deprecation note on DocumentSpec.bu_mips to list the remaining readers (generate_gm_commentary threads it into the GM prompt; generate_cf_plan short-circuits to a deterministic render) so a future PR that trusts the note doesn't silently break either generator. Field removal still tracked under KLAIR-2718.

- tests/board_doc/test_b9_narrative_generators.py

- Adds a TestGenerateMips class covering cold-start, current_content / findings_block / full_doc_block threading, dead-spec.bu_mips-input independence (load-bearing regression for the source-of-truth shift), LLM exception propagation, a strengthened generate_product_detail integration test that exercises the real per-product MIPs render path, and an isolated _render_mips_markdown smoke test. The cold-start test also pins that _resolve_system_prompt picked up _MIPS_SYSTEM (not a sibling B9 constant).

- tests/board_doc/test_wizard_orchestrator.py

- Adds TestRegenerateAllMipsBridge pinning the wizard-MIPs → generated_sections["mips"] bridge: approved MIPs flow through, bu_mips=[] leaves the LLM cold-draft intact.

## Breaking changes

None at the Python API surface — generate_mips keeps its three positional args; the new context kwarg is keyword-only with a None default. Behavioural change for callers that previously relied on spec.bu_mips populating the BU MIPs section: those callers now get the wizard-approved MIPs rendered through the bridge in _regenerate_all, and the section body becomes the new single source of truth on subsequent regenerations.

## Contract surface affected

1. generate_mips signature. Gains *, context: SectionRefreshContext | None = None. Existing call sites in _GENERATOR_MAP route through generate_section's _invoke wrapper, which dispatches the kwarg based on _B9_CONTEXT_AWARE membership — no call-site updates required.

2. _B9_CONTEXT_AWARE set. Grows from 5 to 6 members (adds SectionType.MIPS).

3. _render_mips_markdown caller count. Holds at 2: generate_product_detail (product-level MIPs) and _regenerate_all (new wizard-bridge call). The helper stays in tree.

4. DocumentSpec.bu_mips. Marked deprecated for generate_mips; deprecation note now spells out the two remaining readers (generate_gm_commentary, generate_cf_plan) that block field removal.

## Test plan

- cd klair-api && uv run pytest tests/board_doc/test_b9_narrative_generators.py -v → 38 passed (7 new TestGenerateMips cases).

- cd klair-api && uv run pytest tests/board_doc/test_wizard_orchestrator.py -v → 127 passed (2 new TestRegenerateAllMipsBridge cases).

- cd klair-api && uv run pytest tests/board_doc -q --timeout=120 → 1730 passed, same 8 pre-existing failures verified identical on main with branch stashed (test-ordering flakes in test_review_findings, test_saas_it_ops_benchmark, test_sales_marketing_benchmark, test_section_crud_endpoints, test_support_benchmark; all pass individually).

- cd klair-api && uv run ruff format <touched files> → clean.

- cd klair-api && uv run ruff check <touched files> → all checks passed.

- cd klair-api && uv run pyright budget_bot/board_doc/section_generators.py budget_bot/board_doc/models.py budget_bot/board_doc/wizard_orchestrator.py → 0 errors (1 pre-existing warning at wizard_orchestrator.py:7066, untouched).

### Verification artifact — prompt shape on a populated fixture

TestGenerateMips::test_current_content_threads_into_prompt captures the user-message prompt with context.current_content populated and asserts that the prior MIPs body lands under the canonical ## Current Section Content (cloned-doc body / prior draft — refresh in place) header alongside the BU-wide data block. test_dead_bu_mips_input_does_not_leak is the load-bearing pin for the source-of-truth shift: spec.bu_mips = [MIP(title="STALE WIZARD MIP", ...)] does not appear anywhere in the captured prompt.

### CLAUDE.md sweep on touched modules

- section_generators.py: post-edit grep of the new generate_mips body for spec.bu_mips returns zero matches (load-bearing acceptance criterion). No except Exception: swallow inside the new function; LLM failures propagate to the retry loop in generate_section. The cold-start path's empty-build_key_metrics_block branch logs an observable warning when the context also has no anchor, addressing the empty-defaults / silent-failure shape from CLAUDE.md.

- wizard_orchestrator.py: the empty-result fallback in _regenerate_section is unreachable for the LLM-first family by construction (now documented). The new bridge in _regenerate_all is a deterministic post-generation overwrite — no swallowed exceptions.

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a href="https://cursor.com/agents/bc-344d8b86-5a90-4052-960c-6064b723b98b"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-web-light.png"><img alt="Open in Web" width="114" height="28" src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a>&nbsp;<a href="https://cursor.com/background-agent?bcId=bc-344d8b86-5a90-4052-960c-6064b723b98b"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-cursor-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-cursor-light.png"><img alt="Open in Cursor" width="131" height="28" src="https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a>&nbsp;</div>