rails-ai-context 5.30.1 → 5.30.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e31095f85a3f90825fbd66bf2a7deae9224ac4fe94474c8d60da20c46ed52b47
-  data.tar.gz: 190a7d48230b4ae98300b2619a0d2cf7a1ddb8a6e24619a7a54cfa3a6e5b233b
+  metadata.gz: 49493277fcbe8b2da2d183de723ebf3d5f4c85101f5eff5b6a0c89a1ae4340a9
+  data.tar.gz: ebd28661e4d369b526027b8705c599372383796003287160a460ec3e99990632
 SHA512:
-  metadata.gz: f91198dc48ae6f259c0f4d170b0fbae5d2174fa142a64530ef4ac46f2e6c51c9e22e54057e7f64712f06fc76a085e45994da2a9dc592edfe9ee3f0366608d642
-  data.tar.gz: cee2a7a2d636322fddeedcffa151812d0ae8c52cde17d99394fd7dded5e30e5bddb8db288bc9b31b0fe1281a9a33270739c000735957fab6d64cbafdfec8a149
+  metadata.gz: 3a98be099ee6b23ded854a1820714d9450d8ce304dd08c18d12182b7a8f15097f0ca5eb2c3c0db122b313057aed0a9ec3b44b38aae1c0e1a231d1f41b455c6e6
+  data.tar.gz: 0be3021416fc068c9e93bfaabba548a22cb914c6393f1daf6ef9a7892045cf1984efad3d22de132c29b3d83081e796a5f74e868fc8b4f94883912ff7f4562f75

data/CHANGELOG.md

