rails-ai-context 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e7442b6a28d089867479cba4a99d6f0fcf64e34f692d8c47b576de8e7ec4ffd
-  data.tar.gz: 0b8b21e8c1581a056afbb03e3ef6b3c45a62c7fbb61d345bbec49d370c4fd191
+  metadata.gz: aeeb02e9069ff67b12236ae2f99f169df5b5dd48d42af344ad0734ff1a499307
+  data.tar.gz: 0d5f18c57c512747bc06fc063c9e58c95073f288df15f3d74bd0d951815fabe8
 SHA512:
-  metadata.gz: e1bd3b280678917a3b94576cef271669fc6892ca32cfd522b88a4c7cee93d73d4301b6d995bd75e78fd64bb448f5e226013b8678411bfd56e68de0a59ccba35b
-  data.tar.gz: a57fed3f44c4e1599854caf8243a35f62476f487e8b14a41489bcaee1efb4e8398935211ea9073ca70f9a1e34c16a6fa13d79cdaa5cf943d6f0d5d2e82ea100c
+  metadata.gz: dc0c90e9d22ff8348ce6eefc770ca36eac77bda624795be2813972de0f56b565180bfc974042cc7fa949718a8362c760d3db9123dc8aab294403ca9498efd8f3
+  data.tar.gz: f33d929cf59fdd217d4905a49b5043b689cb7828588ff738d9973d2e97c42f78228327d3574d276180e04663cac3f3470c7b84bc118022d9dc8890a47ff117ed

data/CHANGELOG.md

@@ -5,6 +5,42 @@ 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).
 
+## [1.3.0] - 2026-03-23
+
+### Added
+
+- **Full-stack `analyze_feature` tool** — now discovers services (AF1), jobs with queue/retry config (AF2), views with partial/Stimulus refs (AF3), Stimulus controllers with targets/values/actions (AF4), test files with counts (AF5), related models via associations (AF6), concern tracing (AF12), callback chains (AF13), channels (AF10), mailers (AF11), and environment variable dependencies (AF9). One call returns the complete feature picture.
+- **Modal pattern extraction** (DS1) — detects overlay (`fixed inset-0 bg-black/50`) and modal card patterns
+- **List item pattern extraction** (DS5) — detects repeating card/item patterns from views
+- **Shared partials with descriptions** (DS7) — scans `app/views/shared/` and infers purpose (flash, navbar, status badge, loading, modal, etc.)
+- **"When to use what" decision guide** (DS8) — explicit rules: primary button for CTAs, danger for destructive, when to use shared partials
+- **Bootstrap component extraction** (DS13-DS15) — detects `btn-primary`, `card`, `modal`, `form-control`, `badge`, `alert`, `nav` patterns from Bootstrap apps
+- **Tailwind `@apply` directive parsing** (DS16) — extracts named component classes from CSS `@apply` rules
+- **DaisyUI/Flowbite/Headless UI detection** (DS17) — reports Tailwind plugin libraries from package.json
+- **Animation/transition inventory** (DS19) — extracts `transition-*`, `duration-*`, `animate-*`, `ease-*` patterns
+- **Smarter JSONB strong params check** (V1) — only skips params matching JSON column names, validates the rest
+- **Route-action fix suggestions** (V2) — suggests "add `def action; end`" when route exists but action is missing
+
+### Fixed
+
+- **`self` filtered from class methods** (B2/MD1) — no longer appears in model class method lists
+- **Rules serializer methods cap raised to 20** (RS1) — uses introspector's pre-filtered methods directly instead of redundant re-filtering
+- **oklch token noise filtered** (DS21) — complex color values (oklch, calc, var) hidden from summary, only shown in `detail:"full"`
+
+## [1.2.1] - 2026-03-23
+
+### Fixed
+
+- **New models now discovered via filesystem fallback** — when `ActiveRecord::Base.descendants` misses a newly created model, the introspector scans `app/models/*.rb` and constantizes them. Fixes model invisibility until MCP restart.
+- **Devise meta-methods no longer fill class/instance method caps** — filtered 40+ Devise-generated methods (authentication_keys=, email_regexp=, password_required?, etc.). Source-defined methods now prioritized over reflection-discovered ones.
+- **Controller `unless:`/`if:` conditions now extracted** — filters like `before_action :authenticate_user!, unless: :devise_controller?` now show the condition. Previously silently dropped.
+- **Empty string defaults shown as `""`** — schema tool now renders `""` instead of a blank cell for empty string defaults. AI can distinguish "no default" from "empty string default".
+- **Implicit belongs_to validations labeled** — `presence on user` from `belongs_to :user` now shows `_(implicit from belongs_to)_` and filters phantom `(message: required)` options.
+- **Array columns shown as `type[]`** in generated rules — `string` columns with `array: true` now render as `string[]` in schema rules.
+- **External ID columns no longer hidden** — columns like `paymongo_checkout_id` and `stripe_payment_id` are now shown in schema rules. Only conventional Rails FK columns (matching a table name) are filtered.
+- **Column defaults shown in generated rules** — columns with non-nil defaults now show `(=value)` inline.
+- **`analyze_feature` matches models by table name and underscore form** — `feature:"share"` now finds `CookShare` (via `cook_shares` table and `cook_share` underscore form), not just exact model name substring.
+
 ## [1.2.0] - 2026-03-23
 
 ### Added

