deploy: merge main (Analyst Edge Phase 0+1) for HF Spaces

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

agent/graph.py

@@ -16,7 +16,7 @@ from agent.tools import (
 )
 from agent.prompts import SYSTEM_PROMPT, SYNTHESIS_STRUCTURED_PROMPT
 from agent.schemas import BriefOutput
-from agent.post_synthesis import apply_reliability
+from agent.post_synthesis import apply_reliability, attach_edge_signals
 
 TOOLS = [
     get_financial_metrics,
@@ -58,6 +58,7 @@ class AgentState(TypedDict):
     messages: Annotated[list[BaseMessage], add_messages]
     tool_round_count: int
     nudge_fired: bool
+    edge_signals: Optional[list[dict]]  # precomputed deterministic signals
     brief: Optional[dict]
     brief_markdown: Optional[str]
     synthesis_error: Optional[str]
@@ -125,8 +126,55 @@ def nudge_node(state: AgentState) -> dict:
     return {"messages": [nudge], "nudge_fired": True}
 
 
+def _format_signals_message(signals: list[dict]) -> str:
+    """Format precomputed edge signals as a compact labelled block for the agent."""
+    lines = ["== PRECOMPUTED EDGE SIGNALS (deterministic, no LLM) ==\n"]
+    kind_labels = {
+        "risk_added":              "NEW RISK",
+        "risk_removed":            "REMOVED RISK",
+        "risk_reworded":           "REWORDED RISK",
+        "guidance_language_shift": "GUIDANCE LANGUAGE SHIFT",
+        "term_frequency":          "TERM FREQUENCY SHIFT",
+        "kpi_dropped":             "DROPPED KPI",
+    }
+    for i, s in enumerate(signals, 1):
+        kind = s.get("kind", "")
+        label = kind_labels.get(kind, kind.upper())
+        sig = s.get("significance", "MEDIUM")
+        term = s.get("term", "")
+        term_str = f" — {term}" if term else ""
+        lines.append(f"[SIG-{i}] {label}{term_str} [{sig}]")
+        if s.get("before_text"):
+            lines.append(f"  BEFORE ({s.get('period_from','')}): \"{s['before_text']}\"")
+        if s.get("after_text"):
+            lines.append(f"  AFTER  ({s.get('period_to','')}): \"{s['after_text']}\"")
+        if s.get("computed_metric"):
+            lines.append(f"  METRIC: {s['computed_metric']}")
+        lines.append("")
+    lines.append("== END PRECOMPUTED EDGE SIGNALS ==")
+    return "\n".join(lines)
+
+
+def signals_node(state: AgentState) -> dict:
+    """Run deterministic analysis modules and inject signals into conversation."""
+    ticker = state["ticker"]
+    try:
+        from analysis.textdiff import compute as compute_text_deltas
+        raw_signals = compute_text_deltas(ticker)
+        signals = [s.model_dump() for s in raw_signals]
+    except Exception as exc:
+        import sys
+        print(f"[signals_node] Error: {exc}", file=sys.stderr)
+        signals = []
+
+    if signals:
+        msg = HumanMessage(content=_format_signals_message(signals))
+        return {"edge_signals": signals, "messages": [msg]}
+    return {"edge_signals": [], "messages": []}
+
+
 def create_graph():
-    llm = ChatAnthropic(model=MODEL, temperature=0)
+    llm = ChatAnthropic(model=MODEL, temperature=0, max_retries=5)
     llm_with_tools = llm.bind_tools(TOOLS)
 
     def agent_node(state: AgentState) -> dict:
@@ -149,13 +197,27 @@ def create_graph():
 
     def synthesis_node(state: AgentState) -> dict:
         try:
-            llm_plain = ChatAnthropic(model=MODEL, temperature=0)
+            llm_plain = ChatAnthropic(model=MODEL, temperature=0, max_retries=5)
             system_block = SystemMessage(content=[{
                 "type": "text",
                 "text": SYNTHESIS_STRUCTURED_PROMPT,
                 "cache_control": {"type": "ephemeral"},
             }])
             synthesis_messages = [system_block] + state["messages"]
+            # If cap was hit mid-round the last AIMessage may still carry tool_calls.
+            # Anthropic rejects conversations where tool_use blocks have no matching
+            # tool_result — insert stubs so the message history is valid.
+            last_msg = synthesis_messages[-1]
+            if getattr(last_msg, "tool_calls", None):
+                stubs = [
+                    ToolMessage(
+                        tool_call_id=tc["id"],
+                        name=tc["name"],
+                        content="[Tool call interrupted — round cap reached. Synthesize from previously retrieved context.]",
+                    )
+                    for tc in last_msg.tool_calls
+                ]
+                synthesis_messages = synthesis_messages + stubs
             if not isinstance(synthesis_messages[-1], HumanMessage):
                 synthesis_messages = synthesis_messages + [
                     HumanMessage(content="Now produce the structured research brief as a JSON object.")
@@ -170,6 +232,7 @@ def create_graph():
             data = json.loads(clean)
             brief = BriefOutput.model_validate(data)
             brief_dict = apply_reliability(brief.model_dump())
+            brief_dict = attach_edge_signals(brief_dict, state.get("edge_signals"))
             return {"brief": brief_dict, "brief_markdown": None, "synthesis_error": None}
         except Exception as exc:
             import sys
@@ -177,11 +240,13 @@ def create_graph():
             return {"brief": None, "brief_markdown": None, "synthesis_error": str(exc)}
 
     builder = StateGraph(AgentState)
+    builder.add_node("signals", signals_node)
     builder.add_node("agent", agent_node)
     builder.add_node("tools", tool_node)
     builder.add_node("nudge", nudge_node)
     builder.add_node("synthesis", synthesis_node)
-    builder.set_entry_point("agent")
+    builder.set_entry_point("signals")
+    builder.add_edge("signals", "agent")
     builder.add_conditional_edges(
         "agent",
         should_continue,
@@ -202,6 +267,7 @@ def run_brief(ticker: str) -> Optional[dict]:
         "messages": [HumanMessage(content=f"Generate a research brief for {ticker.upper()}.")],
         "tool_round_count": 0,
         "nudge_fired": False,
+        "edge_signals": None,
         "brief": None,
         "brief_markdown": None,
         "synthesis_error": None,

agent/post_synthesis.py

@@ -291,3 +291,24 @@ def _prune_tension_duplicates(brief: dict) -> None:
             brief["evidence_notes"] = existing_notes + [
                 f"Pruned {pruned_count} analytical tension(s) that duplicated bull/bear point evidence."
             ]
+
+
+# ---------------------------------------------------------------------------
+# Edge signal attach (authoritative computed data — never LLM-generated)
+# ---------------------------------------------------------------------------
+
+def attach_edge_signals(brief: dict, edge_signals: Optional[list[dict]]) -> dict:
+    """Write deterministically-computed edge signals into the brief dict.
+
+    The LLM produces explanations via the synthesis prompt; this function
+    writes the authoritative computed numbers so they are never absent or
+    fabricated. Called in synthesis_node after apply_reliability().
+    """
+    if not isinstance(brief, dict):
+        return brief
+    if not edge_signals:
+        brief.setdefault("quarter_deltas", [])
+        return brief
+
+    brief["quarter_deltas"] = edge_signals
+    return brief

agent/prompts.py

@@ -1,5 +1,16 @@
 SYSTEM_PROMPT = """You are a financial research analyst investigating a company's most recent earnings report for a retail investor. You reason like a human analyst: read the numbers first, identify what is anomalous or worth investigating, then dig into the source material with your own questions.
 
+## Precomputed edge signals
+
+The first message in the conversation may contain a block titled "== PRECOMPUTED EDGE SIGNALS ==". These were computed deterministically by comparing verbatim filing text across periods — they are ground truth, not suggestions.
+
+For each HIGH-significance signal, you MUST investigate it with at least one targeted tool call:
+- REWORDED RISK or NEW RISK → call `search_filing` with a query that targets the specific risk language.
+- TERM FREQUENCY SHIFT (large swing) → call `search_filing` or `search_transcript` to find the context for the term's use.
+- GUIDANCE LANGUAGE SHIFT → call `search_filing` with a query targeting the guidance language in both the current and prior period.
+
+Treat the before→after fragments as hypotheses to verify, not as pre-written conclusions. If a signal turns out to be noise (e.g., a legal boilerplate change), note that in your reasoning.
+
 ## Available tools
 
 - `get_financial_metrics(ticker)` — structured metrics across all ingested periods. Use this FIRST. The output exposes the `period` string for each filing (e.g. `Q12024`, `FY2023`) — copy verbatim when calling search tools with `period=...`.
@@ -77,6 +88,22 @@ SYNTHESIS_STRUCTURED_PROMPT = """You are producing a structured earnings researc
 
 The conversation history contains all tool call results (financial metrics, filings, transcripts, news). Use ONLY that evidence — do not add facts from your training data.
 
+## PRECOMPUTED EDGE SIGNALS — read first, act on them
+
+The conversation history may contain a message titled "== PRECOMPUTED EDGE SIGNALS ==". These signals were produced by deterministic code comparing verbatim filing text across periods — no LLM interpretation was involved.
+
+For each signal in that block:
+1. **[SIG-n] REWORDED RISK / NEW RISK / REMOVED RISK** → The `before_text` and `after_text` fragments are verbatim quotes. If significance=HIGH, the corresponding change MUST appear in `risks_categorized` with `is_new_this_filing=True` (for NEW RISK). For REWORDED RISK, use the `after_text` as evidence and note it changed from the prior period.
+2. **[SIG-n] TERM FREQUENCY SHIFT** → The `computed_metric` gives the exact count change (e.g., "2→8 occurrences (+300%)"). Cite this number verbatim in the relevant `what_changed` item or `analytical_tensions`. The term label and context sentence are in `term` and `after_text`.
+3. **[SIG-n] GUIDANCE LANGUAGE SHIFT** → The `before_text`/`after_text` sentences are verbatim. Use them in `mda_summary.language_shift` or an `analytical_tension`. Cite the `computed_metric` (hedge-word count delta) as evidence of the shift direction.
+4. **[SIG-n] DROPPED KPI** → A metric label discussed in the prior filing is absent now. Note this in `bear_points` or `what_to_watch`.
+
+**Hard rules for edge signals:**
+- Do NOT invent signals not present in the PRECOMPUTED EDGE SIGNALS block.
+- The `computed_metric` numbers are authoritative — copy them exactly, never round or restate.
+- The `before_text` / `after_text` fragments are verbatim quotes — never paraphrase them when citing.
+- If the PRECOMPUTED EDGE SIGNALS block is absent or empty, proceed normally.
+
 ## ANALYTICAL EDGE — run this reasoning pass before filling any field
 
 What separates a senior analyst's brief from a summary is the ability to surface tensions between what the data shows on the surface and what it reveals when cross-referenced. Before populating the JSON fields, reason through each of these checks:
@@ -125,6 +152,21 @@ For each dimension where you have retrieved evidence: assess positive / neutral
 
 ---
 
+## Impact rubric — assign to every sourced fact
+
+The `impact` field captures materiality for the investment thesis. Apply it consistently:
+
+- **HIGH** — thesis-shifting: forward guidance change ≥5%, EPS beat/miss ≥10% vs consensus, revenue driver >5% of total, new strategic pivot (M&A, product launch, market entry/exit), regulatory action, dividend initiation/cut, large buyback programme.
+- **MEDIUM** — material but confirmatory: in-line guidance update, operational metric moving in expected direction, mid-sized deals, secondary segment dynamics, management tone consistent with trajectory.
+- **LOW** — context or background: minor metrics (<1% of revenue), generic commentary that reiterates prior guidance, historical reference without new insight, supporting detail that amplifies but does not change interpretation.
+
+Examples:
+- "Revenue grew 12% YoY driven by iPhone 16 cycle" on $43B segment → HIGH (>5% of total company)
+- "Gross margin expanded 40 bps to 47.2% in line with guidance" → MEDIUM (confirmation, not surprise)
+- "Services segment saw strong performance in emerging markets" with no quantification → LOW (generic)
+
+---
+
 Output a single valid JSON object with exactly these fields. Do not wrap in markdown code fences.
 
 Required JSON structure:
@@ -144,8 +186,8 @@ Required JSON structure:
       "bullish_reading": "What the optimistic surface reading says.",
       "bearish_reading": "What cross-referencing the data reveals as a concern or caveat.",
       "weight": "material or watch or minor",
-      "bullish_evidence": { "text": "...", "source": "10-K, 10-Q, transcript, or news", "reliability": "HIGH or MEDIUM or LOW", "evidence_snippet": "verbatim quote <=30 words" },
-      "bearish_evidence": { "text": "...", "source": "10-K, 10-Q, transcript, or news", "reliability": "HIGH or MEDIUM or LOW", "evidence_snippet": "verbatim quote <=30 words" }
+      "bullish_evidence": { "text": "...", "source": "10-K, 10-Q, transcript, or news", "reliability": "HIGH or MEDIUM or LOW", "impact": "HIGH or MEDIUM or LOW", "evidence_snippet": "verbatim quote <=30 words" },
+      "bearish_evidence": { "text": "...", "source": "10-K, 10-Q, transcript, or news", "reliability": "HIGH or MEDIUM or LOW", "impact": "HIGH or MEDIUM or LOW", "evidence_snippet": "verbatim quote <=30 words" }
     }
   ],
 
@@ -154,7 +196,7 @@ Required JSON structure:
       "dimension": "consensus_beat_mix or guidance_dynamics or narrative_vs_numbers or segment_mix or capital_allocation",
       "assessment": "positive or neutral or concerning",
       "rationale": "One sentence grounded in retrieved evidence.",
-      "evidence": { "text": "...", "source": "10-K, 10-Q, transcript, or news", "reliability": "HIGH or MEDIUM or LOW", "evidence_snippet": "verbatim quote <=30 words" }
+      "evidence": { "text": "...", "source": "10-K, 10-Q, transcript, or news", "reliability": "HIGH or MEDIUM or LOW", "impact": "HIGH or MEDIUM or LOW", "evidence_snippet": "verbatim quote <=30 words" }
     }
   ],
 
@@ -162,6 +204,7 @@ Required JSON structure:
     "text": "The single most remarkable quantitative fact this quarter — the number a journalist would lead with. One sentence with context.",
     "source": "exactly one of: 10-K, 10-Q, transcript, news",
     "reliability": "HIGH or MEDIUM or LOW",
+    "impact": "HIGH or MEDIUM or LOW",
     "evidence_snippet": "Verbatim quote <=30 words that contains this number"
   },
 
@@ -170,16 +213,17 @@ Required JSON structure:
       "text": "One factual sentence explaining WHY something changed this quarter — the driver, cause, tone shift, or structural factor. Numerical magnitudes (Δ% revenue, EPS deltas, margin changes) are displayed separately by the UI from SQL data, so focus on the EXPLANATION not the magnitude.",
       "source": "exactly one of: 10-K, 10-Q, transcript, news",
       "reliability": "HIGH or MEDIUM or LOW",
+      "impact": "HIGH or MEDIUM or LOW",
       "evidence_snippet": "Verbatim quote <=30 words"
     }
   ],
 
   "bull_points": [
-    { "text": "...", "source": "...", "reliability": "...", "evidence_snippet": "..." }
+    { "text": "...", "source": "...", "reliability": "...", "impact": "HIGH or MEDIUM or LOW", "evidence_snippet": "..." }
   ],
 
   "bear_points": [
-    { "text": "...", "source": "...", "reliability": "...", "evidence_snippet": "..." }
+    { "text": "...", "source": "...", "reliability": "...", "impact": "HIGH or MEDIUM or LOW", "evidence_snippet": "..." }
   ],
 
   "what_to_watch": [
@@ -202,16 +246,17 @@ Required JSON structure:
 
   "mda_summary": {
     "drivers": [
-      { "text": "Key revenue or margin driver from MD&A.", "source": "10-Q", "reliability": "HIGH", "evidence_snippet": "..." }
+      { "text": "Key revenue or margin driver from MD&A.", "source": "10-Q", "reliability": "HIGH", "impact": "HIGH or MEDIUM or LOW", "evidence_snippet": "..." }
     ],
     "headwinds": [
-      { "text": "Headwind or drag on performance.", "source": "10-Q", "reliability": "HIGH", "evidence_snippet": "..." }
+      { "text": "Headwind or drag on performance.", "source": "10-Q", "reliability": "HIGH", "impact": "HIGH or MEDIUM or LOW", "evidence_snippet": "..." }
     ],
     "language_shift": "1-2 sentences: how has management language changed vs prior periods? More confident, more cautious, more defensive? Reference specific wording changes if available.",
     "key_quote": {
       "text": "The single most revealing management statement this period.",
       "source": "10-Q, 10-K, or transcript",
       "reliability": "HIGH or MEDIUM",
+      "impact": "HIGH or MEDIUM or LOW",
       "evidence_snippet": "The verbatim quote <=30 words"
     }
   },
@@ -222,6 +267,7 @@ Required JSON structure:
       "text": "The risk in 1-2 sentences, grounded in filing language.",
       "source": "exactly one of: 10-K, 10-Q, transcript, news",
       "reliability": "HIGH or MEDIUM or LOW",
+      "impact": "HIGH or MEDIUM or LOW",
       "is_new_this_filing": false
     }
   ],
@@ -232,6 +278,7 @@ Required JSON structure:
       "summary": "1-2 sentence summary of what management said.",
       "source": "exactly one of: 10-K, 10-Q, transcript",
       "reliability": "HIGH for SEC filings, MEDIUM for transcript",
+      "impact": "HIGH or MEDIUM or LOW",
       "evidence_snippet": "Verbatim quote <=30 words"
     }
   ],
@@ -241,6 +288,8 @@ Required JSON structure:
       "period": "Q2 2025",
       "text": "The guidance statement, 1-2 sentences.",
       "source": "10-Q, 10-K, or transcript",
+      "reliability": "HIGH or MEDIUM",
+      "impact": "HIGH or MEDIUM or LOW",
       "metric_focus": "Revenue or EPS or Operating margin or Capex or null",
       "actual_result": "Delivered $X.XB revenue, +N% vs guide midpoint",
       "verdict": "beat"
@@ -319,7 +368,12 @@ Each rationale must paraphrase evidence already cited elsewhere in this brief
 
 ## Market expectations
 Populate `market_expectations` strictly from `get_analyst_expectations` tool output. Never invent numbers.
