source_monitor 0.2.1 → 0.3.1

data/.claude/skills/sm-architecture/reference/extraction-patterns.md

@@ -0,0 +1,192 @@
+# SourceMonitor Extraction Patterns
+
+Patterns used during Phase 3 and Phase 4 refactoring to decompose large classes into focused sub-modules.
+
+## Pattern 1: Sub-Module Extraction (FeedFetcher)
+
+**Before:** `FeedFetcher` was 627 lines handling HTTP requests, response parsing, source state updates, adaptive interval calculation, and entry processing.
+
+**After:** 285 lines in the main class + 3 sub-modules.
+
+### Structure
+
+```
+lib/source_monitor/fetching/
+  feed_fetcher.rb                    # 285 lines - orchestrator
+  feed_fetcher/
+    adaptive_interval.rb             # Interval calculation logic
+    source_updater.rb                # Source state updates + fetch log creation
+    entry_processor.rb               # Feed entry iteration + ItemCreator calls
+```
+
+### Technique
+
+1. **Create sub-directory** matching the parent class name
+2. **Extract cohesive responsibilities** into separate classes
+3. **Pass dependencies via constructor** (source, adaptive_interval)
+4. **Lazy accessor pattern** in parent:
+   ```ruby
+   def source_updater
+     @source_updater ||= SourceUpdater.new(source: source, adaptive_interval: adaptive_interval)
+   end
+   ```
+5. **Forwarding methods** for backward compatibility with tests:
+   ```ruby
+   def process_feed_entries(feed) = entry_processor.process_feed_entries(feed)
+   def jitter_offset(interval_seconds) = adaptive_interval.jitter_offset(interval_seconds)
+   ```
+6. **Require in parent file** (not autoloaded -- explicit require):
+   ```ruby
+   require "source_monitor/fetching/feed_fetcher/adaptive_interval"
+   require "source_monitor/fetching/feed_fetcher/source_updater"
+   require "source_monitor/fetching/feed_fetcher/entry_processor"
+   ```
+
+### Key Design Decisions
+
+- `AdaptiveInterval` is a pure calculator -- no side effects, receives source for reading config
+- `SourceUpdater` handles all `source.update!` calls and fetch log creation
+- `EntryProcessor` iterates entries and fires events (item_processors, after_item_created)
+- Parent `FeedFetcher` remains the public API (`#call`) and coordinates the pipeline
+
+---
+
+## Pattern 2: Configuration Decomposition
+
+**Before:** `Configuration` was 655 lines with all settings inline.
+
+**After:** 87 lines composing 12 standalone settings objects.
+
+### Structure
+
+```
+lib/source_monitor/configuration.rb          # 87 lines - composer
+lib/source_monitor/configuration/
+  http_settings.rb
+  fetching_settings.rb
+  health_settings.rb
+  scraping_settings.rb
+  realtime_settings.rb
+  retention_settings.rb
+  authentication_settings.rb
+  scraper_registry.rb
+  events.rb
+  validation_definition.rb
+  model_definition.rb
+  models.rb
+```
+
+### Technique
+
+1. **One settings class per domain** (HTTP, fetching, health, etc.)
+2. **Composition via attr_reader** in parent:
+   ```ruby
+   attr_reader :http, :scrapers, :retention, :events, :models,
+               :realtime, :fetching, :health, :authentication, :scraping
+   ```
+3. **Initialize all in constructor**:
+   ```ruby
+   def initialize
+     @http = HTTPSettings.new
+     @fetching = FetchingSettings.new
+     # ...
+   end
+   ```
+4. **Each settings class is a PORO** with `attr_accessor` and sensible defaults
+5. **Explicit require** (not autoloaded) since Configuration is boot-critical
+
+### Key Design Decisions
+
+- Settings objects are simple POROs, not ActiveModel objects
+- No validation at settings level -- validated at usage point
+- Host app accesses via `config.http.timeout = 30` (dot-chain)
+- Reset via `@config = Configuration.new` (new object, not clearing fields)
+
+---
+
+## Pattern 3: Controller Concern Extraction (ImportSessionsController)
+
+**Before:** `ImportSessionsController` was 792 lines with wizard logic, health checks, and OPML parsing.
+
+**After:** 295 lines + 4 concerns.
+
+### Structure
+
+```
+app/controllers/source_monitor/import_sessions_controller.rb   # 295 lines
+app/controllers/concerns/source_monitor/import_sessions/
+  step_navigation.rb          # Wizard step logic
+  health_checking.rb          # Health check actions
+  source_selection.rb         # Source selection/deselection
+  import_execution.rb         # Final import execution
+```
+
+### Technique
+
+1. **Group by wizard step/feature** -- each concern handles a coherent set of actions
+2. **Include in controller**:
+   ```ruby
+   include ImportSessions::StepNavigation
+   include ImportSessions::HealthChecking
+   ```
+3. **Share state via controller methods** (e.g., `@import_session`, `current_user`)
+4. **Before-action filters** stay in main controller for clarity
+
+---
+
+## Pattern 4: Processor Extraction (ItemCreator)
+
+**Before:** `ItemCreator` was 601 lines handling entry parsing, content extraction, readability processing, and item persistence.
+
+**After:** 174 lines + EntryParser (390 lines) + ContentExtractor (113 lines).
+
+### Structure
+
+```
+lib/source_monitor/items/
+  item_creator.rb                        # 174 lines - orchestrator
+  item_creator/
+    entry_parser.rb                      # 390 lines - parse feed entries
+    entry_parser/media_extraction.rb     # Media parsing concern
+    content_extractor.rb                 # 113 lines - readability processing
+```
+
+### Technique
+
+1. **EntryParser** handles all Feedjira entry field extraction:
+   - URL extraction, timestamp parsing, author normalization
+   - GUID generation, fingerprint calculation
+   - Category/tag/keyword parsing, media extraction
+   - Includes `MediaExtraction` concern for media-specific parsing
+
+2. **ContentExtractor** handles readability content processing:
+   - Decision logic for when to process content
+   - HTML wrapping for readability parser
+   - Result metadata building
+
+3. **Parent ItemCreator** remains the public API (`#call`, `.call`) and handles:
+   - Duplicate detection (by GUID or fingerprint)
+   - Create vs update decision
+   - Concurrent duplicate handling (rescue RecordNotUnique)
+
+4. **Forwarding methods** for backward compatibility (same as FeedFetcher pattern)
+
+---
+
+## Common Principles Across All Extractions
+
+1. **Public API stays on the parent** -- callers don't need to change
+2. **Backward-compatible forwarding** -- old test callsites keep working
+3. **Constructor injection** -- dependencies passed in, not looked up globally
+4. **Lazy accessors** -- sub-modules created on first use
+5. **Explicit require** for sub-modules (not autoloaded) since parent requires them
+6. **Cohesion over size** -- extract by responsibility, not arbitrary line count
+7. **No inheritance** -- composition via delegation, not subclassing
+
+## When to Apply
+
+Use sub-module extraction when a class has:
+- 3+ distinct responsibilities that can be named
+- Methods that cluster into groups with different collaborators
+- Test files that are hard to navigate due to mixed concerns
+- A clear "orchestrator" role that coordinates the extracted pieces