data/ROADMAP.md

@@ -0,0 +1,148 @@
+# rails-ai-context — Bugs & Improvements Roadmap
+
+> Comprehensive list from 6 testing sessions, ~500+ MCP calls, 522 specs, verified on DailyContentChef (9 tables, 6 models, 18 controllers, 15 Stimulus controllers).
+> Current version: v1.2.1 (updated 2026-03-23)
+
+---
+
+## Open Bugs
+
+### MCP Tools
+
+| # | Bug | Severity | Tool | Status |
+|---|-----|----------|------|--------|
+| B1 | `unless: :devise_controller?` not fully evaluated — OmniauthCallbacksController shows `authenticate_user!` | LOW | controllers | **FIXED v1.2.1** — evaluates condition at introspection time, removes filter for Devise controllers |
+| B2 | `self` appears in class methods list — Plan shows `self` as a class method alongside `free`, `pro`, `business` | LOW | model_details | Open |
+
+### Rules Serializer (generated CLAUDE.md / rules files)
+
+| # | Bug | Severity | Status |
+|---|-----|----------|--------|
+| R1 | User methods list shows ~5 of 18 — missing concern + model-defined methods | MEDIUM | **FIXED v1.2.1** — source-defined methods prioritized, Devise methods filtered |
+| R3 | `visuals_needed` shown as `string` not `string[]` in rules | MEDIUM | **FIXED v1.2.1** — array columns now render as `type[]` |
+| R4 | payments missing `paymongo_checkout_id` and `paymongo_payment_id` columns in rules | MEDIUM | **FIXED v1.2.1** — external ID columns no longer hidden |
+| R5 | users missing `paymongo_customer_id` column in rules | MEDIUM | **FIXED v1.2.1** — same fix as R4 |
+| R6 | No column defaults shown in generated rules | MEDIUM | **FIXED v1.2.1** — defaults shown inline as `(=value)` |
+
+---
+
+## Improvements: `rails_analyze_feature`
+
+### Tier 1 — Core (makes the tool 10x more useful)
+
+| # | Improvement | Description | Impact |
+|---|-------------|-------------|--------|
+| AF1 | **Services discovery** | Scan `app/services/` for classes matching the feature keyword. Show class name, line count, key method names. `feature:"cook"` → finds `ContentChefService`, `GeminiClient`, `OutputParser` | HIGH |
+| AF2 | **Jobs discovery** | Scan `app/jobs/` for matching classes. Show queue name, retry config, what service it calls. `feature:"cook"` → finds `CookJob` (queue: default, retries: 3, calls ContentChefService) | HIGH |
+| AF3 | **Views + partials discovery** | List matching views with line counts, partial renders, and Stimulus controller references. `feature:"cook"` → shows `cooks/show.html.erb (61 lines) renders: cooks/output, cooks/loading stimulus: cook-status, share` | HIGH |
+| AF4 | **Stimulus controllers discovery** | Match Stimulus controllers by name. Show targets, values, actions. `feature:"cook"` → finds `cook_status` controller with `cookId` value and `checkTimeout` action | HIGH |
+| AF5 | **Test files discovery** | List matching test files with test counts. `feature:"cook"` → shows `test/models/cook_test.rb (13 tests)`, `test/controllers/cooks_controller_test.rb (21 tests)` | HIGH |
+
+### Tier 2 — Cross-cutting intelligence
+
+| # | Improvement | Description | Impact |
+|---|-------------|-------------|--------|
+| AF6 | **Related models via associations** | Show models connected through `belongs_to`, `has_many`. `feature:"cook"` → "Related: User (owner), BrandProfile (optional), CookShare (shares)" | MEDIUM |
+| AF7 | **Execution flow graph** | Trace the full request lifecycle: controller action → authorization check → model operation → job enqueue → service call → external API → broadcast. No other tool does this. | MEDIUM |
+| AF8 | **Permission/authorization mapping** | Map which concern methods guard which actions. `can_cook?` guards `CooksController#create`, `can_use_bonus_modes?` guards `Bonus::BaseController` | MEDIUM |
+| AF9 | **Environment dependencies** | Detect ENV vars referenced by the feature. `feature:"cook"` → requires `GEMINI_API_KEY`, Sidekiq running, Redis connected | MEDIUM |
+| AF10 | **Channel/websocket discovery** | Find `turbo_stream_from` and Action Cable subscriptions. `feature:"cook"` → uses `turbo_stream_from "cook_#{id}"` for real-time output | MEDIUM |
+
+### Tier 3 — Agent workflow optimization
+
+| # | Improvement | Description | Impact |
+|---|-------------|-------------|--------|
+| AF11 | **Mailer/notification discovery** | Scan `app/mailers/` for matching classes and their delivery triggers | LOW |
+| AF12 | **Concern tracing** | When a feature uses concerns, list which concerns and their methods. `feature:"User"` → PlanLimitable adds 12 methods | LOW |
+| AF13 | **Callback chains** | Show before/after hooks that fire. `feature:"brand"` → `before_save :ensure_single_default` on BrandProfile | LOW |
+| AF14 | **"How to extend" hints** | Based on existing patterns, suggest where to add a new action, new validation, new partial. "To add a new cook mode: add to MODES constant (line 7), add view in bonus/" | LOW |
+
+---
+
+## Improvements: `rails_get_design_system`
+
+### Tier 1 — Missing component patterns
+
+| # | Improvement | Description | Impact |
+|---|-------------|-------------|--------|
+| DS1 | **Modal pattern** | Extract overlay + card pattern from `_share_modal.html.erb`. Show: `fixed inset-0 bg-black/50 z-40` overlay + `bg-white rounded-2xl shadow-lg max-w-md w-full p-6` card | HIGH |
+| DS2 | **Badge/tag pattern** | Extract from mode badges: `text-xs font-medium px-2.5 py-1 rounded-full bg-{color}-100 text-{color}-700`. Show color variants (indigo, green, yellow, red) | HIGH |
+| DS3 | **Status indicator pattern** | Extract from `_status_badge.html.erb`. Show as a reusable shared partial reference: `render "shared/status_badge", cook: cook` | HIGH |
+| DS4 | **Flash/toast patterns** | Extract from `_flash.html.erb`. Show success (`bg-green-50 border-green-200 text-green-700`), error (`bg-red-50 border-red-200 text-red-700`), notice variants | HIGH |
+| DS5 | **List item pattern** | Extract the repeating card-per-item layout from cook index: `bg-white rounded-xl p-5 shadow-sm border border-gray-100 flex items-center justify-between gap-4` | HIGH |
+| DS6 | **Secondary button** | Extract: `bg-gray-100 text-gray-700 px-4 py-2 rounded-xl text-sm font-semibold hover:bg-gray-200 transition cursor-pointer`. Currently only primary + danger listed | MEDIUM |
+| DS7 | **Shared partials section** | List all `app/views/shared/` partials with one-line descriptions. Agents should reuse these before creating new markup: `_flash.html.erb`, `_navbar.html.erb`, `_status_badge.html.erb`, `_upgrade_nudge.html.erb` | MEDIUM |
+
+### Tier 2 — Decision guidance
+
+| # | Improvement | Description | Impact |
+|---|-------------|-------------|--------|
+| DS8 | **"When to use what" decision guide** | Not just class strings but rules: "Page needs a form? → Copy Form Page example. Need confirmation? → `data: { turbo_confirm: 'message' }`. Showing status? → `render 'shared/status_badge'`" | HIGH |
+| DS9 | **Loading/spinner pattern** | Extract from `_loading.html.erb`: `animate-spin` emoji + progress bar (`bg-orange-500 h-2 rounded-full animate-pulse`) | MEDIUM |
+| DS10 | **Confirmation dialog convention** | Document the Turbo Confirm pattern: `data: { turbo_confirm: "Are you sure?" }` on `button_to` for destructive actions | MEDIUM |
+| DS11 | **Form error pattern** | Show what validation errors look like: field highlighting, error message placement, `field_with_errors` wrapper behavior | MEDIUM |
+| DS12 | **Spacing system rules** | Explain WHEN to use each spacing: `space-y-3` for list items, `space-y-4` for form fields, `space-y-6` for form sections, `gap-2` for button groups, `mb-6` for section separators | LOW |
+
+### Tier 3 — Framework adaptability
+
+| # | Improvement | Description | Impact |
+|---|-------------|-------------|--------|
+| DS13 | **Auto-detect CSS framework** | Detect Tailwind vs Bootstrap vs custom CSS/Sass. Adapt extraction strategy per framework. Currently hardcoded for Tailwind — broken for all other setups | HIGH |
+| DS14 | **Bootstrap support** | Scan ERB for Bootstrap classes (`btn-primary`, `card`, `modal`, `form-control`). Parse `_variables.scss` for custom theme. Show Bootstrap component examples from actual views | HIGH (for Bootstrap apps) |
+| DS15 | **Custom CSS/Sass support** | Parse `.scss/.css` files for class definitions. Group by file (buttons.scss → Button patterns). Detect BEM naming. Show CSS custom properties (`--color-primary`) | HIGH (for custom apps) |
+| DS16 | **Parse Tailwind `@apply` directives** | If app has `@apply` rules in CSS, extract those as named component classes | MEDIUM |
+| DS17 | **Detect DaisyUI / Flowbite / Headless UI** | If Tailwind plugin libraries are installed, include their component patterns alongside raw Tailwind | MEDIUM |
+| DS18 | **Parse `tailwind.config.js` custom theme** | Extract custom colors, fonts, spacing from the config file. Show `primary: '#FF6B00'` if customized | MEDIUM |
+| DS19 | **Animation/transition inventory** | List all `transition`, `animate-*`, `duration-*` patterns with usage context | LOW |
+| DS20 | **Icon size conventions** | Document when to use which size: `w-3.5 h-3.5` (inline with text), `w-4 h-4` (buttons), `w-5 h-5` (standalone), `w-10 h-10` (feature icons) | LOW |
+| DS21 | **Remove oklch noise from summary** | Token colors (oklch values) waste tokens in summary. Move to `detail:"full"` only. Summary should show Tailwind class names only | LOW |
+
+---
+
+## Improvements: Rules Serializer
+
+| # | Improvement | Description | Impact |
+|---|-------------|-------------|--------|
+| RS1 | **Include all concern methods** | User methods list should include all PlanLimitable methods (12+), not just 5 | HIGH — partially fixed in v1.2.1 (source methods prioritized), full concern method extraction still open |
+| RS2 | **Detect array columns** | Show `visuals_needed:string[]` not `visuals_needed:string` | ~~MEDIUM~~ **FIXED v1.2.1** |
+| RS3 | **Include all non-system columns** | payments should show `paymongo_checkout_id`, `paymongo_payment_id`. users should show `paymongo_customer_id` | ~~MEDIUM~~ **FIXED v1.2.1** |
+| RS4 | **Show column defaults** | Inline defaults: `mode:string(default:"standard")`, `status:string(default:"pending")` | ~~MEDIUM~~ **FIXED v1.2.1** |
+
+---
+
+## Improvements: `rails_validate`
+
+| # | Improvement | Description | Impact |
+|---|-------------|-------------|--------|
+| V1 | **Smarter JSONB strong params skip** | Currently skips ALL params check for models with ANY JSONB column. Could be smarter: only skip params matching JSONB column names, check the rest | LOW |
+| V2 | **Route-action check suggests fix** | When `show` action missing but route exists, suggest: "Add `def show; end` to BrandProfilesController or remove `show` from `resources :brand_profiles`" | LOW |
+
+---
+
+## Improvements: `rails_get_model_details`
+
+| # | Improvement | Description | Impact |
+|---|-------------|-------------|--------|
+| MD1 | **Filter `self` from class methods** | Plan shows `self` as a class method — should be filtered out | LOW |
+
+---
+
+## Summary
+
+| Category | Total | Fixed | Open | Tier 1 (HIGH) | Tier 2 (MEDIUM) | Tier 3 (LOW) |
+|----------|-------|-------|------|--------------|-----------------|--------------|
+| Open Bugs | 7 | 6 | 1 | 0 | 0 | 1 (B2) |
+| analyze_feature | 14 | 0 | 14 | 5 | 5 | 4 |
+| design_system | 21 | 0 | 21 | 9 | 6 | 6 |
+| Rules serializer | 4 | 3 | 1 | 1 (RS1 partial) | 0 | 0 |
+| validate | 2 | 0 | 2 | 0 | 0 | 2 |
+| model_details | 1 | 0 | 1 | 0 | 0 | 1 |
+| **Total** | **49** | **9** | **40** | **15** | **11** | **14** |
+
+### Killer differentiators (no other tool does these)
+
+1. **Execution flow graph** (AF7) — trace a full request from HTTP to database to broadcast in one call
+2. **"When to use what" decision guide** (DS8) — not just patterns but rules for choosing the right one
+3. **Auto-detect CSS framework** (DS13-DS15) — works for Tailwind, Bootstrap, custom CSS, any Rails app
+4. **Services + Jobs + Views + Tests in feature analysis** (AF1-AF5) — full-stack feature discovery in one call
+5. **Environment dependency detection** (AF9) — know what needs to be running before you touch a feature

