rails_pulse 0.4.2 → 0.5.0.pre.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b54f69a078537dd6dabc4074623c3deaf4b0123f4c229b57c706583f104d1b62
-  data.tar.gz: 2cd90650cc8ceb9cf15dac48c4d4695113c73a52fdb4661153fa5c45cbf3b378
+  metadata.gz: 208274704510167233904a19653cfe5bffcf6f29080344d088e9cbee8c425a87
+  data.tar.gz: fbbe9e3a6c35a09236a81158d47026a9ab913f1db6e79800b8c71183df4d9d63
 SHA512:
-  metadata.gz: 125303510a989e6de226b732d14fd76d001b5641feb4f93bd8ae5daf07ec73b2328c022097c36be6b4153cd270a9344bf8d4f14e1364843b96fdabd07beb0aab
-  data.tar.gz: d262a5d599007772f1cccc087b6166fd3a151f93f3cdf990bcd37b3ffed6dc6df3aa785a959ae0ae92ac56df545d9a299aed1ec41e3f3d605adb868ce9bb22d0
+  metadata.gz: 83b22f6771f0c1a99bada73bd60e1af0abb7a7931b5523afa9c1a852c85bf7664d4af32ec025d955ff6db47dfde7c3b2563fee86301d2a7032b0a6f7f1615543
+  data.tar.gz: '08fd08858f4eafa689a17e92c922623f15f11ff9663de193b3f99830faa59a171bef0a7c5357dbb7bcd2df9afd1ab97f7f6c3ff52ca4cb0f67d7835f11c99730'

data/CHANGELOG.md

