rails_pulse 0.4.2 → 0.5.0.pre.1

data/config/routes.rb

@@ -37,6 +37,25 @@ RailsPulse::Engine.routes.draw do
     end
   end
 
+  # Read-only JSON API for the rails-pulse CLI, the MCP server and CI, all
+  # authenticated by config.api_token (app/controllers/rails_pulse/api/v1).
+  scope path: "api/v1", module: "api/v1", as: :api_v1 do
+    resources :routes,      only: :index
+    resources :requests,    only: :index
+    resources :queries,     only: :index
+    resources :jobs,        only: :index
+    resources :job_runs,    only: :index
+    resources :deployments, only: :index
+    resources :exceptions,  only: %i[index show]
+
+    # Whether the data is there, rather than a question about the data.
+    get "coverage", to: "coverage#show", as: :coverage
+
+    # Which application, environment and version answered, so results gathered
+    # against staging are not read as production.
+    get "capabilities", to: "capabilities#show", as: :capabilities
+  end
+
   # CSP compliance testing (development/test only)
   if Rails.env.local?
     get "csp_test", to: "csp_test#show", as: :csp_test

data/db/rails_pulse_migrate/20260506000001_create_rails_pulse_exceptions.rb

@@ -32,7 +32,7 @@ class CreateRailsPulseExceptions < ActiveRecord::Migration[7.0]
         t.string   :request_url,     comment: "Nullable — web requests only"
         t.string   :request_method,  comment: "GET, POST, etc."
         t.string   :environment,     comment: "production, staging, etc."
-        t.string   :deploy_sha,       comment: "Captured now even though Pro uses it — cannot backfill later"
+        t.string   :deploy_sha,       comment: "Captured at occurrence time — cannot backfill later"
         t.text     :request_params,   comment: "JSON hash of filtered request params — web requests only"
         t.datetime :occurred_at,      null: false
         t.timestamps

data/db/rails_pulse_migrate/20260921000001_create_rails_pulse_events.rb

@@ -0,0 +1,21 @@
+class CreateRailsPulseEvents < ActiveRecord::Migration[7.0]
+  def change
+    return if table_exists?(:rails_pulse_events)
+
+    create_table :rails_pulse_events do |t|
+      t.string   :kind,        null: false, comment: "What noticed it, e.g. writer_heartbeat"
+      t.string   :subject,                  comment: "Who it is about: host:pid, rule name, job name, exception class"
+      t.string   :outcome,     null: false, comment: "sampled, triggered, clean, insufficient_data, ran"
+      t.decimal  :value,       precision: 15, scale: 6, comment: "The number behind it: requests dropped since the last sample, or the triggered metric value"
+      t.datetime :occurred_at, null: false
+      t.text     :message
+      t.text     :metadata,                 comment: "JSON with the kind-specific detail"
+      t.timestamps
+    end
+
+    add_index :rails_pulse_events, [ :kind, :occurred_at ],
+      name: "index_rp_events_on_kind_and_occurred_at"
+    add_index :rails_pulse_events, [ :kind, :subject, :occurred_at ],
+      name: "index_rp_events_on_kind_subject_and_occurred_at"
+  end
+end

data/db/rails_pulse_schema.rb

@@ -7,7 +7,7 @@ require "rails_pulse/route_indexes" unless defined?(RailsPulse::RouteIndexes)
 RailsPulse::Schema = lambda do |connection|
   adapter = connection.adapter_name.downcase
   # Skip if all tables already exist to prevent conflicts
-  required_tables = [ :rails_pulse_routes, :rails_pulse_queries, :rails_pulse_requests, :rails_pulse_operations, :rails_pulse_jobs, :rails_pulse_job_runs, :rails_pulse_summaries, :rails_pulse_deployments, :rails_pulse_exception_groups, :rails_pulse_exception_occurrences ]
+  required_tables = [ :rails_pulse_routes, :rails_pulse_queries, :rails_pulse_requests, :rails_pulse_operations, :rails_pulse_jobs, :rails_pulse_job_runs, :rails_pulse_summaries, :rails_pulse_deployments, :rails_pulse_exception_groups, :rails_pulse_exception_occurrences, :rails_pulse_events ]
 
   # Check which tables already exist
   existing_tables = required_tables.select { |table| connection.table_exists?(table) }
