feat(agent,interface): expose SEC filings through agent capabilities and stock page

Wires the filings data layer into user-facing surfaces:
- `sec_filings`, `sec_filing_document`, `sec_filing_section` agent
capabilities with workflow-shaped tool descriptions.
- Stock-page filings routes + payloads and a frontend SecFilings /
FilingMarkdown component for rendering 10-K/10-Q bodies.
- Integration tests for the capabilities, the service, and the stock
filings API.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

docs/interface.md

@@ -293,9 +293,10 @@ routes.
 Source: `src/TerraFin/interface/stock/`
 
 Stock Analysis combines a chart-first page route with a small API family for
-company profile, earnings history, financials, and search routing. The page
-itself uses the shared TerraFin chart session and progressive `3Y -> full`
-history loading described in [chart-architecture.md](./chart-architecture.md).
+company profile, earnings history, financials, SEC filings, and search routing.
+The page itself uses the shared TerraFin chart session and progressive
+`3Y -> full` history loading described in
+[chart-architecture.md](./chart-architecture.md).
 
 ### Page routes
 
@@ -311,8 +312,53 @@ history loading described in [chart-architecture.md](./chart-architecture.md).
 | `GET` | `/stock/api/company-info` | Company profile and price summary (`?ticker=`) |
 | `GET` | `/stock/api/earnings` | Earnings history (`?ticker=`) |
 | `GET` | `/stock/api/financials` | Financial statements (`?ticker=`, `statement=`, `period=`) |
+| `GET` | `/stock/api/filings` | Recent 10-K / 10-Q / 8-K list with EDGAR URLs (`?ticker=`, `limit=`) |
+| `GET` | `/stock/api/filing-document` | Parsed markdown + TOC for one filing (`?ticker=`, `accession=`, `primaryDocument=`, `form=`, `includeImages=`) |
 | `GET` | `/resolve-ticker` | Resolve free-form search into `/stock/...` or `/market-insights?...` |
 
+### SEC Filings panel
+
+The `/stock/{ticker}` page includes a **SEC Filings** card for every US-listed
+issuer. The card is hidden automatically for tickers without an SEC CIK (e.g.
+KOSPI / TSE / HKEX issuers) so non-US pages stay uncluttered.
+
+For supported tickers the card surfaces:
+
+- a form dropdown derived from `df.form.unique()` (covers 10-K, 10-Q,
+  amendments, 8-K, 20-F, 40-F, etc.);
+- a chronological filing list with a **View on EDGAR** link per row pointing
+  at the SEC inline-XBRL viewer (`/ix?doc=/Archives/...`);
+- a reader that opens inline below the list, with:
+    - a two-level accordion preserving Part I / Part II as outer collapsibles
+      and Items (Item 1, Item 2 MD&A, …) as nested inner collapsibles;
+    - a compact custom markdown renderer that handles our `parse_sec_filing`
+      output (`##`/`###` headings, paragraphs, GFM pipe tables, blockquote
+      fallbacks, inline-image placeholders) without pulling in a general
+      markdown dep;
+    - a "View source on EDGAR" pill in the reader header.
+
+The parsed markdown is cached for 30 days via the shared `sec_filings`
+CacheManager namespace (see [caching.md](./caching.md)), so reopening a filing
+is free across sessions. See [data-layer.md](./data-layer.md) for the
+underlying `parse_sec_filing` / `build_toc` / `get_sec_data` helpers.
+
+### Agent integration
+
+When the user opens a filing, the panel publishes the currently-focused
+section to the agent side-panel via `publishAgentViewContext`. The `selection`
+carries `ticker`, `form`, `accession`, `primaryDocument`, `sectionSlug`,
+`sectionTitle`, a bounded `sectionExcerpt` (≤ 4 KB), and EDGAR URLs. The
+hosted agent's `current_view_context` tool reads this payload, and the agent
+can call `sec_filings`, `sec_filing_document`, or `sec_filing_section` to
+fetch the full body when the excerpt is not enough (e.g. "summarize their
+business" on a 10-Q will trigger a cross-filing pivot to the most recent
+10-K's Item 1. Business). See [agent/usage.md](./agent/usage.md#10-k--10-q-research).
+
+For the full end-to-end view-context pipeline (how `publishAgentViewContext`
+reaches the agent, how sessionStorage routes identity, why the session link
+sometimes goes stale, and how to debug when the agent "doesn't know what I'm
+looking at"), see [agent/view-context.md](./agent/view-context.md).
+
 ---
 
 ## Watchlist

src/TerraFin/agent/runtime.py

@@ -601,6 +601,89 @@ def build_default_capability_registry(
                 handler=resolved_service.calendar_events,
                 backgroundable=True,
             ),
+            # ----- Dashboard widget-parity capabilities -----
+            # Each of these mirrors a standalone widget the user sees on the
+            # dashboard / market-insights / stock-analysis pages. Without them
+            # the user would be surprised the agent can't comment on something
+            # they're staring at. Payloads pass through verbatim from the
+            # `build_*_payload` / `get_*` route helpers so the two views never
+            # diverge (DA audit: High-3/4/5, Med-6).
+            TerraFinCapability(
+                name="fear_greed",
+                description=(
+                    "Fetch the CNN Fear & Greed index — same data as the "
+                    "`/dashboard/api/fear-greed` widget. Returns score, rating, "
+                    "previous close, and 1W/1M history."
+                ),
+                handler=resolved_service.fear_greed,
+            ),
+            TerraFinCapability(
+                name="sp500_dcf",
+                description=(
+                    "Fetch the full S&P 500 DCF valuation — same shape as "
+                    "`/market-insights/api/dcf/sp500`. Includes scenarios, "
+                    "sensitivity matrix, methods, rateCurve, dataQuality."
+                ),
+                handler=resolved_service.sp500_dcf,
+                backgroundable=True,
+            ),
+            TerraFinCapability(
+                name="beta_estimate",
+                description=(
+                    "Fetch a 5-year monthly beta estimate with adjusted beta, "
+                    "R², and benchmark — same shape as `/stock/api/beta-estimate`. "
+                    "Use this when you need the statistical quality of the beta; "
+                    "`company_info` only surfaces a bare beta string."
+                ),
+                handler=resolved_service.beta_estimate,
+                focus_extractor=_focus_from_input_keys("ticker"),
+                backgroundable=True,
+            ),
+            TerraFinCapability(
+                name="top_companies",
+                description=(
+                    "Fetch the market-insights top-companies list — same data as "
+                    "`/market-insights/api/top-companies`."
+                ),
+                handler=resolved_service.top_companies,
+            ),
+            TerraFinCapability(
+                name="market_regime",
+                description=(
+                    "Fetch the market regime summary — same data as "
+                    "`/market-insights/api/regime`. Returns a short summary, "
+                    "confidence, and bulleted signals."
+                ),
+                handler=resolved_service.market_regime,
+            ),
+            TerraFinCapability(
+                name="trailing_forward_pe",
+                description=(
+                    "Fetch the trailing vs. forward P/E spread — same data as "
+                    "`/dashboard/api/trailing-forward-pe-spread`."
+                ),
+                handler=resolved_service.trailing_forward_pe,
+                backgroundable=True,
+            ),
+            TerraFinCapability(
+                name="market_breadth",
+                description=(
+                    "Fetch standalone market-breadth metrics — same data as the "
+                    "MarketBreadthCard widget. Was previously bundled inside "
+                    "`market_snapshot`; use this capability when the question is "
+                    "about whole-market state rather than a single ticker."
+                ),
+                handler=resolved_service.market_breadth,
+            ),
+            TerraFinCapability(
+                name="watchlist",
+                description=(
+                    "Fetch the user's current watchlist — same data as the "
+                    "WatchlistSection widget. Standalone now; was previously "
+                    "bundled inside `market_snapshot`."
+                ),
+                handler=resolved_service.watchlist,
+            ),
             TerraFinCapability(
                 name="open_chart",
                 description="Create or update a TerraFin chart session and return a chart artifact.",
@@ -630,6 +713,116 @@ def build_default_capability_registry(
                 focus_extractor=_focus_from_input_keys("ticker"),
                 backgroundable=True,
             ),
+            TerraFinCapability(
+                name="sec_filings",
+                description=(
+                    "List recent 10-K / 10-Q / 8-K filings for a ticker with SEC EDGAR links. "
+                    "Call this ONCE when you need to pivot to a filing not currently in view. The "
+                    "response's `latestByForm` dict is the direct lookup: "
+                    "`latestByForm['10-K'].accession` / `.primaryDocument` give you everything "
+                    "`sec_filing_section` needs. Do NOT scan the flat `filings` array — it's "
+                    "chronological, so 8-Ks cluster at the top and the 10-K/10-Q you want may be in "
+                    "position 5+.\n"
+                    "If a filing is already shown in the user's view context, DON'T call this tool at "
+                    "all — the accession and primaryDocument live in `current_view_context.selection`.\n"
+                    "OUTPUT FORMAT — pick by question type:\n"
+                    "• Quantitative filing analysis ('analyze the 10-Q', 'what do the numbers say'): "
+                    "(1) lead with a '## TL;DR' of 3-5 bullets where each bullet is a punchline number "
+                    "or concrete insight — no filler adjectives; "
+                    "(2) follow with a compact '## Key numbers' table (≤6 rows) comparing current vs "
+                    "prior-year period, showing only metrics that move the thesis; tables MUST include "
+                    "the `| --- |` header-separator row after the header row; "
+                    "(3) narrate with named subsections ('### The X story', '### The Y anomaly') of "
+                    "≤3 sentences each, **bolding** one driver number per sentence maximum; "
+                    "(4) close with '## Not disclosed in this filing' as a short bulleted list.\n"
+                    "• Qualitative/descriptive question ('what is their business', 'how do they make "
+                    "money', 'what are the risks'): 2-4 short paragraphs grounded in the full section "
+                    "body (you MUST have called sec_filing_section first — don't answer off the 4 KB "
+                    "excerpt). Lead with the single most important sentence, then add specifics: "
+                    "products/segments, go-to-market, differentiation, any concrete numbers the "
+                    "filing discloses. Skip the TL;DR bullets and Key-numbers table — they're for "
+                    "quantitative questions, not descriptive ones.\n"
+                    "EDITORIAL DISCIPLINE (strict — reviewers will reject otherwise): "
+                    "(a) no adjectives not grounded in the filing text — avoid 'notable', 'heavy lifting', "
+                    "'nearly wiped', 'pristine'; if you flip management's spin, cite the arithmetic that "
+                    "supports the flip (and report the net number management disclosed); "
+                    "(b) numbers in the TL;DR MUST match the Key-numbers table exactly — no '+12%' in one "
+                    "and '+11.6%' in the other for the same metric; "
+                    "(c) when the fixture provides both QoQ and YoY deltas (or both Q and YTD), report "
+                    "both — a QoQ drop can hide YoY expansion and vice versa; "
+                    "(d) scan every statement for line items moving >50% YoY and surface them — a "
+                    "13x jump in a small bucket or a credits line halving is exactly what skimmers want; "
+                    "(e) if MD&A rounding or direction contradicts what you compute from the statements, "
+                    "report BOTH and prefer the statement-derived number, flagging the discrepancy."
+                ),
+                handler=resolved_service.sec_filings,
+                focus_extractor=_focus_from_input_keys("ticker"),
+            ),
+            TerraFinCapability(
+                name="sec_filing_document",
+                description=(
+                    "Fetch the table of contents (section titles, slugs, and sizes) for a specific "
+                    "10-K, 10-Q, or other SEC filing. Returns structure only — use `sec_filing_section` "
+                    "to pull the actual prose. Requires the accession and primaryDocument fields from "
+                    "`sec_filings` or the current view context.\n"
+                    "Analyst discovery protocol — do NOT assume fixed item numbers across different "
+                    "forms. Instead, scan the TOC for titles containing these keywords:\n"
+                    "• Financial Data: 'Financial Statements', 'Notes', 'Consolidated Statements'.\n"
+                    "• Strategy & Operations: 'Business', 'Management's Discussion', 'MD&A'.\n"
+                    "• Risk & Legal: 'Risk Factors', 'Legal Proceedings', 'Controls'.\n"
+                    "Plan to fetch the specific sections that contain the evidence needed for your "
+                    "answer rather than guessing from summaries."
+                ),
+                handler=resolved_service.sec_filing_document,
+                focus_extractor=_focus_from_input_keys("ticker"),
+                backgroundable=True,
+            ),
+            TerraFinCapability(
+                name="sec_filing_section",
+                description=(
+                    "Fetch the verbatim markdown body of a single filing section by slug. "
+                    "The slug MUST come verbatim from a prior `sec_filing_document` call's TOC — "
+                    "NEVER guess slug names from SEC filing conventions (the parser does not always "
+                    "match convention; trust the actual TOC, not your prior knowledge).\n"
+                    "\n"
+                    "REQUIRED WORKFLOW (follow in order):\n"
+                    "1. Call `sec_filing_document(ticker, accession, primaryDocument, form)` first to "
+                    "obtain the TOC. Every entry has `{slug, text, charCount}`.\n"
+                    "2. Pick the slug whose `text` matches what the user is asking about. If no text "
+                    "matches cleanly (e.g. user asked about 'earnings' but there is no Item labelled "
+                    "'Financial Statements'), use `charCount` as a size signal — the LARGEST section "
+                    "in the relevant Part usually contains the content. 10-K MD&A and Financial "
+                    "Statements often appear as a single very large section when the parser misses the "
+                    "Item 7 / Item 8 split; a 200 KB section body in Part II is almost certainly "
+                    "financial reporting regardless of what its heading says.\n"
+                    "3. Pass that exact slug string to this tool. Do not reformat it, translate it, or "
+                    "guess a canonical form.\n"
+                    "\n"
+                    "IF THIS TOOL RETURNS 'section not found': do NOT tell the user the section "
+                    "doesn't exist. The error response includes the full list of available slugs with "
+                    "their sizes. Pick one from that list (prefer the largest one in the relevant Part "
+                    "if no name matches), and retry this tool immediately. Only after a second real "
+                    "failure should you report inability to find the content.\n"
+                    "\n"
+                    "OUTPUT PROPERTIES:\n"
+                    "- Returns raw, un-truncated markdown including tables. Use the tables to "
+                    "recompute margins, growth rates, and capital allocation signals directly from "
+                    "source data — do not fall back to the `financials` summary tool.\n"
+                    "- If the user is viewing a filing, the `sectionExcerpt` in their view-context is "
+                    "only ~4 KB. Substantive questions (strategy, full financials, segment detail) "
+                    "REQUIRE this tool to fetch the full section body (often 100 KB+).\n"
+                    "\n"
+                    "VERBATIM CITATION RULE:\n"
+                    "When you quote risk factors, MD&A language, forward-looking statements, or "
+                    "legal commitments from the returned body, copy the exact wording inside "
+                    "quotation marks and name the section. Do NOT paraphrase — users need to be "
+                    "able to verify what the filing actually says, not what you think it says. "
+                    "Paraphrasing into friendlier English in safety-sensitive sections is a bug."
+                ),
+                handler=resolved_service.sec_filing_section,
+                focus_extractor=_focus_from_input_keys("ticker"),
+                backgroundable=True,
+            ),
         ]
     )
     return registry

src/TerraFin/agent/service.py

@@ -7,6 +7,7 @@ from TerraFin.analytics.analysis.fundamental.dcf import (
     build_stock_dcf_payload,
     build_stock_reverse_dcf_payload,
 )
+from TerraFin.analytics.analysis.fundamental.dcf.presenters import build_sp500_dcf_payload
 from TerraFin.analytics.analysis.fundamental.screen import run_fundamental_screen
 from TerraFin.analytics.analysis.risk.profile import run_risk_profile
 from TerraFin.analytics.analysis.risk.returns import extract_close_series
@@ -33,9 +34,12 @@ from TerraFin.interface.market_insights.payloads import (
     resolve_macro_type,
 )
 from TerraFin.interface.private_data_service import get_private_data_service
+from TerraFin.interface.stock.data_routes import build_beta_estimate_payload
 from TerraFin.interface.stock.payloads import (
     build_company_info_payload,
     build_earnings_payload,
+    build_filing_document_payload,
+    build_filings_list_payload,
     build_financial_statement_payload,
     resolve_ticker_query,
 )
@@ -424,10 +428,19 @@ class TerraFinAgentService:
         }
 
     def market_snapshot(self, name: str, *, depth: str = "auto", view: str = "daily") -> dict[str, Any]:
+        """Per-ticker price action + indicators only.
+
+        Previously bundled market-wide `market_breadth` and `watchlist`
+        inside this response, which mixed a per-ticker view with
+        whole-market state — the agent would reference breadth numbers
+        alongside a ticker snapshot and risk diverging from the
+        standalone MarketBreadthCard widget if the widget refreshed on
+        its own. Use the `market_breadth` and `watchlist` capabilities
+        for those (matching the standalone widgets).
+        """
         payload = self._market_series(name, depth=depth, view=view)
         series = payload["series"]
         indicator_results, _ = _compute_indicator_results(series, ["rsi", "macd", "bb"])
-        private_service = get_private_data_service()
         return {
             "ticker": payload["name"],
             "price_action": _price_action(series),
@@ -436,8 +449,6 @@ class TerraFinAgentService:
                 "macd_signal": indicator_results.get("macd", {}).get("values", {}).get("signal"),
                 "bb_position": indicator_results.get("bb", {}).get("values", {}).get("position"),
             },
-            "market_breadth": private_service.get_market_breadth(),
-            "watchlist": get_watchlist_service().get_watchlist_snapshot(),
             "processing": payload["processing"],
         }
 
@@ -512,13 +523,139 @@ class TerraFinAgentService:
         )
         return payload
 
