rails-ai-context 5.36.2 → 5.36.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0a04632cfd1114032ce4434e7e8b99d5f92c81bc9537bf5c65b6c65a3124c278
-  data.tar.gz: 3c5210bcb7ba0fef976a00b1224647588d44556bb8d807cbbc87aca9ff0214ce
+  metadata.gz: d0dd31bd07cbfa7f5cb1e1232627cda1c7ea16f035f864d8db86e1f544bb3893
+  data.tar.gz: 92512c007d7fc751a59bf72b1f651fb2a6e58117bc47697e109c145cbd65b6cf
 SHA512:
-  metadata.gz: 41e3246dc1905379a9d39bc4bfb8e95498b752a95f1a96b2e955ad58ca22a06696d0c12fd1b676e7414086cea5e571f772c8638dec36823ee542462dca8f4e64
-  data.tar.gz: ea9ebf310554c650503a9f9b95521988eccbf42286885b294ae86031d8c393a3dc71161ecab3852bb69a17055167b5334669fd0187817c62c73f98ecbf0843c1
+  metadata.gz: 0d751847ce7745680c03f69a54077e1f8a1836c37e788d78ad5072792af68be4f7e531b98e5bc3b62159e8b297259d8ebc2649ee22c41b6150edc90e9faf0c69
+  data.tar.gz: a64566fdec0abb014195d48dcf81d2463a24b9c72addaec1254dcac0778e6f4190805baddfdf073ec2ca5b847fe4ebc4ba643de759b46fc5a16e13b586e80dab

data/CHANGELOG.md