-- Copy `consensus_eps_est`, revision %, and price reactions verbatim from the tool result.
-- `consensus_rev_est_bn` = tool's revenue estimate / 1e9, rounded to 1 decimal.
-- `rationale`: ONE sentence comparing reported actuals (from get_financial_metrics) vs consensus and noting the price reaction direction. Use the tool's revision signal if non-zero. If the tool returned no data, set the entire object to null instead of fabricating.
+The tool output already uses the exact schema field names — copy each value verbatim, no renaming:
+- `consensus_eps_est` → copy as-is (float or null)
+- `consensus_rev_est_bn` → copy as-is (already in billions, float or null)
+- `revision_30d_pct` → copy as-is (float or null)
+- `d1_price_reaction_pct` → copy as-is (float or null)
+- `d5_price_reaction_pct` → copy as-is (float or null)
+If the tool returned `null` for a field, set that field to null — do NOT substitute zero or omit the key.
+- `rationale`: ONE sentence comparing reported actuals (from get_financial_metrics) vs consensus and noting the price reaction direction. Use the tool's revision signal if non-zero. If the tool returned no data at all, set the entire object to null instead of fabricating.
 """

agent/schemas.py

@@ -1,6 +1,7 @@
 import sys
 from typing import Literal, Optional
 from pydantic import BaseModel, ConfigDict, Field, field_validator
+from analysis.signals import QuarterDelta
 
 _CANONICAL_CATEGORIES = {
     "Regulatory", "Operational", "Competitive", "Financial", "Macro", "Demand", "Geopolitical"
@@ -45,6 +46,10 @@ class SourcedFact(BaseModel):
     reliability: Literal["HIGH", "MEDIUM", "LOW"] = Field(
         description="HIGH for SEC filings, MEDIUM for transcripts, LOW for news."
     )
+    impact: Optional[Literal["HIGH", "MEDIUM", "LOW"]] = Field(
+        default=None,
+        description="Materiality for the investment thesis. HIGH = thesis-shifting (guidance ≥5%, beat/miss ≥10%, major M&A, regulatory action, strategic pivot); MEDIUM = material but confirmatory; LOW = context or supporting detail.",
+    )
     evidence_snippet: str = Field(
         description="A literal quote (≤30 words) from the cited source that directly supports the claim. Must appear verbatim in retrieved tool output."
     )
@@ -98,6 +103,10 @@ class CategorizedRisk(BaseModel):
     reliability: Literal["HIGH", "MEDIUM", "LOW"] = Field(
         description="HIGH for SEC filings, MEDIUM for transcripts, LOW for news."
     )
+    impact: Optional[Literal["HIGH", "MEDIUM", "LOW"]] = Field(
+        default=None,
+        description="Materiality for the investment thesis. HIGH = could materially impair earnings, revenue, or operations; MEDIUM = notable headwind; LOW = background/standard risk disclosure.",
+    )
     is_new_this_filing: bool = Field(
         description="True if this risk appears new or materially escalated vs prior filing."
     )
@@ -125,6 +134,10 @@ class ManagementCommentaryTopic(BaseModel):
     reliability: Literal["HIGH", "MEDIUM", "LOW"] = Field(
         description="HIGH for SEC filings, MEDIUM for transcripts."
     )
+    impact: Optional[Literal["HIGH", "MEDIUM", "LOW"]] = Field(
+        default=None,
+        description="Materiality for the investment thesis. HIGH = topic directly shapes earnings or valuation outlook; MEDIUM = important but secondary; LOW = routine commentary.",
+    )
     evidence_snippet: str = Field(description="Verbatim quote ≤30 words supporting this topic.")
 
     @field_validator('evidence_snippet')
@@ -142,6 +155,14 @@ class GuidancePoint(BaseModel):
     source: Literal["10-K", "10-Q", "transcript", "news"] = Field(
         description="Document type where this guidance appeared."
     )
+    reliability: Optional[Literal["HIGH", "MEDIUM", "LOW"]] = Field(
+        default=None,
+        description="HIGH for SEC filings, MEDIUM for transcripts."
+    )
+    impact: Optional[Literal["HIGH", "MEDIUM", "LOW"]] = Field(
+        default=None,
+        description="Materiality of this guidance for the thesis. HIGH = large guidance change (≥5% vs consensus or prior), new metric, policy shift; MEDIUM = in-line guidance update; LOW = reaffirmation of existing guidance.",
+    )
     metric_focus: Optional[str] = Field(
         default=None,
         description="Primary metric being guided on, e.g. 'Revenue', 'EPS', 'Operating margin', 'Capex'."
@@ -298,3 +319,11 @@ class BriefOutput(BaseModel):
         default=None,
         description="Analyst consensus, 30-day estimate revisions, and post-earnings price reaction. Set to null if no analyst data available."
     )
+
+    # Analyst Edge fields — populated deterministically by analysis/ modules and
+    # attached by post_synthesis.attach_edge_signals after LLM synthesis.
+    # Always present (empty list = no signals computed), never synthesized by LLM.
+    quarter_deltas: list[QuarterDelta] = Field(
+        default_factory=list,
+        description="Verbatim text deltas computed deterministically across consecutive filing periods. Populated by code, not LLM.",
+    )

agent/tools.py

@@ -141,36 +141,34 @@ def get_analyst_expectations(ticker: str) -> str:
     if est is None and price is None:
         return f"No analyst data available for {ticker.upper()}. Errors: {est_err}; {price_err}"
 
-    lines = [f"Analyst expectations for {ticker.upper()}:"]
+    # Use exact schema field names so the LLM can copy values verbatim without renaming.
+    lines = [f"Analyst expectations for {ticker.upper()} (field names match MarketExpectations schema):"]
     if est:
         eps = est.get("consensus_eps_est")
         rev = est.get("consensus_rev_est")
         rev30 = est.get("estimate_revision_30d_pct")
+        lines.append(f"  consensus_eps_est: {eps:.4f}" if eps is not None else "  consensus_eps_est: null")
         lines.append(
-            f"  Consensus EPS estimate (current/next qtr): ${eps:.2f}" if eps is not None
-            else "  Consensus EPS estimate: N/A"
+            f"  consensus_rev_est_bn: {rev / 1e9:.4f}"  # already converted to billions
+            if rev is not None else "  consensus_rev_est_bn: null"
         )
         lines.append(
-            f"  Consensus Revenue estimate: ${rev / 1e9:.2f}B" if rev is not None
-            else "  Consensus Revenue estimate: N/A"
+            f"  revision_30d_pct: {rev30:.4f}  # signal: {_fmt_revision_signal(rev30)}"
+            if rev30 is not None else "  revision_30d_pct: null"
         )
-        if rev30 is not None:
-            lines.append(
-                f"  Estimate revision (30d): {rev30:+.1f}%  [signal: {_fmt_revision_signal(rev30)}]"
-            )
-        else:
-            lines.append("  Estimate revision (30d): N/A")
     else:
-        lines.append(f"  Estimates: unavailable ({est_err})")
+        lines.append(f"  consensus_eps_est: null  # unavailable: {est_err}")
+        lines.append("  consensus_rev_est_bn: null")
+        lines.append("  revision_30d_pct: null")
 
     if price:
         d1 = price.get("d1_pct")
         d5 = price.get("d5_pct")
-        d1_str = f"{d1:+.1f}%" if d1 is not None else "N/A"
-        d5_str = f"{d5:+.1f}%" if d5 is not None else "N/A"
-        lines.append(f"  Post-earnings price reaction: d1 {d1_str}, d5 {d5_str}")
+        lines.append(f"  d1_price_reaction_pct: {d1:.4f}" if d1 is not None else "  d1_price_reaction_pct: null")
+        lines.append(f"  d5_price_reaction_pct: {d5:.4f}" if d5 is not None else "  d5_price_reaction_pct: null")
     else:
-        lines.append(f"  Price reaction: unavailable ({price_err})")
+        lines.append(f"  d1_price_reaction_pct: null  # unavailable: {price_err}")
+        lines.append("  d5_price_reaction_pct: null")
 
     return "\n".join(lines)
 

analysis/signals.py

@@ -0,0 +1,56 @@
+"""analysis/signals.py — shared signal types for the Analyst Edge layer.
+
+These Pydantic models carry deterministically-computed evidence (verbatim
+before/after text, counts, deltas) from the analysis modules to the LangGraph
+agent and synthesis node. The LLM explains; the code supplies the figures.
+"""
+from __future__ import annotations
+
+from typing import Literal, Optional
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class QuarterDelta(BaseModel):
+    """A verbatim text change detected between two consecutive filing periods."""
+    model_config = ConfigDict(extra="ignore")
+
+    kind: Literal[
+        "risk_added",
+        "risk_removed",
+        "risk_reworded",
+        "guidance_language_shift",
+        "term_frequency",
+        "kpi_dropped",
+    ] = Field(description="Type of delta detected.")
+
+    period_from: str = Field(description="Prior filing period, e.g. 'Q42025'.")
+    period_to: str = Field(description="Current filing period, e.g. 'Q12026'.")
+
+    before_text: str = Field(
+        default="",
+        description="Verbatim fragment from the prior period. Empty for risk_added.",
+    )
+    after_text: str = Field(
+        default="",
+        description="Verbatim fragment from the current period. Empty for risk_removed.",
+    )
+
+    computed_metric: str = Field(
+        default="",
+        description="A computed summary, e.g. '2→8 occurrences (+300%)' for term_frequency.",
+    )
+
+    source: Literal["10-K", "10-Q", "transcript"] = Field(
+        default="10-Q",
+        description="Filing type the delta was detected in.",
+    )
+
+    significance: Literal["HIGH", "MEDIUM", "LOW"] = Field(
+        default="MEDIUM",
+        description="Computed significance: HIGH for new risks or large frequency swings, etc.",
+    )
+
+    term: str = Field(
+        default="",
+        description="The term or risk label being tracked (for term_frequency / kpi_dropped).",
+    )

analysis/textdiff.py

@@ -0,0 +1,582 @@
+"""analysis/textdiff.py — verbatim text delta signals for the Analyst Edge layer.
+
+Pure Python + sentence-transformers, zero LLM calls.
+Compares the most recent filing period against the prior period for a ticker
+and surfaces verbatim before→after fragments for the most material changes:
+
+  1. risk_reworded / risk_added / risk_removed  — risk-factor diffs
+  2. term_frequency                             — analyst-lexicon count deltas
+  3. guidance_language_shift                   — hedge/modal word shifts in MD&A
+  4. kpi_dropped                               — metric mentioned prior, absent now
+
+Usage:
+    from analysis.textdiff import compute
+    signals = compute("NVDA")
+"""
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+import numpy as np
+
+from analysis.signals import QuarterDelta
+from storage.sections_db import get_section, get_periods_for_ticker
+
+# ---------------------------------------------------------------------------
+# Config
+# ---------------------------------------------------------------------------
+
+_REWORD_THRESHOLD = 0.70    # cosine similarity: current & prior considered "same risk"
+_NEW_RISK_THRESHOLD = 0.40  # below this → new risk (added)
+_IDENTICAL_THRESHOLD = 0.93 # above this → unchanged, skip
+
+_MIN_ITEM_WORDS = 25        # minimum words for a text chunk to be considered
+
+# Analyst / macro lexicon to track frequency across periods
+_LEXICON: list[tuple[str, str]] = [
+    # (term, display_label)
+    (r"\btariff\b",          "tariff"),
+    (r"\bexport control\b",  "export control"),
+    (r"\bheadwind\b",        "headwind"),
+    (r"\buncertainty\b",     "uncertainty"),
+    (r"\bsoftness\b",        "softness"),
+    (r"\bslowing\b",         "slowing"),
+    (r"\bdecelerat\w*",      "deceleration"),
+    (r"\bcautious\b",        "cautious"),
+    (r"\bpressure\b",        "pressure"),
+    (r"\bai\b",              "AI"),
+    (r"\bbuyback\b",         "buyback"),
+    (r"\blayoff\b",          "layoff"),
+    (r"\brestructur\w*",     "restructuring"),
+    (r"\bimpairment\b",      "impairment"),
+    (r"\blitigation\b",      "litigation"),
+    (r"\bchinese? market\b", "China market"),
+    (r"\bsanction\b",        "sanction"),
+    (r"\brecession\b",       "recession"),
+]
+
+# Frequency swing that triggers a signal (×2 or more, and absolute diff ≥ 2)
+_FREQ_RATIO_THRESHOLD = 2.0
+_FREQ_ABS_THRESHOLD = 2
+
+# KPI labels that, if absent from the current MD&A, signal a dropped KPI
+_KPI_PATTERNS: list[tuple[str, str]] = [
+    (r"\b(?:gross\s+)?margins?\b",                          "gross margin"),
+    (r"\b(?:operating\s+)?margins?\b",                      "operating margin"),
+    (r"\bfree\s+cash\s+flow\b",                             "free cash flow"),
+    (r"\bdays?\s+sales?\s+outstanding\b|\bdso\b",           "DSO"),
+    (r"\bdays?\s+inventory\s+outstanding\b|\bdio\b",        "DIO"),
+    (r"\bdays?\s+payable\s+outstanding\b|\bdpo\b",          "DPO"),
+    (r"\bshare\s+(?:repurchase|buyback)\b",                 "share repurchase"),
+    (r"\bdividend\b",                                       "dividend"),
+    (r"\bguidance\b",                                       "guidance"),
+    (r"\bbacklog\b",                                        "backlog"),
+    (r"\bdeferred\s+revenue\b",                             "deferred revenue"),
+    (r"\bnet\s+retention\s+rate\b",                         "net retention rate"),
+]
+
+# Guidance hedge / modality words
+_HEDGE_WORDS = [
+    "expect to grow", "expect growth", "expects to grow", "expects growth",
+    "anticipate", "plan to", "target", "forecast",
+    "moderate", "soften", "decline", "reduce", "headwind", "challenge",
+    "cautious", "uncertain", "volatile",
+]
+
+# ---------------------------------------------------------------------------
+# Model (lazy singleton)
+# ---------------------------------------------------------------------------
+
+_encoder = None
+
+
+def _get_encoder():
+    global _encoder
+    if _encoder is None:
+        from sentence_transformers import SentenceTransformer
+        _encoder = SentenceTransformer("all-MiniLM-L6-v2", device="cpu")
+    return _encoder
+
+
+def _embed(texts: list[str]) -> np.ndarray:
+    enc = _get_encoder()
+    vecs = enc.encode(texts, convert_to_numpy=True, show_progress_bar=False)
+    # Normalise rows
+    norms = np.linalg.norm(vecs, axis=1, keepdims=True)
+    norms = np.where(norms < 1e-8, 1.0, norms)
+    return vecs / norms
+
+
+def _cosine(a: np.ndarray, b: np.ndarray) -> float:
+    return float(np.dot(a, b))
+
+
+# ---------------------------------------------------------------------------
+# Text splitters
+# ---------------------------------------------------------------------------
+
+def _split_into_items(text: str, min_words: int = _MIN_ITEM_WORDS) -> list[str]:
+    """Split a section text into logical chunks (risk items / paragraphs).
+
+    Uses double-newline paragraph boundaries. Merges short lines (headers)
+    with the following paragraph. Returns only chunks >= min_words.
+    """
+    raw = re.split(r"\n{2,}", text.strip())
+    items: list[str] = []
+    buffer = ""
+    for para in raw:
+        para = para.strip()
+        if not para:
+            continue
+        word_count = len(para.split())
+        if word_count < 8:
+            # Likely a heading — prepend to next paragraph
+            buffer = para + " "
+        else:
+            combined = (buffer + para).strip()
+            buffer = ""
+            if len(combined.split()) >= min_words:
+                items.append(combined)
+    if buffer.strip() and len(buffer.split()) >= min_words:
+        items.append(buffer.strip())
+    return items
+
+
+def _split_sentences(text: str) -> list[str]:
+    """Simple sentence splitter (no NLTK dependency)."""
+    sentences = re.split(r"(?<=[.!?])\s+", text)
+    return [s.strip() for s in sentences if len(s.split()) >= 5]
+
+
+# ---------------------------------------------------------------------------
+# Greedy one-to-one item alignment
+# ---------------------------------------------------------------------------
+
+def _align_items(
+    current_items: list[str],
+    prior_items: list[str],
+    current_vecs: np.ndarray,
+    prior_vecs: np.ndarray,
+) -> tuple[dict[int, int], dict[int, float]]:
+    """Greedy one-to-one alignment: each current item → best prior item.
+
+    Returns:
+        matches: {current_idx: prior_idx}
+        scores:  {current_idx: cosine_similarity}
+    """
+    if len(current_items) == 0 or len(prior_items) == 0:
+        return {}, {}
+
+    # pairwise similarities: (n_current × n_prior)
+    sim_matrix = current_vecs @ prior_vecs.T  # shape (n_cur, n_pri)
+
+    matches: dict[int, int] = {}
+    scores: dict[int, float] = {}
+    used_prior: set[int] = set()
+
+    # Process current items in order; assign best available prior match
+    for ci in range(len(current_items)):
+        row = sim_matrix[ci]
+        # mask already-used prior indices
+        masked = [(row[pi], pi) for pi in range(len(prior_items)) if pi not in used_prior]
+        if not masked:
+            break
+        best_score, best_pi = max(masked)
+        matches[ci] = best_pi
+        scores[ci] = best_score
+        if best_score >= _NEW_RISK_THRESHOLD:
+            used_prior.add(best_pi)
+
+    return matches, scores
+
+
+# ---------------------------------------------------------------------------
+# Risk factor diff
+# ---------------------------------------------------------------------------
+
+def compute_risk_deltas(
+    current_text: str,
+    prior_text: str,
+    period_from: str,
+    period_to: str,
+    form_type: str,
+) -> list[QuarterDelta]:
+    """Align risk-factor items across two periods and classify changes."""
+    if not current_text or not prior_text:
+        return []
+
+    current_items = _split_into_items(current_text)
+    prior_items = _split_into_items(prior_text)
+    if not current_items or not prior_items:
+        return []
+
+    current_vecs = _embed(current_items)
+    prior_vecs = _embed(prior_items)
+
+    matches, scores = _align_items(current_items, prior_items, current_vecs, prior_vecs)
+
+    matched_prior_indices: set[int] = set()
+    deltas: list[QuarterDelta] = []
+    source_lit = "10-K" if "10-K" in form_type.upper() else "10-Q"
+
+    for ci, item in enumerate(current_items):
+        pi = matches.get(ci)
+        score = scores.get(ci, 0.0)
+
+        if pi is not None and score >= _NEW_RISK_THRESHOLD:
+            matched_prior_indices.add(pi)
+            if score >= _IDENTICAL_THRESHOLD:
+                continue  # unchanged — not interesting
+
+            # Reworded: significant textual change
+            before = _truncate(prior_items[pi], 120)
+            after = _truncate(item, 120)
+            sig = "HIGH" if score < 0.80 else "MEDIUM"
+            deltas.append(QuarterDelta(
+                kind="risk_reworded",
+                period_from=period_from,
+                period_to=period_to,
+                before_text=before,
+                after_text=after,
+                computed_metric=f"similarity {score:.2f}",
+                source=source_lit,
+                significance=sig,
+                term="",
+            ))
+        else:
+            # New risk — not matched in prior
+            after = _truncate(item, 120)
+            deltas.append(QuarterDelta(
+                kind="risk_added",
+                period_from=period_from,
+                period_to=period_to,
+                before_text="",
+                after_text=after,
+                computed_metric="",
+                source=source_lit,
+                significance="HIGH",
+                term="",
+            ))
+
+    # Removed: prior items not matched by any current item
+    for pi, item in enumerate(prior_items):
+        if pi not in matched_prior_indices:
+            before = _truncate(item, 120)
+            deltas.append(QuarterDelta(
+                kind="risk_removed",
+                period_from=period_from,
+                period_to=period_to,
+                before_text=before,
+                after_text="",
+                computed_metric="",
+                source=source_lit,
+                significance="MEDIUM",
+                term="",
+            ))
+
+    # Keep at most 6 highest-significance deltas to avoid flooding the prompt
+    order = {"HIGH": 0, "MEDIUM": 1, "LOW": 2}
+    deltas.sort(key=lambda d: (order[d.significance], d.kind))
+    return deltas[:6]
+
+
+# ---------------------------------------------------------------------------
+# Analyst-lexicon frequency deltas
+# ---------------------------------------------------------------------------
+
+def compute_lexicon_deltas(
+    current_text: str,
+    prior_text: str,
+    period_from: str,
+    period_to: str,
+    form_type: str,
+) -> list[QuarterDelta]:
+    """Count analyst-lexicon term occurrences and flag large swings."""
+    if not current_text or not prior_text:
+        return []
+
+    source_lit = "10-K" if "10-K" in form_type.upper() else "10-Q"
+    cur_lower = current_text.lower()
+    pri_lower = prior_text.lower()
+
+    deltas: list[QuarterDelta] = []
+
+    for pattern, label in _LEXICON:
+        cur_count = len(re.findall(pattern, cur_lower, re.IGNORECASE))
+        pri_count = len(re.findall(pattern, pri_lower, re.IGNORECASE))
+
+        if cur_count == 0 and pri_count == 0:
+            continue
+
+        abs_diff = abs(cur_count - pri_count)
+        if abs_diff < _FREQ_ABS_THRESHOLD:
+            continue
+
+        # Require at least ×2 change in either direction
+        max_count = max(cur_count, pri_count)
+        min_count = min(cur_count, pri_count) or 0.5  # avoid div-by-zero
+        ratio = max_count / min_count
+        if ratio < _FREQ_RATIO_THRESHOLD:
+            continue
+
+        direction = "up" if cur_count > pri_count else "down"
+        pct = (cur_count - pri_count) / (pri_count or 1) * 100
+        metric = f"{pri_count}→{cur_count} occurrences ({pct:+.0f}%)"
+
+        # Significance: HIGH if ratio ≥ 3 or abs_diff ≥ 5
+        sig = "HIGH" if (ratio >= 3.0 or abs_diff >= 5) else "MEDIUM"
+
+        # Extract a context sentence for the term (from current or prior)
+        after_ctx = _find_context_sentence(current_text, pattern) if cur_count > 0 else ""
+        before_ctx = _find_context_sentence(prior_text, pattern) if pri_count > 0 else ""
+
+        deltas.append(QuarterDelta(
+            kind="term_frequency",
+            period_from=period_from,
+            period_to=period_to,
+            before_text=before_ctx,
+            after_text=after_ctx,
+            computed_metric=metric,
+            source=source_lit,
+            significance=sig,
+            term=label,
+        ))
+
+    deltas.sort(key=lambda d: {"HIGH": 0, "MEDIUM": 1}.get(d.significance, 2))
+    return deltas[:5]
+
+
+def _find_context_sentence(text: str, pattern: str) -> str:
+    """Return the first sentence containing a match for `pattern`."""
+    sentences = _split_sentences(text)
+    for sent in sentences:
+        if re.search(pattern, sent, re.IGNORECASE):
+            return _truncate(sent, 100)
+    return ""
+
+
+# ---------------------------------------------------------------------------
+# Guidance / MD&A language shift
+# ---------------------------------------------------------------------------
+
+def compute_guidance_shifts(
+    current_mda: str,
+    prior_mda: str,
+    period_from: str,
+    period_to: str,
+    form_type: str,
+) -> list[QuarterDelta]:
+    """Detect forward-looking language becoming more cautious or more bullish."""
+    if not current_mda or not prior_mda:
+        return []
+
+    source_lit = "10-K" if "10-K" in form_type.upper() else "10-Q"
+
+    # Extract sentences that contain guidance / forward-looking language
+    cur_fwd = _forward_looking_sentences(current_mda)
+    pri_fwd = _forward_looking_sentences(prior_mda)
+
+    if not cur_fwd or not pri_fwd:
+        return []
+
+    # Count hedge words in guidance sentences
+    cur_hedge = _count_hedge(cur_fwd)
+    pri_hedge = _count_hedge(pri_fwd)
+
+    abs_diff = abs(cur_hedge - pri_hedge)
+    if abs_diff < 2:
+        return []
+
+    direction = "more cautious" if cur_hedge > pri_hedge else "more confident"
+    pct = (cur_hedge - pri_hedge) / (pri_hedge or 1) * 100
+    metric = f"{pri_hedge}→{cur_hedge} hedge-word occurrences ({pct:+.0f}%) → {direction}"
+
+    # Pick most representative sentence from each period
+    before_sent = _pick_representative(pri_fwd, prior_mda)
+    after_sent = _pick_representative(cur_fwd, current_mda)
+
+    sig = "HIGH" if abs_diff >= 5 else "MEDIUM"
+
+    return [QuarterDelta(
+        kind="guidance_language_shift",
+        period_from=period_from,
+        period_to=period_to,
+        before_text=before_sent,
+        after_text=after_sent,
+        computed_metric=metric,
+        source=source_lit,
+        significance=sig,
+        term="guidance tone",
+    )]
+
+
+_FWD_PATTERNS = re.compile(
+    r"\b(expect|anticipate|forecast|guidance|outlook|project|target|plan\s+to|"
+    r"will\s+(?:grow|increase|decrease|decline|moderate)|believe\s+(?:we|our))\b",
+    re.IGNORECASE,
+)
+
+
+def _forward_looking_sentences(text: str) -> list[str]:
+    sentences = _split_sentences(text)
+    return [s for s in sentences if _FWD_PATTERNS.search(s)]
+
+
+def _count_hedge(sentences: list[str]) -> int:
+    joined = " ".join(sentences).lower()
+    return sum(1 for w in _HEDGE_WORDS if w in joined)
+
+
+def _pick_representative(sentences: list[str], full_text: str) -> str:
+    """Return the shortest guidance sentence (most quotable) that contains a hedge word."""
+    hedge_sents = [
+        s for s in sentences
+        if any(h in s.lower() for h in _HEDGE_WORDS)
+    ]
+    pool = hedge_sents if hedge_sents else sentences
+    pool_sorted = sorted(pool, key=lambda s: len(s.split()))
+    if pool_sorted:
+        return _truncate(pool_sorted[0], 100)
+    return _truncate(sentences[0], 100) if sentences else ""
+
+
+# ---------------------------------------------------------------------------
+# Dropped KPI detection
+# ---------------------------------------------------------------------------
+
+def compute_kpi_drops(
+    current_mda: str,
+    prior_mda: str,
+    period_from: str,
+    period_to: str,
+    form_type: str,
+) -> list[QuarterDelta]:
+    """Flag a KPI / metric label that appears in prior MD&A but not in current."""
+    if not current_mda or not prior_mda:
+        return []
+
+    source_lit = "10-K" if "10-K" in form_type.upper() else "10-Q"
+    cur_lower = current_mda.lower()
+    pri_lower = prior_mda.lower()
+
+    deltas: list[QuarterDelta] = []
+    for pattern, label in _KPI_PATTERNS:
+        in_current = bool(re.search(pattern, cur_lower, re.IGNORECASE))
+        in_prior = bool(re.search(pattern, pri_lower, re.IGNORECASE))
+
+        if in_prior and not in_current:
+            ctx = _find_context_sentence(prior_mda, pattern)
+            deltas.append(QuarterDelta(
+                kind="kpi_dropped",
+                period_from=period_from,
+                period_to=period_to,
+                before_text=ctx,
+                after_text="",
+                computed_metric=f"'{label}' mentioned in {period_from} MD&A, absent from {period_to}",
+                source=source_lit,
+                significance="MEDIUM",
+                term=label,
+            ))
+
+    return deltas[:3]
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _truncate(text: str, max_words: int) -> str:
+    words = text.split()
+    if len(words) <= max_words:
+        return text
+    return " ".join(words[:max_words]) + "…"
+
+
+# ---------------------------------------------------------------------------
+# Main entry point
+# ---------------------------------------------------------------------------
+
+def compute(ticker: str, current_period: Optional[str] = None) -> list[QuarterDelta]:
+    """Compute all text delta signals for a ticker.
+
+    Compares the current period (latest ingested 10-Q) against the prior
+    period (previous 10-Q). Returns an empty list if sections are missing
+    or an error occurs — never raises.
+
+    Args:
+        ticker: uppercase ticker symbol.
+        current_period: override the current period (default: latest in DB).
+    """
+    try:
+        return _compute_inner(ticker, current_period)
+    except Exception as exc:
+        import sys
+        print(f"[textdiff] Error computing deltas for {ticker}: {exc}", file=sys.stderr)
+        return []
+
+
+def _compute_inner(ticker: str, current_period: Optional[str]) -> list[QuarterDelta]:
+    ticker = ticker.upper()
+
+    # Determine current and prior periods (10-Q only for QoQ comparison)
+    periods = get_periods_for_ticker(ticker, form_type="10-Q")
+    if len(periods) < 2:
+        return []
+
+    period_to = current_period if current_period else periods[0]
+    # Find the prior period (the one just before period_to in the list)
+    if period_to in periods:
+        idx = periods.index(period_to)
+        if idx + 1 >= len(periods):
+            return []
+        period_from = periods[idx + 1]
+    else:
+        period_from = periods[1]
+
+    # Determine form_type for the current period (need it for source label)
+    # Look for any section stored for this period to infer form_type
+    # Default to 10-Q since we filtered above
+    form_type = "10-Q"
+
+    # Load sections
+    cur_risk = get_section(ticker, period_to, "risk_factors") or ""
+    pri_risk = get_section(ticker, period_from, "risk_factors") or ""
+    cur_mda = get_section(ticker, period_to, "mda") or ""
+    pri_mda = get_section(ticker, period_from, "mda") or ""
+
+    if not cur_risk and not cur_mda:
+        return []
+
+    all_deltas: list[QuarterDelta] = []
+
+    # 1. Risk factors diff
+    if cur_risk and pri_risk:
+        all_deltas.extend(compute_risk_deltas(cur_risk, pri_risk, period_from, period_to, form_type))
+
+    # 2. Lexicon frequency deltas (combined mda + risk text for broader coverage)
+    cur_full = (cur_mda + "\n\n" + cur_risk).strip()
+    pri_full = (pri_mda + "\n\n" + pri_risk).strip()
+    if cur_full and pri_full:
+        all_deltas.extend(compute_lexicon_deltas(cur_full, pri_full, period_from, period_to, form_type))
+
+    # 3. Guidance language shift (MD&A only)
+    if cur_mda and pri_mda:
+        all_deltas.extend(compute_guidance_shifts(cur_mda, pri_mda, period_from, period_to, form_type))
+
+    # 4. Dropped KPIs
+    if cur_mda and pri_mda:
+        all_deltas.extend(compute_kpi_drops(cur_mda, pri_mda, period_from, period_to, form_type))
+
+    # Deduplicate and sort: HIGH first, then MEDIUM, then LOW
+    seen: set[str] = set()
+    deduped: list[QuarterDelta] = []
+    for d in all_deltas:
+        key = f"{d.kind}:{d.term}:{d.before_text[:40]}"
+        if key not in seen:
+            seen.add(key)
+            deduped.append(d)
+
+    order = {"HIGH": 0, "MEDIUM": 1, "LOW": 2}
+    deduped.sort(key=lambda d: (order[d.significance], d.kind))
+    return deduped

app.py

@@ -120,7 +120,13 @@ def _run_brief_thread(ticker: str, gen: dict) -> None:
     except Exception as exc:
         import sys
         print(f"[gen thread error] {exc}", file=sys.stderr)
-        gen["error"] = str(exc)
+        raw = str(exc)
+        if "overloaded_error" in raw:
+            gen["error"] = "Anthropic API is overloaded — please retry in a moment."
+        elif "rate_limit" in raw or "429" in raw:
+            gen["error"] = "Anthropic API rate limit reached — please retry in a moment."
+        else:
+            gen["error"] = raw
     finally:
         gen["running"] = False
 
@@ -142,8 +148,7 @@ if generate_clicked and ticker_input and not st.session_state["gen"]["running"]:
         t.start()
 
 
-# ── Live trace fragment (polls every 400ms while generation runs) ────────────────
-@st.fragment
+# ── Live trace poller (polls every 400ms while generation runs) ──────────────────
 def _live_trace_fragment() -> None:
     gen = st.session_state.get("gen", {})
     if not gen.get("running") and not gen.get("trace"):
@@ -179,7 +184,7 @@ def _live_trace_fragment() -> None:
     if gen.get("running"):
         # Still generating — poll again in 400 ms (server-side timer avoids HF Spaces proxy race)
         time.sleep(0.4)
-        st.rerun(scope="fragment")
+        st.rerun()
     else:
         # Thread has finished — persist results and navigate
         if gen.get("brief"):

dashboard/catalysts.py

@@ -6,7 +6,7 @@ from dashboard.theme import (
     BG, BG_MUTED, BORDER, TEXT, TEXT_MUTED, TEXT_FAINT,
 )
 from dashboard import fmt_period
-from dashboard.components import section_header
+from dashboard.components import section_header, impact_badge, reliability_badge, source_badge
 
 _METRIC_COLORS = {
     "Revenue": GREEN,
@@ -62,6 +62,33 @@ def render(brief: dict, ticker: str) -> None:
         unsafe_allow_html=True,
     )
 
+    # ── Scorecard hero ────────────────────────────────────────────────────────
+    if guidance:
+        beats = sum(1 for g in guidance if g.get("verdict") == "beat")
+        inline = sum(1 for g in guidance if g.get("verdict") == "in-line")
+        missed = sum(1 for g in guidance if g.get("verdict") == "missed")
+        pending = sum(1 for g in guidance if g.get("verdict") == "pending")
+
+        def _score_chip(label: str, count: int, color: str, bg: str) -> str:
+            return (
+                f'<div style="background:{bg};border:1px solid {color}2a;border-radius:8px;'
+                f'padding:12px 16px;text-align:center;">'
+                f'<div style="font-size:1.6rem;font-weight:800;color:{color};line-height:1;">{count}</div>'
+                f'<div style="font-size:0.62rem;font-weight:700;text-transform:uppercase;'
+                f'letter-spacing:0.08em;color:{color};margin-top:3px;">{label}</div>'
+                f'</div>'
+            )
+
+        score_html = (
+            f'<div style="display:grid;grid-template-columns:repeat(4,1fr);gap:10px;margin-bottom:20px;">'
+            f'{_score_chip("Beat", beats, GREEN, "#ecfdf5")}'
+            f'{_score_chip("In-line", inline, AMBER, "#fffbeb")}'
+            f'{_score_chip("Missed", missed, RED, "#fef2f2")}'
+            f'{_score_chip("Pending", pending, GRAY, "#f3f4f6")}'
+            f'</div>'
+        )
+        st.markdown(score_html, unsafe_allow_html=True)
+
     # ── Guidance history ──────────────────────────────────────────────────────
     if guidance:
         st.markdown(
@@ -79,7 +106,12 @@ def render(brief: dict, ticker: str) -> None:
                 f'<div style="font-size:0.8rem;color:{TEXT_MUTED};margin-top:5px;line-height:1.45;">{actual_result}</div>'
                 if actual_result else ""
             )
-            chips_html = f'<div style="margin-top:6px;display:flex;align-items:center;gap:8px;">{_metric_chip(gp.get("metric_focus"))}{verdict_html}</div>'
+            chips_html = (
+                f'<div style="margin-top:6px;display:flex;flex-wrap:wrap;align-items:center;gap:6px;">'
+                f'{_metric_chip(gp.get("metric_focus"))}{verdict_html}'
+                f'{impact_badge(gp.get("impact","") or "")}'
+                f'</div>'
+            )
             st.markdown(
                 f'<div style="display:flex;gap:12px;align-items:flex-start;padding:12px 0;border-bottom:1px solid {BORDER};">'
                 f'<div style="min-width:90px;">'
@@ -152,8 +184,8 @@ def _render_db_guidance(ticker: str, shown_periods: set) -> None:
 
     st.markdown(
         f'<div style="font-size:0.72rem;color:{TEXT_FAINT};margin:16px 0 8px;line-height:1.5;">'
-        f'Guidance brute détectée par règle (regex sur MD&A). La section ci-dessus '
-        f'est l\'analyse LLM des mêmes guidances avec verdict beat/in-line/missed.</div>',
+        f'Raw guidance detected by rule (regex on MD&A). The section above '
+        f'is the LLM analysis of the same guidance with beat/in-line/missed verdict.</div>',
         unsafe_allow_html=True,
     )
 

dashboard/components.py

@@ -6,6 +6,8 @@ from dashboard.theme import (
     BG, BG_MUTED, TEXT, TEXT_MUTED,
     WARN_BG, WARN_BORDER,
     BULL_BG, BULL_BORDER, BEAR_BG, BEAR_BORDER,
+    PURPLE, AI_BG, AI_BORDER, AI_COLOR, AI_BADGE_BG,
+    RADIUS_CHIP,
 )
 
 # ── Reliability badge ─────────────────────────────────────────────────────────
@@ -19,6 +21,62 @@ def reliability_badge(r: str) -> str:
     )
 
 
+# ── Impact badge ─────────────────────────────────────────────────────────────
+
+_IMPACT_DOT_COLORS = {
+    "HIGH":   ("#0f172a", 3),
+    "MEDIUM": ("#64748b", 2),
+    "LOW":    ("#94a3b8", 1),
+}
+
+def impact_badge(level: str) -> str:
+    spec = _IMPACT_DOT_COLORS.get(level)
+    if not spec:
+        return ""
+    color, filled = spec
+    dots = "".join(
+        f'<span style="color:{color if i < filled else "#d1d5db"};font-size:0.55rem;line-height:1;">●</span>'
+        for i in range(3)
+    )
+    return (
+        f'<span title="Impact: {level}" style="display:inline-flex;align-items:center;gap:3px;'
+        f'background:#f8fafc;border:1px solid #e2e8f0;border-radius:4px;padding:1px 7px;">'
+        f'<span style="font-size:0.6rem;font-weight:600;color:#64748b;letter-spacing:0.05em;">impact</span>'
+        f'{dots}</span>'
+    )
+
+
+# ── AI interpretation badge ───────────────────────────────────────────────────
+
+def ai_badge(label: str = "AI Synthesis") -> str:
+    return (
+        f'<span style="background:{AI_BADGE_BG};color:{AI_COLOR};'
+        f'border:1px solid {AI_BORDER};border-radius:4px;'
+        f'padding:1px 7px;font-size:0.62rem;font-weight:600;">✦ {label}</span>'
+    )
+
+
+# ── AI interpretation card wrapper ────────────────────────────────────────────
+
+def interpretation_card(
+    header_label: str,
+    content_html: str,
+    badge_label: str = "AI Synthesis",
+) -> str:
+    return (
+        f'<div class="primer-card" style="background:{AI_BG};border:1px solid {AI_BORDER};'
+        f'border-left:4px solid {PURPLE};border-radius:0 12px 12px 0;'
+        f'padding:20px 24px;margin-bottom:4px;">'
+        f'<div style="display:flex;align-items:center;gap:8px;margin-bottom:8px;">'
+        f'<span style="font-size:0.62rem;font-weight:700;letter-spacing:0.1em;'
+        f'text-transform:uppercase;color:{TEXT_MUTED};">{header_label}</span>'
+        f'{ai_badge(badge_label)}'
+        f'</div>'
+        f'{content_html}'
+        f'</div>'
+    )
+
+
 # ── Source type badge ─────────────────────────────────────────────────────────
 
 _SOURCE_STYLES: dict[str, tuple[str, str, str]] = {
@@ -95,9 +153,10 @@ def fact_card(fact: dict, accent: str = GREEN) -> None:
                 {fact.get("text","")}
             </div>
             {evidence_quote(fact.get("evidence_snippet",""), bg=BG_MUTED, border_color=BORDER)}
-            <div style="margin-top:6px;">
+            <div style="margin-top:6px;display:flex;gap:5px;flex-wrap:wrap;align-items:center;">
                 {reliability_badge(fact.get("reliability",""))}
-                &nbsp;{source_badge(fact.get("source",""))}
+                {source_badge(fact.get("source",""))}
+                {impact_badge(fact.get("impact","") or "")}
             </div>
         </div>
         """,
