From 670771912b4fb334cc5efc046545dd521c37e585 Mon Sep 17 00:00:00 2001
From: Chuck Smith <eclectic-coding@users.noreply.github.com>
Date: Sun, 7 Jun 2026 07:02:30 -0400
Subject: [PATCH 1/2] feat: add config.dashboard_cards for custom overview
 dashboard cards

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  1 +
 README.md                                     | 12 ++++++
 ROADMAP.md                                    |  8 ----
 .../solid_stack_web/_07_dashboard.css         |  7 ++--
 .../solid_stack_web/dashboard/index.html.erb  | 21 ++++++++++
 lib/solid_stack_web.rb                        |  6 ++-
 .../solid_stack_web/dashboard_spec.rb         | 39 +++++++++++++++++++
 7 files changed, 82 insertions(+), 12 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index dab1b26..a322c7c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- `config.dashboard_cards` — accepts an array of `{ title:, link:, stats: }` hashes; each entry renders a custom card on the overview dashboard alongside the built-in Queue, Cache, and Cable cards; `stats` is an optional lambda returning a `{ label => value }` hash evaluated at render time; `link` is an optional `{ label:, url: }` for the card header
 - `config.nav_links` — accepts an array of `{ label:, url: }` hashes; each entry is appended to the main navigation bar so host apps can link back to their own admin pages or related tools without modifying the engine layout
 - i18n support — all UI labels, flash messages, table headers, empty states, confirmations, and sparkline tooltips are now backed by locale YAML files; ships with English (`en`) and Spanish (`es`) out of the box
 - Locale switcher — a `<select>` dropdown in the header lets users switch languages at runtime; locale is stored in the session and applied via `I18n.with_locale`; automatically hidden when only one locale is configured
diff --git a/README.md b/README.md
index d7a9de7..6cc8d02 100644
--- a/README.md
+++ b/README.md
@@ -130,6 +130,18 @@ SolidStackWeb.configure do |config|
     { label: "Back to App", url: "/" },
     { label: "Admin",       url: "/admin" }
   ]