@@ -5,6 +5,80 @@ 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.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
+
+- **`rails_diagnose` names an instance variable receiver with its `@`, and takes it from the line the error names.**
+  `@widget.name` read as `widget`, so the advice named a variable the action does
+  not have. The receiver also came from the first call of the method in the file,
+  not from the line. A line that does not call the method on a plain name now
+  gets no receiver instead of another line's. 5.36.2 and earlier versions had the
+  gap.
+- **`rails_generate_test` says which sign-in helper names it looked for.** The
+  TODO read "this app's tests define no sign-in helper" for a suite that signs in
+  through a helper with another name. It now reads "no `sign_in` or `log_in`
+  helper in this app's test helpers".
+- **A `change_table` migration lists what its block does.** `rails://migrations`
+  showed `"actions": []` for a migration that adds columns through
+  `change_table`, and `migration_stats` left it out of `total_add_column`. The
+  table calls in the block (`t.string`, `t.references`, `t.index`, `t.remove` and
+  the others) are read from the AST. A `create_table` block's columns are not
+  counted.
+- **`rails_search_code` trace says how many sibling methods and internal calls it
+  left out.** It listed 10 siblings and 15 internal calls and stopped. The list
+  now ends with "_...and N more_".
+- **`rails_get_job_pattern` reads sidekiq-scheduler entries from every
+  `config/sidekiq*.yml`.** A schedule kept in `config/sidekiq_production.yml`,
+  one file per environment, showed no `Schedule`, so a worker that runs every
+  night read like dead code. Each file's entry is shown with its file name.
+- **`rails_get_config(section:"conventions")` counts the rake tasks of
+  `lib/tasks` and the templates of `app/views`.** The directory counts took
+  `.rb` files only: `lib/tasks` read 2 files for 67, and `app/views` never
+  appeared.
+- **`rails_get_test_info` counts only `*_spec.rb` under `spec/` in an RSpec
+  suite.** A `*_test.rb` helper in `spec/support` was counted as a test file. A
+  Minitest suite still counts both `*_spec.rb` and `*_test.rb`.
+- **`rails_migration_advisor` writes a reference and a new table with the key
+  type the app uses.** On a schema of `id: :uuid` tables, `add_reference` made a
+  bigint column that PostgreSQL refuses to key to a uuid, and `create_table`
+  made the one bigint table. `add_reference` and `t.references` take the key type
+  of the table they point at (the app's type when the schema lacks that table),
+  and `create_table` takes the type most of the app's tables share.
+- **`rails_review_changes` matches `files` by whole path or directory.**
+  `files: ["Gemfile"]` also returned `Gemfile.lock`. A directory such as
+  `app/models` still matches the files under it.
+- **`rails_analyze_feature` says which directories it stopped reading.** It reads
+  the first 500 files of a directory, and a service, view or test past that was
+  missed with no word. The answer now ends with the directories it did not
+  finish. The "first 500 scanned" note no longer shows when exactly 500 files were
+  read.
+
 ## [5.36.2] - 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

@@ -333,6 +333,19 @@ Proof sources:
    two; MariaDB 10.6 and 11.4 through mysql2 built against MariaDB's client
    library on Linux; `rails_runtime_info` against a real Sidekiq and Redis; and
    the unit suite and the E2E harness on Linux, macOS and Windows.
+   In the v5.36.3 release QA: each fix's example failing on the v5.36.2 code;
+   the issues' repros run through the CLI on a minimal app, and on copies of two
+   large apps (both in the static tier, one also booted) against counts taken
+   from their files; the introspector, tool and integration specs on Ruby 3.1
+   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.
 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/INTROSPECTORS.md

@@ -285,7 +285,7 @@ same wherever it is asked. Those live as their own modules under
 | `ModuleAliases` | Which app file a bare JS import specifier names: tsconfig/jsconfig `compilerOptions.paths` followed through `extends` (relative files and installed packages), and a vite/webpack/rspack `resolve.alias` written as a literal object. The Stimulus scan uses it to tie a registration or a base class to the controller file it imports |
 | `HelperNames` | The helper methods a view can call: every method the app's helper modules define in every code root, and those of a module they `include`, found through the app's autoload roots (`lib` among them) or in its enclosing namespace's file (`CanonicalURL::Helpers` in `canonical_url.rb`). `rails_get_partial_interface` uses it so a helper call is not read as a local |
 | `Interaction` | Whether a class runs as an ActiveInteraction, following its superclass chain through the app's own sources, and the filters it takes - inherited ones first, one per name, each carrying the filters nested inside its block. See the **Interaction filter** entry in `CONTEXT.md` |
-| `RecurringSchedules` | The recurring tasks each scheduler reads from its own file: Solid Queue's `config/recurring.yml`, sidekiq-cron's `config/schedule.yml`, sidekiq-scheduler's section of `config/sidekiq.yml`, GoodJob's `config.good_job.cron` and whenever's `config/schedule.rb`. The job introspector hands it its own config walk, so a file it also reads for queue or mailer settings is walked once |
+| `RecurringSchedules` | The recurring tasks each scheduler reads from its own file: Solid Queue's `config/recurring.yml`, sidekiq-cron's `config/schedule.yml`, sidekiq-scheduler's section of each `config/sidekiq*.yml`, GoodJob's `config.good_job.cron` and whenever's `config/schedule.rb`. The job introspector hands it its own config walk, so a file it also reads for queue or mailer settings is walked once |
 | `AdminResources` | The models an admin gem exposes (ActiveAdmin, Trestle, Administrate, Avo, Madmin), from the folder each gem's generator writes to, with ActiveAdmin's `permit_params`. `rails_get_config(section:"conventions")` and `rails_analyze_feature` both ask it |
 | `SchemaDumpPath` | The primary database's dump file as `DatabaseTasks.schema_dump_path` names it: `database.yml`'s `schema_dump` in the configured `schema_format`, then each format's default file, and the secondary databases' dumps. Every schema reader, the doctor and the pending-migration check ask it |
 | `ApartmentConfig` | The models an Apartment initializer keeps in the shared schema (`excluded_models`), or the source of a list the file computes. The model introspector asks it to say which models get one table per tenant |

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

@@ -826,7 +826,7 @@ Each diff passes through the redaction every tool's source does, read as the fil
 | Parameter | Type | Default | Description |
 |:----------|:-----|:--------|:------------|
 | `ref` | string | `HEAD` | Git ref to diff against: a branch, a tag, `HEAD~3` or a commit SHA. `HEAD` reviews uncommitted changes. Any other ref reviews the commits since HEAD left it, as a pull request does: the file list and each file's diff run from the commit the two last shared to HEAD. A ref that names no commit is refused |
-| `files` | array | - | Review only these changed files (omit for all) |
+| `files` | array | - | Review only these changed files, or the changed files under these directories (omit for all). A path matches whole, so `Gemfile` is not `Gemfile.lock` |
 
 ### `rails_runtime_info`
 

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/introspectors/convention_introspector.rb

@@ -172,6 +172,14 @@ module RailsAiContext
         RailsAiContext.debug_fail(e, false, label: "uses_async_queries?")
       end
 
+      # 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}",
+        "lib/tasks" => "**/*.rake"
+      }.freeze
+
       def scan_directory_structure
         important_dirs = %w[
           app/models app/controllers app/views app/jobs
@@ -190,7 +198,8 @@ module RailsAiContext
         # carries file counts, so the biggest code area had no number anywhere.
         (important_dirs | app_child_dirs).each_with_object({}) do |dir, hash|
           count = SourceScan.paths(root, kind: dir, skip_concerns: false).count
-          count += Dir.glob(File.join(root, dir, "**/*.js")).size if dir.include?("javascript")
+          glob = NON_RUBY_FILES[dir]
+          count += PathResolver.dirs_for(root, dir).sum { |path| Dir.glob(File.join(path, glob)).size } if glob
 
           hash[dir] = count if count > 0
         end

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/migration_introspector.rb

@@ -121,7 +121,32 @@ module RailsAiContext
           add_foreign_key remove_foreign_key
           add_timestamps create_join_table enable_extension execute
           add_check_constraint remove_check_constraint
-        ].select { |action| content.include?(action) }
+        ].select { |action| content.include?(action) } | change_table_actions(content)
+      end
+
+      # What each table call in a change_table block does; a column type adds a column, any other call does nothing.
+      CHANGE_TABLE_CALLS = {
+        index: "add_index", remove_index: "remove_index", remove: "remove_column", remove_timestamps: "remove_column",
+        remove_references: "remove_reference", remove_belongs_to: "remove_reference", references: "add_reference",
+        belongs_to: "add_reference", timestamps: "add_timestamps", rename: "rename_column", change: "change_column",
+        change_default: "change_column_default", change_null: "change_column_null", foreign_key: "add_foreign_key",
+        remove_foreign_key: "remove_foreign_key", check_constraint: "add_check_constraint",
+        remove_check_constraint: "remove_check_constraint"
+      }.freeze
+      COLUMN_CALLS = (Listeners::SchemaDslListener::COLUMN_TYPES.map(&:to_sym) + [ :column ] - CHANGE_TABLE_CALLS.keys).freeze
+
+      # A table call counts only inside a change_table block: the listener links each call to the block that encloses it.
+      def change_table_actions(content)
+        return [] unless content.include?("change_table")
+
+        hits = SourceIntrospector.walk_source(content, {
+          change_table: -> { Listeners::GenericMacroListener.new(:change_table, *CHANGE_TABLE_CALLS.keys, *COLUMN_CALLS, any_receiver: true) }
+        })[:change_table]
+        blocks = hits.select { |hit| hit[:macro] == :change_table }.to_set { |hit| hit[:offset] }
+        return [] if blocks.empty?
+
+        inside = hits.select { |hit| blocks.include?(hit[:parent_offset]) }
+        [ "change_table" ] | inside.map { |hit| CHANGE_TABLE_CALLS.fetch(hit[:macro], "add_column") }
       end
     end
   end

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/introspectors/recurring_schedules.rb