@@ -5,6 +5,128 @@ 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.30.2] - 2026-10-01
+
+### Changed
+
+- **`generate_root_files: false` leaves out `.cursorrules` too, and always
+  writes `.ai-context.json`.** `.cursorrules` is the same compact file as
+  `CLAUDE.md` at the repo root, so it is a root file and now reports "Not
+  applicable (root files disabled)". `.ai-context.json` is data for tools, not
+  an instruction file, and is written whatever the key says.
+- **`serve --port` has no default of its own.** An explicit `--port` wins, then
+  `http_port` from the config, then 6029. The config key never reached `serve`
+  before, although `docs/STANDALONE.md` documents it, and the
+  `streamable_http` alias ignored `--port`.
+- **A PostGIS connection is labelled PostgreSQL everywhere.** The booted schema
+  said PostGIS and the static tier PostgreSQL for the same app. The raw adapter
+  name stays in `.ai-context.json` as `adapter_source`.
+- **The booted schema header lists pending migrations**, as the static tier
+  already did.
+
+### Fixed
+
+- **No machine path in an introspector's error.** A model file that could not
+  load put the absolute path of the app into `rails_get_model_details`,
+  `CLAUDE.md`, the models rules file and `.ai-context.json`, and the controller,
+  component, middleware, migration and rake-task errors did the same. Every
+  section's errors are now written relative to the app root, the resolved
+  `/private/tmp` form included.
+- **A declared, unmigrated table names the migration that adds it.** The booted
+  answer said the table was missing from the database and stopped there. Rails
+  7.2+ refuses to load a migration dated in the future, which also emptied the
+  pending list; the list now comes from the applied versions and the files.
+- **An unreadable model file still counts as the model file for its table**,
+  instead of listing the table under "Tables with no model file".
+- **The static tier carries each `belongs_to` foreign key.** Static
+  association records had none unless the source spelled one, so
+  `rails_get_model_details`, the context files and `.ai-context.json` left it
+  out, and `rails_validate` stayed silent on an unindexed key where the booted
+  tier warned. A polymorphic key indexed as `[type, id]` counts as indexed.
+- **A composite foreign key in `db/structure.sql` is read**, pg_dump and
+  mysqldump both, and renders as a column list like the schema.rb one.
+- **Minitest tests from `rails_generate_test` can pass.** Absence,
+  confirmation, acceptance and exclusion validations asserted on a valid
+  fixture; each now sets up an invalid record, or emits `skip` where it cannot.
+- **A mount at a computed path prints no path.** `mount X => ENV.fetch(...)`
+  printed `` at `[INFERRED]` ``, a bare constant printed its name as the path,
+  and a gem engine mounted that way read as "not mounted by the app's routes".
+  A path written without its leading slash gets one, as Rails does.
+- **Static routes say which engine tables they could not read.** An engine
+  whose routes live in its gem (PgHero, LetterOpenerWeb) dropped out of the
+  static answer with no note; it is listed under "Mounted engines whose routes
+  were not read". A constant the app defines counts as an engine only when it
+  subclasses `Rails::Engine`. An engine mounted at several paths is one line
+  naming each.
+- **Booted filter attribution matches the static tier.** An inherited
+  `after_action` lost its "from" credit when the child declared a
+  `before_action` of the same name, filters from a controller concern were not
+  credited to it, and a concern's `only:`/`except:`/`if:`/`unless:` and its
+  `skip_*_action` calls never reached the booted record. A body that
+  re-declares a concern's filter owns it, and a concern an ancestor already
+  includes stays the ancestor's.
+- **An ERB comment is not read for instance variables**, while a Ruby comment
+  line inside a multi-line code tag no longer hides the code after it.
+- **`rails_get_partial_interface` finds `render(partial: ...)`** with
+  parentheses, on one line or several, counts a nested render once, and a
+  multi-line snippet stops at the call's end.
+- **Jobs on Rails 7.0 to 8.1.** A job with no `queue_as` read as "computed by a
+  block", since ActiveJob's default queue is a lambda; it now shows the
+  resolved default. The booted tier dropped every `retry_on`/`discard_on`, and
+  a job in a code root Zeitwerk does not manage.
+- **A mailer outside `app/mailers` is a mailer in the booted tier too**, and
+  `rails_get_service_pattern` no longer answers a mailer, concern or mixin by
+  name when its listing leaves them out.
+- **`app/concerns` reads as `other`** when the app root directory is itself
+  named `app`, as in Docker's `/app`.
+- **The static default locale reads `Rails.application.config.i18n`** in an
+  initializer, where the last assignment wins.
+- **A bad value for a required enum fails the call.**
+  `migration_advisor --action bogus` said "action is required" and exited 0;
+  it says `bogus` is not a valid `action`, names the allowed values and exits 1.
+- **`rails_diagnose` never suggests a path it refused**, refuses it with or
+  without `--line`, and prints the tier footer once.
+- **`rails_validate` names a `belongs_to` whose key column the table lacks**
+  instead of calling that column unindexed, and says nothing about a table's
+  indexes when its schema calls a helper the reader cannot interpret (Canvas's
+  `t.replica_identity_index`), since that helper may add the index.
+- **A multi-name `t.references :a, :b, :c` adds every column**, with its index
+  and foreign key, in the schema.rb reader and the migration replay. The replay
+  also records `foreign_key: true` on a single reference, which it dropped.
+- **A declaration inside a block the model may not run is kept but not
+  trusted.** `has_details_table do belongs_to :parent end` put a `parent_id`
+  key on the model's own table, and `rails_validate` checked it there. Such
+  declarations are still listed, and `rails_validate`'s schema, column and
+  `:dependent` checks skip them. `with_options`, `included`, `class_methods`,
+  `concerning`, `state_machine` and `aasm` blocks run on the model and are
+  trusted as before.
+- **A foreign key given as a constant or an expression is not read as a column
+  name**, and a composite key stays a column list in both tiers instead of the
+  text of a Ruby array.
+- **Every column type reads as a column in the static schema**, `t.vector`,
+  `t.citext`, `t.enum`, the range and PostGIS types included, and so does a
+  column whose options sit in braces. They were left out of the table.
+- **`attr_reader` and `alias_attribute` names count as attributes** for
+  `rails_validate`'s "column not found" check.
+- **Filters inherited through a Devise or Doorkeeper controller.** The static
+  walk stopped at the gem class, so a controller under `Devise::` or
+  `Doorkeeper::` lost every filter its app base declares and was credited with
+  a concern that base already includes. It now continues at the base the gem's
+  initializer names (`parent_controller`, `base_controller`).
+- **In-repo route files are read statically.** A mounted in-repo engine's own
+  routes are listed under its mount, and a file that draws, appends or prepends
+  to the app's routes adds to the app's table; only an unmounted engine's file
+  still counts as not read.
+- **A failed boot names missing gems once.** A bundle missing many gems listed
+  every name three times; the banner now gives the count and the first few,
+  and `doctor` and `DEBUG=1` keep the full list.
+- **A test file over `max_test_file_size` is named as too large**, not missing.
+- **`rails_runtime_info` says how many rows it left out** of the unused-index
+  list and the summary table sizes, which it cut at 10 and 5 with no note.
+- **`rails_query` on MySQL** reads a `MAX_EXECUTION_TIME` interruption as the
+  timeout, and names `INTO OUTFILE`/`DUMPFILE` as a disk write.
+- The defaults in `configuration.rb`'s comments match the values it sets.
+
 ## [5.30.1] - 2026-09-28
 
 ### Fixed

