rails-ai-context 5.30.1 → 5.31.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e31095f85a3f90825fbd66bf2a7deae9224ac4fe94474c8d60da20c46ed52b47
-  data.tar.gz: 190a7d48230b4ae98300b2619a0d2cf7a1ddb8a6e24619a7a54cfa3a6e5b233b
+  metadata.gz: 44b4fb64c009d96449f8f05375947d6713b07d0a45c7f27e779e0ac271c0bfa6
+  data.tar.gz: d0045d00ef00250f97eeae2ff105b09c7f991a3746c9198bc8126b3e79d8dc2a
 SHA512:
-  metadata.gz: f91198dc48ae6f259c0f4d170b0fbae5d2174fa142a64530ef4ac46f2e6c51c9e22e54057e7f64712f06fc76a085e45994da2a9dc592edfe9ee3f0366608d642
-  data.tar.gz: cee2a7a2d636322fddeedcffa151812d0ae8c52cde17d99394fd7dded5e30e5bddb8db288bc9b31b0fe1281a9a33270739c000735957fab6d64cbafdfec8a149
+  metadata.gz: e60a1a843d881a90404c7f87b6a29e829a60210195375c94a90151b82850d749820828b752e9e6f5f60b22dd92bf948bb8275f207c7df801ce954bd9a53705cd
+  data.tar.gz: 4aa95471cb0a3a4ad1cec127db6322b9b0b5d1f39f00826b1c73dd246cf0acfadc51e14f3e9f16b1cd6f3602acb618ee520eadc2b674825d2f95e675dfa7e6c1

data/CHANGELOG.md

