rails-ai-context 5.36.3 → 5.36.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ecc8cfb0b751983a682c2a2c0bd2082216595b83f12f679d190506425d60ae48
-  data.tar.gz: e0674fed2e5f40ebe3f33166c59d9c17bcd5c5160352100cf8b38d87a73387a4
+  metadata.gz: d19c2da6b45c1d8622c9d97bf31f005a10a904c1c6361c9f2d4d75819bdb236d
+  data.tar.gz: cdc5979f3619e5823f7a3b158864e4c0fe1b2e62037074925334dcfbef50ce2b
 SHA512:
-  metadata.gz: c78d50c7e050632c88f60e901a8805ed5d397f2f12fb9412fa7ac64af1ed3921ff776486a8e4912f0a5a531e6a90661ca6d7b35def872bc4cd11215bde2941b0
-  data.tar.gz: 0b597f6cc7372007cb84936ac62f2ca893791622c62a667ea4601b545c73a9719949f3abfc09fd8fe75fe2e143fb1bfa5a4bbf82ee47e4f5fca6d293392c5b9d
+  metadata.gz: bd790f4fe94ffd61064e3d65d62335de351af8c7d90669370c4b42c6cb37b1284dbf62c6ca3160d1ac7ee801dbf378c40764b361f6903197716823849246d238
+  data.tar.gz: '083dcf1bdcbe006da36854877cae12ae6bdea0282f8411686609e85b4fd029adf62f430f3c5780c78f624059757b46ec58bb188d48a017a7e9451e1ee3253bb4'

data/CHANGELOG.md