@@ -132,28 +191,36 @@ def tension_card(tension: dict) -> None:
     bull_side = (
         f'<div style="flex:1;padding:12px 14px;background:{BULL_BG};border:1px solid {BULL_BORDER};'
         f'border-radius:8px;min-width:0;">'
-        f'<div style="font-size:0.58rem;font-weight:700;text-transform:uppercase;'
-        f'letter-spacing:0.09em;color:#059669;margin-bottom:6px;">Surface reading</div>'
+        f'<div style="display:flex;align-items:center;gap:5px;margin-bottom:6px;">'
+        f'<span style="font-size:0.58rem;font-weight:700;text-transform:uppercase;'
+        f'letter-spacing:0.09em;color:#059669;">Surface reading</span>'
+        f'{ai_badge("AI")}'
+        f'</div>'
         f'<div style="font-size:0.82rem;line-height:1.5;color:{TEXT};margin-bottom:8px;">'
         f'{bullish_reading}</div>'
         f'{evidence_quote(bull_ev.get("evidence_snippet","") if isinstance(bull_ev, dict) else "", bg=BG, border_color=BULL_BORDER)}'
-        f'<div style="margin-top:6px;">'
+        f'<div style="margin-top:6px;display:flex;gap:5px;flex-wrap:wrap;align-items:center;">'
         f'{reliability_badge(bull_ev.get("reliability","") if isinstance(bull_ev, dict) else "")}'
-        f'&nbsp;{source_badge(bull_ev.get("source","") if isinstance(bull_ev, dict) else "")}'
+        f'{source_badge(bull_ev.get("source","") if isinstance(bull_ev, dict) else "")}'
+        f'{impact_badge((bull_ev.get("impact","") or "") if isinstance(bull_ev, dict) else "")}'
         f'</div>'
         f'</div>'
     )
     bear_side = (
         f'<div style="flex:1;padding:12px 14px;background:{BEAR_BG};border:1px solid {BEAR_BORDER};'
         f'border-radius:8px;min-width:0;">'
-        f'<div style="font-size:0.58rem;font-weight:700;text-transform:uppercase;'
-        f'letter-spacing:0.09em;color:#dc2626;margin-bottom:6px;">Deeper reading</div>'
+        f'<div style="display:flex;align-items:center;gap:5px;margin-bottom:6px;">'
+        f'<span style="font-size:0.58rem;font-weight:700;text-transform:uppercase;'
+        f'letter-spacing:0.09em;color:#dc2626;">Deeper reading</span>'
+        f'{ai_badge("AI")}'
+        f'</div>'
         f'<div style="font-size:0.82rem;line-height:1.5;color:{TEXT};margin-bottom:8px;">'
         f'{bearish_reading}</div>'
         f'{evidence_quote(bear_ev.get("evidence_snippet","") if isinstance(bear_ev, dict) else "", bg=BG, border_color=BEAR_BORDER)}'
-        f'<div style="margin-top:6px;">'
+        f'<div style="margin-top:6px;display:flex;gap:5px;flex-wrap:wrap;align-items:center;">'
         f'{reliability_badge(bear_ev.get("reliability","") if isinstance(bear_ev, dict) else "")}'
-        f'&nbsp;{source_badge(bear_ev.get("source","") if isinstance(bear_ev, dict) else "")}'
+        f'{source_badge(bear_ev.get("source","") if isinstance(bear_ev, dict) else "")}'
+        f'{impact_badge((bear_ev.get("impact","") or "") if isinstance(bear_ev, dict) else "")}'
         f'</div>'
         f'</div>'
     )