data/docs/CLI.md

@@ -36,7 +36,7 @@ rails-ai-context serve --transport http --port 6029   # HTTP transport
 | Option | Default | Description |
 |:-------|:--------|:------------|
 | `--transport` | `stdio` | `stdio` or `http` |
-| `--port` | `6029` | HTTP listen port |
+| `--port` | `http_port` from config, else `6029` | HTTP listen port |
 | `--no-boot` | off | Skip booting the app; answer from source alone |
 
 ### `tool`

data/docs/COMPATIBILITY.md

@@ -215,7 +215,9 @@ Proof sources:
    PostgreSQL 17 with a partitioned table added, booted and static from
    schema.rb and structure.sql, a Rails 7.2 app whose schema.rb carries no
    partition marker, and Discourse, Mastodon, OpenFoodNetwork and Forem
-   answering as before.
+   answering as before. In the v5.30.2 release QA: 14 real apps answered by
+   v5.30.1 and by the release branch side by side, and the lab regressions on
+   SQLite in all three tiers, PostgreSQL and MySQL.
 2. Non-crash coverage for every built-in tool including `get_view` in
    `spec/e2e/in_gemfile_install_spec.rb`'s full-tool sweep; output correctness
    (ivar cross-check, render-form detection, partial interfaces) verified

data/docs/CONFIGURATION.md

@@ -86,7 +86,7 @@ config file is written. Before v5.27.0 an empty list wrote every tool's files.
 | `preset` | Symbol | `:full` | `:full` (40 introspectors) or `:standard` (17 introspectors) |
 | `context_mode` | Symbol | `:compact` | `:compact` (context files capped at ~150 lines) or `:full` (no line cap) |
 | `introspectors` | Array of symbols | (from preset) | Override the introspector list directly |
-| `generate_root_files` | Boolean | `true` | Set `false` to generate split rules only, no root CLAUDE.md/AGENTS.md |
+| `generate_root_files` | Boolean | `true` | Set `false` to generate split rules only: no CLAUDE.md, AGENTS.md, .cursorrules or copilot-instructions.md (`.ai-context.json` is still written) |
 | `anti_hallucination_rules` | Boolean | `true` | Embed 6-rule verification protocol in generated context files |
 | `claude_max_lines` | Integer | `150` | Max non-blank lines in a compact context file's gem-managed block, the `<!-- BEGIN/END rails-ai-context -->` markers included. Over budget, data lines are cut and the Commands, Warnings, Rules and MCP-tools sections kept whole |
 
@@ -247,7 +247,7 @@ Lightweight subset for faster generation:
 | AI Tool | Root File | Split Rules | MCP Config |
 |:--------|:----------|:------------|:-----------|
 | Claude Code | `CLAUDE.md` | `.claude/rules/*.md` | `.mcp.json` |
-| Cursor | - | `.cursor/rules/*.mdc` | `.cursor/mcp.json` |
+| Cursor | `.cursorrules` (legacy fallback) | `.cursor/rules/*.mdc` | `.cursor/mcp.json` |
 | GitHub Copilot | `.github/copilot-instructions.md` | `.github/instructions/*.instructions.md` | `.vscode/mcp.json` |
 | OpenCode | `AGENTS.md` | `app/*/AGENTS.md` | `opencode.json` |
 | Codex CLI | (shares `AGENTS.md`) | (shares OpenCode rules) | `.codex/config.toml` |