@@ -249,7 +249,7 @@ RailsPulse::Schema = lambda do |connection|
       t.string   :request_url,     comment: "Nullable — web requests only"
       t.string   :request_method,  comment: "GET, POST, etc."
       t.string   :environment,     comment: "production, staging, etc."
-      t.string   :deploy_sha,       comment: "Captured now even though Pro uses it — cannot backfill later"
+      t.string   :deploy_sha,       comment: "Captured at occurrence time — cannot backfill later"
       t.text     :request_params,   comment: "JSON hash of filtered request params — web requests only"
       t.datetime :occurred_at,      null: false
       t.timestamps
@@ -259,6 +259,24 @@ RailsPulse::Schema = lambda do |connection|
     connection.add_index :rails_pulse_exception_occurrences, :exception_group_id, name: "index_rp_exception_occurrences_on_group_id"
   end
 
+  unless connection.table_exists?(:rails_pulse_events)
+    connection.create_table :rails_pulse_events do |t|
+      t.string   :kind,        null: false, comment: "What noticed it, e.g. writer_heartbeat"
+      t.string   :subject,                  comment: "Who it is about: host:pid, rule name, job name, exception class"
+      t.string   :outcome,     null: false, comment: "sampled, triggered, clean, insufficient_data, ran"
+      t.decimal  :value,       precision: 15, scale: 6, comment: "The number behind it: requests dropped since the last sample, or the triggered metric value"
+      t.datetime :occurred_at, null: false
+      t.text     :message
+      t.text     :metadata,                 comment: "JSON with the kind-specific detail"
+      t.timestamps
+    end
+
+    connection.add_index :rails_pulse_events, [ :kind, :occurred_at ],
+      name: "index_rp_events_on_kind_and_occurred_at"
+    connection.add_index :rails_pulse_events, [ :kind, :subject, :occurred_at ],
+      name: "index_rp_events_on_kind_subject_and_occurred_at"
+  end
+
   # Add indexes to existing tables for efficient aggregation
   unless connection.index_exists?(:rails_pulse_requests, [ :created_at, :route_id ], name: "idx_requests_for_aggregation")
     connection.add_index :rails_pulse_requests, [ :created_at, :route_id ], name: "idx_requests_for_aggregation"

data/exe/rails-pulse

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Runs outside the Rails app: talks to it over the JSON API, so only the CLI
+# is loaded here, never the engine.
+require "rails_pulse/cli/main"
+RailsPulse::CLI::Main.start(ARGV)

data/lib/generators/rails_pulse/base_methods.rb

@@ -15,6 +15,7 @@ module RailsPulse
         rails_pulse_deployments
         rails_pulse_exception_groups
         rails_pulse_exception_occurrences
+        rails_pulse_events
       ].freeze
 
       # Generate next migration number for timestamped migrations

data/lib/generators/rails_pulse/templates/db/rails_pulse_schema.rb

@@ -7,7 +7,7 @@ require "rails_pulse/route_indexes" unless defined?(RailsPulse::RouteIndexes)
 RailsPulse::Schema = lambda do |connection|
   adapter = connection.adapter_name.downcase
   # Skip if all tables already exist to prevent conflicts
-  required_tables = [ :rails_pulse_routes, :rails_pulse_queries, :rails_pulse_requests, :rails_pulse_operations, :rails_pulse_jobs, :rails_pulse_job_runs, :rails_pulse_summaries, :rails_pulse_deployments, :rails_pulse_exception_groups, :rails_pulse_exception_occurrences ]
+  required_tables = [ :rails_pulse_routes, :rails_pulse_queries, :rails_pulse_requests, :rails_pulse_operations, :rails_pulse_jobs, :rails_pulse_job_runs, :rails_pulse_summaries, :rails_pulse_deployments, :rails_pulse_exception_groups, :rails_pulse_exception_occurrences, :rails_pulse_events ]
 
   # Check which tables already exist
   existing_tables = required_tables.select { |table| connection.table_exists?(table) }