+    def sec_filings(self, ticker: str) -> dict[str, Any]:
+        """List recent 10-K / 10-Q / 8-K filings for a ticker with EDGAR links."""
+        payload = build_filings_list_payload(ticker)
+        return {
+            **payload,
+            "processing": _full_processing(
+                requested_depth="full",
+                source_version="sec-filings-list",
+                view=None,
+                frame=None,
+            ),
+        }
+
+    def sec_filing_document(
+        self,
+        ticker: str,
+        accession: str,
+        primaryDocument: str,
+        *,
+        form: str = "10-Q",
+    ) -> dict[str, Any]:
+        """Fetch a filing's structured table of contents without the full markdown body.
+
+        Agents use this to decide which sections are worth reading before pulling
+        their prose via ``sec_filing_section`` — keeps the model's working
+        context small even for 60 KB+ filings.
+        """
+        payload = build_filing_document_payload(ticker, accession, primaryDocument, form=form)
+        return {
+            "ticker": payload["ticker"],
+            "accession": payload["accession"],
+            "primaryDocument": payload["primaryDocument"],
+            "toc": payload["toc"],
+            "charCount": payload["charCount"],
+            "indexUrl": payload["indexUrl"],
+            "documentUrl": payload["documentUrl"],
+            "processing": _full_processing(
+                requested_depth="full",
+                source_version="sec-filing-document",
+                view=None,
+                frame=None,
+            ),
+        }
+
+    def sec_filing_section(
+        self,
+        ticker: str,
+        accession: str,
+        primaryDocument: str,
+        sectionSlug: str,
+        *,
+        form: str = "10-Q",
+    ) -> dict[str, Any]:
+        """Fetch a single section body by slug from a filing.
+
+        Returns only the target section's markdown, keeping the agent's context
+        small for iterative section-by-section analysis.
+        """
+        payload = build_filing_document_payload(ticker, accession, primaryDocument, form=form)
+        toc = payload["toc"]
+        try:
+            entry = next(e for e in toc if e["slug"] == sectionSlug)
+        except StopIteration as exc:
+            # Surface the FULL TOC with sizes so the agent has everything it
+            # needs to retry without another `sec_filing_document` round-trip.
+            # Sort suggestions by charCount descending — when the intended
+            # section wasn't caught by the parser (common for 10-K Item 7/8),
+            # the wanted content usually lives inside the largest neighbor.
+            sorted_entries = sorted(
+                ({"slug": e["slug"], "text": e["text"], "charCount": e["charCount"]} for e in toc),
+                key=lambda e: e["charCount"],
+                reverse=True,
+            )
+            top_hint = ", ".join(
+                f"{e['slug']} ({e['charCount']:,} chars, '{e['text']}')"
+                for e in sorted_entries[:5]
+            )
+            raise LookupError(
+                f"Section '{sectionSlug}' not found. "
+                f"Do NOT report 'section doesn't exist' — retry this tool with one of the available "
+                f"slugs. The 5 largest sections in this filing are: {top_hint}. "
+                f"If the user asked about earnings/financials/MD&A and no slug matches those names "
+                f"directly, pick the LARGEST slug in Part II — 10-K parsers often leave MD&A and "
+                f"Financial Statements inside an oversized neighbor section. "
+                f"All {len(toc)} available slugs: "
+                + ", ".join(e["slug"] for e in toc)
+            ) from exc
+
+        # Upper bound = next raw TOC entry (by ascending lineIndex), so the body
+        # stops at the exact next heading in the markdown.
+        lines = payload["markdown"].split("\n")
+        later = [e for e in toc if e["lineIndex"] > entry["lineIndex"]]
+        end_line = later[0]["lineIndex"] if later else len(lines)
+        body = "\n".join(lines[entry["lineIndex"] + 1 : end_line]).strip()
+
+        return {
+            "ticker": payload["ticker"],
+            "accession": payload["accession"],
+            "sectionSlug": sectionSlug,
+            "sectionTitle": entry["text"],
+            "markdown": body,
+            "charCount": len(body),
+            "documentUrl": payload["documentUrl"],
+            "processing": _full_processing(
+                requested_depth="full",
+                source_version="sec-filing-section",
+                view=None,
+                frame=None,
+            ),
+        }
+
     def portfolio(self, guru: str) -> dict[str, Any]:
         output = get_portfolio_data(guru)
+        # Mirror the route's `topHoldings` pre-computation so the agent and
+        # the UI's treemap/ranking use the same top 8. Without this, the
+        # agent would have to re-sort the full `holdings` list and could
+        # diverge on ties or sort-key interpretation (DA Med-9).
+        df = output.df
+        if not df.empty and {"Stock", "% of Portfolio", "Recent Activity", "Updated"}.issubset(df.columns):
+            top_holdings = (
+                df[["Stock", "% of Portfolio", "Recent Activity", "Updated"]]
+                .sort_values(by="% of Portfolio", ascending=False)
+                .head(8)
+                .to_dict(orient="records")
+            )
+        else:
+            top_holdings = []
         return {
             "guru": guru,
             "info": dict(output.info),
-            "holdings": output.df.to_dict(orient="records"),
-            "count": len(output.df),
+            "holdings": df.to_dict(orient="records"),
+            "topHoldings": top_holdings,
+            "count": len(df),
             "processing": _full_processing(
                 requested_depth="full",
                 source_version="portfolio",
@@ -572,11 +709,64 @@ class TerraFinAgentService:
             ),
         }
 
-    def macro_focus(self, name: str, *, depth: str = "auto", view: str = "daily") -> dict[str, Any]:
+    def macro_focus(
+        self,
+        name: str,
+        *,
+        depth: str = "auto",
+        view: str = "daily",
+        session_id: str | None = None,
+    ) -> dict[str, Any]:
+        """Macro summary + chart-ready series for a named instrument.
+
+        If `session_id` is supplied and the user has stored a named series
+        on that session (e.g. a custom range loaded into the macro chart
+        via the market-insights page), prefer that session-local frame —
+        matches `/market-insights/api/macro-info`'s behavior, where the
+        frontend sends `X-Session-ID` to avoid ignoring the user's chart
+        state. Without session-awareness the agent would answer questions
+        about a different time range than the user was staring at.
+        """
         resolved_name = canonical_macro_name(name)
         indicator_type = resolve_macro_type(resolved_name)
         if indicator_type is None:
             raise LookupError(f"Unknown macro instrument: '{resolved_name}'")
+
+        session_frame = None
+        if session_id:
+            try:
+                from TerraFin.interface.chart.state import get_named_series
+
+                session_frame = get_named_series(session_id).get(resolved_name)
+            except Exception:
+                session_frame = None
+
+        if session_frame is not None:
+            # User has a custom macro series loaded in their session. Use it
+            # verbatim so agent's view matches what they're looking at.
+            session_frame.name = resolved_name
+            series_payload = _primary_series(session_frame, view=_normalize_view(view))
+            info = build_macro_info_payload(
+                resolved_name,
+                get_macro_description(resolved_name),
+                session_frame,
+                indicator_type=indicator_type,
+            )
+            processing = _full_processing(
+                requested_depth=_normalize_depth(depth),
+                source_version="macro-session",
+                view=_normalize_view(view),
+                frame=session_frame,
+            )
+            return {
+                "name": resolved_name,
+                "info": info,
+                "seriesType": series_payload.get("seriesType", "line"),
+                "count": len(series_payload.get("data", [])),
+                "data": _series_points(series_payload),
+                "processing": processing,
+            }
+
         payload = self._market_series(resolved_name, depth=depth, view=view)
         frame = payload["frame"]
         info = build_macro_info_payload(
@@ -709,32 +899,27 @@ class TerraFinAgentService:
         if intrinsic_value and current_price and current_price > 0:
             margin_of_safety = round((intrinsic_value - current_price) / current_price * 100, 2)
 
+        # Pass the full route payloads through verbatim so the agent sees the
+        # exact same `DCFValuationResponse` / `ReverseDCFResponse` structure
+        # that renders in the frontend's DcfValuationPanel — scenarios,
+        # sensitivity matrix, methods, rateCurve, dataQuality, all of it.
+        # Previously this method cherry-picked 4 fields from each, which
+        # broke user↔agent view parity (audit: DA High-1, High-2).
         return {
             "ticker": normalized,
-            "dcf": {
-                "status": dcf.get("status"),
-                "intrinsic_value": dcf.get("currentIntrinsicValue"),
-                "upside_pct": dcf.get("upsidePct"),
-                "assumptions": dcf.get("assumptions"),
-                "warnings": dcf.get("warnings", []),
-            },
-            "reverse_dcf": {
-                "status": reverse_dcf.get("status"),
-                "implied_growth_pct": reverse_dcf.get("impliedGrowthPct"),
-                "model_price": reverse_dcf.get("modelPrice"),
-                "warnings": reverse_dcf.get("warnings", []),
-            },
+            "dcf": dcf,
+            "reverseDcf": reverse_dcf,
             "relative": {
-                "trailing_pe": trailing_pe,
-                "forward_pe": forward_pe,
-                "price_to_book": (
+                "trailingPE": trailing_pe,
+                "forwardPE": forward_pe,
+                "priceToBook": (
                     round(current_price / bvps, 2)
                     if current_price and bvps and bvps > 0 else None
                 ),
             },
-            "graham_number": graham_number,
-            "margin_of_safety_pct": margin_of_safety,
-            "current_price": current_price,
+            "grahamNumber": graham_number,
+            "marginOfSafetyPct": margin_of_safety,
+            "currentPrice": current_price,
             "processing": _full_processing(
                 requested_depth="full",
                 source_version="valuation",
@@ -742,3 +927,161 @@ class TerraFinAgentService:
                 frame=None,
             ),
         }
+
+    # -----------------------------------------------------------------
+    # Capabilities that expose standalone widgets the dashboard and
+    # market-insights pages render. Before these existed, the agent
+    # could not answer questions about data the user was clearly
+    # looking at (Fear & Greed, S&P 500 DCF, beta R², top companies,
+    # regime summary, trailing-forward P/E). Every method here returns
+    # the route's payload verbatim (camelCase intact) so the agent
+    # sees the same fields the frontend renders.
+    # -----------------------------------------------------------------
+
+    def fear_greed(self) -> dict[str, Any]:
+        """CNN Fear & Greed index — matches `/dashboard/api/fear-greed`."""
+        payload = dict(get_private_data_service().get_fear_greed_current())
+        payload["processing"] = _full_processing(
+            requested_depth="full",
+            source_version="fear-greed",
+            view=None,
+            frame=None,
+        )
+        return payload
+
+    def sp500_dcf(self) -> dict[str, Any]:
+        """Full S&P 500 DCF — matches `/market-insights/api/dcf/sp500`.
+
+        Returns the same DCFValuationResponse shape (scenarios, sensitivity,
+        methods, rateCurve, dataQuality) the SP500 DCF panel renders.
+        """
+        payload = dict(build_sp500_dcf_payload())
+        payload["processing"] = _full_processing(
+            requested_depth="full",
+            source_version="sp500-dcf",
+            view=None,
+            frame=None,
+        )
+        return payload
+
+    def beta_estimate(self, ticker: str) -> dict[str, Any]:
+        """5-year monthly beta estimate — matches `/stock/api/beta-estimate`.
+
+        Returns beta, adjusted beta, R², observations, benchmark, warnings.
+        The `company_info` tool only surfaces a string `beta` field; use this
+        capability when you need the statistical quality of the estimate.
+        """
+        payload = dict(build_beta_estimate_payload(ticker))
+        payload["processing"] = _full_processing(
+            requested_depth="full",
+            source_version="beta-estimate",
+            view=None,
+            frame=None,
+        )
+        return payload
+
+    def top_companies(self) -> dict[str, Any]:
+        """Market-insights top-companies list — matches `/market-insights/api/top-companies`."""
+        try:
+            companies = get_private_data_service().get_top_companies()
+        except Exception:
+            companies = []
+        return {
+            "companies": companies,
+            "count": len(companies),
+            "processing": _full_processing(
+                requested_depth="full",
+                source_version="top-companies",
+                view=None,
+                frame=None,
+            ),
+        }
+
+    def market_regime(self) -> dict[str, Any]:
+        """Market regime summary — matches `/market-insights/api/regime`.
+
+        The route currently returns a static placeholder; the agent sees the
+        same placeholder so the two views never diverge. If the route is
+        upgraded to a real regime model later, this capability will
+        automatically reflect the change without code edits here.
+        """
+        # Mirror the route's placeholder exactly — user↔agent parity trumps
+        # "placeholder data should be obvious to callers". If the route is
+        # updated to a real model, update both sides together.
+        return {
+            "summary": "Mixed regime with selective risk-taking and elevated event sensitivity.",
+            "confidence": "low",
+            "signals": [
+                "Breadth is improving in pockets but still uneven.",
+                "Macro event concentration this week can raise short-term volatility.",
+                "Leadership remains concentrated in a handful of large-cap names.",
+            ],
+            "processing": _full_processing(
+                requested_depth="full",
+                source_version="market-regime-placeholder",
+                view=None,
+                frame=None,
+            ),
+        }
+
+    def trailing_forward_pe(self) -> dict[str, Any]:
+        """Trailing minus forward P/E spread — matches `/dashboard/api/trailing-forward-pe-spread`."""
+        private_service = get_private_data_service()
+        payload = private_service.get_trailing_forward_pe() or {}
+        summary = payload.get("summary", {}) if isinstance(payload, dict) else {}
+        coverage = payload.get("coverage", {}) if isinstance(payload, dict) else {}
+        history = payload.get("history", []) if isinstance(payload, dict) else []
+        return {
+            "date": str(payload.get("date", "")) if isinstance(payload, dict) else "",
+            "description": (
+                "Trailing P/E minus forward P/E, used as a rough proxy for how much "
+                "future earnings expectations diverge from trailing earnings."
+            ),
+            "latestValue": summary.get("trailing_forward_pe_spread"),
+            "usableCount": coverage.get("usable"),
+            "requestedCount": coverage.get("requested"),
+            "history": list(history),
+            "processing": _full_processing(
+                requested_depth="full",
+                source_version="trailing-forward-pe",
+                view=None,
+                frame=None,
+            ),
+        }
+
+    def market_breadth(self) -> dict[str, Any]:
+        """Market breadth metrics — matches `/dashboard/api/market-breadth`.
+
+        Was previously bundled inside `market_snapshot`, which mixed a
+        per-ticker view with whole-market state. Now a standalone capability
+        so agent and the MarketBreadthCard widget query the same data.
+        """
+        metrics = get_private_data_service().get_market_breadth()
+        return {
+            "metrics": list(metrics),
+            "processing": _full_processing(
+                requested_depth="full",
+                source_version="market-breadth",
+                view=None,
+                frame=None,
+            ),
+        }
+
+    def watchlist(self) -> dict[str, Any]:
+        """User's watchlist — matches the WatchlistSection dashboard widget.
+
+        Was previously bundled inside `market_snapshot`. Standalone here so
+        agent and the widget query the same list without ticker-scoped
+        confusion.
+        """
+        snapshot = get_watchlist_service().get_watchlist_snapshot() or []
+        return {
+            "items": list(snapshot),
+            "count": len(snapshot),
+            "processing": _full_processing(
+                requested_depth="full",
+                source_version="watchlist",
+                view=None,
+                frame=None,
+            ),
+        }

src/TerraFin/agent/tool_contracts.py

@@ -215,6 +215,98 @@ HOSTED_TOOL_CONTRACTS: dict[str, dict[str, Any]] = {
         ),
         "response_model": "ValuationResponse",
     },
+    "sec_filings": {
+        "input_schema": _object_schema(
+            properties={"ticker": {"type": "string", "minLength": 1}},
+            required=["ticker"],
+        ),
+        "response_model": "SecFilingsListResponse",
+    },
+    "sec_filing_document": {
+        "input_schema": _object_schema(
+            properties={
+                "ticker": {"type": "string", "minLength": 1},
+                "accession": {"type": "string", "minLength": 1},
+                "primaryDocument": {"type": "string", "minLength": 1},
+                "form": {"type": "string", "minLength": 1, "default": "10-Q"},
+            },
+            required=["ticker", "accession", "primaryDocument"],
+        ),
+        "response_model": "SecFilingDocumentResponse",
+    },
+    "sec_filing_section": {
+        "input_schema": _object_schema(
+            properties={
+                "ticker": {"type": "string", "minLength": 1},
+                "accession": {"type": "string", "minLength": 1},
+                "primaryDocument": {"type": "string", "minLength": 1},
+                "sectionSlug": {"type": "string", "minLength": 1},
+                "form": {"type": "string", "minLength": 1, "default": "10-Q"},
+            },
+            required=["ticker", "accession", "primaryDocument", "sectionSlug"],
+        ),
+        "response_model": "SecFilingSectionResponse",
+    },
+    "fear_greed": {
+        "input_schema": _object_schema(properties={}, required=[]),
+        "response_model": "FearGreedResponse",
+    },
+    "sp500_dcf": {
+        "input_schema": _object_schema(properties={}, required=[]),
+        "response_model": "DCFValuationResponse",
+    },
+    "beta_estimate": {
+        "input_schema": _object_schema(
+            properties={"ticker": {"type": "string", "minLength": 1}},
+            required=["ticker"],
+        ),
+        "response_model": "BetaEstimateResponse",
+    },
+    "top_companies": {
+        "input_schema": _object_schema(properties={}, required=[]),
+        "response_model": "TopCompaniesResponse",
+    },
+    "market_regime": {
+        "input_schema": _object_schema(properties={}, required=[]),
+        "response_model": "MarketRegimeResponse",
+    },
+    "trailing_forward_pe": {
+        "input_schema": _object_schema(properties={}, required=[]),
+        "response_model": "TrailingForwardPeSpreadResponse",
+    },
+    "market_breadth": {
+        "input_schema": _object_schema(properties={}, required=[]),
+        "response_model": "MarketBreadthResponse",
+    },
+    "watchlist": {
+        "input_schema": _object_schema(properties={}, required=[]),
+        "response_model": "WatchlistResponse",
+    },
+    # Persona-consult tools. Each takes a single `question` arg (the
+    # orchestrator-scoped prompt sent to the persona subagent) and returns
+    # a `GuruResearchMemo`-shaped payload. See
+    # `docs/agent/architecture.md#orchestrator--persona-subagents`.
+    "consult_warren_buffett": {
+        "input_schema": _object_schema(
+            properties={"question": {"type": "string", "minLength": 1}},
+            required=["question"],
+        ),
+        "response_model": "GuruResearchMemo",
+    },
+    "consult_howard_marks": {
+        "input_schema": _object_schema(
+            properties={"question": {"type": "string", "minLength": 1}},
+            required=["question"],
+        ),
+        "response_model": "GuruResearchMemo",
+    },
+    "consult_stanley_druckenmiller": {
+        "input_schema": _object_schema(
+            properties={"question": {"type": "string", "minLength": 1}},
+            required=["question"],
+        ),
+        "response_model": "GuruResearchMemo",
+    },
 }
 
 

src/TerraFin/agent/tools.py

@@ -2,12 +2,12 @@ from __future__ import annotations
 
 from collections.abc import Mapping
 from dataclasses import dataclass, field
-from typing import Any, Literal
+from typing import TYPE_CHECKING, Any, Literal
 
 from TerraFin.interface.market_insights.payloads import canonical_macro_name, resolve_macro_type
 from TerraFin.interface.stock.payloads import resolve_ticker_query
 
-from .definitions import TerraFinAgentDefinition
+from .definitions import TerraFinAgentDefinition, is_internal_agent_definition
 from .hosted_runtime import (
     TerraFinAgentApprovalRequiredError,
     TerraFinHostedAgentRuntime,
@@ -16,6 +16,10 @@ from .runtime import TerraFinCapability, TerraFinTaskRecord
 from .tool_contracts import HOSTED_TOOL_CONTRACT_VERSION, get_hosted_tool_contract
 
 
+if TYPE_CHECKING:
+    from .loop import TerraFinHostedAgentLoop
+
+
 ToolExecutionMode = Literal["invoke", "task"]
 
 
@@ -63,9 +67,26 @@ class _ToolErrorDisposition:
     model_hint: str | None = None
 
 
+_PERSONA_CONSULT_TOOLS = {
+    "consult_warren_buffett": "warren-buffett",
+    "consult_howard_marks": "howard-marks",
+    "consult_stanley_druckenmiller": "stanley-druckenmiller",
+}
+
+
 class TerraFinHostedToolAdapter:
     def __init__(self, runtime: TerraFinHostedAgentRuntime) -> None:
         self.runtime = runtime
+        # The loop reference is injected after loop construction because the
+        # adapter and loop are mutually dependent: the loop owns the adapter;
+        # the adapter needs the loop to dispatch `consult_<persona>` tools
+        # (persona subagents are full model loops, which the top-level loop
+        # runs). Plain session-scoped capability calls don't need the loop —
+        # they go through `runtime.invoke`.
+        self._loop: "TerraFinHostedAgentLoop" | None = None
+
+    def attach_loop(self, loop: "TerraFinHostedAgentLoop") -> None:
+        self._loop = loop
 
     def list_tools_for_agent(self, agent_name: str) -> tuple[TerraFinToolDefinition, ...]:
         definition = self.runtime.get_agent_definition(agent_name)
@@ -107,6 +128,20 @@ class TerraFinHostedToolAdapter:
                     session_id,
                     view_context_id=_optional_string(resolved_arguments.get("viewContextId")),
                 )
