maquina-generators 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ca10b8ebcd86d74709ad16f64e6366457b53fc9a55da72a997f9084c5819d267
-  data.tar.gz: 3147bb48486e66744e0b2af74ab06368a7b6e782a77b8c3946069f6c6178d76f
+  metadata.gz: 79618453431401c828cd9f89037c0111810fe7ff1b3328986fb99fea3282e010
+  data.tar.gz: e33ebfe0accac9a78432b1548648fce1ca8de0176370673f84665a7928eefeef
 SHA512:
-  metadata.gz: 6d3ab8cb8656f06fa0c1ced220473bf6bfc76c7931ea70133a91405fdc28b866d2f840f35ced6f9056a382b812a4c03898e2b94ec40f7ab76c39297900789b39
-  data.tar.gz: 7c5cec9099144f5a9216afe62df79d5c5561d23886accd332017d2e491bf29fe25d787129288f743ec0784d19ff9c85cfe15274f00976c60c554fe018d84007e
+  metadata.gz: c5c84a544b6295a6dfd32833b8d65febdb7e9d1de3e79da20c67e55cc7d5102c585a61b76f640ae3eb01cd1e59a57172c7930a90ea86f47bbcf7e49583709cf6
+  data.tar.gz: 27361ba6b7f8c51778eee636c43715ce8aa6dcce88c5a6c929c4715d4980b27db240fdbaba8139b3859d920976ad8fc1655881cf965c891099063c63cf88b635

data/README.md

@@ -10,13 +10,13 @@ A collection of Rails generators from the Maquina umbrella. Each generator produ
 
 #### What it generates
 
-- **Models:** `User`, `Session`, `EmailVerification`, `Current`
+- **Models:** `Account`, `User`, `Session`, `EmailVerification`, `Current`
 - **Controllers:** Sign-in/sign-up flows with email code verification
 - **Views:** Minimal, responsive forms styled with Tailwind CSS
 - **Mailer:** Verification code emails (HTML + text)
 - **Job:** Cleanup job for expired sessions and verifications
 - **Locale files:** English and Spanish translations
-- **Migrations:** 3 migrations (users, sessions, email_verifications)
+- **Migrations:** 4 migrations (accounts, users, sessions, email_verifications)
 - **Test helper:** `sign_in_as(user)` and `sign_out` for integration tests
 
 #### Installation

data/lib/generators/maquina/app/app_generator.rb

@@ -20,7 +20,16 @@ module Maquina
         content = File.read(gemfile_path)
 
         remove_gems = ["rubocop-rails-omakase"]
-        dev_gems = {"brakeman" => nil, "bundle-audit" => nil, "letter_opener" => nil, "standard" => nil}
+        # standard >= 1.54: avoids the inoperative placeholder releases
+        # (1.34.0.1 / 1.35.0.1) whose too-loose `rubocop ~> 1.62` requirement
+        # makes bundler backtrack onto them and pair them with an incompatible
+        # rubocop, so the `standard` binary refuses to run.
+        #
+        # standard.rb runs through the generated .rubocop.yml (see
+        # create_config_files) — that file is standard.rb's runner bridge, not
+        # custom RuboCop rules, so it ships even though guidance says "no
+        # .rubocop.yml".
+        dev_gems = {"brakeman" => nil, "bundle-audit" => nil, "letter_opener" => nil, "standard" => ">= 1.54"}
         runtime_gems = {"rails-i18n" => nil, "maquina-components" => nil}
         production_gems = {"aws-sdk-s3" => nil}
 
