source_monitor 0.3.3 → 0.5.0

data/CHANGELOG.md

@@ -15,6 +15,54 @@ All notable changes to this project are documented below. The format follows [Ke
 
 - No unreleased changes yet.
 
+## [0.5.0] - 2026-02-13
+
+### Added
+
+- `bin/source_monitor upgrade` command: detects version changes since last install, copies new migrations, re-runs the generator, runs verification, and reports what changed. Uses a `.source_monitor_version` marker file for version tracking.
+- `PendingMigrationsVerifier` checks for unmigrated SourceMonitor tables in the verification suite, integrated into both `bin/source_monitor verify` and the upgrade flow.
+- Configuration deprecation framework: engine developers can register deprecated config options with `DeprecationRegistry.register`. At boot time, stale options trigger `:warning` (renamed) or `:error` (removed) messages with actionable replacement paths.
+- `sm-upgrade` AI skill guides agents through post-update workflows: CHANGELOG parsing, running the upgrade command, interpreting verification results, and handling deprecation warnings.
+- `docs/upgrade.md` versioned upgrade guide with general steps, version-specific notes (0.1.x through 0.4.x), and troubleshooting.
+- `sm-host-setup` skill cross-references the upgrade workflow.
+
+### Testing
+
+- 1,003 tests, 0 failures (up from 973 in 0.4.0).
+- RuboCop: 397 files, 0 offenses.
+- Brakeman: 0 warnings.
+
+## [0.4.0] - 2026-02-12
+
+### Added
+
+- Install generator now auto-patches `Procfile.dev` with Solid Queue `jobs:` entry and `queue.yml` with `recurring_schedule` dispatcher wiring (idempotent, skip if already present).
+- `RecurringScheduleVerifier` checks that recurring tasks are registered with Solid Queue dispatchers; `SolidQueueVerifier` remediation now mentions `Procfile.dev` for `bin/dev` users.
+- Dashboard fetch log entries display source URL (domain for RSS, item URL for scrapes) alongside existing summary.
+- External links across dashboard, logs, sources, and items open in new tab with visual indicator icon.
+- Configurable Active Storage image downloads: `config.images.download_to_active_storage` (default `false`) detects inline images in feed content, downloads them via background job, and rewrites `<img>` src attributes with Active Storage URLs.
+- `Images::ContentRewriter` extracts and rewrites image URLs from HTML content using Nokolexbor.
+- `Images::Downloader` service validates content type and size before downloading images.
+- `DownloadContentImagesJob` orchestrates the download/attach/rewrite pipeline per item.
+- SSL certificate store configuration: every Faraday connection gets an `OpenSSL::X509::Store` initialized with `set_default_paths`, resolving "unable to get local issuer certificate" errors on systems with incomplete CA bundles.
+- Configurable SSL options in `HTTPSettings`: `ssl_ca_file`, `ssl_ca_path`, `ssl_verify` for non-standard certificate environments.
+- Netflix Tech Blog VCR cassette regression test proving Medium-hosted RSS feeds parse correctly with the SSL fix.
+
+### Fixed
+
+- SSL certificate verification failures for feeds hosted on services requiring intermediate CAs (e.g., Netflix Tech Blog via Medium/AWS).
+- Setup documentation now includes `Procfile.dev` and `recurring_schedule` guidance.
+
+### Changed
+
+- Updated `sm-host-setup`, `sm-configure`, and setup documentation to reflect that the generator handles Procfile.dev and recurring_schedule automatically.
+
+### Testing
+
+- 973 tests, 3,114 assertions, 0 failures (up from 841 tests in 0.3.3).
+- RuboCop: 389 files, 0 offenses.
+- Brakeman: 0 warnings.
+
 ## [0.3.3] - 2026-02-11
 
 ### Fixed

data/CLAUDE.md

@@ -4,9 +4,10 @@
 
 ## Active Context
 
-**Milestone:** none (archived)
-**Last shipped:** default (2026-02-10) -- 4 phases, 14 plans, 841 tests
-**Next action:** /vbw:plan to start new milestone
+**Milestone:** (none active)
+**Last shipped:** upgrade-assurance (2026-02-13) -- 3 phases, 14 tasks, 12 commits
+**Previous:** generator-enhancements (2026-02-12) -- v0.4.0
+**Next action:** /vbw:vibe to start a new milestone
 
 ## Key Decisions
 
@@ -192,6 +193,7 @@ Engine-specific skills (`sm-*` prefix). Consumer skills install by default; cont
 | `sm-event-handler` | Lifecycle callbacks (after_item_created, etc.) |
 | `sm-model-extension` | Extend engine models from host app |
 | `sm-dashboard-widget` | Dashboard queries, presenters, Turbo broadcasts |
+| `sm-upgrade` | Gem upgrade workflow with CHANGELOG parsing |
 
 ### Contributor Skills (opt-in)
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    source_monitor (0.3.3)
+    source_monitor (0.5.0)
       cssbundling-rails (~> 1.4)
       faraday (~> 2.9)
       faraday-follow_redirects (~> 0.4)

data/VERSION

@@ -1 +1 @@
-0.3.3
+0.5.0

data/app/assets/builds/source_monitor/application.css

@@ -705,6 +705,10 @@ video {
   margin-right: 0.25rem;
 }
 
+.fm-admin .mt-0\.5 {
+  margin-top: 0.125rem;
+}
+
 .fm-admin .mt-1 {
   margin-top: 0.25rem;
 }
@@ -1789,6 +1793,11 @@ video {
   --tw-ring-color: transparent;
 }
 
+.fm-admin .invert {
+  --tw-invert: invert(100%);
+  filter: var(--tw-blur) var(--tw-brightness) var(--tw-contrast) var(--tw-grayscale) var(--tw-hue-rotate) var(--tw-invert) var(--tw-saturate) var(--tw-sepia) var(--tw-drop-shadow);
+}
+
 .fm-admin .filter {
   filter: var(--tw-blur) var(--tw-brightness) var(--tw-contrast) var(--tw-grayscale) var(--tw-hue-rotate) var(--tw-invert) var(--tw-saturate) var(--tw-sepia) var(--tw-drop-shadow);
 }

data/app/helpers/source_monitor/application_helper.rb

@@ -212,8 +212,46 @@ module SourceMonitor
       end
     end
 
+    # Renders a clickable link that opens in a new tab with an external-link icon.
+    # Returns the label as plain text if the URL is blank.
+    def external_link_to(label, url, **options)
+      return label if url.blank?
+
+      css = options.delete(:class) || "text-blue-600 hover:text-blue-500"
+      link_to(url, target: "_blank", rel: "noopener noreferrer", class: css, title: url, **options) do
+        safe_join([ label, " ", external_link_icon ])
+      end
+    end
+
+    # Extracts the domain from a URL, returning nil if parsing fails.
+    def domain_from_url(url)
+      return nil if url.blank?
+
+      URI.parse(url.to_s).host
+    rescue URI::InvalidURIError
+      nil
+    end
+
     private
 
+    def external_link_icon
+      tag.svg(
+        class: "inline-block h-3 w-3 text-slate-400",
+        xmlns: "http://www.w3.org/2000/svg",
+        fill: "none",
+        viewBox: "0 0 24 24",
+        stroke_width: "2",
+        stroke: "currentColor",
+        aria: { hidden: "true" }
+      ) do
+        tag.path(
+          stroke_linecap: "round",
+          stroke_linejoin: "round",
+          d: "M13.5 6H5.25A2.25 2.25 0 003 8.25v10.5A2.25 2.25 0 005.25 21h10.5A2.25 2.25 0 0018 18.75V10.5m-10.5 6L21 3m0 0h-5.25M21 3v5.25"
+        )
+      end
+    end
+
     def derive_item_scrape_status(item:, source: nil)
       return "idle" unless item
 

data/app/jobs/source_monitor/download_content_images_job.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module SourceMonitor
+  class DownloadContentImagesJob < ApplicationJob
+    source_monitor_queue :fetch
+
+    discard_on ActiveJob::DeserializationError
+
+    def perform(item_id)
+      item = SourceMonitor::Item.find_by(id: item_id)
+      return unless item
+      return unless SourceMonitor.config.images.download_enabled?
+
+      html = item.content
+      return if html.blank?
+
+      # Build or find item_content for attachment storage
+      item_content = item.item_content || item.build_item_content
+
+      # Skip if images already attached (idempotency)
+      return if item_content.persisted? && item_content.images.attached?
+
+      base_url = item.url
+      rewriter = SourceMonitor::Images::ContentRewriter.new(html, base_url: base_url)
+      image_urls = rewriter.image_urls
+      return if image_urls.empty?
+
+      # Save item_content first so we can attach blobs to it
+      item_content.save! unless item_content.persisted?
+
+      # Download images and build URL mapping
+      url_mapping = download_images(item_content, image_urls)
+      return if url_mapping.empty?
+
+      # Rewrite HTML with Active Storage URLs
+      rewritten_html = rewriter.rewrite do |original_url|
+        url_mapping[original_url]
+      end
+
+      # Update the item content with rewritten HTML
+      item.update!(content: rewritten_html)
+    end
+
+    private
+
+    def download_images(item_content, image_urls)
+      url_mapping = {}
+      settings = SourceMonitor.config.images
+
+      image_urls.each do |image_url|
+        result = SourceMonitor::Images::Downloader.new(image_url, settings: settings).call
+        next unless result
+
+        blob = ActiveStorage::Blob.create_and_upload!(
+          io: result.io,
+          filename: result.filename,
+          content_type: result.content_type
+        )
+        item_content.images.attach(blob)
+
+        # Generate a serving URL for the blob
+        url_mapping[image_url] = Rails.application.routes.url_helpers.rails_blob_path(blob, only_path: true)
+      rescue StandardError
+        # Individual image failure should not block others.
+        # Original URL will be preserved (graceful fallback).
+        next
+      end
+
+      url_mapping
+    end
+  end
+end

data/app/models/source_monitor/item_content.rb

@@ -6,6 +6,8 @@ module SourceMonitor
 
     validates :item, presence: true
 
+    has_many_attached :images if defined?(ActiveStorage)
+
     SourceMonitor::ModelExtensions.register(self, :item_content)
   end
 end

data/app/views/source_monitor/dashboard/_recent_activity.html.erb

@@ -21,6 +21,15 @@
             <div class="mt-1 text-xs text-slate-500">
               <%= event[:description].presence || "No additional details recorded." %>
             </div>
+            <% if event[:url_display].present? %>
+              <div class="mt-0.5 text-xs text-slate-400 truncate max-w-sm" data-testid="event-url-display">
+                <% if event[:url_href].present? %>
+                  <%= external_link_to event[:url_display], event[:url_href], class: "text-slate-400 hover:text-blue-500" %>
+                <% else %>
+                  <%= event[:url_display] %>
+                <% end %>
+              </div>
+            <% end %>
           </div>
           <div class="text-right">
             <span class="inline-flex items-center rounded-full px-3 py-1 text-xs font-semibold <%= event[:status] == :success ? "bg-green-100 text-green-700" : "bg-rose-100 text-rose-700" %>">

data/app/views/source_monitor/items/_details.html.erb

@@ -53,8 +53,8 @@
           <% details = {
                "GUID" => item.guid,
                "Content Fingerprint" => item.content_fingerprint || "—",
-               "URL" => item.url,
-               "Canonical URL" => item.canonical_url || "—",
+               "URL" => (item.url.present? ? external_link_to(item.url, item.url, class: "text-slate-900 hover:text-blue-500") : "\u2014"),
+               "Canonical URL" => (item.canonical_url.present? ? external_link_to(item.canonical_url, item.canonical_url, class: "text-slate-900 hover:text-blue-500") : "\u2014"),
                "Author" => item.author || "—",
                "Published At" => (item.published_at&.strftime("%b %d, %Y %H:%M %Z") || "—"),
                "Updated At (Source)" => (item.updated_at_source&.strftime("%b %d, %Y %H:%M %Z") || "—"),

data/app/views/source_monitor/logs/index.html.erb

@@ -134,6 +134,15 @@
               <% else %>
                 <%= row.primary_label %>
               <% end %>
+              <% if row.url_label.present? %>
+                <div class="mt-0.5 text-xs text-slate-400 truncate max-w-xs">
+                  <% if row.url_href.present? %>
+                    <%= external_link_to row.url_label, row.url_href, class: "text-slate-400 hover:text-blue-500" %>
+                  <% else %>
+                    <%= row.url_label %>
+                  <% end %>
+                </div>
+              <% end %>
             </td>
             <td class="px-6 py-4 text-sm">
               <% if row.source_path %>

data/app/views/source_monitor/sources/_details.html.erb

@@ -25,7 +25,7 @@
           </span>
         <% end %>
       </div>
-      <p class="mt-2 text-sm text-slate-500">Feed URL: <%= source.feed_url %></p>
+      <p class="mt-2 text-sm text-slate-500">Feed URL: <%= external_link_to source.feed_url, source.feed_url, class: "text-slate-500 hover:text-blue-500" %></p>
     </div>
     <div class="flex flex-wrap items-center justify-end gap-3">
       <% fetch_disabled = %w[queued fetching].include?(source.fetch_status) %>
@@ -137,7 +137,7 @@
                end
 
              details = {
-               "Website" => (source.website_url.presence || "—"),
+               "Website" => (source.website_url.present? ? external_link_to(source.website_url, source.website_url, class: "text-slate-900 hover:text-blue-500") : "\u2014"),
                "Fetch interval" => "#{source.fetch_interval_minutes} minutes (~#{interval_hours} hours)",
                "Adaptive interval" => source.adaptive_fetching_enabled? ? "Auto" : "Fixed",
                "Scraper" => source.scraper_adapter,

data/app/views/source_monitor/sources/_row.html.erb

@@ -29,7 +29,7 @@
             class: "text-slate-900 hover:text-blue-600 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2",
             data: { turbo_frame: "_top" } %>
     </div>
-    <div class="text-xs text-slate-500 truncate max-w-xs"><%= source.feed_url %></div>
+    <div class="text-xs text-slate-500 truncate max-w-xs"><%= external_link_to source.feed_url, source.feed_url, class: "text-slate-500 hover:text-blue-500" %></div>
   </td>
   <td class="px-6 py-4">
     <div class="flex flex-col gap-2 text-xs">

data/docs/setup.md

@@ -49,7 +49,12 @@ This ensures Bundler can load SourceMonitor so the commands below are available.
    ```bash
    bin/rails solid_queue:start
    ```
-   Recurring jobs (fetch scheduling, scraping, cleanup) are automatically configured in `config/recurring.yml` by the install generator. They'll run automatically with `bin/dev` or `bin/jobs`.
+   The install generator automatically handles all worker configuration:
+   - **Recurring jobs** are configured in `config/recurring.yml` (fetch scheduling, scraping, cleanup).
+   - **Procfile.dev** is patched with a `jobs:` entry so `bin/dev` starts Solid Queue alongside the web server.
+   - **Queue dispatcher** is patched with `recurring_schedule: config/recurring.yml` in `config/queue.yml` so recurring jobs load on startup.
+
+   All three steps are idempotent. If any configuration is missing, re-run: `bin/rails generate source_monitor:install`
 
 4. **Visit the dashboard** at the chosen mount path, create a source, and trigger “Fetch Now” to validate realtime updates and Solid Queue processing.
 
@@ -87,6 +92,8 @@ Prefer to script each step or plug SourceMonitor into an existing deployment che
 | 4 | `bin/rails railties:install:migrations FROM=source_monitor` | Copy engine migrations (idempotent) |
 | 5 | `bin/rails db:migrate` | Apply schema updates, including Solid Queue tables |
 | 6 | `bin/rails solid_queue:start` | Ensure jobs process via Solid Queue |
+| 6a | Handled by generator (patches `Procfile.dev`) | Ensure `bin/dev` starts Solid Queue workers |
+| 6b | Handled by generator (patches `config/queue.yml`) | Wire recurring jobs into Solid Queue dispatcher |
 | 7 | `bin/jobs --recurring_schedule_file=config/recurring.yml` | Start recurring scheduler (optional but recommended) |
 | 8 | `bin/source_monitor verify` | Confirm Solid Queue/Action Cable readiness and emit telemetry |
 
@@ -100,6 +107,8 @@ Prefer to script each step or plug SourceMonitor into an existing deployment che
 4. **Apply database changes** using `bin/rails db:migrate`. If your host already installed Solid Queue migrations manually, delete duplicate files before migrating.
 5. **Wire Action Cable** if necessary. SourceMonitor defaults to Solid Cable; confirm `ApplicationCable::Connection`/`Channel` exist and that `config/initializers/source_monitor.rb` uses the adapter you expect. To switch to Redis, set `config.realtime.adapter = :redis` and `config.realtime.redis_url`.
 6. **Start workers** with `bin/rails solid_queue:start` (or your process manager). The install generator automatically configures recurring jobs in `config/recurring.yml` for fetch scheduling, scraping, and cleanup. They'll run with `bin/dev` or `bin/jobs`.
+   - **Procfile.dev:** The generator automatically patches `Procfile.dev` with a `jobs:` entry for Solid Queue. Verify the file contains `jobs: bundle exec rake solid_queue:start` after running the generator.
+   - **Recurring schedule:** The generator automatically patches `config/queue.yml` dispatchers with `recurring_schedule: config/recurring.yml`. Verify the key is present after running the generator.
 7. **Review the initializer** and tune queue names, HTTP timeouts, scraping adapters, retention limits, authentication hooks, and Mission Control integration. The [configuration reference](configuration.md) details every option.
 8. **Verify the install**: run `bin/source_monitor verify` to ensure Solid Queue workers and Action Cable are healthy, then visit the mount path to trigger a fetch manually. Enable telemetry if you want JSON logs recorded for support.
 

data/docs/troubleshooting.md

@@ -20,45 +20,76 @@ This guide lists common issues you might encounter while installing, upgrading,
 - Ensure at least one Solid Queue worker is running; the dashboard reads visibility data via `SourceMonitor::Jobs::Visibility`.
 - When using mission control integration, keep `config.mission_control_dashboard_path` pointing at a valid route helper; otherwise the dashboard hides the link.
 
-## 4. Realtime Updates Do Not Stream
+## 4. Recurring Jobs Not Running
+
+- **Symptoms:** Fetch scheduling, scrape scheduling, and cleanup jobs never fire. Sources never auto-fetch on their configured intervals.
+- **Primary fix:** Re-run the install generator, which automatically patches the dispatcher config:
+  ```bash
+  bin/rails generate source_monitor:install
+  ```
+- **Diagnostics:** Run `bin/source_monitor verify` to check recurring task registration. The RecurringScheduleVerifier will report whether SourceMonitor recurring tasks are loaded into Solid Queue.
+- **Manual check:** Verify `config/queue.yml` includes `recurring_schedule: config/recurring.yml` under the `dispatchers:` section. Without this key, Solid Queue's dispatcher will not load the recurring schedule even though `config/recurring.yml` exists.
+- **Manual fix (if generator cannot patch):**
+  ```yaml
+  dispatchers:
+    - polling_interval: 1
+      batch_size: 500
+      recurring_schedule: config/recurring.yml
+  ```
+
+## 5. Jobs Not Processing with bin/dev
+
+- **Symptoms:** `bin/dev` starts the web server but jobs never run. Running `bin/rails solid_queue:start` manually works fine.
+- **Primary fix:** Re-run the install generator, which automatically patches `Procfile.dev`:
+  ```bash
+  bin/rails generate source_monitor:install
+  ```
+- **Diagnostics:** Run `bin/source_monitor verify` to check Solid Queue worker status. The SolidQueueVerifier will suggest Procfile.dev if no workers are detected.
+- **Manual check:** Verify `Procfile.dev` includes a `jobs:` line:
+  ```
+  jobs: bundle exec rake solid_queue:start
+  ```
+- Most Rails 8 apps use foreman or overmind via `bin/dev`. Without a `jobs:` entry, the process manager only starts the web server and asset watchers -- Solid Queue workers are not launched.
+
+## 6. Realtime Updates Do Not Stream
 
 - Confirm Action Cable is mounted and `ApplicationCable` classes exist (see installation guide).
 - In production, verify WebSocket proxy settings allow the `/cable` endpoint.
 - When switching to Redis, add `config.realtime.adapter = :redis` and `config.realtime.redis_url` in the initializer, then restart web and worker processes.
 - For Solid Cable, check that the `solid_cable_messages` table exists and that no other process clears it unexpectedly.
 
-## 5. Fetch Jobs Keep Failing
+## 7. Fetch Jobs Keep Failing
 
 - Review the most recent fetch log entry for the source; it stores the HTTP status, error class, and error message.
 - Increase `config.http.timeout` or `config.http.retry_max` if the feed is slow or prone to transient errors.
 - Supply custom headers or basic auth credentials via the source form when feeds require authentication.
 - Check for TLS issues on self-signed feeds; you may need to configure Faraday with custom SSL options.
 
-## 6. Scraping Returns "Failed"
+## 8. Scraping Returns "Failed"
 
 - Confirm the source has scraping enabled and the configured adapter exists.
 - Override selectors in the source's scrape settings if the default Readability extraction misses key elements.
 - Inspect the scrape log to see the adapter status and content length. Logs store the HTTP status and any exception raised by the adapter.
 - Retry manually from the item detail page after fixing selectors.
 
-## 7. Cleanup Rake Tasks Fail
+## 9. Cleanup Rake Tasks Fail
 
 - Pass numeric values for `FETCH_LOG_DAYS` or `SCRAPE_LOG_DAYS` environment variables (e.g., `FETCH_LOG_DAYS=30`).
 - Ensure workers or the console environment have permission to soft delete (`SOFT_DELETE=true`) if you expect tombstones.
 - If job classes cannot load, verify `SourceMonitor.configure` ran before calling `rake source_monitor:cleanup:*`.
 
-## 8. Test Suite Cannot Launch a Browser
+## 10. Test Suite Cannot Launch a Browser
 
 - System tests rely on Selenium + Chrome. Install Chrome/Chromium and set `SELENIUM_CHROME_BINARY` if the binary lives in a non-standard path.
 - You can run `rbenv exec bin/test-coverage --verbose` to inspect failures with additional logging.
 
-## 9. Mission Control Jobs Link Returns 404
+## 11. Mission Control Jobs Link Returns 404
 
 - Mount `MissionControl::Jobs::Engine` in your host routes (for example, `mount MissionControl::Jobs::Engine, at: "/mission_control"`).
 - Keep `config.mission_control_enabled = true` **and** `config.mission_control_dashboard_path` pointing at that mounted route helper. Call `SourceMonitor.mission_control_dashboard_path` in the Rails console to confirm it resolves.
 - When hosting Mission Control in a separate app, provide a full URL instead of a route helper and ensure CORS/WebSocket settings allow the dashboard iframe.
 
-## 10. Tailwind Build Fails or Admin UI Loads Without Styles
+## 12. Tailwind Build Fails or Admin UI Loads Without Styles
 
 - Running `test/dummy/bin/dev` before configuring the bundling pipeline will serve the admin UI without Tailwind styles or Stimulus behaviours. This happens because the engine no longer ships precompiled assets; see `.ai/engine-asset-configuration.md:11-44` for the required npm setup.
 - Fix by running `npm install` followed by `npm run build` inside the engine root so that `app/assets/builds/source_monitor/application.css` and `application.js` exist. The Rake task `app:source_monitor:assets:build` wraps the same scripts for CI usage.

data/docs/upgrade.md

@@ -0,0 +1,140 @@
+# SourceMonitor Upgrade Guide
+
+This guide covers upgrading SourceMonitor to a new gem version in your host Rails application.
+
+## General Upgrade Steps
+
+1. Review the [CHANGELOG](../CHANGELOG.md) for changes between your current and target versions
+2. Update your Gemfile version constraint and run `bundle update source_monitor`
+3. Run the upgrade command: `bin/source_monitor upgrade`
+4. Apply database migrations if new ones were copied: `bin/rails db:migrate`
+5. Address any deprecation warnings in your initializer (see Deprecation Handling below)
+6. Run verification: `bin/source_monitor verify`
+7. Restart your web server and background workers
+
+## Quick Upgrade (Most Cases)
+
+```bash
+# 1. Update the gem
+bundle update source_monitor
+
+# 2. Run the upgrade command (handles migrations, generator, verification)
+bin/source_monitor upgrade
+
+# 3. Migrate if needed
+bin/rails db:migrate
+
+# 4. Restart
+# (restart web server and Solid Queue workers)
+```
+
+## Deprecation Handling
+
+When upgrading, you may see deprecation warnings in your Rails log:
+
+```
+[SourceMonitor] DEPRECATION: 'http.old_option' was deprecated in v0.5.0 and replaced by 'http.new_option'.
+```
+
+To resolve:
+1. Open `config/initializers/source_monitor.rb`
+2. Find the deprecated option (e.g., `config.http.old_option = value`)
+3. Replace with the new option from the warning message (e.g., `config.http.new_option = value`)
+4. Restart and verify the warning is gone
+
+If a removed option raises an error (`SourceMonitor::DeprecatedOptionError`), you must update the initializer before the app can boot.
+
+## Version-Specific Notes
+
+### Upgrading to 0.4.0 (from 0.3.x)
+
+**Released:** 2026-02-12
+
+**What changed:**
+- Install generator now auto-patches `Procfile.dev` with a Solid Queue `jobs:` entry
+- Install generator now patches `config/queue.yml` dispatcher with `recurring_schedule: config/recurring.yml`
+- Active Storage image download feature added (opt-in)
+- SSL certificate configuration added to HTTP settings
+- Enhanced verification messages for SolidQueue and RecurringSchedule verifiers
+
+**Upgrade steps:**
+```bash
+bundle update source_monitor
+bin/source_monitor upgrade
+bin/rails db:migrate
+```
+
+**Notes:**
+- No breaking changes. All existing configuration remains valid.
+- Re-running the generator (`bin/rails generate source_monitor:install`) will add missing `Procfile.dev` and `queue.yml` entries without overwriting existing config.
+- New optional features: `config.images.download_to_active_storage = true`, `config.http.ssl_ca_file`, `config.http.ssl_ca_path`, `config.http.ssl_verify`.
+
+### Upgrading to 0.3.0 (from 0.2.x)
+
+**Released:** 2026-02-10
+
+**What changed:**
+- Internal refactoring: FeedFetcher, Configuration, ImportSessionsController, and ItemCreator extracted into smaller modules
+- Eager requires replaced with Ruby autoload
+- Skills system added (14 `sm-*` Claude Code skills)
+
+**Upgrade steps:**
+```bash
+bundle update source_monitor
+bin/source_monitor upgrade
+bin/rails db:migrate
+```
+
+**Notes:**
+- No breaking changes to the public API.
+- If you referenced internal classes directly (e.g., `SourceMonitor::FeedFetcher` internals), verify your code against the new module structure.
+- Optionally install AI skills: `bin/rails source_monitor:skills:install`
+
+### Upgrading to 0.2.0 (from 0.1.x)
+
+**Released:** 2025-11-25
+
+**What changed:**
+- OPML import wizard with multi-step flow
+- New `ImportHistory` model and associated migrations
+
+**Upgrade steps:**
+```bash
+bundle update source_monitor
+bin/rails railties:install:migrations FROM=source_monitor
+bin/rails db:migrate
+```
+
+**Notes:**
+- New database tables required. Run migrations after updating.
+- No configuration changes needed.
+
+## Troubleshooting
+
+### "Already up to date" but I expected changes
+- Verify the gem version actually changed: `bundle show source_monitor`
+- Check `Gemfile.lock` for the resolved version
+- If the `.source_monitor_version` marker was manually edited, delete it and re-run upgrade
+
+### Migrations fail with duplicate timestamps
+- Remove the duplicate migration file from `db/migrate/` (keep the newer one)
+- Re-run `bin/rails db:migrate`
+
+### Deprecation error prevents boot
+- Read the error message for the replacement option
+- Update your initializer before restarting
+- If unsure which option to use, consult [Configuration Reference](configuration.md)
+
+### Verification failures after upgrade
+- **PendingMigrations:** Run `bin/rails db:migrate`
+- **SolidQueue:** Ensure workers are running. Check `Procfile.dev` for a `jobs:` entry.
+- **RecurringSchedule:** Re-run `bin/rails generate source_monitor:install` to patch `config/queue.yml`
+- **ActionCable:** Configure Solid Cable or Redis adapter
+
+For additional help, see [Troubleshooting](troubleshooting.md).
+
+## See Also
+- [Setup Guide](setup.md) -- Initial installation
+- [Configuration Reference](configuration.md) -- All configuration options
+- [Troubleshooting](troubleshooting.md) -- Common issues and fixes
+- [CHANGELOG](../CHANGELOG.md) -- Full version history