@@ -249,7 +249,7 @@ RailsPulse::Schema = lambda do |connection|
       t.string   :request_url,     comment: "Nullable — web requests only"
       t.string   :request_method,  comment: "GET, POST, etc."
       t.string   :environment,     comment: "production, staging, etc."
-      t.string   :deploy_sha,       comment: "Captured now even though Pro uses it — cannot backfill later"
+      t.string   :deploy_sha,       comment: "Captured at occurrence time — cannot backfill later"
       t.text     :request_params,   comment: "JSON hash of filtered request params — web requests only"
       t.datetime :occurred_at,      null: false
       t.timestamps
@@ -259,6 +259,24 @@ RailsPulse::Schema = lambda do |connection|
     connection.add_index :rails_pulse_exception_occurrences, :exception_group_id, name: "index_rp_exception_occurrences_on_group_id"
   end
 
+  unless connection.table_exists?(:rails_pulse_events)
+    connection.create_table :rails_pulse_events do |t|
+      t.string   :kind,        null: false, comment: "What noticed it, e.g. writer_heartbeat"
+      t.string   :subject,                  comment: "Who it is about: host:pid, rule name, job name, exception class"
+      t.string   :outcome,     null: false, comment: "sampled, triggered, clean, insufficient_data, ran"
+      t.decimal  :value,       precision: 15, scale: 6, comment: "The number behind it: requests dropped since the last sample, or the triggered metric value"
+      t.datetime :occurred_at, null: false
+      t.text     :message
+      t.text     :metadata,                 comment: "JSON with the kind-specific detail"
+      t.timestamps
+    end
+
+    connection.add_index :rails_pulse_events, [ :kind, :occurred_at ],
+      name: "index_rp_events_on_kind_and_occurred_at"
+    connection.add_index :rails_pulse_events, [ :kind, :subject, :occurred_at ],
+      name: "index_rp_events_on_kind_subject_and_occurred_at"
+  end
+
   # Add indexes to existing tables for efficient aggregation
   unless connection.index_exists?(:rails_pulse_requests, [ :created_at, :route_id ], name: "idx_requests_for_aggregation")
     connection.add_index :rails_pulse_requests, [ :created_at, :route_id ], name: "idx_requests_for_aggregation"

data/lib/generators/rails_pulse/templates/rails_pulse.rb

@@ -327,22 +327,36 @@ RailsPulse.configure do |config|
   # }
 
   # ====================================================================================================
-  #                                             DEPLOYMENT TRACKING
+  #                                    API TOKENS AND DEPLOYMENT TRACKING
   # ====================================================================================================
-  # Record deployments to display vertical marker lines on performance charts, making it easy
-  # to correlate performance changes with specific releases.
+  # Two tokens authenticate what is not the dashboard, so a credential given to a coding agent
+  # cannot write anything. Both are sent as an `X-Rails-Pulse-Token` header.
   #
-  # API token for the POST /rails_pulse/deployments endpoint.
-  # When set, requests must include an `X-Rails-Pulse-Token` header matching this value.
-  # When nil, the endpoint falls back to the standard dashboard authentication.
+  # api_token reads the JSON API under /rails_pulse/api/v1 — what the `rails-pulse` CLI and the
+  # MCP server your coding agent uses talk to. Every endpoint under it is read-only.
+  #   config.api_token = Rails.application.credentials.dig(:rails_pulse, :api_token)
+  #   config.api_token = ENV["RAILS_PULSE_API_TOKEN"]
   #
-  # Set this in your CI/CD pipeline and store the value in credentials or an environment variable:
-  #   config.deployment_api_token = Rails.application.credentials.dig(:rails_pulse, :deployment_api_token)
-  #   config.deployment_api_token = ENV["RAILS_PULSE_DEPLOYMENT_TOKEN"]
+  # deployment_token records a release through POST /rails_pulse/deployments, which your CI calls.
+  # It is the only credential that endpoint accepts: api_token is refused there.
+  #   config.deployment_token = Rails.application.credentials.dig(:rails_pulse, :deployment_token)
+  #   config.deployment_token = ENV["RAILS_PULSE_DEPLOYMENT_TOKEN"]
   #