+
+  # Custom dashboard cards — rendered after the built-in Queue, Cache, and Cable
+  # cards on the overview dashboard (default: []).
+  # Each card accepts a title, an optional header link, and an optional stats lambda
+  # that returns a { label => value } hash evaluated at render time.
+  config.dashboard_cards = [
+    {
+      title: "My App",
+      link:  { label: "View Admin", url: "/admin" },
+      stats: -> { { "Users" => User.count, "Premium" => User.premium.count } }
+    }
+  ]
 end
 ```
 
diff --git a/ROADMAP.md b/ROADMAP.md
index 85c02d5..6bd6aa1 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -5,14 +5,6 @@
 ---
 
 
-## v2.0 — Extensibility
-
-> _Breaking changes or large architectural additions._
-
-- **Custom dashboard cards** — registration hook so host apps can inject their own stat cards alongside the built-in queue, cache, and cable cards
-
----
-
 ## Out of Scope (for now)
 
 - **Background job execution** — this is a monitoring engine, not a worker runner; it will never enqueue or execute jobs itself
diff --git a/app/assets/stylesheets/solid_stack_web/_07_dashboard.css b/app/assets/stylesheets/solid_stack_web/_07_dashboard.css
index bc24208..503ea19 100644
--- a/app/assets/stylesheets/solid_stack_web/_07_dashboard.css
+++ b/app/assets/stylesheets/solid_stack_web/_07_dashboard.css
@@ -16,9 +16,10 @@
 }
 .sqw-gem-card:hover { box-shadow: 0 3px 8px rgba(0,0,0,.12); }
 
-.sqw-gem-card--queue { border-top-color: var(--primary); }
-.sqw-gem-card--cache { border-top-color: var(--purple); }
-.sqw-gem-card--cable { border-top-color: var(--info); }
+.sqw-gem-card--queue   { border-top-color: var(--primary); }
+.sqw-gem-card--cache   { border-top-color: var(--purple); }
+.sqw-gem-card--cable   { border-top-color: var(--info); }
+.sqw-gem-card--custom  { border-top-color: var(--muted); }
 
 .sqw-gem-card__header {
   display: flex;
diff --git a/app/views/solid_stack_web/dashboard/index.html.erb b/app/views/solid_stack_web/dashboard/index.html.erb
index b922ee8..d048139 100644
--- a/app/views/solid_stack_web/dashboard/index.html.erb
+++ b/app/views/solid_stack_web/dashboard/index.html.erb
@@ -142,5 +142,26 @@
       </div>
     <% end %>
   </div>
+
+  <% SolidStackWeb.dashboard_cards.each do |card| %>
+    <div class="sqw-gem-card sqw-gem-card--custom">
+      <div class="sqw-gem-card__header">
+        <span class="sqw-gem-card__title"><%= card[:title] %></span>
+        <% if card[:link] %>
+          <%= link_to card[:link][:label], card[:link][:url], class: "sqw-gem-card__link" %>
+        <% end %>
+      </div>
+      <% if card[:stats] %>
+        <div class="sqw-gem-card__body">
+          <% card[:stats].call.each do |label, value| %>
+            <div class="sqw-inline-stat sqw-inline-stat--neutral">
+              <span class="sqw-inline-stat__label"><%= label %></span>
+              <span class="sqw-inline-stat__value"><%= value %></span>
+            </div>
+          <% end %>
+        </div>
+      <% end %>
+    </div>
+  <% end %>
 </div>
 <% end %>
diff --git a/lib/solid_stack_web.rb b/lib/solid_stack_web.rb
index 5752ea8..856d456 100644
--- a/lib/solid_stack_web.rb
+++ b/lib/solid_stack_web.rb
@@ -9,7 +9,7 @@ class << self
                 :alert_slow_job_count_threshold, :alert_stale_process_threshold,
                 :dashboard_refresh_interval, :default_refresh_interval,
                 :search_results_limit, :allow_value_preview,
-                :available_locales, :nav_links
+                :available_locales, :nav_links, :dashboard_cards
 
     def page_size
       @page_size || 25
@@ -71,6 +71,10 @@ def nav_links
       @nav_links || []
     end
 
+    def dashboard_cards
+      @dashboard_cards || []
+    end
+
     # Returns the path at which the engine is mounted in the host application,
     # derived automatically from the host's routes. Host apps can use this to
     # build links to the dashboard without hardcoding the mount path.
diff --git a/spec/requests/solid_stack_web/dashboard_spec.rb b/spec/requests/solid_stack_web/dashboard_spec.rb
index b70967a..fc532d9 100644
--- a/spec/requests/solid_stack_web/dashboard_spec.rb
+++ b/spec/requests/solid_stack_web/dashboard_spec.rb
@@ -99,4 +99,43 @@
       expect(response.body).not_to include("Oldest")
     end
   end
+
+  describe "custom dashboard cards" do
+    after { SolidStackWeb.dashboard_cards = nil }
+
+    it "renders no custom cards by default" do
+      get engine_root
+      expect(response.body).not_to include('class="sqw-gem-card sqw-gem-card--custom"')
+    end
+
+    it "renders a configured custom card" do
+      SolidStackWeb.dashboard_cards = [{ title: "My App" }]
+      get engine_root
+      expect(response.body).to include('class="sqw-gem-card sqw-gem-card--custom"')
+      expect(response.body).to include("My App")
+    end
+
+    it "renders the optional header link" do
+      SolidStackWeb.dashboard_cards = [{ title: "My App", link: { label: "View Admin", url: "/admin" } }]
+      get engine_root
+      expect(response.body).to include("View Admin")
+      expect(response.body).to include("/admin")
+    end
+
+    it "renders stats returned by the stats lambda" do
+      SolidStackWeb.dashboard_cards = [{ title: "My App", stats: -> { { "Users" => 42, "Premium" => 7 } } }]
+      get engine_root
+      expect(response.body).to include("Users")
+      expect(response.body).to include("42")
+      expect(response.body).to include("Premium")
+      expect(response.body).to include("7")
+    end
+
+    it "renders multiple custom cards" do
+      SolidStackWeb.dashboard_cards = [{ title: "App One" }, { title: "App Two" }]
+      get engine_root
+      expect(response.body).to include("App One")
+      expect(response.body).to include("App Two")
+    end
+  end
 end

From 93421d6991b6d5ba00e72129547aa20a41920724 Mon Sep 17 00:00:00 2001
From: Chuck Smith <eclectic-coding@users.noreply.github.com>
Date: Sun, 7 Jun 2026 07:05:41 -0400
Subject: [PATCH 2/2] docs: add Extensibility section to README for nav_links
 and dashboard_cards

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 README.md | 69 +++++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 52 insertions(+), 17 deletions(-)

diff --git a/README.md b/README.md
index 6cc8d02..89ca433 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,7 @@
 [![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.3-ruby)](https://www.ruby-lang.org)
 [![codecov](https://codecov.io/gh/eclectic-coding/solid_stack_web/branch/main/graph/badge.svg)](https://codecov.io/gh/eclectic-coding/solid_stack_web)
 
-A production-ready operations dashboard for the full Rails Solid Stack. Mount one engine to get deep visibility into **Solid Queue** (job browser, failed job retry, queue controls, recurring tasks, performance stats), **Solid Cache** (entry browser, size distribution, write timeline), and **Solid Cable** (channel browser, message list, purge controls) — with dark mode, i18n locale switching, CSV export, alert webhooks, and a JSON metrics endpoint, all with no asset pipeline dependency.
+A production-ready operations dashboard for the full Rails Solid Stack. Mount one engine to get deep visibility into **Solid Queue** (job browser, failed job retry, queue controls, recurring tasks, performance stats), **Solid Cache** (entry browser, size distribution, write timeline), and **Solid Cable** (channel browser, message list, purge controls) — with dark mode, i18n locale switching, custom nav links, custom dashboard cards, CSV export, alert webhooks, and a JSON metrics endpoint, all with no asset pipeline dependency.
 
 ## Table of Contents
 
@@ -18,6 +18,9 @@ A production-ready operations dashboard for the full Rails Solid Stack. Mount on
   - [Linking to the dashboard](#linking-to-the-dashboard)
 - [i18n](#i18n)
   - [Adding a custom locale](#adding-a-custom-locale)
+- [Extensibility](#extensibility)
+  - [Custom nav links](#custom-nav-links)
+  - [Custom dashboard cards](#custom-dashboard-cards)
 - [Security](#security)
   - [Authentication](#authentication-1)
   - [Sensitive cache values](#sensitive-cache-values)
@@ -125,23 +128,10 @@ SolidStackWeb.configure do |config|
   config.connects_to = { database: { writing: :queue, reading: :queue } }
 
   # Custom nav links — appended to the main navigation bar (default: []).
-  # Use this to link back to your host application's admin pages or related tools.
-  config.nav_links = [
-    { label: "Back to App", url: "/" },
-    { label: "Admin",       url: "/admin" }
-  ]
+  config.nav_links = [{ label: "Admin", url: "/admin" }]
 
-  # Custom dashboard cards — rendered after the built-in Queue, Cache, and Cable
-  # cards on the overview dashboard (default: []).
-  # Each card accepts a title, an optional header link, and an optional stats lambda
-  # that returns a { label => value } hash evaluated at render time.
-  config.dashboard_cards = [
-    {
-      title: "My App",
-      link:  { label: "View Admin", url: "/admin" },
-      stats: -> { { "Users" => User.count, "Premium" => User.premium.count } }
-    }
-  ]
+  # Custom dashboard cards — rendered after the built-in cards (default: []).
+  config.dashboard_cards = [{ title: "My App", stats: -> { { "Users" => User.count } } }]
 end
 ```
 