@@ -26,24 +26,28 @@ module RailsAiContext
         end
       end
 
+      SIDEKIQ_CRON_FILES = %w[config/schedule.yml config/schedule.yaml config/sidekiq_cron.yml].freeze
+
       def sidekiq_cron(root)
-        %w[config/schedule.yml config/schedule.yaml config/sidekiq_cron.yml].flat_map do |file|
+        SIDEKIQ_CRON_FILES.flat_map do |file|
           named_tasks(yaml(root, file)).filter_map { |name, options| task(file, name, options, :cron) }
         end
       end
 
       # sidekiq-scheduler runs a job by its entry's name when no class is given.
+      # Sidekiq starts from any file `-C` names, and apps keep one per environment.
       def sidekiq_scheduler(root)
-        file = "config/sidekiq.yml"
-        data = yaml(root, file)
-        return [] unless data.is_a?(Hash)
+        (Dir.glob("config/sidekiq*.{yml,yaml}", base: root.to_s).sort - SIDEKIQ_CRON_FILES).flat_map do |file|
+          data = yaml(root, file)
+          next [] unless data.is_a?(Hash)
 
-        section = data["scheduler"].is_a?(Hash) ? data["scheduler"]["schedule"] : data["schedule"]
-        named_tasks(section).filter_map do |name, options|
-          next unless options.is_a?(Hash)
+          section = data["scheduler"].is_a?(Hash) ? data["scheduler"]["schedule"] : data["schedule"]
+          named_tasks(section).filter_map do |name, options|
+            next unless options.is_a?(Hash)
 