data/.claude/skills/sm-architecture/reference/module-map.md

@@ -0,0 +1,194 @@
+# SourceMonitor Module Map
+
+Complete module tree with each module's responsibility.
+
+## Top-Level Modules (Explicit Require)
+
+| Module | File | Responsibility |
+|--------|------|----------------|
+| `SourceMonitor` | `lib/source_monitor.rb` | Namespace root, configure/reset API, autoload declarations |
+| `Engine` | `lib/source_monitor/engine.rb` | Rails engine setup, isolate_namespace, initializers |
+| `Configuration` | `lib/source_monitor/configuration.rb` | Central config object, composes 12 settings objects |
+| `ModelExtensions` | `lib/source_monitor/model_extensions.rb` | Dynamic table names, concern/validation injection |
+| `Events` | `lib/source_monitor/events.rb` | Lifecycle event dispatch (item created, scraped, fetch completed) |
+| `Instrumentation` | `lib/source_monitor/instrumentation.rb` | ActiveSupport::Notifications wrapper |
+| `Metrics` | `lib/source_monitor/metrics.rb` | Counter/gauge tracking, notification subscribers |
+| `Health` | `lib/source_monitor/health.rb` | Health monitoring setup, fetch callback registration |
+| `Realtime` | `lib/source_monitor/realtime.rb` | ActionCable/Turbo Streams adapter and broadcaster setup |
+| `FeedJiraExtensions` | `lib/source_monitor/feedjira_extensions.rb` | Feedjira monkey-patches/extensions |
+
+## Autoloaded Modules
+
+### SourceMonitor (Root Level)
+
+| Module | File | Responsibility |
+|--------|------|----------------|
+| `HTTP` | `http.rb` | Faraday client factory with configurable timeouts, user-agent, headers |
+| `Scheduler` | `scheduler.rb` | Coordinates scheduled fetch jobs |
+| `Assets` | `assets.rb` | Asset path resolution helpers |
+
+### Analytics
+
+| Module | File | Responsibility |
+|--------|------|----------------|
+| `SourceFetchIntervalDistribution` | `analytics/source_fetch_interval_distribution.rb` | Distribution stats for fetch intervals |
+| `SourceActivityRates` | `analytics/source_activity_rates.rb` | Item creation rates per source |
+| `SourcesIndexMetrics` | `analytics/sources_index_metrics.rb` | Aggregate metrics for sources index |
+
+### Dashboard
+
+| Module | File | Responsibility |
+|--------|------|----------------|
+| `QuickAction` | `dashboard/quick_action.rb` | Quick action data object |
+| `QuickActionsPresenter` | `dashboard/quick_actions_presenter.rb` | Format quick actions for view |
+| `RecentActivity` | `dashboard/recent_activity.rb` | Recent activity query |
+| `RecentActivityPresenter` | `dashboard/recent_activity_presenter.rb` | Format activity for view |
+| `Queries` | `dashboard/queries.rb` | Dashboard aggregate queries |
+| `TurboBroadcaster` | `dashboard/turbo_broadcaster.rb` | Broadcast dashboard updates |
+| `UpcomingFetchSchedule` | `dashboard/upcoming_fetch_schedule.rb` | Next-fetch schedule display |
+
+### Fetching (Feed Fetch Pipeline)
+
+| Module | File | Responsibility |
+|--------|------|----------------|
+| `FeedFetcher` | `fetching/feed_fetcher.rb` | Main fetch orchestrator: request, parse, process entries, update source |
+| `FeedFetcher::AdaptiveInterval` | `fetching/feed_fetcher/adaptive_interval.rb` | Compute next fetch interval based on content changes |
+| `FeedFetcher::SourceUpdater` | `fetching/feed_fetcher/source_updater.rb` | Update source record after fetch (success/failure/not-modified) |
+| `FeedFetcher::EntryProcessor` | `fetching/feed_fetcher/entry_processor.rb` | Iterate feed entries, call ItemCreator, fire events |
+| `FetchRunner` | `fetching/fetch_runner.rb` | Job-level coordinator: acquire lock, run FeedFetcher, handle completion |
+| `RetryPolicy` | `fetching/retry_policy.rb` | Retry/circuit-breaker decision logic |
+| `StalledFetchReconciler` | `fetching/stalled_fetch_reconciler.rb` | Reset sources stuck in "fetching" status |
+| `AdvisoryLock` | `fetching/advisory_lock.rb` | PostgreSQL advisory lock wrapper |
+| `FetchError` | `fetching/fetch_error.rb` | Error hierarchy (TimeoutError, ConnectionError, HTTPError, ParsingError, UnexpectedResponseError) |
+
+### Items
+
+| Module | File | Responsibility |
+|--------|------|----------------|
+| `ItemCreator` | `items/item_creator.rb` | Create or update Item from feed entry |
+| `ItemCreator::EntryParser` | `items/item_creator/entry_parser.rb` | Parse Feedjira entry into attribute hash |
+| `ItemCreator::ContentExtractor` | `items/item_creator/content_extractor.rb` | Process content through readability parser |
+| `RetentionPruner` | `items/retention_pruner.rb` | Prune items by age/count per source |
+| `RetentionStrategies` | `items/retention_strategies.rb` | Strategy pattern for retention |
+| `RetentionStrategies::Destroy` | `items/retention_strategies/destroy.rb` | Hard-delete retention strategy |
+| `RetentionStrategies::SoftDelete` | `items/retention_strategies/soft_delete.rb` | Soft-delete retention strategy |
+
+### ImportSessions
+
+| Module | File | Responsibility |
+|--------|------|----------------|
+| `EntryNormalizer` | `import_sessions/entry_normalizer.rb` | Normalize OPML entries to standard format |
+| `HealthCheckBroadcaster` | `import_sessions/health_check_broadcaster.rb` | Broadcast health check progress via Turbo Streams |
+
+### Jobs
+
+| Module | File | Responsibility |
+|--------|------|----------------|
+| `CleanupOptions` | `jobs/cleanup_options.rb` | Options for job cleanup tasks |
+| `Visibility` | `jobs/visibility.rb` | Configure queue visibility for Solid Queue |
+| `SolidQueueMetrics` | `jobs/solid_queue_metrics.rb` | Extract metrics from Solid Queue tables |
+| `FetchFailureSubscriber` | `jobs/fetch_failure_subscriber.rb` | ActiveJob error subscriber for fetch failures |
+
+### Logs
+
+| Module | File | Responsibility |
+|--------|------|----------------|
+| `EntrySync` | `logs/entry_sync.rb` | Sync FetchLog/ScrapeLog/HealthCheckLog to unified LogEntry |
+| `FilterSet` | `logs/filter_set.rb` | Log filtering parameters |
+| `Query` | `logs/query.rb` | Log query builder |
+| `TablePresenter` | `logs/table_presenter.rb` | Format log entries for table display |
+
+### Models (Shared Concerns)
+
+| Module | File | Responsibility |
+|--------|------|----------------|
+| `Sanitizable` | `models/sanitizable.rb` | `sanitizes_string_attributes`, `sanitizes_hash_attributes` class methods |
+| `UrlNormalizable` | `models/url_normalizable.rb` | `normalizes_urls`, `validates_url_format` class methods |
+
+### Scrapers (Scraper Adapters)
+
+| Module | File | Responsibility |
+|--------|------|----------------|
+| `Base` | `scrapers/base.rb` | Abstract scraper interface |
+| `Readability` | `scrapers/readability.rb` | Default readability-based scraper |
+| `Fetchers::HttpFetcher` | `scrapers/fetchers/http_fetcher.rb` | HTTP content fetcher for scrapers |
+| `Parsers::ReadabilityParser` | `scrapers/parsers/readability_parser.rb` | Parse HTML to readable content |
+
+### Scraping (Scraping Orchestration)
+
+| Module | File | Responsibility |
+|--------|------|----------------|
+| `Enqueuer` | `scraping/enqueuer.rb` | Queue scrape jobs for items |
+| `Scheduler` | `scraping/scheduler.rb` | Schedule scraping across sources |
+| `ItemScraper` | `scraping/item_scraper.rb` | Scrape a single item |
+| `ItemScraper::AdapterResolver` | `scraping/item_scraper/adapter_resolver.rb` | Select scraper adapter for a source |
+| `ItemScraper::Persistence` | `scraping/item_scraper/persistence.rb` | Save scrape results to ItemContent |
+| `BulkSourceScraper` | `scraping/bulk_source_scraper.rb` | Scrape all pending items for a source |
+| `BulkResultPresenter` | `scraping/bulk_result_presenter.rb` | Format bulk scrape results |
+| `State` | `scraping/state.rb` | Track scraping state per source |
+
+### Configuration (12 Settings Files)
+
+| Module | File | Responsibility |
+|--------|------|----------------|
+| `HTTPSettings` | `configuration/http_settings.rb` | HTTP timeouts, user-agent, proxy |
+| `FetchingSettings` | `configuration/fetching_settings.rb` | Adaptive interval params, retry config |
+| `HealthSettings` | `configuration/health_settings.rb` | Health check thresholds, auto-pause config |
+| `ScrapingSettings` | `configuration/scraping_settings.rb` | Scraping concurrency, timeouts |
+| `RealtimeSettings` | `configuration/realtime_settings.rb` | ActionCable/Turbo Streams config |
+| `RetentionSettings` | `configuration/retention_settings.rb` | Item retention strategy, defaults |
+| `AuthenticationSettings` | `configuration/authentication_settings.rb` | Auth callbacks for host app |
+| `ScraperRegistry` | `configuration/scraper_registry.rb` | Register custom scraper adapters |
+| `Events` | `configuration/events.rb` | Event callback storage |
+| `ValidationDefinition` | `configuration/validation_definition.rb` | Host-app validation definitions |
+| `ModelDefinition` | `configuration/model_definition.rb` | Per-model extension definitions |
+| `Models` | `configuration/models.rb` | Model registry and table prefix config |
+
+### Health
+
+| Module | File | Responsibility |
+|--------|------|----------------|
+| `SourceHealthMonitor` | `health/source_health_monitor.rb` | Calculate rolling success rate, update health_status |
+| `SourceHealthCheck` | `health/source_health_check.rb` | Perform HTTP health check on a source |
+| `SourceHealthReset` | `health/source_health_reset.rb` | Reset health state for a source |
+| `ImportSourceHealthCheck` | `health/import_source_health_check.rb` | Health check for import session sources |
+
+### Security
+
+| Module | File | Responsibility |
+|--------|------|----------------|
+| `ParameterSanitizer` | `security/parameter_sanitizer.rb` | Sanitize controller parameters |
+| `Authentication` | `security/authentication.rb` | Authentication helper callbacks |
+
+### Setup (Install Wizard)
+
+| Module | File | Responsibility |
+|--------|------|----------------|
+| `CLI` | `setup/cli.rb` | Command-line interface for setup |
+| `Workflow` | `setup/workflow.rb` | Step-by-step setup orchestration |
+| `Requirements` | `setup/requirements.rb` | System requirements checking |
+| `Detectors` | `setup/detectors.rb` | Detect existing config/gems |
+| `DependencyChecker` | `setup/dependency_checker.rb` | Check gem dependencies |
+| `GemfileEditor` | `setup/gemfile_editor.rb` | Edit host app Gemfile |
+| `BundleInstaller` | `setup/bundle_installer.rb` | Run bundle install |
+| `NodeInstaller` | `setup/node_installer.rb` | Install Node.js dependencies |
+| `InstallGenerator` | `setup/install_generator.rb` | Rails generator for install |
+| `MigrationInstaller` | `setup/migration_installer.rb` | Copy and run migrations |
+| `InitializerPatcher` | `setup/initializer_patcher.rb` | Patch host app initializer |
+| `Verification::Result` | `setup/verification/result.rb` | Verification result + summary |
+| `Verification::Runner` | `setup/verification/runner.rb` | Run all verification checks |
+| `Verification::Printer` | `setup/verification/printer.rb` | Print verification results |
+| `Verification::SolidQueueVerifier` | `setup/verification/solid_queue_verifier.rb` | Verify Solid Queue setup |
+| `Verification::ActionCableVerifier` | `setup/verification/action_cable_verifier.rb` | Verify Action Cable setup |
+| `Verification::TelemetryLogger` | `setup/verification/telemetry_logger.rb` | Log setup telemetry |
+
+### Other
+
+| Module | File | Responsibility |
+|--------|------|----------------|
+| `Pagination::Paginator` | `pagination/paginator.rb` | Offset-based pagination helper |
+| `Release::Changelog` | `release/changelog.rb` | Generate changelog from git history |
+| `Release::Runner` | `release/runner.rb` | Coordinate gem release process |
+| `Sources::Params` | `sources/params.rb` | Strong parameter definitions |
+| `Sources::TurboStreamPresenter` | `sources/turbo_stream_presenter.rb` | Source Turbo Stream formatting |
+| `TurboStreams::StreamResponder` | `turbo_streams/stream_responder.rb` | Turbo Stream response builder |