data/docs/FAQ.md

@@ -126,7 +126,7 @@ Yes. The file is applied first and a `configure` block wins only the keys it ass
 
 ### What's `generate_root_files`?
 
-When `true` (default), generates root files like CLAUDE.md, AGENTS.md. Set to `false` to only generate split rules (.claude/rules/, .cursor/rules/, etc.).
+When `true` (default), generates the root files: CLAUDE.md, AGENTS.md, .cursorrules and copilot-instructions.md. Set to `false` to only generate split rules (.claude/rules/, .cursor/rules/, etc.). `.ai-context.json` is written either way.
 
 ---
 

data/docs/GUIDE.md

@@ -1353,7 +1353,7 @@ end
 | `live_reload_debounce` | Float | `1.5` | Debounce interval in seconds for live reload |
 | `server_name` | String | `"rails-ai-context"` | MCP server name |
 | `server_version` | String | gem version | MCP server version |
-| `generate_root_files` | Boolean | `true` | Generate root files (CLAUDE.md, etc.) - set `false` for split rules only |
+| `generate_root_files` | Boolean | `true` | Set `false` to generate split rules only: no CLAUDE.md, AGENTS.md, .cursorrules or copilot-instructions.md (`.ai-context.json` is still written) |
 | `anti_hallucination_rules` | Boolean | `true` | Embed 6-rule Anti-Hallucination Protocol in generated context files - set `false` to skip |
 | `hydration_enabled` | Boolean | `true` | Inject schema hints into controller/view tool responses |
 | `hydration_max_hints` | Integer | `5` | Max schema hints per tool response |

data/exe/rails-ai-context

@@ -175,15 +175,14 @@ class RailsAiContextCLI < Thor
 
     desc "serve", "Start MCP server (stdio transport)"
     option :transport, type: :string, default: "stdio", desc: "Transport: stdio or http"
-    option :port, type: :numeric, default: 6029, desc: "HTTP port (only for http transport)"
+    option :port, type: :numeric, desc: "HTTP port (only for http transport; default: config http_port, else 6029)"
     option :no_boot, type: :boolean, default: false, desc: "Skip booting the app; serve static analysis only"
     def serve
       boot_rails!(command: "serve", allow_static: true)
 
       transport = options[:transport].to_sym
-      if transport == :http
-        ::RailsAiContext.configuration.http_port = options[:port]
-      end
+      # No Thor default: it would overwrite the config file's http_port.
+      ::RailsAiContext.configuration.http_port = options[:port] if options[:port]
 
       ::RailsAiContext.start_mcp_server(transport: transport)
     end

data/lib/rails_ai_context/action_filters.rb

@@ -58,19 +58,25 @@ module RailsAiContext
       # The whole ancestor entry, not only its `from:`: an entry the walk
       # could not attribute carries `provenance` instead, and merging only
       # `from` dropped that on the tier the label exists for.
-      attribution_of = parent.to_h { |f| [ entry_key(f), f.slice(:from, :provenance) ] }
+      attribution_of = parent.to_h { |f| [ entry_key(f), f.slice(:from, :from_concern, :provenance) ] }
       declared_on = attribution_of
       declared_names = declared.map { |f| entry_key(f) }.to_set
 
       # A filter this body declares is its own, whatever an ancestor declares
       # as well. The runtime tier's list also carries names it only inherits,
       # and those are the ones that move: they carry no `declared` mark.