-          kind = SCHEDULER_KEYS.find { |key| options.key?(key.to_s) } or next
-          task(file, name, { "class" => name }.merge(options), kind)
+            kind = SCHEDULER_KEYS.find { |key| options.key?(key.to_s) } or next
+            task(file, name, { "class" => name }.merge(options), kind)
+          end
         end
       end
 

data/lib/rails_ai_context/introspectors/test_introspector.rb

@@ -10,8 +10,6 @@ module RailsAiContext
       extend StaticTier
       static_tier :files_only
 
-      TEST_FILE_GLOB = "*_{spec,test}.rb"
-
       # An engine's test/dummy is tested by the engine's suite.
       def suite_root
         @suite_root ||= PathResolver.test_root(root)
@@ -56,6 +54,17 @@ module RailsAiContext
         RailsAiContext.debug_fail(e, "unknown", label: "detect_framework")
       end
 
+      # RSpec runs *_spec.rb only, so a *_test.rb under spec/ is a helper.
+      def test_file_glob(base)
+        base == "spec" && rspec_suite? ? "*_spec.rb" : "*_{spec,test}.rb"
+      end
+
+      def rspec_suite?
+        return @rspec_suite if defined?(@rspec_suite)
+
+        @rspec_suite = RailsAiContext::TestFramework.suites(suite_root).include?("rspec")
+      end
+
       # First listed wins: an app holding the same thing under spec/ and test/
       # reports one location, not both. `detect_system_tests` deliberately
       # answers the other way.
@@ -247,7 +256,7 @@ module RailsAiContext
           dir = File.join(suite_root, rel)
           next unless Dir.exist?(dir)
 
-          count = Dir.glob(File.join(dir, "**/#{TEST_FILE_GLOB}")).size
+          count = Dir.glob(File.join(dir, "**/#{test_file_glob(rel.split("/").first)}")).size
           [ rel, count ] if count > 0
         end
         return nil if rows.empty?
@@ -479,11 +488,11 @@ module RailsAiContext
             dir = File.join(base_dir, entry)
             next unless File.directory?(dir)
 
-            count = Dir.glob(File.join(dir, "**/#{TEST_FILE_GLOB}")).size
+            count = Dir.glob(File.join(dir, "**/#{test_file_glob(base)}")).size
             rows[entry] << [ "#{base}/#{entry}", count ] if count > 0
           end
 
-          loose = Dir.glob(File.join(base_dir, TEST_FILE_GLOB)).size
+          loose = Dir.glob(File.join(base_dir, test_file_glob(base))).size
           rows[base] << [ base, loose ] if loose > 0
         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

@@ -62,23 +62,24 @@ module RailsAiContext
         pattern = feature.downcase
         root = rails_app.root.to_s
         lines = [ "# Feature Analysis: #{feature}", "" ]
+        unread = Set.new
 
         matched_models = discover_models(ctx, pattern, lines)
         discover_controllers(ctx, pattern, lines)
         discover_routes(ctx, pattern, lines)
-        discover_services(root, pattern, lines)
+        discover_services(root, pattern, lines, unread)
         discover_admin(root, pattern, lines)
         discover_jobs(ctx, pattern, lines)
-        discover_views(ctx, root, pattern, lines)
+        discover_views(ctx, root, pattern, lines, unread)
         discover_stimulus(ctx, pattern, lines)
-        _feature_tests, all_tests, tests_truncated = discover_tests(root, pattern, lines)
+        _feature_tests, all_tests, tests_truncated = discover_tests(root, pattern, lines, unread)
         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)
-        discover_test_gaps(root, pattern, matched_models, ctx, all_tests || [], lines, truncated: tests_truncated)
+        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_components(ctx, pattern, lines)
 
         # For auth-related keywords, also discover auth gems
@@ -96,10 +97,17 @@ module RailsAiContext
         # If nothing was discovered, return a clean "no match" with real suggestions
         has_content = lines.any? { |l| l.start_with?("## ") || l.start_with?("### ") }
         unless has_content