@@ -5,6 +5,87 @@ 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.36.5] - 2026-10-19
+
+### Added
+
+- **`rails_get_edit_context` takes a `line`.** It shows `context_lines` either
+  side of that line, so a line from a stack trace needs no text to search for.
+  `near` is needed only without one.
+
+### Fixed
+
+- **`rails_diagnose` shows the code around the line it was given** (#495). It
+  searched for the method name and opened on its first mention, a comment
+  included, so the failing line was missing from the code shown in 18 of 30
+  real calls on one app. It also reads a setter's name (`title=`) and an index
+  call's (`[]`), and names their nil receiver.
+- **`rails_migration_advisor` points a foreign key at the key of a table not
+  keyed by `id`** (#496): `foreign_key: { primary_key: :bid }`, where
+  `foreign_key: true` made PostgreSQL refuse the migration. A table with a
+  composite primary key, and a `t.references` table the schema lacks, get no
+  foreign key and a line saying why.
+- **`rails_migration_advisor` types a reference the way the key it points at
+  is typed** (#501). A reference to an `integer` key gets `type: :integer`
+  and the key's `limit:` when it has one, and on MySQL one to an `unsigned`
+  key gets `unsigned: true`. It wrote Rails' default signed bigint, and MySQL
+  and MariaDB refuse a foreign key whose column differs from the key, so the
+  migration failed. PostgreSQL, which accepted the bigint, now gets the
+  matching type too. A `serial` key gives `integer` and a `smallserial` one
+  `smallint`, where the reference used to get a sequence of its own that
+  filled it with a made-up owner. SQLite, where every key is an integer,
+  still gets no type.
+- **`rails_analyze_feature` lists every service, view and spec whose name
+  matches** (#497), wherever it sorts. Only the files it reads stop at 500 per
+  directory, and the closing note says which directory past them was matched
+  by name alone. The test gap list reads the name of every test, so it is no
+  longer left out on a suite of more than 500.
+- **`conventions` counts the TypeScript, JSX and Vue files of `app/javascript`**
+  (#498), and the `.ruby` templates of `app/views`. Mastodon's `app/javascript`
+  read 78 files; it holds 922. An edit to one of those files, or to a
+  `.jbuilder` or `.builder` view, now refreshes the cached answers, as one to a
+  `.js` or `.erb` file did.
+- **`rails_migration_advisor`'s Strong Migrations warning for `add_association`
+  rewrites the `add_reference` it wrote** (#499). It named the reference as the
+  table (`add_foreign_key :listings, :owner`) and added a second key after the
+  migration had added one. On PostgreSQL it now gives the reference with
+  `disable_ddl_transaction!` and a concurrent index, the key in its own
+  `add_foreign_key ... validate: false` (strong_migrations before 2.5.2 flags any
+  foreign key inside `add_reference`), then `validate_foreign_key` with
+  the real table and column. On MySQL it moves the key to a separate
+  migration, as strong_migrations 2.7 and later require; an older locked version,
+  which does not check a MySQL key, gets no warning. A reference with no
+  foreign key gets only the concurrent index on PostgreSQL and nothing on
+  MySQL, and SQLite, which strong_migrations does not check, gets nothing. A
+  reference whose column already exists gets no warning, since its migration
+  fails first, and an undecided database gets one line when the reference has
+  a key.
+
+## [5.36.4] - 2026-10-16
+
+### Added
+
+- **The standalone binary says when a newer release is out.** A copy installed
+  with `gem install` stayed at its version until someone thought to update it.
+  It now asks rubygems.org for the latest version at most once a day, in a
+  detached child process, and keeps the answer under `$XDG_STATE_HOME`
+  (`~/.local/state/rails-ai-context/latest`). A command run in a terminal prints
+  one line on stderr naming the Ruby to update under and the two commands to
+  run. The MCP server adds the line to its instructions and to the end of
+  `rails_onboard` for the agent to pass on, or asks for a restart when the new
+  version is already installed. `RAILS_AI_CONTEXT_NO_UPDATE_CHECK=1` turns it
+  off. It is off in CI, on a prerelease, for an older version run on purpose
+  (`_5.30.0_`) and in a copy the app's bundle runs. Nothing is installed for you.
+
+### Fixed
+
+- **The code reads prism 2 the way it reads prism 1.** prism's main branch
+  (2.0.0.rc1) parses with the running Ruby's grammar when it is given none,
+  replaced `MissingNode` with `ErrorRecoveryNode`, and leaves an unterminated
+  heredoc without a closing location. The gem now names the newest grammar
+  when it parses and lexes, reads either recovery node, and ends an
+  unterminated heredoc at its body. The gemspec still requires prism below 2.0.
+
 ## [5.36.3] - 2026-10-15
 
 ### Fixed

data/SECURITY.md

@@ -32,4 +32,4 @@ If you discover a security vulnerability in rails-ai-context, please report it r
 - **Migration input validation** - `rails_migration_advisor` validates table and column names as safe identifiers before generating migration code.
 - **Cache invalidation coverage** - Fingerprinter watches `app/components`, `package.json`, and `tsconfig.json` alongside models/controllers/views to prevent stale tool responses.
 - **Fetch size limits** - `rails_search_docs` caps fetched documentation content at 2MB to prevent memory exhaustion.
-- The gem makes outbound HTTPS requests only when `rails_search_docs` is called with `fetch: true` (to fetch Rails documentation from GitHub raw content). All other tools are offline.
+- The gem makes outbound HTTPS requests in two places. `rails_search_docs` fetches Rails documentation from GitHub raw content when called with `fetch: true`. The standalone binary (installed with `gem install`, not through the app's Gemfile) asks `https://rubygems.org/api/v1/versions/rails-ai-context/latest.json` for the latest version at most once a day, in a child process that sends nothing about the app, and writes the answer to `rails-ai-context/latest` under `$XDG_STATE_HOME` (`~/.local/state`). `RAILS_AI_CONTEXT_NO_UPDATE_CHECK=1` turns it off; it is off in CI and in a copy the app's bundle runs. All other tools are offline.

data/docs/COMPATIBILITY.md

@@ -340,6 +340,20 @@ Proof sources:
    with Rails 7.0 and 7.2, Ruby 3.3 with Rails 7.1, Ruby 3.4 with Rails 8.0 and
    8.1, and Ruby 4.0 with Rails 8.1; and the unit suite and the E2E harness on
    Linux, macOS and Windows.
+   In the v5.36.4 release QA: the update check run as the installed binary on
+   Ruby 3.1, 3.3, 3.4 and 4.0 against rubygems.org, through a terminal and over
+   MCP stdio on a fixture app, a large private app booted and another in the
+   static tier, with the app's pinned json and net-http still loaded; the
+   suite on prism 1.4.0 and on prism main under Ruby 3.2 and 3.4; and the unit
+   suite and the E2E harness on Linux, macOS and Windows.
+   In the v5.36.5 release QA: each fix's example failing on the code before
+   it; the advice `rails_migration_advisor` writes run as real migrations
+   under strong_migrations 1.8 to 2.8 and Active Record 7.0 to 8.1 against
+   PostgreSQL 13, 16 and 17, MySQL 8.0 and 8.4, MariaDB 10.6 and 11.4 and
+   SQLite, for bigint, integer, unsigned, serial and uuid keys; its answers on
+   three corpus apps in the static tier; the unit suite on Ruby 3.1 to 4.0
+   with Rails 7.0 to 8.1 on macOS, with seeds 1, 27377 and 90210 and defined
+   order; and the unit suite and the E2E harness on Linux, macOS and Windows.
 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

@@ -266,6 +266,7 @@ server entry's `env`.
 | Variable | Read by | Effect |
 |:---------|:--------|:-------|
 | `RAILS_AI_CONTEXT_BOOT_TIMEOUT` | Every command that boots the app, and the `ai:serve`, `ai:serve_http` and `ai:tool` rake tasks | Seconds a boot may take before it counts as failed; a command that can then answers from the static tier. Default 20 for `serve` over stdio and `rails ai:serve`, whose client waits about 30 seconds for its first answer, and 60 for everything else. A value that is not a whole number warns and keeps the default |
+| `RAILS_AI_CONTEXT_NO_UPDATE_CHECK` | The standalone binary | Any non-empty value turns off the daily check for a newer release on rubygems.org. The check also stays off in CI, on a prerelease and in a copy the app's bundle runs |
 | `RAILS_AI_CONTEXT_SERVER_NAME` | The MCP server | The name it announces for one process, in place of the default `server_name`; a `server_name` the app sets wins. A workspace's MCP entries set it |
 | `DEBUG` | Every command and the MCP server | Any value prints the backtrace of a failed boot, a failed command and an exception that escapes a tool, and names the errors a fallback swallows |
 | `RAILS_ENV`, `RACK_ENV` | Every command | The Rails environment to boot, read the way Rails reads it; `--environment` sets it for one command. Default `development` |

data/docs/GUIDE.md

@@ -700,8 +700,9 @@ Returns just enough context to make a surgical Edit to a file. Returns the targe
 | Param | Type | Description |
 |-------|------|-------------|
 | `file` | string | **Required.** File path relative to Rails root (e.g. `app/models/post.rb`). |
-| `near` | string | **Required.** What to find - a method name, keyword, or string to locate (e.g. `scope`, `def index`). |
+| `near` | string | **Required** unless `line` is given. What to find - a method name, keyword, or string to locate (e.g. `scope`, `def index`). |
 | `context_lines` | integer | Lines of context above and below the match. Default: 5. |
+| `line` | integer | Show `context_lines` either side of this line number instead of searching for `near`. |
 
 **Examples:**
 

data/docs/SECURITY.md

@@ -18,7 +18,7 @@
 1. **Read-only by design** - All 35 tools are annotated as non-destructive in the MCP protocol
 2. **Defense in depth** - Multiple security layers, not single points of failure
 3. **Sensitive data blocking** - Configurable patterns prevent access to secrets
-4. **Offline by default** - No network calls except optional `rails_search_docs` with `fetch: true`
+4. **Offline except where named** - No network calls except optional `rails_search_docs` with `fetch: true`, and the standalone binary's daily version check against rubygems.org (`RAILS_AI_CONTEXT_NO_UPDATE_CHECK=1` turns it off)
 5. **Graceful degradation** - Missing optional dependencies don't expose errors or state
 
 ---

data/docs/STANDALONE.md

@@ -140,6 +140,26 @@ Codex CLI is special - it `env_clear()`s the process before spawning MCP servers
 
 If you switch Ruby versions, re-run `rails-ai-context init` to update the snapshot.
 
+## Updating
+
+A gem installed with `gem install` stays at its version until you update it:
+
+```bash
+gem update rails-ai-context
+rails-ai-context init --defaults   # in each app: brings its MCP configs and context files up to the new version
+```
+
+Each Ruby has its own copy, so update under the Ruby your AI client starts the
+server with. Restart the AI client afterwards so its MCP server runs the new copy.
+
+The binary checks rubygems.org for a newer release at most once a day, in the
+background. When there is one, a command run in a terminal says so on stderr,
+and the MCP server tells the agent to pass it on, in its instructions and at the
+end of `rails_onboard`. A server reads the answer the check left the last time,
+so the first check shows up from the next start. `RAILS_AI_CONTEXT_NO_UPDATE_CHECK=1` turns the check off.
+It stays off in CI and in a copy the app's bundle runs, where the lockfile picks
+the version.
+
 ## Switching between standalone and in-Gemfile
 
 You can switch freely:

data/docs/TOOLS.md

@@ -104,8 +104,9 @@ Method-aware code extraction with surrounding class context. Every line returned
 | Parameter | Type | Default | Description |
 |:----------|:-----|:--------|:------------|
 | `file` | string | *required* | File path relative to Rails root |
-| `near` | string | *required* | What to find in the file: a method name, keyword or string (e.g. `def index`, `validates`, `STATUSES`) |
+| `near` | string | *required* unless `line` | What to find in the file: a method name, keyword or string (e.g. `def index`, `validates`, `STATUSES`) |
 | `context_lines` | integer | `5` | Lines of context above and below the match |
+| `line` | integer | - | Show `context_lines` either side of this line instead of searching for `near`; past the end of the file, `near` is searched for |
 
 <p align="right"><a href="#table-of-contents">↑ back to top</a></p>
 

data/exe/rails-ai-context

@@ -201,7 +201,10 @@ class RailsAiContextCLI < Thor
     # One answer for any command's failure; Thor's refusals and SystemExit pass through.
     no_commands do
       def invoke_command(command, *args)
-        super
+        start_update_check
+        result = super
+        check_for_update
+        result
       rescue Thor::Error
         raise
       rescue StandardError, ScriptError => e
@@ -319,6 +322,7 @@ class RailsAiContextCLI < Thor
       # No Thor default: it would overwrite the config file's http_port.
       ::RailsAiContext.configuration.http_port = options[:port] if options[:port]
 
+      start_update_check&.refresh(env: STARTING_ENV)
       ::RailsAiContext.start_mcp_server(transport: transport)
     end
 
@@ -1326,6 +1330,29 @@ class RailsAiContextCLI < Thor
       nil
     end
 
+    # A notice on a terminal only: stdout may be piped, and an agent reads rails_onboard's copy instead.
+    def check_for_update
+      check = start_update_check or return
+      check.refresh(env: STARTING_ENV)
+      note = check.notice unless check.told?
+      $stderr.puts note if note && $stderr.tty?
+    rescue StandardError, ScriptError
+      nil
+    end
+
+    # Only this copy run outside a bundle checks; under bundle exec the app's lockfile picks the version.
+    # Started before the command, while Gem.path is still the one an app's boot replaces.
+    def start_update_check
+      return if STARTING_ENV["BUNDLE_BIN_PATH"]
+
+      @start_update_check ||= begin
+        require_relative "../lib/rails_ai_context/update_check"
+        ::RailsAiContext::UpdateCheck.tap(&:enable!)
+      end
+    rescue StandardError, ScriptError
+      nil
+    end
+
     # Stdlib only, so it is safe to load before the app boots.
     def entry_boot
       @entry_boot ||= begin

data/lib/rails_ai_context/ast_cache.rb

@@ -80,14 +80,14 @@ module RailsAiContext
     # A one-shot parse that stores nothing: for a scan reading thousands of
     # files once, whose entries would only evict what other readers reuse.
     def self.parse_uncached(source)
-      Prism.parse(source)
+      Prism.parse(source, version: NEWEST_GRAMMAR)
     end
 
     # Whether a file parses under `ruby:`'s grammar, with no tree built or
     # kept: the check before a loader requires each file it walks.
     def self.parse_success?(path, ruby: nil)
       version = prism_version(ruby)
-      version ? Prism.parse_file_success?(path, version: version) : Prism.parse_file_success?(path)
+      Prism.parse_file_success?(path, version: version || NEWEST_GRAMMAR)
     end
 
     # Parse a Ruby source string, cached by content digest, so every extractor
@@ -112,6 +112,8 @@ module RailsAiContext
     private_class_method :content_key
 
     OLDEST_GRAMMAR = "3.3"
+    # Named, because prism 2 parses with the running Ruby's grammar when given none.
+    NEWEST_GRAMMAR = "latest"
     GRAMMARS = Concurrent::Map.new # major.minor => whether the loaded prism parses it
 
     # The grammar prism parses `ruby` with: its own major.minor, the oldest prism
@@ -134,7 +136,7 @@ module RailsAiContext
     private_class_method :supported?
 
     def self.prism_parse(source, version)
-      version ? Prism.parse(source, version: version) : Prism.parse(source)
+      Prism.parse(source, version: version || NEWEST_GRAMMAR)
     end
     private_class_method :prism_parse
 

data/lib/rails_ai_context/fingerprinter.rb

@@ -50,7 +50,7 @@ module RailsAiContext
     # a change and a walk that names it read the same tree.
     # sql: a structure dump, under whatever name database.yml's schema_dump gives it.
     # tt: a generator template override under lib/templates.
-    WATCHED_EXTNAMES = %w[.rb .rake .js .ts .erb .haml .slim .yml .sql .tt].freeze
+    WATCHED_EXTNAMES = %w[.rb .rake .js .jsx .mjs .cjs .ts .tsx .vue .svelte .erb .haml .slim .jbuilder .builder .ruby .yml .sql .tt].freeze
     WATCHED_EXTENSIONS = "**/*{#{WATCHED_EXTNAMES.join(",")}}"
 
     # jsbundling and cssbundling rewrite this on every frontend save, and no reader reads it.

data/lib/rails_ai_context/introspectors/convention_introspector.rb

@@ -172,11 +172,12 @@ module RailsAiContext
         RailsAiContext.debug_fail(e, false, label: "uses_async_queries?")
       end
 
+      SCRIPT_FILES = "**/*.{js,jsx,mjs,cjs,ts,tsx,vue,svelte}"
       # Files a directory holds besides Ruby, which SourceScan leaves out.
       NON_RUBY_FILES = {
-        "app/javascript" => "**/*.js",
-        "app/javascript/controllers" => "**/*.js",
-        "app/views" => "**/*.{erb,haml,slim,jbuilder,builder}",
+        "app/javascript" => SCRIPT_FILES,
+        "app/javascript/controllers" => SCRIPT_FILES,
+        "app/views" => "**/*.{erb,haml,slim,jbuilder,builder,ruby}",
         "lib/tasks" => "**/*.rake"
       }.freeze
 

data/lib/rails_ai_context/introspectors/listeners/base_listener.rb

@@ -122,7 +122,7 @@ module RailsAiContext
         end
 
         def lex(text)
-          Prism.lex(text).value.map(&:first)
+          Prism.lex(text, version: AstCache::NEWEST_GRAMMAR).value.map(&:first)
         rescue StandardError
           []
         end

data/lib/rails_ai_context/introspectors/listeners/queue_assignment_listener.rb

@@ -9,6 +9,9 @@ module RailsAiContext
       # and Que's `self.queue = "name"`, or a `def self.queue` returning one, which
       # Resque asks for when @queue is unset. A literal is kept as its value, anything else as source.
       class QueueAssignmentListener < BaseListener
+        # What a half-written `@queue =` parses its value as: MissingNode before prism 2, ErrorRecoveryNode from it.
+        RECOVERY_NODES = %i[MissingNode ErrorRecoveryNode].filter_map { |name| Prism.const_get(name) if Prism.const_defined?(name, false) }.freeze
+
         def initialize
           super
           @def_depth = 0
@@ -40,9 +43,8 @@ module RailsAiContext
 
         private
 
-        # A half-written `@queue =` parses with a MissingNode value.
         def record(node, value, form)
-          return if value.is_a?(Prism::MissingNode)
+          return if RECOVERY_NODES.any? { |type| value.is_a?(type) }
 
           literal = value.is_a?(Prism::SymbolNode) || value.is_a?(Prism::StringNode)
           @results << { form: form, queue: literal ? value.unescaped : nil, source: value.slice,

data/lib/rails_ai_context/introspectors/node_source.rb

@@ -18,12 +18,12 @@ module RailsAiContext
       # @return [String] the node's slice, followed by the body of every
       #   heredoc it opens whose body lies past its end
       def text(node)
-        trailing = heredocs(node).select { |doc| doc.closing_loc.end_offset > node.location.end_offset }
+        trailing = heredocs(node).select { |doc| body_end(doc).end_offset > node.location.end_offset }
         return node.slice if trailing.empty?
 
         first = trailing.min_by { |doc| body_start(doc).start_offset }
-        last = trailing.max_by { |doc| doc.closing_loc.end_offset }
-        "#{node.slice}\n#{body_start(first).join(last.closing_loc).slice}"
+        last = trailing.max_by { |doc| body_end(doc).end_offset }
+        "#{node.slice}\n#{body_start(first).join(body_end(last)).slice}"
       end
 
       def heredocs(node)
@@ -40,9 +40,14 @@ module RailsAiContext
       def body_start(doc)
         if doc.respond_to?(:content_loc) then doc.content_loc
         elsif doc.parts.any? then doc.parts.first.location
-        else doc.closing_loc
+        else body_end(doc)
         end
       end
+
+      # The terminator; an unterminated heredoc has none from prism 2 on, and ends with its body.
+      def body_end(doc)
+        doc.closing_loc || (doc.content_loc if doc.respond_to?(:content_loc)) || doc.parts.last&.location || doc.location
+      end
     end
   end
 end

data/lib/rails_ai_context/server.rb

@@ -273,11 +273,15 @@ module RailsAiContext
     # code changed (BaseTool.stale_code_note).
     def self.instructions
       intro = "Ground truth engine for Rails apps. Live Prism AST introspection."
-      return "#{intro} Answers follow edits to the app's files." if CodeReloader.reloadable? || RailsAiContext.static_tier?
-
-      "#{intro} Answers follow edits to the app's files, except what reflection reads, such as associations: " \
-        "RAILS_ENV=#{RailsAiContext.environment_name} does not reload code, so that stays as of boot, and every " \
-        "answer says when app code changed since."
+      text = if CodeReloader.reloadable? || RailsAiContext.static_tier?
+        "#{intro} Answers follow edits to the app's files."
+      else
+        "#{intro} Answers follow edits to the app's files, except what reflection reads, such as associations: " \
+          "RAILS_ENV=#{RailsAiContext.environment_name} does not reload code, so that stays as of boot, and every " \
+          "answer says when app code changed since."
+      end
+      note = UpdateCheck.agent_note
+      note ? "#{text} #{note}" : text
     end
 
     # Anything that still escapes a tool (schema validation bugs, SDK-level

data/lib/rails_ai_context/tools/analyze_feature.rb

@@ -33,12 +33,8 @@ module RailsAiContext
       # Map well-known feature keywords to gem-based patterns
       AUTH_KEYWORDS = %w[auth authentication login signup signin session devise omniauth].freeze
 
-      # Cap per-directory file scans to avoid unbounded work on large monorepos.
-      # Note: Dir.glob materialises the full path array before .first() truncates.
-      # the directory walk itself is unbounded; only per-file reading and processing
-      # is capped at MAX_SCAN_FILES. Applied to every discover_* method that walks
-      # the filesystem. Tool output notes when the cap is hit so the AI agent knows
-      # to narrow its feature keyword. v5.8.1 hardening; all glob sites in r2.
+      # Names are matched over every file a glob finds; only the files read per directory, and the
+      # matches listed per section, stop at MAX_SCAN_FILES, and the answer says where they did.
       MAX_SCAN_FILES = 500
       # The callers named under each service; rails_get_service_pattern(service:) lists more.
       CALLERS_SHOWN = 5
@@ -70,16 +66,16 @@ module RailsAiContext
         discover_services(root, pattern, lines, unread)
         discover_admin(root, pattern, lines)
         discover_jobs(ctx, pattern, lines)
-        discover_views(ctx, root, pattern, lines, unread)
+        discover_views(ctx, root, pattern, lines)
         discover_stimulus(ctx, pattern, lines)
-        _feature_tests, all_tests, tests_truncated = discover_tests(root, pattern, lines, unread)
+        all_tests = discover_tests(root, pattern, lines)
         discover_related_models(ctx, matched_models, lines)
         discover_concerns(ctx, matched_models, lines)
         discover_callbacks(ctx, matched_models, lines)
         discover_channels(ctx, pattern, lines)
         discover_mailers(ctx, pattern, lines)
-        discover_env_dependencies(root, pattern, matched_models, lines, unread)
-        discover_test_gaps(root, pattern, matched_models, ctx, all_tests || [], lines, unread, truncated: tests_truncated)
+        discover_env_dependencies(root, pattern, matched_models, lines)
+        discover_test_gaps(root, pattern, matched_models, ctx, all_tests, lines)
         discover_components(ctx, pattern, lines)
 
         # For auth-related keywords, also discover auth gems
@@ -103,11 +99,11 @@ module RailsAiContext
         text_response(lines.join("\n") + unread_note(unread))
       end
 
-      # Files past MAX_SCAN_FILES in a directory are never read, so a section that is missing may only be unread.
+      # Files past MAX_SCAN_FILES in a directory are matched by name alone, so a match by content may be missing.
       def self.unread_note(unread)
         return "" if unread.empty?
 
-        "\n\n_Only the first #{MAX_SCAN_FILES} files of a directory are read, so any past them in #{unread.sort.join(', ')} were not checked._"
+        "\n\n_Only the first #{MAX_SCAN_FILES} files of a directory are read, so any past them in #{unread.sort.join(', ')} were matched by name alone._"
       end
 
       # The names a keyword that matched nothing could have been.
@@ -123,12 +119,7 @@ module RailsAiContext
       class << self
         private
 
-        # The first MAX_SCAN_FILES of a glob; a directory holding more goes into `unread`.
-        def capped_glob(dir, pattern, real_root, label, unread)
-          files = safe_glob(dir, pattern, real_root)
-          unread << label if files.size > MAX_SCAN_FILES
-          files.first(MAX_SCAN_FILES)
-        end
+        def listed_suffix(found) = found.size > MAX_SCAN_FILES ? " - first #{MAX_SCAN_FILES} listed" : ""
 
         # A conditional skip names the condition it is taken out on.
         def inherited_filter_label(filter)
@@ -281,17 +272,17 @@ module RailsAiContext
 
           real_root = File.realpath(root).to_s
           real_dir = File.realpath(dir).to_s
-          candidates = capped_glob(dir, "**/*.rb", real_root, "app/services", unread)
-          # Prefer basename match (fast, no file read) and only fall back to
-          # a content scan for files whose basename doesn't match. This
-          # avoids reading every service file's full contents on large apps.
-          found = candidates.select do |path|
-            next true if feature_word_match?(File.basename(path, ".rb"), pattern)
+          files = safe_glob(dir, "**/*.rb", real_root)
+          # A name matches without a read; only the files whose name does not are read for the word.
+          by_name, rest = files.partition { |path| feature_word_match?(File.basename(path, ".rb"), pattern) }
+          unread << "app/services" if rest.size > MAX_SCAN_FILES
+          by_content = rest.first(MAX_SCAN_FILES).select do |path|
             File.size(path) < 50_000 && feature_word_match?(RailsAiContext::SafeFile.read(path), pattern)
           end
+          found = files & (by_name + by_content)
           return if found.empty?
 
-          services = found.filter_map do |path|
+          services = found.first(MAX_SCAN_FILES).filter_map do |path|
             source = RailsAiContext::SafeFile.read(path) or next
             # The path carries the namespace Zeitwerk expects, as rails_get_service_pattern reads it.
             constant = path.delete_prefix("#{real_dir}/").delete_suffix(".rb").camelize
@@ -302,7 +293,7 @@ module RailsAiContext
           named = services.select { |s| s[:name] }
           callers, callers_truncated = GetServicePattern.callers_of(named.to_h { |s| [ s[:name], s[:path] ] }, real_root)
 
-          lines << "## Services (#{found.size}#{unread.include?("app/services") ? " - first #{MAX_SCAN_FILES} scanned" : ""})"
+          lines << "## Services (#{found.size}#{listed_suffix(found)})"
           services.each do |service|
             relative = service[:path].sub("#{real_root}/", "")
             methods = service[:name] ? service_methods(service[:source], service[:name]) : []
@@ -368,20 +359,19 @@ module RailsAiContext
         end
 
         # --- AF3: Views + Partials ---
-        def discover_views(ctx, root, pattern, lines, unread)
+        def discover_views(ctx, root, pattern, lines)
           views_dir = File.join(root, "app", "views")
           return unless Dir.exist?(views_dir)
 
           real_root = File.realpath(root).to_s
           real_views_dir = File.realpath(views_dir).to_s
-          candidates = capped_glob(views_dir, "**/*.{erb,haml,slim,jbuilder}", real_root, "app/views", unread)
-          found = candidates.select do |path|
+          found = safe_glob(views_dir, "**/*.{erb,haml,slim,jbuilder}", real_root).select do |path|
             feature_word_match?(path.sub("#{real_views_dir}/", ""), pattern)
           end
           return if found.empty?
 
-          lines << "## Views (#{found.size}#{unread.include?("app/views") ? " - first #{MAX_SCAN_FILES} scanned" : ""})"
-          found.each do |path|
+          lines << "## Views (#{found.size}#{listed_suffix(found)})"
+          found.first(MAX_SCAN_FILES).each do |path|
             relative = path.sub("#{real_views_dir}/", "")
             source = RailsAiContext::SafeFile.read(path) or next
             line_count = source.lines.size
@@ -451,20 +441,17 @@ module RailsAiContext
           relative.sub(%r{(\A|/)(?:spec|test)_}, "\\1")
         end
 
-        # @return [Array(Array<String>, Array<String>, Boolean)] the tests the
-        #   feature word names, every test read (relative to the suite's root),
-        #   and whether a glob stopped at MAX_SCAN_FILES
-        def discover_tests(root, pattern, lines, unread)
+        # @return [Array<String>] every test in the suite, relative to the suite's root
+        def discover_tests(root, pattern, lines)
           real_root = File.realpath(root).to_s
           found = []
           all = []
-          truncated = false
 
           base = RailsAiContext::PathResolver.test_root(root)
           real_base = File.realpath(base).to_s
           [ File.join(base, "spec"), File.join(base, "test") ].each do |dir|
             next unless Dir.exist?(dir)
-            suffix_glob = capped_glob(dir, "**/*_{test,spec}.rb", real_base, File.basename(dir), unread)
+            suffix_glob = safe_glob(dir, "**/*_{test,spec}.rb", real_base)
             # The path, not the basename: the gap checker below matches this
             # way for the same reason, and a spec whose feature word is a
             # directory (billing/invoices/create_spec.rb) is the normal shape
@@ -472,20 +459,18 @@ module RailsAiContext
             suffix_glob.each do |path|
               found << path if feature_word_match?(relative_test_name(path, real_base), pattern)
             end
-            prefix_glob = capped_glob(dir, "**/{test,spec}_*.rb", real_base, File.basename(dir), unread)
+            prefix_glob = safe_glob(dir, "**/{test,spec}_*.rb", real_base)
             prefix_glob.each do |path|
               found << path if feature_word_match?(relative_test_name(path, real_base), pattern)
             end
             all.concat(suffix_glob, prefix_glob)
           end
-          truncated = unread.include?("spec") || unread.include?("test")
           found.uniq!
           all = all.uniq.map { |path| path.delete_prefix("#{real_base}/") }
-          return [ found, all, truncated ] if found.empty?
+          return all if found.empty?
 
-          header = "## Tests (#{found.size}#{truncated ? " - first #{MAX_SCAN_FILES} per glob scanned" : ""})"
-          lines << header
-          found.each do |path|
+          lines << "## Tests (#{found.size}#{listed_suffix(found)})"
+          found.first(MAX_SCAN_FILES).each do |path|
             relative = Pathname.new(path).relative_path_from(Pathname.new(real_root)).to_s
             source = RailsAiContext::SafeFile.read(path) or next
             test_count = source.each_line.count do |line|
@@ -494,19 +479,15 @@ module RailsAiContext
             lines << "- `#{relative}` (#{count_phrase(test_count, "test")})"
           end
           lines << ""
-          [ found, all, truncated ]
+          all
         rescue => e
-          RailsAiContext.debug_fail(e, [ [], [], false ], label: "discover_tests")
+          RailsAiContext.debug_fail(e, [], label: "discover_tests")
         end
 
         # --- Test coverage gaps ---
-        def discover_test_gaps(root, pattern, matched_models, ctx, test_files, lines, unread, truncated: false)
-          # A gap is a claim that something has no test, and a scan that stopped
-          # at MAX_SCAN_FILES cannot make it: Discourse has 1,672 spec files, so
-          # the first 500 missed the ones that cover the feature and every
-          # controller was reported as untested.
-          return if truncated
-
+        # A gap is a claim that something has no test, so it reads the name of every test in the suite:
+        # Discourse has 1,672 spec files, and the first 500 missed the ones that cover the feature.
+        def discover_test_gaps(root, pattern, matched_models, ctx, test_files, lines)
           gaps = []
           # Paths, not basenames: a namespaced name underscores to admin/badges,
           # which no basename can contain, so every namespaced controller was
@@ -540,7 +521,7 @@ module RailsAiContext
             path_dir = File.join(root, "app", dir)
             next unless Dir.exist?(path_dir)
 
-            capped_glob(path_dir, "**/*.rb", real_root, "app/#{dir}", unread).each do |path|
+            safe_glob(path_dir, "**/*.rb", real_root).each do |path|
               snake = File.basename(path, ".rb")
               next unless feature_word_match?(snake, pattern)
               next if test_basenames.any? { |t| t.include?(snake) }
@@ -667,15 +648,19 @@ module RailsAiContext
         end
 
         # --- AF9: Environment Dependencies ---
-        def discover_env_dependencies(root, pattern, matched_models, lines, unread)
+        def discover_env_dependencies(root, pattern, matched_models, lines)
           # Scan services, jobs, and model files for ENV references
           real_root = File.realpath(root).to_s
           dirs = %w[app/services app/jobs].map { |d| File.join(root, d) }.select { |d| Dir.exist?(d) }
           env_vars = Set.new
+          truncated = false
 
           dirs.each do |dir|
-            capped_glob(dir, "**/*.rb", real_root, dir.delete_prefix("#{root}/"), unread).each do |path|
-              next unless feature_word_match?(File.basename(path, ".rb"), pattern) || feature_word_match?(path, pattern)
+            matched = safe_glob(dir, "**/*.rb", real_root).select do |path|
+              feature_word_match?(File.basename(path, ".rb"), pattern) || feature_word_match?(path, pattern)
+            end
+            truncated ||= matched.size > MAX_SCAN_FILES
+            matched.first(MAX_SCAN_FILES).each do |path|
               source = RailsAiContext::SafeFile.read(path) or next
               source.scan(/ENV\[["']([^"']+)["']\]|ENV\.fetch\(["']([^"']+)["']\)/).each do |m|
                 env_vars << (m[0] || m[1])
@@ -684,7 +669,6 @@ module RailsAiContext
           end
           return if env_vars.empty?
 
-          truncated = dirs.any? { |dir| unread.include?(dir.delete_prefix("#{root}/")) }
           header = "## Environment Dependencies#{truncated ? " (first #{MAX_SCAN_FILES} per dir scanned)" : ""}"
           lines << header
           env_vars.sort.each { |v| lines << "- `#{v}`" }

data/lib/rails_ai_context/tools/diagnose.rb

@@ -220,7 +220,7 @@ module RailsAiContext
 
         # Next steps
         next_steps = [
-          (pointer("rails_get_edit_context", %(file:"#{file}", near:"#{parsed[:method_name] || line || parsed[:exception_class]}"), "to see the code.") if file),
+          (pointer("rails_get_edit_context", line ? %(file:"#{file}", line:#{line}) : %(file:"#{file}", near:"#{parsed[:method_name] || parsed[:exception_class]}"), "to see the code.") if file),
           (pointer("rails_search_code", %(pattern:"#{parsed[:method_name]}", match_type:"trace"), "to trace the method.") if parsed[:method_name])
         ].compact.map { |step| "_Use #{step}_" }
         if next_steps.any?
@@ -283,7 +283,7 @@ module RailsAiContext
           end
 
           # Extract method name from "undefined method `foo`" or "undefined method 'foo'"
-          if (m = result[:message].match(/undefined method [`'](\w+[?!]?)[`']/))
+          if (m = result[:message].match(/undefined method [`'](\w+[?!=]?|\[\]=?)[`']/))
             result[:method_name] = m[1]
           end
 
@@ -497,7 +497,7 @@ module RailsAiContext
           known = known_model_methods(model_data)
           # "published?" / "save!" resolve through the bare attribute name, so
           # compare without the trailing punctuation too.
-          base_name = method_name.to_s.sub(/[?!]\z/, "")
+          base_name = method_name.to_s.sub(/[?!=]\z/, "")
           return nil if known.include?(base_name) || known.include?(method_name.to_s)
 
           suggestion = find_closest_match(base_name, known)
@@ -575,7 +575,7 @@ module RailsAiContext
 
           if file && line
             add_section(lines, "Code Context", report_error: true) do
-              compose(GetEditContext, file: file, near: parsed[:method_name] || line.to_s)
+              compose(GetEditContext, file: file, near: parsed[:method_name], line: line)
             end
           end
 
@@ -616,12 +616,18 @@ module RailsAiContext
 
         # Regex because a lone source line is no program a listener can walk.
         def nil_receiver(file, line, method)
-          call = /((?:@@?|\$)?\w+)\.#{Regexp.escape(method)}(?![\w?!])/
+          name = method.chomp("=")
+          # A `%w[` literal is no index call, and in `a[:b][:c]` the nil one may be `a[:b]`.
+          call = if method.start_with?("[") then /(?<![%\w@$])((?:@@?|\$)?\w+)\[[^\[\]]*\](?!\[)/
+          elsif method.end_with?("=") then /((?:@@?|\$)?\w+)\.#{Regexp.escape(name)}\s*=(?!=)/
+          else /((?:@@?|\$)?\w+)\.#{Regexp.escape(method)}(?![\w?!])/
+          end
           located = RailsAiContext::SafePath.locate(file, under: rails_app.root.to_s)
           failing = line.to_i.positive? && located.ok? && RailsAiContext::SafeFile.read(located.realpath).to_s.lines[line.to_i - 1]
           return failing[call, 1] if failing
+          return nil if method.start_with?("[")
 
-          response_text(compose(GetEditContext, file: file, near: method))[call, 1]
+          response_text(compose(GetEditContext, file: file, near: ".#{name}"))[call, 1]
         end
 
         # Infer a specific diagnosis from the error + context

data/lib/rails_ai_context/tools/get_edit_context.rb

@@ -6,7 +6,7 @@ module RailsAiContext
       tool_name "rails_get_edit_context"
       description "Get targeted code context for surgical edits: returns matching lines with surrounding code and line numbers. " \
         "Use when: you need to edit a specific method or section without reading the entire file. " \
-        "Requires file:\"app/models/user.rb\" and near:\"def activate\" to locate the code region."
+        "Requires file:\"app/models/user.rb\" and near:\"def activate\" (or line:42) to locate the code region."
 
       input_schema(
         properties: {
@@ -21,9 +21,13 @@ module RailsAiContext
           context_lines: {
             type: "integer",
             description: "Lines of context above and below the match. Default: 5."
+          },
+          line: {
+            type: "integer",
+            description: "Show context_lines either side of this line number instead of searching for `near` (e.g. a line from a stack trace)."
           }
         },
-        required: %w[file near]
+        required: %w[file]
       )
 
       guide_row(
@@ -35,14 +39,14 @@ module RailsAiContext
 
       annotations(read_only_hint: true, destructive_hint: false, idempotent_hint: true, open_world_hint: false)
 
-      def self.call(file:, near:, context_lines: 5, server_context: nil)
+      def self.call(file:, near: nil, context_lines: 5, line: nil, server_context: nil)
         # Reject empty parameters
         if file.nil? || file.strip.empty?
           return text_response("The `file` parameter is required. Provide a path relative to Rails root (e.g. 'app/models/post.rb').")
         end
 
-        if near.nil? || near.strip.empty?
-          return text_response("The `near` parameter is required. Provide a method name, keyword, or string to find.")
+        if line.nil? && (near.nil? || near.strip.empty?)
+          return text_response("The `near` or `line` parameter is required. Provide a method name, keyword, or string to find, or a line number.")
         end
 
         located = RailsAiContext::SafePath.locate(file, under: rails_app.root.to_s)
@@ -79,10 +83,13 @@ module RailsAiContext
         # start brought back a window where a wrong guess brought "not found".
         redacted = RailsAiContext::Redaction.redact_source_lines(source_lines.map(&:rstrip), path: file)
 
-        # Find all matching lines
-        matches = []
-        redacted.each_with_index do |line, idx|
-          matches << idx if line.include?(near)
+        at_line = line.to_i.between?(1, source_lines.size)
+        matches = if at_line
+          [ line.to_i - 1 ]
+        elsif near.nil? || near.strip.empty?
+          return empty_response("Line #{echo_input(line.to_s)} is not in #{file} (#{count_phrase(source_lines.size, "line")}).")
+        else
+          redacted.each_index.select { |idx| redacted[idx].include?(near) }
         end
 
         if matches.empty?
@@ -94,9 +101,10 @@ module RailsAiContext
         start_idx = [ match_idx - context_lines, 0 ].max
         end_idx = [ match_idx + context_lines, source_lines.size - 1 ].min
 
-        # If match is inside a method, expand to include the full method
+        # If match is inside a method, expand to include the full method; a line asked for keeps its
+        # window, which a 300-line method would push out of a caller's cut.
         method_start = find_method_start(source_lines, match_idx)
-        method_end = find_method_end(source_lines, method_start) if method_start
+        method_end = find_method_end(source_lines, method_start) if method_start && !at_line
         if method_start && method_end && source_lines[match_idx].match?(/\A\s*def\s/)
           # Match IS a method definition - show the complete method, no extra context
           start_idx = method_start

data/lib/rails_ai_context/tools/migration_advisor.rb

@@ -148,10 +148,7 @@ module RailsAiContext
         lines.concat(column_mention_lines(column)) if %w[remove_column rename_column change_type].include?(action) && column
 
         # Strong Migrations warnings (only when the gem is present in the project).
-        # add_association accepts the associated table via either `column` or
-        # `type` (see generate_add_association) - resolve the same way here.
-        warning_column = action == "add_association" ? (column || type) : column
-        lines.concat(strong_migrations_warnings(action, table, warning_column, options)) if strong_migrations_gem_present?
+        lines.concat(strong_migrations_warnings(action, table, column, options)) if strong_migrations_gem_present?
 
         text_response(lines.join("\n"))
       end
@@ -532,7 +529,8 @@ module RailsAiContext
           reference = written.to_s.singularize
           lines = []
           fk_column = "#{reference}_id"
-          if column_exists?(table, fk_column)
+          fk_column_exists = column_exists?(table, fk_column)
+          if fk_column_exists
             lines << "**Warning:** Column `#{fk_column}` already exists on `#{table}`. This migration will fail. Use `add_index` if you only need an index."
             lines << ""
           end
@@ -563,20 +561,76 @@ module RailsAiContext
             lines << ""
           end
 
-          foreign_key = if across || to_table.nil? then ""
-          elsif to_table == reference.pluralize then ", foreign_key: true"
-          else ", foreign_key: { to_table: :#{to_table} }"
+          composite = to_table && !across && composite_key(schema, to_table)
+          if composite
+            lines << "**Foreign key:** `#{to_table}` has the composite primary key (#{composite.join(', ')}), " \
+                     "which one column cannot reference, so the reference below has none."
+            lines << ""
           end
+
+          fk_target = to_table unless across || composite
+          foreign_key = fk_target ? foreign_key_option(schema, fk_target, reference) : ""
+          reference_call = "add_reference :#{table}, :#{reference}#{key_type_option(schema, table, to_table)}"
           lines << "```ruby"
           lines << "class Add#{written.camelize}To#{table.camelize} < ActiveRecord::Migration[#{rails_version}]"
           lines << "  def change"
-          lines << "    add_reference :#{table}, :#{reference}#{key_type_option(schema, to_table)}#{foreign_key}"
+          lines << "    #{reference_call}#{foreign_key}"
           lines << "  end"
           lines << "end"
           lines << "```"
           lines << ""
           lines << "**Reversible:** Yes"
           lines.concat(association_model_lines(table, reference, to_table))
+          # A migration that fails on its existing column has nothing to make safe.
+          lines.concat(association_strong_migrations_lines(table, reference, reference_call, fk_target, schema)) if strong_migrations_gem_present? && !fk_column_exists
+          lines
+        end
+
+        # The add_reference above as strong_migrations wants it on each
+        # database: the index and the foreign key are what it checks.
+        def association_strong_migrations_lines(table, reference, reference_call, fk_target, schema)
+          column_option = ", column: :#{reference}_id"
+          target_key = custom_primary_key(schema, fk_target) if fk_target
+          add_foreign_key_call = "add_foreign_key :#{table}, :#{fk_target}#{column_option}#{", primary_key: :#{target_key}" if target_key}"
+          warnings = case family(table).key
+          when :postgresql
+            # strong_migrations before 2.5.2 flags any key inside add_reference, so the key goes on its own.
+            unvalidated_key_step = " and `#{add_foreign_key_call}, validate: false`" if fk_target
+            steps = [
+              "**`add_reference` builds its index without `algorithm: :concurrently`**, which blocks writes" \
+              "#{", and its foreign key checks every existing row under a `SHARE ROW EXCLUSIVE` lock on both tables" if fk_target}. Instead:",
+              "  1. `disable_ddl_transaction!` at the top of the migration, then `#{reference_call}, index: { algorithm: :concurrently }`#{unvalidated_key_step}"
+            ]
+            steps << "  2. In a separate migration: `validate_foreign_key :#{table}, :#{fk_target}#{column_option}`" if fk_target
+            steps
+          when :mysql
+            if fk_target && strong_migrations_checks_mysql_foreign_keys?
+              [
+                "**`add_reference` with a foreign key blocks writes on both tables.** Add the reference without one, `#{reference_call}`, " \
+                "and the key in a separate migration. If every row is valid and migrations do not run through a connection pooler:",
+                "```ruby",
+                "class Add#{reference.camelize}ForeignKeyTo#{table.camelize} < ActiveRecord::Migration[#{rails_version}]",
+                "  def up",
+                "    safety_assured do",
+                "      execute \"SET SESSION foreign_key_checks = 0\"",
+                "      #{add_foreign_key_call}",
+                "    ensure",
+                "      execute \"SET SESSION foreign_key_checks = 1\"",
+                "    end",
+                "  end",
+                "",
+                "  def down",
+                "    remove_foreign_key :#{table}#{column_option}",
+                "  end",
+                "end",
+                "```"
+              ]
+            end
+          when :sqlite then nil # strong_migrations checks no foreign key on SQLite
+          else
+            [ "**The foreign key from `add_reference` validates existing rows**, which can block writes on both tables while it runs." ] if fk_target
+          end
+          strong_migrations_section(warnings)
         end
 
         # The belongs_to and has_many the reference wants, in the models that
@@ -617,18 +671,53 @@ module RailsAiContext
           Payload.schema_tables(schema).any? { |_, table, _| table.to_s == name.to_s }
         end
 
-        # The primary key type of a table when it is not the integer Rails defaults to.
-        def custom_key_type(table_data)
+        def key_column(table_data)
           keys = Array(table_data && table_data[:columns]).select { |c| c[:primary_key] }
-          type = keys.first[:type].to_s if keys.size == 1
-          type unless type.nil? || %w[bigint integer].include?(type)
+          keys.first if keys.size == 1
         end
 
-        # ", type: :uuid" for a reference to a table keyed that way; a table the schema lacks is keyed as the app's tables are.
-        def key_type_option(schema, to_table)
+        # The key type of a table when a reference would not get it by default: bigint never, integer unless counted as default.
+        def custom_key_type(table_data, integer_is_default: true)
+          type = key_column(table_data)&.dig(:type)&.to_s
+          type unless type.nil? || type == "bigint" || (integer_is_default && type == "integer")
+        end
+
+        # A reference takes the column type of a serial key, never a sequence of its own.
+        SERIAL_COLUMN_TYPES = { "serial" => "integer", "smallserial" => "smallint", "bigserial" => nil }.freeze
+
+        # The type, limit and sign a reference needs to match its key, which a MySQL foreign key requires;
+        # only SQLite types every integer alike. A table the schema lacks is keyed as the app's tables are.
+        def key_type_option(schema, table, to_table)
+          database = family(table).key
           target = to_table && schema_known?(schema) && Payload.schema_table(schema, to_table)
-          type = target ? custom_key_type(target) : app_key_type(schema)
-          type ? ", type: :#{type}" : ""
+          key = key_column(target) if target
+          type = target ? custom_key_type(target, integer_is_default: database == :sqlite) : app_key_type(schema)
+          type = SERIAL_COLUMN_TYPES.fetch(type, type)
+          limit = key[:limit] if key && type == "integer"
+          unsigned = key && key[:unsigned] && database == :mysql
+          "#{", type: :#{type}" if type}#{", limit: #{limit}" if limit}#{", unsigned: true" if unsigned}"
+        end
+
+        # Rails points a foreign key at the reference pluralized and at its
+        # `id`, so another table, or a table keyed by another column, is named.
+        def foreign_key_option(schema, to_table, reference)
+          key = custom_primary_key(schema, to_table)
+          options = [ ("to_table: :#{to_table}" if to_table != reference.pluralize), ("primary_key: :#{key}" if key) ].compact
+          options.empty? ? ", foreign_key: true" : ", foreign_key: { #{options.join(', ')} }"
+        end
+
+        def custom_primary_key(schema, to_table)
+          key = primary_key(schema, to_table)
+          key if key.is_a?(String) && key != "id"
+        end
+
+        def composite_key(schema, to_table)
+          key = primary_key(schema, to_table)
+          key if key.is_a?(Array)
+        end
+
+        def primary_key(schema, to_table)
+          schema_known?(schema) ? Payload.schema_table(schema, to_table)&.dig(:primary_key) : nil
         end
 
         # The key type more than half of the app's tables share, when it is not Rails' default.
@@ -698,7 +787,14 @@ module RailsAiContext
               name = parts[0]&.strip
               type = parts[1]&.strip || "string"
               if type == "references"
-                lines << "      t.references :#{name}#{key_type_option(schema, name.to_s.pluralize)}, foreign_key: true"
+                to_table = name.to_s.pluralize
+                missing = schema_known?(schema) && !table_in_schema?(schema, to_table)
+                composite = !missing && composite_key(schema, to_table)
+                foreign_key = if missing then " # no foreign key: the schema has no #{to_table} table"
+                elsif composite then " # no foreign key: #{to_table} has the composite primary key (#{composite.join(', ')})"
+                else foreign_key_option(schema, to_table, name)
+                end
+                lines << "      t.references :#{name}#{key_type_option(schema, table, to_table)}#{foreign_key}"
               else
                 lines << "      t.#{type} :#{name}"
               end
@@ -719,7 +815,8 @@ module RailsAiContext
         # 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).
+        # Catalog covers the most common breaking-change patterns (columns, indexes);
+        # add_association's warning lives with the reference it rewrites.
         # 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
@@ -751,26 +848,6 @@ module RailsAiContext
                 "Use `add_index :#{table}, :#{column}, algorithm: :concurrently` and add `disable_ddl_transaction!` at the top of the migration."
               ]
             end
-          when "add_association"
-            case family(table).key
-            when :mysql
-              [
-                "**`add_foreign_key` blocks writes on both tables while validating existing rows.** MySQL/MariaDB has no `validate: false` + separate-validation two-step like Postgres.",
-                "If you're certain all rows are valid, wrap in `safety_assured` and drop `foreign_key_checks` for the duration:",
-                "  1. `execute \"SET SESSION foreign_key_checks = 0\"`",
-                "  2. `add_foreign_key :#{table}, :#{column}`",
-                "  3. `execute \"SET SESSION foreign_key_checks = 1\"`"
-              ]
-            when :postgresql
-              [
-                "**`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}, :#{column}, validate: false` (lock-free)",
-                "  2. In a separate migration: `validate_foreign_key :#{table}, :#{column}`"
-              ]
-            else
-              [ "**`add_foreign_key` validates existing rows by default**, which can block writes on both tables while it runs." ]
-            end
           when "add_column"
             if options.to_s.match?(/null:\s*false/) && !options.to_s.include?("default:")
               [
@@ -784,6 +861,10 @@ module RailsAiContext
             end
           end
 
+          strong_migrations_section(warnings)
+        end
+
+        def strong_migrations_section(warnings)
           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
@@ -795,6 +876,14 @@ module RailsAiContext
           RailsAiContext.debug_fail(e, false, label: "strong_migrations_gem_present?")
         end
 
+        # strong_migrations checks a MySQL foreign key from 2.7 on; an unlocked or unreadable version is taken as current.
+        def strong_migrations_checks_mysql_foreign_keys?
+          version = RailsAiContext::GemLock.for(rails_app.root).version("strong_migrations")
+          version.nil? || Gem::Version.new(version).release >= Gem::Version.new("2.7")
+        rescue => e
+          RailsAiContext.debug_fail(e, true, label: "strong_migrations_checks_mysql_foreign_keys?")
+        end
+
         # ignored_columns has to go on the class that owns the table, and
         # every STI class records that same table, so a child that sorts
         # earlier would otherwise win. The conventional name is the base.

data/lib/rails_ai_context/tools/onboard.rb

@@ -46,7 +46,8 @@ module RailsAiContext
         else
           compose_standard(ctx)
         end
-        text_response(body, suffix: introspection_warnings_note(ctx))
+        update = RailsAiContext::UpdateCheck.agent_note
+        text_response(body, suffix: [ introspection_warnings_note(ctx), ("\n\n---\n#{update}" if update) ].compact.join)
       end
 
       class << self

data/lib/rails_ai_context/update_check.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+require_relative "version"
+
+module RailsAiContext
+  # Tells the copy `gem install` put on PATH that rubygems.org has a newer
+  # release. Only the gem's own binary, run outside a bundle, turns it on
+  # (enable!), so a copy an app's bundle loads never checks: its lockfile
+  # decides the version.
+  #
+  # Core Ruby only. The binary loads this before the app boots, and requiring
+  # net/http or json here would activate the newest installed versions over
+  # the ones the app's lock pins. The fetch runs in a detached child instead,
+  # at most once a day, and the version it writes is what the next check reads.
+  module UpdateCheck
+    OPT_OUT_ENV = "RAILS_AI_CONTEXT_NO_UPDATE_CHECK"
+    URL = "https://rubygems.org/api/v1/versions/rails-ai-context/latest.json"
+    INTERVAL = 24 * 60 * 60
+
+    FETCH = <<~RUBY
+      require "net/http"
+      path, url = ARGV
+      uri = URI(url)
+      response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: 5, read_timeout: 5) do |http|
+        http.get(uri.request_uri)
+      end
+      version = response.body[/"version"\\s*:\\s*"([^"]+)"/, 1] if response.is_a?(Net::HTTPSuccess)
+      exit unless version
+      tmp = "\#{path}.\#{Process.pid}"
+      begin
+        File.write(tmp, version)
+        File.rename(tmp, path)
+      ensure
+        File.delete(tmp) if File.exist?(tmp)
+      end
+    RUBY
+
+    module_function
+
+    # Called before an app's boot, which swaps Gem.path for the bundle's.
+    def enable!
+      @enabled = true
+      @gem_dirs = Gem.path
+      newest_at_start
+    end
+
+    # The notice for an agent to pass on. Giving it marks it told, so the CLI does not print it again.
+    def agent_note
+      note = notice or return
+      @told = true
+      "Tell the user: #{note}"
+    end
+
+    def told?
+      @told == true
+    end
+
+    def disabled?
+      !@enabled || !ENV[OPT_OUT_ENV].to_s.empty? || ci? || Gem::Version.new(VERSION).prerelease?
+    end
+
+    # Starts the fetch when the last one is a day old (or in the future, after a
+    # clock change). The file's time is set first, so a failed fetch waits a day
+    # too. Its own process group keeps a Ctrl-C at the terminal from killing it.
+    # @param env [Hash] the environment the binary started in, before an app's boot changed it
+    def refresh(env:)
+      return if disabled?
+
+      path = state_file
+      age = Time.now - File.mtime(path) if File.exist?(path)
+      return if age&.between?(0, INTERVAL)
+
+      make_dirs(File.dirname(path))
+      File.open(path, "a") { nil }
+      File.utime(nil, nil, path)
+      group = Gem.win_platform? ? { new_pgroup: true } : { pgroup: true }
+      pid = Process.spawn(env, RbConfig.ruby, "-e", FETCH, path, URL,
+                          unsetenv_others: true, in: File::NULL, out: File::NULL, err: File::NULL, **group)
+      Process.detach(pid)
+    rescue StandardError
+      nil
+    end
+
+    # One sentence for the user, or nil when this copy is current.
+    def notice
+      return if disabled?
+
+      latest = latest_release or return
+      running = Gem::Version.new(VERSION)
+      return unless latest > running
+      # A newer copy installed when this process started means an older one was run on purpose (`_5.30.0_`).
+      return if newest_at_start && newest_at_start > running
+
+      installed = newest_installed
+      if installed && installed >= latest
+        "rails-ai-context #{installed} is installed, but this process still runs #{VERSION}. " \
+          "Restart the MCP server (or the AI client) to load it."
+      else
+        "rails-ai-context #{latest} is out; this is #{VERSION} on Ruby #{RUBY_VERSION} (#{RbConfig.ruby}). " \
+          "Under that Ruby run `gem update rails-ai-context`, then `rails-ai-context init --defaults` in each app. " \
+          "#{OPT_OUT_ENV}=1 turns this check off."
+      end
+    end
+
+    def latest_release
+      text = File.read(state_file, 64).to_s.strip
+      return if text.empty? || !Gem::Version.correct?(text)
+
+      version = Gem::Version.new(text)
+      version unless version.prerelease?
+    rescue StandardError
+      nil
+    end
+
+    def state_file
+      home = Gem.respond_to?(:state_home) ? Gem.state_home : (ENV["XDG_STATE_HOME"] || File.join(Gem.user_home, ".local", "state"))
+      File.join(home, "rails-ai-context", "latest")
+    end
+
+    # The newest copy installed for this Ruby, in any directory of the gem path.
+    def newest_installed
+      Array(@gem_dirs).flat_map { |dir| Dir[File.join(dir, "specifications", "rails-ai-context-*.gemspec")] }.filter_map do |spec|
+        number = File.basename(spec, ".gemspec").delete_prefix("rails-ai-context-")
+        Gem::Version.new(number) if Gem::Version.correct?(number)
+      end.max
+    end
+
+    def newest_at_start
+      return @newest_at_start if defined?(@newest_at_start)
+
+      @newest_at_start = newest_installed
+    end
+
+    def ci?
+      defined?(Gem::CIDetector) ? Gem::CIDetector.ci? : !ENV["CI"].to_s.empty?
+    end
+
+    # Dir.mkdir one level at a time: fileutils is a gem an app may pin.
+    def make_dirs(dir)
+      return if Dir.exist?(dir)
+
+      make_dirs(File.dirname(dir))
+      Dir.mkdir(dir)
+    rescue Errno::EEXIST
+      nil
+    end
+  end
+end

data/lib/rails_ai_context/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-ai-context
 version: !ruby/object:Gem::Version
-  version: 5.36.3
+  version: 5.36.5
 platform: ruby
 authors:
 - crisnahine
@@ -560,6 +560,7 @@ files:
 - lib/rails_ai_context/tools/session_context.rb
 - lib/rails_ai_context/tools/validate.rb
 - lib/rails_ai_context/tools/validate_semantics.rb
+- lib/rails_ai_context/update_check.rb
 - lib/rails_ai_context/version.rb
 - lib/rails_ai_context/vfs.rb
 - lib/rails_ai_context/view_file.rb