source_monitor 0.13.1 → 0.15.0

data/CLAUDE.md

@@ -2,6 +2,8 @@
 
 **Core value:** Drop-in Rails engine for feed monitoring, content scraping, and operational dashboards.
 
+> **Engine conventions live in [`AGENTS.md`](AGENTS.md)** — the canonical, cross-agent reference for tech stack, architecture, testing, quality gates, the pre-push CI checklist, security rules, configuration DSL, and commands. This file holds only Claude Code-specific context: working memory, VBW commands, and the `.claude/` agent/skill catalogs. When a convention changes, edit `AGENTS.md`, not here.
+
 ## Active Context
 
 **Last shipped:** rails-audit-and-refactoring (7 phases, 30 plans)
@@ -10,7 +12,7 @@
 ## Key Decisions
 
 - Keep PostgreSQL-only for now
-- Keep host-app auth model
+- Keep host-app auth model (fail-closed by default since #129)
 - Ruby autoload for lib/ modules (not Zeitwerk)
 - PG parallel fork segfault resolved: switched to thread-based parallelism in aia-ssl-fix milestone
 
@@ -23,13 +25,6 @@
 - vastai (global)
 - find-skills (global)
 
-## Learned Patterns
-
-- Sub-module extraction: create `module/submodule.rb` with `require_relative`, lazy accessors, forwarding methods for backward compat
-- Coverage runs need `COVERAGE=1 PARALLEL_WORKERS=1` with threads (not forks) to avoid PG segfault and SimpleCov data loss
-- Test isolation: scope queries to specific source/item to prevent cross-test contamination in parallel runs
-- RuboCop omakase: only 45/775 cops enabled, all Metrics cops disabled -- no file size enforcement
-
 ## VBW Commands
 
 This project uses VBW (Vibe Better with Claude Code).
@@ -38,111 +33,10 @@ Run /vbw:help for all commands.
 
 ---
 
-# Rails Development Conventions
-
-## Tech Stack
-
-| Layer | Technology |
-|-------|------------|
-| Ruby | 4.0+ |
-| Rails | 8.x |
-| Testing | Minitest (no fixtures -- uses factory helpers + WebMock/VCR) |
-| Authorization | Host app responsibility (mountable engine) |
-| Jobs | Solid Queue |
-| Frontend | Hotwire (Turbo + Stimulus) + Tailwind CSS |
-| Linting | RuboCop (omakase) + Brakeman |
-| Database | PostgreSQL only |
-
-## Architecture Conventions
-
-### Models First
-- Business logic lives in models. Use concerns for horizontal sharing.
-- Service objects ONLY for operations spanning 3+ models or external integrations.
-- Query objects for complex queries that don't fit a single scope.
-- Presenters (SimpleDelegator) for view-specific formatting.
-
-### Everything-is-CRUD Routing
-- Prefer creating a new resource over adding custom actions.
-- `POST /posts/:id/publications` over `POST /posts/:id/publish`.
-- RESTful routes only; no `member` or `collection` blocks with custom verbs.
-
-### State as Records
-- Track business state transitions as separate records (who/when/why).
-- Boolean columns ONLY for technical flags (e.g., `email_verified`).
-
-### Jobs
-- Shallow jobs: call `_later` or `_now` methods on models/services.
-- Jobs contain only deserialization + delegation. No business logic.
-- Use Solid Queue recurring jobs for scheduled work.
-
-### Frontend
-- Turbo Frames for partial page updates.
-- Turbo Streams for real-time broadcasts.
-- Stimulus controllers: small, focused, one behavior each.
-- Tailwind CSS utility classes; extract components for repeated patterns.
-
-## Testing Conventions
-
-- **Framework:** Minitest. NEVER use RSpec or FactoryBot.
-- **Helpers:** `create_source!` factory, `with_inline_jobs`, `with_queue_adapter`.
-- **HTTP:** WebMock disables external HTTP; VCR for recorded cassettes.
-- **Config:** Reset every test with `SourceMonitor.reset_configuration!`.
-- **TDD workflow:** Red (failing test) -> Green (minimal pass) -> Refactor.
-- **Coverage:** Every model validation, scope, and public method. Every controller action.
-
-## Quality Gates
-
-- `bin/rubocop` -- zero offenses before commit.
-- `bin/brakeman --no-pager` -- zero warnings before merge.
-- `bin/rails test` -- all tests pass.
-- `yarn build` -- rebuild JS assets if any `.js` files changed (ESLint runs in CI).
-- No N+1 queries (use `includes`/`preload`).
-- No hardcoded credentials (use Rails credentials or ENV).
-
-### Pre-Push CI Checklist (run ALL before pushing to GitHub)
-
-Before pushing any branch (especially release branches), run the full CI equivalent locally:
-
-1. `bin/rubocop` -- catches Ruby lint issues
-2. `PARALLEL_WORKERS=1 bin/rails test` -- catches test failures AND diff coverage gaps
-3. `bin/brakeman --no-pager` -- catches security issues
-4. `yarn build` -- rebuilds JS and catches ESLint issues (CI runs ESLint separately)
-
-**Why:** CI failures cost ~5 min per round-trip. In v0.8.0, skipping ESLint and diff coverage checks locally caused 2 wasted CI cycles. Common blind spots:
-- JS files need `/* global */` declarations for browser APIs (MutationObserver, requestAnimationFrame, etc.)
-- Every `rescue` / fallback / error path in new source code needs test coverage (CI diff coverage gate rejects uncovered lines)
-- `yarn build` must run after JS changes to sync sourcemaps
-
-## QA and UAT Rules
+## QA and UAT Rules (Claude Code)
 
 - **Browser-first verification:** During VBW QA (`/vbw:qa`) and UAT (`/vbw:verify`), ALWAYS start by using `agent-browser` to test UI scenarios yourself before presenting checkpoints to the user. Navigate to the dummy app (port 3002), take snapshots/screenshots, and verify visual and functional behavior with agents first.
-- **Automate what you can:** Any test that can be verified programmatically (config defaults, job enqueue behavior, controller responses) should be automated -- only present truly visual/interactive tests to the user.
-- **Dummy app port:** The SourceMonitor dummy app runs on port 3002 (`cd test/dummy && bin/rails server -p 3002`).
-
-## Security Rules
-
-### Protected Files (NEVER read or output)
-- `.env`, `.env.*`
-- `config/master.key`, `config/credentials.yml.enc`
-- `.kamal/secrets`
-- Any `*.pem`, `*.key` files
-
-### Forbidden Operations
-- `git push --force` to main/master/production
-- `git reset --hard` without explicit user confirmation
-- `rm -rf` on root, home, or parent directories
-- `chmod 777`
-
-## Development Commands
-
-```bash
-bin/dev                     # Start dev server
-bin/rails test              # Run all tests
-bin/rubocop                 # Check style
-bin/rubocop -a              # Auto-fix style
-bin/brakeman --no-pager     # Security scan
-bin/rails db:migrate        # Run migrations
-```
+- **Automate what you can:** anything verifiable programmatically should be a test — see the Testing section in [`AGENTS.md`](AGENTS.md) — and only present truly visual/interactive checks to the user.
 
 ## Agent Catalog
 
@@ -200,7 +94,7 @@ These skills are available in `.claude/skills/`:
 
 ## Source Monitor Skills
 
-Engine-specific skills (`sm-*` prefix). Consumer skills install by default; contributor skills are opt-in.
+Engine-specific skills (`sm-*` prefix). Consumer skills install by default; contributor skills are opt-in. The **Skills & Docs Alignment** maintenance rule lives in [`AGENTS.md`](AGENTS.md).
 
 ### Consumer Skills (default install)
 
@@ -237,7 +131,3 @@ bin/rails source_monitor:skills:contributor     # Contributor skills
 bin/rails source_monitor:skills:all            # All skills
 bin/rails source_monitor:skills:remove         # Remove all sm-* skills
 ```
-
-## Maintenance Rules
-
-- **Skills & docs alignment**: Whenever engine code changes (models, configuration, pipeline, jobs, migrations, scrapers, events, health rules, or dashboard), the corresponding `sm-*` skill and its `reference/` files MUST be updated in the same PR to ensure skills always reflect current engine behavior.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    source_monitor (0.13.1)
+    source_monitor (0.15.0)
       cssbundling-rails (~> 1.4)
       faraday (~> 2.9)
       faraday-follow_redirects (~> 0.4)
@@ -16,36 +16,36 @@ PATH
       solid_cable (>= 3.0, < 4.0)
       solid_queue (>= 0.3, < 3.0)
       turbo-rails (~> 2.0)
-      view_component (>= 3.0, < 4.0)
+      view_component (>= 3.0, < 5.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    action_text-trix (2.1.16)
+    action_text-trix (2.1.17)
       railties
-    actioncable (8.1.2)
-      actionpack (= 8.1.2)
-      activesupport (= 8.1.2)
+    actioncable (8.1.3)
+      actionpack (= 8.1.3)
+      activesupport (= 8.1.3)
       nio4r (~> 2.0)
       websocket-driver (>= 0.6.1)
       zeitwerk (~> 2.6)
-    actionmailbox (8.1.2)
-      actionpack (= 8.1.2)
-      activejob (= 8.1.2)
-      activerecord (= 8.1.2)
-      activestorage (= 8.1.2)
-      activesupport (= 8.1.2)
+    actionmailbox (8.1.3)
+      actionpack (= 8.1.3)
+      activejob (= 8.1.3)
+      activerecord (= 8.1.3)
+      activestorage (= 8.1.3)
+      activesupport (= 8.1.3)
       mail (>= 2.8.0)
-    actionmailer (8.1.2)
-      actionpack (= 8.1.2)
-      actionview (= 8.1.2)
-      activejob (= 8.1.2)
-      activesupport (= 8.1.2)
+    actionmailer (8.1.3)
+      actionpack (= 8.1.3)
+      actionview (= 8.1.3)
+      activejob (= 8.1.3)
+      activesupport (= 8.1.3)
       mail (>= 2.8.0)
       rails-dom-testing (~> 2.2)
-    actionpack (8.1.2)
-      actionview (= 8.1.2)
-      activesupport (= 8.1.2)
+    actionpack (8.1.3)
+      actionview (= 8.1.3)
+      activesupport (= 8.1.3)
       nokogiri (>= 1.8.5)
       rack (>= 2.2.4)
       rack-session (>= 1.0.1)
@@ -53,36 +53,36 @@ GEM
       rails-dom-testing (~> 2.2)
       rails-html-sanitizer (~> 1.6)
       useragent (~> 0.16)
-    actiontext (8.1.2)
+    actiontext (8.1.3)
       action_text-trix (~> 2.1.15)
-      actionpack (= 8.1.2)
-      activerecord (= 8.1.2)
-      activestorage (= 8.1.2)
-      activesupport (= 8.1.2)
+      actionpack (= 8.1.3)
+      activerecord (= 8.1.3)
+      activestorage (= 8.1.3)
+      activesupport (= 8.1.3)
       globalid (>= 0.6.0)
       nokogiri (>= 1.8.5)
-    actionview (8.1.2)
-      activesupport (= 8.1.2)
+    actionview (8.1.3)
+      activesupport (= 8.1.3)
       builder (~> 3.1)
       erubi (~> 1.11)
       rails-dom-testing (~> 2.2)
       rails-html-sanitizer (~> 1.6)
-    activejob (8.1.2)
-      activesupport (= 8.1.2)
+    activejob (8.1.3)
+      activesupport (= 8.1.3)
       globalid (>= 0.3.6)
-    activemodel (8.1.2)
-      activesupport (= 8.1.2)
-    activerecord (8.1.2)
-      activemodel (= 8.1.2)
-      activesupport (= 8.1.2)
+    activemodel (8.1.3)
+      activesupport (= 8.1.3)
+    activerecord (8.1.3)
+      activemodel (= 8.1.3)
+      activesupport (= 8.1.3)
       timeout (>= 0.4.0)
-    activestorage (8.1.2)
-      actionpack (= 8.1.2)
-      activejob (= 8.1.2)
-      activerecord (= 8.1.2)
-      activesupport (= 8.1.2)
+    activestorage (8.1.3)
+      actionpack (= 8.1.3)
+      activejob (= 8.1.3)
+      activerecord (= 8.1.3)
+      activesupport (= 8.1.3)
       marcel (~> 1.0)
-    activesupport (8.1.2)
+    activesupport (8.1.3)
       base64
       bigdecimal
       concurrent-ruby (~> 1.0, >= 1.3.1)
@@ -95,12 +95,12 @@ GEM
       securerandom (>= 0.3)
       tzinfo (~> 2.0, >= 2.0.5)
       uri (>= 0.13.1)
-    addressable (2.8.7)
-      public_suffix (>= 2.0.2, < 7.0)
+    addressable (2.9.0)
+      public_suffix (>= 2.0.2, < 8.0)
     ast (2.4.3)
     base64 (0.3.0)
-    bigdecimal (4.0.1)
-    brakeman (8.0.2)
+    bigdecimal (4.1.2)
+    brakeman (8.0.4)
       racc
     builder (3.3.0)
     capybara (3.40.0)
@@ -125,7 +125,7 @@ GEM
     digest (3.2.1)
     docile (1.4.1)
     drb (2.2.3)
-    erb (6.0.1)
+    erb (6.0.2)
     erubi (1.13.1)
     et-orbi (1.4.0)
       tzinfo
@@ -163,11 +163,11 @@ GEM
       reline (>= 0.4.2)
     jsbundling-rails (1.3.1)
       railties (>= 6.0.0)
-    json (2.18.1)
+    json (2.19.2)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     logger (1.7.0)
-    loofah (2.25.0)
+    loofah (2.25.1)
       crass (~> 1.0.2)
       nokogiri (>= 1.12.0)
     mail (2.9.0)
@@ -178,17 +178,17 @@ GEM
       net-smtp
     marcel (1.1.0)
     matrix (0.4.3)
-    method_source (1.1.0)
     mini_magick (5.3.1)
       logger
     mini_mime (1.1.5)
     mini_portile2 (2.8.9)
-    minitest (6.0.1)
+    minitest (6.0.2)
+      drb (~> 2.0)
       prism (~> 1.5)
     minitest-mock (5.27.0)
     net-http (0.9.1)
       uri (>= 0.11.1)
-    net-imap (0.6.2)
+    net-imap (0.6.3)
       date
       net-protocol
     net-pop (0.1.2)
@@ -198,18 +198,18 @@ GEM
     net-smtp (0.5.1)
       net-protocol
     nio4r (2.7.5)
-    nokogiri (1.19.0)
+    nokogiri (1.19.2)
       mini_portile2 (~> 2.8.2)
       racc (~> 1.4)
-    nokogiri (1.19.0-aarch64-linux-gnu)
+    nokogiri (1.19.2-aarch64-linux-gnu)
       racc (~> 1.4)
-    nokogiri (1.19.0-aarch64-linux-musl)
+    nokogiri (1.19.2-aarch64-linux-musl)
       racc (~> 1.4)
-    nokogiri (1.19.0-arm-linux-gnu)
+    nokogiri (1.19.2-arm-linux-gnu)
       racc (~> 1.4)
-    nokogiri (1.19.0-arm-linux-musl)
+    nokogiri (1.19.2-arm-linux-musl)
       racc (~> 1.4)
-    nokolexbor (0.6.2)
+    nokolexbor (0.6.4)
     ostruct (0.6.3)
     parallel (1.27.0)
     parser (3.3.10.1)
@@ -229,12 +229,12 @@ GEM
     psych (5.3.1)
       date
       stringio
-    public_suffix (6.0.2)
+    public_suffix (7.0.5)
     puma (7.2.0)
       nio4r (~> 2.0)
     raabro (1.4.0)
     racc (1.8.1)
-    rack (3.2.4)
+    rack (3.2.5)
     rack-session (2.1.1)
       base64 (>= 0.1.0)
       rack (>= 3.0.0)
@@ -242,30 +242,30 @@ GEM
       rack (>= 1.3)
     rackup (2.3.1)
       rack (>= 3)
-    rails (8.1.2)
-      actioncable (= 8.1.2)
-      actionmailbox (= 8.1.2)
-      actionmailer (= 8.1.2)
-      actionpack (= 8.1.2)
-      actiontext (= 8.1.2)
-      actionview (= 8.1.2)
-      activejob (= 8.1.2)
-      activemodel (= 8.1.2)
-      activerecord (= 8.1.2)
-      activestorage (= 8.1.2)
-      activesupport (= 8.1.2)
+    rails (8.1.3)
+      actioncable (= 8.1.3)
+      actionmailbox (= 8.1.3)
+      actionmailer (= 8.1.3)
+      actionpack (= 8.1.3)
+      actiontext (= 8.1.3)
+      actionview (= 8.1.3)
+      activejob (= 8.1.3)
+      activemodel (= 8.1.3)
+      activerecord (= 8.1.3)
+      activestorage (= 8.1.3)
+      activesupport (= 8.1.3)
       bundler (>= 1.15.0)
-      railties (= 8.1.2)
+      railties (= 8.1.3)
     rails-dom-testing (2.3.0)
       activesupport (>= 5.0.0)
       minitest
       nokogiri (>= 1.6)
-    rails-html-sanitizer (1.6.2)
-      loofah (~> 2.21)
+    rails-html-sanitizer (1.7.0)
+      loofah (~> 2.25)
       nokogiri (>= 1.15.7, != 1.16.7, != 1.16.6, != 1.16.5, != 1.16.4, != 1.16.3, != 1.16.2, != 1.16.1, != 1.16.0.rc1, != 1.16.0)
-    railties (8.1.2)
-      actionpack (= 8.1.2)
-      activesupport (= 8.1.2)
+    railties (8.1.3)
+      actionpack (= 8.1.3)
+      activesupport (= 8.1.3)
       irb (~> 1.13)
       rackup (>= 1.0.0)
       rake (>= 12.2)
@@ -321,7 +321,7 @@ GEM
     rubyzip (3.2.2)
     sax-machine (1.3.2)
     securerandom (0.4.1)
-    selenium-webdriver (4.40.0)
+    selenium-webdriver (4.41.0)
       base64 (~> 0.2)
       logger (~> 1.4)
       rexml (~> 3.2, >= 3.2.5)
@@ -338,18 +338,18 @@ GEM
       activejob (>= 7.2)
       activerecord (>= 7.2)
       railties (>= 7.2)
-    solid_queue (1.3.1)
+    solid_queue (1.4.0)
       activejob (>= 7.1)
       activerecord (>= 7.1)
       concurrent-ruby (>= 1.3.1)
       fugit (~> 1.11)
       railties (>= 7.1)
       thor (>= 1.3.1)
-    stackprof (0.2.27)
+    stackprof (0.2.28)
     stringio (3.2.0)
-    test-prof (1.5.2)
+    test-prof (1.6.0)
     thor (1.5.0)
-    timeout (0.6.0)
+    timeout (0.6.1)
     tsort (0.2.0)
     turbo-rails (2.0.23)
       actionpack (>= 7.1.0)
@@ -362,11 +362,11 @@ GEM
     uri (1.1.1)
     useragent (0.16.11)
     vcr (6.4.0)
-    view_component (3.24.0)
-      activesupport (>= 5.2.0, < 8.2)
+    view_component (4.5.0)
+      actionview (>= 7.1.0)
+      activesupport (>= 7.1.0)
       concurrent-ruby (~> 1)
-      method_source (~> 1.0)
-    webmock (3.26.1)
+    webmock (3.26.2)
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
@@ -377,7 +377,7 @@ GEM
     websocket-extensions (0.1.5)
     xpath (3.2.0)
       nokogiri (~> 1.8)
-    zeitwerk (2.7.4)
+    zeitwerk (2.7.5)
     zlib (3.2.2)
 
 PLATFORMS

data/README.md

@@ -9,8 +9,8 @@ SourceMonitor is a production-ready Rails 8 mountable engine for ingesting, norm
 In your host Rails app:
 
 ```bash
-bundle add source_monitor --version "~> 0.13.1"
-# or add `gem "source_monitor", "~> 0.13.1"` manually, then run:
+bundle add source_monitor --version "~> 0.15.0"
+# or add `gem "source_monitor", "~> 0.15.0"` manually, then run:
 bundle install
 ```
 
@@ -46,7 +46,7 @@ This exposes `bin/source_monitor` (via Bundler binstubs) so you can run the guid
 Before running any SourceMonitor commands inside your host app, add the gem and install dependencies:
 
 ```bash
-bundle add source_monitor --version "~> 0.13.1"
+bundle add source_monitor --version "~> 0.15.0"
 # or edit your Gemfile, then run
 bundle install
 ```

data/VERSION

@@ -1 +1 @@
-0.13.0
+0.15.0

data/app/controllers/source_monitor/application_controller.rb

@@ -4,11 +4,13 @@ module SourceMonitor
   class ApplicationController < ActionController::Base
     protect_from_forgery with: :exception, prepend: true
 
+    before_action :enforce_source_monitor_access_default
     before_action :authenticate_source_monitor_user
     before_action :authorize_source_monitor_access
 
-    helper_method :source_monitor_current_user, :source_monitor_user_signed_in?
-    after_action :broadcast_flash_toasts
+    helper_method :source_monitor_current_user, :source_monitor_user_signed_in?,
+      :source_monitor_flash_toasts
+    after_action :append_flash_toasts_to_turbo_stream
 
     rescue_from ActiveRecord::RecordNotFound, with: :record_not_found
 
@@ -40,6 +42,30 @@ module SourceMonitor
     TOAST_DURATION_DEFAULT = 5000
     TOAST_DURATION_ERROR = 6000
 
+    # Fail-closed guard: when the host app has configured no authentication or
+    # authorization handler and has not explicitly opted into open access, deny
+    # all engine routes. Configured handlers short-circuit this and decide for
+    # themselves (see SourceMonitor::Security::Authentication).
+    def enforce_source_monitor_access_default
+      return unless SourceMonitor::Security::Authentication.access_denied_by_default?(self)
+
+      source_monitor_access_forbidden
+    end
+
+    def source_monitor_access_forbidden
+      message = "SourceMonitor access is not configured"
+      respond_to do |format|
+        format.html { render plain: message, status: :forbidden }
+        format.turbo_stream do
+          render turbo_stream: turbo_stream.append("flash",
+            partial: "source_monitor/shared/toast",
+            locals: { message: message, level: :error }),
+            status: :forbidden
+        end
+        format.json { render json: { error: message }, status: :forbidden }
+      end
+    end
+
     def authenticate_source_monitor_user
       SourceMonitor::Security::Authentication.authenticate!(self)
     end
@@ -60,22 +86,55 @@ module SourceMonitor
       level.to_sym == :error ? TOAST_DURATION_ERROR : TOAST_DURATION_DEFAULT
     end
 
-    def broadcast_flash_toasts
-      return if flash.empty?
-      return unless request.format.html? || request.format.turbo_stream?
+    # Request flashes are delivered response-local, never broadcast over the
+    # global ActionCable notification stream. On full-page HTML loads the layout
+    # renders the toasts inline (see +source_monitor_flash_toasts+); on
+    # turbo_stream responses we append the toasts to the response body so they
+    # reach only the requesting tab.
+    def source_monitor_flash_toasts
+      payloads = flash_toast_payloads
+      # Reading via the layout consumes the flash for this request so it does
+      # not linger into the next one.
+      flash.discard unless payloads.empty?
+      payloads
+    end
 
-      flash.each do |key, message|
-        next if message.blank?
+    def append_flash_toasts_to_turbo_stream
+      return unless request.format.turbo_stream?
+      return if response.redirect?
+
+      payloads = flash_toast_payloads
+      return if payloads.empty?
+
+      streams = payloads.map do |payload|
+        view_context.turbo_stream.append(
+          "source_monitor_notifications",
+          partial: "source_monitor/shared/toast",
+          locals: {
+            message: payload[:message],
+            level: payload[:level],
+            delay_ms: toast_delay_for(payload[:level])
+          }
+        )
+      end
 
-        Array(message).each do |msg|
-          SourceMonitor::Realtime.broadcast_toast(
-            message: msg,
-            level: FLASH_LEVELS[key.to_sym] || :info
-          )
+      response.body = "#{response.body}#{streams.join}"
+      flash.discard
+    end
+
+    # Builds the list of toast payloads ({ message:, level: }) for the current
+    # request's flash. Used by both the inline layout renderer and the
+    # turbo_stream after_action so request flashes stay response-local.
+    def flash_toast_payloads
+      return [] if flash.empty?
+
+      flash.flat_map do |key, message|
+        Array(message).filter_map do |msg|
+          next if msg.blank?
+
+          { message: msg, level: FLASH_LEVELS[key.to_sym] || :info }
         end
       end
-    ensure
-      flash.discard
     end
   end
 end

data/app/views/layouts/source_monitor/application.html.erb

@@ -19,6 +19,12 @@
       <div id="source_monitor_notifications"
            data-notification-container-target="list"
            class="flex w-full flex-col gap-3">
+        <%# Request flashes render response-local here (never broadcast to all tabs). %>
+        <% source_monitor_flash_toasts.each do |toast| %>
+          <%= render "source_monitor/shared/toast",
+                message: toast[:message],
+                level: toast[:level] %>
+        <% end %>
       </div>
       <div data-notification-container-target="badge"
            class="pointer-events-auto hidden">

data/docs/configuration.md

@@ -137,6 +137,11 @@ Call `config.realtime.action_cable_config` if you need a full hash for environme
 
 ## Authentication Helpers
 
+**Fail-closed by default.** SourceMonitor denies access to every engine route
+(returning `403 Forbidden`) unless you configure an authentication or
+authorization handler. This prevents the engine's create/update/delete/enqueue
+routes from being public by accident.
+
 Protect the dashboard with host-specific auth in one place:
 
 ```ruby
@@ -148,7 +153,19 @@ config.authentication.current_user_method = :current_user
 config.authentication.user_signed_in_method = :user_signed_in?
 ```
 
-Handlers can be symbols (invoked on the controller) or callables. Return `false` or raise to deny access.
+Handlers can be symbols (invoked on the controller) or callables. Return `false` or raise to deny access. As soon as either handler is configured, the handler decides access and the fail-closed guard no longer applies.
+
+### Open access opt-in (non-production)
+
+For local demos or sandboxes where engine routes are deliberately public, you
+can explicitly opt out of the fail-closed guard:
+
+```ruby
+config.authentication.open_access = true # default: false
+```
+
+This is intended for non-production/demo environments only. Configuring a
+handler always takes precedence over this flag.
 
 ## Health Model
 

data/docs/deployment.md

@@ -33,7 +33,7 @@ SourceMonitor assumes the standard Rails 8 process split:
 
 ## Security & Authentication
 
-- Lock down the engine routes with authentication hooks (`config.authentication.authenticate_with` / `authorize_with`).
+- SourceMonitor is **fail-closed by default**: without a configured handler every engine route returns `403 Forbidden`. Lock down the routes with authentication hooks (`config.authentication.authenticate_with` / `authorize_with`). Only set `config.authentication.open_access = true` for non-production demos where public access is intentional.
 - Configure HTTPS for Action Cable if you expose Solid Cable over the public internet.
 - Store API keys for authenticated feeds in encrypted credentials and inject them via per-source custom headers.