source_monitor 0.3.2 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 24dc578d91173b255c4d1a4ecc7d85542c5c2a86daabac9ee779b73c4f012ed5
-  data.tar.gz: 43f2ae2005109c50a5c3298c315a48092926411e02a8a4715459e39304324e14
+  metadata.gz: ae2bf8e389d7c36d4f7061a13f7f4bb213c8365408f9d0c1fb818ea25b385ff7
+  data.tar.gz: a3b8b537ea6bb06251edbc53a203d9c9e9c20a1d555679a722f00ff62eef9967
 SHA512:
-  metadata.gz: 640830590b4e1638b0fd2e90c337f49f41c788948abd7a2552338a15e80b13560da320d449ec55fad12a6a9724916af2e1a0942129ca396e9c11f0ddb3abcc89
-  data.tar.gz: 5dae4fbfe5864a33fd2895a275f2511d014e5a94ccf49a19bc1f4d0c284bd9045a561c003e945fec3acf9565b116f868616c45566310857675f3b02d3768f0e8
+  metadata.gz: 418df72b1757e7a941e645e171d00f012072c5f2974352851015cc3501adf6a546703a0b3cc38c35de7f1d6034b05c4bf13ce162815640a609612d395a40ac3d
+  data.tar.gz: bef273caaf974979aa4a9e5dce7c4b0043efa47149a0b3f2bcba80874f7b3ff303e5f4672e90ab176d79306a4085ff6ed692f883709a37490e7df279595803e7

data/.claude/agent-memory/vbw-vbw-dev/MEMORY.md