-      inherited_here = ->(f) { declared_on.key?(entry_key(f)) && !f[:declared] }
+      # An ActiveSupport::Concern an ancestor already includes does not run again, so its filters stay the ancestor's.
+      inherited_here = lambda do |f|
+        next false unless declared_on.key?(entry_key(f))
+
+        !f[:declared] || (f[:from_concern] && declared_on[entry_key(f)][:from_concern] == f[:from_concern] &&
+                          runs_once?(f[:from_concern], root, controller_name))
+      end
       own = mark_conditional_skips(applicable.reject(&inherited_here), conditions, action)
       inherited = mark_conditional_skips(
         parent.reject { |f| declared_names.include?(entry_key(f)) } +
           applicable.select(&inherited_here)
-            .map { |f| f.except(:from, :provenance).merge(attribution_of[entry_key(f)]) }, conditions, action
+            .map { |f| f.except(:from, :from_concern, :provenance).merge(attribution_of[entry_key(f)]) }, conditions, action
       )
 
       { own: own,
@@ -196,7 +202,10 @@ module RailsAiContext
         info = controllers[name]
         source = info.is_a?(Hash) ? nil : base_controller_source(name, root)
         info ||= { filters: base_filters(source, name, root) } if source
-        break unless info.is_a?(Hash)
+        unless info.is_a?(Hash)
+          name = gem_controller_base(name, root)
+          next
+        end
 
         # The class that skips a filter must not contribute it either: in the
         # booted tier its own list is the reflection list, which carries every
@@ -234,7 +243,9 @@ module RailsAiContext
                            evidence = {}, body_known = false)
       key = entry_key(filter)
       if found.key?(key)
-        found[key] = found[key].merge(from: ancestor) if filter[:declared] && !attributed.include?(key)
+        if filter[:declared] && !attributed.include?(key)
+          found[key] = found[key].except(:from_concern).merge(filter.slice(:from_concern), from: ancestor)
+        end
       else
         found[key] = filter.merge(from: ancestor)
         positions[key] = depth
@@ -363,6 +374,58 @@ module RailsAiContext
       path && SafeFile.read(path)
     end
 
+    # Gem controllers whose base class is set in the app's initializers:
+    # [gem base, setting that names its parent, the gem's default parent].
+    GEM_CONTROLLER_BASES = [
+      [ /\ADevise(::|Controller\z)/, "parent_controller=", "ApplicationController" ],
+      [ /\ADoorkeeper::(Tokens|TokenInfo|ApplicationMetal)Controller\z/, "base_metal_controller", "ActionController::API" ],
+      [ /\ADoorkeeper::/, "base_controller", "ActionController::Base" ]
+    ].freeze
+
+    # The static tier cannot read a gem's class chain, but these gems end it
+    # at a class the app names, so the walk resumes there.
+    def gem_controller_base(name, root)
+      _, setting, default = GEM_CONTROLLER_BASES.find { |pattern, _, _| name.to_s.match?(pattern) }
+      return nil unless setting
+
+      root ||= default_root
+      configured = root && RunCache.fetch([ :gem_controller_base, root.to_s, setting ]) { configured_base(root, setting) }
+      return nil if configured == :computed
+
+      (configured || default).delete_prefix("::")
+    rescue => e
+      RailsAiContext.debug_fail(e, nil, label: "ActionFilters gem_controller_base")
+    end
+
+    # ActiveSupport::Concern skips a re-include; a plain module's `self.included` runs on each.
+    # A module whose file is not found is taken for a concern.
+    def runs_once?(name, root, within)
+      root ||= default_root
+      path = root && ConcernPaths.find_file(root.to_s, name, prefer: "controller", within: within.to_s)
+      source = path && SafeFile.read(path)
+      return true unless source
+
+      RunCache.fetch([ :concern_module, path ]) do
+        Introspectors::SourceIntrospector.walk_source(source, { mixins: Introspectors::Listeners::MixinsListener })[:mixins]
+          .any? { |mixin| mixin[:macro] == :extend && mixin[:name] == "ActiveSupport::Concern" }
+      end
+    end
+
+    # The last value the initializers set; :computed when it is not a string literal.
+    def configured_base(root, setting)
+      Dir.glob(File.join(root.to_s, "config", "initializers", "**", "*.rb")).sort.filter_map do |path|
+        source = SafeFile.read(path)
+        next unless source&.include?(setting.delete_suffix("="))
+
+        tree = AstCache.parse_string(source)&.value
+        call = tree && Introspectors::AstWalk.each(tree).select { |node| node.is_a?(Prism::CallNode) && node.name == setting.to_sym }.last
+        next unless call
+
+        value = call.arguments&.arguments&.first
+        value.is_a?(Prism::StringNode) ? value.unescaped : :computed
+      end.last
+    end
+
     def base_filters(source, name, root)
       Introspectors::ControllerFilters.with_concerns(source, root: (root || default_root).to_s, within: name.to_s).first
     end