+            elif tool.name in _PERSONA_CONSULT_TOOLS:
+                if self._loop is None:
+                    raise RuntimeError(
+                        "Tool adapter has no loop reference; consult_<persona> "
+                        "tools require `attach_loop(...)` to have been called "
+                        "after loop construction."
+                    )
+                guru_name = _PERSONA_CONSULT_TOOLS[tool.name]
+                question = _optional_string(resolved_arguments.get("question")) or ""
+                if not question:
+                    raise ValueError(
+                        f"{tool.name} requires a non-empty `question` argument."
+                    )
+                payload = self._loop.consult_guru(session_id, guru_name, question)
             elif tool.execution_mode == "task":
                 task = self.runtime.start_task(session_id, tool.capability_name, **resolved_arguments)
                 payload = {
@@ -197,8 +232,93 @@ class TerraFinHostedToolAdapter:
             if definition.allow_background_tasks and capability.backgroundable:
                 tools.append(self._build_tool_definition(capability, execution_mode="task"))
         tools.append(self._build_current_view_context_tool())
+        # Persona-consult tools — only the user-facing orchestrator gets
+        # them. Persona subagents themselves (hiddenInternal guru roles)
+        # must not recurse through consult_* onto each other, so they are
+        # filtered out by `is_internal_agent_definition`.
+        if not is_internal_agent_definition(definition):
+            tools.append(self._build_consult_warren_buffett_tool())
+            tools.append(self._build_consult_howard_marks_tool())
+            tools.append(self._build_consult_stanley_druckenmiller_tool())
         return tuple(tools)
 
+    def _build_consult_warren_buffett_tool(self) -> TerraFinToolDefinition:
+        contract = get_hosted_tool_contract("consult_warren_buffett")
+        return TerraFinToolDefinition(
+            name="consult_warren_buffett",
+            capability_name="consult_warren_buffett",
+            description=(
+                "Consult the hidden Warren Buffett subagent for a business-quality / "
+                "long-term-ownership lens. Best when the user asks about moats, "
+                "competitive advantage, earnings power, capital allocation, intrinsic "
+                "value under conservative assumptions, or whether a business is worth "
+                "owning for the long run. Pass the specific question as `question`. "
+                "Returns a structured memo with stance, confidence (0-100, "
+                "self-reported by the persona agent based on evidence quality), "
+                "thesis, key_evidence, risks, open_questions, citations. "
+                "Call this alongside `consult_howard_marks` or "
+                "`consult_stanley_druckenmiller` when the user explicitly asks for "
+                "multiple investor perspectives."
+            ),
+            input_schema=contract["input_schema"],
+            execution_mode="invoke",
+            side_effecting=False,
+            metadata={
+                "backgroundable": False,
+                "capabilityName": "consult_warren_buffett",
+                "contractVersion": HOSTED_TOOL_CONTRACT_VERSION,
+                "responseModel": contract["response_model"],
+            },
+        )
+
+    def _build_consult_howard_marks_tool(self) -> TerraFinToolDefinition:
+        contract = get_hosted_tool_contract("consult_howard_marks")
+        return TerraFinToolDefinition(
+            name="consult_howard_marks",
+            capability_name="consult_howard_marks",
+            description=(
+                "Consult the hidden Howard Marks subagent for a cycle / "
+                "risk-premium / second-level-thinking lens. Best when the user asks "
+                "about downside risk, what's priced in, cycle position, bear cases, "
+                "valuation sensitivity, or whether the market is complacent. "
+                "Returns a structured memo (same schema as `consult_warren_buffett`). "
+                "Complementary to Buffett for quality vs. price tension."
+            ),
+            input_schema=contract["input_schema"],
+            execution_mode="invoke",
+            side_effecting=False,
+            metadata={
+                "backgroundable": False,
+                "capabilityName": "consult_howard_marks",
+                "contractVersion": HOSTED_TOOL_CONTRACT_VERSION,
+                "responseModel": contract["response_model"],
+            },
+        )
+
+    def _build_consult_stanley_druckenmiller_tool(self) -> TerraFinToolDefinition:
+        contract = get_hosted_tool_contract("consult_stanley_druckenmiller")
+        return TerraFinToolDefinition(
+            name="consult_stanley_druckenmiller",
+            capability_name="consult_stanley_druckenmiller",
+            description=(
+                "Consult the hidden Stanley Druckenmiller subagent for a macro / "
+                "liquidity / regime / momentum lens. Best when the user asks about "
+                "Fed policy impact, rates higher-for-longer, risk-on/off regime, "
+                "liquidity conditions, currency or commodity backdrop, or when an "
+                "asset's fate depends more on the macro tape than on its own "
+                "fundamentals. Returns a structured memo (same schema)."
+            ),
+            input_schema=contract["input_schema"],
+            execution_mode="invoke",
+            side_effecting=False,
+            metadata={
+                "backgroundable": False,
+                "capabilityName": "consult_stanley_druckenmiller",
+                "contractVersion": HOSTED_TOOL_CONTRACT_VERSION,
+                "responseModel": contract["response_model"],
+            },
+        )
+
     def _preflight_tool_misuse(
         self,
         tool: TerraFinToolDefinition,
@@ -278,7 +398,42 @@ class TerraFinHostedToolAdapter:
             capability_name="current_view_context",
             description=(
                 "Read the user's current TerraFin page/view context when the request depends on "
-                "what they are looking at right now. Do not use unless the request is view-dependent."
+                "what they are looking at right now (pronouns like 'this', 'their', 'it', or implicit "
+                "subjects).\n"
+                "If the user is viewing a SEC filing, `selection` will carry "
+                "`{ticker, form, accession, primaryDocument, sectionSlug, sectionTitle, "
+                "sectionExcerpt, documentUrl, indexUrl}`. Key rules:\n"
+                "1. USE `selection.accession` AND `selection.primaryDocument` DIRECTLY (don't "
+                "call `sec_filings` first) — the filing the user is viewing is already identified. "
+                "But the `selection.sectionSlug` may be stale relative to the filing's current TOC "
+                "(the browser cached it earlier). So the correct workflow when user asks about the "
+                "in-view filing:\n"
+                "   a. Call `sec_filing_document(ticker=selection.ticker, accession=selection.accession, "
+                "primaryDocument=selection.primaryDocument, form=selection.form)` FIRST to get the "
+                "current TOC.\n"
+                "   b. Pick a `sectionSlug` from that TOC that matches the user's question. For "
+                "earnings / revenue / MD&A / financial statements in a 10-K, prefer the LARGEST slug "
+                "in Part II — 10-K parsers sometimes leave MD&A and Financial Statements inside an "
+                "oversized neighbor slug (e.g. `item-6-reserved` with 200 KB of body).\n"
+                "   c. Call `sec_filing_section(...)` with the TOC-sourced slug.\n"
+                "If `selection.sectionSlug` exists AND the user's question is scoped to that exact "
+                "section, you MAY skip step (a) and pass `selection.sectionSlug` directly — but on "
+                "a 'section not found' error, always fall back to the TOC workflow above.\n"
+                "2. The excerpt is only ~4 KB, usually a small slice of a much larger section "
+                "(Item 1 Business in a 10-K is typically 100-200 KB). For any substantive question — "
+                "business model, operations, strategy, risk factors, segment descriptions, etc. — "
+                "ALWAYS call `sec_filing_section` to get the full body before answering. Writing a "
+                "two-sentence summary off the excerpt alone is a UX failure.\n"
+                "3. `documentUrl` and `indexUrl` are citation links, NOT places to send the user — "
+                "they are ALREADY reading this filing in TerraFin's reader. Do NOT write 'you can "
+                "view the filing here' or 'open on EDGAR for details' as a tail to your answer. "
+                "Only mention an external link if the user explicitly asks for the source URL.\n"
+                "4. Cross-filing pivots: if the user asks about content that lives in a *different* "
+                "filing than the one in view (e.g. they're on a 10-Q but ask 'what is their business' — "
+                "Item 1 Business is a 10-K section, not a 10-Q section), call `sec_filings(ticker)` "
+                "ONCE to get the response, then read `filings_response.latestByForm['10-K']` to get "
+                "the target filing's accession + primaryDocument directly. Do NOT scan the "
+                "chronological `filings` array — 8-Ks cluster at the top and hide the 10-K/10-Q."
             ),
             input_schema=contract["input_schema"],
             execution_mode="invoke",
@@ -357,6 +512,39 @@ class TerraFinHostedToolAdapter:
                 expose_to_user=True,
             )
 
+        # Missing section slug on `sec_filing_section` — the service
+        # layer raises LookupError with a full slug list + explicit
+        # retry instructions, but without this classifier branch the
+        # error bubbles up with no `retryable=True` / `modelHint`
+        # signal. The model then paraphrases the error and gives up
+        # instead of reissuing the call with a valid slug. Surface it
+        # as a retryable tool-input error so the loop retries and the
+        # model sees a clear hint. The full slug list from the raised
+        # message becomes the `modelHint`.
+        if tool.name == "sec_filing_section" and "not found" in lowered and "slug" in lowered:
+            requested_slug = _optional_string(arguments.get("sectionSlug"))
+            return _ToolErrorDisposition(
+                code="sec_filing_section_slug_not_found",
+                message=(
+                    f"The requested section slug "
+                    f"{repr(requested_slug) if requested_slug else 'provided'} "
+                    "is not in this filing's TOC. Retry with one of the slugs listed "
+                    "in the error body."
+                ),
+                retryable=True,
+                expose_to_user=False,
+                model_hint=(
+                    "DO NOT tell the user the section doesn't exist. The error body "
+                    "contains the full TOC slug list with sizes. Pick ONE slug from "
+                    "that list verbatim and call `sec_filing_section` again — "
+                    "prefer the largest slug in Part II of a 10-K when the user "
+                    "asked about earnings / revenue / MD&A / financial statements, "
+                    "because 10-K parsers sometimes leave those sections buried "
+                    "inside an oversized neighbor slug. Full error message for "
+                    "reference:\n" + message
+                ),
+            )
+
         name_value = _optional_string(arguments.get("name"))
         ticker_value = _optional_string(arguments.get("ticker"))
         requested_value = name_value or ticker_value or ""

src/TerraFin/configuration.py

@@ -20,6 +20,7 @@ DEFAULT_CACHE_INTERVALS = {
     "yfinance": 43200,
     "portfolio": 259200,
     "ticker_info": 43200,
+    "sec_filings": 2592000,
 }
 
 DEFAULT_WATCHLIST_DATABASE = "terrafin_status_db"

src/TerraFin/interface/frontend/src/stock/StockPage.tsx

@@ -12,6 +12,7 @@ import StockHeader from './components/StockHeader';
 import StockChart from './components/StockChart';
 import CompanyProfile from './components/CompanyProfile';
 import EarningsTable from './components/EarningsTable';
+import SecFilings from './components/SecFilings';
 import { useCompanyInfo, useEarnings } from './useStockData';
 
 const TICKER_GROUPS = [
@@ -119,6 +120,14 @@ const StockPage: React.FC = () => {
     setIsReverseDcfOpen(false);
   }, [ticker]);
 
+  // SEC filings section hides itself for non-US tickers (KOSPI, TSE, etc.)
+  // where the ticker has no SEC CIK. Reset on ticker change so switching
+  // from 005930.KS to AAPL re-shows the section.
+  const [hideSecFilings, setHideSecFilings] = React.useState(false);
+  React.useEffect(() => {
+    setHideSecFilings(false);
+  }, [ticker]);
+
   React.useEffect(() => {
     const route = window.location.pathname;
     if (!ticker) {
@@ -378,6 +387,19 @@ const StockPage: React.FC = () => {
 
         {!isMobile ? dcfResultCard : null}
 
+        {!hideSecFilings ? (
+          <section>
+            <InsightCard
+              title="SEC Filings"
+              subtitle={`10-K / 10-Q filings for ${ticker}. Open a filing to browse section-by-section.`}
+              fillContent
+              allowOverflow
+            >
+              <SecFilings ticker={ticker} onUnavailable={() => setHideSecFilings(true)} />
+            </InsightCard>
+          </section>
+        ) : null}
+
         <section style={reverseDcfToggleCardStyle}>
           <button
             type="button"

src/TerraFin/interface/frontend/src/stock/components/FilingMarkdown.test.helper.mjs

@@ -0,0 +1,115 @@
+// Quick sanity harness for parseBlocks without React. Run with:
+//   node src/TerraFin/interface/frontend/src/stock/components/FilingMarkdown.test.helper.mjs
+// Mirrors the block-parsing logic of FilingMarkdown.tsx.
+
+const HEADING_RE = /^(#{2,4})\s+(.*?)\s*$/;
+const TABLE_SEPARATOR_RE = /^\|?\s*:?-{2,}:?\s*(\|\s*:?-{2,}:?\s*)*\|?\s*$/;
+const IMAGE_RE = /^!\[([^\]]*)\]\(([^)]+)\)$/;
+
+function splitTableCells(line) {
+  const parts = line.split('|').map((s) => s.trim());
+  if (parts.length > 0 && parts[0] === '') parts.shift();
+  if (parts.length > 0 && parts[parts.length - 1] === '') parts.pop();
+  return parts;
+}
+
+function parseBlocks(md) {
+  const lines = md.split('\n');
+  const blocks = [];
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (!line.trim()) { i++; continue; }
+    const h = line.match(HEADING_RE);
+    if (h) { blocks.push({ kind: 'heading', level: h[1].length, text: h[2] }); i++; continue; }
+    const img = line.match(IMAGE_RE);
+    if (img) { blocks.push({ kind: 'image', alt: img[1], src: img[2] }); i++; continue; }
+    if (line.startsWith('> ')) {
+      const quote = [];
+      while (i < lines.length && lines[i].startsWith('> ')) { quote.push(lines[i].slice(2)); i++; }
+      blocks.push({ kind: 'blockquote', text: quote.join('\n') }); continue;
+    }
+    if (line.includes('|') && i + 1 < lines.length && TABLE_SEPARATOR_RE.test(lines[i + 1])) {
+      const header = splitTableCells(line);
+      i += 2;
+      const rows = [];
+      while (i < lines.length && lines[i].trim() && lines[i].includes('|')) {
+        rows.push(splitTableCells(lines[i])); i++;
+      }
+      blocks.push({ kind: 'table', header, rows }); continue;
+    }
+    const paragraph = [line]; i++;
+    while (
+      i < lines.length && lines[i].trim()
+      && !lines[i].match(HEADING_RE)
+      && !lines[i].startsWith('> ')
+      && !lines[i].match(IMAGE_RE)
+      && !(lines[i].includes('|') && i + 1 < lines.length && TABLE_SEPARATOR_RE.test(lines[i + 1]))
+    ) { paragraph.push(lines[i]); i++; }
+    blocks.push({ kind: 'paragraph', text: paragraph.join(' ') });
+  }
+  return blocks;
+}
+
+function assertEq(actual, expected, msg) {
+  const a = JSON.stringify(actual);
+  const e = JSON.stringify(expected);
+  if (a !== e) { console.error(`FAIL: ${msg}\n  expected: ${e}\n  actual:   ${a}`); process.exit(1); }
+  console.log(`ok: ${msg}`);
+}
+
+// --- Real edge cases flagged by the devil's advocate ---
+
+// 1. Blockquote table-error fallback (from parser.py:122).
+const withFallback = `## PART I
+
+### Item 1
+
+Intro text.
+
+> [Table parse error: ragged rows; raw markdown follows]
+> | Col A | Col B |
+> | 1 | 2 |
+
+After the table.`;
+const blocks1 = parseBlocks(withFallback);
+assertEq(
+  blocks1.map((b) => b.kind),
+  ['heading', 'heading', 'paragraph', 'blockquote', 'paragraph'],
+  'blockquote fallback recognized, paragraphs around it intact',
+);
+
+// 2. nan cells in a table (from astype(str) on NaN).
+const withNan = `| Metric | Q1 | Q2 |
+| --- | --- | --- |
+| Revenue | 100 | 120 |
+| Other | nan | nan |`;
+const blocks2 = parseBlocks(withNan);
+assertEq(blocks2.length, 1, 'nan-bearing table is still one table block');
+assertEq(blocks2[0].kind, 'table', 'nan-bearing block kind is table');
+assertEq(blocks2[0].rows[1], ['Other', 'nan', 'nan'], 'nan survives the parse (cleaned at render)');
+
+// 3. Inline-image placeholder (from our data-URI replacement).
+const withPlaceholder = `![Company logo](<inline-image:image/png>)`;
+const blocks3 = parseBlocks(withPlaceholder);
+assertEq(blocks3.length, 1, 'inline-image is one block');
+assertEq(blocks3[0], { kind: 'image', alt: 'Company logo', src: '<inline-image:image/png>' }, 'placeholder src preserved');
+
+// 4. Paragraph with mid-text dollar signs and percent (won't be mistaken for a table).
+const withDollars = `Revenue grew 12.3% to $48.5B, driven by services.`;
+const blocks4 = parseBlocks(withDollars);
+assertEq(blocks4.map((b) => b.kind), ['paragraph'], 'currency/percent paragraph stays paragraph');
+
+// 5. Line with pipes but no separator below — NOT a table.
+const withPipesNoSep = `Contact us at sales | support | marketing for details.
+
+More text.`;
+const blocks5 = parseBlocks(withPipesNoSep);
+assertEq(blocks5.map((b) => b.kind), ['paragraph', 'paragraph'], 'pipes without separator is paragraph, not table');
+
+// 6. Heading levels.
+const headings = `## Two\n### Three\n#### Four`;
+const blocks6 = parseBlocks(headings);
+assertEq(blocks6.map((b) => b.level), [2, 3, 4], 'h2/h3/h4 levels preserved');
+
+console.log('\nAll FilingMarkdown edge-case checks passed.');

src/TerraFin/interface/frontend/src/stock/components/FilingMarkdown.tsx

@@ -0,0 +1,196 @@
+import React from 'react';
+
+// Minimal markdown renderer tailored to TerraFin's `parse_sec_filing` output.
+// Handles: ##/### headings, blank-line-separated paragraphs, GFM pipe tables,
+// blockquote table-error fallbacks (`> [Table parse error: ...]\nRAW_MD`), and
+// optional `![alt](src)` images. Anything else falls through as a plain line.
+//
+// Deliberately NOT a general markdown renderer — adding that would mean
+// pulling in react-markdown + remark-gfm (~60KB gz) for output we fully
+// control the producer of.
+
+interface Props {
+  markdown: string;
+  lineIndexStart?: number; // so headings can carry stable ids for scroll-target
+  lineIndexEnd?: number;
+}
+
+const H2_STYLE: React.CSSProperties = { fontSize: 16, fontWeight: 800, color: '#0f172a', margin: '18px 0 8px', lineHeight: 1.3 };
+const H3_STYLE: React.CSSProperties = { fontSize: 14, fontWeight: 700, color: '#1e293b', margin: '14px 0 6px', lineHeight: 1.35 };
+const H4_STYLE: React.CSSProperties = { fontSize: 13, fontWeight: 700, color: '#334155', margin: '12px 0 4px' };
+const P_STYLE: React.CSSProperties = { fontSize: 13, color: '#334155', lineHeight: 1.6, margin: '0 0 8px' };
+const BLOCKQUOTE_STYLE: React.CSSProperties = {
+  borderLeft: '3px solid #fb923c',
+  background: '#fff7ed',
+  color: '#9a3412',
+  padding: '8px 12px',
+  fontSize: 12,
+  margin: '8px 0',
+  borderRadius: 4,
+};
+const TABLE_STYLE: React.CSSProperties = { borderCollapse: 'collapse', fontSize: 12, margin: '8px 0', width: '100%' };
+const TH_STYLE: React.CSSProperties = { border: '1px solid #e2e8f0', background: '#f1f5f9', padding: '6px 8px', textAlign: 'left', fontWeight: 700 };
+const TD_STYLE: React.CSSProperties = { border: '1px solid #e2e8f0', padding: '6px 8px', verticalAlign: 'top' };
+const IMG_STYLE: React.CSSProperties = { maxWidth: '100%', border: '1px solid #e2e8f0', borderRadius: 4, margin: '8px 0' };
+const PLACEHOLDER_STYLE: React.CSSProperties = { ...P_STYLE, color: '#94a3b8', fontStyle: 'italic' };
+
+const HEADING_RE = /^(#{2,4})\s+(.*?)\s*$/;
+const TABLE_SEPARATOR_RE = /^\|?\s*:?-{2,}:?\s*(\|\s*:?-{2,}:?\s*)*\|?\s*$/;
+const IMAGE_RE = /^!\[([^\]]*)\]\(([^)]+)\)$/;
+
+function splitTableCells(line: string): string[] {
+  // Simple pipe-split. sec_parser table cells occasionally contain escaped pipes
+  // or currency strings; we accept the naive split and clean leading/trailing
+  // empty cells that come from wrapper pipes like "| a | b |".
+  const parts = line.split('|').map((s) => s.trim());
+  if (parts.length > 0 && parts[0] === '') parts.shift();
+  if (parts.length > 0 && parts[parts.length - 1] === '') parts.pop();
+  return parts;
+}
+
+function cleanCell(text: string): string {
+  // `_modify_to_valid_md_table` uses `astype(str)` which emits literal "nan"
+  // for missing values. Scrub these to empty so tables don't look broken.
+  if (text === 'nan' || text === 'NaN' || text === 'None') return '';
+  return text;
+}
+
+interface Block {
+  kind: 'heading' | 'paragraph' | 'table' | 'blockquote' | 'image' | 'empty';
+  payload: unknown;
+}
+
+function parseBlocks(md: string): Block[] {
+  const lines = md.split('\n');
+  const blocks: Block[] = [];
+  let i = 0;
+
+  while (i < lines.length) {
+    const line = lines[i];
+
+    if (!line.trim()) {
+      i++;
+      continue;
+    }
+
+    // Heading
+    const headingMatch = line.match(HEADING_RE);
+    if (headingMatch) {
+      blocks.push({ kind: 'heading', payload: { level: headingMatch[1].length, text: headingMatch[2] } });
+      i++;
+      continue;
+    }
+
+    // Standalone image
+    const imageMatch = line.match(IMAGE_RE);
+    if (imageMatch) {
+      blocks.push({ kind: 'image', payload: { alt: imageMatch[1], src: imageMatch[2] } });
+      i++;
+      continue;
+    }
+
+    // Blockquote run (contiguous `> ` lines)
+    if (line.startsWith('> ')) {
+      const quote: string[] = [];
+      while (i < lines.length && lines[i].startsWith('> ')) {
+        quote.push(lines[i].slice(2));
+        i++;
+      }
+      blocks.push({ kind: 'blockquote', payload: quote.join('\n') });
+      continue;
+    }
+
+    // Possible pipe table: current line has `|` AND next line is a separator.
+    if (line.includes('|') && i + 1 < lines.length && TABLE_SEPARATOR_RE.test(lines[i + 1])) {
+      const header = splitTableCells(line);
+      i += 2; // skip header + separator
+      const rows: string[][] = [];
+      while (i < lines.length && lines[i].trim() && lines[i].includes('|')) {
+        rows.push(splitTableCells(lines[i]));
+        i++;
+      }
+      blocks.push({ kind: 'table', payload: { header, rows } });
+      continue;
+    }
+
+    // Paragraph run (contiguous non-blank, non-special lines).
+    const paragraph: string[] = [line];
+    i++;
+    while (
+      i < lines.length
+      && lines[i].trim()
+      && !lines[i].match(HEADING_RE)
+      && !lines[i].startsWith('> ')
+      && !lines[i].match(IMAGE_RE)
+      && !(
+        lines[i].includes('|')
+        && i + 1 < lines.length
+        && TABLE_SEPARATOR_RE.test(lines[i + 1])
+      )
+    ) {
+      paragraph.push(lines[i]);
+      i++;
+    }
+    blocks.push({ kind: 'paragraph', payload: paragraph.join(' ') });
+  }
+  return blocks;
+}
+
+const FilingMarkdown: React.FC<Props> = ({ markdown }) => {
+  const blocks = React.useMemo(() => parseBlocks(markdown), [markdown]);
+
+  return (
+    <div>
+      {blocks.map((block, idx) => {
+        switch (block.kind) {
+          case 'heading': {
+            const { level, text } = block.payload as { level: number; text: string };
+            const style = level === 2 ? H2_STYLE : level === 3 ? H3_STYLE : H4_STYLE;
+            if (level === 2) return <h2 key={idx} style={style}>{text}</h2>;
+            if (level === 3) return <h3 key={idx} style={style}>{text}</h3>;
+            return <h4 key={idx} style={style}>{text}</h4>;
+          }
+          case 'paragraph': {
+            return <p key={idx} style={P_STYLE}>{block.payload as string}</p>;
+          }
+          case 'blockquote': {
+            return <blockquote key={idx} style={BLOCKQUOTE_STYLE}>{block.payload as string}</blockquote>;
+          }
+          case 'table': {
+            const { header, rows } = block.payload as { header: string[]; rows: string[][] };
+            return (
+              <div key={idx} style={{ overflowX: 'auto' }}>
+                <table style={TABLE_STYLE}>
+                  <thead>
+                    <tr>{header.map((h, hi) => (<th key={hi} style={TH_STYLE}>{cleanCell(h)}</th>))}</tr>
+                  </thead>
+                  <tbody>
+                    {rows.map((row, ri) => (
+                      <tr key={ri}>
+                        {row.map((cell, ci) => (<td key={ci} style={TD_STYLE}>{cleanCell(cell)}</td>))}
+                      </tr>
+                    ))}
+                  </tbody>
+                </table>
+              </div>
+            );
+          }
+          case 'image': {
+            const { alt, src } = block.payload as { alt: string; src: string };
+            // Our parser replaces data URIs with `<inline-image:...>` placeholders
+            // that aren't fetchable. Render them as a visible stub instead of a
+            // broken <img>.
+            if (src.startsWith('<inline-image')) {
+              return <div key={idx} style={PLACEHOLDER_STYLE}>[inline image: {alt || 'no alt text'}]</div>;
+            }
+            return <img key={idx} src={src} alt={alt} style={IMG_STYLE} />;
+          }
+          default:
+            return null;
+        }
+      })}
+    </div>
+  );
+};
+
+export default FilingMarkdown;

src/TerraFin/interface/frontend/src/stock/components/SecFilings.tsx

@@ -0,0 +1,469 @@
+import React from 'react';
+import { publishAgentViewContext, clearAgentViewContextSource } from '../../agent/viewContext';
+import type { FilingRow, TocEntry } from '../useStockData';
+import { useFilingDocument, useFilings } from '../useStockData';
+import FilingMarkdown from './FilingMarkdown';
+
+interface Props {
+  ticker: string;
+  // Fired when the ticker has no SEC registration (CIK lookup 404s). The parent
+  // uses this to hide the whole card — non-US tickers like KOSPI / TSE / HKEX
+  // issuers don't file with SEC, and an empty card is just noise.
+  onUnavailable?: () => void;
+}
+
+// Maximum chars of section body we publish to the agent side-panel.
+// Balances "agent can answer questions about this section" against context
+// size. Larger sections get truncated with an explicit marker.
+const AGENT_EXCERPT_CHAR_LIMIT = 4000;
+
+const PART_HEADING_RE = /^PART\s/i;
+
+interface FilingGroup {
+  part: TocEntry | null; // null only for headings that precede any Part (rare)
+  items: TocEntry[];
+}
+
+// Render every Item the TOC returns — user↔agent parity trumps UI
+// tidiness. Empty-placeholder Items (e.g. the literal "Item 6.
+// Reserved" left in 10-Ks after the SEC removed it) render with a
+// 0-char body; they're unobtrusive when collapsed and stopping the
+// agent from citing a section the user can't see is worse than a
+// small visual noise bump.
+function groupTocByPart(toc: TocEntry[]): FilingGroup[] {
+  const groups: FilingGroup[] = [];
+  let current: FilingGroup = { part: null, items: [] };
+  for (const entry of toc) {
+    if (PART_HEADING_RE.test(entry.text)) {
+      if (current.part || current.items.length > 0) groups.push(current);
+      current = { part: entry, items: [] };
+    } else {
+      current.items.push(entry);
+    }
+  }
+  if (current.part || current.items.length > 0) groups.push(current);
+  return groups;
+}
+
+function groupKey(group: FilingGroup): string {
+  return group.part?.slug ?? '_orphan_';
+}
+
+function sliceSection(markdown: string, entry: TocEntry, next: TocEntry | undefined): string {
+  const lines = markdown.split('\n');
+  const endLine = next ? next.lineIndex : lines.length;
+  // Skip the heading line itself so the body doesn't repeat it.
+  return lines.slice(entry.lineIndex + 1, endLine).join('\n').trim();
+}
+
+function excerptForAgent(body: string): string {
+  if (body.length <= AGENT_EXCERPT_CHAR_LIMIT) return body;
+  return body.slice(0, AGENT_EXCERPT_CHAR_LIMIT) + '\n\n…[excerpt truncated]';
+}
+
+const SecFilings: React.FC<Props> = ({ ticker, onUnavailable }) => {
+  const { data: filingsList, loading: listLoading, error: listError } = useFilings(ticker);
+
+  // Signal the parent once the ticker is confirmed not to be an SEC filer.
+  React.useEffect(() => {
+    if (listError === '404') onUnavailable?.();
+  }, [listError, onUnavailable]);
+  const [selectedForm, setSelectedForm] = React.useState<string | null>(null);
+
+  // Auto-pick the best form when the list first arrives: prefer 10-K, then 10-Q,
+  // then whatever comes first.
+  React.useEffect(() => {
+    if (!filingsList || filingsList.forms.length === 0) {
+      setSelectedForm(null);
+      return;
+    }
+    const preferred = ['10-K', '10-Q'].find((f) => filingsList.forms.includes(f));
+    setSelectedForm(preferred || filingsList.forms[0]);
+  }, [filingsList]);
+
+  const filteredFilings = React.useMemo<FilingRow[]>(() => {
+    if (!filingsList || !selectedForm) return [];
+    return filingsList.filings.filter((f) => f.form === selectedForm);
+  }, [filingsList, selectedForm]);
+
+  const [selectedAccession, setSelectedAccession] = React.useState<string | null>(null);
+  React.useEffect(() => {
+    // On form change, collapse the reader until the user picks a filing.
+    setSelectedAccession(null);
+  }, [selectedForm, ticker]);
+
+  const selectedFiling = React.useMemo<FilingRow | null>(
+    () => filteredFilings.find((f) => f.accession === selectedAccession) ?? null,
+    [filteredFilings, selectedAccession],
+  );
+
+  const { data: filingDoc, loading: docLoading, error: docError } = useFilingDocument(
+    ticker,
+    selectedFiling?.accession ?? null,
+    selectedFiling?.primaryDocument ?? null,
+    selectedFiling?.form ?? '10-Q',
+    Boolean(selectedFiling),
+  );
+
+  // Two-level navigation: outer Parts (Part I / Part II / ...), each holding
+  // its Items. Parts are the structural halves of a 10-K / 10-Q; Items are
+  // the actual content sections.
+  const groups = React.useMemo(
+    () => (filingDoc ? groupTocByPart(filingDoc.toc) : []),
+    [filingDoc],
+  );
+
+  // Default-open state: all Parts expanded so users can scan, plus the first
+  // Item of the first Part so the reader isn't empty on open.
+  const [openParts, setOpenParts] = React.useState<Set<string>>(new Set());
+  const [openItems, setOpenItems] = React.useState<Set<string>>(new Set());
+  React.useEffect(() => {
+    if (groups.length === 0) {
+      setOpenParts(new Set());
+      setOpenItems(new Set());
+      return;
+    }
+    setOpenParts(new Set(groups.map(groupKey)));
+    const first = groups[0].items[0];
+    setOpenItems(first ? new Set([first.slug]) : new Set());
+  }, [groups]);
+
+  const togglePart = (key: string) => {
+    setOpenParts((prev) => {
+      const next = new Set(prev);
+      if (next.has(key)) next.delete(key);
+      else next.add(key);
+      return next;
+    });
+  };
+  const toggleItem = (slug: string) => {
+    setOpenItems((prev) => {
+      const next = new Set(prev);
+      if (next.has(slug)) next.delete(slug);
+      else next.add(slug);
+      return next;
+    });
+  };
+
+  // Publish agent view context: the currently-focused Item (Parts have no
+  // body themselves, so we track Item focus only). Picks the first open Item
+  // in document order — keeps the agent's context small even with multiple
+  // expanded.
+  const visibleItems = React.useMemo(() => groups.flatMap((g) => g.items), [groups]);
+  const focusedSlug = openItems.size > 0
+    ? visibleItems.find((e) => openItems.has(e.slug))?.slug
+    : undefined;
+
+  React.useEffect(() => {
+    if (!selectedFiling || !filingDoc || !focusedSlug) {
+      return;
+    }
+    const entry = visibleItems.find((e) => e.slug === focusedSlug);
+    if (!entry) return;
+    // Use the next *raw* TOC entry (not the next visible one) as the slice
+    // upper bound so we stop at the exact next heading in the markdown.
+    const rawIdx = filingDoc.toc.indexOf(entry);
+    const nextEntry = filingDoc.toc[rawIdx + 1];
+    const body = sliceSection(filingDoc.markdown, entry, nextEntry);
+
+    void publishAgentViewContext({
+      source: 'sec-filings',
+      scope: 'panel',
+      route: window.location.pathname,
+      pageType: 'stock',
+      title: `${ticker} ${selectedFiling.form} — ${entry.text}`,
+      summary: `Viewing ${selectedFiling.form} (filed ${selectedFiling.filingDate}), section "${entry.text}".`,
+      selection: {
+        ticker,
+        // Matches the `form` parameter name on sec_filing_section so the agent
+        // can plug this straight back in without a rename.
+        form: selectedFiling.form,
+        accession: selectedFiling.accession,
+        // Required to call sec_filing_section for a fuller body when the
+        // 4 KB excerpt below isn't enough (Item 1. Business in a large 10-K
+        // can be 30-50 KB).
+        primaryDocument: selectedFiling.primaryDocument,
+        filingDate: selectedFiling.filingDate,
+        reportDate: selectedFiling.reportDate,
+        sectionSlug: entry.slug,
+        sectionTitle: entry.text,
+        sectionExcerpt: excerptForAgent(body),
+        documentUrl: filingDoc.documentUrl,
+        indexUrl: filingDoc.indexUrl,
+      },
+      entities: [
+        { kind: 'ticker', id: ticker, label: ticker },
+        { kind: 'sec-filing', id: selectedFiling.accession, label: `${selectedFiling.form} ${selectedFiling.filingDate}` },
+      ],
+      metadata: { source: 'sec-filings' },
+    });
+    return () => {
+      void clearAgentViewContextSource('sec-filings');
+    };
+  }, [filingDoc, focusedSlug, selectedFiling, ticker, visibleItems]);
+
+  return (
+    <div style={rootStyle}>
+      {listError === '404' ? (
+        // Parent will unmount us via onUnavailable. Render nothing in the
+        // meantime to avoid an error flash.
+        null
+      ) : listLoading && !filingsList ? (
+        <div style={dimStyle}>Loading filings…</div>
+      ) : listError ? (
+        <div style={errorStyle}>Could not load filings: {listError}</div>
+      ) : !filingsList || filingsList.filings.length === 0 ? (
+        <div style={dimStyle}>No SEC filings found for {ticker}.</div>
+      ) : (
+        <>
+          <div style={formRowStyle}>
+            <label htmlFor="filings-form" style={formLabelStyle}>Form</label>
+            <select
+              id="filings-form"
+              value={selectedForm ?? ''}
+              onChange={(e) => setSelectedForm(e.target.value || null)}
+              style={selectStyle}
+            >
+              {filingsList.forms.map((f) => (<option key={f} value={f}>{f}</option>))}
+            </select>
+            <span style={dimStyle}>{filteredFilings.length} filing{filteredFilings.length === 1 ? '' : 's'}</span>
+          </div>
+
+          <div style={filingListStyle}>
+            {filteredFilings.map((row) => {
+              const isSelected = row.accession === selectedAccession;
+              return (
+                <div
+                  key={row.accession}
+                  style={filingRowStyle(isSelected)}
+                  onClick={() => setSelectedAccession(isSelected ? null : row.accession)}
+                  role="button"
+                  tabIndex={0}
+                  onKeyDown={(e) => { if (e.key === 'Enter' || e.key === ' ') setSelectedAccession(isSelected ? null : row.accession); }}
+                >
+                  <div style={{ flex: 1, minWidth: 0 }}>
+                    <div style={{ fontSize: 13, fontWeight: 700, color: '#0f172a' }}>{row.form}</div>
+                    <div style={{ fontSize: 12, color: '#64748b' }}>
+                      Filed {row.filingDate}{row.reportDate ? ` · Period ${row.reportDate}` : ''}
+                    </div>
+                  </div>
+                  <a
+                    href={row.documentUrl}
+                    target="_blank"
+                    rel="noopener noreferrer"
+                    onClick={(e) => e.stopPropagation()}
+                    style={edgarLinkStyle}
+                  >View on EDGAR ↗</a>
+                </div>
+              );
+            })}
+          </div>
+
+          {selectedFiling ? (
+            <div style={readerWrapStyle}>
+              <div style={readerHeaderStyle}>
+                <div style={{ flex: 1, minWidth: 0 }}>
+                  <div style={{ fontSize: 14, fontWeight: 800, color: '#0f172a' }}>
+                    {selectedFiling.form} · Filed {selectedFiling.filingDate}
+                  </div>
+                  {selectedFiling.primaryDocDescription ? (
+                    <div style={{ fontSize: 12, color: '#64748b' }}>{selectedFiling.primaryDocDescription}</div>
+                  ) : null}
+                </div>
+                {filingDoc ? (
+                  <a href={filingDoc.documentUrl} target="_blank" rel="noopener noreferrer" style={edgarPillStyle}>
+                    View source on EDGAR ↗
+                  </a>
+                ) : null}
+              </div>
+
+              {docLoading ? (
+                <div style={dimStyle}>Loading filing…</div>
+              ) : docError ? (
+                docError === '422' ? (
+                  <div style={unsupportedStyle}>
+                    <div style={{ fontSize: 13, color: '#1e293b', marginBottom: 6 }}>
+                      In-app reader doesn&rsquo;t support <strong>{selectedFiling.form}</strong> filings yet.
+                    </div>
+                    <a href={selectedFiling.documentUrl} target="_blank" rel="noopener noreferrer" style={edgarPillStyle}>
+                      Open on EDGAR ↗
+                    </a>
+                  </div>
+                ) : (
+                  <div style={errorStyle}>Could not load filing: {docError}</div>
+                )
+              ) : filingDoc ? (
+                groups.length === 0 ? (
+                  <div style={dimStyle}>Filing has no sections to navigate. Open on EDGAR for the raw document.</div>
+                ) : (
+                  <div style={accordionStyle}>
+                    {groups.map((group) => {
+                      const key = groupKey(group);
+                      const partOpen = openParts.has(key);
+                      const totalChars = group.items.reduce((acc, it) => acc + it.charCount, 0);
+                      return (
+                        <div key={key} style={partCardStyle}>
+                          <button
+                            type="button"
+                            onClick={() => togglePart(key)}
+                            aria-expanded={partOpen}
+                            style={partHeaderStyle(partOpen)}
+                          >
+                            <span style={headerLeftStyle(10)}>
+                              <span style={chevronStyle(partOpen)}>▸</span>
+                              <span style={headerTitleStyle(14, 800, '#0f172a')}>
+                                {group.part?.text ?? 'Sections'}
+                              </span>
+                            </span>
+                            <span style={headerBadgeStyle}>
+                              {group.items.length} item{group.items.length === 1 ? '' : 's'} · {totalChars.toLocaleString()} chars
+                            </span>
+                          </button>
+                          {partOpen ? (
+                            <div style={itemsWrapStyle}>
+                              {group.items.map((entry) => {
+                                const rawIdx = filingDoc.toc.indexOf(entry);
+                                const next = filingDoc.toc[rawIdx + 1];
+                                const body = sliceSection(filingDoc.markdown, entry, next);
+                                const itemOpen = openItems.has(entry.slug);
+                                return (
+                                  <div key={entry.slug} style={itemCardStyle}>
+                                    <button
+                                      type="button"
+                                      onClick={() => toggleItem(entry.slug)}
+                                      aria-expanded={itemOpen}
+                                      style={itemHeaderStyle(itemOpen)}
+                                    >
+                                      <span style={headerLeftStyle(8)}>
+                                        <span style={chevronStyle(itemOpen)}>▸</span>
+                                        <span style={headerTitleStyle(13, 700, '#1e293b')}>
+                                          {entry.text}
+                                        </span>
+                                      </span>
+                                      <span style={headerBadgeStyle}>
+                                        {entry.charCount.toLocaleString()} chars
+                                      </span>
+                                    </button>
+                                    {itemOpen ? (
+                                      <div style={sectionBodyStyle}>
+                                        <FilingMarkdown markdown={body} />
+                                      </div>
+                                    ) : null}
+                                  </div>
+                                );
+                              })}
+                            </div>
+                          ) : null}
+                        </div>
+                      );
+                    })}
+                  </div>
+                )
+              ) : null}
+            </div>
+          ) : (
+            <div style={pickerHintStyle}>Select a filing above to read it with a collapsible section-by-section view.</div>
+          )}
+        </>
+      )}
+    </div>
+  );
+};
+
+// ── styles ─────────────────────────────────────────────────────────────────
+
+const rootStyle: React.CSSProperties = { display: 'flex', flexDirection: 'column', gap: 12, minWidth: 0 };
+const dimStyle: React.CSSProperties = { fontSize: 12, color: '#64748b' };
+const errorStyle: React.CSSProperties = { fontSize: 12, color: '#b91c1c', padding: 8, background: '#fef2f2', borderRadius: 6 };
+const formRowStyle: React.CSSProperties = { display: 'flex', alignItems: 'center', gap: 10, flexWrap: 'wrap' };
+const formLabelStyle: React.CSSProperties = { fontSize: 11, fontWeight: 700, color: '#475569', textTransform: 'uppercase', letterSpacing: 0.5 };
+const selectStyle: React.CSSProperties = {
+  height: 32, borderRadius: 6, border: '1px solid #cbd5e1', background: '#fff',
+  padding: '0 10px', fontSize: 13, color: '#0f172a', outline: 'none',
+};
+const filingListStyle: React.CSSProperties = { display: 'flex', flexDirection: 'column', gap: 6, maxHeight: 220, overflowY: 'auto' };
+const filingRowStyle = (selected: boolean): React.CSSProperties => ({
+  display: 'flex', alignItems: 'center', gap: 10, padding: '8px 10px',
+  border: `1px solid ${selected ? '#1d4ed8' : '#e2e8f0'}`,
+  borderRadius: 8, background: selected ? '#eff6ff' : '#ffffff', cursor: 'pointer',
+});
+const edgarLinkStyle: React.CSSProperties = { fontSize: 11, color: '#475569', textDecoration: 'none', flexShrink: 0 };
+const readerWrapStyle: React.CSSProperties = {
+  display: 'flex', flexDirection: 'column', gap: 10,
+  borderTop: '1px solid #e2e8f0', paddingTop: 12, marginTop: 4,
+};
+const readerHeaderStyle: React.CSSProperties = {
+  display: 'flex', alignItems: 'center', gap: 10, justifyContent: 'space-between', flexWrap: 'wrap',
+};
+const edgarPillStyle: React.CSSProperties = {
+  padding: '6px 12px', borderRadius: 999, background: '#1d4ed8', color: '#fff',
+  fontSize: 12, fontWeight: 700, textDecoration: 'none', flexShrink: 0,
+};
+const accordionStyle: React.CSSProperties = { display: 'flex', flexDirection: 'column', gap: 10 };
+// Part — outer container, heavier visual weight because it's a structural
+// division (10-K Part I = Financial Info, Part II = Other Info).
+const partCardStyle: React.CSSProperties = {
+  border: '1px solid #cbd5e1', borderRadius: 10, background: '#ffffff', overflow: 'hidden',
+  boxShadow: '0 1px 2px rgba(15, 23, 42, 0.04)',
+};
+const partHeaderStyle = (open: boolean): React.CSSProperties => ({
+  width: '100%', border: 'none',
+  background: open ? 'linear-gradient(180deg, #f1f5f9 0%, #e2e8f0 100%)' : '#f8fafc',
+  padding: '12px 14px', display: 'flex', alignItems: 'center', gap: 10,
+  justifyContent: 'space-between', cursor: 'pointer', textAlign: 'left',
+});
+const itemsWrapStyle: React.CSSProperties = {
+  display: 'flex', flexDirection: 'column', gap: 6, padding: '10px 12px 12px',
+  background: '#f8fafc',
+};
+// Item — inner, lighter card.
+const itemCardStyle: React.CSSProperties = {
+  border: '1px solid #e2e8f0', borderRadius: 8, background: '#ffffff', overflow: 'hidden',
+};
+const itemHeaderStyle = (open: boolean): React.CSSProperties => ({
+  width: '100%', border: 'none', background: open ? '#f1f5f9' : '#ffffff',
+  padding: '9px 12px', display: 'flex', alignItems: 'center', gap: 10,
+  justifyContent: 'space-between', cursor: 'pointer', textAlign: 'left',
+});
+const chevronStyle = (open: boolean): React.CSSProperties => ({
+  display: 'inline-block', transition: 'transform 0.15s', transform: open ? 'rotate(90deg)' : 'rotate(0deg)',
+  color: '#64748b', fontSize: 12, flexShrink: 0, width: 12,
+});
+// Header left-hand column (chevron + title). Takes available space and can
+// shrink below its intrinsic width — the `minWidth: 0` is what lets the
+// nowrap+ellipsis truncation actually kick in on narrow viewports instead of
+// the weird mid-word wrap we hit with ZETA ("Bus" / chars / "iness").
+const headerLeftStyle = (gap: number): React.CSSProperties => ({
+  display: 'flex', alignItems: 'center', gap, minWidth: 0, flex: '1 1 auto',
+});
+// Title span itself — must carry `minWidth: 0` so the flex-shrink cascade
+// reaches the span where `overflow: hidden` + `textOverflow: ellipsis`
+// actually clip on narrow viewports.
+const headerTitleStyle = (
+  fontSize: number,
+  fontWeight: number,
+  color: string,
+): React.CSSProperties => ({
+  fontSize,
+  fontWeight,
+  color,
+  minWidth: 0,
+  overflow: 'hidden',
+  textOverflow: 'ellipsis',
+  whiteSpace: 'nowrap',
+});
+const headerBadgeStyle: React.CSSProperties = {
+  fontSize: 11, color: '#64748b', flexShrink: 0,
+};
+const sectionBodyStyle: React.CSSProperties = { padding: '4px 14px 14px' };
+const pickerHintStyle: React.CSSProperties = {
+  fontSize: 12, color: '#64748b', padding: 12, textAlign: 'center',
+  background: '#f8fafc', border: '1px dashed #e2e8f0', borderRadius: 8,
+};
+const unsupportedStyle: React.CSSProperties = {
+  padding: 14, background: '#fffbeb', border: '1px solid #fde68a',
+  borderRadius: 8, display: 'flex', alignItems: 'center', gap: 12,
+  justifyContent: 'space-between', flexWrap: 'wrap',
+};
+
+export default SecFilings;

src/TerraFin/interface/frontend/src/stock/useStockData.ts

@@ -51,7 +51,44 @@ interface ChartPoint {
   close: number;
 }
 
-export type { CompanyInfo, EarningsRecord, FinancialRow, FinancialStatement, ChartPoint };
+interface FilingRow {
+  accession: string;
+  form: string;
+  filingDate: string;
+  reportDate: string | null;
+  primaryDocument: string;
+  primaryDocDescription: string | null;
+  indexUrl: string;
+  documentUrl: string;
+}
+
+interface FilingsListResponse {
+  ticker: string;
+  cik: number;
+  forms: string[];
+  filings: FilingRow[];
+}
+
+interface TocEntry {
+  level: number;
+  text: string;
+  lineIndex: number;
+  slug: string;
+  charCount: number;
+}
+
+interface FilingDocument {
+  ticker: string;
+  accession: string;
+  primaryDocument: string;
+  markdown: string;
+  toc: TocEntry[];
+  charCount: number;
+  indexUrl: string;
+  documentUrl: string;
+}
+
+export type { ChartPoint, CompanyInfo, EarningsRecord, FilingDocument, FilingRow, FilingsListResponse, FinancialRow, FinancialStatement, TocEntry };
 
 export function useCompanyInfo(ticker: string, enabled = true) {
   const [data, setData] = useState<CompanyInfo | null>(null);
@@ -127,6 +164,61 @@ export function useFinancials(ticker: string, statement: string, period: string,
   return { data, loading, error };
 }
 
+export function useFilings(ticker: string, enabled = true) {
+  const [data, setData] = useState<FilingsListResponse | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (!ticker || !enabled) {
+      setData(null);
+      setError(null);
+      setLoading(false);
+      return;
+    }
+    setLoading(true);
+    setError(null);
+    fetch(`/stock/api/filings?ticker=${encodeURIComponent(ticker)}`)
+      .then((res) => (res.ok ? res.json() : Promise.reject(new Error(`${res.status}`))))
+      .then((d: FilingsListResponse) => setData(d))
+      .catch((e) => setError(e.message))
+      .finally(() => setLoading(false));
+  }, [enabled, ticker]);
+
+  return { data, loading, error };
+}
+
+export function useFilingDocument(
+  ticker: string,
+  accession: string | null,
+  primaryDocument: string | null,
+  form: string,
+  enabled = true,
+) {
+  const [data, setData] = useState<FilingDocument | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (!enabled || !ticker || !accession || !primaryDocument) {
+      setData(null);
+      setError(null);
+      setLoading(false);
+      return;
+    }
+    setLoading(true);
+    setError(null);
+    const qs = new URLSearchParams({ ticker, accession, primaryDocument, form });
+    fetch(`/stock/api/filing-document?${qs.toString()}`)
+      .then((res) => (res.ok ? res.json() : Promise.reject(new Error(`${res.status}`))))
+      .then((d: FilingDocument) => setData(d))
+      .catch((e) => setError(e.message))
+      .finally(() => setLoading(false));
+  }, [accession, enabled, form, primaryDocument, ticker]);
+
+  return { data, loading, error };
+}
+
 export function useChartOHLCV(ticker: string) {
   const [data, setData] = useState<ChartPoint[]>([]);
   const [loading, setLoading] = useState(true);

src/TerraFin/interface/stock/data_routes.py

@@ -11,6 +11,8 @@ from TerraFin.analytics.analysis.risk import estimate_beta_5y_monthly, estimate_
 from TerraFin.interface.stock.payloads import (
     build_company_info_payload,
     build_earnings_payload,
+    build_filing_document_payload,
+    build_filings_list_payload,
     build_financial_statement_payload,
     resolve_ticker_query,
 )
@@ -84,6 +86,54 @@ class ResolveTickerResponse(BaseModel):
     path: str
 
 
+class FilingRowResponse(BaseModel):
+    accession: str
+    form: str
+    filingDate: str
+    reportDate: str | None = None
+    primaryDocument: str
+    primaryDocDescription: str | None = None
+    indexUrl: str
+    documentUrl: str
+
+
+class FilingLatestByFormEntry(BaseModel):
+    accession: str
+    primaryDocument: str
+    filingDate: str
+    reportDate: str | None = None
+    documentUrl: str
+
+
+class FilingsListResponse(BaseModel):
+    ticker: str
+    cik: int
+    forms: list[str]
+    filings: list[FilingRowResponse]
+    # Shortcut: `latestByForm["10-K"].accession` gives direct access to the
+    # newest filing of a given form without scanning the chronological list.
+    latestByForm: dict[str, FilingLatestByFormEntry] = {}
+
+
+class TocEntry(BaseModel):
+    level: int
+    text: str
+    lineIndex: int
+    slug: str
+    charCount: int
+
+
+class FilingDocumentResponse(BaseModel):
+    ticker: str
+    accession: str
+    primaryDocument: str
+    markdown: str
+    toc: list[TocEntry]
+    charCount: int
+    indexUrl: str
+    documentUrl: str
+
+
 class BetaEstimateResponse(BaseModel):
     status: str
     symbol: str
@@ -207,4 +257,29 @@ def create_stock_data_router() -> APIRouter:
     def api_resolve_ticker(q: str = Query(..., min_length=1)):
         return ResolveTickerResponse(**resolve_ticker_query(q))
 
+    @router.get(f"{STOCK_API_PREFIX}/filings", response_model=FilingsListResponse)
+    def api_filings(
+        ticker: str = Query(..., min_length=1),
+        limit: int = Query(default=20, ge=1, le=100),
+    ):
+        return FilingsListResponse(**build_filings_list_payload(ticker, limit=limit))
+
+    @router.get(f"{STOCK_API_PREFIX}/filing-document", response_model=FilingDocumentResponse)
+    def api_filing_document(
+        ticker: str = Query(..., min_length=1),
+        accession: str = Query(..., min_length=1),
+        primaryDocument: str = Query(..., min_length=1),
+        form: str = Query(default="10-Q", min_length=1),
+        includeImages: bool = Query(default=False),
+    ):
+        return FilingDocumentResponse(
+            **build_filing_document_payload(
+                ticker,
+                accession,
+                primaryDocument,
+                form=form,
+                include_images=includeImages,
+            )
+        )
+
     return router

src/TerraFin/interface/stock/payloads.py

@@ -5,6 +5,14 @@ from typing import Any
 from fastapi import HTTPException
 
 from TerraFin.data import DataFactory
+from TerraFin.data.providers.corporate.filings.sec_edgar import (
+    build_toc,
+    download_filing,
+    get_company_filings,
+    get_ticker_to_cik_dict_cached,
+    parse_sec_filing,
+)
+from TerraFin.data.providers.corporate.filings.sec_edgar.filing import SecEdgarError
 from TerraFin.data.providers.market.ticker_info import get_ticker_earnings, get_ticker_info
 from TerraFin.interface.market_insights.payloads import canonical_macro_name, resolve_macro_type
 
@@ -119,3 +127,156 @@ def resolve_ticker_query(query: str) -> dict[str, str]:
 
     upper = name.upper()
     return {"type": "stock", "name": upper, "path": f"/stock/{upper}"}
+
+
+# ---------------------------------------------------------------------------
+# SEC filings
+# ---------------------------------------------------------------------------
+
+
+def _edgar_urls(cik: int, accession_number: str, primary_doc: str) -> dict[str, str]:
+    acc_clean = accession_number.replace("-", "")
+    cik_padded = str(cik).zfill(10)
+    archive_base = f"https://www.sec.gov/Archives/edgar/data/{cik_padded}/{acc_clean}"
+    # Human-facing link: SEC's inline-XBRL viewer (`/ix?doc=/Archives/...`).
+    # This is the URL you get when you click a filing on EDGAR — it wraps the
+    # primary document in SEC's viewer UI with proper styling and navigation,
+    # working for both iXBRL-tagged and plain HTML filings.
+    # `indexUrl` still points at the raw directory listing for debugging and
+    # file-level access.
+    if primary_doc:
+        document_url = f"https://www.sec.gov/ix?doc=/Archives/edgar/data/{cik_padded}/{acc_clean}/{primary_doc}"
+    else:
+        document_url = f"{archive_base}/"
+    return {
+        "indexUrl": f"{archive_base}/",
+        "documentUrl": document_url,
+    }
+
+
+def _resolve_cik(ticker: str) -> int:
+    cik = get_ticker_to_cik_dict_cached().get(ticker.upper())
+    if cik is None:
+        raise HTTPException(status_code=404, detail=f"CIK not found for ticker '{ticker}'.")
+    return int(cik)
+
+
+def build_filings_list_payload(ticker: str, *, limit: int = 20) -> dict[str, Any]:
+    """List recent 10-K / 10-Q / 8-K filings with EDGAR links."""
+    normalized = ticker.upper()
+    cik = _resolve_cik(normalized)
+    try:
+        df = get_company_filings(cik, include_8k=True)
+    except SecEdgarError as exc:
+        raise HTTPException(status_code=503, detail=str(exc)) from exc
+
+    if df is None or df.empty:
+        return {"ticker": normalized, "cik": cik, "forms": [], "filings": []}
+
+    df = df.sort_values("filingDate", ascending=False).head(limit)
+
+    filings: list[dict[str, Any]] = []
+    for _, row in df.iterrows():
+        accession = str(row.get("accessionNumber", ""))
+        primary_doc = str(row.get("primaryDocument", ""))
+        urls = _edgar_urls(cik, accession, primary_doc)
+        filings.append(
+            {
+                "accession": accession,
+                "form": str(row.get("form", "")),
+                "filingDate": str(row.get("filingDate", "")),
+                "reportDate": str(row.get("reportDate", "")) or None,
+                "primaryDocument": primary_doc,
+                "primaryDocDescription": str(row.get("primaryDocDescription", "")) or None,
+                "indexUrl": urls["indexUrl"],
+                "documentUrl": urls["documentUrl"],
+            }
+        )
+
+    # Forms present in this result, in canonical order (10-K first, then 10-Q, 8-K,
+    # then anything else). Lets the frontend build a form dropdown without
+    # guessing what exists for this ticker (e.g. 20-F for foreign filers).
+    seen: list[str] = []
+    for f in filings:
+        form = f["form"]
+        if form and form not in seen:
+            seen.append(form)
+    priority = {"10-K": 0, "10-K/A": 1, "10-Q": 2, "10-Q/A": 3, "8-K": 4, "8-K/A": 5}
+    seen.sort(key=lambda f: priority.get(f, 100))
+
+    # Per-form shortcut so an agent can do `latestByForm["10-K"]` directly
+    # instead of scanning a chronological list that mixes 8-Ks in front of
+    # quarterly/annual filings. Each entry carries enough to call
+    # `sec_filing_section` / `sec_filing_document` with no follow-up.
+    latest_by_form: dict[str, dict[str, Any]] = {}
+    for f in filings:
+        form = f["form"]
+        if form and form not in latest_by_form:
+            latest_by_form[form] = {
+                "accession": f["accession"],
+                "primaryDocument": f["primaryDocument"],
+                "filingDate": f["filingDate"],
+                "reportDate": f["reportDate"],
+                "documentUrl": f["documentUrl"],
+            }
+
+    return {
+        "ticker": normalized,
+        "cik": cik,
+        "forms": seen,
+        "filings": filings,
+        "latestByForm": latest_by_form,
+    }
+
+
+def build_filing_document_payload(
+    ticker: str,
+    accession: str,
+    primary_document: str,
+    *,
+    form: str = "10-Q",
+    include_images: bool = False,
+) -> dict[str, Any]:
+    """Fetch + parse a specific filing, returning the markdown body plus a TOC."""
+    normalized = ticker.upper()
+    cik = _resolve_cik(normalized)
+
+    acc_clean = accession.replace("-", "")
+    if not primary_document:
+        raise HTTPException(status_code=400, detail="primaryDocument is required.")
+
+    try:
+        html = download_filing(cik, acc_clean, primary_document)
+    except SecEdgarError as exc:
+        raise HTTPException(status_code=503, detail=str(exc)) from exc
+
+    try:
+        markdown = parse_sec_filing(html, form, include_images=include_images)
+    except ValueError as exc:
+        # Unsupported form (e.g., a DEF 14A passed through) — raw fallback.
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+    # `max_level=2` keeps the sidebar compact (Part/Item scaffold only).
+    # Normalize keys to camelCase for frontend consistency with the rest of the API.
+    toc = [
+        {
+            "level": entry["level"],
+            "text": entry["text"],
+            "lineIndex": entry["line_index"],
+            "slug": entry["slug"],
+            "charCount": entry["char_count"],
+        }
+        for entry in build_toc(markdown, max_level=2)
+    ]
+
+    urls = _edgar_urls(cik, acc_clean, primary_document)
+    return {
+        "ticker": normalized,
+        "accession": acc_clean,
+        "primaryDocument": primary_document,
+        "markdown": markdown,
+        "toc": toc,
+        "charCount": len(markdown),
+        "indexUrl": urls["indexUrl"],
+        "documentUrl": urls["documentUrl"],
+    }

tests/agent/fixtures/aapl_10q_fy25q2_sample.md

@@ -0,0 +1,75 @@
+## PART I - FINANCIAL INFORMATION
+
+## Item 1. Financial Statements
+
+CONDENSED CONSOLIDATED STATEMENTS OF OPERATIONS (unaudited, in millions, except per share data)
+
+| | Three Months Ended March 29, 2025 | Three Months Ended March 30, 2024 | Six Months Ended March 29, 2025 | Six Months Ended March 30, 2024 |
+| --- | --- | --- | --- | --- |
+| Products net sales | 68,714 | 66,886 | 166,674 | 163,582 |
+| Services net sales | 26,645 | 23,867 | 52,086 | 46,984 |
+| Total net sales | 95,359 | 90,753 | 218,760 | 210,566 |
+| Products cost of sales | 45,598 | 43,757 | 108,905 | 106,557 |
+| Services cost of sales | 6,723 | 6,280 | 12,819 | 11,926 |
+| Total cost of sales | 52,321 | 50,037 | 121,724 | 118,483 |
+| Gross margin | 43,038 | 40,716 | 97,036 | 92,083 |
+| Operating expenses — Research and development | 8,550 | 7,903 | 16,850 | 15,668 |
+| Operating expenses — Selling, general and administrative | 6,728 | 6,468 | 13,836 | 13,418 |
+| Total operating expenses | 15,278 | 14,371 | 30,686 | 29,086 |
+| Operating income | 27,760 | 26,345 | 66,350 | 62,997 |
+| Other income/(expense), net | 308 | 158 | 515 | 208 |
+| Income before provision for income taxes | 28,068 | 26,503 | 66,865 | 63,205 |
+| Provision for income taxes | 3,477 | 4,422 | 10,697 | 10,551 |
+| Net income | 24,591 | 22,081 | 56,168 | 52,654 |
+| Earnings per share — basic | 1.65 | 1.42 | 3.75 | 3.39 |
+| Earnings per share — diluted | 1.65 | 1.41 | 3.74 | 3.37 |
+
+## Item 2. Management's Discussion and Analysis of Financial Condition and Results of Operations
+
+### Products and Services Performance
+
+iPhone net sales increased during Q2 2025 compared to Q2 2024 driven by the iPhone 16 family and higher average selling prices. Mac net sales increased primarily due to higher sales of MacBook Air following the M4 refresh. iPad net sales were roughly flat on a year-over-year basis. Wearables, Home and Accessories net sales decreased, reflecting softer demand for Apple Watch. Services net sales grew 12% year over year and reached an all-time high, driven by App Store, advertising, and subscription services.
+
+### Gross Margin
+
+Products gross margin was 33.6% versus 34.6% in the year-ago quarter, reflecting a less favorable mix and higher component costs. Services gross margin was 74.7% versus 74.6%, essentially flat. Company-wide gross margin was 45.1% versus 44.9%, improving slightly on Services mix.
+
+### Operating Expenses
+
+R&D spending grew 8% year over year, reflecting continued investment in Apple Intelligence and custom silicon. SG&A grew 4%, below the rate of net sales growth, indicating operating leverage.
+
+### Liquidity and Capital Resources
+
+Cash, cash equivalents and marketable securities totaled $140.8 billion at quarter end. During the first six months of fiscal 2025, the Company generated $63.8 billion in cash from operating activities. The Company returned $55.7 billion to shareholders in the first six months through $14.1 billion of dividends and $41.6 billion of share repurchases. The Company expects to continue its capital return program.
+
+As of March 29, 2025, the Company had $95.3 billion of term debt outstanding, with a weighted average effective interest rate of 3.9%. $9.4 billion of term debt is scheduled to mature within the next 12 months.
+
+## Item 3. Quantitative and Qualitative Disclosures About Market Risk
+
+There have been no material changes in the Company's exposure to market risk since September 28, 2024. Refer to Part II, Item 7A of the Annual Report on Form 10-K for the fiscal year ended September 28, 2024.
+
+## Item 4. Controls and Procedures
+
+Based on an evaluation, management concluded that the Company's disclosure controls and procedures were effective as of March 29, 2025. There were no changes in the Company's internal control over financial reporting during the quarter that materially affected, or are reasonably likely to materially affect, internal control over financial reporting.
+
+## PART II - OTHER INFORMATION
+
+## Item 1. Legal Proceedings
+
+Refer to Note 10, "Commitments and Contingencies," of the Notes to Condensed Consolidated Financial Statements for a description of the Company's legal proceedings. The Company is currently subject to multiple legal and regulatory matters, including antitrust investigations by the European Commission and the U.S. Department of Justice relating to App Store practices. On April 30, 2025, the U.S. District Court for the Northern District of California issued findings adverse to the Company in the Epic Games matter. The Company intends to appeal.
+
+## Item 1A. Risk Factors
+
+The Company's business, reputation, results of operations and financial condition are subject to various risks, many of which are not exclusively within the Company's control. The risks and uncertainties described in Part I, Item 1A of the Annual Report on Form 10-K for the fiscal year ended September 28, 2024, remain materially unchanged. Additional risks not currently known or that are currently considered immaterial may also impact the Company's business.
+
+## Item 2. Unregistered Sales of Equity Securities and Use of Proceeds
+
+During the second quarter of fiscal 2025, the Company repurchased $20.9 billion of its common stock. The repurchase program authorized in May 2024 had $81.1 billion remaining as of March 29, 2025.
+
+## Item 5. Other Information
+
+During the three months ended March 29, 2025, none of the Company's directors or officers adopted or terminated a Rule 10b5-1 trading arrangement or a non-Rule 10b5-1 trading arrangement.
+
+## Item 6. Exhibits
+
+Reference is made to the Exhibit Index included herewith.

tests/agent/fixtures/nvda_10q_fy26q3_sample.md

@@ -0,0 +1,90 @@
+## PART I - FINANCIAL INFORMATION
+
+## Item 1. Financial Statements
+
+CONDENSED CONSOLIDATED STATEMENTS OF INCOME (unaudited, in millions, except per share data)
+
+| | Three Months Ended October 26, 2025 | Three Months Ended October 27, 2024 | Nine Months Ended October 26, 2025 | Nine Months Ended October 27, 2024 |
+| --- | --- | --- | --- | --- |
+| Revenue | 45,217 | 35,082 | 126,441 | 90,840 |
+| Cost of revenue | 11,856 | 9,150 | 33,412 | 23,901 |
+| Gross profit | 33,361 | 25,932 | 93,029 | 66,939 |
+| Research and development | 4,612 | 3,390 | 13,184 | 9,518 |
+| Sales, general and administrative | 1,098 | 896 | 3,012 | 2,558 |
+| Operating income | 27,651 | 21,646 | 76,833 | 54,863 |
+| Interest income | 623 | 471 | 1,845 | 1,289 |
+| Interest expense | (61) | (63) | (183) | (188) |
+| Other, net | 57 | (11) | 142 | (18) |
+| Income before income tax | 28,270 | 22,043 | 78,637 | 55,946 |
+| Income tax expense | 4,529 | 3,053 | 12,267 | 7,845 |
+| Net income | 23,741 | 18,990 | 66,370 | 48,101 |
+| Earnings per share — basic | 0.97 | 0.78 | 2.71 | 1.97 |
+| Earnings per share — diluted | 0.96 | 0.77 | 2.69 | 1.94 |
+
+Segment revenue (unaudited, in millions):
+
+| | Three Months Ended Oct 26, 2025 | Three Months Ended Oct 27, 2024 | Nine Months Ended Oct 26, 2025 | Nine Months Ended Oct 27, 2024 |
+| --- | --- | --- | --- | --- |
+| Data Center | 39,542 | 30,771 | 109,875 | 77,313 |
+| Gaming | 3,205 | 3,279 | 9,410 | 8,412 |
+| Professional Visualization | 601 | 486 | 1,763 | 1,346 |
+| Automotive | 592 | 449 | 1,706 | 1,181 |
+| OEM & Other | 1,277 | 97 | 3,687 | 2,588 |
+
+## Item 2. Management's Discussion and Analysis of Financial Condition and Results of Operations
+
+### Data Center
+
+Data Center revenue of $39.5 billion for Q3 FY26 was up 29% sequentially and up 29% year over year. Growth was driven by ramp of Blackwell platform systems, which generated more than $28 billion of revenue during the quarter, and continued demand from large cloud service providers. Enterprise contribution was approximately 15% of Data Center revenue, up from roughly 10% in the prior-year quarter. Networking within Data Center grew to approximately $6 billion quarterly revenue, driven by Spectrum-X Ethernet and NVLink switching.
+
+### Gaming
+
+Gaming revenue of $3.2 billion was down 2% year over year, reflecting slower supply of Blackwell-generation GeForce products that shipped late in the quarter. Management expects Gaming to return to year-over-year growth in Q4 FY26 as supply normalizes.
+
+### Gross Margin
+
+GAAP gross margin for Q3 FY26 was 73.8%, down 120 basis points sequentially and up 140 basis points year over year. The sequential decline reflects higher initial yield costs on the transition to Blackwell HGX-based systems with more complex packaging and integration. Management expects gross margin to stabilize in the mid-70s as yields improve and the product mix benefits from higher-margin NVLink-based systems.
+
+### Operating Expenses
+
+Operating expenses grew to $5.7 billion, up approximately 33% year over year, reflecting higher compensation expense for an expanded engineering workforce, multi-generation roadmap execution (Blackwell Ultra and Rubin), and build-out of data-center networking capabilities. Full-year FY26 non-GAAP operating expense growth is expected in the high-30% range.
+
+### Liquidity and Capital Resources
+
+Cash, cash equivalents and marketable securities totaled $38.5 billion at quarter end, up from $34.8 billion at the end of Q2 FY26. The Company generated $26.8 billion of cash from operating activities in Q3, and $71.2 billion in the first nine months. Capital expenditures were $1.4 billion for Q3 and $3.7 billion year to date, reflecting investments in data-center build-out, including internal compute capacity for engineering and product development.
+
+During Q3, the Company repurchased 125.3 million shares of common stock for $22.4 billion. An additional $1.8 billion in dividends was paid. As of October 26, 2025, approximately $29.6 billion remained available under the Company's share-repurchase authorization. The Board has authorized share repurchases without an expiration date, and repurchases are made from time to time based on market conditions.
+
+The Company has $8.46 billion in long-term debt outstanding with interest rates ranging from 1.55% to 3.70%.
+
+## Item 3. Quantitative and Qualitative Disclosures About Market Risk
+
+Our exposure to market risk has not changed materially since January 26, 2025. Refer to Part II, Item 7A of our Annual Report on Form 10-K for the fiscal year ended January 26, 2025.
+
+## Item 4. Controls and Procedures
+
+Based on an evaluation, management concluded that the Company's disclosure controls and procedures were effective as of October 26, 2025. There were no changes in the Company's internal control over financial reporting during the quarter that materially affected, or are reasonably likely to materially affect, internal control over financial reporting.
+
+## PART II - OTHER INFORMATION
+
+## Item 1. Legal Proceedings
+
+Refer to Note 13, "Commitments and Contingencies," of the Notes to Condensed Consolidated Financial Statements for a description of the Company's legal proceedings. The Company is subject to various class-action lawsuits in the United States alleging violations of federal securities laws with respect to disclosures relating to the AI accelerator business. Additionally, the Company is subject to export-licensing requirements imposed by the U.S. Department of Commerce, and on September 12, 2025, additional licensing requirements were published that further restrict sales of certain GPU products to customers in specified regions. The Company does not currently believe that these restrictions, individually or in the aggregate, will have a material adverse effect on its results of operations for the remainder of fiscal 2026, given visible order substitution.
+
+## Item 1A. Risk Factors
+
+The Company's business, reputation, results of operations and financial condition are subject to various risks, many of which are not exclusively within the Company's control. Except as noted below, the risks and uncertainties described in Part I, Item 1A of the Annual Report on Form 10-K for the fiscal year ended January 26, 2025, remain materially unchanged.
+
+Export controls: On September 12, 2025, the U.S. government published additional export-licensing requirements that further restrict sales of certain GPU products. The Company continues to assess the impact and may need to redesign products for compliance, which could delay product availability and reduce revenue from affected customers. For the quarter ended October 26, 2025, the Company recorded $1.2 billion of revenue from products covered by the new restrictions, substantially all of which was recognized prior to the restrictions becoming effective.
+
+## Item 2. Unregistered Sales of Equity Securities and Use of Proceeds
+
+During the third quarter of fiscal 2026, the Company repurchased 125.3 million shares of common stock for $22.4 billion. As of October 26, 2025, approximately $29.6 billion remained available under the share-repurchase program.
+
+## Item 5. Other Information
+
+During the three months ended October 26, 2025, one of our officers, Colette M. Kress (Executive Vice President and Chief Financial Officer), adopted a Rule 10b5-1 trading arrangement on September 11, 2025 providing for the potential sale of up to 200,000 shares of common stock until September 11, 2026. No director or other officer adopted or terminated a Rule 10b5-1 trading arrangement or a non-Rule 10b5-1 trading arrangement.
+
+## Item 6. Exhibits
+
+Reference is made to the Exhibit Index included herewith.

tests/agent/fixtures/tsla_10q_2025q2_sample.md

@@ -0,0 +1,91 @@
+## PART I - FINANCIAL INFORMATION
+
+## Item 1. Financial Statements
+
+CONDENSED CONSOLIDATED STATEMENTS OF OPERATIONS (unaudited, in millions, except per share data)
+
+| | Three Months Ended June 30, 2025 | Three Months Ended June 30, 2024 | Six Months Ended June 30, 2025 | Six Months Ended June 30, 2024 |
+| --- | --- | --- | --- | --- |
+| Automotive sales | 17,894 | 19,878 | 34,961 | 38,873 |
+| Automotive regulatory credits | 439 | 890 | 1,034 | 1,332 |
+| Automotive leasing | 472 | 458 | 969 | 934 |
+| Total automotive revenues | 18,805 | 21,226 | 36,964 | 41,139 |
+| Energy generation and storage | 2,856 | 3,014 | 5,523 | 4,649 |
+| Services and other | 2,892 | 2,608 | 5,657 | 5,071 |
+| Total revenues | 24,553 | 26,848 | 48,144 | 50,859 |
+| Automotive cost of revenues | 15,842 | 17,376 | 31,144 | 33,857 |
+| Energy cost of revenues | 2,183 | 2,285 | 4,243 | 3,628 |
+| Services cost of revenues | 2,648 | 2,519 | 5,267 | 4,828 |
+| Total cost of revenues | 20,673 | 22,180 | 40,654 | 42,313 |
+| Gross profit | 3,880 | 4,668 | 7,490 | 8,546 |
+| Research and development | 1,584 | 1,074 | 2,852 | 2,225 |
+| Selling, general and administrative | 1,439 | 1,277 | 2,806 | 2,655 |
+| Restructuring and other | — | 622 | 50 | 1,164 |
+| Total operating expenses | 3,023 | 2,973 | 5,708 | 6,044 |
+| Income from operations | 857 | 1,695 | 1,782 | 2,502 |
+| Interest income | 324 | 348 | 672 | 698 |
+| Interest expense | (54) | (86) | (109) | (168) |
+| Other income/(expense), net | 237 | (30) | 425 | 98 |
+| Income before income taxes | 1,364 | 1,927 | 2,770 | 3,130 |
+| Provision for income taxes | 172 | 364 | 381 | 775 |
+| Net income | 1,192 | 1,563 | 2,389 | 2,355 |
+| Earnings per share — basic | 0.37 | 0.49 | 0.74 | 0.74 |
+| Earnings per share — diluted | 0.37 | 0.48 | 0.74 | 0.72 |
+
+## Item 2. Management's Discussion and Analysis of Financial Condition and Results of Operations
+
+### Overview
+
+Total revenues for the three months ended June 30, 2025 decreased 9% year over year to $24.55 billion, primarily reflecting lower vehicle average selling prices and reduced automotive regulatory credit revenue. Deliveries for the quarter were approximately 384,000 vehicles, down 13% year over year, driven by softer demand in key markets and the production changeover at the Fremont and Austin factories to support the refreshed Model Y. Energy generation and storage revenue declined 5% as storage deployments timing shifted into the second half of the year, partially offset by continued Megapack pricing strength.
+
+### Automotive Gross Margin (excluding regulatory credits)
+
+Automotive gross margin excluding regulatory credits was 14.9% compared with 14.6% in the year-ago quarter. The improvement reflects $1,100 per vehicle of cost reduction driven by lower component costs and manufacturing efficiency, partially offset by lower average selling prices of approximately $1,700 per vehicle. Regulatory credit revenue of $439 million compared with $890 million in the prior-year quarter reflects a contraction in credit demand from U.S. original equipment manufacturers.
+
+### Energy Storage
+
+Energy storage deployments were 9.4 GWh compared with 9.4 GWh in Q2 2024. Megapack gross margin expanded approximately 500 basis points to 33.7%. Management expects full-year storage deployments of 40-50 GWh versus 31.4 GWh in 2024.
+
+### Operating Expenses
+
+R&D expense increased 47% year over year to $1.58 billion, reflecting accelerated investment in AI training infrastructure (Cortex supercomputer cluster now at approximately 50,000 H100-equivalent GPUs) and continued development of the next-generation vehicle platform. SG&A grew 13%. There were no material restructuring charges in the current quarter compared with $622 million in Q2 2024.
+
+### Liquidity and Capital Resources
+
+Cash, cash equivalents, and short-term investments totaled $36.8 billion as of June 30, 2025, up from $30.7 billion at December 31, 2024. The Company generated $3.6 billion of operating cash flow during Q2 2025 and $6.3 billion for the six months ended June 30, 2025. Capital expenditures were $2.3 billion for the quarter and $4.5 billion year to date, including Cortex cluster build-out, production capacity for the Model Y refresh, and Gigafactory Shanghai storage expansion.
+
+The Company does not pay dividends and has no share-repurchase program.
+
+Long-term debt net of current portion was $5.4 billion as of June 30, 2025, at a weighted average interest rate of 2.4%.
+
+## Item 3. Quantitative and Qualitative Disclosures About Market Risk
+
+There have been no material changes in our market risk exposures since December 31, 2024. Refer to Part II, Item 7A of our Annual Report on Form 10-K for the fiscal year ended December 31, 2024.
+
+## Item 4. Controls and Procedures
+
+Based on an evaluation, management concluded that the Company's disclosure controls and procedures were effective as of June 30, 2025. There were no changes in the Company's internal control over financial reporting during the quarter that materially affected, or are reasonably likely to materially affect, internal control over financial reporting.
+
+## PART II - OTHER INFORMATION
+
+## Item 1. Legal Proceedings
+
+Refer to Note 12, "Commitments and Contingencies," of the Notes to Condensed Consolidated Financial Statements for a description of the Company's legal proceedings. The Company is subject to various lawsuits concerning product-liability matters related to Autopilot and Full Self-Driving features, and in June 2025 the National Highway Traffic Safety Administration opened a formal investigation into alleged phantom-braking incidents affecting approximately 1.9 million Model 3 and Model Y vehicles produced between 2017 and 2025. The Company continues to cooperate with NHTSA and other regulators.
+
+## Item 1A. Risk Factors
+
+Except as noted below, the risks and uncertainties described in Part I, Item 1A of the Annual Report on Form 10-K for the fiscal year ended December 31, 2024, remain materially unchanged.
+
+Tariff exposure: Effective April 3, 2025, the U.S. government imposed tariffs on imported automotive components, which has increased per-vehicle production cost by approximately $1,500 for certain imported powertrain parts. The Company has taken steps to mitigate this exposure through supplier diversification and may not be able to fully offset the impact through pricing.
+
+## Item 2. Unregistered Sales of Equity Securities and Use of Proceeds
+
+The Company does not have an authorized share-repurchase program, and no shares were repurchased during the quarter.
+
+## Item 5. Other Information
+
+During the three months ended June 30, 2025, none of our directors or officers adopted or terminated a Rule 10b5-1 trading arrangement or a non-Rule 10b5-1 trading arrangement.
+
+## Item 6. Exhibits
+
+Reference is made to the Exhibit Index included herewith.

tests/agent/test_runtime.py

@@ -121,6 +121,43 @@ class _FakeService:
             "processing": _processing(),
         }
 