data/lib/rails_ai_context/introspectors/controller_introspector.rb

@@ -167,8 +167,14 @@ module RailsAiContext
               if (sc = source_constraints[f[:name]])
                 f[:only] = sc[:only] if sc[:only]&.any?
                 f[:except] = sc[:except] if sc[:except]&.any?
+                f[:unless] = sc[:unless] if sc[:unless]
+                f[:if] = sc[:if] if sc[:if]
               end
             end
+
+            # Evaluate known runtime conditions to remove inapplicable filters
+            reflection_filters.reject! { |f| filter_excluded_by_condition?(ctrl, f) }
+
             return reflection_filters
           end
         end
@@ -221,6 +227,15 @@ module RailsAiContext
           except = parse_action_constraint(line, "except")
           filter[:only] = only if only&.any?
           filter[:except] = except if except&.any?
+
+          # Extract conditional modifiers (unless:, if:)
+          if (unless_match = line.match(/unless:\s*:(\w+[?!]?)/))
+            filter[:unless] = unless_match[1]
+          end
+          if (if_match = line.match(/\bif:\s*:(\w+[?!]?)/))
+            filter[:if] = if_match[1]
+          end
+
           filters << filter
         end
         filters
@@ -247,6 +262,29 @@ module RailsAiContext
         nil
       end
 