@@ -392,6 +455,6 @@ module RailsAiContext
                          :skip_calls, :base_filters, :skip_flag_records, :redeclared_names, :last_records, :own_skips,
                          :record_attribution, :conditional?, :partial?, :absolute_names, :conditions_by_name,
                          :merge_conditions, :mark_conditional_skips, :skip_tail, :action_names, :condition_text,
-                         :unplaced_conditional_skips, :evidence_skips
+                         :unplaced_conditional_skips, :evidence_skips, :gem_controller_base, :configured_base, :runs_once?
   end
 end

data/lib/rails_ai_context/boot_manager.rb

@@ -31,6 +31,20 @@ module RailsAiContext
 
     DEFAULT_TIMEOUT = 60
 
+    # Bundler names every gem the bundle lacks; an app missing its whole bundle
+    # is thousands of characters. DEBUG keeps the full list.
+    MISSING_GEMS = /\ACould not find ((?:[^\s,]+, )+[^\s,]+) in (.+)\z/
+    MISSING_GEMS_SHOWN = 3
+
+    def self.shorten_missing_gems(line)
+      match = line.to_s.match(MISSING_GEMS)
+      return line if match.nil? || ENV["DEBUG"]
+
+      gems = match[1].split(", ").uniq
+      listed = gems.size > MISSING_GEMS_SHOWN ? "#{gems.size} gems (first few: #{gems.first(MISSING_GEMS_SHOWN).join(', ')})" : gems.join(", ")
+      "Could not find #{listed} in #{match[2]}"
+    end
+
     # Ruby quotes the method name differently across versions.
     CONFIGURE_WITHOUT_GEM = /undefined method .?configure.? for (module )?RailsAiContext/
 
@@ -55,16 +69,18 @@ module RailsAiContext
       # One-line summary safe to relay to an AI client or a terminal. It
       # carries the cause too: the footer this feeds is the only place most
       # callers ever see, and a gem name with no reason is not actionable.
-      def failure_summary
+      # `full:` keeps a long missing-gem list whole, for a command that stops on the failure.
+      def failure_summary(full: false)
         return nil if booted?
 
-        summary = one_line(error)
+        summary = one_line(error, full)
         cause = root_cause
-        cause ? "#{summary} (cause: #{one_line(cause)})" : summary
+        cause ? "#{summary} (cause: #{one_line(cause, full)})" : summary
       end
 
-      def one_line(e)
-        "#{e.class}: #{e.message.to_s.lines.first&.strip}"
+      def one_line(e, full = false)
+        line = e.message.to_s.lines.first&.strip
+        "#{e.class}: #{full ? line : BootManager.shorten_missing_gems(line)}"
       end
 
       # An unguarded `RailsAiContext.configure` in config/initializers has

data/lib/rails_ai_context/cli/entry_boot.rb

@@ -131,7 +131,7 @@ module RailsAiContext
 
       def self.boot_failed(result, root, timeout, messages)
         messages << "Error: Rails app failed to boot in #{root}"
-        messages << "  #{result.failure_summary}"
+        messages << "  #{result.failure_summary(full: true)}"
         if ENV["DEBUG"]
           Array(result.error.backtrace).first(15).each { |line| messages << "    #{line}" }
           # The wrapper's frames stop at the require; the frames that name the
@@ -170,7 +170,8 @@ module RailsAiContext
         RailsAiContext.static_kind = kind
         RailsAiContext.configuration.app_root = root
         Configuration.auto_load!(root)
-        messages << "[rails-ai-context] static tier active: #{reason}"
+        # A failed boot's reason is already the line above.
+        messages << "[rails-ai-context] static tier active#{": #{reason}" unless kind == :boot_failed}"
         Outcome.new(tier: :static, reason: reason, kind: kind, messages: messages)
       rescue StandardError, ScriptError => e
         messages << "Error: #{e.message}"

data/lib/rails_ai_context/cli/tool_runner.rb