@@ -193,6 +183,51 @@ Rails will pick up the file automatically via its standard `config.i18n.load_pat
 
 ---
 
+## Extensibility
+
+### Custom nav links
+
+`config.nav_links` appends extra links to the main navigation bar after the built-in Queue / Cache / Cable links. Use it to link back to your host application's admin pages or related tools without modifying the engine layout.
+
+```ruby
+SolidStackWeb.configure do |config|
+  config.nav_links = [
+    { label: "Back to App", url: "/" },
+    { label: "Admin",       url: "/admin" }
+  ]
+end
+```
+
+Defaults to `[]` — no extra links appear when unconfigured.
+
+### Custom dashboard cards
+
+`config.dashboard_cards` adds custom stat cards to the overview dashboard after the built-in Queue, Cache, and Cable cards. Each card accepts three keys:
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `title` | String | Card heading (required) |
+| `link` | `{ label:, url: }` | Optional header link rendered top-right |
+| `stats` | Lambda | Optional — called at render time; must return a `{ label => value }` hash |
+
+```ruby
+SolidStackWeb.configure do |config|
+  config.dashboard_cards = [
+    {
+      title: "My App",
+      link:  { label: "View Admin", url: "/admin" },
+      stats: -> { { "Users" => User.count, "Premium" => User.premium.count } }
+    }
+  ]
+end
+```
+
+The `stats` lambda runs on every dashboard render, so keep it fast. Defaults to `[]` — no custom cards appear when unconfigured.
+
+[↑ Back to top](#table-of-contents)
+
+---
+
 ## Security
 
 ### Authentication