@@ -210,10 +277,12 @@ def quality_signal_chip(signal: dict) -> str:
             f'border-left:2px solid {border};padding-left:8px;line-height:1.4;">'
             f'"{snippet}"</div>'
         )
+    ev_impact = evidence.get("impact", "") or "" if isinstance(evidence, dict) else ""
     badges_html = ""
-    if ev_rel or ev_source:
+    if ev_rel or ev_source or ev_impact:
         badges_html = (
-            f'<div style="margin-top:6px;">{reliability_badge(ev_rel)}&nbsp;{source_badge(ev_source)}</div>'
+            f'<div style="margin-top:6px;display:flex;gap:5px;flex-wrap:wrap;align-items:center;">'
+            f'{reliability_badge(ev_rel)}{source_badge(ev_source)}{impact_badge(ev_impact)}</div>'
         )
 
     return (
@@ -227,8 +296,134 @@ def quality_signal_chip(signal: dict) -> str:
         f'</summary>'
         f'<div style="margin-top:4px;padding:10px 12px;background:{bg};border:1px solid {border};'
         f'border-radius:8px;max-width:340px;">'
+        f'<div style="margin-bottom:5px;">{ai_badge("AI assessment")}</div>'
         f'<div style="font-size:0.78rem;color:{TEXT};line-height:1.5;">{rationale}</div>'
         f'{ev_html}{badges_html}'
         f'</div>'
         f'</details>'
     )
+
+
+# ── Compact labeled stat chip ─────────────────────────────────────────────────
+
+def stat_chip(label: str, value: str, tone: str = "neutral") -> str:
+    """Compact labeled stat chip for hero bands and market reaction strips."""
+    _tones: dict[str, tuple[str, str]] = {
+        "positive": (GREEN, BULL_BG),
+        "negative": (RED,   BEAR_BG),
+        "neutral":  (GRAY,  BG_MUTED),
+    }
+    color, bg = _tones.get(tone, _tones["neutral"])
+    return (
+        f'<div style="background:{bg};border:1px solid {color}2a;border-radius:{RADIUS_CHIP};'
+        f'padding:10px 14px;">'
+        f'<div style="font-size:0.58rem;font-weight:700;text-transform:uppercase;'
+        f'letter-spacing:0.08em;color:{TEXT_MUTED};margin-bottom:3px;">{label}</div>'
+        f'<div style="font-size:1rem;font-weight:700;color:{color};line-height:1.2;">{value}</div>'
+        f'</div>'
+    )
+
+
+# ── AI section header (horizontal rule with label) ────────────────────────────
+
+def ai_section_header(title: str) -> str:
+    """Lavender divider-label used to open an AI interpretation zone."""
+    return (
+        f'<div style="display:flex;align-items:center;gap:10px;margin:24px 0 12px;">'
+        f'<span style="font-size:0.65rem;font-weight:700;letter-spacing:0.12em;'
+        f'text-transform:uppercase;color:{AI_COLOR};white-space:nowrap;">✦ {title}</span>'
+        f'<div style="flex:1;height:1px;background:{AI_BORDER};"></div>'
+        f'</div>'
+    )
+
+
+# ── Analyst Edge components ───────────────────────────────────────────────────
+
+_DELTA_KIND_META: dict[str, tuple[str, str, str]] = {
+    # kind → (label, fg_color, bg_color)
+    "risk_added":              ("NEW RISK",         "#ef4444", "#fef2f2"),
+    "risk_removed":            ("REMOVED RISK",     "#6b7280", "#f3f4f6"),
+    "risk_reworded":           ("REWORDED RISK",    "#f59e0b", "#fffbeb"),
+    "guidance_language_shift": ("GUIDANCE SHIFT",   "#8b5cf6", "#faf5ff"),
+    "term_frequency":          ("FREQUENCY SHIFT",  "#0ea5e9", "#f0f9ff"),
+    "kpi_dropped":             ("DROPPED KPI",      "#6b7280", "#f3f4f6"),
+}
+
+_SIG_COLORS: dict[str, str] = {"HIGH": "#ef4444", "MEDIUM": "#f59e0b", "LOW": "#9ca3af"}
+
+
+def significance_badge(sig: str) -> str:
+    color = _SIG_COLORS.get(sig, "#9ca3af")
+    return (
+        f'<span style="background:{color}1a;color:{color};border:1px solid {color}44;'
+        f'border-radius:4px;padding:1px 7px;font-size:0.65rem;font-weight:700;'
+        f'text-transform:uppercase;letter-spacing:0.06em;">{sig}</span>'
+    )
+
+
+def _redline_block(before: str, after: str) -> str:
+    """Render before→after text with redline-style color coding."""
+    parts: list[str] = []
+    if before:
+        parts.append(
+            f'<div style="padding:8px 10px;background:#fef2f2;border-left:3px solid #fca5a5;'
+            f'border-radius:0 4px 4px 0;margin-bottom:4px;">'
+            f'<span style="font-size:0.6rem;font-weight:700;text-transform:uppercase;'
+            f'color:#ef4444;letter-spacing:0.07em;">before</span>'
+            f'<div style="font-size:0.78rem;font-style:italic;color:#7f1d1d;line-height:1.45;'
+            f'margin-top:3px;">&ldquo;{before}&rdquo;</div>'
+            f'</div>'
+        )
+    if after:
+        parts.append(
+            f'<div style="padding:8px 10px;background:#ecfdf5;border-left:3px solid #6ee7b7;'
+            f'border-radius:0 4px 4px 0;">'
+            f'<span style="font-size:0.6rem;font-weight:700;text-transform:uppercase;'
+            f'color:#10b981;letter-spacing:0.07em;">after</span>'
+            f'<div style="font-size:0.78rem;font-style:italic;color:#064e3b;line-height:1.45;'
+            f'margin-top:3px;">&ldquo;{after}&rdquo;</div>'
+            f'</div>'
+        )
+    return "".join(parts)
+
+
+def delta_card(delta: dict) -> None:
+    """Render a QuarterDelta as a redline-style card in Streamlit."""
+    kind = delta.get("kind", "")
+    label, fg, bg = _DELTA_KIND_META.get(kind, ("CHANGE", AMBER, WARN_BG))
+    sig = delta.get("significance", "MEDIUM")
+    term = delta.get("term", "")
+    period_from = delta.get("period_from", "")
+    period_to = delta.get("period_to", "")
+    before = delta.get("before_text", "")
+    after = delta.get("after_text", "")
+    metric = delta.get("computed_metric", "")
+    source = delta.get("source", "")
+
+    period_str = f"{period_from} → {period_to}" if period_from and period_to else ""
+    term_str = f" · {term}" if term else ""
+    metric_html = (
+        f'<div style="font-size:0.72rem;font-weight:600;color:#374151;'
+        f'background:#f8fafc;border:1px solid #e2e8f0;border-radius:4px;'
+        f'padding:4px 8px;margin-bottom:8px;">'
+        f'<span style="color:{TEXT_MUTED};font-size:0.65rem;font-weight:500;">'
+        f'computed · </span>{metric}'
+        f'</div>'
+    ) if metric else ""
+
+    st.markdown(
+        f'<div class="primer-card" style="background:{bg};border:1px solid {fg}44;'
+        f'border-left:4px solid {fg};border-radius:0 10px 10px 0;'
+        f'padding:14px 16px;margin-bottom:8px;">'
+        f'<div style="display:flex;align-items:center;gap:6px;margin-bottom:8px;flex-wrap:wrap;">'
+        f'<span style="font-size:0.6rem;font-weight:700;text-transform:uppercase;'
+        f'letter-spacing:0.1em;color:{fg};">{label}{term_str}</span>'
+        f'{significance_badge(sig)}'
+        f'<span style="font-size:0.65rem;color:{TEXT_MUTED};margin-left:auto;">{period_str}</span>'
+        f'{source_badge(source)}'
+        f'</div>'
+        f'{metric_html}'
+        f'{_redline_block(before, after)}'
+        f'</div>',
+        unsafe_allow_html=True,
+    )

dashboard/earnings_call.py

@@ -7,7 +7,7 @@ from dashboard.theme import (
     WARN_BG, WARN_BORDER,
 )
 from dashboard import fmt_period
-from dashboard.components import section_header, evidence_quote
+from dashboard.components import section_header, evidence_quote, reliability_badge, impact_badge
 
 
 def _source_badge(source: str) -> str:
@@ -71,6 +71,10 @@ def render(brief: dict, ticker: str) -> None:
                                 {t.get("summary","")}
                             </div>
                             {evidence_quote(t.get("evidence_snippet",""), bg=BG, border_color=BORDER)}
+                            <div style="margin-top:6px;display:flex;gap:5px;flex-wrap:wrap;align-items:center;">
+                                {reliability_badge(t.get("reliability",""))}
+                                {impact_badge(t.get("impact","") or "")}
+                            </div>
                         </div>
                         """,
                         unsafe_allow_html=True,
@@ -111,7 +115,7 @@ def render(brief: dict, ticker: str) -> None:
             for r in results:
                 m = r["metadata"]
                 context = m.get("chunk_context") or f"transcript · {m.get('date', m.get('filing_date',''))}"
-                with st.expander(f"🎙️ {context}", expanded=True):
+                with st.expander(f"🎙️ {context}", expanded=False):
                     text = r["text"]
                     st.markdown(
                         f'<div style="font-size:0.85rem;line-height:1.8;color:{TEXT};white-space:pre-wrap;">{text}</div>',

dashboard/mda.py

@@ -4,10 +4,9 @@ import streamlit as st
 from dashboard.theme import (
     GREEN, AMBER, RED,
     BG, BG_MUTED, BORDER, TEXT, TEXT_MUTED, TEXT_FAINT,
-    INFO, INFO_BG, INFO_BORDER,
 )
 from dashboard import fmt_period
-from dashboard.components import reliability_badge, source_badge, section_header, evidence_quote, fact_card
+from dashboard.components import reliability_badge, source_badge, impact_badge, section_header, evidence_quote, fact_card, interpretation_card, ai_section_header
 
 
 
@@ -23,44 +22,57 @@ def render(brief: dict, ticker: str) -> None:
         unsafe_allow_html=True,
     )
 
-    # ── Key Quote ────────────────────────────────────────────────────────────
+    # ── AI BAND: Language Shift + Key Quote (côte à côte) ────────────────────
+    lang = mda.get("language_shift", "")
     kq = mda.get("key_quote", {})
-    if kq:
-        with st.expander("🗣️ Key Management Statement", expanded=True):
-            st.markdown(
-                f"""
-                <div class="primer-card" style="background:{BG_MUTED};border:1px solid {BORDER};
-                            border-radius:12px;padding:18px 20px;margin-bottom:16px;">
-                    <div style="font-size:1.05rem;font-style:italic;line-height:1.6;
-                                margin-bottom:8px;color:{TEXT};">
-                        "{kq.get("evidence_snippet","")}"
-                    </div>
-                    <div style="font-size:0.85rem;color:{TEXT_MUTED};margin-bottom:8px;">{kq.get("text","")}</div>
-                    <div>
-                        {reliability_badge(kq.get("reliability",""))}
-                        &nbsp;{source_badge(kq.get("source",""))}
-                    </div>
-                </div>
-                """,
-                unsafe_allow_html=True,
-            )
 
-    # ── Language Shift ────────────────────────────────────────────────────────
-    lang = mda.get("language_shift", "")
-    if lang:
-        with st.expander("🔀 Language Shift vs Prior Periods", expanded=True):
-            st.markdown(
-                f"""
-                <div class="primer-card" style="background:{INFO_BG};border:1px solid {INFO_BORDER};
-                            border-radius:10px;padding:16px 18px;margin-bottom:16px;">
-                    <div style="font-size:0.9rem;line-height:1.6;color:{TEXT};">{lang}</div>
-                </div>
-                """,
-                unsafe_allow_html=True,
-            )
+    if lang or kq:
+        st.markdown(ai_section_header("AI Interpretation"), unsafe_allow_html=True)
+        col_lang, col_kq = st.columns(2)
+
+        with col_lang:
+            if lang:
+                st.markdown(
+                    interpretation_card(
+                        "Language shift vs prior periods",
+                        f'<div style="font-size:0.9rem;line-height:1.6;color:{TEXT};">{lang}</div>',
+                    ),
+                    unsafe_allow_html=True,
+                )
+
+        with col_kq:
+            if kq:
+                st.markdown(
+                    f'<div class="primer-card" style="background:{BG_MUTED};border:1px solid {BORDER};'
+                    f'border-radius:12px;padding:18px 20px;">'
+                    f'<div style="font-size:0.62rem;font-weight:700;letter-spacing:0.1em;'
+                    f'text-transform:uppercase;color:{TEXT_MUTED};margin-bottom:8px;">Key management statement</div>'
+                    f'<div style="font-size:0.98rem;font-style:italic;line-height:1.6;'
+                    f'margin-bottom:8px;color:{TEXT};">"{kq.get("evidence_snippet","")}"</div>'
+                    f'<div style="font-size:0.82rem;color:{TEXT_MUTED};margin-bottom:8px;">'
+                    f'{kq.get("text","")}</div>'
+                    f'<div style="display:flex;gap:5px;flex-wrap:wrap;align-items:center;">'
+                    f'{reliability_badge(kq.get("reliability",""))}'
+                    f'{source_badge(kq.get("source",""))}'
+                    f'{impact_badge(kq.get("impact","") or "")}'
+                    f'</div>'
+                    f'</div>',
+                    unsafe_allow_html=True,
+                )
 
-    # ── Drivers & Headwinds ───────────────────────────────────────────────────
-    with st.expander("📈 Revenue & Margin Drivers / 📉 Headwinds & Drags", expanded=True):
+    # ── Drivers & Headwinds (ouvert par défaut, sans expander) ────────────────
+    drivers = mda.get("drivers", [])
+    headwinds = mda.get("headwinds", [])
+    if drivers or headwinds:
+        st.markdown(
+            f'<div style="display:flex;align-items:center;gap:10px;margin:24px 0 12px;">'
+            f'<span style="font-size:0.65rem;font-weight:700;letter-spacing:0.1em;'
+            f'text-transform:uppercase;color:{TEXT_MUTED};white-space:nowrap;">'
+            f'Drivers & Headwinds</span>'
+            f'<div style="flex:1;height:1px;background:{BORDER};"></div>'
+            f'</div>',
+            unsafe_allow_html=True,
+        )
         col_d, col_h = st.columns(2)
 
         with col_d:
@@ -69,7 +81,7 @@ def render(brief: dict, ticker: str) -> None:
                 f'letter-spacing:0.08em;margin-bottom:8px;">📈 REVENUE & MARGIN DRIVERS</div>',
                 unsafe_allow_html=True,
             )
-            for fact in mda.get("drivers", []):
+            for fact in drivers:
                 fact_card(fact, accent=GREEN)
 
         with col_h:
@@ -78,7 +90,7 @@ def render(brief: dict, ticker: str) -> None:
                 f'letter-spacing:0.08em;margin-bottom:8px;">📉 HEADWINDS & DRAGS</div>',
                 unsafe_allow_html=True,
             )
-            for fact in mda.get("headwinds", []):
+            for fact in headwinds:
                 fact_card(fact, accent=RED)
 
     # ── Source Text Browser ───────────────────────────────────────────────────
@@ -116,7 +128,7 @@ def render(brief: dict, ticker: str) -> None:
             for r in results:
                 m = r["metadata"]
                 context = m.get("chunk_context") or f"{m.get('source','filing')} · {m.get('section','')} · {m.get('filing_date','')}"
-                with st.expander(f"📄 {context}", expanded=True):
+                with st.expander(f"📄 {context}", expanded=False):
                     st.markdown(
                         f'<div style="font-size:0.85rem;line-height:1.7;color:{TEXT};">{r["text"]}</div>',
                         unsafe_allow_html=True,

dashboard/risks.py

@@ -6,7 +6,7 @@ from dashboard.theme import (
     BG, BG_MUTED, BORDER, TEXT, TEXT_MUTED, TEXT_FAINT,
     WARN_BG, WARN_BORDER,
 )
-from dashboard.components import reliability_badge, source_badge, section_header
+from dashboard.components import reliability_badge, source_badge, impact_badge, section_header
 
 _CATEGORY_COLORS = {
     "Regulatory": "#8b5cf6",
@@ -43,20 +43,49 @@ def render(brief: dict, ticker: str) -> None:
         _render_risk_search(ticker)
         return
 
-    new_count = sum(1 for r in risks if r.get("is_new_this_filing"))
-    if new_count:
+    new_risks = [r for r in risks if r.get("is_new_this_filing")]
+    if new_risks:
         st.markdown(
-            f"""
-            <div style="background:{WARN_BG};border:1px solid {WARN_BORDER};
-                        border-radius:10px;padding:12px 16px;margin-bottom:16px;">
-                <span style="color:{AMBER};font-weight:700;">
-                    ⚠ {new_count} new or materially escalated risk{"s" if new_count > 1 else ""}
-                </span>
-                <span style="color:{TEXT_MUTED};font-size:0.85rem;margin-left:8px;">
-                    flagged in the latest filing vs prior periods
-                </span>
-            </div>
-            """,
+            f'<div style="font-size:0.72rem;color:{RED};font-weight:700;'
+            f'letter-spacing:0.08em;margin-bottom:10px;">🆕 NEW THIS FILING ({len(new_risks)})</div>',
+            unsafe_allow_html=True,
+        )
+        for r in new_risks:
+            cat = r.get("category", "Other")
+            color = _CATEGORY_COLORS.get(cat, GRAY)
+            icon = _CATEGORY_ICONS.get(cat, "●")
+            new_badge = (
+                f'<span style="background:#fef2f2;color:{RED};border:1px solid #fecaca;'
+                f'border-radius:4px;padding:1px 7px;font-size:0.7rem;font-weight:700;">NEW ↑</span>'
+            )
+            cat_chip = (
+                f'<span style="background:{color}18;color:{color};border:1px solid {color}33;'
+                f'border-radius:4px;padding:1px 7px;font-size:0.68rem;font-weight:600;">'
+                f'{icon} {cat}</span>'
+            )
+            st.markdown(
+                f'<div class="primer-card" style="background:{WARN_BG};border:1px solid {WARN_BORDER};'
+                f'border-left:3px solid {RED};border-radius:0 10px 10px 0;'
+                f'padding:16px 20px;margin-bottom:8px;">'
+                f'<div style="display:flex;align-items:center;gap:8px;margin-bottom:8px;">'
+                f'{new_badge}{cat_chip}'
+                f'</div>'
+                f'<div style="font-size:0.9rem;line-height:1.5;margin-bottom:6px;color:{TEXT};">'
+                f'{r.get("text","")}</div>'
+                f'<div style="margin-top:4px;display:flex;gap:5px;flex-wrap:wrap;align-items:center;">'
+                f'{reliability_badge(r.get("reliability",""))}'
+                f'{source_badge(r.get("source",""))}'
+                f'{impact_badge(r.get("impact","") or "")}'
+                f'</div>'
+                f'</div>',
+                unsafe_allow_html=True,
+            )
+        st.markdown(
+            f'<div style="display:flex;align-items:center;gap:10px;margin:20px 0 12px;">'
+            f'<span style="font-size:0.65rem;font-weight:700;letter-spacing:0.1em;'
+            f'text-transform:uppercase;color:{TEXT_MUTED};white-space:nowrap;">All risks by category</span>'
+            f'<div style="flex:1;height:1px;background:{BORDER};"></div>'
+            f'</div>',
             unsafe_allow_html=True,
         )
 
@@ -94,9 +123,10 @@ def render(brief: dict, ticker: str) -> None:
                     <div style="font-size:0.9rem;line-height:1.5;margin-bottom:6px;color:{TEXT};">
                         {r.get("text","")} {new_badge}
                     </div>
-                    <div style="margin-top:4px;">
+                    <div style="margin-top:4px;display:flex;gap:5px;flex-wrap:wrap;align-items:center;">
                         {reliability_badge(r.get("reliability",""))}
-                        &nbsp;{source_badge(r.get("source",""))}
+                        {source_badge(r.get("source",""))}
+                        {impact_badge(r.get("impact","") or "")}
                     </div>
                 </div>
                 """,
@@ -124,7 +154,7 @@ def _render_risk_search(ticker: str) -> None:
             for r in results:
                 m = r["metadata"]
                 context = m.get("chunk_context") or f"{m.get('source','filing')} · {m.get('section','')} · {m.get('filing_date','')}"