@@ -0,0 +1,34 @@
+# VBW Dev Agent Memory
+
+## Project: source_monitor
+- Rails engine gem for RSS/feed monitoring
+- Ruby 3.4.4, Rails 8.x
+- Test suite: 473 tests via `bin/rails test` (takes ~76 seconds)
+- RuboCop uses `rubocop-rails-omakase` base config
+
+## Key Learnings
+
+### Shell/Bash in zsh
+- `!` in zsh inline scripts causes `command not found` errors. Use `case` statements instead of `if ! ...` patterns.
+- Use `IFS= read -r` when reading filenames from pipes to handle edge cases.
+
+### RuboCop scope vs git scope
+- RuboCop inspects ALL Ruby-like files (Gemfile, Rakefile, .gemspec, .rake, bin/*, config.ru), not just `.rb` files.
+- `git ls-files -- '*.rb'` only matches `.rb` extensions. Plans scoped to `.rb` files may miss RuboCop violations in non-`.rb` Ruby files.
+- `test/tmp/` contains untracked generated Rails app templates. These are NOT git-tracked but RuboCop scans them unless excluded.
+
+### File structure
+- `test/lib/tmp/install_generator/` contains test fixtures (1 tracked file: `config/initializers/source_monitor.rb`)
+- `test/tmp/host_app_template_*` directories are generated test artifacts, not git-tracked
+- `.rubocop.yml` is at project root, inherits from `rubocop-rails-omakase`
+
+### Frozen string literal pragma
+- Completed in commit `5f02db8` -- 113 files modified
+- Added `test/tmp/**/*` to RuboCop exclude list
+
+### RuboCop omakase ruleset details
+- Only 45 cops enabled (out of 775 available)
+- ALL Metrics cops disabled (ClassLength, MethodLength, BlockLength, etc.)
+- After frozen_string_literal fix, codebase had zero remaining violations
+- No `.rubocop.yml` exclusions needed for large files since Metrics cops are off
+- Plan 02 completed with no code changes required

data/.claude/agent-memory/vbw-vbw-lead/MEMORY.md

@@ -0,0 +1,49 @@
+# Lead Agent Memory -- SourceMonitor
+
+## Project Quick Facts
+- Rails 8 engine, Ruby 3.4+, PostgreSQL-only
+- 325 git-tracked Ruby files, 130 test files
+- Coverage baseline: 2328 uncovered lines in config/coverage_baseline.json
+- RuboCop: rubocop-rails-omakase, config at .rubocop.yml
+- CI: .github/workflows/ci.yml (lint, security, test, release-verify, nightly profiling)
+- Large files: FeedFetcher (627), Configuration (655), ImportSessionsController (792)
+
+## Phase 1 Findings
+- 98 git-tracked .rb files missing frozen_string_literal (out of 325)
+- Breakdown: app/(5), lib/(24), test/(43 non-dummy), test/dummy/(22), config/(1), db/migrate/(4)
+- test/tmp/ is NOT git-tracked (generated by install_generator tests) -- exclude from changes
+- test/lib/tmp/install_generator/config/initializers/source_monitor.rb IS tracked and already has pragma
+- bin/rubocop wrapper forces --config .rubocop.yml
+- Phase 1 criterion #3 (10% coverage shrink) not addressed by plans 01/02 -- noted for future
+
+## Phase 2 Planning Insights
+- Coverage baseline.json has 2117 uncovered lines across 105 files (not 2328 -- that was line count)
+- Top 7 files account for ~743 uncovered lines (35% of total)
+- FeedFetcher: 245 uncovered, 12 existing tests, uses VCR+WebMock
+- ItemCreator: 228 uncovered, 8 existing tests, needs mock entries for Atom/JSON branches
+- Configuration: 94 uncovered, 5 existing tests, ~12 nested settings classes
+- Dashboard::Queries: 66 uncovered, 7 existing tests, uses raw SQL + Cache
+- BulkSourceScraper: 66 uncovered, 6 existing tests, ActiveJob test adapter
+- Broadcaster: 48 uncovered, NO existing test file -- needs creation
+- SourcesIndexMetrics: 34 uncovered, 3 existing tests
+- All 5 Phase 2 plans are Wave 1 (no inter-plan dependencies, no file conflicts)
+- Testing main files will indirectly cover supporting files (retry_policy, fetch_error, state, enqueuer, etc.)
+- Broadcaster tests need Turbo::StreamsChannel stubs -- no full Action Cable required
+- 50% coverage target requires ~1059 lines covered; direct plans target ~630, rest from indirect
+
+## Phase 4 Planning Insights
+- 3 plans: conventions-audit (wave 1), item-creator-extraction (wave 1), final-verification (wave 2)
+- SourcesController has dead `fetch`/`retry` methods (leftover from Phase 3 CRUD extraction)
+- ImportSessionsController `new` and `create` are byte-for-byte identical
+- 4 RuboCop violations in db/migrate/20260210204022_add_composite_index_to_log_entries.rb
+- Duplicate test: test/controllers/concerns/ vs test/controllers/source_monitor/concerns/
+- ItemCreator at 601 lines is the last file over 300 lines -- extract to entry_parser + content_extractor
+- Coverage baseline still at 2117 uncovered (not regenerated since Phase 1) -- must regenerate
+- 60% reduction target: at most 847 uncovered lines
+- dashboard/queries.rb (356) and application_helper.rb (346) are near 300 but acceptable as view/query code
+- `bin/update-coverage-baseline` requires `COVERAGE=1 bin/rails test` first
+
+## Bash/Shell Notes
+- zsh on macOS -- `!` in shell conditionals causes `command not found` errors
+- Use `case` statements instead of `if ! grep` patterns in zsh
+- git ls-files piped to while loops works reliably for file enumeration

data/.claude/commands/release.md

@@ -0,0 +1,212 @@
+# Release: PR, CI, Merge, and Gem Build
+
+Orchestrate a full release cycle for the source_monitor gem. This command handles changelog generation, version bumping, PR creation, CI monitoring, auto-merge on success, release tagging, and gem build with push instructions.
+
+## Inputs
+
+- `$ARGUMENTS` -- Optional: version bump description or release notes summary. If empty, derive from commits since last tag.
+
+## Step 1: Git Hygiene
+
+Run these checks. If ANY fail, STOP and report the issue to the user.
+
+1. **Working tree clean**: `git status --porcelain` must be empty. If not, list the dirty files and ask the user whether to commit, stash, or abort.
+2. **On main branch**: `git branch --show-current` must be `main`. If not, ask the user if they want to continue from the current branch or switch.
+3. **Fetch latest**: `git fetch origin main`
+4. **Up to date with remote**: Compare `git rev-parse HEAD` with `git rev-parse origin/main`. If behind, ask the user whether to pull.
+5. **No unpushed commits**: Compare local HEAD with `origin/main`. If ahead, note how many commits are unpushed -- these will be included in the PR.
+
+Report a summary:
+```
+Git Status:
+  Branch: main
+  Clean: yes
+  Synced with origin: yes
+  Unpushed commits: N
+```
+
+## Step 2: Version Check
+
+1. Read `lib/source_monitor/version.rb` to get the current VERSION.
+2. Read the latest git tag with `git tag --sort=-v:refname | head -1`.
+3. If the VERSION matches the latest tag (e.g., both are `0.3.2`), the version hasn't been bumped. Ask the user:
+   - "Current version is X.Y.Z which already has a tag. What should the new version be?"
+   - Offer options: patch (X.Y.Z+1), minor (X.Y+1.0), major (X+1.0.0), or custom.
+   - Update `lib/source_monitor/version.rb` with the new version.
+4. If VERSION is ahead of the latest tag, proceed with the current version.
+
+Store the release version for later steps. Do NOT commit yet -- that happens after the changelog is updated.
+
+## Step 3: Update CHANGELOG.md
+
+The changelog follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format. The file is at `CHANGELOG.md` in the project root.
+
+1. **Gather commit history** since the last tag:
+   ```
+   git log vPREVIOUS..HEAD --oneline --no-merges
+   ```
+2. **Categorize commits** into Keep a Changelog sections based on commit prefixes and content:
+   - `feat:`, `add:` --> **Added**
+   - `fix:`, `bugfix:` --> **Fixed**
+   - `chore:`, `refactor:`, `perf:` --> **Changed**
+   - `docs:` --> **Documentation** (only include if substantive)
+   - `BREAKING:` or `!:` --> **Breaking Changes** (at the top)
+   - `remove:`, `deprecate:` --> **Removed**
+   - Skip merge commits, version bumps, and CI-only changes.
+   - If `$ARGUMENTS` was provided, use it to inform/supplement the categorization.
+
+3. **Draft the changelog entry** and present it to the user for review:
+   ```
+   ## [X.Y.Z] - YYYY-MM-DD
+
+   ### Added
+   - <items>
+
+   ### Fixed
+   - <items>
+
+   ### Changed
+   - <items>
+   ```
+   Each bullet should be a concise, user-facing description (not a raw commit message). Consolidate related commits into single bullets where it makes sense.
+
+4. **Ask the user to approve** the changelog entry. Offer to edit if they want changes.
+
+5. **Write the entry** into `CHANGELOG.md`:
+   - Replace the `## [Unreleased]` section contents with `- No unreleased changes yet.`
+   - Insert the new versioned entry immediately after the `## [Unreleased]` block and before the previous release entry.
+   - Preserve all existing entries below.
+
+## Step 4: Commit Version Bump + Changelog
+
+Once both `lib/source_monitor/version.rb` (if changed) and `CHANGELOG.md` are updated:
+
+1. Stage the changed files:
+   ```
+   git add lib/source_monitor/version.rb CHANGELOG.md
+   ```
+2. Create a single commit:
+   ```
+   chore: bump version to X.Y.Z and update changelog
+   ```
+   If only the changelog changed (version was already bumped), use:
+   ```
+   chore: update changelog for vX.Y.Z release
+   ```
+
+## Step 5: Create Release Branch and PR
+
+1. Create a release branch: `git checkout -b release/vX.Y.Z`
+2. Push the branch: `git push -u origin release/vX.Y.Z`
+3. Generate a PR body from the new CHANGELOG.md entry (use the entry written in Step 3, not raw commits).
+4. Create the PR using `gh pr create`:
+   - Title: `Release vX.Y.Z`
+   - Body format:
+     ```
+     ## Release vX.Y.Z
+
+     <paste the CHANGELOG.md entry content here>
+
+     ### Release Checklist
+     - [x] Version bumped in `lib/source_monitor/version.rb`
+     - [x] CHANGELOG.md updated
+     - [ ] CI passes (lint, security, test, release_verification)
+
+     ---
+     Auto-generated release PR by `/release` command.
+     ```
+   - Base: `main`
+5. Report the PR URL to the user.
+
+## Step 6: Monitor CI Pipeline
+
+Poll the CI status using `gh pr checks <PR_NUMBER> --watch` or repeated `gh pr checks <PR_NUMBER>` calls. The CI has 4 required jobs: `lint`, `security`, `test`, `release_verification`.
+
+1. Tell the user: "Monitoring CI pipeline for PR #N... This typically takes 3-5 minutes."
+2. Poll with `gh pr checks <PR_NUMBER>` every 30 seconds, up to 15 minutes.
+3. After each poll, report progress if any jobs completed.
+
+### If CI PASSES (all checks green):
+
+Continue to Step 7.
+
+### If CI FAILS:
+
+1. Get the failure details: `gh pr checks <PR_NUMBER>` to identify which jobs failed.
+2. For each failed job, fetch the log summary:
+   ```
+   gh run view <RUN_ID> --log-failed | tail -50
+   ```
+3. Present to the user:
+   ```
+   CI Failed on PR #N
+
+   Failed Jobs:
+   - <job_name>: <brief summary of failure>
+
+   Log excerpt:
+   <relevant log lines>
+   ```
+4. Ask the user what to do:
+   - "Fix the issues and re-push" -- Help fix the issues, commit, push, and restart CI monitoring
+   - "Close the PR and abort" -- Close the PR, delete the branch, switch back to main
+   - "Investigate manually" -- Stop and let the user handle it
+
+## Step 7: Auto-Merge PR
+
+Once CI is green:
+
+1. Merge the PR: `gh pr merge <PR_NUMBER> --merge --delete-branch`
+2. Switch back to main and pull: `git checkout main && git pull origin main`
+3. Report: "PR #N merged successfully."
+
+## Step 8: Tag the Release
+
+1. Create an annotated tag:
+   ```
+   git tag -a vX.Y.Z -m "Release vX.Y.Z"
+   ```
+2. Push the tag: `git push origin vX.Y.Z`
+3. Create a GitHub release from the tag:
+   ```
+   gh release create vX.Y.Z --title "vX.Y.Z" --notes "<changelog entry from Step 3>"
+   ```
+4. Report the release URL.
+
+## Step 9: Build the Gem
+
+1. Clean any old gem files: remove any `source_monitor-*.gem` files in the project root.
+2. Build the gem: `gem build source_monitor.gemspec`
+3. Verify the gem was built: check for `source_monitor-X.Y.Z.gem` in the project root.
+4. Show the gem contents summary: `gem spec source_monitor-X.Y.Z.gem | head -30`
+
+## Step 10: Gem Push Instructions
+
+Present the final instructions to the user:
+
+```
+Release vX.Y.Z Complete!
+
+  Git tag:    vX.Y.Z (pushed)
+  GitHub:     <release URL>
+  Gem built:  source_monitor-X.Y.Z.gem
+
+To publish to RubyGems:
+
+  gem push source_monitor-X.Y.Z.gem
+
+You'll be prompted for your RubyGems OTP code (check your authenticator app).
+The gem has `rubygems_mfa_required` enabled, so the OTP is mandatory.
+
+After pushing, verify at:
+  https://rubygems.org/gems/source_monitor/versions/X.Y.Z
+```
+
+Do NOT run `gem push` automatically -- always let the user handle the OTP-protected push manually.
+
+## Error Recovery
+
+- If any step fails unexpectedly, report what happened and where things stand.
+- If a release branch already exists, ask the user whether to reuse or recreate it.
+- If the tag already exists, skip tagging and inform the user.
+- Always leave the user on the `main` branch in a clean state when possible.

data/.claude/skills/sm-host-setup/SKILL.md

@@ -61,7 +61,7 @@ bin/source_monitor install --yes
 gem "source_monitor", "~> 0.3.0"  # in Gemfile
 bundle install
 
-# 2. Run the install generator
+# 2. Run the install generator (mounts engine, creates initializer, configures recurring jobs)
 bin/rails generate source_monitor:install --mount-path=/source_monitor
 
 # 3. Copy engine migrations
@@ -70,7 +70,7 @@ bin/rails railties:install:migrations FROM=source_monitor
 # 4. Apply migrations
 bin/rails db:migrate
 
-# 5. Start background workers
+# 5. Start background workers (recurring jobs configured automatically in config/recurring.yml)
 bin/rails solid_queue:start
 
 # 6. Verify
@@ -86,7 +86,7 @@ gem "source_monitor", github: "dchuk/source_monitor"
 
 ## What the Install Generator Does
 
-The generator (`SourceMonitor::Generators::InstallGenerator`) performs two actions:
+The generator (`SourceMonitor::Generators::InstallGenerator`) performs three actions:
 
 1. **Mounts the engine** in `config/routes.rb`:
    ```ruby
@@ -97,6 +97,9 @@ The generator (`SourceMonitor::Generators::InstallGenerator`) performs two actio
 2. **Creates the initializer** at `config/initializers/source_monitor.rb`:
    Uses the template at `lib/generators/source_monitor/install/templates/source_monitor.rb.tt`. Skips if the file already exists.
 
+3. **Configures recurring jobs** in `config/recurring.yml`:
+   Adds entries for `ScheduleFetchesJob` (every minute), scrape scheduling (every 2 minutes), `ItemCleanupJob` (2am daily), and `LogCleanupJob` (3am daily). If the file doesn't exist, creates it with `default: &default` and environment sections. If it exists, merges entries without overwriting. Skips if SourceMonitor entries are already present.
+
 Re-running the generator is safe and idempotent.
 
 ## Post-Install Configuration
@@ -217,6 +220,7 @@ end
 - [ ] `bundle install` completed
 - [ ] Install generator ran (`bin/rails generate source_monitor:install`)
 - [ ] Engine migrations copied and applied
+- [ ] Recurring jobs configured in `config/recurring.yml`
 - [ ] Solid Queue workers started
 - [ ] Authentication hooks configured in initializer
 - [ ] `bin/source_monitor verify` passes

data/.claude/skills/sm-host-setup/reference/setup-checklist.md

@@ -39,6 +39,7 @@ bin/rails generate source_monitor:install --mount-path=/source_monitor
 Verify after running:
 - [ ] `config/routes.rb` contains `mount SourceMonitor::Engine, at: "/source_monitor"`
 - [ ] `config/initializers/source_monitor.rb` exists
+- [ ] `config/recurring.yml` contains SourceMonitor recurring job entries
 
 ## Phase 4: Database Setup
 
@@ -75,6 +76,8 @@ end
 
 ## Phase 6: Configure Workers
 
+The install generator automatically configures recurring jobs in `config/recurring.yml` (fetch scheduling, scrape scheduling, item cleanup, log cleanup). These run automatically with `bin/dev` or `bin/jobs`.
+
 Ensure `config/solid_queue.yml` (or equivalent) includes the SourceMonitor queues:
 
 ```yaml

data/.claude/skills/sm-job/SKILL.md

@@ -159,15 +159,16 @@ SourceMonitor.queue_name(:fetch)  # => "source_monitor_fetch"
 
 ### Recurring Jobs
 
-ScheduleFetchesJob is typically configured as a recurring job in `config/recurring.yml`:
-
-```yaml
-production:
-  schedule_fetches:
-    class: SourceMonitor::ScheduleFetchesJob
-    schedule: every 1 minute
-    queue: source_monitor_fetch
-```
+The install generator (`bin/rails generate source_monitor:install`) automatically configures these recurring jobs in `config/recurring.yml`:
+
+| Job | Schedule |
+|-----|----------|
+| `SourceMonitor::ScheduleFetchesJob` | every minute |
+| `SourceMonitor::Scraping::Scheduler.run` | every 2 minutes |
+| `SourceMonitor::ItemCleanupJob` | at 2am every day |
+| `SourceMonitor::LogCleanupJob` | at 3am every day |
+
+These run automatically with `bin/dev` or `bin/jobs`. If you need to customize, edit `config/recurring.yml` directly.
 
 ## Retry Policies
 

data/.gitignore

@@ -15,3 +15,7 @@
 /app/assets/builds/*
 !/app/assets/builds/.keep
 !/app/assets/builds/source_monitor/
+.vbw-planning/.cost-ledger.json
+.vbw-planning/.notification-log.jsonl
+.vbw-planning/.session-log.jsonl
+.vbw-planning/.hook-errors.log

data/CHANGELOG.md

@@ -15,6 +15,18 @@ All notable changes to this project are documented below. The format follows [Ke
 
 - No unreleased changes yet.
 
+## [0.3.3] - 2026-02-11
+
+### Fixed
+
+- Added missing `recurring.yml` configuration to the install generator so host apps get Solid Queue recurring job config on install.
+- Fixed YAML alias parsing in install generator so merging into existing `recurring.yml` files with `<<: *default` anchors works correctly.
+
+### Changed
+
+- Updated `sm-host-setup` and `sm-job` skills to reflect latest conventions.
+- Updated setup documentation with current installation steps.
+
 ## [0.3.2] - 2026-02-10
 
 ### Fixed

data/Gemfile.lock

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

data/VERSION

@@ -1 +1 @@
-0.3.2
+0.3.3

data/docs/setup.md

@@ -48,8 +48,8 @@ This ensures Bundler can load SourceMonitor so the commands below are available.
 3. **Start background workers:**
    ```bash
    bin/rails solid_queue:start
-   bin/jobs --recurring_schedule_file=config/recurring.yml # optional recurring scheduler
    ```
+   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`.
 
 4. **Visit the dashboard** at the chosen mount path, create a source, and trigger “Fetch Now” to validate realtime updates and Solid Queue processing.
 
@@ -83,7 +83,7 @@ Prefer to script each step or plug SourceMonitor into an existing deployment che
 | --- | --- | --- |
 | 1 | `gem "source_monitor", github: "dchuk/source_monitor"` | Add the engine to your Gemfile (skip if already present) |
 | 2 | `bundle install` | Install Ruby dependencies |
-| 3 | `bin/rails generate source_monitor:install --mount-path=/source_monitor` | Mount the engine and create the initializer |
+| 3 | `bin/rails generate source_monitor:install --mount-path=/source_monitor` | Mount the engine, create the initializer, and configure recurring jobs |
 | 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 |
@@ -95,11 +95,11 @@ Prefer to script each step or plug SourceMonitor into an existing deployment che
 ### Step-by-step Details
 
 1. **Add the gem** to the host `Gemfile` (GitHub edge or released version) and run `bundle install`. If your host manages node tooling, run `npm install` also.
-2. **Install the engine** via `bin/rails generate source_monitor:install --mount-path=/source_monitor`. The generator mounts the engine, creates `config/initializers/source_monitor.rb`, and prints follow-up instructions. Re-running the generator is safe; it detects existing mounts/initializers.
+2. **Install the engine** via `bin/rails generate source_monitor:install --mount-path=/source_monitor`. The generator mounts the engine, creates `config/initializers/source_monitor.rb`, and configures recurring Solid Queue jobs in `config/recurring.yml`. Re-running the generator is safe; it detects existing mounts/initializers and skips entries that are already present.
 3. **Copy migrations** with `bin/rails railties:install:migrations FROM=source_monitor`. This brings in the SourceMonitor tables plus Solid Cable/Queue schema when needed. The command is idempotent—run it again after upgrading the gem.
 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). Add a recurring process via `bin/jobs --recurring_schedule_file=config/recurring.yml` when you need fetch/scrape schedules.
+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`.
 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/lib/generators/source_monitor/install/install_generator.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "yaml"
 require "rails/generators"
 require "rails/generators/base"
 
@@ -32,7 +33,26 @@ module SourceMonitor
         template "source_monitor.rb.tt", initializer_path
       end
 
+      def configure_recurring_jobs
+        recurring_path = "config/recurring.yml"
+        destination = File.join(destination_root, recurring_path)
+
+        if recurring_file_has_source_monitor_entries?(destination)
+          say_status :skip, "#{recurring_path} (SourceMonitor entries already present)", :yellow
+          return
+        end
+
+        if File.exist?(destination)
+          merge_into_existing_recurring(destination, recurring_path)
+        else
+          create_recurring_file(destination, recurring_path)
+        end
+      end
+
       def print_next_steps
+        say_status :info,
+          "Recurring jobs configured in config/recurring.yml — they'll run automatically with bin/dev or bin/jobs.",
+          :green
         say_status :info,
           "Next steps: review docs/setup.md for the guided + manual install walkthrough and docs/troubleshooting.md for common fixes.",
           :green
@@ -40,6 +60,86 @@ module SourceMonitor
 
       private
 
+      RECURRING_ENTRIES = {
+        "source_monitor_schedule_fetches" => {
+          "class" => "SourceMonitor::ScheduleFetchesJob",
+          "args" => [ { "limit" => 100 } ],
+          "schedule" => "every minute"
+        },
+        "source_monitor_schedule_scrapes" => {
+          "command" => "SourceMonitor::Scraping::Scheduler.run(limit: 100)",
+          "schedule" => "every 2 minutes"
+        },
+        "source_monitor_item_cleanup" => {
+          "class" => "SourceMonitor::ItemCleanupJob",
+          "schedule" => "at 2am every day"
+        },
+        "source_monitor_log_cleanup" => {
+          "class" => "SourceMonitor::LogCleanupJob",
+          "args" => [ { "fetch_logs_older_than_days" => 90, "scrape_logs_older_than_days" => 60 } ],
+          "schedule" => "at 3am every day"
+        }
+      }.freeze
+
+      def recurring_file_has_source_monitor_entries?(path)
+        return false unless File.exist?(path)
+
+        content = File.read(path)
+        content.include?("source_monitor_schedule_fetches")
+      end
+
+      def merge_into_existing_recurring(destination, recurring_path)
+        parsed = YAML.safe_load(File.read(destination), aliases: true) || {}
+        default_key = parsed.key?("default") ? "default" : nil
+
+        if default_key
+          parsed["default"] = (parsed["default"] || {}).merge(RECURRING_ENTRIES)
+        else
+          parsed.merge!(RECURRING_ENTRIES)
+        end
+
+        write_recurring_yaml(destination, parsed, has_environments: parsed.key?("development"))
+        say_status :append, recurring_path, :green
+      end
+
+      def create_recurring_file(destination, recurring_path)
+        FileUtils.mkdir_p(File.dirname(destination))
+        yaml_content = build_fresh_recurring_yaml
+        File.write(destination, yaml_content)
+        say_status :create, recurring_path, :green
+      end
+
+      def build_fresh_recurring_yaml
+        entries_yaml = format_entries_yaml(RECURRING_ENTRIES)
+
+        "default: &default\n#{entries_yaml}\n" \
+          "development:\n  <<: *default\n\n" \
+          "test:\n  <<: *default\n\n" \
+          "production:\n  <<: *default\n"
+      end
+
+      def write_recurring_yaml(destination, parsed, has_environments: false)
+        if has_environments
+          default_entries = parsed["default"] || {}
+          entries_yaml = format_entries_yaml(default_entries)
+          envs = %w[development test production].select { |e| parsed.key?(e) }
+          env_sections = envs.map { |e| "#{e}:\n  <<: *default" }.join("\n\n")
+
+          content = "default: &default\n#{entries_yaml}"
+          content += "\n#{env_sections}\n" unless envs.empty?
+          File.write(destination, content)
+        else
+          File.write(destination, YAML.dump(parsed))
+        end
+      end
+
+      def format_entries_yaml(entries)
+        entries.map { |key, value|
+          entry = YAML.dump({ key => value }).delete_prefix("---\n")
+          entry.gsub(/^/, "  ")
+        }.join("\n")
+      end
+
       def engine_already_mounted?(mount_path)
         routes_path = File.join(destination_root, "config/routes.rb")
         return false unless File.exist?(routes_path)

data/lib/source_monitor/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SourceMonitor
-  VERSION = "0.3.2"
+  VERSION = "0.3.3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: source_monitor
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.3.3
 platform: ruby
 authors:
 - dchuk
@@ -238,6 +238,8 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".claude/agent-memory/vbw-vbw-dev/MEMORY.md"
+- ".claude/agent-memory/vbw-vbw-lead/MEMORY.md"
 - ".claude/agents/rails-concern.md"
 - ".claude/agents/rails-controller.md"
 - ".claude/agents/rails-hotwire.md"
@@ -256,6 +258,7 @@ files:
 - ".claude/agents/rails-tdd.md"
 - ".claude/agents/rails-test.md"
 - ".claude/agents/rails-view-component.md"
+- ".claude/commands/release.md"
 - ".claude/hooks/block-secrets.sh"
 - ".claude/settings.json"
 - ".claude/skills/action-cable-patterns/SKILL.md"
@@ -336,8 +339,6 @@ files:
 - ".gitignore"
 - ".rubocop.yml"
 - ".ruby-version"
-- ".vbw-planning/.notification-log.jsonl"
-- ".vbw-planning/.session-log.jsonl"
 - ".vbw-planning/PROJECT.md"
 - ".vbw-planning/REQUIREMENTS.md"
 - ".vbw-planning/SHIPPED.md"