Fix spec ambiguities: StatementKey/PeriodKey types, FCF margin source, FinancialsPage props

1 files changed, 11 insertions, 2 deletions

diff --git a/docs/superpowers/specs/2026-05-17-financials-tab-design.md b/docs/superpowers/specs/2026-05-17-financials-tab-design.md
index 6aed8af..2e7ad3f 100644
--- a/docs/superpowers/specs/2026-05-17-financials-tab-design.md
+++ b/docs/superpowers/specs/2026-05-17-financials-tab-design.md
@@ -66,7 +66,7 @@ New function `get_financials(ticker, period)` using yfinance:
 - **Annual:** `t.income_stmt`, `t.balance_sheet`, `t.cashflow` (4 fiscal years). TTM column computed as sum of last 4 quarters from quarterly statements. Balance sheet last column is MRQ (most recent quarter), not TTM.
 - **Quarterly:** `t.quarterly_income_stmt`, `t.quarterly_balance_sheet`, `t.quarterly_cashflow` (last 8 quarters). No TTM column.
 - Follows v1 `get_income_statement` / `get_balance_sheet` / `get_cash_flow` pattern with empty-DataFrame fallback on error.
-- Margin rows (gross margin, net margin, FCF margin) are computed server-side and included as `is_margin=True` rows.
+- Margin rows (gross margin, net margin, FCF margin) are computed server-side and included as `is_margin=True` rows. FCF margin = FCF / Total Revenue; Revenue is pulled from the income statement so both statements share the same fetch call.
 
 ---
 
@@ -146,6 +146,13 @@ Section eyebrows: OPERATING, INVESTING, FINANCING (is_section=True)
 - `frontend/lib/overview.ts` — add `financials` to `OVERVIEW_NAV_ITEMS`
 - `frontend/app/page.tsx` — read `tab` from `useSearchParams`, render `<FinancialsPage>` when appropriate
 
+### Types
+
+```ts
+type StatementKey = "income" | "balance" | "cash_flow"
+type PeriodKey    = "annual" | "quarterly"
+```
+
 ### FinancialsCard
 
 Props: `{ data: FinancialsResponse, statement: StatementKey, period: PeriodKey, onChangeStatement, onChangePeriod }`
@@ -165,7 +172,9 @@ Props: `{ data: FinancialsResponse, statement: StatementKey, period: PeriodKey,
 
 ### FinancialsPage
 
-Handles three states: `loading`, `ready`, `error`. Fetches on ticker + period change. Renders `<TickerHeader>`, `<KPIStrip>` (reused from Overview), then `<FinancialsCard>`.
+Props: `{ overview: TickerOverview, ticker: string }` — `page.tsx` already fetches `overview` for the header and passes it down.
+
+Handles three states: `loading`, `ready`, `error` for the financials fetch. Renders `<TickerHeader>` and `<KPIStrip>` (same components as Overview, fed from the `overview` prop), then `<FinancialsCard>`. Fetches financials on mount and when `ticker` or `period` changes.
 
 ---