+      # Statically evaluate known runtime conditions to exclude inapplicable filters.
+      # e.g., `unless: :devise_controller?` on a Devise controller means the filter doesn't apply.
+      def filter_excluded_by_condition?(ctrl, filter)
+        # unless: :devise_controller? — filter does NOT apply to Devise controllers
+        if filter[:unless] == "devise_controller?"
+          return true if devise_controller?(ctrl)
+        end
+
+        # if: :devise_controller? — filter ONLY applies to Devise controllers
+        if filter[:if] == "devise_controller?"
+          return true unless devise_controller?(ctrl)
+        end
+
+        false
+      end
+
+      def devise_controller?(ctrl)
+        return false unless defined?(::DeviseController)
+        ctrl < ::DeviseController || ctrl.ancestors.any? { |a| a.name&.start_with?("Devise::") }
+      rescue
+        false
+      end
+
       def extract_action_condition(condition)
         return nil unless condition.is_a?(String) || condition.respond_to?(:to_s)
         match = condition.to_s.match(/action_name\s*==\s*['"](\w+)['"]/)

data/lib/rails_ai_context/introspectors/design_token_introspector.rb

@@ -32,6 +32,7 @@ module RailsAiContext
         extract_css_custom_properties(root, tokens)
         extract_webpacker_styles(root, tokens)
         extract_component_css(root, tokens)
+        extract_apply_directives(root, tokens)
 
         return { skipped: true, reason: "No design tokens found" } if tokens.empty?
 
@@ -48,20 +49,29 @@ module RailsAiContext
 
       def detect_framework(root)
         gemfile = File.join(root, "Gemfile")
-        return "unknown" unless File.exist?(gemfile)
-        content = File.read(gemfile, encoding: "UTF-8", invalid: :replace, undef: :replace)
+        package_json = File.join(root, "package.json")
+        gemfile_content = File.exist?(gemfile) ? (File.read(gemfile, encoding: "UTF-8", invalid: :replace, undef: :replace) rescue "") : ""
+        pkg_content = File.exist?(package_json) ? (File.read(package_json, encoding: "UTF-8", invalid: :replace, undef: :replace) rescue "") : ""
 
-        if content.include?("tailwindcss-rails")
+        framework = if gemfile_content.include?("tailwindcss-rails")
           "tailwind"
-        elsif content.include?("bootstrap")
+        elsif gemfile_content.include?("bootstrap")
           "bootstrap"
-        elsif content.include?("dartsass-rails") || content.include?("sassc-rails") || content.include?("sass-rails")
+        elsif gemfile_content.include?("dartsass-rails") || gemfile_content.include?("sassc-rails") || gemfile_content.include?("sass-rails")
           "sass"
-        elsif content.include?("cssbundling-rails")
+        elsif gemfile_content.include?("cssbundling-rails")
           "cssbundling"
         else
           "plain_css"
         end
+
+        # DS17: Detect Tailwind plugin libraries
+        plugins = []
+        plugins << "daisyui" if pkg_content.include?("daisyui") || gemfile_content.include?("daisyui")
+        plugins << "flowbite" if pkg_content.include?("flowbite")
+        plugins << "headlessui" if pkg_content.include?("headlessui") || pkg_content.include?("@headlessui")
+
+        plugins.any? ? "#{framework}+#{plugins.join('+')}" : framework
       rescue
         "unknown"
       end
@@ -238,6 +248,18 @@ module RailsAiContext
         categories.reject { |_, v| v.empty? }
       end
 
+      # DS16: Extract @apply directives as named component classes
+      def extract_apply_directives(root, tokens)
+        %w[app/assets/stylesheets app/assets/tailwind].each do |dir|
+          Dir.glob(File.join(root, dir, "**", "*.css")).each do |path|
+            content = File.read(path, encoding: "UTF-8", invalid: :replace, undef: :replace) rescue next
+            content.scan(/\.([a-zA-Z][\w-]*)\s*\{[^}]*@apply\s+([^;]+);/m).each do |name, classes|
+              tokens["@apply-#{name}"] = classes.strip
+            end
+          end
+        end
+      end
+
       # Helper: extract :root { --var: value } from CSS content
       def extract_root_vars(content, tokens)
         content.scan(/:root\s*(?:,\s*:host)?\s*\{([^}]+)\}/m).each do |match|

data/lib/rails_ai_context/introspectors/model_introspector.rb

@@ -47,11 +47,33 @@ module RailsAiContext
       def discover_models
         return [] unless defined?(ActiveRecord::Base)
 
-        ActiveRecord::Base.descendants.reject do |model|
+        models = ActiveRecord::Base.descendants.reject do |model|
           model.abstract_class? ||
             model.name.nil? ||
             config.excluded_models.include?(model.name)
-        end.sort_by(&:name)
+        end
+
+        # Filesystem fallback — discover model files not yet loaded by descendants
+        models_dir = File.join(app.root.to_s, "app", "models")
+        if Dir.exist?(models_dir)
+          known = models.map(&:name).to_set
+          Dir.glob(File.join(models_dir, "**", "*.rb")).each do |path|
+            relative = path.sub("#{models_dir}/", "").sub(/\.rb\z/, "")
+            class_name = relative.camelize
+            next if known.include?(class_name)
+            next if config.excluded_models.include?(class_name)
+
+            begin
+              klass = class_name.constantize
+              next unless klass < ActiveRecord::Base && !klass.abstract_class?
+              models << klass
+            rescue NameError, LoadError
+              # Not a valid model class
+            end
+          end
+        end
+
+        models.uniq.sort_by(&:name)
       end
 
       def extract_model_details(model)
@@ -196,29 +218,117 @@ module RailsAiContext
         RailsAiContext.configuration.excluded_concerns.any? { |pattern| name.match?(pattern) }
       end
 
+      DEVISE_CLASS_METHOD_PATTERNS = %w[
+        authentication_keys= case_insensitive_keys= strip_whitespace_keys=
+        reset_password_keys= confirmation_keys= unlock_keys=
+        email_regexp= password_length= timeout_in= remember_for=
+        sign_in_after_reset_password= sign_in_after_change_password=
+        reconfirmable= extend_remember_period= pepper=
+        stretches= allow_unconfirmed_access_for=
+        confirm_within= remember_for= unlock_in=
+        lock_strategy= unlock_strategy= maximum_attempts=
+        paranoid= last_attempt_warning=
+      ].to_set.freeze
+
       def extract_public_class_methods(model)
         scope_names = extract_scopes(model).map(&:to_s)
-        (model.methods - ActiveRecord::Base.methods - Object.methods)
+
+        # Prioritize methods defined in the model's own source file
+        source_methods = extract_source_class_methods(model)
+
+        all_methods = (model.methods - ActiveRecord::Base.methods - Object.methods)
           .reject { |m|
             ms = m.to_s
-            ms.start_with?("_", "autosave") || scope_names.include?(ms)
+            ms == "self" ||
+              ms.start_with?("_", "autosave") ||
+              scope_names.include?(ms) ||
+              DEVISE_CLASS_METHOD_PATTERNS.include?(ms) ||
+              ms.end_with?("=") && ms.length > 20 # Devise setter-like methods
           }
-          .sort
-          .first(30) # Cap to avoid noise
           .map(&:to_s)
+          .sort
+
+        # Source-defined methods first, then reflection-discovered ones
+        ordered = source_methods + (all_methods - source_methods)
+        ordered.first(30)
       end
 
+      def extract_source_class_methods(model)
+        path = model_source_path(model)
+        return [] unless path && File.exist?(path)
+
+        source = File.read(path)
+        methods = []
+        in_class_methods = false
+        source.each_line do |line|
+          in_class_methods = true if line.match?(/\A\s*(?:class << self|def self\.)/)
+          if line.match?(/\A\s*def self\.(\w+)/)
+            methods << line.match(/def self\.(\w+)/)[1]
+          end
+          if in_class_methods && line.match?(/\A\s*def (\w+)/)
+            methods << line.match(/def (\w+)/)[1]
+          end
+          in_class_methods = false if in_class_methods && line.match?(/\A\s*end\s*$/) && !line.match?(/def/)
+        end
+        methods.uniq
+      rescue
+        []
+      end
+
+      DEVISE_INSTANCE_PATTERNS = %w[
+        password_required? email_required? confirmation_required?
+        active_for_authentication? inactive_message authenticatable_salt
+        after_database_authentication send_devise_notification
+        send_confirmation_instructions send_reset_password_instructions
+        send_unlock_instructions send_on_create_confirmation_instructions
+        devise_mailer clean_up_passwords skip_confirmation!
+        skip_reconfirmation! valid_password? update_with_password
+        destroy_with_password remember_me! forget_me!
+        unauthenticated_message confirmation_period_valid?
+        pending_reconfirmation? reconfirmation_required?
+        send_email_changed_notification send_password_change_notification
+      ].to_set.freeze
+
       def extract_public_instance_methods(model)
         generated = generated_association_methods(model)
 
-        (model.instance_methods - ActiveRecord::Base.instance_methods - Object.instance_methods)
+        # Prioritize source-defined methods
+        source_methods = extract_source_instance_methods(model)
+
+        all_methods = (model.instance_methods - ActiveRecord::Base.instance_methods - Object.instance_methods)
           .reject { |m|
             ms = m.to_s
-            ms.start_with?("_", "autosave", "validate_associated") || generated.include?(ms)
+            ms.start_with?("_", "autosave", "validate_associated") ||
+              generated.include?(ms) ||
+              DEVISE_INSTANCE_PATTERNS.include?(ms) ||
+              ms.match?(/\Awill_save_change_to_|_before_last_save\z|_in_database\z|_before_type_cast\z/)
           }
-          .sort
-          .first(30)
           .map(&:to_s)
+          .sort
+
+        # Source-defined methods first
+        ordered = source_methods + (all_methods - source_methods)
+        ordered.first(30)
+      end
+
+      def extract_source_instance_methods(model)
+        path = model_source_path(model)
+        return [] unless path && File.exist?(path)
+
+        source = File.read(path)
+        methods = []
+        in_private = false
+        source.each_line do |line|
+          in_private = true if line.match?(/\A\s*private\s*$/)
+          next if in_private
+          next if line.match?(/\A\s*def self\./)
+          if (match = line.match(/\A\s*def (\w+[?!]?)/))
+            methods << match[1] unless match[1] == "initialize"
+          end
+        end
+        methods.uniq
+      rescue
+        []
       end
 
       # Build list of AR-generated association helper method names to exclude