data/.claude/skills/sm-configuration-setting/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: sm-configuration-setting
+description: How to add or modify configuration settings in the Source Monitor engine. Use when adding a new config option, modifying defaults, creating a new settings section, or understanding the configuration architecture.
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# Source Monitor Configuration Settings
+
+## Architecture Overview
+
+The `SourceMonitor::Configuration` class was refactored from 655 lines into a lean 87-line orchestrator plus 12 extracted settings files. Each settings file follows a consistent pattern.
+
+```
+lib/source_monitor/configuration.rb          # Main class (87 lines)
+lib/source_monitor/configuration/
+  authentication_settings.rb                  # Auth handlers
+  events.rb                                   # Callbacks and processors
+  fetching_settings.rb                        # Adaptive interval tuning
+  health_settings.rb                          # Health monitoring thresholds
+  http_settings.rb                            # HTTP client defaults
+  model_definition.rb                         # Concern/validation injection
+  models.rb                                   # Model definitions registry
+  realtime_settings.rb                        # ActionCable adapter config
+  retention_settings.rb                       # Item retention policies
+  scraper_registry.rb                         # Scraper adapter registry
+  scraping_settings.rb                        # Scraping concurrency limits
+  validation_definition.rb                    # Validation DSL
+```
+
+## How Configuration Works
+
+```ruby
+# In host app initializer
+SourceMonitor.configure do |config|
+  config.fetching.min_interval_minutes = 10
+  config.http.timeout = 30
+  config.retention.strategy = :soft_delete
+end
+
+# Access at runtime
+SourceMonitor.config.fetching.min_interval_minutes  # => 10
+```
+
+The `config` object is a `SourceMonitor::Configuration` instance. Sub-sections are accessed via reader methods that return settings objects.
+
+## Adding a Setting to an Existing Section
+
+### Step 1: Identify the Settings File
+
+| Setting Category | File | Class |
+|-----------------|------|-------|
+| HTTP client | `http_settings.rb` | `HTTPSettings` |
+| Adaptive fetching | `fetching_settings.rb` | `FetchingSettings` |
+| Health monitoring | `health_settings.rb` | `HealthSettings` |
+| Scraping limits | `scraping_settings.rb` | `ScrapingSettings` |
+| Item retention | `retention_settings.rb` | `RetentionSettings` |
+| Realtime/cable | `realtime_settings.rb` | `RealtimeSettings` |
+| Authentication | `authentication_settings.rb` | `AuthenticationSettings` |
+| Events/callbacks | `events.rb` | `Events` |
+| Scraper adapters | `scraper_registry.rb` | `ScraperRegistry` |
+| Model extensions | `models.rb` / `model_definition.rb` | `Models` / `ModelDefinition` |
+
+### Step 2: Add the Attribute
+
+```ruby
+# lib/source_monitor/configuration/fetching_settings.rb
+class FetchingSettings
+  attr_accessor :min_interval_minutes,
+    :max_interval_minutes,
+    :increase_factor,
+    :decrease_factor,
+    :failure_increase_factor,
+    :jitter_percent,
+    :my_new_setting              # <-- Add here
+
+  def reset!
+    @min_interval_minutes = 5
+    @max_interval_minutes = 24 * 60
+    @increase_factor = 1.25
+    @decrease_factor = 0.75
+    @failure_increase_factor = 1.5
+    @jitter_percent = 0.1
+    @my_new_setting = "default"  # <-- Set default here
+  end
+end
+```
+
+### Step 3: Write Tests
+
+```ruby
+# test/lib/source_monitor/configuration_test.rb
+test "my_new_setting has correct default" do
+  assert_equal "default", SourceMonitor.config.fetching.my_new_setting
+end
+
+test "my_new_setting can be overridden" do
+  SourceMonitor.configure do |config|
+    config.fetching.my_new_setting = "custom"
+  end
+  assert_equal "custom", SourceMonitor.config.fetching.my_new_setting
+end
+```
+
+### Step 4: Verify Reset
+
+Ensure `reset!` restores the default. The test suite calls `SourceMonitor.reset_configuration!` in setup, which recreates the entire Configuration object.
+
+## Adding a Setting with Validation
+
+For settings that need input normalization or validation, use custom setters:
+
+```ruby
+class ScrapingSettings
+  attr_accessor :max_in_flight_per_source, :max_bulk_batch_size
+
+  # Custom setter with normalization
+  def max_in_flight_per_source=(value)
+    @max_in_flight_per_source = normalize_numeric(value)
+  end
+
+  private
+
+  def normalize_numeric(value)
+    return nil if value.nil?
+    return nil if value == ""
+    integer = value.respond_to?(:to_i) ? value.to_i : value
+    integer.positive? ? integer : nil
+  end
+end
+```
+
+For enum-style settings with strict validation:
+
+```ruby
+class RetentionSettings
+  def strategy=(value)
+    normalized = normalize_strategy(value)
+    @strategy = normalized unless normalized.nil?
+  end
+
+  private
+
+  def normalize_strategy(value)
+    return :destroy if value.nil?
+    if value.respond_to?(:to_sym)
+      candidate = value.to_sym
+      raise ArgumentError, "Invalid retention strategy #{value.inspect}" unless %i[destroy soft_delete].include?(candidate)
+      candidate
+    else
+      raise ArgumentError, "Invalid retention strategy #{value.inspect}"
+    end
+  end
+end
+```
+
+## Creating a New Settings Section
+
+### Step 1: Create the Settings Class
+
+```ruby
+# lib/source_monitor/configuration/notifications_settings.rb
+# frozen_string_literal: true
+
+module SourceMonitor
+  class Configuration
+    class NotificationsSettings
+      attr_accessor :enabled, :channels, :throttle_seconds
+
+      def initialize
+        reset!
+      end
+
+      def reset!
+        @enabled = true
+        @channels = []
+        @throttle_seconds = 60
+      end
+    end
+  end
+end
+```
+
+### Step 2: Register in Configuration
+
+```ruby
+# lib/source_monitor/configuration.rb
+require "source_monitor/configuration/notifications_settings"
+
+class Configuration
+  attr_reader :http, :scrapers, :retention, :events, :models,
+    :realtime, :fetching, :health, :authentication, :scraping,
+    :notifications  # <-- Add reader
+
+  def initialize
+    # ... existing initialization ...
+    @notifications = NotificationsSettings.new  # <-- Initialize
+  end
+end
+```
+
+### Step 3: Write Tests
+
+```ruby
+test "notifications settings have correct defaults" do
+  settings = SourceMonitor.config.notifications
+  assert_equal true, settings.enabled
+  assert_equal [], settings.channels
+  assert_equal 60, settings.throttle_seconds
+end
+
+test "notifications settings can be configured" do
+  SourceMonitor.configure do |config|
+    config.notifications.enabled = false
+    config.notifications.channels = [:email, :slack]
+    config.notifications.throttle_seconds = 30
+  end
+
+  settings = SourceMonitor.config.notifications
+  assert_equal false, settings.enabled
+  assert_equal [:email, :slack], settings.channels
+  assert_equal 30, settings.throttle_seconds
+end
+```
+
+## Patterns by Section Type
+
+### Simple Accessor Pattern (FetchingSettings, HealthSettings)
+
+Plain `attr_accessor` with defaults in `reset!`. No validation.
+
+### Normalized Setter Pattern (ScrapingSettings)
+
+Custom setter that normalizes input (strings to integers, negatives to nil).
+
+### Enum Setter Pattern (RetentionSettings, RealtimeSettings)
+
+Custom setter that validates against an allowed list and raises `ArgumentError`.
+
+### Handler/Callback Pattern (AuthenticationSettings, Events)
+
+Registration methods that accept symbols, lambdas, or blocks.
+
+### Registry Pattern (ScraperRegistry)
+
+Named registration with lookup, unregistration, and enumeration.
+
+### Nested Object Pattern (RealtimeSettings::SolidCableOptions)
+
+Sub-objects with their own `reset!` and `to_h` methods.
+
+## Testing Checklist
+
+- [ ] Default value is correct
+- [ ] Value can be overridden via `SourceMonitor.configure`
+- [ ] `reset!` restores the default (tested via `SourceMonitor.reset_configuration!`)
+- [ ] Validation raises `ArgumentError` for invalid values (if applicable)
+- [ ] String/nil normalization works correctly (if applicable)
+- [ ] Test file: `test/lib/source_monitor/configuration_test.rb`
+- [ ] Run: `PARALLEL_WORKERS=1 bin/rails test test/lib/source_monitor/configuration_test.rb`
+
+## References
+
+- [reference/settings-catalog.md](reference/settings-catalog.md) -- All settings sections with their attributes
+- [reference/settings-pattern.md](reference/settings-pattern.md) -- Step-by-step pattern for adding settings