rails-ai-context 5.7.1 → 5.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e613f50465df28b1b7830acae8a75665fb6c5ce1fc2058e9c4e33f0dbc7e5e47
-  data.tar.gz: cc04cd3316cba5728ee08c5324ee546aedf60eea9dd656aa942754edccbbb58d
+  metadata.gz: 4b34bd6800329b83e18ec7ee97eceb2d4ccab18019bf0c1f3444485e70273938
+  data.tar.gz: 548ab9e6f769651b2e06c81c01fa570e033b8a4c42a4400db7e888ff9a1ba377
 SHA512:
-  metadata.gz: d6950c03b5b7ad58f2ae1df320d698e82dc244976b1140b19fe8c0aad9a37b7430db2504d990a9bb794fc2278ff591e4416b68c0c6027df7df6001198d5fe55f
-  data.tar.gz: e80e37aba8ea2602a9142490c69fb35fa574669e234cf9b7c71093846d57687b7c4b355dbdf3fd295459e74b0b4e19fc4316cb69fc009608c8e28b19e9558409
+  metadata.gz: 3c55e65978c097c6d7b16c4c5a20c1d36d494e9571183569ef4faa91252aeb97dddedd4e858fc8727d169982861320b1db4b963ceee94a1d1f2a38d7708bd61e
+  data.tar.gz: e24ececc1491709b0f07eb235e066048d0f751cd18756462cd6e76c8ee090abc30231e02a7211f23248bb9a40f476e8ce882dcdd106b6056aa3f26406c274b22

data/CHANGELOG.md