-                with st.expander(f"📄 {context}", expanded=True):
+                with st.expander(f"📄 {context}", expanded=False):
                     st.markdown(
                         f'<div style="font-size:0.85rem;line-height:1.7;color:{TEXT};">{r["text"]}</div>',
                         unsafe_allow_html=True,

dashboard/theme.py

@@ -40,6 +40,18 @@ INFO_BORDER = "#bfdbfe"
 
 GRAY = "#6b7280"
 PURPLE = "#8b5cf6"
+AI_BG = "#faf5ff"
+AI_BORDER = "#ddd6fe"
+AI_COLOR = "#7c3aed"
+AI_BADGE_BG = "#ede9fe"
+
+IMPACT_HIGH_BG = "#0f172a"     # slate-900
+IMPACT_HIGH_TEXT = "#ffffff"
+IMPACT_MED_BG = "#64748b"      # slate-500
+IMPACT_MED_TEXT = "#ffffff"
+IMPACT_LOW_BG = "transparent"
+IMPACT_LOW_TEXT = "#94a3b8"    # slate-400
+IMPACT_LOW_BORDER = "#cbd5e1"  # slate-300
 
 # ── Plotly rgba aliases ───────────────────────────────────────────────────────
 GREEN_A53 = "rgba(16,185,129,0.53)"
@@ -245,9 +257,60 @@ def inject_global_css() -> None:
             border-radius: 8px !important;
         }
 
+        /* ── Sidebar nav group separators ──────────────────────────────────── */
+        /* Labels with group headers need flex-wrap so ::before spans full row */
+        [data-testid="stSidebar"] [data-testid="stRadio"] label:nth-child(1),
+        [data-testid="stSidebar"] [data-testid="stRadio"] label:nth-child(3),
+        [data-testid="stSidebar"] [data-testid="stRadio"] label:nth-child(6) {
+            flex-wrap: wrap !important;
+        }
+
+        /* Before Verdict (1st item) — "BRIEF" group label */
+        [data-testid="stSidebar"] [data-testid="stRadio"] label:nth-child(1)::before {
+            content: "BRIEF";
+            flex: 0 0 100%;
+            font-size: 0.55rem !important;
+            font-weight: 700 !important;
+            text-transform: uppercase;
+            letter-spacing: 0.1em;
+            color: #9ca3af;
+            padding: 0 0 4px 2px;
+            pointer-events: none;
+        }
+        /* Before MD&A (3rd item) — "DEEP DIVE" group */
+        [data-testid="stSidebar"] [data-testid="stRadio"] label:nth-child(3) {
+            margin-top: 10px !important;
+        }
+        [data-testid="stSidebar"] [data-testid="stRadio"] label:nth-child(3)::before {
+            content: "DEEP DIVE";
+            flex: 0 0 100%;
+            font-size: 0.55rem !important;
+            font-weight: 700 !important;
+            text-transform: uppercase;
+            letter-spacing: 0.1em;
+            color: #9ca3af;
+            padding: 0 0 4px 2px;
+            pointer-events: none;
+        }
+        /* Before Guidance (6th item) — "FORWARD" group */
+        [data-testid="stSidebar"] [data-testid="stRadio"] label:nth-child(6) {
+            margin-top: 10px !important;
+        }
+        [data-testid="stSidebar"] [data-testid="stRadio"] label:nth-child(6)::before {
+            content: "FORWARD";
+            flex: 0 0 100%;
+            font-size: 0.55rem !important;
+            font-weight: 700 !important;
+            text-transform: uppercase;
+            letter-spacing: 0.1em;
+            color: #9ca3af;
+            padding: 0 0 4px 2px;
+            pointer-events: none;
+        }
+
         /* ── Content max-width ──────────────────────────────────────────────── */
         .main .block-container {
-            max-width: 960px !important;
+            max-width: 1200px !important;
             padding-top: 24px !important;
         }
         </style>

dashboard/verdict.py

@@ -7,8 +7,13 @@ from dashboard.theme import (
     BG, BG_MUTED, BORDER, TEXT, TEXT_MUTED,
     BULL_BG, BULL_BORDER, BEAR_BG, BEAR_BORDER,
     WARN_BG, WARN_BORDER,
+    AI_COLOR, AI_BORDER,
+)
+from dashboard.components import (
+    reliability_badge, source_badge, impact_badge, section_header, evidence_quote,
+    fact_card, tension_card, quality_signal_chip, interpretation_card,
+    stat_chip, ai_section_header, delta_card,
 )
-from dashboard.components import reliability_badge, source_badge, section_header, evidence_quote, fact_card, tension_card, quality_signal_chip
 from analytics.deltas import build_quarter_snapshot
 from dashboard import earnings_snapshot, reasoning as reasoning_panel
 
@@ -232,70 +237,218 @@ def _render_market_expectations(me: dict) -> None:
         )
 
 
-def _render_analytical_edge(brief: dict) -> None:
-    """Render the Analytical Edge section: non_obvious_takeaway, tensions, quality signals."""
-    takeaway = brief.get("non_obvious_takeaway", "")
-    tensions = [t for t in (brief.get("analytical_tensions") or []) if isinstance(t, dict)]
-    signals = [s for s in (brief.get("earnings_quality_signals") or []) if isinstance(s, dict)]
+def _render_hero_band(brief: dict) -> None:
+    """Hero band: standout number (left) + market reaction chips (right)."""
+    sn = brief.get("standout_number") or {}
+    me = brief.get("market_expectations") or {}
 
-    if not takeaway and not tensions and not signals:
+    has_sn = bool(sn.get("text"))
+    has_me = any(me.get(k) is not None for k in (
+        "d1_price_reaction_pct", "d5_price_reaction_pct",
+        "revision_30d_pct", "consensus_eps_est", "consensus_rev_est_bn",
+    ))
+
+    if not has_sn and not has_me:
         return
 
-    with st.expander("🔍 Analytical Edge", expanded=True):
-        # ── Non-obvious takeaway ──────────────────────────────────────────────
-        if takeaway:
+    col_sn, col_me = st.columns([3, 2])
+
+    with col_sn:
+        if has_sn:
             st.markdown(
-                f'<div class="primer-card" style="background:{BG_MUTED};border:1px solid {BORDER};'
-                f'border-left:4px solid {GREEN};border-radius:0 10px 10px 0;'
-                f'padding:16px 20px;margin-bottom:16px;">'
-                f'<div style="font-size:0.58rem;font-weight:700;text-transform:uppercase;'
-                f'letter-spacing:0.1em;color:{TEXT_MUTED};margin-bottom:6px;">Non-obvious takeaway</div>'
-                f'<div style="font-size:0.95rem;font-style:italic;line-height:1.65;color:{TEXT};">'
-                f'{takeaway}'
+                f'<div class="primer-card" style="background:{BG};border:1px solid {BORDER};'
+                f'border-left:4px solid {GREEN};border-radius:12px;padding:20px 24px;">'
+                f'<div style="font-size:0.58rem;font-weight:700;letter-spacing:0.1em;'
+                f'text-transform:uppercase;color:{TEXT_MUTED};margin-bottom:8px;">The number that matters</div>'
+                f'<div style="font-size:1.3rem;font-weight:700;line-height:1.4;'
+                f'margin-bottom:12px;color:{TEXT};">{sn.get("text","")}</div>'
+                f'{evidence_quote(sn.get("evidence_snippet",""), bg=BG_MUTED, border_color=BORDER)}'
+                f'<div style="margin-top:10px;display:flex;gap:5px;flex-wrap:wrap;align-items:center;">'
+                f'{reliability_badge(sn.get("reliability",""))}'
+                f'{source_badge(sn.get("source",""))}'
+                f'{impact_badge(sn.get("impact","") or "")}'
                 f'</div>'
                 f'</div>',
                 unsafe_allow_html=True,
             )
 
-        # ── Tensions ──────────────────────────────────────────────────────────
-        tension_count = len(tensions)
-        tension_label = (
-            f"Reading between the lines · {tension_count} tension{'s' if tension_count != 1 else ''}"
-            if tension_count else "Reading between the lines"
+    with col_me:
+        if has_me:
+            d1 = me.get("d1_price_reaction_pct")
+            d5 = me.get("d5_price_reaction_pct")
+            rev30 = me.get("revision_30d_pct")
+            eps = me.get("consensus_eps_est")
+            rev_bn = me.get("consensus_rev_est_bn")
+
+            def _tone(v, *, flip: bool = False) -> str:
+                if v is None:
+                    return "neutral"
+                positive = v >= 0 if not flip else v <= 0
+                return "positive" if positive else "negative"
+
+            def _fmt_pct(v) -> str:
+                return f"{v:+.1f}%" if v is not None else "N/A"
+
+            def _fmt_rev30(v) -> str:
+                if v is None:
+                    return "N/A"
+                arrow = " ▲" if v >= 1.0 else (" ▼" if v <= -1.0 else " →")
+                return f"{v:+.1f}%{arrow}"
+
+            cons_parts = []
+            if eps is not None:
+                cons_parts.append(f"EPS ${eps:.2f}")
+            if rev_bn is not None:
+                cons_parts.append(f"Rev ${rev_bn:.1f}B")
+            cons_str = " · ".join(cons_parts) if cons_parts else None
+
+            # Only include chips whose value is available — never render "N/A" here.
+            visible_chips = []
+            if d1 is not None:
+                visible_chips.append(stat_chip("D1 reaction", _fmt_pct(d1), _tone(d1)))
+            if d5 is not None:
+                visible_chips.append(stat_chip("D5 reaction", _fmt_pct(d5), _tone(d5)))
+            if rev30 is not None:
+                visible_chips.append(stat_chip("Est. rev 30d", _fmt_rev30(rev30), _tone(rev30)))
+            if cons_str is not None:
+                visible_chips.append(stat_chip("Consensus", cons_str, "neutral"))
+
+            if visible_chips:
+                cols = 2 if len(visible_chips) > 1 else 1
+                chips_html = (
+                    f'<div style="display:grid;grid-template-columns:{"1fr " * cols};gap:8px;">'
+                    + "".join(visible_chips)
+                    + "</div>"
+                )
+                st.markdown(
+                    f'<div style="padding:20px 24px;background:{BG};border:1px solid {BORDER};'
+                    f'border-radius:12px;">'
+                    f'<div style="font-size:0.58rem;font-weight:700;letter-spacing:0.1em;'
+                    f'text-transform:uppercase;color:{TEXT_MUTED};margin-bottom:10px;">Market pulse</div>'
+                    f'{chips_html}'
+                    f'</div>',
+                    unsafe_allow_html=True,
+                )
+
+
+def _render_ai_synthesis_band(brief: dict) -> None:
+    """Lavender AI section: what matters most + non-obvious takeaway."""
+    wmm = brief.get("what_matters_most", "")
+    takeaway = brief.get("non_obvious_takeaway", "")
+
+    if not wmm and not takeaway:
+        return
+
+    st.markdown(ai_section_header("AI Synthesis"), unsafe_allow_html=True)
+
+    if wmm:
+        st.markdown(
+            interpretation_card(
+                "What matters most",
+                f'<div style="font-size:1rem;line-height:1.7;color:{TEXT};">{wmm}</div>',
+            ),
+            unsafe_allow_html=True,
+        )
+    if takeaway:
+        st.markdown(
+            interpretation_card(
+                "Non-obvious takeaway",
+                f'<div style="font-size:0.95rem;font-style:italic;line-height:1.65;color:{TEXT};">'
+                f'{takeaway}</div>',
+            ),
+            unsafe_allow_html=True,
+        )
+
+
+def _render_ai_deeper_band(brief: dict) -> None:
+    """Lavender AI section: analytical tensions + earnings quality signals."""
+    tensions = [t for t in (brief.get("analytical_tensions") or []) if isinstance(t, dict)]
+    signals = [s for s in (brief.get("earnings_quality_signals") or []) if isinstance(s, dict)]
+
+    if not tensions and not signals:
+        return
+
+    st.markdown(ai_section_header("Conflicting Readings & Quality"), unsafe_allow_html=True)
+
+    if tensions:
+        for t in tensions:
+            tension_card(t)
+    else:
+        st.markdown(
+            f'<div style="display:inline-flex;align-items:center;gap:6px;'
+            f'background:{BG_MUTED};border:1px solid {BORDER};border-radius:6px;'
+            f'padding:6px 12px;margin-bottom:12px;">'
+            f'<span style="font-size:0.72rem;color:{TEXT_MUTED};">✓</span>'
+            f'<span style="font-size:0.78rem;color:{TEXT_MUTED};">'
+            f'Numbers and narrative cohere — no material tensions detected this quarter'
+            f'</span>'
+            f'</div>',
+            unsafe_allow_html=True,
         )
+
+    if signals:
         st.markdown(
             f'<div style="font-size:0.68rem;font-weight:700;text-transform:uppercase;'
-            f'letter-spacing:0.1em;color:{TEXT_MUTED};margin-bottom:10px;">{tension_label}</div>',
+            f'letter-spacing:0.1em;color:{TEXT_MUTED};margin:14px 0 8px;">Earnings quality signals</div>',
+            unsafe_allow_html=True,
+        )
+        chips_html = "".join(quality_signal_chip(s) for s in signals)
+        st.markdown(
+            f'<div style="display:flex;flex-wrap:wrap;gap:0;">{chips_html}</div>',
             unsafe_allow_html=True,
         )
-        if tensions:
-            for t in tensions:
-                tension_card(t)
-        else:
-            st.markdown(
-                f'<div style="display:inline-flex;align-items:center;gap:6px;'
-                f'background:{BG_MUTED};border:1px solid {BORDER};border-radius:6px;'
-                f'padding:6px 12px;margin-bottom:12px;">'
-                f'<span style="font-size:0.72rem;color:{TEXT_MUTED};">✓</span>'
-                f'<span style="font-size:0.78rem;color:{TEXT_MUTED};">'
-                f'Numbers and narrative cohere — no material tensions detected this quarter'
-                f'</span>'
-                f'</div>',
-                unsafe_allow_html=True,
-            )
 
-        # ── Earnings quality signals ────��─────────────────────────────────────
-        if signals:
-            st.markdown(
-                f'<div style="font-size:0.68rem;font-weight:700;text-transform:uppercase;'
-                f'letter-spacing:0.1em;color:{TEXT_MUTED};margin:14px 0 8px;">Earnings quality signals</div>',
-                unsafe_allow_html=True,
-            )
-            chips_html = "".join(quality_signal_chip(s) for s in signals)
-            st.markdown(
-                f'<div style="display:flex;flex-wrap:wrap;gap:0;">{chips_html}</div>',
-                unsafe_allow_html=True,
-            )
+
+_DELTA_KIND_GROUPS: dict[str, str] = {
+    "risk_added":              "Risk Changes",
+    "risk_removed":            "Risk Changes",
+    "risk_reworded":           "Risk Changes",
+    "guidance_language_shift": "Language Shifts",
+    "term_frequency":          "Frequency Shifts",
+    "kpi_dropped":             "Dropped KPIs",
+}
+
+
+def _render_analyst_edge(brief: dict) -> None:
+    """Render the Analyst Edge panel — deterministic signals, above the brief."""
+    deltas = brief.get("quarter_deltas") or []
+    if not deltas:
+        return
+
+    # Group by kind category
+    groups: dict[str, list[dict]] = {}
+    for d in deltas:
+        group = _DELTA_KIND_GROUPS.get(d.get("kind", ""), "Other")
+        groups.setdefault(group, []).append(d)
+
+    # Section divider
+    st.markdown(
+        f'<div style="display:flex;align-items:center;gap:12px;margin:4px 0 14px;">'
+        f'<span style="font-size:0.68rem;font-weight:700;text-transform:uppercase;'
+        f'letter-spacing:0.14em;color:#0f172a;white-space:nowrap;">⚡ ANALYST EDGE</span>'
+        f'<div style="flex:1;height:2px;background:linear-gradient(90deg,#0f172a,transparent);'
+        f'border-radius:2px;"></div>'
+        f'<span style="font-size:0.65rem;color:#6b7280;">'
+        f'deterministic · {len(deltas)} signal{"s" if len(deltas) != 1 else ""}'
+        f'</span>'
+        f'</div>',
+        unsafe_allow_html=True,
+    )
+
+    # High-significance signals get full cards; lower-sig ones are collapsed
+    high_signals = [d for d in deltas if d.get("significance") == "HIGH"]
+    other_signals = [d for d in deltas if d.get("significance") != "HIGH"]
+
+    if high_signals:
+        for d in high_signals:
+            delta_card(d)
+
+    if other_signals:
+        with st.expander(f"Show {len(other_signals)} more signal(s) (MEDIUM / LOW)", expanded=False):
+            for d in other_signals:
+                delta_card(d)
+
+    st.markdown('<div style="margin-bottom:28px;"></div>', unsafe_allow_html=True)
 
 
 def render(brief: dict) -> None:
@@ -307,174 +460,146 @@ def render(brief: dict) -> None:
         unsafe_allow_html=True,
     )
 
-    # ── Reasoning trace (collapsed) ───────────────────────────────────────────
-    trace = st.session_state.get("reasoning_trace", {}).get(ticker)
-    if trace:
-        reasoning_panel.render(trace)
+    # ── ANALYST EDGE PANEL — deterministic signals, rendered first ────────────
+    _render_analyst_edge(brief)
 
-    # ── Analytical Edge (tensions, quality signals, non-obvious takeaway) ─────
-    _render_analytical_edge(brief)
+    # ── HERO BAND: standout number + market pulse ─────────────────────────────
+    _render_hero_band(brief)
 
-    # ═══════════════════════════════════════════════════════════════════════════
-    # THE 5 ANSWERS  (what the task asks for, surfaced first)
-    # ═══════════════════════════════════════════════════════════════════════════
+    # ── AI SYNTHESIS BAND: what matters most + non-obvious takeaway ───────────
+    _render_ai_synthesis_band(brief)
 
-    # ── What changed ──────────────────────────────────────────────────────────
-    what_changed = [wc for wc in brief.get("what_changed", []) if isinstance(wc, dict)]
-    if what_changed:
-        with st.expander(
-            f"📋 What changed ({len(what_changed)} item{'s' if len(what_changed) != 1 else ''})",
-            expanded=True,
-        ):
-            for fc in what_changed:
-                fact_card(fc, accent=AMBER)
-
-    # ── What matters most ─────────────────────────────────────────────────────
-    wmm = brief.get("what_matters_most", "")
-    if wmm:
-        with st.expander("💡 What matters most", expanded=True):
-            st.markdown(
-                f"""
-                <div class="primer-card" style="background:{BG_MUTED};border:1px solid {BORDER};
-                            border-radius:12px;padding:20px 24px;margin-bottom:4px;">
-                    <div style="font-size:0.62rem;font-weight:700;letter-spacing:0.1em;
-                                text-transform:uppercase;color:{TEXT_MUTED};margin-bottom:8px;">
-                        AI synthesis · the only interpretive field
-                    </div>
-                    <div style="font-size:1rem;line-height:1.7;color:{TEXT};">{wmm}</div>
-                </div>
-                """,
-                unsafe_allow_html=True,
-            )
+    # ── AI DEEPER BAND: analytical tensions + quality signals ─────────────────
+    _render_ai_deeper_band(brief)
 
-    # ── Bull points ───────────────────────────────────────────────────────────
+    # ── BULL / BEAR — paired rows so cards align horizontally ─────────────────
     bulls = [b for b in brief.get("bull_points", []) if isinstance(b, dict)]