-          return text_response("No matches found for '#{echo_input(feature)}'. No models, controllers, routes, services, or views match this keyword.#{model_names_hint(ctx)}")
+          return text_response("No matches found for '#{echo_input(feature)}'. No models, controllers, routes, services, or views match this keyword.#{model_names_hint(ctx)}#{unread_note(unread)}")
         end
 
-        text_response(lines.join("\n"))
+        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.
+      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._"
       end
 
       # The names a keyword that matched nothing could have been.
@@ -115,6 +123,13 @@ 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
+
         # A conditional skip names the condition it is taken out on.
         def inherited_filter_label(filter)
           "#{filter[:name]}#{Serializers::SectionFacts.filter_origin(filter)}" \
@@ -260,13 +275,13 @@ module RailsAiContext
         end
 
         # --- AF1: Services ---
-        def discover_services(root, pattern, lines)
+        def discover_services(root, pattern, lines, unread)
           dir = File.join(root, "app", "services")
           return unless Dir.exist?(dir)
 
           real_root = File.realpath(root).to_s
           real_dir = File.realpath(dir).to_s
-          candidates = safe_glob(dir, "**/*.rb", real_root).first(MAX_SCAN_FILES)
+          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.
@@ -287,7 +302,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}#{candidates.size == MAX_SCAN_FILES ? " - first #{MAX_SCAN_FILES} scanned" : ""})"
+          lines << "## Services (#{found.size}#{unread.include?("app/services") ? " - first #{MAX_SCAN_FILES} scanned" : ""})"
           services.each do |service|
             relative = service[:path].sub("#{real_root}/", "")
             methods = service[:name] ? service_methods(service[:source], service[:name]) : []
@@ -353,19 +368,19 @@ module RailsAiContext
         end
 
         # --- AF3: Views + Partials ---
-        def discover_views(ctx, root, pattern, lines)
+        def discover_views(ctx, root, pattern, lines, unread)
           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 = safe_glob(views_dir, "**/*.{erb,haml,slim,jbuilder}", real_root).first(MAX_SCAN_FILES)
+          candidates = capped_glob(views_dir, "**/*.{erb,haml,slim,jbuilder}", real_root, "app/views", unread)
           found = candidates.select do |path|
             feature_word_match?(path.sub("#{real_views_dir}/", ""), pattern)
           end
           return if found.empty?
 
-          lines << "## Views (#{found.size}#{candidates.size == MAX_SCAN_FILES ? " - first #{MAX_SCAN_FILES} scanned" : ""})"
+          lines << "## Views (#{found.size}#{unread.include?("app/views") ? " - first #{MAX_SCAN_FILES} scanned" : ""})"
           found.each do |path|
             relative = path.sub("#{real_views_dir}/", "")
             source = RailsAiContext::SafeFile.read(path) or next
@@ -439,7 +454,7 @@ module RailsAiContext
         # @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)
+        def discover_tests(root, pattern, lines, unread)
           real_root = File.realpath(root).to_s
           found = []
           all = []
@@ -449,8 +464,7 @@ module RailsAiContext
           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 = safe_glob(dir, "**/*_{test,spec}.rb", real_base).first(MAX_SCAN_FILES)
-            truncated = true if suffix_glob.size == MAX_SCAN_FILES
+            suffix_glob = capped_glob(dir, "**/*_{test,spec}.rb", real_base, File.basename(dir), unread)
             # 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
@@ -458,13 +472,13 @@ module RailsAiContext
             suffix_glob.each do |path|
               found << path if feature_word_match?(relative_test_name(path, real_base), pattern)
             end
-            prefix_glob = safe_glob(dir, "**/{test,spec}_*.rb", real_base).first(MAX_SCAN_FILES)
-            truncated = true if prefix_glob.size == MAX_SCAN_FILES
+            prefix_glob = capped_glob(dir, "**/{test,spec}_*.rb", real_base, File.basename(dir), unread)
             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?
@@ -486,7 +500,7 @@ module RailsAiContext
         end
 
         # --- Test coverage gaps ---
-        def discover_test_gaps(root, pattern, matched_models, ctx, test_files, lines, truncated: false)
+        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
@@ -526,7 +540,7 @@ module RailsAiContext
             path_dir = File.join(root, "app", dir)
             next unless Dir.exist?(path_dir)
 