@@ -5,6 +5,39 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.8.0] — 2026-04-14
+
+### Added — Modern Rails Coverage Pass
+
+Five targeted gaps in modern Rails introspection, identified by an audit of the introspectors against current Rails 7/8 patterns. Net result: the gem now surfaces what AI agents need to know about Rails 8 built-in auth, Solid Errors, async query usage, strong_migrations safety, and Action Cable channel detail.
+
+- **Rails 8 built-in auth depth.** `auth_introspector#detect_authentication` previously detected `bin/rails generate authentication` only as a boolean. Now returns a hash with the Authentication concern path, the Sessions/Passwords controller paths, and a per-controller list of `allow_unauthenticated_access` filters with their `only:`/`except:` scope. Each declaration in a file yields its own entry (a controller with both `only:` and `except:` is captured fully, not collapsed to the first match), and trailing line comments are stripped from the captured scope. AI agents can answer "which controllers are public?" in one tool call.
+- **Solid Errors gem detection.** Added `solid_errors` (Rails 8 database-backed error tracking, by @fractaledmind) to `gem_introspector.rb`'s `NOTABLE_GEMS` map under the `:monitoring` category. Was the only Solid-* gem missing from the list (`solid_queue`, `solid_cache`, `solid_cable` were already covered). `solid_health` is NOT a real published gem — Rails 8 ships a built-in `/up` healthcheck endpoint with no gem needed.
+- **Async query pattern detection.** `convention_introspector#detect_patterns` now adds `async_queries` to the patterns array when it finds `load_async` or any of the `async_count`/`async_sum`/`async_minimum`/`async_maximum`/`async_average`/`async_pluck`/`async_ids`/`async_exists`/`async_find_by`/`async_find`/`async_first`/`async_last`/`async_take` calls in `app/controllers`, `app/services`, `app/jobs`, or `app/models`. Comment-only references (e.g. `# TODO: bring back load_async`) are skipped to avoid false positives. AI agents can recognize the perf optimization is in use without re-scanning.
+- **Strong Migrations integration.** `migration_advisor` now emits a `## Strong Migrations Warnings` section when the `strong_migrations` gem is in `Gemfile.lock`. Catalog covers the most common breaking-change patterns: `remove_column` (needs `safety_assured` + `ignored_columns` first), `rename_column` (unsafe under load, two-step pattern), `change_column` type change (table rewrite), `add_index` without `algorithm: :concurrently` (Postgres write lock), `add_foreign_key` without `validate: false` (lock validation), and `add_column` with `null: false` but no default (table rewrite). Each warning includes the safer pattern. Fires only when the gem is detected — zero noise for projects that don't use it.
+- **Action Cable channel detail.** `job_introspector#extract_channels` was returning `{ name, stream_methods }` only. Enriched to also extract `identified_by` attributes, `stream_from`/`stream_for` targets, `periodically` timers with their full intervals (including lambdas like `every: -> { current_user.interval }`), RPC action methods (excluding subscribed/unsubscribed/stream_*), and the source file path. **`get_job_pattern` now renders an "Action Cable Channels" section with all of these fields**, so AI agents calling the tool actually see the data instead of just the channel name. Also added `eager_load_channels!` to `JobIntrospector` so the channel set is populated in development mode (where `config.eager_load = false` and `ActionCable::Channel::Base.descendants` is otherwise empty until a client subscribes).
+
+### Changed — CI matrix expanded to cover Ruby 4.0 + Rails 8.1
+
+- Added Ruby `4.0` and Rails `8.1` to the GitHub Actions test matrix. Net jobs: 12 (was 8). Excludes the unsupported combinations: Ruby 3.2 × Rails 8.x (Rails 8 needs 3.3+) and Ruby 4.0 × Rails 7.x (Rails 7 has no Ruby 4 support). Verified locally that the full spec suite passes on Ruby 4.0.2 + Rails 8.1.3 (the environment in #69) — 1925 examples, 0 failures, rubocop clean across all 282 source files.
+
+### Fixed — Standalone Install Path Crashed Inside Bundler-Backed Rails Apps
+
+- **`rails-ai-context` installed via `gem install` (standalone path) crashed on every tool call** when run inside a Rails app that has its own `Gemfile`. Root cause: `boot_rails!` in `exe/rails-ai-context` calls `require config/environment.rb` which runs `Bundler.setup`, which strips `Gem.loaded_specs` to only the app's Gemfile-resolved gems. The MCP SDK reads `Gem.loaded_specs["json-schema"].full_gem_path` at tool-call time (`mcp/tool/schema.rb:45`) — but `json-schema` is a transitive dep of `mcp`, not in the app's Gemfile, so the lookup nils and crashes with `NoMethodError: undefined method 'full_gem_path' for nil`.
+- **Fix:** added `restore_standalone_gem_specs` to `exe/rails-ai-context` which re-registers `mcp`, `json-schema`, and a couple of their transitive deps in `Gem.loaded_specs` after `Bundler.setup` runs. No-op in in-Gemfile mode (the specs are already registered). This was a pre-existing bug that was discovered during v5.8.0 pre-release E2E verification — affected v5.4.0 onward.
+
+### Fixed — MCP Tool Responses Rejected by Strict Clients (#69)
+
+- **Removed default `output_schema` from all 38 tools.** Since v5.4.0, `BaseTool.inherited` automatically assigned a `DEFAULT_OUTPUT_SCHEMA` to every tool. The schema described the response wire envelope (`{content: [...]}`) rather than app-level structured data, and tools never returned matching `structured_content`. Per MCP spec, when a tool declares `outputSchema`, it MUST return `structuredContent` matching it. Strict MCP clients (e.g. Copilot CLI) reject responses that don't, with `MCP error -32600: Tool ... has an output schema but did not return structured content`. Lenient clients (Claude Code, Cursor) silently ignored the missing field, which is why the bug went unnoticed since v5.4.0.
+- **Why this happened.** The MCP Ruby SDK does not enforce `output_schema` server-side (no `validate_result` call in `MCP::Server`), so the test suite passed end-to-end. Validation happens client-side, and only strict clients caught it. Reported by @pardeyke.
+- **What changed.** Deleted `DEFAULT_OUTPUT_SCHEMA` constant and the `inherited` hook line that set it (`lib/rails_ai_context/tools/base_tool.rb`). Tools now ship with no `outputSchema` by default — matching what they actually return (text-only). Individual tools can still declare their own `output_schema` via the MCP::Tool DSL, provided they also return matching `structured_content`.
+- **Regression spec added.** `spec/lib/rails_ai_context/tools_spec.rb` now asserts (a) no tool advertises a default `outputSchema`, and (b) any tool that *does* declare one must also have `structured_content:` in its source — preventing the v5.4.0 misuse from sneaking back in.
+- **Future enhancement.** Per-tool structured output (returning parseable JSON alongside the Markdown text via `structured_content:`) is a future feature for tools where it adds value (`get_schema`, `get_routes`, etc.). Out of scope for this patch.
+
+### Added — Framework Association Noise Filter
+
+- **`excluded_association_names` config option** — filters framework-generated associations (ActiveStorage, ActionText, ActionMailbox, Noticed) from model introspection output. 7 association names excluded by default. Configurable via initializer (`config.excluded_association_names += %w[...]`) or YAML. Closes #57.
+
 ## [5.7.1] — 2026-04-09
 
 ### Changed — SLOP Cleanup

data/README.md

@@ -21,7 +21,7 @@
 <br>
 [![Ruby](https://img.shields.io/badge/Ruby-3.2%20%7C%203.3%20%7C%203.4-CC342D)](https://github.com/crisnahine/rails-ai-context)
 [![Rails](https://img.shields.io/badge/Rails-7.1%20%7C%207.2%20%7C%208.0-CC0000)](https://github.com/crisnahine/rails-ai-context)
-[![Tests](https://img.shields.io/badge/Tests-1889%20passing-brightgreen)](https://github.com/crisnahine/rails-ai-context/actions)
+[![Tests](https://img.shields.io/badge/Tests-1925%20passing-brightgreen)](https://github.com/crisnahine/rails-ai-context/actions)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
 </div>
@@ -543,7 +543,7 @@ end
 ## About
 
 Built by a Rails developer with 10+ years of production experience.<br>
-1889 tests. 38 tools. 5 resource templates. 31 introspectors. Standalone or in-Gemfile.<br>
+1925 tests. 38 tools. 5 resource templates. 31 introspectors. Standalone or in-Gemfile.<br>
 MIT licensed. [Contributions welcome.](CONTRIBUTING.md)
 
 <br>

data/docs/CONFIGURATION.md

@@ -94,6 +94,7 @@ preset: full
 | `excluded_filters` | Array | 3 framework filters | Controller filters to skip |
 | `excluded_middleware` | Array | 24 framework middleware | Middleware to skip in listing |
 | `excluded_paths` | Array | `["node_modules", "tmp", "log", "vendor", ".git", "doc", "docs"]` | Paths excluded from search |
+| `excluded_association_names` | Array | 7 framework associations | Association names to hide from model output |
 | `excluded_concerns` | Array of Regex | Framework concerns | Concerns to skip (supports regex) |
 
 ### File Size Limits

data/docs/FAQ.md

@@ -81,7 +81,7 @@ config.skip_tools = %w[rails_security_scan rails_query]
 
 ### What's the `detail` parameter?
 
-Most tools accept `detail`: `summary` (compact), `standard` (default), `full` (everything). Start with summary and drill down as needed. This keeps AI context windows lean.
+Individual lookup tools accept `detail`: `summary` (compact), `standard` (default), `full` (everything). Start with summary and drill down as needed. This keeps AI context windows lean. Composite tools (`rails_get_context`, `rails_analyze_feature`) do not accept `detail` — they always return their full bundled output.
 
 ### What are `[VERIFIED]` and `[INFERRED]` tags?
 

data/docs/GUIDE.md

@@ -1243,6 +1243,9 @@ if defined?(RailsAiContext)
     # Route prefixes hidden with app_only (e.g. admin frameworks)
     # config.excluded_route_prefixes += %w[admin/]
 
+    # Framework association names hidden from model output (ActiveStorage, ActionText, etc.)
+    # config.excluded_association_names += %w[my_custom_framework_assoc]
+
     # Regex patterns for concerns to hide from model output
     # config.excluded_concerns += [/MyInternal::/]
 
@@ -1342,6 +1345,7 @@ end
 | `max_validate_files` | Integer | `50` | Max files per validate call |
 | `excluded_controllers` | Array | `DeviseController`, etc. | Controller classes hidden from listings |
 | `excluded_route_prefixes` | Array | `action_mailbox/`, `active_storage/`, etc. | Route controller prefixes hidden with `app_only` |
+| `excluded_association_names` | Array | 7 framework associations | Framework association names hidden from model output |
 | `excluded_concerns` | Array | framework regex patterns | Regex patterns for concerns to hide from model output |
 | `excluded_filters` | Array | `verify_authenticity_token`, etc. | Framework filter names hidden from controller output |
 | `excluded_middleware` | Array | standard Rails middleware | Default middleware hidden from config output |

data/docs/STANDALONE.md

@@ -77,6 +77,9 @@ allow_query_in_production: false
 # Filtering
 excluded_models:
   - ApplicationRecord
+excluded_association_names:
+  - active_storage_attachments
+  - active_storage_blobs
 excluded_paths:
   - node_modules
   - tmp

data/docs/TOOLS.md

@@ -43,7 +43,7 @@ Tool name resolution is flexible — all of these work:
 | `get_schema` | `rails_get_schema` |
 | `rails_get_schema` | `rails_get_schema` |
 
-Most tools accept a **`detail`** parameter: `summary` (compact), `standard` (default), or `full` (everything). Start with summary, drill down as needed.
+Individual lookup tools accept a **`detail`** parameter: `summary` (compact), `standard` (default), or `full` (everything). Start with summary, drill down as needed. Composite tools (`rails_get_context`, `rails_analyze_feature`) do not accept `detail`.
 
 <p align="right"><a href="#table-of-contents">↑ back to top</a></p>
 

data/docs/social-preview.html

@@ -144,7 +144,7 @@
         <div class="stat-label">Introspectors</div>
       </div>
       <div class="stat">
-        <div class="stat-number">1889</div>
+        <div class="stat-number">1925</div>
         <div class="stat-label">Tests</div>
       </div>
       <div class="stat">

data/exe/rails-ai-context

@@ -414,6 +414,12 @@ class RailsAiContextCLI < Thor
       (result[:skipped] || []).each { |f| $stderr.puts "  Skipped: #{f} (unchanged)" }
     end
 
+    # Gems that the MCP SDK reads from `Gem.loaded_specs` at tool-call time
+    # (specifically `Gem.loaded_specs["json-schema"].full_gem_path` in
+    # mcp/tool/schema.rb). Bundler.setup strips them in standalone mode so we
+    # capture references BEFORE Rails boot runs and re-register them afterwards.
+    STANDALONE_REQUIRED_GEMS = %w[mcp json-schema addressable public_suffix].freeze
+
     def boot_rails!
       config_path = File.join(Dir.pwd, "config", "environment.rb")
       unless File.exist?(config_path)
@@ -426,22 +432,54 @@ class RailsAiContextCLI < Thor
       # Bundler.setup (in config/boot.rb) strips $LOAD_PATH to Gemfile-only gems.
       # In standalone mode (gem not in Gemfile), this removes our gem and mcp paths.
       # We restore them after boot so lazy requires (mcp, etc.) still resolve.
-      #
-      # We do NOT require mcp or rails_ai_context before boot — that would activate
-      # gem versions that conflict with Bundler's resolution (e.g., bigdecimal).
-      # Instead, paths are restored and gems load lazily using Bundler-resolved deps.
       pre_boot_paths = $LOAD_PATH.dup
 
+      # Capture spec references BEFORE Bundler.setup runs. After Bundler.setup,
+      # Gem::Specification.find_by_name is filtered to only Gemfile-resolved gems
+      # and our transitive deps (mcp, json-schema) become invisible — find_by_name
+      # raises Gem::MissingSpecError. Capturing first means we hold real spec
+      # objects we can splice back in after boot. No-op in in-Gemfile mode (the
+      # captured specs already exist in Gem.loaded_specs and our `||=` skips them).
+      pre_boot_specs = capture_standalone_specs
+
       require config_path
 
-      # Restore paths that Bundler.setup stripped (standalone mode).
-      # For Gemfile users, this is a no-op — no paths were removed.
+      # Restore paths and specs that Bundler.setup stripped (standalone mode).
+      # For Gemfile users, both restorations are no-ops.
       (pre_boot_paths - $LOAD_PATH).each { |p| $LOAD_PATH << p }
+      pre_boot_specs.each { |name, spec| Gem.loaded_specs[name] ||= spec }
+
+      # Loud warning if any required spec couldn't be restored — silent failure
+      # here means tools will crash later with `undefined method 'full_gem_path'
+      # for nil` from inside the MCP SDK.
+      missing = STANDALONE_REQUIRED_GEMS.reject { |g| Gem.loaded_specs.key?(g) }
+      if missing.any? && !ENV["BUNDLE_BIN_PATH"]
+        $stderr.puts "[rails-ai-context] WARNING: standalone CLI could not restore gemspec(s): #{missing.join(', ')}."
+        $stderr.puts "[rails-ai-context]   Tool calls may crash with `undefined method 'full_gem_path' for nil`."
+        $stderr.puts "[rails-ai-context]   Try `gem install rails-ai-context` to ensure all transitive deps are installed."
+      end
 
       require "rails_ai_context"
 
       RailsAiContext::Configuration.auto_load!
     end
+
+    # Look up each required gem via Gem::Specification.find_by_name BEFORE
+    # Bundler.setup runs and filters the spec registry. Returns a hash of
+    # {gem_name => Gem::Specification}. In in-Gemfile mode the lookups still
+    # succeed but the result is unused (Bundler keeps these specs registered).
+    def capture_standalone_specs
+      return {} unless defined?(Gem) && Gem.respond_to?(:loaded_specs)
+
+      STANDALONE_REQUIRED_GEMS.each_with_object({}) do |gem_name, acc|
+        spec = Gem::Specification.find_by_name(gem_name)
+        acc[gem_name] = spec if spec
+      rescue Gem::MissingSpecError, Gem::LoadError
+        # The gem is not installed at all (not just Bundler-filtered). Skip
+        # silently — the downstream `require` produces a clearer error.
+        next
+      end
+    end
 end
 
 RailsAiContextCLI.start(ARGV)

data/lib/generators/rails_ai_context/install/install_generator.rb

@@ -203,6 +203,10 @@ module RailsAiContext
             # Models to exclude from introspection
             # config.excluded_models += %w[AdminUser InternalThing]
 
+            # Framework association names hidden from model output
+            # (ActiveStorage, ActionText, ActionMailbox, Noticed associations are excluded by default)
+            # config.excluded_association_names += %w[my_custom_framework_assoc]
+
             # Controllers to exclude from listings
             # config.excluded_controllers += %w[Admin::BaseController]
 

data/lib/rails_ai_context/configuration.rb

@@ -17,7 +17,7 @@ module RailsAiContext
       server_name cache_ttl max_tool_response_chars
       live_reload live_reload_debounce auto_mount http_path http_bind http_port
       output_dir skip_tools excluded_models excluded_controllers
-      excluded_route_prefixes excluded_filters excluded_middleware excluded_paths
+      excluded_route_prefixes excluded_filters excluded_middleware excluded_association_names excluded_paths
       sensitive_patterns search_extensions concern_paths frontend_paths
       max_file_size max_test_file_size max_schema_file_size max_view_total_size
       max_view_file_size max_search_results max_validate_files
@@ -189,12 +189,20 @@ module RailsAiContext
       /\A(Devise::Models|Devise::Orm|Bullet::|Turbo::|GlobalID::|Rolify::)/
     ].freeze
 
+    DEFAULT_EXCLUDED_ASSOCIATION_NAMES = %w[
+      active_storage_attachments active_storage_blobs
+      rich_text_body rich_text_content
+      action_mailbox_inbound_emails
+      noticed_events noticed_notifications
+    ].freeze
+
     # Filtering — customize what's hidden from AI output
     attr_accessor :excluded_controllers   # Controller classes hidden from listings (e.g. DeviseController)
     attr_accessor :excluded_route_prefixes # Route controller prefixes hidden with app_only (e.g. action_mailbox/)
     attr_accessor :excluded_concerns      # Regex patterns for concerns to hide (e.g. /Devise::Models/)
     attr_accessor :excluded_filters       # Framework filter names hidden from controller output
     attr_accessor :excluded_middleware     # Default middleware hidden from config output
+    attr_accessor :excluded_association_names # Framework association names hidden from model output
 
     # Search and file discovery
     attr_accessor :search_extensions      # File extensions for Ruby fallback search (default: rb,js,erb,yml,yaml,json)
@@ -255,6 +263,7 @@ module RailsAiContext
       @excluded_concerns        = DEFAULT_EXCLUDED_CONCERNS.dup
       @excluded_filters         = DEFAULT_EXCLUDED_FILTERS.dup
       @excluded_middleware      = DEFAULT_EXCLUDED_MIDDLEWARE.dup
+      @excluded_association_names = DEFAULT_EXCLUDED_ASSOCIATION_NAMES.dup
       @custom_tools             = []
       @skip_tools               = []
       @ai_tools                 = nil

data/lib/rails_ai_context/introspectors/auth_introspector.rb

@@ -36,10 +36,9 @@ module RailsAiContext
         devise_models = scan_models_for(/devise\s+(.+)$/)
         auth[:devise] = devise_models if devise_models.any?
 
-        # Rails 8 built-in auth
-        if file_exists?("app/models/session.rb") && file_exists?("app/models/current.rb")
-          auth[:rails_auth] = true
-        end
+        # Rails 8 built-in auth (`bin/rails generate authentication`)
+        rails_auth = detect_rails_auth
+        auth[:rails_auth] = rails_auth if rails_auth
 
         # has_secure_password
         secure_pw = scan_models_for(/has_secure_password/)
@@ -56,6 +55,65 @@ module RailsAiContext
         auth
       end
 
+      # Rails 8's `bin/rails generate authentication` produces a Session model,
+      # a Current attributes model, an Authentication concern in app/controllers/concerns,
+      # a SessionsController, and a PasswordsController. AI agents need to know:
+      #
+      #   1. that this app uses the built-in pattern (not Devise / not custom)
+      #   2. which controllers opt out via `allow_unauthenticated_access`
+      #   3. where the Authentication concern lives so they can find before_actions
+      def detect_rails_auth
+        return nil unless file_exists?("app/models/session.rb") && file_exists?("app/models/current.rb")
+
+        result = { detected: true }
+
+        result[:authentication_concern] = "app/controllers/concerns/authentication.rb" if file_exists?("app/controllers/concerns/authentication.rb")
+        result[:sessions_controller]    = "app/controllers/sessions_controller.rb"     if file_exists?("app/controllers/sessions_controller.rb")
+        result[:passwords_controller]   = "app/controllers/passwords_controller.rb"    if file_exists?("app/controllers/passwords_controller.rb")
+
+        unauth = scan_allow_unauthenticated_access
+        result[:allow_unauthenticated_access] = unauth if unauth.any?
+
+        result
+      rescue => e
+        $stderr.puts "[rails-ai-context] detect_rails_auth failed: #{e.message}" if ENV["DEBUG"]
+        nil
+      end
+
+      def scan_allow_unauthenticated_access
+        controllers_dir = File.join(root, "app/controllers")
+        return [] unless Dir.exist?(controllers_dir)
+
+        Dir.glob(File.join(controllers_dir, "**/*.rb")).flat_map do |path|
+          content = RailsAiContext::SafeFile.read(path) or next []
+          next [] unless content.match?(/\ballow_unauthenticated_access\b/)
+
+          relative = path.sub("#{root}/", "")
+          # Capture every `only:` / `except:` declaration in the file. A single
+          # controller can have multiple (e.g. `only:` + `except:` mixed via concerns).
+          scoped = content.scan(/allow_unauthenticated_access\s+(only|except):\s*(\[?[^\n]+)/)
+
+          if scoped.empty?
+            [ { file: relative, scope: "all actions" } ]
+          else
+            scoped.map do |kw, value|
+              { file: relative, scope: "#{kw}: #{strip_trailing_comment(value).strip}" }
+            end
+          end
+        end.compact.sort_by { |h| h[:file] }
+      rescue => e
+        $stderr.puts "[rails-ai-context] scan_allow_unauthenticated_access failed: #{e.message}" if ENV["DEBUG"]
+        []
+      end
+
+      # Strip a trailing `# comment` from a captured scope value while preserving
+      # `#` characters that appear inside string literals or array element syntax.
+      # Conservative: only strips when the `#` is preceded by whitespace, which
+      # matches the common style (`only: %i[index] # comment`).
+      def strip_trailing_comment(value)
+        value.sub(/\s+#.*\z/, "")
+      end
+
       def detect_authorization
         authz = {}
 

data/lib/rails_ai_context/introspectors/convention_introspector.rb

@@ -105,10 +105,36 @@ module RailsAiContext
 
         patterns << "view_components" if dir_exists?("app/components")
         patterns << "phlex" if gem_present?("phlex-rails")
+        patterns << "async_queries" if uses_async_queries?
 
         patterns
       end
 
+      ASYNC_QUERY_PATTERN = /\bload_async\b|\.async_(count|sum|minimum|maximum|average|pluck|ids|exists|find_by|find|first|last|take)\b/
+
+      def uses_async_queries?
+        %w[app/controllers app/services app/jobs app/models].any? do |rel_dir|
+          dir = File.join(root, rel_dir)
+          next false unless Dir.exist?(dir)
+
+          Dir.glob(File.join(dir, "**/*.rb")).first(500).any? do |f|
+            content = RailsAiContext::SafeFile.read(f) or next false
+            # Skip lines whose first non-whitespace character is `#` so we don't
+            # match deleted-code comments or TODO references like
+            # `# TODO: use load_async here`. Doesn't strip in-line trailing
+            # comments — Ruby AST parsing would be needed for that, and the
+            # false-positive rate from in-line trailing comments is tiny.
+            content.each_line.any? do |line|
+              next false if line.lstrip.start_with?("#")
+              line.match?(ASYNC_QUERY_PATTERN)
+            end
+          end
+        end
+      rescue => e
+        $stderr.puts "[rails-ai-context] uses_async_queries? failed: #{e.message}" if ENV["DEBUG"]
+        false
+      end
+
       def scan_directory_structure
         important_dirs = %w[
           app/models app/controllers app/views app/jobs

data/lib/rails_ai_context/introspectors/gem_introspector.rb

@@ -97,6 +97,7 @@ module RailsAiContext
         "scout_apm"       => { category: :monitoring, note: "APM via Scout." },
         "newrelic_rpm"    => { category: :monitoring, note: "APM via New Relic." },
         "skylight"        => { category: :monitoring, note: "Performance monitoring via Skylight." },
+        "solid_errors"    => { category: :monitoring, note: "Database-backed error tracking via Solid Errors. Mounted at /solid_errors by default." },
 
         # Admin
         "activeadmin"     => { category: :admin, note: "Admin interface via ActiveAdmin." },

data/lib/rails_ai_context/introspectors/job_introspector.rb

@@ -150,20 +150,110 @@ module RailsAiContext
       def extract_channels
         return [] unless defined?(ActionCable::Channel::Base)
 
+        # In development (config.eager_load = false), channel files are not
+        # loaded until a client subscribes. Without this, .descendants is empty
+        # and the entire channels array is missing from the introspector output.
+        # Mirrors the eager_load pattern used by ModelIntrospector / ControllerIntrospector.
+        eager_load_channels!
+
         ActionCable::Channel::Base.descendants.filter_map do |channel|
           next if channel.name.nil? || channel.name == "ApplicationCable::Channel"
 
+          source = channel_source(channel)
+
           {
-            name: channel.name,
+            name:           channel.name,
+            file:           channel_relative_path(channel),
             stream_methods: channel.instance_methods(false)
               .select { |m| m.to_s.start_with?("stream_") || m == :subscribed }
-              .map(&:to_s)
-          }
+              .map(&:to_s),
+            identified_by:  extract_identified_by(source),
+            streams:        extract_channel_streams(source),
+            periodic:       extract_channel_periodic(source),
+            actions:        extract_channel_actions(channel)
+          }.compact
         end.sort_by { |c| c[:name] }
       rescue => e
         $stderr.puts "[rails-ai-context] extract_channels failed: #{e.message}" if ENV["DEBUG"]
         []
       end
+
+      def eager_load_channels!
+        return if Rails.application.config.eager_load
+
+        channels_path = File.join(app.root, "app", "channels")
+        if defined?(Zeitwerk) && Dir.exist?(channels_path) &&
+           Rails.autoloaders.respond_to?(:main) && Rails.autoloaders.main.respond_to?(:eager_load_dir)
+          Rails.autoloaders.main.eager_load_dir(channels_path)
+        end
+      rescue => e
+        $stderr.puts "[rails-ai-context] eager_load_channels! failed: #{e.message}" if ENV["DEBUG"]
+        nil
+      end
+
+      def channel_source(channel)
+        path = channel_absolute_path(channel)
+        return nil unless path && File.exist?(path)
+        RailsAiContext::SafeFile.read(path)
+      end
+
+      def channel_absolute_path(channel)
+        method_source = channel.instance_methods(false).first
+        return nil unless method_source
+        location = channel.instance_method(method_source).source_location
+        location&.first
+      rescue
+        nil
+      end
+
+      def channel_relative_path(channel)
+        path = channel_absolute_path(channel)
+        return nil unless path
+        rails_root = app.root.to_s
+        path.start_with?(rails_root) ? path.sub("#{rails_root}/", "") : path
+      end
+
+      # `identified_by :current_user, :tenant` — declared on ApplicationCable::Connection,
+      # but channels can also use it. Returns array of attribute names.
+      def extract_identified_by(source)
+        return nil unless source
+        matches = source.scan(/\bidentified_by\s+([^\n]+)/)
+        return nil if matches.empty?
+        matches.flat_map { |m| m.first.scan(/:(\w+)/).flatten }.uniq
+      end
+
+      # `stream_from "channel_name"` and `stream_for object` — what the channel broadcasts.
+      def extract_channel_streams(source)
+        return nil unless source
+        from_targets = source.scan(/\bstream_from\s+["']([^"']+)["']/).flatten
+        for_targets  = source.scan(/\bstream_for\s+([^\s\n,]+)/).flatten
+        result = {}
+        result[:stream_from] = from_targets.uniq if from_targets.any?
+        result[:stream_for]  = for_targets.uniq  if for_targets.any?
+        result.empty? ? nil : result
+      end
+
+      # `periodically :method_name, every: 3.seconds`
+      # The `[^\n]+` capture group is already line-bounded, so we keep the full
+      # captured value (after stripping whitespace). Earlier versions tried to
+      # trim past the first comma/whitespace, which mangled lambdas and
+      # complex intervals like `-> { current_user.interval }`.
+      def extract_channel_periodic(source)
+        return nil unless source
+        timers = source.scan(/\bperiodically\s+:(\w+),\s*every:\s*([^\n]+)/).map do |method_name, interval|
+          { method: method_name, every: interval.strip }
+        end
+        timers.any? ? timers : nil
+      end
+
+      # RPC actions = public instance methods that aren't lifecycle hooks or stream helpers.
+      def extract_channel_actions(channel)
+        ignored = %i[subscribed unsubscribed]
+        actions = channel.instance_methods(false).reject do |m|
+          ignored.include?(m) || m.to_s.start_with?("stream_")
+        end
+        actions.empty? ? nil : actions.map(&:to_s).sort
+      end
     end
   end
 end

data/lib/rails_ai_context/introspectors/model_introspector.rb

@@ -135,7 +135,8 @@ module RailsAiContext
       # ── Reflection-based extraction (unchanged) ─────────────────────
 
       def extract_associations(model)
-        model.reflect_on_all_associations.map do |assoc|
+        excluded = config.excluded_association_names
+        model.reflect_on_all_associations.reject { |assoc| excluded.include?(assoc.name.to_s) }.map do |assoc|
           detail = {
             name: assoc.name.to_s,
             type: assoc.macro.to_s,

data/lib/rails_ai_context/serializers/tool_guide_helper.rb

@@ -75,15 +75,19 @@ module RailsAiContext
 
       def tools_detail_guidance
         detail_param = tool_mode == :cli ? "detail=summary" : "detail:\"summary\""
+        context_tool = tool_mode == :cli ? cli_cmd("context") : "rails_get_context"
+        analyze_tool = tool_mode == :cli ? cli_cmd("analyze_feature") : "rails_analyze_feature"
         [
           "### detail parameter — ALWAYS start with summary",
           "",
-          "Most tools accept `#{detail_param}`. Use the right level:",
+          "Individual lookup tools accept `#{detail_param}`. Use the right level:",
           "- **summary** — first call, orient yourself (table list, model names, route overview)",
           "- **standard** — working detail (columns with types, associations, action source) — DEFAULT",
           "- **full** — only when you need indexes, foreign keys, code snippets, or complete content",
           "",
           "Pattern: summary to find the target → standard to understand it → full only if needed.",
+          "",
+          "**Do NOT pass `detail` to composite tools** — `#{context_tool}` and `#{analyze_tool}` do not accept it and will return an error.",
           ""
         ]
       end

data/lib/rails_ai_context/tools/base_tool.rb

@@ -8,27 +8,6 @@ module RailsAiContext
     # Inherits from the official MCP::Tool to get schema validation,
     # annotations, and protocol compliance for free.
     class BaseTool < MCP::Tool
-      # Default output schema for all tools. MCP::Tool.inherited resets
-      # @output_schema_value to nil on each subclass, so we re-set it
-      # via our own inherited hook.
-      DEFAULT_OUTPUT_SCHEMA = MCP::Tool::OutputSchema.new(
-        type: "object",
-        properties: {
-          content: {
-            type: "array",
-            items: {
-              type: "object",
-              properties: {
-                type: { type: "string", enum: [ "text" ] },
-                text: { type: "string", description: "Tool response as Markdown-formatted text" }
-              },
-              required: [ "type", "text" ]
-            }
-          }
-        },
-        required: [ "content" ]
-      ).freeze
-
       # ── Auto-registration ────────────────────────────────────────────
       # Every subclass is tracked automatically via inherited.
       # BaseTool itself is abstract — only concrete tools are registered.
@@ -39,7 +18,6 @@ module RailsAiContext
 
       def self.inherited(subclass)
         super
-        subclass.instance_variable_set(:@output_schema_value, DEFAULT_OUTPUT_SCHEMA)
         subclass.instance_variable_set(:@abstract, false)
         # Thread-safe append. Mutex is NOT held during eager_load!'s const_get
         # (which triggers inherited), so no recursive locking risk here.

data/lib/rails_ai_context/tools/get_job_pattern.rb

@@ -28,23 +28,37 @@ module RailsAiContext
         root = Rails.root.to_s
         jobs_dir = File.join(root, "app", "jobs")
 
-        unless Dir.exist?(jobs_dir)
-          return text_response("No app/jobs/ directory found. This app may not use background jobs.")
+        job_files = if Dir.exist?(jobs_dir)
+          files = Dir.glob(File.join(jobs_dir, "**", "*.rb")).sort
+          files.reject { |f| File.basename(f) == "application_job.rb" }
+        else
+          []
         end
 
-        job_files = Dir.glob(File.join(jobs_dir, "**", "*.rb")).sort
-        # Filter out application_job.rb base class
-        job_files.reject! { |f| File.basename(f) == "application_job.rb" }
-
-        if job_files.empty?
-          return text_response("app/jobs/ directory exists but contains no job files (besides ApplicationJob).")
-        end
+        # Pull enriched channel data from the cached introspector context — this
+        # gives us the v5.8.0 fields (identified_by, streams, periodic, actions)
+        # that JobIntrospector#extract_channels populates.
+        channels = (cached_context.dig(:jobs, :channels) || []).reject { |c| c.is_a?(Hash) && c[:error] }
 
+        # Single-job query: requires jobs to be present.
         if job
+          return text_response("No app/jobs/ directory found. This app may not use background jobs.") if job_files.empty?
           return format_single_job(job, job_files, jobs_dir, root)
         end
 
-        format_job_listing(job_files, jobs_dir, root, detail)
+        # No jobs and no channels — bail out with the legacy message.
+        if job_files.empty? && channels.empty?
+          return text_response("No app/jobs/ directory found and no Action Cable channels detected. This app may not use background jobs.")
+        end
+
+        # Compose: jobs section (if any) + channels section (if any).
+        lines = []
+        lines.concat(format_job_listing_lines(job_files, jobs_dir, root, detail)) if job_files.any?
+        if channels.any?
+          lines << "" if lines.any?
+          lines.concat(format_channels_section(channels))
+        end
+        text_response(lines.join("\n"))
       end
 
       private_class_method def self.format_single_job(job, job_files, jobs_dir, root)
@@ -137,7 +151,7 @@ module RailsAiContext
         text_response(lines.join("\n"))
       end
 
-      private_class_method def self.format_job_listing(job_files, jobs_dir, root, detail)
+      private_class_method def self.format_job_listing_lines(job_files, jobs_dir, root, detail)
         job_data = []
 
         job_files.each do |file|
@@ -219,7 +233,50 @@ module RailsAiContext
           lines << "_Use `job:\"Name\"` to see enqueuers and cross-references._"
         end
 
-        text_response(lines.join("\n"))
+        lines
+      end
+
+      # Renders the v5.8.0 enriched Action Cable channel detail produced by
+      # JobIntrospector#extract_channels (identified_by, streams, periodic, actions).
+      # Returns lines, not a Response — caller composes.
+      private_class_method def self.format_channels_section(channels)
+        lines = [ "# Action Cable Channels (#{channels.size})", "" ]
+
+        channels.each do |c|
+          lines << "## `#{c[:name]}`"
+          lines << ""
+          lines << "- **File:** `#{c[:file]}`" if c[:file]
+
+          if (ids = c[:identified_by]) && ids.any?
+            lines << "- **Identified by:** #{ids.map { |i| "`#{i}`" }.join(', ')}"
+          end
+
+          if (streams = c[:streams])
+            from = Array(streams[:stream_from])
+            for_ = Array(streams[:stream_for])
+            lines << "- **stream_from:** #{from.map { |s| "`#{s}`" }.join(', ')}" if from.any?
+            lines << "- **stream_for:** #{for_.map { |s| "`#{s}`" }.join(', ')}"   if for_.any?
+          end
+
+          if (periodic = c[:periodic]) && periodic.any?
+            lines << "- **Periodic timers:**"
+            periodic.each do |t|
+              lines << "  - `#{t[:method]}` every `#{t[:every]}`"
+            end
+          end
+
+          if (actions = c[:actions]) && actions.any?
+            lines << "- **RPC actions:** #{actions.map { |a| "`#{a}`" }.join(', ')}"
+          end
+
+          if (sm = c[:stream_methods]) && sm.any?
+            lines << "- **Stream methods:** #{sm.map { |m| "`#{m}`" }.join(', ')}"
+          end
+
+          lines << ""
+        end
+
+        lines
       end
 
       private_class_method def self.extract_class_name(source)

data/lib/rails_ai_context/tools/migration_advisor.rb

@@ -101,6 +101,9 @@ module RailsAiContext
         # Show affected models
         lines.concat(show_affected_models(table, models))
 
+        # Strong Migrations warnings (only when the gem is present in the project)
+        lines.concat(strong_migrations_warnings(action, table, column, options)) if strong_migrations_gem_present?
+
         text_response(lines.join("\n"))
       end
 
@@ -338,6 +341,71 @@ module RailsAiContext
           lines
         end
 
+        # Strong Migrations integration — surfaces the same warnings the gem would raise
+        # at migration runtime, so AI agents see them at code-generation time. Only fires
+        # when the gem is actually present in the project's Gemfile.lock.
+        #
+        # Catalog covers the most common breaking-change patterns (columns, indexes, FKs).
+        # Not exhaustive — see https://github.com/ankane/strong_migrations#checks for the full list.
+        def strong_migrations_warnings(action, table, column, options)
+          warnings = case action
+          when "remove_column"
+            [
+              "**`remove_column` is unsafe under load.** strong_migrations requires:",
+              "  1. Add the column to `self.ignored_columns += %w[#{column}]` in `app/models/#{table.singularize}.rb` first.",
+              "  2. Deploy that change.",
+              "  3. THEN run the migration in a separate deploy.",
+              "  Or wrap in `safety_assured do ... end` if you accept the risk."
+            ]
+          when "rename_column"
+            [
+              "**`rename_column` is unsafe under load.** Old code references the old name and breaks during the deploy window.",
+              "Safer pattern: add a new column, backfill, dual-write, deploy, then remove the old column in a later release."
+            ]
+          when "change_type"
+            [
+              "**`change_column` (type change) blocks writes** on Postgres for the duration of the table rewrite, which can be hours on large tables.",
+              "Safer pattern: add a new column with the new type, backfill, dual-write, swap, drop the old column."
+            ]
+          when "add_index"
+            unless options.to_s.include?("concurrently")
+              [
+                "**`add_index` without `algorithm: :concurrently`** acquires an `ACCESS EXCLUSIVE` lock on Postgres and blocks writes.",
+                "Use `add_index :#{table}, :#{column}, algorithm: :concurrently` and add `disable_ddl_transaction!` at the top of the migration."
+              ]
+            end
+          when "add_association"
+            [
+              "**`add_foreign_key` validates existing rows by default**, which acquires a `SHARE ROW EXCLUSIVE` lock on both tables.",
+              "Safer two-step pattern:",
+              "  1. `add_foreign_key :#{table}, :other_table, validate: false` (lock-free)",
+              "  2. In a separate migration: `validate_foreign_key :#{table}, :other_table`"
+            ]
+          when "add_column"
+            if options.to_s.match?(/null:\s*false/) && !options.to_s.include?("default:")
+              [
+                "**Adding a `NOT NULL` column without a default rewrites the table** on older Postgres and fails on existing rows.",
+                "Safer pattern: add the column nullable, backfill in batches, then add the NOT NULL constraint with `change_column_null`."
+              ]
+            end
+          end
+
+          return [] unless warnings&.any?
+
+          [ "", "## Strong Migrations Warnings", "", "_The `strong_migrations` gem is in your Gemfile — these warnings match what it would raise at migration runtime._", "" ] + warnings
+        end
+
+        def strong_migrations_gem_present?
+          lock_path = File.join(rails_app.root.to_s, "Gemfile.lock")
+          return false unless File.exist?(lock_path)
+          content = RailsAiContext::SafeFile.read(lock_path)
+          return false unless content
+          content.include?("    strong_migrations (")
+        rescue => e
+          $stderr.puts "[rails-ai-context] strong_migrations_gem_present? failed: #{e.message}" if ENV["DEBUG"]
+          false
+        end
+
         def show_affected_models(table, models)
           lines = [ "", "## Affected Models", "" ]
 

data/lib/rails_ai_context/tools/query.rb

@@ -70,6 +70,20 @@ module RailsAiContext
           )
         end
 
+        # ── ActiveRecord guard (api-only apps) ──────────────────────
+        # Must come BEFORE any code that rescues ActiveRecord::* — Ruby
+        # resolves rescue class constants at raise time, and `rescue
+        # ActiveRecord::ConnectionNotEstablished` crashes with NameError
+        # on apps where ActiveRecord is not loaded (e.g.
+        # `rails new --api --skip-active-record`).
+        unless defined?(ActiveRecord::Base)
+          return text_response(
+            "Database queries are unavailable: ActiveRecord is not loaded in this app. " \
+            "This happens on API-only apps created with `rails new --api --skip-active-record`. " \
+            "rails_query requires a database connection to function."
+          )
+        end
+
         # ── Layer 1: SQL validation ─────────────────────────────────
         valid, error = validate_sql(sql)
         return text_response(error) unless valid

data/lib/rails_ai_context/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RailsAiContext
-  VERSION = "5.7.1"
+  VERSION = "5.8.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-ai-context
 version: !ruby/object:Gem::Version
-  version: 5.7.1
+  version: 5.8.0
 platform: ruby
 authors:
 - crisnahine