@@ -31,6 +31,7 @@ module RailsAiContext
         @environment = environment
         @error = false
         @missing_required = false
+        @invalid_required = []
         @out_of_type = {}
       end
 
@@ -38,6 +39,8 @@ module RailsAiContext
         kwargs = build_kwargs
         schema = tool_schema
         validate_kwargs!(kwargs, schema)
+        return extract_output(invalid_required_response) if @invalid_required.any?
+
         response = tool_class.call(**kwargs)
         extract_output(response)
       end
@@ -418,7 +421,9 @@ module RailsAiContext
         end
 
         # Check enum constraints - downcase before comparing for case-insensitive match.
-        # If invalid, strip the param so the tool uses its default behavior.
+        # If invalid, strip the param so the tool uses its default behavior; a
+        # required one has no default, so the call answers with the error itself
+        # rather than letting the tool report the value as missing.
         kwargs.each do |key, value|
           prop = properties[key]
           next unless prop&.dig(:enum)
@@ -431,12 +436,26 @@ module RailsAiContext
           if matched
             kwargs[key] = matched
           else
-            $stderr.puts "Warning: '#{value}' is not a valid value for #{key}. Valid: #{prop[:enum].join(', ')}. Using default."
-            kwargs.delete(key)
+            valid = prop[:enum].join(", ")
+            if required.include?(key.to_s)
+              @invalid_required << "**Error:** `#{value}` is not a valid `#{key}`. Valid: #{valid}"
+              @missing_required = true
+            else
+              $stderr.puts "Warning: '#{value}' is not a valid value for #{key}. Valid: #{valid}. Using default."
+              kwargs.delete(key)
+            end
           end
         end
       end
 
+      # Through the tool's own wrapper when it has one, so the static-tier banner rides along.
+      def invalid_required_response
+        text = @invalid_required.join("\n")
+        return tool_class.text_response(text) if tool_class <= Tools::BaseTool
+
+        MCP::Tool::Response.new([ { type: "text", text: text } ])
+      end
+
       def blank?(value)
         return true if value.nil?
         return value.strip.empty? if value.is_a?(String)

data/lib/rails_ai_context/concern_paths.rb

@@ -107,7 +107,8 @@ module RailsAiContext
     # concerns. Singular so a filter reads `type: "mailer"`.
     def type_for(dir)
       segment = dir[%r{/app/([^/]+)/concerns/?\z}, 1]
-      segment ? segment.singularize : "other"
+      # An app root named app (Docker's /app) puts app/concerns at app/app/concerns.
+      segment && segment != "app" ? segment.singularize : "other"
     end
 
     # The path only approximates the declared constant: an app inflection makes

data/lib/rails_ai_context/configuration.rb

@@ -220,7 +220,7 @@ module RailsAiContext
     # Models/tables to exclude from introspection
     attr_accessor :excluded_models
 
-    # TTL in seconds for cached introspection (default: 30)
+    # TTL in seconds for cached introspection (default: 60)
     attr_accessor :cache_ttl
 
     # Context file generation mode
@@ -262,8 +262,8 @@ module RailsAiContext
     # `generate_root_files`, which still writes the split rule files.
     attr_accessor :context_files
 
-    # Whether to generate root-level context files (CLAUDE.md, AGENTS.md, etc.)
-    # When false, only generates split rule files (.claude/rules/, .cursor/rules/, etc.)
+    # Whether to generate root-level context files (CLAUDE.md, AGENTS.md, .cursorrules,
+    # copilot-instructions.md). When false, only split rule files and .ai-context.json are written.
     attr_accessor :generate_root_files
 
     # Whether to embed the Anti-Hallucination Protocol section in generated context files.
@@ -272,14 +272,14 @@ module RailsAiContext
     attr_accessor :anti_hallucination_rules
 
     # File size limits (bytes) - increase for larger projects