-  # Limits: revision ≤ 255 characters, metadata ≤ 4 KB serialized, started_at at most
-  # one hour in the future. Rows beyond max_table_records[:rails_pulse_deployments]
-  # are pruned oldest-first by the cleanup task.
+  # Set both to the same value if you would rather run one credential for both.
+  #
+  # With no api_token the JSON API refuses every request. With no deployment_token the deployments
+  # endpoint refuses every request too; a dashboard login is never accepted in its place. The
+  # rails_pulse:record_deployment and finish_deployment rake tasks need no token. (deployment_api_token
+  # is the pre-0.5 name for deployment_token and still works.)
+  #
+  # Point the CLI and MCP server at this app with `rails-pulse configure`, or set RAILS_PULSE_URL
+  # and RAILS_PULSE_TOKEN in the agent's environment. The MCP server needs `gem "mcp"` in this
+  # app's Gemfile (a development group is enough); Rails Pulse does not pull it into production.
+  #
+  # Deployments draw vertical markers on the charts so a change in performance can be lined up
+  # with the release that caused it. Limits: revision ≤ 255 characters, metadata ≤ 4 KB
+  # serialized, started_at at most one hour in the future. Rows beyond
+  # max_table_records[:rails_pulse_deployments] are pruned oldest-first by the cleanup task.
   #
   # Record a deployment from your CI/CD pipeline:
   #   curl -X POST https://yourapp.com/rails_pulse/deployments \
@@ -356,7 +370,8 @@ RailsPulse.configure do |config|
   # Metadata for the rake task comes from an environment variable, as a JSON object:
   #   RAILS_PULSE_DEPLOYMENT_METADATA='{"environment":"production"}' rake rails_pulse:record_deployment[abc1234]
 
-  # config.deployment_api_token = ENV["RAILS_PULSE_DEPLOYMENT_TOKEN"]
+  # config.api_token = ENV["RAILS_PULSE_API_TOKEN"]
+  # config.deployment_token = ENV["RAILS_PULSE_DEPLOYMENT_TOKEN"]
 
   # ====================================================================================================
   #                                               DATA CLEANUP
@@ -376,6 +391,14 @@ RailsPulse.configure do |config|
   # Time-based retention - delete records older than this period
   config.full_retention_period = 30.days
 
+  # How long rows in rails_pulse_events are kept. The background writer's
+  # heartbeats are pruned after a day regardless.
+  config.event_retention_period = 90.days
+
+  # Event kinds exempt from event_retention_period — for rows a writer updates
+  # in place rather than appends.
+  config.event_retention_exempt_kinds = []
+
   # Count-based retention - maximum records to keep per table
   # After time-based cleanup, if tables still exceed these limits,
   # the oldest remaining records will be deleted to stay under the limit

data/lib/rails_pulse/cleanup_service.rb

@@ -29,6 +29,7 @@ module RailsPulse
 
       perform_time_based_cleanup
       perform_count_based_cleanup
+      perform_event_cleanup
       perform_summary_cleanup
 
       log_cleanup_summary
@@ -116,6 +117,22 @@ module RailsPulse
       end
     end
 
+    # event_retention_exempt_kinds are rows a writer updates in place, which
+    # must survive so "last ran" never becomes "never ran"
+    def perform_event_cleanup
+      return unless @config.event_retention_period
+      return unless RailsPulse::Event.table_available?
+
+      cutoff_time = [ @config.event_retention_period.ago, 1.hour.ago ].min
+      run_stage(:time_based, :events) do
+        delete_in_batches(
+          RailsPulse::Event
+            .where.not(kind: @config.event_retention_exempt_kinds)
+            .where(occurred_at: ...cutoff_time)
+        )
+      end
+    end
+
     def perform_count_based_cleanup
       return unless @config.max_table_records&.any?
 