+    def sec_filings(self, ticker: str) -> dict[str, object]:
+        return {"ticker": ticker, "cik": 1, "forms": [], "filings": [], "processing": _processing()}
+
+    def sec_filing_document(
+        self, ticker: str, accession: str, primaryDocument: str, *, form: str = "10-Q"
+    ) -> dict[str, object]:
+        return {"ticker": ticker, "accession": accession, "primaryDocument": primaryDocument, "toc": [], "charCount": 0, "indexUrl": "", "documentUrl": "", "processing": _processing()}
+
+    def sec_filing_section(
+        self, ticker: str, accession: str, primaryDocument: str, sectionSlug: str, *, form: str = "10-Q"
+    ) -> dict[str, object]:
+        return {"ticker": ticker, "accession": accession, "sectionSlug": sectionSlug, "sectionTitle": "stub", "markdown": "", "charCount": 0, "documentUrl": "", "processing": _processing()}
+
+    def fear_greed(self) -> dict[str, object]:
+        return {"score": 50, "rating": "Neutral", "processing": _processing()}
+
+    def sp500_dcf(self) -> dict[str, object]:
+        return {"status": "ready", "currentIntrinsicValue": 5000.0, "processing": _processing()}
+
+    def beta_estimate(self, ticker: str) -> dict[str, object]:
+        return {"symbol": ticker, "beta": 1.0, "adjustedBeta": 1.0, "rSquared": 0.5, "processing": _processing()}
+
+    def top_companies(self) -> dict[str, object]:
+        return {"companies": [], "count": 0, "processing": _processing()}
+
+    def market_regime(self) -> dict[str, object]:
+        return {"summary": "stub", "confidence": "low", "signals": [], "processing": _processing()}
+
+    def trailing_forward_pe(self) -> dict[str, object]:
+        return {"date": "2026-04-01", "latestValue": 0.0, "history": [], "processing": _processing()}
+
+    def market_breadth(self) -> dict[str, object]:
+        return {"metrics": [], "processing": _processing()}
+
+    def watchlist(self) -> dict[str, object]:
+        return {"items": [], "count": 0, "processing": _processing()}
+
 
 class _ExplodingService(_FakeService):
     def market_snapshot(self, name: str, *, depth: str = "auto", view: str = "daily") -> dict[str, object]:
@@ -160,10 +197,24 @@ def test_default_capability_registry_contains_kernel_capabilities() -> None:
         "economic",
         "macro_focus",
         "calendar_events",
+        # Dashboard widget-parity capabilities, inserted before `open_chart` so
+        # registry ordering tracks grouping (research read-only first, then
+        # chart-opening, then SEC filings).
+        "fear_greed",
+        "sp500_dcf",
+        "beta_estimate",
+        "top_companies",
+        "market_regime",
+        "trailing_forward_pe",
+        "market_breadth",
+        "watchlist",
         "open_chart",
         "fundamental_screen",
         "risk_profile",
         "valuation",
+        "sec_filings",
+        "sec_filing_document",
+        "sec_filing_section",
     )
 
 

tests/agent/test_sec_capabilities.py

@@ -0,0 +1,161 @@
+"""Tests for the three SEC-filing capabilities wired into the agent runtime."""
+
+import pytest
+
+from TerraFin.agent.runtime import build_default_capability_registry
+from TerraFin.agent.service import TerraFinAgentService
+from TerraFin.agent.tool_contracts import HOSTED_TOOL_CONTRACTS
+from TerraFin.interface.stock import payloads
+
+
+@pytest.fixture(autouse=True)
+def _stub_payloads(monkeypatch):
+    """Intercept network-facing payload builders with deterministic stubs."""
+    monkeypatch.setattr(payloads, "get_ticker_to_cik_dict_cached", lambda: {"AAPL": 320193})
+
+    def fake_filings_df(cik, include_8k=False):
+        import pandas as pd
+
+        return pd.DataFrame(
+            {
+                "form": ["10-K", "10-Q", "8-K"],
+                "accessionNumber": ["0000320193-25-000001", "0000320193-24-000010", "0000320193-24-000007"],
+                "filingDate": ["2025-02-02", "2024-11-02", "2024-08-02"],
+                "reportDate": ["2024-12-28", "2024-09-28", "2024-08-01"],
+                "primaryDocument": ["aapl-20241228.htm", "aapl-20240928.htm", "aapl-8k.htm"],
+                "primaryDocDescription": ["10-K", "10-Q", "8-K"],
+            }
+        )
+
+    monkeypatch.setattr(payloads, "get_company_filings", fake_filings_df)
+    monkeypatch.setattr(payloads, "download_filing", lambda cik, acc, doc: "<html>irrelevant</html>")
+    fake_md = (
+        "## PART I - FINANCIAL INFORMATION\n\n"
+        "## Item 1. Business\n\n"
+        "Apple designs, manufactures, and markets smartphones.\n"
+        "Revenue grew 5% year over year driven by services growth.\n\n"
+        "## Item 7. MD&A\n\n"
+        "Liquidity remained strong with operating cash flow of $110B.\n"
+    )
+    monkeypatch.setattr(payloads, "parse_sec_filing", lambda html, form, *, include_images=False: fake_md)
+
+
+def test_capability_registry_exposes_three_sec_tools() -> None:
+    registry = build_default_capability_registry()
+    names = registry.names()
+    for expected in ("sec_filings", "sec_filing_document", "sec_filing_section"):
+        assert expected in names, f"{expected} should be registered"
+
+
+def test_tool_contracts_registered_for_every_sec_capability() -> None:
+    for expected in ("sec_filings", "sec_filing_document", "sec_filing_section"):
+        assert expected in HOSTED_TOOL_CONTRACTS, f"{expected} missing a tool contract"
+
+
+def test_sec_filings_returns_list_with_edgar_links() -> None:
+    svc = TerraFinAgentService()
+    result = svc.sec_filings("AAPL")
+
+    assert result["ticker"] == "AAPL"
+    assert result["cik"] == 320193
+    assert len(result["filings"]) == 3
+    assert all("documentUrl" in f and "indexUrl" in f for f in result["filings"])
+    # iXBRL viewer wrapper lands on the primary document.
+    assert "sec.gov/ix?doc=" in result["filings"][0]["documentUrl"]
+    assert result["processing"]["sourceVersion"] == "sec-filings-list"
+
+
+def test_sec_filing_document_returns_toc_without_markdown() -> None:
+    svc = TerraFinAgentService()
+    result = svc.sec_filing_document(
+        "AAPL",
+        accession="0000320193-25-000001",
+        primaryDocument="aapl-20241228.htm",
+        form="10-K",
+    )
+
+    assert "markdown" not in result, "document-level tool must NOT return the full body"
+    assert [e["text"] for e in result["toc"]] == [
+        "PART I - FINANCIAL INFORMATION",
+        "Item 1. Business",
+        "Item 7. MD&A",
+    ]
+    assert result["charCount"] > 0
+    assert result["processing"]["sourceVersion"] == "sec-filing-document"
+
+
+def test_sec_filing_section_returns_only_target_section_body() -> None:
+    svc = TerraFinAgentService()
+    result = svc.sec_filing_section(
+        "AAPL",
+        accession="0000320193-25-000001",
+        primaryDocument="aapl-20241228.htm",
+        sectionSlug="item-1-business",
+        form="10-K",
+    )
+
+    assert result["sectionSlug"] == "item-1-business"
+    assert result["sectionTitle"] == "Item 1. Business"
+    assert "Apple designs" in result["markdown"]
+    # MUST stop at the next heading — Item 7 prose must not leak in.
+    assert "Liquidity" not in result["markdown"]
+    assert result["charCount"] == len(result["markdown"])
+
+
+def test_sec_filing_section_raises_lookup_error_for_unknown_slug() -> None:
+    svc = TerraFinAgentService()
+    with pytest.raises(LookupError, match="not found"):
+        svc.sec_filing_section(
+            "AAPL",
+            accession="0000320193-25-000001",
+            primaryDocument="aapl-20241228.htm",
+            sectionSlug="does-not-exist",
+            form="10-K",
+        )
+
+
+def test_sec_filing_section_error_includes_retry_hint_and_full_slug_list() -> None:
+    """The error message must give the LLM everything it needs to retry
+    without giving up: explicit 'do NOT report not exist', the 5 largest
+    slugs with sizes (as a size-based fallback when name matching fails),
+    and the full slug list. Otherwise the agent reads 'not found' as a
+    dead end and tells the user the section doesn't exist — which is
+    exactly the failure mode this fix targets."""
+    svc = TerraFinAgentService()
+    try:
+        svc.sec_filing_section(
+            "AAPL",
+            accession="0000320193-25-000001",
+            primaryDocument="aapl-20241228.htm",
+            sectionSlug="financial-statements",  # agent's common guess
+            form="10-K",
+        )
+    except LookupError as exc:
+        msg = str(exc)
+    else:
+        raise AssertionError("Expected LookupError for unknown slug.")
+
+    # Retry directive — the LLM must not treat this as a dead end.
+    assert "Do NOT report" in msg or "retry" in msg.lower()
+    # 5-largest hint — this is how the agent recovers when Item 7 / Item 8
+    # aren't in the TOC under their expected names.
+    assert "largest" in msg.lower() or "chars" in msg
+    # Full slug list so the agent can self-correct without a second TOC fetch.
+    assert "part-i" in msg
+    assert "item-1-business" in msg
+
+
+def test_sec_filing_section_stops_at_raw_toc_entry_not_next_content_heading() -> None:
+    """Body bounds come from the TOC's own lineIndex list — no scanning markdown
+    for heading-looking text, which would false-match inline `##` tokens."""
+    svc = TerraFinAgentService()
+    # Item 1 Business → next toc entry is Item 7 MD&A; Liquidity section must be absent.
+    result = svc.sec_filing_section(
+        "AAPL",
+        accession="0000320193-25-000001",
+        primaryDocument="aapl-20241228.htm",
+        sectionSlug="item-1-business",
+        form="10-K",
+    )
+    assert "Revenue grew 5%" in result["markdown"]
+    assert "operating cash flow" not in result["markdown"]