-            safe_glob(path_dir, "**/*.rb", real_root).first(MAX_SCAN_FILES).each do |path|
+            capped_glob(path_dir, "**/*.rb", real_root, "app/#{dir}", unread).each do |path|
               snake = File.basename(path, ".rb")
               next unless feature_word_match?(snake, pattern)
               next if test_basenames.any? { |t| t.include?(snake) }
@@ -653,17 +667,14 @@ module RailsAiContext
         end
 
         # --- AF9: Environment Dependencies ---
-        def discover_env_dependencies(root, pattern, matched_models, lines)
+        def discover_env_dependencies(root, pattern, matched_models, lines, unread)
           # 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|
-            candidates = safe_glob(dir, "**/*.rb", real_root).first(MAX_SCAN_FILES)
-            truncated = true if candidates.size == MAX_SCAN_FILES
-            candidates.each do |path|
+            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)
               source = RailsAiContext::SafeFile.read(path) or next
               source.scan(/ENV\[["']([^"']+)["']\]|ENV\.fetch\(["']([^"']+)["']\)/).each do |m|
@@ -673,6 +684,7 @@ 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

@@ -186,7 +186,7 @@ module RailsAiContext
         # Likely cause - enriched with specific inference when possible
         lines << "## Likely Cause"
         lines << classification[:likely]
-        specific = infer_specific_cause(parsed, classification, file, action)
+        specific = infer_specific_cause(parsed, classification, file, action, line)
         lines << "" << "**Specific:** #{specific}" if specific
         lines << ""
 
@@ -614,8 +614,18 @@ module RailsAiContext
           lines << "## #{title}" << "_Could not load: #{e.message}_" << ""
         end
 
+        # 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?!])/
+          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
+
+          response_text(compose(GetEditContext, file: file, near: method))[call, 1]
+        end
+
         # Infer a specific diagnosis from the error + context
-        def infer_specific_cause(parsed, classification, file, action)
+        def infer_specific_cause(parsed, classification, file, action, line = nil)
           msg = parsed[:message].to_s
           method = parsed[:method_name]
 
@@ -629,12 +639,8 @@ module RailsAiContext
             # Check if calling on an association
             if method && file
               begin
-                ctx = compose(GetEditContext, file: file, near: method)
-                code = response_text(ctx)
-                # Find the receiver: something.method_name
-                receiver_match = code.match(/(\w+)\.#{Regexp.escape(method)}/)
-                if receiver_match
-                  receiver = receiver_match[1]
+                receiver = nil_receiver(file, line, method)
+                if receiver
                   return "`#{receiver}` is nil when `.#{method}` is called. " \
                          "This variable may not be set in all code paths - check if it's assigned before use, " \
                          "or use `#{receiver}&.#{method}` for safe navigation."

data/lib/rails_ai_context/tools/generate_test.rb

@@ -793,7 +793,7 @@ module RailsAiContext
             names = res[:login].map { |login| login[:filter][:name] }.join(" and ")
             "this app's #{res[:helper]} is not known to get a request past #{names}, so send what #{names} checks"
           else
-            "this app's tests define no sign-in helper, so sign a user in first the way the app's login does"
+            "no `sign_in` or `log_in` helper in this app's test helpers, so sign a user in first the way the app's login does"
           end
           [ "  # TODO: #{login_phrase(ctrl_class, res)}, so each request here is redirected or refused until the test signs in: #{how}." ]
         end

data/lib/rails_ai_context/tools/migration_advisor.rb

@@ -570,7 +570,7 @@ module RailsAiContext
           lines << "```ruby"
           lines << "class Add#{written.camelize}To#{table.camelize} < ActiveRecord::Migration[#{rails_version}]"
           lines << "  def change"
-          lines << "    add_reference :#{table}, :#{reference}#{foreign_key}"
+          lines << "    add_reference :#{table}, :#{reference}#{key_type_option(schema, to_table)}#{foreign_key}"
           lines << "  end"
           lines << "end"
           lines << "```"
@@ -617,6 +617,27 @@ 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)
+          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)
+        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)
+          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}" : ""
+        end
+
+        # The key type more than half of the app's tables share, when it is not Rails' default.
+        def app_key_type(schema)
+          tables = schema.is_a?(Hash) && schema[:tables].is_a?(Hash) ? schema[:tables].values : []
+          type, count = tables.map { |data| custom_key_type(data) }.tally.max_by(&:last)
+          type if type && count * 2 > tables.size
+        end
+
         def generate_change_type(table, column, type, options)
           return [ "**Error:** column and type are required" ] unless column && type
 
