## ADDED Requirements

### Requirement: Provider-agnostic analysis-agent interface

The system SHALL define an `AnalysisAgent` interface that accepts a structured
evaluation object and returns a written analysis. Consumers MUST depend only on
this interface so the underlying model provider can change without affecting the
evaluation engine or UI.

#### Scenario: Agent invoked through the interface
- **WHEN** an evaluation object is passed to the configured analysis agent
- **THEN** the agent returns a written analysis produced through the interface

#### Scenario: Alternate implementation can be registered
- **WHEN** a different agent implementation is configured
- **THEN** the system uses it without changes to evaluation or UI code

### Requirement: Claude default implementation via Anthropic SDK

The system SHALL ship a default `AnalysisAgent` backed by Claude through the
`@anthropic-ai/sdk`, targeting a current Claude model. The API key SHALL be
supplied by the user (bring-your-own-key) via configuration and never hard-coded
or committed.

#### Scenario: Claude produces the written thesis
- **WHEN** a valid Anthropic API key is configured and an evaluation is submitted
- **THEN** the default agent calls Claude and returns the written thesis

#### Scenario: Key sourced from configuration
- **WHEN** the app reads its configuration
- **THEN** the Anthropic API key is loaded from environment/config, not source code

### Requirement: Grounded, structured written analysis

The agent SHALL base its narrative only on the supplied evaluation data and
SHALL NOT invent figures. It SHALL produce the narrative sections reflected in the
example evaluation: current standing, earnings recap and quality-of-earnings
caveats, valuation with explicit over/undervalued reasoning, macro factors, timing,
entry/exit/stop-loss rationale, bull-versus-bear, and an actionable plan. When a
data caveat or discrepancy is present in the input, the agent SHALL preserve it.

#### Scenario: Narrative grounded in provided data
- **WHEN** the agent writes the analysis
- **THEN** every figure it cites is present in the supplied evaluation object

#### Scenario: Data caveats preserved
- **WHEN** the evaluation object flags a discrepancy or one-time item
- **THEN** the written analysis surfaces that caveat rather than omitting it

#### Scenario: Disclaimer preserved in narrative
- **WHEN** the agent returns its analysis
- **THEN** the analysis-not-advice disclaimer is present

### Requirement: Graceful degradation without an API key

When no analysis-agent key is configured, the system SHALL still return the full
structured evaluation and SHALL clearly indicate that the written narrative is
unavailable until a key is provided.

#### Scenario: No key configured
- **WHEN** an evaluation is requested and no agent API key is configured
- **THEN** the structured evaluation is returned
- **AND** the response indicates the written analysis is unavailable pending a key

### Requirement: Agent error handling

The system SHALL handle agent failures (auth errors, rate limits, timeouts) by
returning a typed error and the underlying structured evaluation, without losing
the data already computed.

#### Scenario: Agent call fails
- **WHEN** the agent call errors after retries
- **THEN** the system returns the structured evaluation plus a typed agent error
- **AND** the computed data is not discarded