@@ -313,37 +330,26 @@ module RailsPulse
       RailsPulse::ExceptionOccurrence.where.not(exception_group_id: preserved_ids)
     end
 
-    # Prune oldest non-preserved, non-ignored groups when over the configured cap.
-    # Child occurrences must be deleted first — there is no ON DELETE CASCADE on the FK.
+    # Prune the oldest deletable groups when over the configured cap. Preserved
+    # and ignored groups are outside the cap: counting them would make a cap
+    # that they alone fill impossible to satisfy, so every run would trim the
+    # deletable groups for no gain (decision 0017). Child occurrences must be
+    # deleted first — there is no ON DELETE CASCADE on the FK.
     def cleanup_exception_groups_by_count
       max_records = @config.max_table_records[:rails_pulse_exception_groups]
       return 0 unless max_records
 
-      current_count = RailsPulse::ExceptionGroup.count
-      return 0 if current_count <= max_records
-
-      overage = current_count - max_records
       scope = RailsPulse::ExceptionGroup.where(preserve: false).where.not(status: "ignored")
-      # Only delete as many as the deletable population allows — if ignored/preserved
-      # groups dominate, we delete what we can and log when the cap cannot be met.
-      deletable_count = scope.count
-      records_to_delete = [ overage, deletable_count ].min
-      return 0 if records_to_delete <= 0
+      overage = scope.count - max_records
+      return 0 if overage <= 0
 