@@ -28,22 +37,19 @@ module Maquina
           gsub_file "Gemfile", /^\s*gem\s+["']#{gem_name}["'].*\n/, ""
         end
 
-        dev_gems.each do |gem_name, _|
-          unless content.include?("gem \"#{gem_name}\"")
-            append_to_file "Gemfile", "\ngem \"#{gem_name}\", group: :development\n"
-          end
+        dev_gems.each do |gem_name, version|
+          next if content.include?("gem \"#{gem_name}\"")
+          append_to_file "Gemfile", "\n#{gem_line(gem_name, version, group: :development)}\n"
         end
 
-        runtime_gems.each do |gem_name, _|
-          unless content.include?("gem \"#{gem_name}\"")
-            append_to_file "Gemfile", "\ngem \"#{gem_name}\"\n"
-          end
+        runtime_gems.each do |gem_name, version|
+          next if content.include?("gem \"#{gem_name}\"")
+          append_to_file "Gemfile", "\n#{gem_line(gem_name, version)}\n"
         end
 
-        production_gems.each do |gem_name, _|
-          unless content.include?("gem \"#{gem_name}\"")
-            append_to_file "Gemfile", "\ngem \"#{gem_name}\", group: :production\n"
-          end
+        production_gems.each do |gem_name, version|
+          next if content.include?("gem \"#{gem_name}\"")
+          append_to_file "Gemfile", "\n#{gem_line(gem_name, version, group: :production)}\n"
         end
 
         return unless rails_app?
@@ -255,7 +261,45 @@ module Maquina
         end
       end
 
-      # 18. Run all migrations
+      # 18. Restore database.yml from its example in bin/setup. config/database.yml
+      #     is gitignored (it differs per environment), so a fresh clone has only
+      #     the committed example — bin/setup must copy it before db:prepare.
+      def configure_bin_setup
+        setup_file = File.join(destination_root, "bin/setup")
+        return unless File.exist?(setup_file)
+        return if File.read(setup_file).include?("config/database.yml.example")
+
+        inject_into_file "bin/setup",
+          after: %r{system\("bundle check"\) \|\| system!\("bundle install"\)\n} do
+          <<~RUBY.indent(2)
+
+            # config/database.yml is gitignored; restore it from the committed example
+            unless File.exist?("config/database.yml")
+              puts "\\n== Copying config/database.yml =="
+              FileUtils.cp "config/database.yml.example", "config/database.yml"
+            end
+          RUBY
+        end
+      end
+
+      # 19. Restore database.yml from its example in CI. Without it, the test job
+      #     boots with no database.yml and every Rails task fails. Only touched
+      #     when the host app already has a GitHub Actions workflow.
+      def configure_ci
+        ci_file = File.join(destination_root, ".github/workflows/ci.yml")
+        return unless File.exist?(ci_file)
+        return if File.read(ci_file).include?("config/database.yml.example")
+
+        inject_into_file ".github/workflows/ci.yml",
+          before: /^      - name: Run tests$/ do
+          <<~YAML.indent(6)
+            - name: Prepare database config
+              run: cp config/database.yml.example config/database.yml
+          YAML
+        end
+      end
+
+      # 20. Run all migrations
       def run_migrations
         return unless rails_app?
 
@@ -264,7 +308,7 @@ module Maquina
         end
       end
 
-      # 19. Post-install message
+      # 21. Post-install message
       def show_post_install
         say ""
         say "=" * 60, :green
@@ -298,6 +342,13 @@ module Maquina
 
       private
 
+      def gem_line(name, version, group: nil)
+        line = "gem \"#{name}\""
+        line << ", \"#{version}\"" if version
+        line << ", group: :#{group}" if group
+        line
+      end
+
       def rails_app?
         File.exist?(File.join(destination_root, "bin/rails"))
       end

data/lib/generators/maquina/app/templates/.rubocop.yml

@@ -1,3 +1,9 @@
+# standard.rb's runner bridge, not custom RuboCop rules.
+#
+# This is the entry point RuboCop (and editors/LSP) need to run the Standard
+# ruleset — all style comes from the `standard` gem via config/base.yml below.
+# Keep this file even though general guidance says "no .rubocop.yml": for
+# standard.rb this IS the runner config, not a custom rule set.
 require:
   - standard
 

data/lib/generators/maquina/mission_control_jobs/templates/app/views/mission_control/jobs/jobs/_general_information.html.erb

@@ -7,7 +7,7 @@
     <div class="space-y-4">
       <div>
         <span class="text-sm text-muted-foreground">Arguments</span>
-        <div class="mt-1 text-sm font-mono text-foreground break-words"><%= job_arguments(job) %></div>
+        <div class="mt-1 text-sm font-mono text-foreground break-words overflow-wrap-anywhere"><%= job_arguments(job) %></div>
       </div>
 
       <div>

data/lib/generators/maquina/mission_control_jobs/templates/app/views/mission_control/jobs/jobs/failed/_job.html.erb

@@ -1,7 +1,7 @@
 <%= render "components/table/cell" do %>
-  <div>
+  <div class="min-w-0">
     <%= link_to failed_job_error(job), application_job_path(@application, job.job_id, anchor: "error"),
-        class: "text-sm text-foreground hover:text-primary transition-colors" %>
+        class: "block text-sm text-foreground hover:text-primary transition-colors break-words overflow-wrap-anywhere line-clamp-2" %>
     <div class="text-xs text-muted-foreground mt-1"><%= time_distance_in_words_with_title(job.failed_at) %> ago</div>
   </div>
 <% end %>

data/lib/generators/maquina/mission_control_jobs/templates/app/views/mission_control/jobs/shared/_job.html.erb

@@ -12,7 +12,7 @@
   <% end %>
   <%= render "components/table/cell" do %>
     <% if job.serialized_arguments.present? %>
-      <span class="text-xs font-mono text-muted-foreground"><%= job_arguments(job) %></span>
+      <span class="block min-w-0 text-xs font-mono text-muted-foreground break-words overflow-wrap-anywhere line-clamp-2"><%= job_arguments(job) %></span>
     <% end %>
   <% end %>
   <%= render "components/table/cell" do %>

data/lib/generators/maquina/solid_errors/USAGE

@@ -7,9 +7,33 @@ Description:
   Authentication tries Rails credentials (backstage.username/password)
   first, then falls back to environment variables.
 
+  Regardless of options, ApplicationJob is patched to tag reported errors
+  with the job class, arguments, and id, so background-job failures appear
+  in the Solid Errors dashboard with replayable context.
+
+  With --agent, it also generates read-only AI-agent triage tooling: query
+  and triage objects over the errors store (with a redaction pass), a
+  bin/failures runner, and a stdio MCP server (bin/failures-mcp, gem "mcp").
+  The agent tooling never writes — resolution stays in the dashboards.
+
+  With --mcp-http (implies --agent), it additionally generates an
+  MCP-over-HTTP endpoint at <prefix>/failures/mcp, behind the same backstage
+  Basic Auth as the dashboards, so a developer can query a DEPLOYED app from
+  their machine over HTTPS. It self-disables until backstage credentials are
+  set. It serves redacted-but-sensitive data over the internet, so enable it
+  only where intended and put it behind an IP allowlist/VPN.
+
+  To query a deployed app without exposing HTTP, run the stdio server where the
+  errors DB lives and tunnel its stdio (the post-install prints ssh/docker/kamal
+  examples), or copy storage/<env>_errors.sqlite3 down for offline analysis.
+
 Examples:
   rails g maquina:solid_errors --prefix /admin
 
   rails g maquina:solid_errors --prefix /backstage \
     --user-env-var ADMIN_USER \
     --password-env-var ADMIN_PASSWORD
+
+  rails g maquina:solid_errors --prefix /admin --agent
+
+  rails g maquina:solid_errors --prefix /admin --mcp-http

data/lib/generators/maquina/solid_errors/solid_errors_generator.rb

@@ -13,6 +13,10 @@ module Maquina
         desc: "Environment variable for HTTP auth password"
       class_option :copy_views, type: :boolean, default: true,
         desc: "Copy custom Solid Errors views to the host app"
+      class_option :agent, type: :boolean, default: false,
+        desc: "Generate read-only AI-agent triage tooling (bin/failures + stdio MCP server)"
+      class_option :mcp_http, type: :boolean, default: false,
+        desc: "Also expose the MCP server over HTTP behind backstage auth (implies --agent; internet-exposed)"
       class_option :quiet, type: :boolean, default: false,
         desc: "Suppress post-install instructions"
 
@@ -36,25 +40,62 @@ module Maquina
           "config/initializers/solid_errors.rb"
       end
 
-      # 4. Add gem to Gemfile
+      # 4. Enrich job failures with job context (always — benefits the dashboard
+      #    too, not just the agent). On Solid Queue >= 1.0.2 a failed job's
+      #    exception already flows to the Rails error reporter that Solid Errors
+      #    subscribes to; this only attaches the job class/arguments/id to that
+      #    report so a job failure is distinguishable and replayable.
+      def configure_application_job
+        job_path = "app/jobs/application_job.rb"
+        full_path = File.join(destination_root, job_path)
+        return unless File.exist?(full_path)
+        return if File.read(full_path).include?("Rails.error.set_context")
+
+        inject_into_class job_path, "ApplicationJob", <<~RUBY
+          # Attach job context to errors reported to Rails.error so background-job
+          # failures are distinguishable from request failures in Solid Errors,
+          # and carry replayable arguments. Sets context only and lets Solid
+          # Queue's built-in reporting forward the exception (reported once).
+          #
+          # If your Solid Queue version does not propagate this context to its
+          # report, fall back to rescuing in the block, reporting explicitly with
+          # `Rails.error.report(e, handled: false)`, and RE-RAISING (re-raising is
+          # required: it preserves the failed_execution record and retries).
+          around_perform do |job, block|
+            Rails.error.set_context(
+              active_job: job.class.name,
+              arguments: job.arguments,
+              job_id: job.job_id,
+              queue_name: job.queue_name
+            )
+            block.call
+          end
+        RUBY
+      end
+
+      # 5. Add gem to Gemfile
       def add_gem
         gemfile_path = File.join(destination_root, "Gemfile")
-        if File.exist?(gemfile_path)
-          content = File.read(gemfile_path)
-          unless content.include?('gem "solid_errors"')
-            append_to_file "Gemfile", "\ngem \"solid_errors\"\n"
-          end
+        return unless File.exist?(gemfile_path)
+
+        content = File.read(gemfile_path)
+        unless content.include?('gem "solid_errors"')
+          append_to_file "Gemfile", "\ngem \"solid_errors\"\n"
+        end
+
+        if agent? && !content.include?('gem "mcp"')
+          append_to_file "Gemfile", "\ngem \"mcp\"\n"
         end
       end
 
-      # 5. Routes
+      # 6. Routes
       def add_route
         mount_path = "#{options[:prefix]}/solid_errors"
 
         route "mount SolidErrors::Engine, at: \"#{mount_path}\""
       end
 
-      # 6. Admin navigation
+      # 7. Admin navigation
       def create_admin_navigation
         nav_path = "app/views/layouts/_admin_navigation.html.erb"
         return if File.exist?(File.join(destination_root, nav_path))
@@ -62,13 +103,13 @@ module Maquina
         template "app/views/layouts/_admin_navigation.html.erb.tt", nav_path
       end
 
-      # 7. Layout
+      # 8. Layout
       def copy_layout
         copy_file "app/views/layouts/solid_errors/application.html.erb",
           "app/views/layouts/solid_errors/application.html.erb"
       end
 
-      # 8. Stimulus controllers
+      # 9. Stimulus controllers
       def copy_stimulus_controllers
         copy_file "app/javascript/controllers/clipboard_controller.js",
           "app/javascript/controllers/clipboard_controller.js"
@@ -76,7 +117,7 @@ module Maquina
           "app/javascript/controllers/backtrace_filter_controller.js"
       end
 
-      # 9. Custom views
+      # 10. Custom views
       def copy_views
         return unless options[:copy_views]
 
@@ -85,7 +126,36 @@ module Maquina
         end
       end
 
-      # 10. Bundle install
+      # 11. AI-agent triage tooling (opt-in). Read-only query/triage layer over
+      #     the errors store, a bin/ runner, and a stdio MCP server. Resolution
+      #     stays a human action in the Backstage dashboards.
+      def create_agent_files
+        return unless agent?
+
+        agent_files.each do |file|
+          copy_file file, file
+        end
+
+        copy_file "bin/failures", "bin/failures"
+        copy_file "bin/failures-mcp", "bin/failures-mcp"
+        chmod "bin/failures", 0o755
+        chmod "bin/failures-mcp", 0o755
+      end
+
+      # 12. MCP-over-HTTP endpoint (opt-in, internet-exposed). Mounts the same
+      #     read-only tool surface behind the existing backstage Basic Auth so a
+      #     developer can query a deployed app's failures from their machine.
+      def create_mcp_http_controller
+        return unless options[:mcp_http]
+
+        template "app/controllers/failures_mcp_controller.rb.tt",
+          "app/controllers/failures_mcp_controller.rb"
+
+        route %(match "#{options[:prefix]}/failures/mcp", ) +
+          %(to: "failures_mcp#handle", via: %i[get post delete])
+      end
+
+      # 13. Bundle install
       def run_bundle_install
         return unless rails_app?
 
@@ -94,7 +164,7 @@ module Maquina
         end
       end
 
-      # 11. Post-install message
+      # 14. Post-install message
       def show_post_install
         return if options[:quiet]
 
@@ -113,10 +183,59 @@ module Maquina
         say "      password: your_password"
         say "  - Or set ENV vars: #{options[:user_env_var]}, #{options[:password_env_var]}"
         say ""
+        say "Job failures: app/jobs/application_job.rb now tags reported errors with", :yellow
+        say "  job class, arguments, and id so background-job failures show up in the"
+        say "  Solid Errors dashboard with replayable context (Solid Queue >= 1.0.2)."
+        say ""
+
+        show_agent_post_install if agent?
+        show_mcp_http_post_install if options[:mcp_http]
       end
 
       private
 
+      def agent?
+        options[:agent] || options[:mcp_http]
+      end
+
+      def show_agent_post_install
+        say "AI-agent triage tooling (read-only):", :green
+        say ""
+        say "  bin/failures overview                 # unresolved errors as JSON"
+        say "  bin/failures top [limit]              # most frequent unresolved"
+        say "  bin/failures exception <fingerprint>  # full detail + backtrace"
+        say ""
+        say "  Register the local stdio MCP server with Claude Code (app root):", :yellow
+        say "    claude mcp add failures -- bin/failures-mcp"
+        say ""
+        say "  Query a DEPLOYED app from your machine (server runs where the", :yellow
+        say "  errors DB lives — pick what matches your deploy):"
+        say "    ssh:    claude mcp add failures -- ssh user@host 'cd /app && bin/failures-mcp'"
+        say "    docker: claude mcp add failures -- ssh user@host 'docker exec -i <container> bin/failures-mcp'"
+        say "    kamal:  claude mcp add failures -- kamal app exec -i --reuse \"bin/failures-mcp\""
+        say "    offline: copy storage/production_errors.sqlite3 down, run bin/failures locally"
+        say ""
+        say "  Review app/agents/error_redactor.rb — it masks sensitive keys", :yellow
+        say "  (passwords, tokens, email, ...) before any data reaches the agent."
+        say ""
+      end
+
+      def show_mcp_http_post_install
+        say "MCP-over-HTTP endpoint (internet-exposed, read-only):", :green
+        say ""
+        say "  Mounted at #{options[:prefix]}/failures/mcp behind backstage Basic Auth."
+        say "  It self-disables (503) until backstage credentials are set."
+        say ""
+        say "  Register from your machine:", :yellow
+        say "    claude mcp add --transport http failures \\"
+        say "      https://yourapp.com#{options[:prefix]}/failures/mcp \\"
+        say "      --header \"Authorization: Basic $(echo -n user:pass | base64)\""
+        say ""
+        say "  SECURITY: this serves redacted-but-sensitive failure data over the", :red
+        say "  internet. Enable only where intended and put it behind an IP allowlist/VPN."
+        say ""
+      end
+
       def rails_app?
         File.exist?(File.join(destination_root, "bin/rails"))
       end
@@ -127,6 +246,13 @@ module Maquina
           File.join("app/views/solid_errors", file)
         end
       end
+
+      def agent_files
+        agents_dir = File.join(self.class.source_root, "app/agents")
+        Dir.glob("**/*.rb", base: agents_dir).map do |file|
+          File.join("app/agents", file)
+        end
+      end
     end
   end
 end

data/lib/generators/maquina/solid_errors/templates/app/agents/error_redactor.rb

@@ -0,0 +1,34 @@
+# Redacts sensitive values out of error context and job arguments before they
+# leave the query layer for an AI agent (or any log). Job arguments and request
+# context routinely carry passwords, tokens, and PII; this is the one place that
+# stops them from reaching the agent.
+#
+# Tune SENSITIVE_KEY_PATTERN for your app. Keys that match are masked; everything
+# else passes through untouched. Nested hashes and arrays are walked recursively.
+class ErrorRedactor
+  SENSITIVE_KEY_PATTERN = /pass(word)?|secret|token|api[_-]?key|auth|credential|ssn|card|cvv|email/i
+  MASK = "[REDACTED]"
+
+  def self.redact(value)
+    new.redact(value)
+  end
+
+  def redact(value)
+    case value
+    when Hash
+      value.each_with_object({}) do |(key, val), acc|
+        acc[key] = sensitive?(key) ? MASK : redact(val)
+      end
+    when Array
+      value.map { |item| redact(item) }
+    else
+      value
+    end
+  end
+
+  private
+
+  def sensitive?(key)
+    SENSITIVE_KEY_PATTERN.match?(key.to_s)
+  end
+end

data/lib/generators/maquina/solid_errors/templates/app/agents/errors_query.rb

@@ -0,0 +1,84 @@
+# Read-only queries over the Solid Errors store, shaped for agent consumption.
+#
+# This layer NEVER writes. Resolution, retry, and discard stay with the human in
+# the Backstage dashboards. Every context hash and job argument list passes
+# through ErrorRedactor before leaving this class.
+#
+# Failed background jobs reach Solid Errors through the Rails error reporter and
+# carry the job class/arguments attached by ApplicationJob's around_perform hook,
+# so a single read here covers both request and job failures.
+#
+# Column and association names (fingerprint, occurrences_count, recent_occurrence,
+# parsed_backtrace) follow the solid_errors gem schema; confirm against your
+# generated db/errors_schema.rb if you pin an unusual version.
+class ErrorsQuery
+  DEFAULT_LIMIT = 25
+  TOP_LIMIT = 10
+  BACKTRACE_LIMIT = 50
+
+  class << self
+    def unresolved(limit: DEFAULT_LIMIT)
+      SolidErrors::Error.where(resolved_at: nil)
+        .order(created_at: :desc)
+        .limit(limit)
+        .map { |error| summarize(error) }
+    end
+
+    def top(limit: TOP_LIMIT)
+      SolidErrors::Error.where(resolved_at: nil)
+        .order(occurrences_count: :desc)
+        .limit(limit)
+        .map { |error| summarize(error) }
+    end
+
+    def find(fingerprint)
+      detail(SolidErrors::Error.find_by!(fingerprint: fingerprint))
+    end
+
+    private
+
+    def summarize(error)
+      {
+        fingerprint: error.fingerprint,
+        exception: error.exception_class,
+        message: error.message,
+        occurrences: error.occurrences_count,
+        last_seen: error.recent_occurrence&.created_at,
+        job: job_context(error)
+      }.compact
+    end
+
+    def detail(error)
+      occurrence = error.recent_occurrence
+
+      summarize(error).merge(
+        severity: error.severity,
+        source: error.source,
+        context: ErrorRedactor.redact(occurrence&.context || {}),
+        backtrace: backtrace_lines(occurrence)
+      ).compact
+    end
+
+    # Surfaces the job class, redacted arguments, and job_id attached by the
+    # ApplicationJob hook. Returns nil for request-sourced errors so the caller
+    # can tell a job failure from a controller failure.
+    def job_context(error)
+      context = (error.recent_occurrence&.context || {}).with_indifferent_access
+      return unless (job_class = context[:active_job])
+
+      {
+        class: job_class,
+        arguments: ErrorRedactor.redact(context[:arguments]),
+        job_id: context[:job_id]
+      }.compact
+    end
+
+    def backtrace_lines(occurrence)
+      backtrace = occurrence&.parsed_backtrace
+      return [] unless backtrace
+
+      lines = backtrace.is_a?(Array) ? backtrace : backtrace.to_s.lines
+      lines.map { |line| line.to_s.strip }.first(BACKTRACE_LIMIT)
+    end
+  end
+end

data/lib/generators/maquina/solid_errors/templates/app/agents/failure_triage.rb

@@ -0,0 +1,21 @@
+# Single read-only entry point the agent tooling (bin/failures and the MCP
+# server) calls into. Keeping the surface here means bin/ and MCP stay thin and
+# always return the same shapes.
+#
+# Read-only by design: nothing here mutates the errors or queue databases.
+class FailureTriage
+  def self.overview(limit: ErrorsQuery::DEFAULT_LIMIT)
+    {
+      exceptions: ErrorsQuery.unresolved(limit: limit),
+      generated_at: Time.current
+    }
+  end
+
+  def self.exception(fingerprint)
+    ErrorsQuery.find(fingerprint)
+  end
+
+  def self.top(limit: ErrorsQuery::TOP_LIMIT)
+    {top_exceptions: ErrorsQuery.top(limit: limit)}
+  end
+end

data/lib/generators/maquina/solid_errors/templates/app/agents/get_exception_tool.rb

@@ -0,0 +1,26 @@
+# MCP tool: full detail for one error by fingerprint — backtrace, redacted
+# context, and (for job failures) the replayable arguments the agent can turn
+# into a regression test.
+class GetExceptionTool < MCP::Tool
+  tool_name "get_exception"
+  description "Fetch full detail for one error by fingerprint: backtrace, redacted " \
+    "context, and — for background-job failures — the redacted arguments that " \
+    "triggered it. Get the fingerprint from list_failures or top_exceptions."
+
+  input_schema(
+    properties: {
+      fingerprint: {type: "string", description: "Error fingerprint from list_failures."}
+    },
+    required: ["fingerprint"]
+  )
+
+  def self.call(fingerprint:, server_context: nil)
+    payload = FailureTriage.exception(fingerprint)
+    MCP::Tool::Response.new([{type: "text", text: JSON.pretty_generate(payload)}])
+  rescue ActiveRecord::RecordNotFound
+    MCP::Tool::Response.new(
+      [{type: "text", text: JSON.pretty_generate(error: "No unresolved error found for fingerprint #{fingerprint}")}],
+      error: true
+    )
+  end
+end

data/lib/generators/maquina/solid_errors/templates/app/agents/list_failures_tool.rb

@@ -0,0 +1,20 @@
+# MCP tool: the agent's entry point. Lists unresolved errors (request failures
+# and failed jobs alike), most recent first, with redacted job context where
+# present.
+class ListFailuresTool < MCP::Tool
+  tool_name "list_failures"
+  description "List unresolved application errors, most recent first. Covers both " \
+    "request exceptions and failed background jobs; job failures include their " \
+    "class and redacted arguments. Use this first, then get_exception for detail."
+
+  input_schema(
+    properties: {
+      limit: {type: "integer", description: "Max errors to return (default 25)."}
+    }
+  )
+
+  def self.call(limit: ErrorsQuery::DEFAULT_LIMIT, server_context: nil)
+    payload = FailureTriage.overview(limit: limit)
+    MCP::Tool::Response.new([{type: "text", text: JSON.pretty_generate(payload)}])
+  end
+end

data/lib/generators/maquina/solid_errors/templates/app/agents/top_exceptions_tool.rb

@@ -0,0 +1,18 @@
+# MCP tool: the most frequent unresolved errors by occurrence count — lets the
+# agent prioritize what is failing most, not just what failed most recently.
+class TopExceptionsTool < MCP::Tool
+  tool_name "top_exceptions"
+  description "List the most frequent unresolved errors by occurrence count, to " \
+    "prioritize what is failing most often rather than most recently."
+
+  input_schema(
+    properties: {
+      limit: {type: "integer", description: "Max errors to return (default 10)."}
+    }
+  )
+
+  def self.call(limit: ErrorsQuery::TOP_LIMIT, server_context: nil)
+    payload = FailureTriage.top(limit: limit)
+    MCP::Tool::Response.new([{type: "text", text: JSON.pretty_generate(payload)}])
+  end
+end