-    attr_accessor :max_file_size          # Per-file read limit for tools (default: 2MB)
-    attr_accessor :max_test_file_size     # Test file read limit (default: 500KB)
+    attr_accessor :max_file_size          # Per-file read limit for tools (default: 5MB)
+    attr_accessor :max_test_file_size     # Test file read limit (default: 1MB)
     attr_accessor :max_schema_file_size   # schema.rb / structure.sql parse limit (default: 10MB)
     # Doctor thresholds, not read caps: the view tools do not stop at them.
     attr_accessor :max_view_total_size    # Size of app/views doctor warns past (default: 10MB)
     attr_accessor :max_view_file_size     # Accepted and stored; no check reads it (default: 1MB)
     attr_accessor :max_search_results     # Max lines a search may emit, matches and context together (default: 200)
-    attr_accessor :max_validate_files     # Max files per validate call (default: 20)
+    attr_accessor :max_validate_files     # Max files per validate call (default: 50)
 
     # Additional MCP tool classes to register alongside built-in tools
     attr_accessor :custom_tools

data/lib/rails_ai_context/erb_source.rb

@@ -14,9 +14,14 @@ module RailsAiContext
       source.to_s.include?("<%")
     end
 
-    # The tag bodies, joined. Order is kept; line numbers are not.
+    # The code tag bodies, joined. Order is kept; line numbers are not.
     def tag_bodies(source)
-      source.to_s.scan(TAG).flatten.join("\n")
+      source.to_s.scan(TAG).flatten.reject { |body| comment?(body) }.join("\n")
+    end
+
+    # Only `<%#` (or `<%-#`) is an ERB comment; `<% # note` is code whose first line is a Ruby comment.
+    def comment?(body)
+      body.to_s.start_with?("#")
     end
 
     # The same Ruby with everything outside the tags blanked rather than
@@ -30,7 +35,7 @@ module RailsAiContext
         match = Regexp.last_match
         out << blank(text[last...match.begin(0)])
         body = match[1].to_s
-        out << (body.lstrip.start_with?("#") ? blank(body) : body)
+        out << (comment?(body) ? blank(body) : blank_comment_lines(body))
         last = match.end(0)
       end
       out << blank(text[last..].to_s)
@@ -47,5 +52,19 @@ module RailsAiContext
       text.gsub(/[^\n]/, " ")
     end
     private_class_method :blank
+
+    # Tags sharing a line are joined, so a comment left in would swallow the next tag's code.
+    def blank_comment_lines(body)
+      return body unless body.include?("#")
+
+      out = body.b
+      # Last first: a multibyte comment blanks to fewer bytes and would shift later offsets.
+      AstCache.parse_string(body).comments.reverse_each do |comment|
+        loc = comment.location
+        out[loc.start_offset...loc.end_offset] = blank(loc.slice).b
+      end
+      out.force_encoding(body.encoding)
+    end
+    private_class_method :blank_comment_lines
   end
 end

data/lib/rails_ai_context/introspector.rb

@@ -52,6 +52,7 @@ module RailsAiContext
       warnings = []
       config.introspectors.each do |name|
         data = context[name]
+        portable_errors!(data)
         if data.is_a?(Hash) && data[:error]
           warnings << { introspector: name.to_s, error: data[:error] }
         end
@@ -133,12 +134,11 @@ module RailsAiContext
       # nothing about the database, and answering for it would be the
       # fabrication this method exists to remove.
       return if schema[:adapter].nil?
-      return unless SchemaAdapter.placeholder?(schema[:adapter])
 
       # "unknown" is a placeholder too. Swapping one for another buys nothing
       # and would bury the parse mode that at least says how the schema was read.
       resolved = SchemaAdapter.label(context)
-      return if SchemaAdapter.placeholder?(resolved)
+      return if SchemaAdapter.placeholder?(resolved) || resolved == schema[:adapter]
 
       schema[:adapter_source] = schema[:adapter]
       schema[:adapter] = resolved
@@ -178,6 +178,17 @@ module RailsAiContext
       end
     end
 
+    # An exception message names files by absolute path, and the context is committed.
+    def portable_errors!(data)
+      case data
+      when Hash
+        data[:error] = PortablePath.relativize_text(data[:error], app.root) if data[:error].is_a?(String) && !data.frozen?
+        data.each_value { |value| portable_errors!(value) }
+      when Array
+        data.each { |value| portable_errors!(value) }
+      end
+    end
+
     def unavailable_reason
       Introspectors::StaticTier.unavailable_reason
     end