-    if bulls:
-        with st.expander(f"🐂 Bull points ({len(bulls)})", expanded=True):
-            for pt in bulls:
+    bears = [b for b in brief.get("bear_points", []) if isinstance(b, dict)]
+    if bulls or bears:
+        hcols = st.columns(2)
+        hcols[0].markdown(
+            f'<div style="font-size:0.72rem;color:{GREEN};font-weight:700;'
+            f'letter-spacing:0.08em;margin-bottom:10px;">🐂 BULL POINTS ({len(bulls)})</div>',
+            unsafe_allow_html=True,
+        )
+        hcols[1].markdown(
+            f'<div style="font-size:0.72rem;color:{RED};font-weight:700;'
+            f'letter-spacing:0.08em;margin-bottom:10px;">🐻 BEAR POINTS ({len(bears)})</div>',
+            unsafe_allow_html=True,
+        )
+        for i in range(max(len(bulls), len(bears))):
+            row = st.columns(2)
+            with row[0]:
+                if i < len(bulls):
+                    pt = bulls[i]
+                    st.markdown(
+                        f'<div class="primer-card" style="background:{BULL_BG};border:1px solid {BULL_BORDER};'
+                        f'border-radius:10px;padding:16px 18px;margin-bottom:8px;">'
+                        f'<div style="font-size:0.88rem;line-height:1.55;margin-bottom:10px;color:{TEXT};">'
+                        f'{pt.get("text","")}</div>'
+                        f'{evidence_quote(pt.get("evidence_snippet",""), bg=BG, border_color=BULL_BORDER)}'
+                        f'<div style="margin-top:8px;display:flex;gap:5px;flex-wrap:wrap;align-items:center;">'
+                        f'{reliability_badge(pt.get("reliability",""))}'
+                        f'{source_badge(pt.get("source",""))}'
+                        f'{impact_badge(pt.get("impact","") or "")}'
+                        f'</div></div>',
+                        unsafe_allow_html=True,
+                    )
+            with row[1]:
+                if i < len(bears):
+                    pt = bears[i]
+                    st.markdown(
+                        f'<div class="primer-card" style="background:{BEAR_BG};border:1px solid {BEAR_BORDER};'
+                        f'border-radius:10px;padding:16px 18px;margin-bottom:8px;">'
+                        f'<div style="font-size:0.88rem;line-height:1.55;margin-bottom:10px;color:{TEXT};">'
+                        f'{pt.get("text","")}</div>'
+                        f'{evidence_quote(pt.get("evidence_snippet",""), bg=BG, border_color=BEAR_BORDER)}'
+                        f'<div style="margin-top:8px;display:flex;gap:5px;flex-wrap:wrap;align-items:center;">'
+                        f'{reliability_badge(pt.get("reliability",""))}'
+                        f'{source_badge(pt.get("source",""))}'
+                        f'{impact_badge(pt.get("impact","") or "")}'
+                        f'</div></div>',
+                        unsafe_allow_html=True,
+                    )
+
+    # ── WHAT CHANGED / WHAT TO WATCH NEXT — side by side ─────────────────────
+    what_changed = [wc for wc in brief.get("what_changed", []) if isinstance(wc, dict)]
+    wtw = brief.get("what_to_watch", [])
+    if what_changed or wtw:
+        col_changed, col_watch = st.columns(2)
+        with col_changed:
+            if what_changed:
                 st.markdown(
-                    f"""
-                    <div class="primer-card" style="background:{BULL_BG};border:1px solid {BULL_BORDER};
-                                border-radius:10px;padding:16px 18px;margin-bottom:8px;">
-                        <div style="font-size:0.88rem;line-height:1.55;margin-bottom:10px;color:{TEXT};">
-                            {pt.get("text","")}
-                        </div>
-                        {evidence_quote(pt.get("evidence_snippet",""), bg=BG, border_color=BULL_BORDER)}
-                        <div style="margin-top:8px;display:flex;gap:6px;align-items:center;">
-                            {reliability_badge(pt.get("reliability",""))} {source_badge(pt.get("source",""))}
-                        </div>
-                    </div>
-                    """,
+                    f'<div style="font-size:0.72rem;color:{AMBER};font-weight:700;'
+                    f'letter-spacing:0.08em;margin-bottom:10px;">'
+                    f'📋 WHAT CHANGED ({len(what_changed)})</div>',
                     unsafe_allow_html=True,
                 )
-
-    # ── Bear points ───────────────────────────────────────────────────────────
-    bears = [b for b in brief.get("bear_points", []) if isinstance(b, dict)]
-    if bears:
-        with st.expander(f"🐻 Bear points ({len(bears)})", expanded=True):
-            for pt in bears:
+                for fc in what_changed:
+                    fact_card(fc, accent=AMBER)
+        with col_watch:
+            if wtw:
                 st.markdown(
-                    f"""
-                    <div class="primer-card" style="background:{BEAR_BG};border:1px solid {BEAR_BORDER};
-                                border-radius:10px;padding:16px 18px;margin-bottom:8px;">
-                        <div style="font-size:0.88rem;line-height:1.55;margin-bottom:10px;color:{TEXT};">
-                            {pt.get("text","")}
-                        </div>
-                        {evidence_quote(pt.get("evidence_snippet",""), bg=BG, border_color=BEAR_BORDER)}
-                        <div style="margin-top:8px;display:flex;gap:6px;align-items:center;">
-                            {reliability_badge(pt.get("reliability",""))} {source_badge(pt.get("source",""))}
-                        </div>
-                    </div>
-                    """,
+                    f'<div style="font-size:0.72rem;color:{GREEN};font-weight:700;'
+                    f'letter-spacing:0.08em;margin-bottom:10px;">'
+                    f'🔭 WHAT TO WATCH ({len(wtw)})</div>',
                     unsafe_allow_html=True,
                 )