tests/agent/test_service.py

@@ -73,6 +73,32 @@ class _FakePrivateDataService:
     def get_market_breadth(self):
         return [{"label": "Advancers", "value": "320", "tone": "#047857"}]
 
+    def get_fear_greed_current(self):
+        return {
+            "score": 42,
+            "rating": "Fear",
+            "previousClose": 45,
+            "oneWeekAgo": 50,
+            "oneMonthAgo": 38,
+        }
+
+    def get_top_companies(self):
+        return [
+            {"symbol": "AAPL", "name": "Apple", "marketCap": 3_200_000_000_000},
+            {"symbol": "MSFT", "name": "Microsoft", "marketCap": 3_100_000_000_000},
+        ]
+
+    def get_trailing_forward_pe(self):
+        return {
+            "date": "2026-04-15",
+            "summary": {"trailing_forward_pe_spread": 2.1},
+            "coverage": {"usable": 480, "requested": 500},
+            "history": [
+                {"date": "2026-04-14", "spread": 2.0},
+                {"date": "2026-04-15", "spread": 2.1},
+            ],
+        }
+
     def get_calendar_events(self, *, year: int, month: int, categories=None, limit=None):
         _ = categories, limit
         return [
@@ -150,8 +176,15 @@ def test_market_snapshot_and_calendar_include_processing(monkeypatch) -> None:
     calendar = service.calendar_events(year=2026, month=4, categories="macro")
 
     assert snapshot["processing"]["resolvedDepth"] == "recent"
-    assert snapshot["market_breadth"][0]["label"] == "Advancers"
-    assert snapshot["watchlist"][0]["symbol"] == "AAPL"
+    # market_breadth and watchlist are now standalone capabilities —
+    # `market_snapshot` is per-ticker only (was mixing whole-market state
+    # with per-ticker view, audit: DA Med-7).
+    assert "market_breadth" not in snapshot
+    assert "watchlist" not in snapshot
+    breadth = service.market_breadth()
+    watchlist = service.watchlist()
+    assert breadth["metrics"][0]["label"] == "Advancers"
+    assert watchlist["items"][0]["symbol"] == "AAPL"
     assert calendar["processing"]["resolvedDepth"] == "full"
     assert calendar["count"] == 1
 
@@ -176,3 +209,198 @@ def test_economic_normalizes_human_friendly_indicator_aliases(monkeypatch) -> No
 
     assert "Federal Funds Effective Rate" in payload["indicators"]
     assert "SOMA" in payload["indicators"]
+
+
+# ---------------------------------------------------------------------------
+# DA-audit mismatch fixes — the agent must see the same payload shape the
+# frontend widgets/routes render, so questions like "what's the Fear & Greed
+# score?" or "what's the S&P 500 implied growth?" answer the same way whether
+# the user looks at the widget or asks the agent. Before these fixes, agent
+# had either no tool (widgets invisible to agent) or a cherry-picked subset
+# (divergent between UI and agent).
+# ---------------------------------------------------------------------------
+
+
+def test_fear_greed_returns_full_widget_payload(monkeypatch) -> None:
+    monkeypatch.setattr(agent_service, "get_private_data_service", lambda: _FakePrivateDataService())
+    service = agent_service.TerraFinAgentService()
+
+    payload = service.fear_greed()
+
+    assert payload["score"] == 42
+    assert payload["rating"] == "Fear"
+    assert payload["previousClose"] == 45
+    assert payload["oneWeekAgo"] == 50
+    assert payload["oneMonthAgo"] == 38
+    assert payload["processing"]["resolvedDepth"] == "full"
+
+
+def test_top_companies_returns_full_list(monkeypatch) -> None:
+    monkeypatch.setattr(agent_service, "get_private_data_service", lambda: _FakePrivateDataService())
+    service = agent_service.TerraFinAgentService()
+
+    payload = service.top_companies()
+
+    assert payload["count"] == 2
+    assert payload["companies"][0]["symbol"] == "AAPL"
+
+
+def test_market_regime_mirrors_route_placeholder() -> None:
+    """Route returns a placeholder; agent mirrors it verbatim so the two
+    views never diverge (even for placeholder content)."""
+    service = agent_service.TerraFinAgentService()
+
+    payload = service.market_regime()
+
+    assert "selective risk-taking" in payload["summary"]
+    assert payload["confidence"] == "low"
+    assert len(payload["signals"]) == 3
+
+
+def test_trailing_forward_pe_returns_dashboard_shape(monkeypatch) -> None:
+    monkeypatch.setattr(agent_service, "get_private_data_service", lambda: _FakePrivateDataService())
+    service = agent_service.TerraFinAgentService()
+
+    payload = service.trailing_forward_pe()
+
+    assert payload["date"] == "2026-04-15"
+    assert payload["latestValue"] == 2.1
+    assert payload["usableCount"] == 480
+    assert payload["requestedCount"] == 500
+    assert len(payload["history"]) == 2
+
+
+def test_market_breadth_standalone_returns_metrics_list(monkeypatch) -> None:
+    """Was bundled inside market_snapshot; now a standalone tool so agent
+    and the MarketBreadthCard widget query the same data (DA Med-7)."""
+    monkeypatch.setattr(agent_service, "get_private_data_service", lambda: _FakePrivateDataService())
+    service = agent_service.TerraFinAgentService()
+
+    payload = service.market_breadth()
+
+    assert payload["metrics"][0]["label"] == "Advancers"
+
+
+def test_watchlist_standalone_returns_items_list(monkeypatch) -> None:
+    monkeypatch.setattr(agent_service, "get_watchlist_service", lambda: _FakeWatchlistService())
+    service = agent_service.TerraFinAgentService()
+
+    payload = service.watchlist()
+
+    assert payload["count"] == 1
+    assert payload["items"][0]["symbol"] == "AAPL"
+
+
+def test_market_snapshot_no_longer_bundles_whole_market_widgets(monkeypatch) -> None:
+    """Regression guard for DA Med-7 fix: market_snapshot is per-ticker
+    only. The temptation to re-bundle market-wide widgets for
+    "convenience" is what caused the original UI↔agent divergence —
+    widgets refresh on their own cadence while market_snapshot bundled a
+    point-in-time copy, so the agent's number could lag the UI's."""
+    monkeypatch.setattr(agent_service, "DataFactory", _FakeDataFactory)
+    service = agent_service.TerraFinAgentService()
+
+    snapshot = service.market_snapshot("TEST")
+
+    assert "market_breadth" not in snapshot
+    assert "watchlist" not in snapshot
+
+
+def test_portfolio_exposes_top_holdings_matching_route_sort(monkeypatch) -> None:
+    """Route pre-computes `topHoldings` (top 8 by % of Portfolio). Agent
+    must return the same list so the UI treemap and the agent agree on
+    which positions are the "top" ones (DA Med-9)."""
+    import pandas as _pd
+
+    class _FakePortfolio:
+        def __init__(self) -> None:
+            self.df = _pd.DataFrame(
+                [
+                    {"Stock": "AAPL", "% of Portfolio": 25.0, "Recent Activity": "Hold", "Updated": "2026-03-31"},
+                    {"Stock": "MSFT", "% of Portfolio": 15.0, "Recent Activity": "Buy", "Updated": "2026-03-31"},
+                    {"Stock": "NVDA", "% of Portfolio": 10.0, "Recent Activity": "Buy", "Updated": "2026-03-31"},
+                ]
+            )
+            self.info = {"guru": "buffett"}
+
+    monkeypatch.setattr(agent_service, "get_portfolio_data", lambda _g: _FakePortfolio())
+    service = agent_service.TerraFinAgentService()
+
+    payload = service.portfolio("buffett")
+
+    assert payload["count"] == 3
+    assert len(payload["topHoldings"]) == 3
+    # Sorted by % of Portfolio descending.
+    assert payload["topHoldings"][0]["Stock"] == "AAPL"
+    assert payload["topHoldings"][1]["Stock"] == "MSFT"
+
+
+def test_valuation_passes_through_full_dcf_and_reverse_dcf_payloads(monkeypatch) -> None:
+    """Regression for DA High-1 / High-2: agent must see the same
+    DCFValuationResponse shape the user sees in DcfValuationPanel —
+    scenarios, sensitivity, methods, rateCurve, dataQuality, not just
+    a cherry-picked 4-field subset."""
+    dcf_full = {
+        "status": "ready",
+        "currentIntrinsicValue": 120.0,
+        "upsidePct": 8.0,
+        "assumptions": {"discountRate": 0.1},
+        "scenarios": {"base": {}, "bull": {}, "bear": {}},
+        "sensitivity": [[1.1, 1.2], [0.9, 1.0]],
+        "methods": ["dcf", "pe"],
+        "rateCurve": [{"year": 2025, "rate": 0.05}],
+        "dataQuality": {"grade": "A"},
+        "warnings": [],
+    }
+    reverse_full = {
+        "status": "ready",
+        "impliedGrowthPct": 10.5,
+        "modelPrice": 115.0,
+        "projectedCashFlows": [10, 11, 12],
+        "growthProfile": {"terminalGrowth": 0.025},
+        "priceToCashFlowMultiple": 12.0,
+        "terminalValue": 1000.0,
+        "terminalGrowthPct": 2.5,
+        "discountSpreadPct": 3.0,
+        "rateCurve": [{"year": 2025, "rate": 0.05}],
+        "dataQuality": {"grade": "A"},
+        "warnings": [],
+    }
+    monkeypatch.setattr(agent_service, "build_stock_dcf_payload", lambda _t: dcf_full)
+    monkeypatch.setattr(agent_service, "build_stock_reverse_dcf_payload", lambda _t: reverse_full)
+    monkeypatch.setattr(
+        agent_service,
+        "build_company_info_payload",
+        lambda _t: {"currentPrice": 110.0, "trailingPE": 22.0, "forwardPE": 20.0, "trailingEps": 5.0},
+    )
+
+    class _FakeDF:
+        def __init__(self) -> None:
+            self._data = {"TotalStockholdersEquity": [2_000_000_000], "SharesOutstanding": [20_000_000]}
+            self.columns = list(self._data.keys())
+            self.empty = False
+
+        def __getitem__(self, col):
+            return type("_S", (), {"iloc": type("_I", (), {"__getitem__": lambda _, idx: self._data[col][idx]})()})()
+
+    class _FactoryStub:
+        def __init__(self, *args, **kwargs) -> None:
+            _ = args, kwargs
+
+        def get_corporate_data(self, *args, **kwargs):
+            _ = args, kwargs
+            return _FakeDF()
+
+    monkeypatch.setattr(agent_service, "DataFactory", _FactoryStub)
+    service = agent_service.TerraFinAgentService()
+
+    payload = service.valuation("AAPL")
+
+    # Full DCF payload preserved, not cherry-picked.
+    assert payload["dcf"]["scenarios"]["base"] == {}
+    assert payload["dcf"]["sensitivity"] == [[1.1, 1.2], [0.9, 1.0]]
+    assert payload["dcf"]["dataQuality"]["grade"] == "A"
+    # Full reverse DCF payload preserved.
+    assert payload["reverseDcf"]["projectedCashFlows"] == [10, 11, 12]
+    assert payload["reverseDcf"]["terminalGrowthPct"] == 2.5
+    assert payload["reverseDcf"]["priceToCashFlowMultiple"] == 12.0

tests/agent/test_tools.py

@@ -128,6 +128,67 @@ class _FakeService:
             "processing": _processing(),
         }
 