@@ -5,7 +5,64 @@ All notable changes to Rails Pulse will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## 0.4.2 - 2025-10-01
+## [Unreleased]
+
+## [0.5.0.pre.2] - 2026-10-11
+
+### Added
+
+- **Before-and-after comparison for every deployment.** The deployments API, `rails-pulse deployments list` and the `rails_pulse_deployments` tool now say whether each release made things worse: response time or error rate materially worse in the hour after the deploy finished than in the hour before it started, or too little traffic to tell.
+- **What needs attention, and whether the thresholds fit.** `GET /rails_pulse/api/v1/insights`, `rails-pulse insights show` and the `rails_pulse_insights` tool list the routes, queries and jobs past their thresholds over one hour, day, week or month, and suggest an initializer line when `route_thresholds` or `query_thresholds` is too noisy or never fires.
+- **Exact lookups for the keys Rails Pulse Cloud holds.** The API, CLI and MCP tools can now find a query by `hashed_sql`, an exception group by `fingerprint`, a route by exact path and controller action, a deployment by revision, and requests by path prefix, so a Cloud alert leads straight to the local detail.
+- **Rails Pulse Cloud sync.** With `config.cloud.api_key` and `config.cloud.application` set, hourly summaries, exception groups, deployments and a per-minute health update are sent to Rails Pulse Cloud (never request URLs, SQL values or exception messages), and `rails rails_pulse:cloud:preview` prints exactly what would be sent; to use it, run `rails generate rails_pulse:install_cloud`, migrate, and schedule `RailsPulse::CloudHealthJob` every minute.
+- **`rails rails_pulse:status` checks how the install is run.** It reports whether `SummaryJob` has skipped hours and whether `CleanupJob` is running, how long hourly summaries are kept, and whether jobs are tracked, and lists suggestions for each without changing the exit status. Each cleanup run is now recorded in `rails_pulse_events` so the task can tell.
+
+### Changed
+
+- **A query is the same query however many values it loads.** `WHERE id IN (…)` with 3 ids and with 12 ids, and a batch insert of 2 rows and of 50, used to be tracked as separate queries, each with its own stats, N+1 flags and EXPLAIN; they are now one entry. Entries recorded by earlier versions keep their old form until retention removes them, so a query may appear twice on the Queries page for a while after upgrading.
+- **Hourly summaries are kept for 7 days instead of 2.** Deployment comparisons and hour-precise change points read them, so at 2 days a deploy from earlier in the week could no longer be compared; `config.hourly_summary_retention` tunes it.
+
+### Fixed
+
+- **Normalised SQL no longer shows some string values.** A value written in one of SQL's less common string forms — only possible in hand-written SQL — stayed visible in the normalised query on the dashboard, the API and the MCP server, and split that query's stats into one entry per value; it is now replaced with `?` like any other value. On MySQL the same happened to any value containing an apostrophe or any double-quoted value shaped like a column name, and on every database to very small or very large decimals. (#335, #313)
+- **The dashboard no longer counts every Rails Pulse table on each load.** On PostgreSQL and MySQL its storage panel now shows the database's row estimates, and on SQLite it leaves record counts to the Storage page, so large installs no longer wait tens of seconds per page view; the storage-pressure checks also run once per page instead of four times. On MySQL 8, record counts and disk sizes on the dashboard and the Storage page are read current instead of from a statistics cache up to a day old. (#363)
+- **Needs Attention and System Health no longer overcount traffic.** Request, error, query and exception counts were added up once per summary granularity, which inflated them and could raise an exception group's severity; today's traffic now counts in windows longer than a day. (#338)
+- **Threshold recommendations no longer suggest a critical threshold equal to `very_slow` or below a rarely run slow query.** A suggested critical threshold now sits at least one step above `very_slow`, and the query check reads the period's slowest query rather than only its most expensive ones.
+- **The dashboard no longer reports cleanup as blocked when it is not.** The critical "summarize first" Storage item appeared whenever expired requests were waiting for the next daily cleanup, which deletes them by age regardless of summaries; it has been removed, and a stalled summary job is still flagged.
+- **PostgreSQL Unicode escape strings (`U&'…'`) are normalised to `?`** like other prefixed strings, instead of leaving `U&?` in the normalised query.
+- **Daily charts no longer go blank after a daylight-saving change.** In a `config.time_zone` with daylight saving, every day after the clocks changed was drawn empty in a range that crossed the change; chart days now follow the zone's calendar.
+
+## [0.5.0.pre.1] - 2026-10-03
+
+### Added
+
+- **JSON API, `rails-pulse` CLI and MCP server.** A read-only API under `/rails_pulse/api/v1`, a `rails-pulse` executable and an MCP server (`rails-pulse mcp`; add `gem "mcp"` to your Gemfile) give scripts, CI and coding agents what the dashboard shows: routes, requests, queries, jobs, job runs, exceptions and deployments. (#309)
+- **Coverage reporting for agents.** `rails-pulse coverage show` and the `rails_pulse_coverage` tool report what has been recorded, how recently, any collection gaps, and which application and environment answered, so missing data is not mistaken for an all-clear. (#309)
+- **Fixed windows and drilldown.** Every windowed command and tool takes ISO 8601 `since`/`until` and reports the window it measured, and `rails_pulse_queries` takes an endpoint's `route_id` to show the SQL inside it with the file and line each query came from. (#309)
+- **Agent instructions.** `rails-pulse install claude` installs a Claude Code skill, and `rails-pulse install agents` writes a Rails Pulse section into `AGENTS.md`, alongside a project's own instructions with `--append`. (#309)
+- `rails rails_pulse:status` reports whether the API and deployment tokens are set. (#309)
+- **Dropped requests are now visible.** Each background writer records a heartbeat once a minute (queue depth and requests dropped since the last one), pruned after a day. The dashboard's health bar gains a Tracking badge, shown only when a writer is backlogged or dropping requests; the Storage page lists every live writer with its queue and drops; and `rails rails_pulse:status` reports the totals and exits 1 when anything was dropped in the last hour. (#281)
+- **A `rails_pulse_events` table** for what Rails Pulse notices rather than measures, starting with the writer heartbeats above. `config.event_retention_period` (default 90 days) prunes it. Run `rails generate rails_pulse:upgrade` and migrate; tracking pauses until the table exists.
+- CI now exercises the separate-database upgrade path (`bin/test_separate_database_upgrade`, SQLite and PostgreSQL), and the migration regression suite gains a 0.3.2 baseline. (#284)
+- **Charts say which time zone they are in.** Every chart carries a zone badge (hover for the full zone name and the exact window shown), chart tooltips end with the zone, and the custom date range picker states the zone its inputs are read in. (#303)
+
+### Changed
+
+- **Daily, weekly and monthly summaries are built from shorter periods instead of raw rows.** The summary job's memory no longer grows with the length of the period or with raised retention caps, and longer periods stay complete after raw data is pruned; their P50/P95/P99 are now traffic-weighted from the hours or days below them, as the dashboard already shows for multi-period ranges. A period is summarized only once it ends, so the backfill task no longer writes a partial row for the current day. (#279)
+- **`config.deployment_api_token` is now `config.deployment_token`.** The old name still works and still only records deployments; the JSON API reads a separate `config.api_token`, so a token given to a coding agent cannot record a release. (#309)
+- **Recording a deployment over HTTP requires `config.deployment_token`.** The deployments endpoint no longer accepts a dashboard login in place of the token, which let any page a signed-in admin visited record a release; set the token for CI, or use the `rails_pulse:record_deployment` task, which needs none. (#309)
+- **All timestamps display in the app's `config.time_zone`.** Chart axes and tooltips are formatted in that zone rather than the browser's, so a daily point no longer lands on the wrong calendar day for viewers in another zone. Request, job, exception and operation timestamps also use it instead of the server's OS zone; on a host whose server runs in UTC with a different `config.time_zone`, those pages now show the configured zone. (#303)
+- **Dashboard health bar badges omit zero counts.** "26 healthy · 0 slow · 0 critical" now reads "26 healthy"; the Storage badge is shown only under warning or critical pressure.
+- **Dropped the `request_store` runtime dependency.** Per-request tracking state now goes through `RailsPulse::Current`, built on Rails' own `ActiveSupport::CurrentAttributes`. No configuration or behavior change; a host that read `RequestStore.store[:rails_pulse_request_id]` directly (undocumented, but reachable) needs to switch to `RailsPulse::Current.rails_pulse_request_id`. (#277)
+- **Requires Ruby 3.2+ and Rails 7.2+.** The gemspec advertised Ruby 3.1 and Rails 7.1 but CI never ran them; the floors now match what is tested, and the untested Rails 7.1 and Ruby 3.1 code paths are gone. (#270)
+
+### Fixed
+
+- Weekly and monthly summaries written by `SummaryJob` now include the period's last day. (#279)
+- Backfill date arguments are read in the app's time zone, so backfilled summaries land on the same period boundaries the scheduled job writes instead of UTC midnights. (#279)
+- **The exception-group row cap no longer counts preserved and ignored groups.** Once those exempt groups approached the cap, every cleanup run deleted the oldest deletable groups without ever getting under it. The cap now applies to deletable groups only. (#285)
+
+## [0.4.2] - 2026-10-01
 
 ### Changed
 

data/README.md

@@ -8,7 +8,7 @@
 
 ![Gem Version](https://img.shields.io/gem/v/rails_pulse)
 ![Rails Version](https://img.shields.io/badge/Rails-7.2%2B-blue)
-![Ruby Version](https://img.shields.io/badge/Ruby-3.1%2B-red)
+![Ruby Version](https://img.shields.io/badge/Ruby-3.2%2B-red)
 ![License](https://img.shields.io/badge/License-MIT-green)
 
 Rails Pulse is a Rails engine. It hooks into the instrumentation Rails already emits, writes what it sees to a handful of tables, and mounts a dashboard that shows you where the time went. Install the gem, run one migration, schedule two jobs, and you have monitoring that works the same on SQLite, PostgreSQL and MySQL.
@@ -27,6 +27,7 @@ Rails Pulse is a Rails engine. It hooks into the instrumentation Rails already e
 - **Jobs and exceptions in the same place.** Duration, queue wait and failure rate for every Active Job class on any adapter. Unhandled exceptions from requests and jobs grouped by class and location, with filtered params and backtraces.
 - **Numbers over time.** Hourly, daily, weekly and monthly summaries with P50, P95 and P99, your service level objectives drawn as lines on the charts, and a marker for every deploy so a regression lines up with the release that caused it.
 - **Built for production.** Tracking is queued off the request thread and dropped rather than blocked under load. If the gem is deployed before its migrations, tracking pauses and tells you what to run. Retention is enforced by age and by row count so the tables never grow without bound.
+- **Your coding agent can read it.** A read-only JSON API, a `rails-pulse` CLI and an MCP server give Claude Code, Codex, Cursor or a CI script the same data: the slowest endpoints since the last deploy, the queries behind them, the jobs that failed. Ask the agent why checkout got slow and it can go and look.
 
 <table>
   <tr>
@@ -89,7 +90,7 @@ production:
 
 Open `http://localhost:3000/rails_pulse`. That's the whole setup.
 
-Requirements: Ruby 3.1+, Rails 7.2+ (tested on 7.2, 8.0 and 8.1), SQLite, PostgreSQL or MySQL.
+Requirements: Ruby 3.2+, Rails 7.2+ (tested on 7.2, 8.0 and 8.1), SQLite, PostgreSQL or MySQL.
 
 Full install guide, including a separate database and plain cron: [railspulse.com/documentation/installation](https://railspulse.com/documentation/installation)
 
@@ -109,7 +110,17 @@ With nothing configured it falls back to HTTP Basic against `RAILS_PULSE_USERNAM
 
 **Run the dashboard on its own.** `bundle exec rails_pulse_server` serves the UI from a separate process with its own health endpoint, so a slow report never competes with your app for a thread. [Deployment modes](https://railspulse.com/documentation/deployment-modes)
 
-**Mark your deploys.** `rails rails_pulse:record_deployment[sha]` from a release script, or `POST /rails_pulse/deployments` with a token from CI, and every chart draws a line at that moment.
+**Mark your deploys.** `rails rails_pulse:record_deployment[sha]` from a release script, or `POST /rails_pulse/deployments` with the API token from CI, and every chart draws a line at that moment.
+
+**Brief your agent.** Set `config.api_token`, then on your machine:
+
+```bash
+rails-pulse configure          # URL and token, saved to ~/.rails-pulse
+rails-pulse routes list --since 2026-06-01T00:00:00Z
+rails-pulse install claude     # Claude Code skill: when and how to use the tools
+```
+
+Add `gem "mcp"` to your Gemfile (a development group is enough), register `rails-pulse mcp` as an MCP server, and the agent gets eleven read-only tools: routes, slow requests, errors, exception groups and their backtraces, one endpoint in depth, expensive and N+1 queries, job health, deployments and whether each one made things worse, what needs attention and whether your thresholds fit, and what has actually been recorded. Nothing the agent can call changes production. [Agent tooling](docs/api.md)
 
 **Keep it in its own database.** `rails generate rails_pulse:install --database=separate` puts the tables somewhere your primary never has to vacuum. [Database setup](https://railspulse.com/documentation/database)
 
@@ -126,7 +137,7 @@ Upgrading from 0.3.x to 0.4? **Back up first**, run `rails rails_pulse:migrate_r
 
 ## Contributing
 
-Bug reports and pull requests are welcome on [GitHub](https://github.com/railspulse/rails_pulse). `docs/` explains how the pieces fit and why they are built the way they are.
+Bug reports and pull requests are welcome on [GitHub](https://github.com/railspulse/rails_pulse). `docs/` explains how the pieces fit and why they are built the way they are. Building on top of Rails Pulse (a plugin, scripting the CLI)? [`docs/api.md`](docs/api.md) states what's public and stable across minor releases.
 
 ```bash
 git config core.hooksPath .githooks   # once, after cloning

data/app/assets/stylesheets/rails_pulse/components/chart.css

@@ -85,6 +85,17 @@
   border-left: none;
 }
 
+/* Aggregation-zone badge beside a chart title or tab strip. Its title
+   attribute carries the full zone name and the resolved window, hence the
+   help cursor. */
+.zone-badge {
+  font-size: var(--text-xs);
+  font-weight: var(--font-normal);
+  color: var(--color-text-subtle);
+  white-space: nowrap;
+  cursor: help;
+}
+
 .panel-tab {
   display: inline-flex;
   align-items: center;

data/app/assets/stylesheets/rails_pulse/components/descriptive_list.css

@@ -1,3 +1,9 @@
+/* @container rules match descendants of the container, not the container
+   itself, so the containment context has to live on the parent. */
+:has(> .descriptive-list) {
+  container-type: inline-size;
+}
+
 .descriptive-list {
   display: grid;
   grid-template-columns: 200px 1fr;
@@ -6,9 +12,21 @@
 
 .descriptive-list dt, .descriptive-list dd {
   font-size: var(--text-sm);
+  min-width: 0;
 }
 
 .descriptive-list dd {
   overflow-wrap: break-word;
-  min-width: 0;
+}
+
+/* Below this the fixed 200px label column crowds out the value column */
+@container (max-width: 340px) {
+  .descriptive-list {
+    grid-template-columns: 1fr;
+    gap: 0.125rem 0.5rem;
+  }
+
+  .descriptive-list dd {
+    margin-block-end: 0.5rem;
+  }
 }

data/app/assets/stylesheets/rails_pulse/components/row.css

@@ -23,7 +23,7 @@
   flex: 1;
 }
 
-/* Responsive layout for screens smaller than 768px */
+/* Single column below 768px */
 @media (max-width: 768px) {
   .row {
       display: flex;
@@ -34,35 +34,21 @@
   }
 
   .row > * {
-      flex: 0 0 calc(50% - 0.25rem);
+      flex: 0 0 100%;
       min-width: 0;
       height: auto;
   }
 
   .row > .grid-item {
       height: auto;
+      min-height: auto;
   }
 
   .row > .grid-item > * {
       flex: none;
   }
 
-  /* Tables and chart panels should stack in single column on tablet */
-  .row:has(.table-container) > *,
-  .row:has(.chart-container) > * {
-      flex: 0 0 100%;
-  }
-
-  /* Single column for very small screens */
   @media (max-width: 480px) {
-    .row > * {
-        flex: 0 0 100%;
-    }
-
-    .row > .grid-item {
-        min-height: auto;
-    }
-
     /* Make metric cards more compact on mobile */
     .row > .grid-item .card {
         padding: var(--size-3);

data/app/controllers/concerns/chart_table_concern.rb

@@ -2,7 +2,6 @@
 #
 # Core concern for controllers that display both charts and tables (routes, requests, queries, jobs).
 # Orchestrates time range setup, chart generation, table queries, and zoom/filter handling.
-# Includes TimeRangeConcern, ResponseRangeConcern, and ZoomRangeConcern for filter management.
 #
 # Controllers including this concern must implement:
 # - chart_model, table_model, chart_definitions, default_table_sort, build_table_results
@@ -13,9 +12,7 @@ module ChartTableConcern
   VALID_PERIOD_TYPES = %w[hour day].freeze
 
   included do
-    include TimeRangeConcern
-    include ResponseRangeConcern
-    include ZoomRangeConcern
+    include RansackParamsConcern
     include DeploymentMarkersConcern
 
     before_action :setup_page_timings
@@ -24,32 +21,16 @@ module ChartTableConcern
 
   private
 
+  # Hook: override to change the default time range (e.g. :last_7_days).
+  def default_time_range_key = :last_24_hours
+
   def setup_page_timings
-    start_time, end_time, selected_time_range, time_diff_hours = setup_time_range
-    start_duration, selected_response_range = setup_duration_range(duration_range_type)
-    zoom_start, zoom_end, table_start_time, table_end_time =
-      setup_zoom_range(start_time, end_time)
-
-    @page_timings = PageTimings.new(
-      start_time: start_time, end_time: end_time,
-      table_start_time: table_start_time, table_end_time: table_end_time,
-      zoom_start: zoom_start, zoom_end: zoom_end,
-      time_diff_hours: time_diff_hours, start_duration: start_duration,
-      selected_time_range: selected_time_range, selected_response_range: selected_response_range
+    @time_range = RailsPulse::TimeRange.resolve(
+      params: params,
+      session: session,
+      default_key: default_time_range_key,
+      duration_range_type: duration_range_type
     )
-
-    # Keep individual @vars for backward compat with views, helpers, and other
-    # concerns (DeploymentMarkersConcern, MetricCardConcern, ChartHelper).
-    @start_time = start_time
-    @end_time = end_time
-    @time_diff_hours = time_diff_hours
-    @start_duration = start_duration
-    @selected_time_range = selected_time_range
-    @selected_response_range = selected_response_range
-    @zoom_start = zoom_start
-    @zoom_end = zoom_end
-    @table_start_time = table_start_time
-    @table_end_time = table_end_time
   end
 
   def setup_chart_and_table_data
@@ -78,9 +59,8 @@ module ChartTableConcern
     common_options = {
       ransack_query: chart_ransack_query,
       period_type: period_type,
-      start_time: @page_timings.start_time,
-      end_time: @page_timings.end_time,
-      start_duration: @page_timings.start_duration,
+      window: @time_range&.window,
+      start_duration: @time_range&.start_duration,
       disabled_tags: session_disabled_tags,
       show_non_tagged: session[:show_non_tagged] != false,
       **chart_options
@@ -110,22 +90,7 @@ module ChartTableConcern
   end
 
   def period_type
-    time_diff = @page_timings&.time_diff_hours
-
-    type = if time_diff.nil?
-      "day"  # Default to day for "recent" mode or when time_diff isn't set
-    elsif time_diff <= 25
-      "hour"
-    else
-      "day"
-    end
-
-    # Validate period type to prevent SQL injection via string interpolation
-    unless VALID_PERIOD_TYPES.include?(type)
-      raise ArgumentError, "Invalid period_type: #{type}. Must be one of: #{VALID_PERIOD_TYPES.join(", ")}"
-    end
-
-    type
+    @time_range&.period_type || "day"
   end
 
   def meaningful_chart_data?
@@ -181,15 +146,13 @@ module ChartTableConcern
 
   # Builds ransack parameters for chart queries
   # Common pattern: time range + optional duration filter + resource scope
-  # Handles "recent" mode where @page_timings.start_time/@end_time may be nil
   def build_chart_ransack_params(ransack_params)
     base_params = ransack_params.except(:s, *chart_filter_exclusions)
 
-    # Add time filters if we have time boundaries (not in "recent" mode)
-    if @page_timings&.start_time && @page_timings&.end_time
+    if @time_range&.window
       base_params.merge!(
-        period_start_gteq: Time.at(@page_timings.start_time),
-        period_start_lt: Time.at(@page_timings.end_time)
+        period_start_gteq: @time_range.window.start_time,
+        period_start_lt: @time_range.window.end_time
       )
     end
 
@@ -197,8 +160,8 @@ module ChartTableConcern
     base_params.merge!(summarizable_type_eq: summarizable_type) if summarizable_type
 
     # Only add duration filter if we have a meaningful threshold
-    if @page_timings&.start_duration && @page_timings.start_duration > 0
-      base_params[:avg_duration_gteq] = @page_timings.start_duration
+    if @time_range&.start_duration && @time_range.start_duration > 0
+      base_params[:avg_duration_gteq] = @time_range.start_duration
     end
 
     # Scope to specific resource on show pages
@@ -220,41 +183,37 @@ module ChartTableConcern
   end
 
   # Builds table params for show pages (individual records like Request, JobRun)
-  # Handles "recent" mode where time boundaries may be nil
   def build_show_table_ransack_params(ransack_params)
     params = ransack_params.dup
 
-    # Add time filters if we have time boundaries (not in "recent" mode)
-    if @page_timings&.table_start_time && @page_timings&.table_end_time
+    if @time_range&.table_window
       params.merge!(
-        occurred_at_gteq: Time.at(@page_timings.table_start_time),
-        occurred_at_lt: Time.at(@page_timings.table_end_time)
+        occurred_at_gteq: @time_range.table_window.start_time,
+        occurred_at_lt: @time_range.table_window.end_time
       )
     end
 
     params.merge!(show_resource_filter)
-    if @page_timings&.start_duration && @page_timings.start_duration > 0
-      params[:duration_gteq] = @page_timings.start_duration
+    if @time_range&.start_duration && @time_range.start_duration > 0
+      params[:duration_gteq] = @time_range.start_duration
     end
     params
   end
 
   # Builds table params for index pages (summary records)
-  # Handles "recent" mode where time boundaries may be nil
   def build_index_table_ransack_params(ransack_params)
     params = ransack_params.dup
 
-    # Add time filters if we have time boundaries (not in "recent" mode)
-    if @page_timings&.table_start_time && @page_timings&.table_end_time
+    if @time_range&.table_window
       params.merge!(
-        period_start_gteq: Time.at(@page_timings.table_start_time),
-        period_start_lt: Time.at(@page_timings.table_end_time)
+        period_start_gteq: @time_range.table_window.start_time,
+        period_start_lt: @time_range.table_window.end_time
       )
     end
 
     params.merge!(summarizable_type_eq: summarizable_type) if summarizable_type
-    if @page_timings&.start_duration && @page_timings.start_duration > 0
-      params[:avg_duration_gteq] = @page_timings.start_duration
+    if @time_range&.start_duration && @time_range.start_duration > 0
+      params[:avg_duration_gteq] = @time_range.start_duration
     end
     params
   end
@@ -285,7 +244,7 @@ module ChartTableConcern
     raise NotImplementedError, "#{self.class} must implement #chart_definitions"
   end
 
-  # Returns options passed to chart classes (e.g., { route: @route })
+  # Returns options passed to chart classes (e.g., { subject: @route })
   def chart_options
     {}
   end

data/app/controllers/concerns/deployment_markers_concern.rb

@@ -1,7 +1,9 @@
 module DeploymentMarkersConcern
   def populate_deployment_markers
+    return unless @time_range&.window
+
     @deployment_markers = RailsPulse::Deployment
-      .for_range(Time.zone.at(@start_time), Time.zone.at(@end_time))
+      .for_range(@time_range.window.start_time, @time_range.window.end_time)
       .map(&:to_chart_marker)
   end
 end

data/app/controllers/concerns/metric_card_concern.rb

@@ -33,14 +33,13 @@ module MetricCardConcern
     end
   end
 
-  # Common parameters passed to all metric card classes
+  # Common parameters passed to all metric card classes. Deliberately does
+  # NOT pass window: — these cards show a "trailing period" figure, not the
+  # exact selected range (ChartTableConcern's charts get the exact window;
+  # see Cards::Base#window_days).
   def metric_card_params
-    # For "recent" mode with no time filtering, use a default period of 7 days
-    period_days = if @start_time.nil? || @end_time.nil?
-      7
-    else
-      ((@end_time - @start_time) / 1.day).round
-    end
+    window = @time_range&.window
+    period_days = window ? ((window.end_time - window.start_time) / 1.day).round : 7
 
     {
       resource_key => current_resource,

data/app/controllers/rails_pulse/api/v1/base_controller.rb

@@ -0,0 +1,133 @@
+module RailsPulse
+  module Api
+    module V1
+      # Read-only JSON API for the rails-pulse CLI, the MCP server, CI scripts
+      # and coding agents. Authenticated by config.api_token alone: the
+      # dashboard session is never consulted, and with no token configured
+      # every request is refused.
+      class BaseController < RailsPulse::ApplicationController
+        skip_before_action :authenticate_rails_pulse_user!
+        skip_before_action :set_show_non_tagged_default
+        skip_before_action :set_onboarding_state
+        skip_before_action :load_deployment_markers
+
+        # Prepended so it runs ahead of the inherited require_current_schema!:
+        # the schema report lists missing tables and columns and must not be
+        # served to anonymous callers.
+        prepend_before_action :authenticate_api_token!
+
+        # After authentication, so an anonymous caller learns nothing from
+        # which of its parameters were refused.
+        before_action :validate_params!
+
+        # Every action is a GET read from the query string. Rails would
+        # otherwise copy a JSON request's parameters into a hash named after
+        # the controller (`route`, `job`), which collides with the filters of
+        # the same name whenever a client sends Content-Type: application/json.
+        wrap_parameters false
+
+        # Parameters every endpoint reads as one string. A repeated or nested
+        # one (`search[]=x`) is refused rather than reaching a String method.
+        SCALAR_PARAMS = %i[
+          limit offset min_requests occurrences since until search route status sort job period at
+          hashed_sql fingerprint path controller_action path_prefix revision
+        ].freeze
+        INTEGER_PARAMS = %i[limit offset min_requests occurrences].freeze
+
+        # Past any real table, and inside a 64-bit integer on every adapter.
+        MAX_INTEGER = 1_000_000_000
+
+        # A date, optionally a time, optionally a zone. Time.parse would also
+        # take "10" as the 10th of this month, which is not a window anyone
+        # asked for.
+        ISO8601 = /\A\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?)?(?:Z|[+-]\d{2}:?\d{2})?\z/i
+
+        private
+
+        def authenticate_api_token!
+          token = RailsPulse.configuration.api_token.to_s
+          provided = request.headers["X-Rails-Pulse-Token"].to_s
+          return if token.present? && ActiveSupport::SecurityUtils.secure_compare(provided, token)
+
+          render json: { error: "Unauthorized" }, status: :unauthorized
+        end
+
+        # The schema report picks its format from the request; API callers
+        # rarely send an Accept header, so answer JSON regardless.
+        def require_current_schema!
+          request.format = :json
+          super
+        end
+
+        def validate_params!
+          SCALAR_PARAMS.each do |name|
+            value = params[name]
+            next if value.nil? || value.is_a?(String)
+
+            return render_bad_request("'#{name}' must be a single value")
+          end
+
+          INTEGER_PARAMS.each do |name|
+            value = params[name]
+            next if value.blank? || value.match?(/\A\d+\z/)
+
+            return render_bad_request("'#{name}' must be a whole number")
+          end
+
+          @since_time = parse_time_param(:since)
+          return if performed?
+          @until_time = parse_time_param(:until)
+          return if performed?
+
+          if @since_time && @until_time && @until_time <= @since_time
+            render_bad_request("'until' must be later than 'since'")
+          end
+        end
+
+        def render_bad_request(message)
+          render json: { error: message }, status: :bad_request
+        end
+
+        def limit
+          integer_param(:limit, 25, 1..500)
+        end
+
+        def offset
+          integer_param(:offset, 0, 0..MAX_INTEGER)
+        end
+
+        def integer_param(name, default, range)
+          params[name].blank? ? default : params[name].to_i.clamp(range)
+        end
+
+        # A time with no zone is read as UTC, so a window means the same thing
+        # wherever the caller and the server are.
+        def parse_time_param(name)
+          value = params[name]
+          return if value.blank?
+
+          string = value.strip
+          raise ArgumentError unless string.match?(ISO8601)
+
+          ActiveSupport::TimeZone["UTC"].parse(string)
+        rescue ArgumentError
+          render_bad_request(
+            "Invalid time format for '#{name}'. Use ISO 8601, such as 2026-09-24T12:00:00Z; " \
+            "a time with no zone is read as UTC."
+          )
+        end
+
+        # Parsed and checked by validate_params! before the action runs.
+        def time_range
+          [ @since_time, @until_time ]
+        end
+
+        def paginated(collection)
+          total = collection.count
+          data = collection.limit(limit).offset(offset)
+          [ data, { total: total, limit: limit, offset: offset } ]
+        end
+      end
+    end
+  end
+end

data/app/controllers/rails_pulse/api/v1/capabilities_controller.rb

@@ -0,0 +1,27 @@
+module RailsPulse
+  module Api
+    module V1
+      # Which installation answered, so a caller can tell one deployment's
+      # numbers from another's before it starts reading them.
+      class CapabilitiesController < BaseController
+        def show
+          render json: {
+            rails_pulse_version: RailsPulse::VERSION,
+            environment: Rails.env.to_s,
+            # Names the installation a response came from, so two profiles
+            # pointed at staging and production cannot be confused.
+            application: application_name
+          }
+        end
+
+        private
+
+        def application_name
+          Rails.application.class.module_parent_name
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end