bulk commit changes!

openspec/specs/image-provider-fallback-chain/spec.md

@@ -0,0 +1,63 @@
+## Purpose
+
+Canonical specification for image-provider-fallback-chain requirements synced from OpenSpec change deltas.
+
+## Requirements
+
+### Requirement: Configurable provider priority
+The system SHALL support configuring image provider order via `ROYALTY_IMAGE_PROVIDERS` environment variable.
+
+#### Scenario: Custom provider order
+- **WHEN** `ROYALTY_IMAGE_PROVIDERS=unsplash,pexels,pixabay,wikimedia,picsum`
+- **THEN** system tries providers in order: Unsplash → Pexels → Pixabay → Wikimedia → Picsum
+
+#### Scenario: Default provider order
+- **WHEN** `ROYALTY_IMAGE_PROVIDERS` is not set or empty
+- **THEN** system uses default order: `pixabay,unsplash,pexels,wikimedia,picsum`
+
+#### Scenario: Single provider configured
+- **WHEN** `ROYALTY_IMAGE_PROVIDERS=pexels`
+- **THEN** system only tries Pexels provider
+- **AND** returns `(None, None)` if Pexels fails or is not configured
+
+### Requirement: Sequential fallback execution
+The system SHALL try providers sequentially until one returns a valid image.
+
+#### Scenario: First provider succeeds
+- **WHEN** provider chain is `pixabay,unsplash,pexels` AND Pixabay returns valid image
+- **THEN** system returns Pixabay image immediately
+- **AND** does NOT call Unsplash or Pexels APIs
+
+#### Scenario: First provider fails, second succeeds
+- **WHEN** provider chain is `pixabay,unsplash,pexels` AND Pixabay returns no results AND Unsplash returns valid image
+- **THEN** system returns Unsplash image
+- **AND** does NOT call Pexels API
+
+#### Scenario: All providers fail
+- **WHEN** all configured providers return `(None, None)`
+- **THEN** system returns `(None, None)` as final result
+- **AND** caller handles fallback to article image or placeholder
+
+### Requirement: MCP endpoint override
+The existing `ROYALTY_IMAGE_MCP_ENDPOINT` SHALL take priority over the provider chain when configured.
+
+#### Scenario: MCP endpoint configured
+- **WHEN** `ROYALTY_IMAGE_MCP_ENDPOINT` is set to valid URL
+- **THEN** system tries MCP endpoint first before provider chain
+- **AND** falls back to provider chain only if MCP endpoint fails
+
+#### Scenario: MCP endpoint not configured
+- **WHEN** `ROYALTY_IMAGE_MCP_ENDPOINT` is empty or unset
+- **THEN** system skips MCP endpoint and proceeds directly to provider chain
+
+### Requirement: Provider skip on missing credentials
+Providers without required API keys SHALL be skipped silently.
+
+#### Scenario: Skip unconfigured provider
+- **WHEN** provider chain includes `pixabay` AND `PIXABAY_API_KEY` is not set
+- **THEN** Pixabay is skipped without error
+- **AND** chain continues to next provider
+
+#### Scenario: All providers skipped
+- **WHEN** no providers in chain have valid API keys configured
+- **THEN** system falls back to Wikimedia (no key required) or Picsum (always available)