+    def sec_filings(self, ticker: str) -> dict[str, object]:
+        return {"ticker": ticker, "cik": 1, "forms": ["10-K"], "filings": [], "processing": _processing()}
+
+    def sec_filing_document(
+        self, ticker: str, accession: str, primaryDocument: str, *, form: str = "10-Q"
+    ) -> dict[str, object]:
+        return {
+            "ticker": ticker,
+            "accession": accession,
+            "primaryDocument": primaryDocument,
+            "toc": [],
+            "charCount": 0,
+            "indexUrl": "",
+            "documentUrl": "",
+            "processing": _processing(),
+        }
+
+    def sec_filing_section(
+        self,
+        ticker: str,
+        accession: str,
+        primaryDocument: str,
+        sectionSlug: str,
+        *,
+        form: str = "10-Q",
+    ) -> dict[str, object]:
+        return {
+            "ticker": ticker,
+            "accession": accession,
+            "sectionSlug": sectionSlug,
+            "sectionTitle": "stub",
+            "markdown": "",
+            "charCount": 0,
+            "documentUrl": "",
+            "processing": _processing(),
+        }
+
+    def fear_greed(self) -> dict[str, object]:
+        return {"score": 50, "rating": "Neutral", "processing": _processing()}
+
+    def sp500_dcf(self) -> dict[str, object]:
+        return {"status": "ready", "currentIntrinsicValue": 5000.0, "processing": _processing()}
+
+    def beta_estimate(self, ticker: str) -> dict[str, object]:
+        return {"symbol": ticker, "beta": 1.0, "adjustedBeta": 1.0, "rSquared": 0.5, "processing": _processing()}
+
+    def top_companies(self) -> dict[str, object]:
+        return {"companies": [], "count": 0, "processing": _processing()}
+
+    def market_regime(self) -> dict[str, object]:
+        return {"summary": "stub", "confidence": "low", "signals": [], "processing": _processing()}
+
+    def trailing_forward_pe(self) -> dict[str, object]:
+        return {"date": "2026-04-01", "latestValue": 0.0, "history": [], "processing": _processing()}
+
+    def market_breadth(self) -> dict[str, object]:
+        return {"metrics": [], "processing": _processing()}
+
+    def watchlist(self) -> dict[str, object]:
+        return {"items": [], "count": 0, "processing": _processing()}
+
 
 class _RetryingFakeService(_FakeService):
     def __init__(self) -> None:
@@ -283,6 +344,69 @@ def test_run_tool_retries_with_repaired_macro_alias_before_exposing_error() -> N
     assert service.calls == ["NASDAQ COMPOSITE", "Nasdaq"]
 
 
+class _SecFilingSlugNotFoundService(_FakeService):
+    """Service fake where sec_filing_section raises the exact LookupError
+    shape the real service emits when the slug isn't in the TOC."""
+
+    def sec_filing_section(
+        self,
+        ticker: str,
+        accession: str,
+        primaryDocument: str,
+        sectionSlug: str,
+        *,
+        form: str = "10-Q",
+    ) -> dict[str, object]:
+        raise LookupError(
+            f"Section '{sectionSlug}' not found. "
+            "Do NOT report 'section doesn't exist' — retry this tool with one of the available "
+            "slugs. The 5 largest sections in this filing are: "
+            "item-6-reserved (213068 chars, 'Item 6. Reserved.'), "
+            "item-1-business (180091 chars, 'Item 1. Business.'), "
+            "part-ii (218055 chars, 'Part II'), "
+            "part-i (185218 chars, 'PART I'), "
+            "item-3-legal-proceedings (4203 chars, 'Item 3. Legal Proceedings.'). "
+            "All 7 available slugs: part-i, item-1-business, item-2-properties, "
+            "item-3-legal-proceedings, part-ii, item-5-market, item-6-reserved"
+        )
+
+
+def test_run_tool_classifies_sec_filing_section_bad_slug_as_retryable() -> None:
+    """The `sec_filing_section` service raises a rich LookupError with
+    the full TOC slug list and explicit retry guidance. Without the
+    classifier recognizing it, the exception propagates raw — the model
+    sees an unstructured error, paraphrases it, and gives up instead
+    of retrying with a valid slug (the exact ZETA 10-K failure mode).
+
+    Regression for QA-identified CRITICAL #2."""
+    adapter = _adapter(service=_SecFilingSlugNotFoundService())
+    session = adapter.runtime.create_session(DEFAULT_HOSTED_AGENT_NAME, session_id="tool:sec-slug-not-found")
+
+    result = adapter.run_tool(
+        session.session.session_id,
+        "sec_filing_section",
+        {
+            "ticker": "ZETA",
+            "accession": "0000000000-26-000000",
+            "primaryDocument": "zeta.htm",
+            "sectionSlug": "financial-statements",  # bad guess, not in TOC
+            "form": "10-K",
+        },
+    )
+
+    assert result.is_error is True
+    assert result.retryable is True
+    assert result.error_code == "sec_filing_section_slug_not_found"
+    assert result.payload["accepted"] is False
+    assert result.payload["error"]["retryable"] is True
+    # Model hint must tell the LLM to retry and include the full slug list.
+    hint = result.payload["error"]["modelHint"]
+    assert "DO NOT tell the user" in hint
+    assert "item-6-reserved" in hint  # largest slug surfaced
+    assert "part-ii" in hint  # Part II reference for 10-K earnings guidance
+    assert "MD&A" in hint or "earnings" in hint  # earnings/MD&A hint
+
+
 def test_run_tool_returns_internal_retryable_error_result_for_symbol_resolution_failures() -> None:
     adapter = _adapter(service=_UnrepairableRecoverableErrorService())
     session = adapter.runtime.create_session(DEFAULT_HOSTED_AGENT_NAME, session_id="tool:recoverable-error")

tests/interface/test_stock_filings_api.py

@@ -0,0 +1,146 @@
+import pandas as pd
+import pytest
+from fastapi import HTTPException
+
+from TerraFin.interface.stock import payloads
+
+
+def _stub_filings_df() -> pd.DataFrame:
+    return pd.DataFrame(
+        {
+            "form": ["10-K", "10-Q", "10-Q/A", "8-K", "DEF 14A"],
+            "accessionNumber": ["0000320193-25-000001", "0000320193-24-000010", "0000320193-24-000008", "0000320193-24-000007", "0000320193-24-000006"],
+            "filingDate": ["2025-02-02", "2024-11-02", "2024-08-10", "2024-08-02", "2024-05-01"],
+            "reportDate": ["2024-12-28", "2024-09-28", "2024-06-28", "2024-08-01", ""],
+            "primaryDocument": ["aapl-20241228.htm", "aapl-20240928.htm", "aapl-20240628a.htm", "aapl-8k.htm", "def14a.htm"],
+            "primaryDocDescription": ["10-K", "10-Q", "10-Q/A", "8-K", "DEF 14A"],
+        }
+    )
+
+
+@pytest.fixture
+def cik_mapping(monkeypatch):
+    monkeypatch.setattr(payloads, "get_ticker_to_cik_dict_cached", lambda: {"AAPL": 320193})
+
+
+def test_build_filings_list_payload_returns_filings_with_edgar_links(monkeypatch, cik_mapping) -> None:
+    monkeypatch.setattr(payloads, "get_company_filings", lambda cik, include_8k=False: _stub_filings_df())
+
+    result = payloads.build_filings_list_payload("AAPL")
+
+    assert result["ticker"] == "AAPL"
+    assert result["cik"] == 320193
+    assert len(result["filings"]) == 5
+    # Newest-first ordering preserved.
+    assert result["filings"][0]["filingDate"] == "2025-02-02"
+    # documentUrl uses SEC's inline-XBRL viewer so the click opens the rendered
+    # filing (styled, navigable) rather than the raw HTML. indexUrl still points
+    # at the directory for debugging / file-level access.
+    first = result["filings"][0]
+    assert first["indexUrl"] == "https://www.sec.gov/Archives/edgar/data/0000320193/000032019325000001/"
+    assert first["documentUrl"] == (
+        "https://www.sec.gov/ix?doc=/Archives/edgar/data/0000320193/000032019325000001/aapl-20241228.htm"
+    )
+
+
+def test_build_filings_list_payload_prioritizes_forms_for_frontend_dropdown(monkeypatch, cik_mapping) -> None:
+    monkeypatch.setattr(payloads, "get_company_filings", lambda cik, include_8k=False: _stub_filings_df())
+
+    result = payloads.build_filings_list_payload("AAPL")
+
+    # Frontend dropdown gets 10-K first, 10-Q next, amendments grouped with parent
+    # priority, other forms at the end. Amendment appears after its parent form.
+    assert result["forms"][:4] == ["10-K", "10-Q", "10-Q/A", "8-K"]
+    assert "DEF 14A" in result["forms"]
+
+
+def test_build_filings_list_payload_surfaces_latestByForm_even_when_buried(monkeypatch, cik_mapping) -> None:
+    """Agents otherwise scan the flat list and give up when 8-Ks cluster on top.
+    Verify `latestByForm` offers a direct lookup regardless of chronological order."""
+    import pandas as pd
+
+    # 8-Ks cluster on top in chronological order — 10-K is position 2, 10-Q position 3.
+    eight_k_heavy = pd.DataFrame(
+        {
+            "form": ["8-K", "8-K", "10-K", "8-K", "10-Q"],
+            "accessionNumber": ["a1", "a2", "a3", "a4", "a5"],
+            "filingDate": ["2026-04-10", "2026-04-02", "2026-02-05", "2026-02-04", "2025-10-30"],
+            "reportDate": ["2026-04-07", "2026-03-30", "2025-12-31", "2026-02-04", "2025-09-30"],
+            "primaryDocument": ["a1.htm", "a2.htm", "a3.htm", "a4.htm", "a5.htm"],
+            "primaryDocDescription": ["8-K", "8-K", "10-K", "8-K", "10-Q"],
+        }
+    )
+    monkeypatch.setattr(payloads, "get_company_filings", lambda cik, include_8k=False: eight_k_heavy)
+
+    result = payloads.build_filings_list_payload("AAPL")
+
+    latest = result["latestByForm"]
+    assert latest["10-K"]["accession"] == "a3"
+    assert latest["10-K"]["primaryDocument"] == "a3.htm"
+    assert latest["10-Q"]["accession"] == "a5"
+    assert latest["8-K"]["accession"] == "a1", "latestByForm must pick the newest 8-K (a1), not some other one"
+
+
+def test_build_filings_list_payload_raises_for_unknown_ticker(monkeypatch) -> None:
+    monkeypatch.setattr(payloads, "get_ticker_to_cik_dict_cached", lambda: {})
+
+    with pytest.raises(HTTPException) as exc:
+        payloads.build_filings_list_payload("BOGUS")
+    assert exc.value.status_code == 404
+
+
+def test_build_filings_list_payload_handles_empty_upstream(monkeypatch, cik_mapping) -> None:
+    monkeypatch.setattr(payloads, "get_company_filings", lambda cik, include_8k=False: pd.DataFrame())
+
+    result = payloads.build_filings_list_payload("AAPL")
+    assert result["filings"] == []
+    assert result["forms"] == []
+
+
+def test_build_filing_document_payload_returns_markdown_and_camelcase_toc(monkeypatch, cik_mapping) -> None:
+    monkeypatch.setattr(payloads, "download_filing", lambda cik, acc, doc: "<html>ignored</html>")
+
+    fake_md = "## PART I\n\nbody\n\n## PART II\n"
+    monkeypatch.setattr(payloads, "parse_sec_filing", lambda html, form, *, include_images=False: fake_md)
+
+    result = payloads.build_filing_document_payload(
+        "AAPL",
+        accession="0000320193-25-000001",
+        primary_document="aapl-20241228.htm",
+        form="10-K",
+    )
+
+    assert result["ticker"] == "AAPL"
+    assert result["accession"] == "000032019325000001"
+    assert result["markdown"] == fake_md
+    assert result["charCount"] == len(fake_md)
+    # Every TOC entry must expose camelCase keys consistent with the rest of the API.
+    assert all({"level", "text", "lineIndex", "slug", "charCount"}.issubset(e) for e in result["toc"])
+    assert [e["text"] for e in result["toc"]] == ["PART I", "PART II"]
+    # documentUrl opens the iXBRL viewer, not the raw archive path.
+    assert result["documentUrl"].startswith("https://www.sec.gov/ix?doc=/Archives/edgar/data/")
+    assert result["documentUrl"].endswith("aapl-20241228.htm")
+
+
+def test_build_filing_document_payload_requires_primary_document(monkeypatch, cik_mapping) -> None:
+    with pytest.raises(HTTPException) as exc:
+        payloads.build_filing_document_payload("AAPL", accession="0000320193-25-000001", primary_document="")
+    assert exc.value.status_code == 400
+
+
+def test_build_filing_document_payload_propagates_unsupported_form_as_422(monkeypatch, cik_mapping) -> None:
+    monkeypatch.setattr(payloads, "download_filing", lambda cik, acc, doc: "<html></html>")
+
+    def bad_parse(*_args, **_kwargs):
+        raise ValueError("Filing form 'DEF 14A' not supported.")
+
+    monkeypatch.setattr(payloads, "parse_sec_filing", bad_parse)
+
+    with pytest.raises(HTTPException) as exc:
+        payloads.build_filing_document_payload(
+            "AAPL",
+            accession="0000320193-25-000001",
+            primary_document="def14a.htm",
+            form="DEF 14A",
+        )
+    assert exc.value.status_code == 422