-      deleted = delete_parents_in_batches(
+      delete_parents_in_batches(
         scope,
         order_column: :last_seen_at,
         children: RailsPulse::ExceptionOccurrence,
         foreign_key: :exception_group_id,
-        limit: records_to_delete
+        limit: overage
       )
-
-      if overage > deletable_count
-        RailsPulse.logger.warn("[RailsPulse] Exception group cap #{max_records} cannot be met: " \
-          "#{current_count - deleted} remain (#{current_count - deletable_count} are preserved/ignored)")
-      end
-
-      deleted
     end
 
     # Delete groups whose last occurrence was removed — the orphan check and

data/lib/rails_pulse/cli/agent_files/agents.md

@@ -0,0 +1,87 @@
+# Rails Pulse — Agent Integration
+
+Rails Pulse gives AI coding agents read access to a Rails application's performance data: requests, SQL queries, background jobs, exceptions and deployments, all from the application's own database. Two interfaces, one token.
+
+## MCP server
+
+```
+rails-pulse mcp
+```
+
+The server needs the `mcp` gem, which Rails Pulse does not depend on: add `gem "mcp", "~> 1.0"` to the application's Gemfile (a development group is enough), or `gem install mcp` when running `rails-pulse` outside Bundler.
+
+**Claude Code** (`~/.claude.json`):
+```json
+{
+  "mcpServers": {
+    "rails-pulse": {
+      "command": "rails-pulse",
+      "args": ["mcp"],
+      "env": {
+        "RAILS_PULSE_URL": "https://myapp.com",
+        "RAILS_PULSE_TOKEN": "your-token"
+      }
+    }
+  }
+}
+```
+
+**Cursor** (`.cursor/mcp.json`):
+```json
+{
+  "mcpServers": {
+    "rails-pulse": { "command": "rails-pulse", "args": ["mcp"] }
+  }
+}
+```
+
+### Tools
+
+All tools are read-only. Each returns a `summary` and `next_steps`.
+
+| Tool | Purpose |
+|------|---------|
+| `rails_pulse_routes` | Discover endpoints with request volume, latency and errors |
+| `rails_pulse_slow_requests` | Slowest endpoints for a period |
+| `rails_pulse_coverage` | What has been recorded, how recently, and any collection gaps |
+| `rails_pulse_errors` | Recent errors grouped by endpoint |
+| `rails_pulse_exceptions` | Exception groups with status, count, location and latest message |
+| `rails_pulse_exception` | One group's recent occurrences with backtraces, request and params |
+| `rails_pulse_endpoint` | Deep performance profile of one endpoint |
+| `rails_pulse_queries` | Most expensive SQL queries with N+1 detection |
+| `rails_pulse_jobs` | Background job health and recent failures |
+| `rails_pulse_deployments` | Recent deployments with revision, timing and metadata |
+
+Every tool that takes a `period` also takes `since` and `until` as ISO 8601 timestamps, read as UTC when no zone is given, and echoes the bounds it measured back as `window`. `period` itself is only `last_hour`, `last_24_hours` or `last_7_days` (plus `all` on `rails_pulse_exceptions`); any other window is `since`/`until`. Use them to compare two fixed windows — the 24 hours before a release against the 24 hours after — rather than a relative period that moves between calls.
+
+## CLI
+
+The `rails-pulse` CLI works without MCP. Append `--json` for structured output.
+
+| Command | Description |
+|---------|-------------|
+| `rails-pulse routes list` | Tracked routes (`--since` adds request stats) |
+| `rails-pulse requests list` | Recorded requests with status and time filters |
+| `rails-pulse queries list` | SQL queries (`--since` adds timing stats) |
+| `rails-pulse jobs list` | Background jobs: lifetime stats, or one window's with `--since` / `--until` |
+| `rails-pulse job_runs list` | Individual job runs with errors |
+| `rails-pulse exceptions list` | Exception groups with status and occurrence counts |
+| `rails-pulse exceptions show ID` | One group with backtraces and recent occurrences |
+| `rails-pulse deployments list` | Recorded deployments, most recent first |
+| `rails-pulse coverage show` | What has been recorded, how recently, and any collection gaps |
+
+Common flags on every list command: `--limit N` (1 to 500, default 25), `--offset N`, `--json`, `--since TIME` / `--until TIME` (ISO 8601; no zone means UTC).
+
+## Authentication
+
+Set `RAILS_PULSE_URL` and `RAILS_PULSE_TOKEN` (the application's `config.api_token`), or run `rails-pulse configure` to write `~/.rails-pulse`. That token is read-only; recording a deployment needs `config.deployment_token`, which these tools do not carry.
+
+## Investigation pattern
+
+1. Pin the time window to a deployment (`rails_pulse_deployments`)
+2. Identify slow or failing endpoints (`rails_pulse_slow_requests`); resolve names with `rails_pulse_routes`
+3. Profile the suspect endpoint (`rails_pulse_endpoint`)
+4. Check errors (`rails_pulse_errors`)
+5. Inspect SQL and jobs (`rails_pulse_queries`, `rails_pulse_jobs`)
+6. Correlate with source code: pass the endpoint's `route_id` to `rails_pulse_queries` for the SQL inside it and the file and line each query came from
+7. Fix, deploy, and re-check the same endpoint

data/lib/rails_pulse/cli/agent_files/claude_skill.md

@@ -0,0 +1,165 @@
+---
+name: rails-pulse
+description: Investigate Rails application performance with Rails Pulse. Use when asked about slow endpoints, regressions after a deploy, expensive or N+1 SQL, error rates, failing background jobs, or whether a performance fix worked. Prefers the rails_pulse_* MCP tools; falls back to the rails-pulse CLI.
+---
+
+# Rails Pulse
+
+Rails Pulse records every request, SQL query, background job and exception of a Rails application in the application's own database. This skill gives you read access to that data so you can find what is slow, why, and whether a change fixed it. Nothing here can modify the application.
+
+## When to use it
+
+- Investigating a performance complaint or a slow endpoint
+- Diagnosing a regression after a deployment
+- Finding expensive or N+1 SQL queries
+- Investigating an increased error rate
+- Analysing background job failures or slowness
+- Validating whether a performance fix worked
+
+## Interfaces
+
+### MCP tools (preferred when available)
+
+All tools are read-only. Each returns a `summary` and `next_steps`.
+
+| Tool | Purpose |
+|------|---------|
+| `rails_pulse_routes` | Discover endpoints: request volume, latency and errors per route |
+| `rails_pulse_slow_requests` | The slowest endpoints for a period |
+| `rails_pulse_coverage` | What has been recorded, how recently, and any collection gaps |
+| `rails_pulse_errors` | Recent 4xx/5xx responses grouped by endpoint |
+| `rails_pulse_exceptions` | Exception groups with status, occurrence count, location and latest message |
+| `rails_pulse_exception` | One group's recent occurrences with full backtraces, request, params and deploy SHA |
+| `rails_pulse_endpoint` | Deep profile of one endpoint |
+| `rails_pulse_queries` | Most expensive SQL queries, with N+1 detection |
+| `rails_pulse_jobs` | Background job health and recent failures with error classes |
+| `rails_pulse_deployments` | Recent deployments with revision, start and finish time, and metadata |
+
+### CLI
+
+The `rails-pulse` executable ships with the gem. Add `--json` for structured output.
+
+| Command | Purpose |
+|---------|---------|
+| `rails-pulse routes list --json` | Tracked routes (add `--since` for stats) |
+| `rails-pulse requests list --json` | Recorded requests with status and time filters |
+| `rails-pulse queries list --json` | SQL queries (add `--since` for timing stats) |
+| `rails-pulse jobs list --json` | Background jobs: lifetime stats, or one window's with `--since` / `--until` |
+| `rails-pulse job_runs list --json` | Individual job runs with error class and message |
+| `rails-pulse exceptions list --json` | Exception groups with status, count, location and message |
+| `rails-pulse exceptions show ID --json` | One group with backtraces, request, params and deploy SHA |
+| `rails-pulse deployments list --json` | Recorded deployments, most recent first |
+| `rails-pulse coverage show --json` | What has been recorded, how recently, and any collection gaps |
+
+## Investigation workflow
+
+### 1. Establish the time period
+
+Check recent deployments first; a regression usually lines up with one.
+
+```
+rails_pulse_deployments(period: "last_7_days")
+rails-pulse deployments list --json
+```
+
+Use a deployment's `started_at` as `since` for the tools below, then compare against the same length of time before it.
+
+### 2. Identify affected endpoints
+
+```
+rails_pulse_slow_requests(period: "last_24_hours", limit: 10)
+rails_pulse_routes(search: "checkout", period: "last_7_days")
+rails-pulse requests list --limit 50 --json
+```
+
+### 3. Profile the suspect endpoint
+
+```
+rails_pulse_endpoint(endpoint: "CheckoutController#create", period: "last_7_days")
+rails-pulse requests list --since 2026-06-01T00:00:00Z --json
+```
+
+### 4. Check errors
+
+```
+rails_pulse_errors(period: "last_24_hours", status: "5xx")
+rails-pulse requests list --status 5xx --since 2026-06-01T00:00:00Z --json
+```
+
+### 5. Inspect SQL and background jobs
+
+```
+rails_pulse_queries(period: "last_24_hours", sort: "total_duration")
+rails_pulse_queries(n_plus_one_only: true)
+rails_pulse_jobs(period: "last_24_hours")
+rails-pulse queries list --since 2026-06-01T00:00:00Z --json
+rails-pulse job_runs list --status failed --json
+```
+
+### 6. Correlate with source code
+
+Pass the endpoint's `route_id` to `rails_pulse_queries` to see only the SQL that ran inside it,
+with `source_locations` naming the file and line each query was issued from.
+
+```
+rails_pulse_queries(route: 42, period: "last_24_hours")
+```
+
+Start at those locations rather than searching for the SQL. Look for N+1 queries, missing
+indexes, expensive work in the request path, unnecessary serialization and missing caching.
+
+### 7. Fix, then validate
+
+After the fix is deployed, re-check the same endpoint over the period since the deploy.
+
+```
+rails_pulse_deployments(period: "last_24_hours")
+rails_pulse_endpoint(endpoint: "CheckoutController#create", period: "last_hour")
+```
+
+To show a change rather than a snapshot, measure the same endpoint over two fixed windows
+either side of the release. Every windowed tool takes `since` and `until` as ISO 8601
+timestamps, read as UTC when no zone is given, and echoes the bounds it used back as `window`.
+
+```
+rails_pulse_endpoint(endpoint: "CheckoutController#create", since: "2026-09-24T12:00:00Z", until: "2026-09-25T12:00:00Z")
+rails_pulse_endpoint(endpoint: "CheckoutController#create", since: "2026-09-25T12:00:00Z", until: "2026-09-26T12:00:00Z")
+```
+
+Use the deploy time as the boundary, and exclude the minutes around it when a rolling deploy
+makes them a mix of both versions.
+
+## Guidelines
+
+- **SQL is not always the cause.** External API calls, serialization, view rendering and application logic slow requests too.
+- **Use more than one tool.** Cross-reference latency with error rates, SQL timing and job performance before concluding.
+- **Orient once before investigating.** `rails_pulse_coverage` names the application, environment and version you are querying. Call it first, so findings are attributed to the installation that actually produced them.
+- **Confirm the data exists before reporting an all-clear.** An empty result means nothing was recorded, which only means nothing happened when collection was healthy over that window. Call `rails_pulse_coverage` before concluding a period was clean, and say so when it flags a gap, stale summaries or a kind that is not tracked.
+- **Check the error rate.** A fast endpoint with a high error rate may be failing early rather than performing well.
+- **Read percentiles, not just averages.** A low average with a high p95 or p99 means intermittent trouble.
+- **Weigh request volume.** A slow endpoint nobody calls may not be worth the work.
+- **Job figures cover the window.** `rails_pulse_jobs` reads them from summaries plus the runs not yet summarized. p95 and p99 are given only when one summary period holds the whole window; otherwise they are null and `note` says why, so compare averages and failure rates instead.
+- **Check what the percentiles covered.** `rails_pulse_endpoint` computes them over the most recent requests it sampled, not the whole window. When `sampled_requests` is below `request_count` it says so in `latency.computed_over`; narrow the window until the two match before comparing percentiles across windows.
+
+## Authentication
+
+The CLI and MCP server read credentials from environment variables or `~/.rails-pulse`. The token is `config.api_token` in the application's Rails Pulse initializer. It is read-only: recording a deployment needs `config.deployment_token`, which these tools do not carry.
+
+```
+RAILS_PULSE_URL=https://myapp.com
+RAILS_PULSE_TOKEN=my-secret-token
+RAILS_PULSE_MOUNT_PATH=/rails_pulse   # optional, default /rails_pulse
+```
+
+```yaml
+# ~/.rails-pulse
+url: https://myapp.com
+token: my-secret-token
+mount_path: /rails_pulse
+```
+
+Interactive setup: `rails-pulse configure`.
+
+## CLI reference
+
+List commands accept `--limit N` (1 to 500, default 25), `--offset N` and `--json`. Every list command also accepts `--since TIME` and `--until TIME` as ISO 8601; a time with no zone is read as UTC. JSON output is `{ "data": [...], "meta": { "total", "limit", "offset" } }`; page with `--offset`.

data/lib/rails_pulse/cli/base_command.rb

@@ -0,0 +1,37 @@
+require "thor"
+require_relative "config"
+require_relative "client"
+
+module RailsPulse
+  module CLI
+    class BaseCommand < Thor
+      # A usage error (unknown command, missing argument, bad flag) exits 1,
+      # so a script or CI step running the CLI can tell it failed.
+      def self.exit_on_failure?
+        true
+      end
+
+      # A mistyped flag is an error rather than silently ignored, so
+      # `--limt 5` does not quietly return the default page.
+      check_unknown_options!
+
+      no_commands do
+        def with_error_handling
+          yield
+        rescue RailsPulse::CLI::Config::ConfigError => e
+          say "Error: #{e.message}.", :red
+          exit 1
+        rescue RailsPulse::CLI::Client::ApiError => e
+          say "API error: #{e.message}", :red
+          exit 1
+        end
+      end
+
+      private
+
+      def client
+        @client ||= Client.new
+      end
+    end
+  end
+end