@@ -667,7 +688,9 @@ module RailsAiContext
           lines << "```ruby"
           lines << "class Create#{table.camelize} < ActiveRecord::Migration[#{rails_version}]"
           lines << "  def change"
-          lines << "    create_table :#{table} do |t|"
+          schema = cached_context[:schema]
+          key_type = app_key_type(schema)
+          lines << "    create_table :#{table}#{", id: :#{key_type}" if key_type} do |t|"
 
           if columns_str
             columns_str.split(",").each do |col|
@@ -675,7 +698,7 @@ module RailsAiContext
               name = parts[0]&.strip
               type = parts[1]&.strip || "string"
               if type == "references"
-                lines << "      t.references :#{name}, foreign_key: true"
+                lines << "      t.references :#{name}#{key_type_option(schema, name.to_s.pluralize)}, foreign_key: true"
               else
                 lines << "      t.#{type} :#{name}"
               end

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/tools/review_changes.rb

@@ -21,7 +21,7 @@ module RailsAiContext
           files: {
             type: "array",
             items: { type: "string" },
-            description: "Filter to specific files (relative to Rails root). Omit to review all changed files."
+            description: "Filter to files or directories (relative to Rails root). Omit to review all changed files."
           }
         }
       )
@@ -91,7 +91,7 @@ module RailsAiContext
         end
 
         changed = get_changed_files(base, root)
-        changed = changed.select { |f| files.any? { |filter| f.include?(filter) } } if files&.any?
+        changed = changed.select { |f| files.any? { |filter| path_matches?(f, filter) } } if files&.any?
 
         if changed.empty?
           return text_response("No changes found for ref '#{echo_input(ref)}'.#{files ? " Filter: #{echo_input(files.join(', '))}" : ""}")
@@ -214,6 +214,12 @@ module RailsAiContext
           status.success? && !prefix.strip.empty?
         end
 
+        # A filter names one file or a directory, never part of a name: `Gemfile` is not `Gemfile.lock`.
+        def path_matches?(path, filter)
+          wanted = filter.delete_prefix("./").chomp("/")
+          path == wanted || path.start_with?("#{wanted}/")
+        end
+
         # The Ruby folders count only Ruby files: the install writes app/models/AGENTS.md beside the models.
         def classify_file(path)
           case path

data/lib/rails_ai_context/tools/search_code.rb

@@ -23,6 +23,11 @@ module RailsAiContext
       BINARY_PROBE_BYTES = 64 * 1024
 
       TEST_DIRS = %w[test/ spec/ features/].freeze
+
+      # A trace lists this many internal calls and sibling methods, then says how many it left out.
+      INTERNAL_CALLS_SHOWN = 15
+      SIBLINGS_SHOWN = 10
+
       MATCH_FIELD_SEPARATOR = "\x1f"
       # A comment line by the file's own syntax. `#{` and ` * ` are Ruby code;
       # `#id` is a selector in a stylesheet and an element in Haml or Slim.
@@ -768,7 +773,8 @@ module RailsAiContext
 
               if internal_calls.any?
                 lines << "" << "## Calls internally"
-                internal_calls.first(15).each { |c| lines << "- `#{c}`" }
+                internal_calls.first(INTERNAL_CALLS_SHOWN).each { |c| lines << "- `#{c}`" }
+                lines << "- _...and #{internal_calls.size - INTERNAL_CALLS_SHOWN} more_" if internal_calls.size > INTERNAL_CALLS_SHOWN
               end
             end
 
@@ -776,7 +782,8 @@ module RailsAiContext
             siblings = extract_sibling_methods(File.join(root, r[:file]), cleaned)
             if siblings.any?
               lines << "" << "## Sibling methods (same file)"
-              siblings.first(10).each { |s| lines << "- `#{s}`" }
+              siblings.first(SIBLINGS_SHOWN).each { |s| lines << "- `#{s}`" }
+              lines << "- _...and #{siblings.size - SIBLINGS_SHOWN} more_" if siblings.size > SIBLINGS_SHOWN
             end
 
             lines << ""

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.2"
+  VERSION = "5.36.4"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-ai-context
 version: !ruby/object:Gem::Version
-  version: 5.36.2
+  version: 5.36.4
 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