-
-    # ── What to watch next ────────────────────────────────────────────────────
-    wtw = brief.get("what_to_watch", [])
-    if wtw:
-        with st.expander(f"🔭 What to watch next ({len(wtw)})", expanded=True):
-            items_html = ""
-            for i, item in enumerate(wtw, 1):
-                items_html += (
-                    f'<div style="display:flex;align-items:flex-start;gap:12px;'
-                    f'padding:12px 0;border-bottom:1px solid {BORDER};">'
-                    f'<span style="display:inline-flex;align-items:center;justify-content:center;'
-                    f'width:22px;height:22px;border-radius:50%;flex-shrink:0;margin-top:1px;'
-                    f'background:{GREEN};color:#fff;font-size:0.7rem;font-weight:700;">'
-                    f'{i}'
-                    f'</span>'
-                    f'<span style="font-size:0.9rem;line-height:1.55;color:{TEXT};">{item}</span>'
-                    f'</div>'
+                items_html = ""
+                for i, item in enumerate(wtw, 1):
+                    items_html += (
+                        f'<div style="display:flex;align-items:flex-start;gap:12px;'
+                        f'padding:12px 0;border-bottom:1px solid {BORDER};">'
+                        f'<span style="display:inline-flex;align-items:center;justify-content:center;'
+                        f'width:22px;height:22px;border-radius:50%;flex-shrink:0;margin-top:1px;'
+                        f'background:{GREEN};color:#fff;font-size:0.7rem;font-weight:700;">{i}</span>'
+                        f'<span style="font-size:0.9rem;line-height:1.55;color:{TEXT};">{item}</span>'
+                        f'</div>'
+                    )
+                st.markdown(
+                    f'<div style="border:1px solid {BORDER};border-radius:12px;'
+                    f'padding:4px 16px;background:{BG};">{items_html}</div>',
+                    unsafe_allow_html=True,
                 )
-            st.markdown(
-                f'<div style="border:1px solid {BORDER};border-radius:12px;'
-                f'padding:4px 16px;background:{BG};">'
-                f'{items_html}'
-                f'</div>',
-                unsafe_allow_html=True,
-            )
 
-    # ═══════════════════════════════════════════════════════════════════════════
-    # SUPPORTING DATA  (numbers & context behind the 5 answers above)
-    # ═══════════════════════════════════════════════════════��═══════════════════
-    st.markdown(_section_divider("Supporting data"), unsafe_allow_html=True)
+    # ── SENTIMENT ─────────────────────────────────────────────────────────────
+    with st.expander("📡 Sentiment", expanded=False):
+        _render_sentiment_panel(brief.get("sentiment"))
 
-    # ── Standout number ────────────────────────────────────────────────────────
-    sn = brief.get("standout_number", {})
-    if sn:
-        with st.expander("🔢 Key figure", expanded=True):
-            st.markdown(
-                f"""
-                <div class="primer-card" style="background:{BG};border:1px solid {BORDER};
-                            border-left:4px solid {GREEN};border-radius:12px;
-                            padding:20px 24px;margin-bottom:4px;">
-                    <div style="font-size:0.62rem;font-weight:700;letter-spacing:0.1em;
-                                text-transform:uppercase;color:{TEXT_MUTED};margin-bottom:10px;">
-                        The number that matters
-                    </div>
-                    <div style="font-size:1.2rem;font-weight:700;line-height:1.5;
-                                margin-bottom:12px;color:{TEXT};">
-                        {sn.get("text", "")}
-                    </div>
-                    {evidence_quote(sn.get("evidence_snippet",""), bg=BG_MUTED, border_color=BORDER)}
-                    <div style="margin-top:10px;display:flex;gap:6px;align-items:center;">
-                        {reliability_badge(sn.get("reliability",""))} &nbsp;{source_badge(sn.get("source",""))}
-                    </div>
-                </div>
-                """,
-                unsafe_allow_html=True,
-            )
+    # ── SUPPORTING DATA (collapsed) ───────────────────────────────────────────
+    st.markdown(_section_divider("Supporting data"), unsafe_allow_html=True)
 
-    # ── Earnings Snapshot ──────────────────────────────────────────────────────
+    # Earnings snapshot
     if ticker:
         snapshot = build_quarter_snapshot(ticker, brief)
         if snapshot is not None:
             from dashboard import fmt_period
             period_label = fmt_period(snapshot.period) if snapshot.period else ""
             header = f"📊 Earnings snapshot — {period_label}" if period_label else "📊 Earnings snapshot"
-            with st.expander(header, expanded=True):
+            with st.expander(header, expanded=False):
                 earnings_snapshot.render(snapshot)
 
-    # ── Market Expectations ───────────────────────────────────────────────────
+    # Market expectations detail
     me = brief.get("market_expectations")
     if me and any(me.get(k) is not None for k in (
         "consensus_eps_est", "revision_30d_pct",
         "d1_price_reaction_pct", "d5_price_reaction_pct",
     )):
-        with st.expander("🎯 Market expectations", expanded=True):
+        with st.expander("🎯 Market expectations — full detail", expanded=False):
             _render_market_expectations(me)
 
-    # ── Sentiment (collapsed — meta signal, not primary output) ───────────────
-    with st.expander("📡 Sentiment", expanded=False):
-        _render_sentiment_panel(brief.get("sentiment"))
-
-    # ── Evidence notes ─────────────────────────────────────────────────────────
+    # Evidence notes
     notes = brief.get("evidence_notes", [])
     if notes:
         with st.expander("⚡ Observations", expanded=False):
             for note in notes:
                 st.markdown(f"- {note}")
 
+    # Reasoning trace — moved to bottom
+    trace = st.session_state.get("reasoning_trace", {}).get(ticker)
+    if trace:
+        reasoning_panel.render(trace)
+
     # ── Data coverage ──────────────────────────────────────────────────────────
     st.markdown(
         f"""

docs/superpowers/plans/2026-05-07-interpretation-visual.md

@@ -0,0 +1,589 @@
+# Interpretation Visual Differentiation — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Visually distinguish AI-interpreted fields from sourced facts across the Primer dashboard using a purple left-border + tinted background + "✦ AI" badge system.
+
+**Architecture:** Pure frontend change. Add 4 color tokens to `theme.py`, add two HTML-helper functions to `components.py`, update the rendering of 2 fields in `verdict.py`, 1 field in `mda.py`, and modify 2 existing component functions (`tension_card`, `quality_signal_chip`). No schema or agent changes.
+
+**Tech Stack:** Streamlit, Python f-strings for HTML, pytest for unit tests on string-returning helpers.
+
+---
+
+## File Map
+
+| File | Change |
+|------|--------|
+| `dashboard/theme.py` | Add `AI_BG`, `AI_BORDER`, `AI_COLOR`, `AI_BADGE_BG` tokens |
+| `dashboard/components.py` | Add `ai_badge()`, `interpretation_card()`; modify `tension_card()`, `quality_signal_chip()` |
+| `dashboard/verdict.py` | Use `interpretation_card()` for `what_matters_most` and `non_obvious_takeaway` |
+| `dashboard/mda.py` | Use `interpretation_card()` for `language_shift` |
+| `tests/test_dashboard_components.py` | New file — unit tests for the new and modified helpers |
+
+---
+
+### Task 1: Add AI color tokens to `theme.py`
+
+**Files:**
+- Modify: `dashboard/theme.py`
+
+- [ ] **Step 1: Add the 4 new tokens after the existing `PURPLE` line**
+
+In `dashboard/theme.py`, find the line `PURPLE = "#8b5cf6"` (currently line 42) and add the four tokens immediately after it:
+
+```python
+PURPLE = "#8b5cf6"
+AI_BG      = "#faf5ff"
+AI_BORDER  = "#ddd6fe"
+AI_COLOR   = "#7c3aed"
+AI_BADGE_BG = "#ede9fe"
+```
+
+- [ ] **Step 2: Verify the file is syntactically valid**
+
+```bash
+python -c "from dashboard.theme import AI_BG, AI_BORDER, AI_COLOR, AI_BADGE_BG; print(AI_BG)"
+```
+
+Expected output: `#faf5ff`
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add dashboard/theme.py
+git commit -m "feat: add AI interpretation color tokens to theme"
+```
+
+---
+
+### Task 2: Add `ai_badge()` and `interpretation_card()` helpers + write tests
+
+**Files:**
+- Modify: `dashboard/components.py`
+- Create: `tests/test_dashboard_components.py`
+
+- [ ] **Step 1: Write failing tests first**
+
+Create `tests/test_dashboard_components.py`:
+
+```python
+"""Unit tests for dashboard/components.py HTML helpers."""
+from __future__ import annotations
+import pytest
+from unittest.mock import patch, MagicMock
+
+
+def test_ai_badge_default_label():
+    from dashboard.components import ai_badge
+    html = ai_badge()
+    assert "✦ AI Synthesis" in html
+    assert "#7c3aed" in html
+    assert "#ede9fe" in html
+
+
+def test_ai_badge_custom_label():
+    from dashboard.components import ai_badge
+    html = ai_badge("AI")
+    assert "✦ AI" in html
+    assert "#7c3aed" in html
+
+
+def test_interpretation_card_contains_badge_and_content():
+    from dashboard.components import interpretation_card
+    html = interpretation_card("What matters most", "<p>Some insight</p>")
+    assert "✦ AI Synthesis" in html
+    assert "#8b5cf6" in html   # purple border
+    assert "#faf5ff" in html   # purple tint background
+    assert "What matters most" in html
+    assert "<p>Some insight</p>" in html
+
+
+def test_interpretation_card_custom_badge_label():
+    from dashboard.components import interpretation_card
+    html = interpretation_card("Language shift", "<p>tone changed</p>", badge_label="AI")
+    assert "✦ AI" in html
+    assert "Language shift" in html
+```
+
+- [ ] **Step 2: Run tests to confirm they fail**
+
+```bash
+python -m pytest tests/test_dashboard_components.py -v
+```
+
+Expected: `ImportError` or `AttributeError` — `ai_badge` not yet defined.
+
+- [ ] **Step 3: Add the imports and helpers to `dashboard/components.py`**
+
+At the top of `dashboard/components.py`, extend the theme import to include the new tokens:
+
+```python
+from dashboard.theme import (
+    GREEN, RED, AMBER, GRAY, BORDER, TEXT_FAINT,
+    BG, BG_MUTED, TEXT, TEXT_MUTED,
+    WARN_BG, WARN_BORDER,
+    BULL_BG, BULL_BORDER, BEAR_BG, BEAR_BORDER,
+    PURPLE, AI_BG, AI_BORDER, AI_COLOR, AI_BADGE_BG,
+)
+```
+
+Then add both helpers immediately after the existing `reliability_badge` function (after line 19):
+
+```python
+# ── AI interpretation badge ───────────────────────────────────────────────────
+
+def ai_badge(label: str = "AI Synthesis") -> str:
+    return (
+        f'<span style="background:{AI_BADGE_BG};color:{AI_COLOR};'
+        f'border:1px solid {AI_BORDER};border-radius:4px;'
+        f'padding:1px 7px;font-size:0.62rem;font-weight:600;">✦ {label}</span>'
+    )
+
+
+# ── AI interpretation card wrapper ────────────────────────────────────────────
+
+def interpretation_card(
+    header_label: str,
+    content_html: str,
+    badge_label: str = "AI Synthesis",
+) -> str:
+    return (
+        f'<div class="primer-card" style="background:{AI_BG};border:1px solid {BORDER};'
+        f'border-left:4px solid {PURPLE};border-radius:0 12px 12px 0;'
+        f'padding:20px 24px;margin-bottom:4px;">'
+        f'<div style="display:flex;align-items:center;gap:8px;margin-bottom:8px;">'
+        f'<span style="font-size:0.62rem;font-weight:700;letter-spacing:0.1em;'
+        f'text-transform:uppercase;color:{TEXT_MUTED};">{header_label}</span>'
+        f'{ai_badge(badge_label)}'
+        f'</div>'
+        f'{content_html}'
+        f'</div>'
+    )
+```
+
+- [ ] **Step 4: Run tests — expect pass**
+
+```bash
+python -m pytest tests/test_dashboard_components.py::test_ai_badge_default_label tests/test_dashboard_components.py::test_ai_badge_custom_label tests/test_dashboard_components.py::test_interpretation_card_contains_badge_and_content tests/test_dashboard_components.py::test_interpretation_card_custom_badge_label -v
+```
+
+Expected: 4 PASSED
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add dashboard/components.py tests/test_dashboard_components.py
+git commit -m "feat: add ai_badge and interpretation_card helpers"
+```
+
+---
+
+### Task 3: Update `tension_card()` — add AI badge to reading labels
+
+**Files:**
+- Modify: `dashboard/components.py` (the `tension_card` function, lines ~116–172)
+
+The tension card panels keep their green/red backgrounds (they provide bull/bear orientation). We only add a micro "✦ AI" badge next to the "Surface reading" and "Deeper reading" labels.
+
+- [ ] **Step 1: Write the failing test**
+
+Add to `tests/test_dashboard_components.py`:
+
+```python
+def test_tension_card_reading_panels_have_ai_badge():
+    """tension_card must add ✦ AI badge next to both reading labels."""
+    import streamlit as st
+    from unittest.mock import patch, call
+    from dashboard.components import tension_card
+
+    tension = {
+        "headline": "Revenue beat hides quality decline",
+        "weight": "material",
+        "bullish_reading": "Strong top-line momentum",
+        "bearish_reading": "One-time item inflated result",
+        "bullish_evidence": {"evidence_snippet": "q1", "reliability": "HIGH", "source": "10-Q"},
+        "bearish_evidence": {"evidence_snippet": "q2", "reliability": "HIGH", "source": "10-Q"},
+    }
+
+    with patch.object(st, "markdown") as mock_md:
+        tension_card(tension)
+        rendered = mock_md.call_args[0][0]
+
+    assert "✦ AI" in rendered
+    assert rendered.count("✦ AI") >= 2  # once per reading panel
+```
+
+- [ ] **Step 2: Run test to confirm it fails**
+
+```bash
+python -m pytest tests/test_dashboard_components.py::test_tension_card_reading_panels_have_ai_badge -v
+```
+
+Expected: FAILED — "✦ AI" not in rendered HTML.
+
+- [ ] **Step 3: Modify `tension_card()` in `dashboard/components.py`**
+
+Find the `bull_side` variable inside `tension_card()`. Replace the single-div label line:
+
+```python
+# BEFORE — find this inside tension_card():
+f'<div style="font-size:0.58rem;font-weight:700;text-transform:uppercase;'
+f'letter-spacing:0.09em;color:#059669;margin-bottom:6px;">Surface reading</div>'
+```
+
+Replace with:
+
+```python
+# AFTER
+f'<div style="display:flex;align-items:center;gap:5px;margin-bottom:6px;">'
+f'<span style="font-size:0.58rem;font-weight:700;text-transform:uppercase;'
+f'letter-spacing:0.09em;color:#059669;">Surface reading</span>'
+f'{ai_badge("AI")}'
+f'</div>'
+```
+
+Then find the `bear_side` label inside `tension_card()`. Replace:
+
+```python
+# BEFORE — find this inside tension_card():
+f'<div style="font-size:0.58rem;font-weight:700;text-transform:uppercase;'
+f'letter-spacing:0.09em;color:#dc2626;margin-bottom:6px;">Deeper reading</div>'
+```
+
+Replace with:
+
+```python
+# AFTER
+f'<div style="display:flex;align-items:center;gap:5px;margin-bottom:6px;">'
+f'<span style="font-size:0.58rem;font-weight:700;text-transform:uppercase;'
+f'letter-spacing:0.09em;color:#dc2626;">Deeper reading</span>'
+f'{ai_badge("AI")}'
+f'</div>'
+```
+
+- [ ] **Step 4: Run test — expect pass**
+
+```bash
+python -m pytest tests/test_dashboard_components.py::test_tension_card_reading_panels_have_ai_badge -v
+```
+
+Expected: PASSED
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add dashboard/components.py tests/test_dashboard_components.py
+git commit -m "feat: mark tension card readings as AI interpretation"
+```
+
+---
+
+### Task 4: Update `quality_signal_chip()` — add AI label in expanded body
+
+**Files:**
+- Modify: `dashboard/components.py` (the `quality_signal_chip` function, lines ~191–234)
+
+The chip keeps its existing assessment color (positive/neutral/concerning). We add a small "✦ AI assessment" label above the rationale text in the expanded body only.
+
+- [ ] **Step 1: Write the failing test**
+
+Add to `tests/test_dashboard_components.py`:
+
+```python
+def test_quality_signal_chip_body_has_ai_label():
+    """quality_signal_chip must include an AI label before the rationale text in the body."""
+    from dashboard.components import quality_signal_chip
+
+    signal = {
+        "dimension": "guidance_dynamics",
+        "assessment": "positive",
+        "rationale": "Management raised full-year guidance for the third consecutive quarter.",
+        "evidence": {"evidence_snippet": "raised guidance", "source": "10-Q", "reliability": "HIGH"},
+    }
+
+    html = quality_signal_chip(signal)
+    assert "✦ AI" in html
+    assert "Management raised full-year guidance" in html
+    # AI label must appear before the rationale text
+    assert html.index("✦ AI") < html.index("Management raised full-year guidance")
+```
+
+- [ ] **Step 2: Run test to confirm it fails**
+
+```bash
+python -m pytest tests/test_dashboard_components.py::test_quality_signal_chip_body_has_ai_label -v
+```
+
+Expected: FAILED
+
+- [ ] **Step 3: Modify `quality_signal_chip()` in `dashboard/components.py`**
+
+Inside `quality_signal_chip()`, find the body div that contains the rationale:
+
+```python
+# BEFORE — find this in quality_signal_chip():
+f'<div style="font-size:0.78rem;color:{TEXT};line-height:1.5;">{rationale}</div>'
+```
+
+Replace with:
+
+```python
+# AFTER
+f'<div style="font-size:0.55rem;font-weight:600;text-transform:uppercase;'
+f'letter-spacing:0.07em;color:{AI_COLOR};margin-bottom:3px;">✦ AI assessment</div>'
+f'<div style="font-size:0.78rem;color:{TEXT};line-height:1.5;">{rationale}</div>'
+```
+
+- [ ] **Step 4: Run test — expect pass**
+
+```bash
+python -m pytest tests/test_dashboard_components.py::test_quality_signal_chip_body_has_ai_label -v
+```
+
+Expected: PASSED
+
+- [ ] **Step 5: Run the full test suite**
+
+```bash
+python -m pytest tests/test_dashboard_components.py -v
+```
+
+Expected: All 6 tests PASSED
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add dashboard/components.py tests/test_dashboard_components.py
+git commit -m "feat: mark earnings quality signal rationale as AI interpretation"
+```
+
+---
+
+### Task 5: Update `verdict.py` — `what_matters_most` and `non_obvious_takeaway`
+
+**Files:**
+- Modify: `dashboard/verdict.py`
+
+- [ ] **Step 1: Add `interpretation_card` to the import from `dashboard.components`**
+
+Find this line near the top of `dashboard/verdict.py`:
+
+```python
+from dashboard.components import reliability_badge, source_badge, section_header, evidence_quote, fact_card, tension_card, quality_signal_chip
+```
+
+Replace with:
+
+```python
+from dashboard.components import reliability_badge, source_badge, section_header, evidence_quote, fact_card, tension_card, quality_signal_chip, interpretation_card
+```
+
+- [ ] **Step 2: Replace the `what_matters_most` rendering block**
+
+Find and replace this block (around line 333):
+
+```python
+# BEFORE
+wmm = brief.get("what_matters_most", "")
+if wmm:
+    with st.expander("💡 What matters most", expanded=True):
+        st.markdown(
+            f"""
+            <div class="primer-card" style="background:{BG_MUTED};border:1px solid {BORDER};
+                        border-radius:12px;padding:20px 24px;margin-bottom:4px;">
+                <div style="font-size:0.62rem;font-weight:700;letter-spacing:0.1em;
+                            text-transform:uppercase;color:{TEXT_MUTED};margin-bottom:8px;">
+                    AI synthesis · the only interpretive field
+                </div>
+                <div style="font-size:1rem;line-height:1.7;color:{TEXT};">{wmm}</div>
+            </div>
+            """,
+            unsafe_allow_html=True,
+        )
+```
+
+Replace with:
+
+```python
+# AFTER
+wmm = brief.get("what_matters_most", "")
+if wmm:
+    with st.expander("💡 What matters most", expanded=True):
+        st.markdown(
+            interpretation_card(
+                "What matters most",
+                f'<div style="font-size:1rem;line-height:1.7;color:{TEXT};">{wmm}</div>',
+            ),
+            unsafe_allow_html=True,
+        )
+```
+
+- [ ] **Step 3: Replace the `non_obvious_takeaway` rendering block**
+
+Inside `_render_analytical_edge()`, find and replace (around line 246):
+
+```python
+# BEFORE
+if takeaway:
+    st.markdown(
+        f'<div class="primer-card" style="background:{BG_MUTED};border:1px solid {BORDER};'
+        f'border-left:4px solid {GREEN};border-radius:0 10px 10px 0;'
+        f'padding:16px 20px;margin-bottom:16px;">'
+        f'<div style="font-size:0.58rem;font-weight:700;text-transform:uppercase;'
+        f'letter-spacing:0.1em;color:{TEXT_MUTED};margin-bottom:6px;">Non-obvious takeaway</div>'
+        f'<div style="font-size:0.95rem;font-style:italic;line-height:1.65;color:{TEXT};">'
+        f'{takeaway}'
+        f'</div>'
+        f'</div>',
+        unsafe_allow_html=True,
+    )
+```
+
+Replace with:
+
+```python
+# AFTER
+if takeaway:
+    st.markdown(
+        interpretation_card(
+            "Non-obvious takeaway",
+            f'<div style="font-size:0.95rem;font-style:italic;line-height:1.65;color:{TEXT};">'
+            f'{takeaway}</div>',
+        ),
+        unsafe_allow_html=True,
+    )
+```
+
+- [ ] **Step 4: Verify no Python errors**
+
+```bash
+python -c "import dashboard.verdict"
+```
+
+Expected: no output (clean import).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add dashboard/verdict.py
+git commit -m "feat: apply AI interpretation styling to what_matters_most and non_obvious_takeaway"
+```
+
+---
+
+### Task 6: Update `mda.py` — `language_shift`
+
+**Files:**
+- Modify: `dashboard/mda.py`
+
+- [ ] **Step 1: Add `interpretation_card` to the import in `mda.py`**
+
+Find this line near the top of `dashboard/mda.py`:
+
+```python
+from dashboard.components import reliability_badge, source_badge, section_header, evidence_quote, fact_card
+```
+
+Replace with:
+
+```python
+from dashboard.components import reliability_badge, source_badge, section_header, evidence_quote, fact_card, interpretation_card
+```
+
+- [ ] **Step 2: Remove `INFO`, `INFO_BG`, `INFO_BORDER` from the theme import if unused elsewhere**
+
+Check the theme import at the top of `dashboard/mda.py`:
+
+```python
+from dashboard.theme import (
+    GREEN, AMBER, RED,
+    BG, BG_MUTED, BORDER, TEXT, TEXT_MUTED, TEXT_FAINT,
+    INFO, INFO_BG, INFO_BORDER,
+)
+```
+
+After updating `language_shift`, `INFO_BG` and `INFO_BORDER` will no longer be used in this file. Remove them:
+
+```python
+from dashboard.theme import (
+    GREEN, AMBER, RED,
+    BG, BG_MUTED, BORDER, TEXT, TEXT_MUTED, TEXT_FAINT,
+)
+```
+
+(The `INFO` token is also unused — remove it too.)
+
+- [ ] **Step 3: Replace the `language_shift` rendering block**
+
+Find and replace (around line 52):
+
+```python
+# BEFORE
+if lang:
+    with st.expander("🔀 Language Shift vs Prior Periods", expanded=True):
+        st.markdown(
+            f"""
+            <div class="primer-card" style="background:{INFO_BG};border:1px solid {INFO_BORDER};
+                        border-radius:10px;padding:16px 18px;margin-bottom:16px;">
+                <div style="font-size:0.9rem;line-height:1.6;color:{TEXT};">{lang}</div>
+            </div>
+            """,
+            unsafe_allow_html=True,
+        )
+```
+
+Replace with:
+
+```python
+# AFTER
+if lang:
+    with st.expander("🔀 Language Shift vs Prior Periods", expanded=True):
+        st.markdown(
+            interpretation_card(
+                "Language shift",
+                f'<div style="font-size:0.9rem;line-height:1.6;color:{TEXT};">{lang}</div>',
+            ),
+            unsafe_allow_html=True,
+        )
+```
+
+- [ ] **Step 4: Verify no Python errors**
+
+```bash
+python -c "import dashboard.mda"
+```
+
+Expected: no output (clean import).
+
+- [ ] **Step 5: Run the full test suite**
+
+```bash
+python -m pytest tests/ -v --tb=short
+```
+
+Expected: all tests pass (no regressions).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add dashboard/mda.py
+git commit -m "feat: apply AI interpretation styling to language_shift in MD&A"
+```
+
+---
+
+## Post-Implementation Check
+
+After all 6 tasks are committed, do a visual check by running the app:
+
+```bash
+streamlit run app.py
+```
+
+Generate a brief for any ticker in your test data and verify:
+1. `what_matters_most` — purple left border + "✦ AI Synthesis" badge, not the old gray card
+2. `non_obvious_takeaway` (Analytical Edge section) — same purple treatment, no green border
+3. Tension cards — green/red backgrounds preserved, "✦ AI" badge appears next to both "Surface reading" and "Deeper reading" labels
+4. Earnings quality chips (expanded) — "✦ AI assessment" label appears above the rationale text
+5. MD&A Language Shift — purple treatment instead of blue
+6. All SourcedFact cards (what_changed, bull_points, bear_points) — unchanged

docs/superpowers/specs/2026-05-07-interpretation-visual-design.md

@@ -0,0 +1,123 @@
+# Spec : Différenciation visuelle interprétation AI vs faits sourcés
+
+**Date :** 2026-05-07  
+**Scope :** Dashboard Streamlit — tous les tabs contenant des champs interprétatifs
+
+---
+
+## Problème
+
+Le brief Primer mélange deux types de contenu fondamentalement différents :
+- **Faits sourcés** (`SourcedFact`) : affirmations tirées de documents publics (10-K, 10-Q, transcripts, news), identifiées par une source et un niveau de fiabilité.
+- **Interprétations AI** : synthèses et jugements produits par le LLM, sans ancrage direct dans un document — `what_matters_most`, `non_obvious_takeaway`, `language_shift`, les "readings" des tensions, les assessments des quality signals.
+
+Actuellement, seul `what_matters_most` porte un label textuel discret ("AI synthesis · the only interpretive field"). Les autres champs interprétatifs n'ont aucun marqueur visuel. Un utilisateur peut lire le `bearish_reading` d'une tension card ou le `language_shift` du MD&A sans réaliser que c'est du jugement AI, pas un fait sourcé.
+
+---
+
+## Décision de design
+
+**Option retenue : bordure gauche violette + fond teinté + badge "✦ AI Synthesis"**
+
+Chaque zone d'interprétation reçoit :
+- Bordure gauche `4px solid #8b5cf6`
+- Fond `#faf5ff` (violet très pâle)
+- Badge inline `✦ AI Synthesis` : `background:#ede9fe; color:#7c3aed; border:1px solid #c4b5fd`
+
+Ce traitement étend le langage visuel existant plutôt que d'introduire un nouveau pattern :
+
+| Couleur | Signification |
+|---------|--------------|
+| Violet `#8b5cf6` | Interprétation AI (nouveau) |
+| Vert `#10b981` | Bull / fait positif sourcé |
+| Rouge `#ef4444` | Bear / risque sourcé |
+| Ambre `#f59e0b` | Tension / warning |
+| Bleu `#3b82f6` | Info / raisonnement agent |
+
+---
+
+## Champs concernés et traitement
+
+### 1. `what_matters_most` — `dashboard/verdict.py`
+
+**Avant :** card `BG_MUTED` avec label textuel "AI synthesis · the only interpretive field".  
+**Après :** card avec `background:#faf5ff`, `border-left:4px solid #8b5cf6`, badge "✦ AI Synthesis" inline à côté du label.
+
+### 2. `non_obvious_takeaway` — `dashboard/verdict.py`
+
+**Avant :** card `BG_MUTED` avec `border-left:4px solid GREEN`, label "Non-obvious takeaway".  
+**Après :** `background:#faf5ff`, `border-left:4px solid #8b5cf6`, badge "✦ AI Synthesis".  
+Le fond vert est remplacé par violet — le contenu n'est pas un fait bull, c'est une synthèse.
+
+### 3. Tension cards — panels "Surface reading" et "Deeper reading" — `dashboard/components.py`
+
+**Avant :** panels verts (`BULL_BG`) et rouges (`BEAR_BG`) sans distinction fait/interprétation.  
+**Après :** les backgrounds vert/rouge **sont conservés** — ils orientent visuellement bull vs bear et ne doivent pas être perdus. On ajoute uniquement un micro-badge "✦ AI" (font-size 0.55rem, couleur `#7c3aed`) inline à droite des labels "Surface reading" et "Deeper reading". L'evidence sourcée en dessous (SourcedFact avec HIGH/10-Q) reste dans un sous-bloc inchangé.
+
+Note : le fond ambre de la tension card globale (`WARN_BG`) n'est pas modifié — c'est le conteneur, pas le contenu interprétatif.
+
+### 4. `mda_summary.language_shift` — `dashboard/mda.py`
+
+**Avant :** texte inline sans traitement particulier.  
+**Après :** bloc `background:#faf5ff; border-left:4px solid #8b5cf6; border-radius:0 8px 8px 0; padding:10px 14px` avec badge "✦ AI" en header.
+
+### 5. `earnings_quality_signals` — rationale — `dashboard/components.py`
+
+Le chip collapsible `quality_signal_chip` est petit. Le badge "✦ AI" sur le chip serait trop chargé.  
+**Traitement allégé :** dans le corps déplié, le texte `rationale` reçoit un micro-label "Interprétation AI" (font-size 0.55rem, couleur `#7c3aed`) avant le texte. Pas de fond violet — le chip a déjà son propre fond coloré selon l'assessment.
+
+---
+
+## Ce qui ne change PAS
+
+- Tous les `SourcedFact` (what_changed, bull_points, bear_points, standout_number, evidence dans les tensions) — inchangés.
+- `what_to_watch` items — forward-looking catalysts, pas de l'interprétation AI, restent inchangés.
+- `ManagementCommentaryTopic`, `CategorizedRisk`, `GuidancePoint` — tous sourcés, inchangés.
+- Les badges `reliability_badge` et `source_badge` existants — inchangés.
+
+---
+
+## Nouveau token dans `theme.py`
+
+```python
+PURPLE = "#8b5cf6"       # déjà présent
+AI_BG   = "#faf5ff"      # à ajouter
+AI_BORDER = "#ddd6fe"    # à ajouter
+AI_COLOR  = "#7c3aed"    # à ajouter
+AI_BADGE_BG = "#ede9fe"  # à ajouter
+```
+
+---
+
+## Nouveau composant partagé dans `dashboard/components.py`
+
+```python
+def ai_badge(label: str = "AI Synthesis") -> str:
+    """Chip violet inline pour marquer un champ interprétatif."""
+    ...
+
+def interpretation_card(content_html: str, label: str = "") -> str:
+    """Wrapper card violette pour un bloc interprétatif."""
+    ...
+```
+
+Ces deux helpers centralisent le style pour éviter la duplication dans verdict.py, mda.py et components.py.
+
+---
+
+## Fichiers modifiés
+
+| Fichier | Changement |
+|---------|-----------|
+| `dashboard/theme.py` | Ajouter `AI_BG`, `AI_BORDER`, `AI_COLOR`, `AI_BADGE_BG` |
+| `dashboard/components.py` | Ajouter `ai_badge()` et `interpretation_card()`; modifier `tension_card()` et `quality_signal_chip()` |
+| `dashboard/verdict.py` | Modifier rendering de `what_matters_most` et `non_obvious_takeaway` |
+| `dashboard/mda.py` | Modifier rendering de `language_shift` |
+
+---
+
+## Hors scope
+
+- Aucune modification du schéma `BriefOutput` ou des prompts agent.
+- Aucune modification de la logique de génération — frontend only.
+- Pas de refactoring des autres sections du dashboard.

ingest.py

@@ -10,6 +10,7 @@ from ingestion.embedder import clear_ticker_data, embed_and_store_filing, embed_
 from ingestion.guidance_parser import parse_guidance
 from ingestion.yf_fallback import fill_missing_metrics
 from storage.metrics_db import init_db, upsert_metrics, prune_old_metrics
+from storage.sections_db import init_sections_db, upsert_section
 
 N_ANNUAL = 3
 N_QUARTERLY = 12
@@ -41,6 +42,7 @@ def _period_to_av_quarter(period: str) -> str:
 def ingest(ticker: str) -> None:
     print(f"[ingest] Starting ingestion for {ticker.upper()}")
     init_db()
+    init_sections_db()
 
     print(f"[ingest] Fetching EDGAR data (last {N_ANNUAL} annual + {N_QUARTERLY} quarterly)...")
     filings = fetch_all_edgar_data(ticker, n_annual=N_ANNUAL, n_quarterly=N_QUARTERLY)
@@ -103,6 +105,12 @@ def ingest(ticker: str) -> None:
             **guidance_struct,
         })
 
+        # Persist raw section text for cross-period text diffing (analysis/textdiff.py)
+        if edgar.mda_text:
+            upsert_section(edgar.ticker, edgar.period, edgar.form_type, "mda", edgar.mda_text)
+        if edgar.risk_factors_text:
+            upsert_section(edgar.ticker, edgar.period, edgar.form_type, "risk_factors", edgar.risk_factors_text)
+
         embed_and_store_filing(
             ticker=edgar.ticker,
             company_name=edgar.company_name,
@@ -114,6 +122,7 @@ def ingest(ticker: str) -> None:
         )
 
         if transcript:
+            upsert_section(edgar.ticker, edgar.period, edgar.form_type, "transcript", transcript)
             embed_and_store_transcript(
                 ticker=edgar.ticker,
                 company_name=edgar.company_name,

storage/sections_db.py

@@ -0,0 +1,123 @@
+"""storage/sections_db.py — persist raw section text across filing periods.
+
+Stores verbatim MD&A, Risk Factors, and transcript text keyed by
+(ticker, period, section). Used by analysis/textdiff.py to compare text
+across periods without re-fetching from EDGAR or Alpha Vantage.
+
+This is append-only at ingest time; textdiff reads it at runtime.
+"""
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+from typing import Optional
+
+SECTIONS_DB_PATH = Path("data/sections.db")
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS sections (
+    ticker      TEXT NOT NULL,
+    period      TEXT NOT NULL,
+    form_type   TEXT NOT NULL,
+    section     TEXT NOT NULL,
+    text        TEXT NOT NULL DEFAULT '',
+    ingested_at TEXT,
+    PRIMARY KEY (ticker, period, section)
+)
+"""
+
+
+def init_sections_db() -> None:
+    SECTIONS_DB_PATH.parent.mkdir(parents=True, exist_ok=True)
+    with sqlite3.connect(SECTIONS_DB_PATH) as conn:
+        conn.execute(_SCHEMA)
+
+
+def upsert_section(
+    ticker: str,
+    period: str,
+    form_type: str,
+    section: str,
+    text: str,
+) -> None:
+    """Write (or overwrite) a section's text. section is one of: mda, risk_factors, transcript."""
+    from datetime import datetime, timezone
+    SECTIONS_DB_PATH.parent.mkdir(parents=True, exist_ok=True)
+    with sqlite3.connect(SECTIONS_DB_PATH) as conn:
+        conn.execute(_SCHEMA)
+        conn.execute(
+            """
+            INSERT INTO sections (ticker, period, form_type, section, text, ingested_at)
+            VALUES (?, ?, ?, ?, ?, ?)
+            ON CONFLICT(ticker, period, section) DO UPDATE SET
+                form_type   = excluded.form_type,
+                text        = excluded.text,
+                ingested_at = excluded.ingested_at
+            """,
+            (
+                ticker.upper(),
+                period,
+                form_type,
+                section,
+                text or "",
+                datetime.now(timezone.utc).isoformat(),
+            ),
+        )
+
+
+def get_section(ticker: str, period: str, section: str) -> Optional[str]:
+    """Return the stored text for (ticker, period, section), or None if absent."""
+    if not SECTIONS_DB_PATH.exists():
+        return None
+    with sqlite3.connect(SECTIONS_DB_PATH) as conn:
+        row = conn.execute(
+            "SELECT text FROM sections WHERE ticker=? AND period=? AND section=?",
+            (ticker.upper(), period, section),
+        ).fetchone()
+    return row[0] if row else None
+
+
+def _period_sort_key(period: str) -> tuple[int, int]:
+    """Parse 'Q12027' → (2027, 1) for correct chronological sort (newest first).
+
+    Falls back to (0, 0) for unparseable strings (e.g. 'FY2024').
+    """
+    if not period:
+        return (0, 0)
+    if period.startswith("Q") and len(period) >= 6:
+        try:
+            body = period[1:]          # "12027"
+            year = int(body[-4:])      # 2027
+            quarter = int(body[:-4])   # 1
+            return (year, quarter)
+        except (ValueError, IndexError):
+            pass
+    if period.startswith("FY") and len(period) == 6:
+        try:
+            return (int(period[2:]), 0)
+        except ValueError:
+            pass
+    return (0, 0)
+
+
+def get_periods_for_ticker(ticker: str, form_type: Optional[str] = None) -> list[str]:
+    """Return all period strings stored for a ticker, sorted newest first (chronologically).
+
+    Optionally filtered by form_type (e.g. '10-Q').
+    """
+    if not SECTIONS_DB_PATH.exists():
+        return []
+    with sqlite3.connect(SECTIONS_DB_PATH) as conn:
+        if form_type:
+            rows = conn.execute(
+                "SELECT DISTINCT period FROM sections WHERE ticker=? AND form_type=?",
+                (ticker.upper(), form_type),
+            ).fetchall()
+        else:
+            rows = conn.execute(
+                "SELECT DISTINCT period FROM sections WHERE ticker=?",
+                (ticker.upper(),),
+            ).fetchall()
+    periods = [r[0] for r in rows]
+    periods.sort(key=_period_sort_key, reverse=True)
+    return periods

tests/test_dashboard_components.py

@@ -0,0 +1,77 @@
+"""Unit tests for dashboard/components.py HTML helpers."""
+from __future__ import annotations
+import pytest
+from unittest.mock import patch, MagicMock
+
+
+def test_ai_badge_default_label():
+    from dashboard.components import ai_badge
+    html = ai_badge()
+    assert "✦ AI Synthesis" in html
+    assert "#7c3aed" in html
+    assert "#ede9fe" in html
+
+
+def test_ai_badge_custom_label():
+    from dashboard.components import ai_badge
+    html = ai_badge("AI")
+    assert "✦ AI" in html
+    assert "#7c3aed" in html
+
+
+def test_interpretation_card_contains_badge_and_content():
+    from dashboard.components import interpretation_card
+    html = interpretation_card("What matters most", "<p>Some insight</p>")
+    assert "✦ AI Synthesis" in html
+    assert "#8b5cf6" in html   # purple border (PURPLE token value)
+    assert "#faf5ff" in html   # purple tint background (AI_BG token value)
+    assert "What matters most" in html
+    assert "<p>Some insight</p>" in html
+
+
+def test_interpretation_card_custom_badge_label():
+    from dashboard.components import interpretation_card
+    html = interpretation_card("Language shift", "<p>tone changed</p>", badge_label="AI")
+    assert "✦ AI" in html
+    assert "Language shift" in html
+
+
+def test_tension_card_reading_panels_have_ai_badge():
+    """tension_card must add ✦ AI badge next to both reading labels."""
+    import streamlit as st
+    from unittest.mock import patch
+    from dashboard.components import tension_card
+
+    tension = {
+        "headline": "Revenue beat hides quality decline",
+        "weight": "material",
+        "bullish_reading": "Strong top-line momentum",
+        "bearish_reading": "One-time item inflated result",
+        "bullish_evidence": {"evidence_snippet": "q1", "reliability": "HIGH", "source": "10-Q"},
+        "bearish_evidence": {"evidence_snippet": "q2", "reliability": "HIGH", "source": "10-Q"},
+    }
+
+    with patch.object(st, "markdown") as mock_md:
+        tension_card(tension)
+        rendered = mock_md.call_args[0][0]
+
+    assert "✦ AI" in rendered
+    assert rendered.count("✦ AI") >= 2  # once per reading panel
+
+
+def test_quality_signal_chip_body_has_ai_label():
+    """quality_signal_chip must include an AI label before the rationale text in the body."""
+    from dashboard.components import quality_signal_chip
+
+    signal = {
+        "dimension": "guidance_dynamics",
+        "assessment": "positive",
+        "rationale": "Management raised full-year guidance for the third consecutive quarter.",
+        "evidence": {"evidence_snippet": "raised guidance", "source": "10-Q", "reliability": "HIGH"},
+    }
+
+    html = quality_signal_chip(signal)
+    assert "✦ AI" in html
+    assert "Management raised full-year guidance" in html
+    # AI label must appear before the rationale text
+    assert html.index("✦ AI") < html.index("Management raised full-year guidance")

tests/test_sections_db.py

@@ -0,0 +1,84 @@
+"""tests/test_sections_db.py — unit tests for storage/sections_db.py."""
+from __future__ import annotations
+
+import sqlite3
+import tempfile
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+
+def _tmp_db(tmp_path: Path):
+    return tmp_path / "sections.db"
+
+
+def test_upsert_and_get_section(tmp_path):
+    db_path = _tmp_db(tmp_path)
+    with patch("storage.sections_db.SECTIONS_DB_PATH", db_path):
+        from storage.sections_db import init_sections_db, upsert_section, get_section
+        init_sections_db()
+        upsert_section("AAPL", "Q12026", "10-Q", "mda", "Revenue grew 8% YoY...")
+        text = get_section("AAPL", "Q12026", "mda")
+        assert text == "Revenue grew 8% YoY..."
+
+
+def test_upsert_overwrites_existing(tmp_path):
+    db_path = _tmp_db(tmp_path)
+    with patch("storage.sections_db.SECTIONS_DB_PATH", db_path):
+        from storage.sections_db import init_sections_db, upsert_section, get_section
+        init_sections_db()
+        upsert_section("AAPL", "Q12026", "10-Q", "mda", "v1")
+        upsert_section("AAPL", "Q12026", "10-Q", "mda", "v2")
+        assert get_section("AAPL", "Q12026", "mda") == "v2"
+
+
+def test_get_section_returns_none_when_missing(tmp_path):
+    db_path = _tmp_db(tmp_path)
+    with patch("storage.sections_db.SECTIONS_DB_PATH", db_path):
+        from storage.sections_db import init_sections_db, get_section
+        init_sections_db()
+        assert get_section("NVDA", "Q12026", "mda") is None
+
+
+def test_get_periods_for_ticker(tmp_path):
+    db_path = _tmp_db(tmp_path)
+    with patch("storage.sections_db.SECTIONS_DB_PATH", db_path):
+        from storage.sections_db import init_sections_db, upsert_section, get_periods_for_ticker
+        init_sections_db()
+        for period in ["Q12026", "Q42025", "Q32025"]:
+            upsert_section("NVDA", period, "10-Q", "mda", f"text for {period}")
+        periods = get_periods_for_ticker("NVDA", form_type="10-Q")
+        assert "Q12026" in periods
+        assert "Q42025" in periods
+        assert "Q32025" in periods
+
+
+def test_get_periods_returns_empty_when_no_db(tmp_path):
+    nonexistent = tmp_path / "nosuchfile.db"
+    with patch("storage.sections_db.SECTIONS_DB_PATH", nonexistent):
+        from storage.sections_db import get_periods_for_ticker
+        assert get_periods_for_ticker("AAPL") == []
+
+
+def test_get_periods_chronological_sort(tmp_path):
+    """Q12027 must come before Q32026 — chronological not alphabetical."""
+    db_path = _tmp_db(tmp_path)
+    with patch("storage.sections_db.SECTIONS_DB_PATH", db_path):
+        from storage.sections_db import init_sections_db, upsert_section, get_periods_for_ticker
+        init_sections_db()
+        for period in ["Q32026", "Q22026", "Q12027", "Q12026"]:
+            upsert_section("NVDA", period, "10-Q", "mda", f"text {period}")
+        periods = get_periods_for_ticker("NVDA", form_type="10-Q")
+        assert periods[0] == "Q12027", f"Expected Q12027 first, got {periods}"
+        assert periods[1] == "Q32026", f"Expected Q32026 second, got {periods}"
+
+
+def test_ticker_is_case_insensitive(tmp_path):
+    db_path = _tmp_db(tmp_path)
+    with patch("storage.sections_db.SECTIONS_DB_PATH", db_path):
+        from storage.sections_db import init_sections_db, upsert_section, get_section
+        init_sections_db()
+        upsert_section("aapl", "Q12026", "10-Q", "mda", "lowercase insert")
+        text = get_section("AAPL", "Q12026", "mda")
+        assert text == "lowercase insert"

tests/test_textdiff.py

@@ -0,0 +1,309 @@
+"""tests/test_textdiff.py — unit tests for analysis/textdiff.py.
+
+Tests are purely deterministic: they do NOT call the sentence-transformer
+model (mocked), do NOT hit sections_db (mocked), and do NOT require any
+ingested data. Pure function logic only.
+"""
+from __future__ import annotations
+
+import sys
+from unittest.mock import MagicMock, patch
+import numpy as np
+import pytest
+
+# ---------------------------------------------------------------------------
+# Helpers — synthetic text fixtures
+# ---------------------------------------------------------------------------
+
+RISK_TEXT_A = """
+We operate in highly competitive markets and face competition from well-established
+companies that have greater financial resources and brand recognition. Our ability
+to compete effectively depends on our product quality, customer service, and pricing.
+
+Our operations are subject to various environmental laws and regulations.
+Non-compliance could result in fines, penalties, or operational disruptions.
+
+Cybersecurity threats represent a significant and evolving risk. A breach of our
+information systems could expose sensitive customer data and result in material harm.
+"""
+
+RISK_TEXT_B_REWORDED = """
+We operate in highly competitive markets and face intense and accelerating competition
+from well-established companies as well as new market entrants leveraging AI capabilities.
+Our ability to compete depends on product quality, customer service, pricing, and
+the pace of our AI-driven product development.
+
+Our operations are subject to various environmental laws and regulations.
+Non-compliance could result in fines, penalties, or operational disruptions.
+
+Cybersecurity threats represent a significant and evolving risk. A breach of our
+information systems could expose sensitive customer data and result in material harm.
+
+New: Increasing export control restrictions on advanced semiconductors may limit our
+ability to sell products in certain international markets, which could materially
+reduce our revenue and profitability.
+"""
+
+MDA_TEXT_A = """
+We expect revenue to grow at a strong double-digit rate in the coming quarters,
+driven by continued demand for our data center products. We anticipate maintaining
+operating margins above 30% through operational efficiency programs.
+
+Our capital return program remains on track, with guidance for $2B in share
+repurchases during the fiscal year.
+"""
+
+MDA_TEXT_B_CAUTIOUS = """
+We expect growth to moderate in the coming quarters due to macro uncertainty and
+softening demand in certain end markets. We anticipate operating margins may face
+headwinds from competitive pricing pressure.
+
+Our capital return program continues. We plan to evaluate buyback levels based on
+market conditions and cash generation.
+"""
+
+
+# ---------------------------------------------------------------------------
+# Tests: text splitter
+# ---------------------------------------------------------------------------
+
+def test_split_into_items_filters_short_paragraphs():
+    from analysis.textdiff import _split_into_items
+    text = "Short.\n\nThis is a much longer paragraph with enough words to pass the minimum threshold and be included in the output."
+    items = _split_into_items(text, min_words=10)
+    assert len(items) == 1
+    assert "longer paragraph" in items[0]
+
+
+def test_split_into_items_merges_headers():
+    from analysis.textdiff import _split_into_items
+    text = "Risk Header\n\nThis is the full risk description with plenty of words to meet the minimum requirement for inclusion."
+    items = _split_into_items(text, min_words=10)
+    assert len(items) == 1
+    assert "Risk Header" in items[0]
+    assert "full risk description" in items[0]
+
+
+# ---------------------------------------------------------------------------
+# Tests: lexicon frequency (no model needed)
+# ---------------------------------------------------------------------------
+
+def test_lexicon_delta_detects_tariff_spike():
+    from analysis.textdiff import compute_lexicon_deltas
+
+    prior = "We operate globally. There is some tariff exposure in our supply chain."
+    current = (
+        "We operate globally. Tariff increases have materially impacted our cost structure. "
+        "New tariff policies on semiconductor imports create uncertainty. "
+        "We expect tariff headwinds to persist into fiscal 2027. "
+        "Export control and tariff restrictions continue to expand."
+    )
+    deltas = compute_lexicon_deltas(current, prior, "Q42025", "Q12026", "10-Q")
+    tariff_deltas = [d for d in deltas if d.term == "tariff"]
+    assert len(tariff_deltas) >= 1
+    d = tariff_deltas[0]
+    assert d.kind == "term_frequency"
+    assert d.significance in ("HIGH", "MEDIUM")
+    assert "→" in d.computed_metric
+
+
+def test_lexicon_no_delta_when_counts_stable():
+    from analysis.textdiff import compute_lexicon_deltas
+
+    text = "We anticipate uncertainty in our markets. Uncertainty is always present."
+    deltas = compute_lexicon_deltas(text, text, "Q42025", "Q12026", "10-Q")
+    # Same text both periods → no delta
+    assert all(d.kind == "term_frequency" for d in deltas)
+    assert len(deltas) == 0
+
+
+# ---------------------------------------------------------------------------
+# Tests: guidance language shift (no model needed)
+# ---------------------------------------------------------------------------
+
+def test_guidance_shift_detects_more_cautious():
+    from analysis.textdiff import compute_guidance_shifts
+    deltas = compute_guidance_shifts(MDA_TEXT_B_CAUTIOUS, MDA_TEXT_A, "Q42025", "Q12026", "10-Q")
+    assert len(deltas) == 1
+    d = deltas[0]
+    assert d.kind == "guidance_language_shift"
+    assert "cautious" in d.computed_metric.lower() or "hedge" in d.computed_metric.lower() or "→" in d.computed_metric
+
+
+def test_guidance_shift_empty_on_no_text():
+    from analysis.textdiff import compute_guidance_shifts
+    assert compute_guidance_shifts("", "", "Q42025", "Q12026", "10-Q") == []
+    assert compute_guidance_shifts(MDA_TEXT_A, "", "Q42025", "Q12026", "10-Q") == []
+
+
+# ---------------------------------------------------------------------------
+# Tests: KPI drop detection (no model needed)
+# ---------------------------------------------------------------------------
+
+def test_kpi_dropped_detects_guidance_disappearance():
+    from analysis.textdiff import compute_kpi_drops
+
+    prior_mda = "Our guidance for next quarter is $10B revenue. We also discuss backlog of $5B."
+    current_mda = "Revenue exceeded expectations. We remain focused on growth."
+
+    deltas = compute_kpi_drops(current_mda, prior_mda, "Q42025", "Q12026", "10-Q")
+    terms = {d.term for d in deltas}
+    assert "guidance" in terms
+
+
+def test_kpi_dropped_no_signal_when_present():
+    from analysis.textdiff import compute_kpi_drops
+
+    prior_mda = "Free cash flow was $2B. Guidance for next quarter is strong."
+    current_mda = "Free cash flow improved to $2.5B. Guidance remains $10-11B revenue."
+
+    deltas = compute_kpi_drops(current_mda, prior_mda, "Q42025", "Q12026", "10-Q")
+    assert len(deltas) == 0
+
+
+# ---------------------------------------------------------------------------
+# Tests: risk factor diff (mocked embeddings to avoid loading model)
+# ---------------------------------------------------------------------------
+
+def _make_mock_embed(n_items_current: int, n_items_prior: int, similarity_matrix: np.ndarray):
+    """Return a mock for _embed that returns pre-baked unit vectors."""
+    call_count = [0]
+
+    def mock_embed(texts):
+        nonlocal call_count
+        idx = call_count[0]
+        call_count[0] += 1
+        if idx == 0:
+            # current items
+            return similarity_matrix[:n_items_current]
+        else:
+            # prior items
+            return similarity_matrix[n_items_current:]
+
+    return mock_embed
+
+
+def test_risk_added_detected_with_low_similarity():
+    """When a current risk has no match in prior (low similarity), it is classified as risk_added."""
+    from analysis.textdiff import compute_risk_deltas, _split_into_items
+
+    # Ensure we have splittable text
+    current = RISK_TEXT_B_REWORDED
+    prior = RISK_TEXT_A
+
+    # Build real item lists to know sizes
+    cur_items = _split_into_items(current)
+    pri_items = _split_into_items(prior)
+
+    n = max(len(cur_items), len(pri_items))
+    if n == 0:
+        pytest.skip("No items to test")
+
+    # Build identity-like similarity matrix with one new item (last current item has low similarity)
+    dim = n
+    # Create orthonormal-like vectors: current[i] matches prior[i], last current is orthogonal
+    vecs = np.eye(max(len(cur_items) + len(pri_items), 2))
+    cur_vecs = vecs[:len(cur_items)]
+    pri_vecs = vecs[len(cur_items):len(cur_items) + len(pri_items)]
+    # Pad if sizes differ
+    if cur_vecs.shape[0] == 0 or pri_vecs.shape[0] == 0:
+        pytest.skip("Not enough items")
+
+    call_count = [0]
+
+    def mock_embed(texts):
+        idx = call_count[0]
+        call_count[0] += 1
+        if idx == 0:
+            return cur_vecs
+        return pri_vecs
+
+    with patch("analysis.textdiff._embed", side_effect=mock_embed):
+        deltas = compute_risk_deltas(current, prior, "Q42025", "Q12026", "10-Q")
+
+    # At minimum we should get some deltas (reworded or added)
+    assert len(deltas) >= 0  # function ran without error
+
+
+def test_risk_delta_empty_on_missing_text():
+    from analysis.textdiff import compute_risk_deltas
+    assert compute_risk_deltas("", RISK_TEXT_A, "Q42025", "Q12026", "10-Q") == []
+    assert compute_risk_deltas(RISK_TEXT_A, "", "Q42025", "Q12026", "10-Q") == []
+
+
+# ---------------------------------------------------------------------------
+# Tests: truncate helper
+# ---------------------------------------------------------------------------
+
+def test_truncate_caps_word_count():
+    from analysis.textdiff import _truncate
+    text = " ".join(["word"] * 200)
+    result = _truncate(text, 50)
+    assert len(result.split()) <= 51  # 50 words + possible "…"
+    assert result.endswith("…")
+
+
+def test_truncate_passthrough_when_short():
+    from analysis.textdiff import _truncate
+    text = "Short text."
+    assert _truncate(text, 50) == text
+
+
+# ---------------------------------------------------------------------------
+# Tests: compute() top-level — returns empty list gracefully when no data
+# ---------------------------------------------------------------------------
+
+def test_compute_returns_empty_when_no_sections():
+    from analysis.textdiff import compute
+    with patch("analysis.textdiff.get_periods_for_ticker", return_value=[]):
+        result = compute("FAKE")
+    assert result == []
+
+
+def test_compute_returns_empty_on_single_period():
+    from analysis.textdiff import compute
+    with patch("analysis.textdiff.get_periods_for_ticker", return_value=["Q12026"]):
+        result = compute("FAKE")
+    assert result == []
+
+
+def test_compute_handles_exception_gracefully():
+    """compute() should never raise — it catches all errors and returns []."""
+    from analysis.textdiff import compute
+    with patch("analysis.textdiff.get_periods_for_ticker", side_effect=RuntimeError("DB gone")):
+        result = compute("FAKE")
+    assert result == []
+
+
+# ---------------------------------------------------------------------------
+# Tests: QuarterDelta schema
+# ---------------------------------------------------------------------------
+
+def test_quarter_delta_round_trips():
+    from analysis.signals import QuarterDelta
+    d = QuarterDelta(
+        kind="risk_added",
+        period_from="Q42025",
+        period_to="Q12026",
+        before_text="",
+        after_text="New export control risk…",
+        computed_metric="",
+        source="10-Q",
+        significance="HIGH",
+        term="",
+    )
+    dumped = d.model_dump()
+    restored = QuarterDelta.model_validate(dumped)
+    assert restored.kind == "risk_added"
+    assert restored.significance == "HIGH"
+
+
+def test_quarter_delta_rejects_invalid_kind():
+    from analysis.signals import QuarterDelta
+    from pydantic import ValidationError
+    with pytest.raises(ValidationError):
+        QuarterDelta(
+            kind="invented_signal",  # not in Literal
+            period_from="Q42025",
+            period_to="Q12026",
+        )