<% new_count = insights.count(&:active?) %>
- <% if new_count.positive? %>
-
<%= t("insights.feed.header_new") %>·<%= new_count %>
- <% else %>
-
<%= t("insights.feed.header") %>
- <% end %>
+
+ <% if new_count.positive? %>
+
<%= t("insights.feed.header_new") %>·<%= new_count %>
+ <% else %>
+
<%= t("insights.feed.header") %>
+ <% end %>
+ <%= render DS::Pill.new(label: t("shared.preview")) %>
+
<%= render DS::Link.new(
text: t("insights.feed.view_all"),
diff --git a/config/schedule.yml b/config/schedule.yml
index eecea6985..795ccab7e 100644
--- a/config/schedule.yml
+++ b/config/schedule.yml
@@ -59,7 +59,7 @@ generate_insights:
cron: "0 6 * * *" # daily at 6:00 AM UTC, after the nightly cleanup jobs
class: "GenerateInsightsJob"
queue: "scheduled"
- description: "Generates proactive financial insights for all families"
+ description: "Generates proactive financial insights for families with preview features enabled"
sweep_expired_goal_pledges:
cron: "*/15 * * * *" # every 15 minutes
diff --git a/docs/llm-guides/gating-a-preview-feature.md b/docs/llm-guides/gating-a-preview-feature.md
index 43bec54f5..e396aef3c 100644
--- a/docs/llm-guides/gating-a-preview-feature.md
+++ b/docs/llm-guides/gating-a-preview-feature.md
@@ -140,6 +140,25 @@ Grep for `require_preview_features!` and `preview_features_enabled?` near your f
The flag is per-user, not per-family. Two users in the same family can see different versions of the product if one opts in and the other doesn't. That's intentional. Data is family-scoped, but visibility is a personal preference. If you write a feature that creates family-shared data (goals, budgets, etc.), the data persists when a user toggles preview off. The UI just disappears from their view while still showing up for opted-in family members.
-The gate does nothing for background jobs. If your feature has a Sidekiq cron job, it runs regardless of who has preview enabled. That's usually correct (data should keep flowing), but if the job sends notifications or emails, gate those at the send site too.
+The gate does nothing for background jobs on its own — `PreviewGateable` reads `Current.user`, which a Sidekiq worker doesn't have. A cron job runs regardless of who has preview enabled. That's usually correct: data should keep flowing, so it's there when someone opts in. `SweepExpiredGoalPledgesJob` is the typical shape — it only walks pledges that opted-in users created, so it's naturally inert for everyone else and needs no gate.
+
+Gate the job when it does work that isn't free. Two cases: it sends something outward (notifications, emails — gate at the send site), or it *manufactures* data for every family rather than moving existing data around, burning compute or paid API calls per family. `GenerateInsightsJob` is the second case: seven generators over the income statement and balance sheet, plus optional LLM narration, for every family nightly.
+
+For a family-scoped job, roll the per-user flag up to the family:
+
+```ruby
+# app/models/family.rb
+scope :with_preview_features, -> { where(id: User.with_preview_features.select(:family_id)) }
+
+def preview_features_enabled?
+ users.with_preview_features.exists?
+end
+```
+
+Filter the fan-out with the scope (one indexed query — `User.with_preview_features` is a jsonb containment match against the GIN index on `users.preferences`, not a load-and-iterate), and re-check with the predicate inside the per-family path, which is reachable directly from controllers and the console. Keep the same predicate name on both models so the GA-removal grep finds every call site. `GenerateInsightsJob` is the reference implementation.
+
+One opted-in member is enough to generate for the whole family — consistent with the per-user-visibility / family-scoped-data split described above.
+
+Note what the shared name costs: `preview_features_enabled?` means "I opted in" on `User` but "somebody in my household opted in" on `Family`. Only ever gate background work on the family form. Gating UI on it (`Current.family.preview_features_enabled?` reads naturally, which is the trap) would show the feature to someone who explicitly opted out because a family member opted in. For anything a person sees, use the `PreviewGateable` helper, which reads `Current.user`.
The redirect target is `/`. If you want gated controllers to land somewhere else (a docs page, an opt-in nudge), override `require_preview_features!` in the controller, or write a thin custom `before_action` that calls `preview_features_enabled?` directly.
diff --git a/test/controllers/insights_controller_test.rb b/test/controllers/insights_controller_test.rb
index 90c8e06e0..41c2573ab 100644
--- a/test/controllers/insights_controller_test.rb
+++ b/test/controllers/insights_controller_test.rb
@@ -3,6 +3,7 @@ require "test_helper"
class InsightsControllerTest < ActionDispatch::IntegrationTest
setup do
sign_in @user = users(:family_admin)
+ enable_preview_features
@insight = insights(:spending_anomaly_dining)
ensure_tailwind_build
end
@@ -97,4 +98,55 @@ class InsightsControllerTest < ActionDispatch::IntegrationTest
assert_redirected_to insights_path
end
+
+ # Preview gate. Insights is opt-in via Settings → Preferences, so a user
+ # without the flag reaches none of it — not the page, not the dashboard
+ # section, not the top-bar entry, and not the job the refresh action would
+ # otherwise enqueue.
+ test "redirects users without preview access" do
+ disable_preview_features
+
+ get insights_url
+
+ assert_redirected_to root_path
+ assert_match(/preview/i, flash[:alert])
+ end
+
+ test "refresh does not enqueue generation for users without preview access" do
+ disable_preview_features
+
+ assert_no_enqueued_jobs only: GenerateInsightsJob do
+ post refresh_insights_url
+ end
+
+ assert_redirected_to root_path
+ end
+
+ test "dismiss is blocked for users without preview access" do
+ disable_preview_features
+
+ patch dismiss_insight_url(@insight), as: :turbo_stream
+
+ assert_redirected_to root_path
+ assert @insight.reload.active?
+ end
+
+ test "dashboard omits the insights feed and top-bar entry without preview access" do
+ disable_preview_features
+
+ get root_url
+
+ assert_response :success
+ assert_select "#insights-feed", count: 0
+ assert_select "a[href=?]", insights_path, count: 0
+ end
+
+ private
+ def enable_preview_features
+ @user.update!(preferences: (@user.preferences || {}).merge("preview_features_enabled" => true))
+ end
+
+ def disable_preview_features
+ @user.update!(preferences: (@user.preferences || {}).merge("preview_features_enabled" => false))
+ end
end
diff --git a/test/jobs/generate_insights_job_test.rb b/test/jobs/generate_insights_job_test.rb
index f369670bf..55ef3ce21 100644
--- a/test/jobs/generate_insights_job_test.rb
+++ b/test/jobs/generate_insights_job_test.rb
@@ -3,12 +3,56 @@ require "test_helper"
class GenerateInsightsJobTest < ActiveJob::TestCase
setup do
@family = families(:dylan_family)
+ enable_preview_features(@family)
end
- test "without args enqueues one job per family" do
- assert_enqueued_jobs Family.count, only: GenerateInsightsJob do
+ test "without args enqueues one job per preview-enabled family" do
+ assert_operator Family.count, :>, Family.with_preview_features.count,
+ "fixture setup should leave some families without preview access"
+
+ assert_enqueued_jobs Family.with_preview_features.count, only: GenerateInsightsJob do
GenerateInsightsJob.perform_now
end
+
+ assert_enqueued_with(job: GenerateInsightsJob, args: [ { family_id: @family.id } ])
+ end
+
+ # Insights is a preview feature and the job manufactures data (and can spend
+ # LLM budget) per family, so families with nobody opted in are skipped
+ # entirely rather than generated for and hidden.
+ test "without args enqueues nothing when no family has preview access" do
+ disable_preview_features(@family)
+
+ assert_no_enqueued_jobs only: GenerateInsightsJob do
+ GenerateInsightsJob.perform_now
+ end
+ end
+
+ test "does nothing for a family without preview access" do
+ disable_preview_features(@family)
+
+ assert_no_difference "Insight.count" do
+ GenerateInsightsJob.perform_now(family_id: @family.id)
+ end
+ end
+
+ test "does not broadcast for a family without preview access" do
+ disable_preview_features(@family)
+
+ Turbo::StreamsChannel.expects(:broadcast_replace_to).never
+
+ GenerateInsightsJob.perform_now(family_id: @family.id)
+ end
+
+ test "generates for a family where only one member opted in" do
+ @family.users.each { |user| set_preview_features(user, false) }
+ set_preview_features(@family.users.first, true)
+
+ stub_generated([ generated_insight ])
+
+ assert_difference "@family.insights.count", 1 do
+ GenerateInsightsJob.perform_now(family_id: @family.id)
+ end
end
test "does nothing for an unknown family" do
@@ -157,6 +201,18 @@ class GenerateInsightsJobTest < ActiveJob::TestCase
end
private
+ def enable_preview_features(family)
+ family.users.each { |user| set_preview_features(user, true) }
+ end
+
+ def disable_preview_features(family)
+ family.users.each { |user| set_preview_features(user, false) }
+ end
+
+ def set_preview_features(user, enabled)
+ user.update!(preferences: (user.preferences || {}).merge("preview_features_enabled" => enabled))
+ end
+
def stub_generated(generated_insights, succeeded_types: nil)
result = Insight::GeneratorRegistry::Result.new(
insights: generated_insights,
diff --git a/test/models/family_test.rb b/test/models/family_test.rb
index 432a97ffd..f53be0b3a 100644
--- a/test/models/family_test.rb
+++ b/test/models/family_test.rb
@@ -312,4 +312,48 @@ class FamilyTest < ActiveSupport::TestCase
assert_equal count_after_first, AccountShare.where(user: newcomer).count,
"re-running must not create duplicate shares"
end
+
+ # Preview access is per-user, but jobs that act on family-scoped data have no
+ # Current.user. One opted-in member enables the family.
+ test "preview_features_enabled? is true when any member has opted in" do
+ family = families(:dylan_family)
+ family.users.each { |user| set_preview_features(user, false) }
+
+ assert_not family.reload.preview_features_enabled?
+
+ set_preview_features(family.users.first, true)
+
+ assert family.reload.preview_features_enabled?
+ end
+
+ test "with_preview_features scope agrees with the predicate" do
+ family = families(:dylan_family)
+ family.users.each { |user| set_preview_features(user, false) }
+
+ assert_not_includes Family.with_preview_features, family.reload
+
+ set_preview_features(family.users.first, true)
+
+ assert_includes Family.with_preview_features, family.reload
+ end
+
+ # The family rollup is a jsonb containment match; the UI gates on
+ # User#preview_features_enabled?'s strict `== true`. If containment were the
+ # looser of the two, the nightly job would generate for families whose UI
+ # still hides the feature — so assert the user-level predicate agrees.
+ test "with_preview_features ignores truthy non-boolean values" do
+ family = families(:dylan_family)
+ family.users.each { |user| set_preview_features(user, false) }
+ set_preview_features(family.users.first, "yes")
+
+ assert_not family.users.first.reload.preview_features_enabled?,
+ "the per-user predicate the UI reads must reject a non-boolean"
+ assert_not family.reload.preview_features_enabled?
+ assert_not_includes Family.with_preview_features, family
+ end
+
+ private
+ def set_preview_features(user, enabled)
+ user.update!(preferences: (user.preferences || {}).merge("preview_features_enabled" => enabled))
+ end
end