@@ -5,6 +5,301 @@ 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.31.0] - 2026-10-05
+
+### Changed
+
+- **A committed placeholder is not a secret.** A file whose name ends in
+  `.example`, `.sample`, `.template` or `.dist` (`.env.example`) is readable by
+  `rails_get_edit_context` and the other file tools, although the default
+  `.env.*` pattern matches it, and `doctor` no longer lists it as unread or
+  says to gitignore it. A `sensitive_patterns` entry that names the file
+  exactly, with no glob characters, still blocks it, and so does a path
+  pattern with a `/` (`.ssh/*` keeps `.ssh/id_rsa.template` blocked).
+  Redaction treats the four suffixes alike. `rails_search_code` now drops
+  sensitive files from ripgrep's output where it used to exclude them by glob,
+  so a sensitive file ripgrep cannot open is not reported as an error and does
+  not send a no-match search through the Ruby fallback. (#267)
+- **`rails_query` on a SQLite file stops at `query_timeout`.** The query runs
+  in a child process with its own read-only connection, which is stopped at the
+  deadline. sqlite3 2.x's `statement_timeout=` interrupts any statement of more
+  than a few thousand steps whatever the value, and the extension holds the GVL
+  while a statement runs, so no in-process limit exists. The child takes the
+  app's `extensions:` and waits on a locked database as the app would. An
+  in-memory database, a platform without `fork`, or a query that needs a
+  function, virtual-table module, collation or encryption key only the app's
+  own connection has runs in-process; the table and EXPLAIN answers then say it
+  ran without a time limit, and CSV output stays plain data. (#256)
+- **`rails_get_callbacks` lists callbacks in the order Rails runs them**: base
+  classes first, a concern's callbacks where its `include` line stands, then
+  the model's own, and a `before_` or `around_` callback with `prepend: true`
+  first. `after_commit` and `after_rollback` list last declared first, as
+  Rails runs them, unless `run_after_transaction_callbacks_in_order_defined`
+  is on (`load_defaults 7.1` or later). The static tier reads that from
+  `config/application.rb` and the initializers, the last line that sets it
+  winning, and when the config does not tell, `rails_get_callbacks` and
+  `rails_get_model_details` say so. A method declared twice under one callback
+  type shows the declaration Rails keeps, the later one, which corrects the
+  5.30.0 entry that said each declaration is shown. A declaration inside a
+  method body counts where the class calls the method, and not at all when
+  nothing does, so an uncalled method that redeclares a callback no longer
+  hides it. A call counts written bare or as `self.name`, made inside a class
+  method it runs, or made from a concern's `included` block. A module joins a
+  class chain once, at the first place the chain adds it: the outermost class
+  that adds it, at its first include there, which can be a call to a class
+  method that includes it. A Concern's `included` block runs there only; a
+  plain `self.included` hook runs on every include. A call runs the definition
+  Ruby's lookup finds as of the call: a module the class prepends to its
+  singleton class, the class's own class methods, then the modules it extends
+  and its concerns' class methods, the last added first, then the same for
+  each base, then what every model has: class methods an initializer writes in
+  `ActiveRecord::Base.class_eval` or a reopened base, the file Rails loads
+  later winning (Canvas's `validates_locale` adds its `before_validation` to
+  Account, User and Course), then the modules mixed into the base. One an
+  initializer writes on `ApplicationRecord` replaces ApplicationRecord's own.
+  A class's own class methods are its `def self.`, an `alias_method` in
+  `class << self` (it runs what its original name ran at the alias), and those
+  a Concern's `included` block or a hook writes on the class (`def self.x` or
+  `class << self`, in the block, in `base.class_eval` or in `class << base`),
+  each from its line where that code runs. A module counts from the line
+  adding it, where that line runs: an `extend`, `singleton_class.include` or
+  `singleton_class.prepend` (which counts as prepended) in the class, in a
+  hook or in a Concern's `included` block, and an `extend` in a class method a
+  call reaches (an `acts_as_x` that extends its methods, whose `self.extended`
+  hook then runs); a plain module's nested `ClassMethods` counts only when
+  something extends it. A module a hook includes runs its own hooks. Two
+  concerns' modules of one name (each concern's `ClassMethods`) stay two: each
+  name is the constant it resolves to where it is written, and one that
+  resolves to nothing no longer hides the other. A `super` runs the next
+  definition, at the `super`. An instance method or a nested class's method of
+  the same name never runs. A module a class method includes joins only when a
+  call reaches that method, and only calls after it see its methods. A nested
+  class's callbacks are its own, and a module nested in the model's file reads
+  like any concern: `include` runs its `included` block, `extend` its methods
+  and `self.extended` only. A module a plugin's lib loads by a glob `require`
+  is read from beside the file naming it, and from its definition rather than
+  an empty namespace stub above it, so OpenProject's journalized models list
+  `save_journals`. A Mongoid document's own callbacks list in the same run
+  order, one in a class method where the document calls it. Neither tier
+  evaluates `send`, `define_singleton_method` or a module included in
+  `class << self` for this, so the list can miss what they register or show
+  the definition they replace. (#253)
+- **A lambda or Proc given to `queue_as` reads as what ActiveJob does with
+  it.** ActiveJob never calls it; it names the queue after the Proc's text.
+  Both tiers now say so, with the source, where the booted tier printed the
+  Proc's address and the static tier called it computed. A `queue_as` block is
+  the computed case and now shows its source too; a block argument
+  (`queue_as(&pick)`) reads as computed in both tiers. The 5.30.0 entry used
+  `queue_as -> { ... }` as its example of a computed queue; that was wrong.
+  (#271)
+- **An MCP stdio session carries nothing but JSON-RPC on stdout for its whole
+  life.** Output written during a tool call (a logger built on first use, as
+  Sidekiq's is, `puts`, a child process) goes to stderr; only boot was guarded
+  before. (#255)
+- **The booted `rails_security_scan` parses in its own process.** Brakeman's
+  forked parse workers could not return a parse error from an app that loads
+  web-console, and the scan failed where the static tier scanned. (#257)
+
+### Fixed
+
+- **A concern's declarations name the module the include resolves to.**
+  `rails_get_callbacks` on OpenProject's WorkPackage lists
+  `after_save :save_journals` from `Acts::Journalized::SaveHooks`, where it
+  said `SaveHooks`.
+- **A module declared in its outer module's file is read from there.**
+  Canvas's `Role::AssociationHelper` lives in role.rb, and its `included`
+  hook adds `before_save :resolve_cross_account_role` to Enrollment and its
+  subclasses, AccountUser and RoleOverride; the static tier called the
+  module unread and missed the callback. `rails_get_callbacks`,
+  `rails_get_model_details` and the controller filters and actions find it
+  there and read that module, not the outer class.
+- **`rails_get_callbacks` lists models of one callback count by name**, so a
+  model gaining a callback no longer moves the sections around it.
+- **A model macro written over `*args` reads each call's own arguments.**
+  The list binds to the call's positionals past the method's other
+  parameters, less the options hash the body takes off the end
+  (`args.extract_options!`), plus literals its leading statements push. A
+  block over the list is read once per item, so Canvas's
+  `validates_locale :locale, :browser_locale, allow_nil: true` lists an
+  inclusion validation on each field with its own `if: :<field>_changed?`, in
+  place of the macro's own row and one on a computed `field`. An options
+  hash, list or parameter the method changes in place (`options[:x] = 1`,
+  `options[:x] ||= 1`, `reverse_merge!`, `delete`) is not read as the call's
+  value. A declaration it decides, the method name included (`before_save
+  name` after `name.strip!`), is held back and listed under "Not decided from
+  the source (the method name or a condition)", the heading that was "Only
+  under a condition the source does not decide".
+- **A `load_defaults` written after `belongs_to_required_by_default = false`
+  turns the default back on** in the static tier, as Rails does, so the
+  implicit presence of a required `belongs_to` is listed. A literal assignment
+  used to win wherever it stood. A value the source cannot evaluate
+  (`ENV.fetch(...) == "true"`), app-wide or in the class, makes the presence
+  conditional on it, named in the answer. A literal `nil` reads as off, as
+  Rails reads it, here and for the commit-order setting. A `belongs_to` with
+  `required: nil` is optional, and `required:` decides over `optional:` when
+  both are written, as in Rails.
+- **`rails_get_callbacks` prints `on:`** for validation callbacks and any
+  callback whose type does not already name the event, before `if:` and
+  `unless:`. (#252)
+- **`rails_performance_check` with `model` and `category` counts only what it
+  lists.** (#265)
+- **`rails_search_docs` caches a fetched guide whole.** A guide with non-ASCII
+  text failed to write in the booted tier and left an empty file that read as a
+  cached guide for 24 hours; the write is now binary and atomic, and an empty
+  cache file is a miss. (#266)
+- **`rails_search_code` trace finds one definition and no sibling of itself**:
+  `qa_ping` no longer matches `def qa_ping?`, `qa_ping!` or `qa_ping=`, and
+  `def self.qa_ping` is left out of its own sibling list, where a setter now
+  appears. Every method-body lookup (concerns, callbacks, actions, conventions)
+  ends a name the same way, and ripgrep and the Ruby fallback agree on
+  non-ASCII text, where any character outside ASCII is part of the name, as
+  Ruby reads it. (#258)
+- **`rails_search_code` call sites skip comment lines** with the rule trace
+  uses, by file type: `#` in Ruby, `//` and `/*` in JS and TS, `/*` in CSS and
+  `//` too in SCSS, Sass and Less, `-#` in Haml, `/` in Slim. A stylesheet
+  line that starts with a `#id` selector is not a call site either. A line
+  holding a live ERB tag is a call site, and a spaced setter call
+  (`obj.qa_ping = 1`) is not a call of `qa_ping`. (#269)
+- **Both search backends read the same excludes file.** The Ruby fallback read
+  `core.excludesFile` from the repository's own config, which ripgrep does not.
+  It now reads what ripgrep 15 reads: `~/.gitconfig`, then the XDG git config,
+  then the default ignore file. (#268)
+- **A `db/structure.sql` table that `INHERITS` reads its parent's columns
+  first, then its own**, with multiple parents, chains, a parent defined later
+  in the file, and `ALTER COLUMN ... SET NOT NULL`/`SET DEFAULT`. A parent in
+  another schema resolves; one the file does not define is named. An index, key
+  or foreign key lands on the table its statement names, schema included. The
+  one-line form read its column type as `integer) INHERITS (...`. (#259)
+- **A Stimulus controller under `app/javascript/controllers` keeps its
+  identifier** when another `controllers` directory holds the same path, and a
+  nested `controllers` directory stays in the name (`admin--controllers--x`).
+  (#264)
+- **`query_allowed_columns` exempts a column from result redaction too**, as
+  it does from the pre-query check. Columns declared with `encrypts` stay
+  redacted. (#270)
+
+## [5.30.2] - 2026-10-01
+
+### Changed
+
+- **`generate_root_files: false` leaves out `.cursorrules` too, and always
+  writes `.ai-context.json`.** `.cursorrules` is the same compact file as
+  `CLAUDE.md` at the repo root, so it is a root file and now reports "Not
+  applicable (root files disabled)". `.ai-context.json` is data for tools, not
+  an instruction file, and is written whatever the key says.
+- **`serve --port` has no default of its own.** An explicit `--port` wins, then
+  `http_port` from the config, then 6029. The config key never reached `serve`
+  before, although `docs/STANDALONE.md` documents it, and the
+  `streamable_http` alias ignored `--port`.
+- **A PostGIS connection is labelled PostgreSQL everywhere.** The booted schema
+  said PostGIS and the static tier PostgreSQL for the same app. The raw adapter
+  name stays in `.ai-context.json` as `adapter_source`.
+- **The booted schema header lists pending migrations**, as the static tier
+  already did.
+
+### Fixed
+
+- **No machine path in an introspector's error.** A model file that could not
+  load put the absolute path of the app into `rails_get_model_details`,
+  `CLAUDE.md`, the models rules file and `.ai-context.json`, and the controller,
+  component, middleware, migration and rake-task errors did the same. Every
+  section's errors are now written relative to the app root, the resolved
+  `/private/tmp` form included.
+- **A declared, unmigrated table names the migration that adds it.** The booted
+  answer said the table was missing from the database and stopped there. Rails
+  7.2+ refuses to load a migration dated in the future, which also emptied the
+  pending list; the list now comes from the applied versions and the files.
+- **An unreadable model file still counts as the model file for its table**,
+  instead of listing the table under "Tables with no model file".
+- **The static tier carries each `belongs_to` foreign key.** Static
+  association records had none unless the source spelled one, so
+  `rails_get_model_details`, the context files and `.ai-context.json` left it
+  out, and `rails_validate` stayed silent on an unindexed key where the booted
+  tier warned. A polymorphic key indexed as `[type, id]` counts as indexed.
+- **A composite foreign key in `db/structure.sql` is read**, pg_dump and
+  mysqldump both, and renders as a column list like the schema.rb one.
+- **Minitest tests from `rails_generate_test` can pass.** Absence,
+  confirmation, acceptance and exclusion validations asserted on a valid
+  fixture; each now sets up an invalid record, or emits `skip` where it cannot.
+- **A mount at a computed path prints no path.** `mount X => ENV.fetch(...)`
+  printed `` at `[INFERRED]` ``, a bare constant printed its name as the path,
+  and a gem engine mounted that way read as "not mounted by the app's routes".
+  A path written without its leading slash gets one, as Rails does.
+- **Static routes say which engine tables they could not read.** An engine
+  whose routes live in its gem (PgHero, LetterOpenerWeb) dropped out of the
+  static answer with no note; it is listed under "Mounted engines whose routes
+  were not read". A constant the app defines counts as an engine only when it
+  subclasses `Rails::Engine`. An engine mounted at several paths is one line
+  naming each.
+- **Booted filter attribution matches the static tier.** An inherited
+  `after_action` lost its "from" credit when the child declared a
+  `before_action` of the same name, filters from a controller concern were not
+  credited to it, and a concern's `only:`/`except:`/`if:`/`unless:` and its
+  `skip_*_action` calls never reached the booted record. A body that
+  re-declares a concern's filter owns it, and a concern an ancestor already
+  includes stays the ancestor's.
+- **An ERB comment is not read for instance variables**, while a Ruby comment
+  line inside a multi-line code tag no longer hides the code after it.
+- **`rails_get_partial_interface` finds `render(partial: ...)`** with
+  parentheses, on one line or several, counts a nested render once, and a
+  multi-line snippet stops at the call's end.
+- **Jobs on Rails 7.0 to 8.1.** A job with no `queue_as` read as "computed by a
+  block", since ActiveJob's default queue is a lambda; it now shows the
+  resolved default. The booted tier dropped every `retry_on`/`discard_on`, and
+  a job in a code root Zeitwerk does not manage.
+- **A mailer outside `app/mailers` is a mailer in the booted tier too**, and
+  `rails_get_service_pattern` no longer answers a mailer, concern or mixin by
+  name when its listing leaves them out.
+- **`app/concerns` reads as `other`** when the app root directory is itself
+  named `app`, as in Docker's `/app`.
+- **The static default locale reads `Rails.application.config.i18n`** in an
+  initializer, where the last assignment wins.
+- **A bad value for a required enum fails the call.**
+  `migration_advisor --action bogus` said "action is required" and exited 0;
+  it says `bogus` is not a valid `action`, names the allowed values and exits 1.
+- **`rails_diagnose` never suggests a path it refused**, refuses it with or
+  without `--line`, and prints the tier footer once.
+- **`rails_validate` names a `belongs_to` whose key column the table lacks**
+  instead of calling that column unindexed, and says nothing about a table's
+  indexes when its schema calls a helper the reader cannot interpret (Canvas's
+  `t.replica_identity_index`), since that helper may add the index.
+- **A multi-name `t.references :a, :b, :c` adds every column**, with its index
+  and foreign key, in the schema.rb reader and the migration replay. The replay
+  also records `foreign_key: true` on a single reference, which it dropped.
+- **A declaration inside a block the model may not run is kept but not
+  trusted.** `has_details_table do belongs_to :parent end` put a `parent_id`
+  key on the model's own table, and `rails_validate` checked it there. Such
+  declarations are still listed, and `rails_validate`'s schema, column and
+  `:dependent` checks skip them. `with_options`, `included`, `class_methods`,
+  `concerning`, `state_machine` and `aasm` blocks run on the model and are
+  trusted as before.
+- **A foreign key given as a constant or an expression is not read as a column
+  name**, and a composite key stays a column list in both tiers instead of the
+  text of a Ruby array.
+- **Every column type reads as a column in the static schema**, `t.vector`,
+  `t.citext`, `t.enum`, the range and PostGIS types included, and so does a
+  column whose options sit in braces. They were left out of the table.
+- **`attr_reader` and `alias_attribute` names count as attributes** for
+  `rails_validate`'s "column not found" check.
+- **Filters inherited through a Devise or Doorkeeper controller.** The static
+  walk stopped at the gem class, so a controller under `Devise::` or
+  `Doorkeeper::` lost every filter its app base declares and was credited with
+  a concern that base already includes. It now continues at the base the gem's
+  initializer names (`parent_controller`, `base_controller`).
+- **In-repo route files are read statically.** A mounted in-repo engine's own
+  routes are listed under its mount, and a file that draws, appends or prepends
+  to the app's routes adds to the app's table; only an unmounted engine's file
+  still counts as not read.
+- **A failed boot names missing gems once.** A bundle missing many gems listed
+  every name three times; the banner now gives the count and the first few,
+  and `doctor` and `DEBUG=1` keep the full list.
+- **A test file over `max_test_file_size` is named as too large**, not missing.
+- **`rails_runtime_info` says how many rows it left out** of the unused-index
+  list and the summary table sizes, which it cut at 10 and 5 with no note.
+- **`rails_query` on MySQL** reads a `MAX_EXECUTION_TIME` interruption as the
+  timeout, and names `INTO OUTFILE`/`DUMPFILE` as a disk write.
+- The defaults in `configuration.rb`'s comments match the values it sets.
+
 ## [5.30.1] - 2026-09-28
 
 ### Fixed

data/docs/CLI.md

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

data/docs/COMPATIBILITY.md

@@ -215,7 +215,14 @@ Proof sources:
    PostgreSQL 17 with a partitioned table added, booted and static from
    schema.rb and structure.sql, a Rails 7.2 app whose schema.rb carries no
    partition marker, and Discourse, Mastodon, OpenFoodNetwork and Forem
-   answering as before.
+   answering as before. In the v5.30.2 release QA: 14 real apps answered by
+   v5.30.1 and by the release branch side by side, and the lab regressions on
+   SQLite in all three tiers, PostgreSQL and MySQL. In the v5.31.0 release QA:
+   a private Rails 8.0 API app booted and static, and Discourse, Mastodon,
+   Forem, OpenFoodNetwork, OpenProject, Consul, Canvas and Errbit answered by
+   v5.30.2 and by the release branch side by side, every changed answer
+   checked against the app's source; the lab regressions on SQLite in all three
+   tiers, PostgreSQL and MySQL; and the unit suite on Ruby 3.1 with Rails 7.0.
 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
@@ -275,12 +282,21 @@ Postgres instance in `spec/e2e/postgres_install_spec.rb`, opt-in via
   stay marked `[UNAVAILABLE]`. A concern whose file cannot be found, a gem's
   module for example, is named under `Concerns` as not read.
 - **Callbacks are what the file declares.** In both tiers the callback list is
-  what the model file, the app concerns it includes and the classes it
-  inherits from declare. A callback a
-  gem registers on include without an `include` line in the model file (Devise,
-  counter caches, attachment purges) is not listed. Within one type the order
-  is declaration order, the model file first and then its concerns, not the
-  order Rails registered them in; the order across types is Rails' event order.
+  what the model file, the app concerns it includes and the classes it inherits
+  from declare. A callback a gem registers on include without an `include` line
+  in the model file (Devise, counter caches, attachment purges) is not listed.
+  Within one type the order is the order Rails runs them: base classes first, a
+  concern's callbacks where its `include` line stands, then the model's own,
+  and a `before_` or `around_` callback with `prepend: true` first.
+  `after_commit` and `after_rollback` run last declared first unless
+  `run_after_transaction_callbacks_in_order_defined` is on (`load_defaults 7.1`
+  or later; Rails 7.0 has no such setting). The booted tier reads the setting;
+  the static tier reads `load_defaults` and any assignment in
+  `config/application.rb` or an initializer, the last line that sets it
+  winning, and when those do not say, keeps declaration order and the answer
+  says so. The static tier does not read `config/environments/*.rb` for this
+  setting or for `belongs_to_required_by_default`, so a value set per
+  environment is missed. The order across types is Rails' event order.
 - **Concern-style Mongoid documents in runtime results.** Mongoid documents
   are invisible to ActiveRecord reflection, so `ModelIntrospector#call` falls
   back to the same source-parsing pass used in the static tier even when the

data/docs/CONFIGURATION.md

@@ -86,7 +86,7 @@ config file is written. Before v5.27.0 an empty list wrote every tool's files.
 | `preset` | Symbol | `:full` | `:full` (40 introspectors) or `:standard` (17 introspectors) |
 | `context_mode` | Symbol | `:compact` | `:compact` (context files capped at ~150 lines) or `:full` (no line cap) |
 | `introspectors` | Array of symbols | (from preset) | Override the introspector list directly |
-| `generate_root_files` | Boolean | `true` | Set `false` to generate split rules only, no root CLAUDE.md/AGENTS.md |
+| `generate_root_files` | Boolean | `true` | Set `false` to generate split rules only: no CLAUDE.md, AGENTS.md, .cursorrules or copilot-instructions.md (`.ai-context.json` is still written) |
 | `anti_hallucination_rules` | Boolean | `true` | Embed 6-rule verification protocol in generated context files |
 | `claude_max_lines` | Integer | `150` | Max non-blank lines in a compact context file's gem-managed block, the `<!-- BEGIN/END rails-ai-context -->` markers included. Over budget, data lines are cut and the Commands, Warnings, Rules and MCP-tools sections kept whole |
 
@@ -213,6 +213,9 @@ fits neither that shape nor the conventional one.
 |:-------|:-----|:--------|:------------|
 | `sensitive_patterns` | Array | 34 patterns | File patterns blocked from search/read (`.env*`, `*.env`, `.envrc`, `*.key`, `*.pem`, `config/credentials.yml.enc`, `config/application.yml`, `config/settings.local.yml`, `.ssh/*`, etc.) |
 
+A placeholder such as `.env.example` stays readable unless a path pattern or
+its exact name blocks it; see [SECURITY.md](SECURITY.md).
+
 ### Extensibility
 
 | Option | Type | Default | Description |
@@ -247,7 +250,7 @@ Lightweight subset for faster generation:
 | AI Tool | Root File | Split Rules | MCP Config |
 |:--------|:----------|:------------|:-----------|
 | Claude Code | `CLAUDE.md` | `.claude/rules/*.md` | `.mcp.json` |
-| Cursor | - | `.cursor/rules/*.mdc` | `.cursor/mcp.json` |
+| Cursor | `.cursorrules` (legacy fallback) | `.cursor/rules/*.mdc` | `.cursor/mcp.json` |
 | GitHub Copilot | `.github/copilot-instructions.md` | `.github/instructions/*.instructions.md` | `.vscode/mcp.json` |
 | OpenCode | `AGENTS.md` | `app/*/AGENTS.md` | `opencode.json` |
 | Codex CLI | (shares `AGENTS.md`) | (shares OpenCode rules) | `.codex/config.toml` |

data/docs/FAQ.md

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

data/docs/GUIDE.md

@@ -826,7 +826,13 @@ rails_get_callbacks(model: "Order", detail: "full")
   → Order's callbacks with the actual method source code for each callback
 ```
 
-**Returns:** Callbacks grouped by type, in Rails event order. Includes concern-provided callbacks, with their bodies read from the concern file. Within one type the order is declaration order, not the order Rails registered them in.
+**Returns:** Callbacks grouped by type, in Rails event order. Includes
+concern-provided callbacks, with their bodies read from the concern file.
+Within one type the order is the order Rails runs them, base classes first, a
+`before_` or `around_` callback with `prepend: true` first, and
+`after_commit`/`after_rollback` last declared first unless the app runs them in
+order (`load_defaults 7.1`). A method declared again shows once with the later
+declaration's conditions.
 
 ### rails_get_helper_methods
 
@@ -1353,7 +1359,7 @@ end
 | `live_reload_debounce` | Float | `1.5` | Debounce interval in seconds for live reload |
 | `server_name` | String | `"rails-ai-context"` | MCP server name |
 | `server_version` | String | gem version | MCP server version |
-| `generate_root_files` | Boolean | `true` | Generate root files (CLAUDE.md, etc.) - set `false` for split rules only |
+| `generate_root_files` | Boolean | `true` | Set `false` to generate split rules only: no CLAUDE.md, AGENTS.md, .cursorrules or copilot-instructions.md (`.ai-context.json` is still written) |
 | `anti_hallucination_rules` | Boolean | `true` | Embed 6-rule Anti-Hallucination Protocol in generated context files - set `false` to skip |
 | `hydration_enabled` | Boolean | `true` | Inject schema hints into controller/view tool responses |
 | `hydration_max_hints` | Integer | `5` | Max schema hints per tool response |

data/docs/INTROSPECTORS.md

@@ -186,7 +186,7 @@ It runs a single-pass Dispatcher that walks the AST once and feeds events to all
 | CallbacksListener | All AR callback types including `around_*`, `after_touch`, `after_initialize` and `after_find`; `after_commit` with `on:` resolution; a callback object by its constant, a block as `[inline_block]`; `if:`/`unless:` kept as the source wrote them, and the options of an enclosing `with_options` block |
 | MacrosListener | `encrypts`, `normalizes`, `delegate`, `has_secure_password`, `serialize`, `store`, `has_one_attached`, `has_many_attached`, `has_rich_text`, `generates_token_for`, `attribute` |
 | MethodsListener | `def`/`def self.`, visibility tracking, parameter extraction, `class << self`; `include_initialize: true` adds the constructor a caller reports on its own |
-| MixinsListener | `include`, `prepend`, `extend`, flagging the ones that reach the ancestor chain |
+| MixinsListener | `include`, `prepend`, `extend`, `singleton_class.include` and `singleton_class.prepend` (`singleton_class.extend` is not read), flagging the ones that reach the ancestor chain, as reflection reports them |
 
 ### The targeted-walk listeners
 
@@ -214,8 +214,13 @@ Passed to `SourceIntrospector.walk(path, key => Listener)` when a specific file
 | MailboxRoutingListener | Action Mailbox `routing` and processing callbacks |
 | ModelReferenceListener | Model constants used in controllers: `Post.find`, `params.require(:post)`, ivar writes |
 | VariantCallListener | `variant` calls (ChainedCallListener with `:variant` preset) |
+| ProcLiteralListener | Proc literals: line, source, assigned constant |
 | MethodCallListener | Call sites by name or pattern anywhere in a file, inside a `def`, a lambda or a block included, with arguments, options, receiver and line. Used by the Turbo introspector for broadcast calls and by `ActionFilters` for the skip macros |
 
+`GenericMacroListener.new(*names, block_source: [:name])` adds `block`, the
+one-line source of the block those macros are given. ProcLiteralListener is
+what the job introspector reads a `queue_as` Proc with.
+
 ### Adding a listener
 
 1. Subclass `BaseListener` in `lib/rails_ai_context/introspectors/listeners/`. Use its helpers rather than re-reading nodes: `extract_symbol_args`, `extract_keyword_options`, `extract_arg_values` (source-slice fallback for expressions like `2.hours`), `extract_keyword_sources`, `extract_keyword_nodes`, `keyword_hash`, `constant_path_string`.

data/docs/SECURITY.md

@@ -66,10 +66,23 @@ After validation, the query runs inside a transaction:
 |:---------|:----------|
 | PostgreSQL | `SET TRANSACTION READ ONLY` + `SET LOCAL statement_timeout` |
 | MySQL | `SET TRANSACTION READ ONLY` + `MAX_EXECUTION_TIME` hint |
-| SQLite | `PRAGMA query_only = ON` + progress handler for timeout |
+| SQLite | A read-only connection in a child process, killed at timeout |
 
 All queries execute inside a transaction, then rollback (even if they could write, they can't).
 
+A SQLite query runs in-process under `PRAGMA query_only = ON`, with no time
+limit, for an in-memory database, on a platform without `fork`, or when it
+needs a function, virtual-table module, collation or encryption key only the
+app's own connection has. The table and EXPLAIN answers then say so; CSV output
+stays plain data.
+
+On sqlite3 1.x a query fails at its timeout, with the statement-timeout error,
+when another connection in the same process held an exclusive lock on a
+rollback-journal database as it started (`BEGIN EXCLUSIVE`): the child
+inherits that lock record and it never clears. A lock held
+by another process is waited on as usual, and an open write transaction or any
+lock in WAL mode does not block it.
+
 ### Layer 3 - Row limit
 
 - Default: 100 rows
@@ -90,6 +103,9 @@ If one of your own columns merely looks sensitive (an `oauth_applications.secret
 config.query_allowed_columns = %w[secret]
 ```
 
+The exemption covers the results too: an allowed name comes back unredacted. A
+column declared with `encrypts` stays `[FILTERED]` either way.
+
 ### Environment guard
 
 > [!WARNING]
@@ -115,6 +131,12 @@ config/mongoid.yml config/redis.yml
 .ssh/* .aws/credentials .aws/config .netrc .pgpass .my.cnf
 ```
 
+A placeholder whose name ends in `.example`, `.sample`, `.template` or
+`.dist` (`.env.example`) is committed to be read, so a basename glob such as
+`.env.*` does not block it. A pattern that names it exactly, with no glob
+characters, still does, and so does a path pattern (one with a `/`, such as
+`.ssh/*`), which covers everything under it.
+
 ### AI context file exclusions
 
 Search also excludes generated AI context files to prevent circular references:

data/docs/TOOLS.md

@@ -179,8 +179,17 @@ Concerns as `[UNAVAILABLE]` rather than dropped.
 Callbacks grouped by type, in Rails event order, with source code. The list
 covers concern-declared callbacks too, with the body read from the concern
 file, and the "From Concerns" section says which concern declared each one.
-Within one type the order is declaration order (the model file first, then
-its concerns), not the order Rails registered them in.
+Within one type the order is the order Rails runs them: base classes first, a
+concern's callbacks where its `include` line stands, then the model's own, and
+a `before_` or `around_` callback with `prepend: true` first. `after_commit`
+and `after_rollback` are last declared first unless the app turns on
+`run_after_transaction_callbacks_in_order_defined` (`load_defaults 7.1`). A
+method declared again for one type shows once, with the later declaration's
+conditions, as Rails keeps it. The order is read from source in both tiers,
+and dynamic dispatch is not evaluated: a callback registered through
+`send(:before_save, ...)`, through a method called with `send` or defined with
+`define_singleton_method`, or through a module included in `class << self` is
+not read, so the list can miss it or show the definition it replaces.
 
 | Parameter | Type | Default | Description |
 |:----------|:-----|:--------|:------------|

data/exe/rails-ai-context

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