rails-ai-context 5.32.0 → 5.32.2

data/docs/INTROSPECTORS.md

@@ -84,20 +84,20 @@ end
 
 | Introspector | Key | What it extracts |
 |:-------------|:----|:-----------------|
-| SchemaIntrospector | `:schema` | Database tables, columns, types, indexes, defaults, encrypted hints |
+| SchemaIntrospector | `:schema` | Database tables, columns, types, indexes, defaults, check constraints, enum types, extensions |
 | ModelIntrospector | `:models` | Associations, validations, scopes, enums, concerns (AST-based). Both tiers merge what the included concerns declare, tagged `from_concern:`; a concern whose file could not be read is listed in `concerns_unread`, a base class whose file could not be read in `bases_unread`, and the number of concerns `excluded_concerns` hid in `concerns_hidden` |
 | RouteIntrospector | `:routes` | Routes with helpers, HTTP methods, constraints |
-| ControllerIntrospector | `:controllers` | Actions, filters, strong params, render paths |
+| ControllerIntrospector | `:controllers` | Actions, filters, strong params, concerns, `rescue_from` handlers, rate limits |
 | ViewIntrospector | `:views` | View files, layouts, partials |
-| ViewTemplateIntrospector | `:view_templates` | Template content with ivars, Turbo frames, Stimulus refs |
+| ViewTemplateIntrospector | `:view_templates` | Each template with its line count, ivars, rendered partials and Stimulus refs; each partial with its line count, model fields and helper calls |
 
 ### Models & Data
 
 | Introspector | Key | What it extracts |
 |:-------------|:----|:-----------------|
-| MigrationIntrospector | `:migrations` | Migration files, versions, reversibility. `recent` and `pending` entries are `{ version:, name: }`, and the name is the migration class (`CreatePosts`) in both tiers |
+| MigrationIntrospector | `:migrations` | Migration files, versions, the schema actions each one takes. `recent` and `pending` entries are `{ version:, name: }`, and the name is the migration class (`CreatePosts`) in both tiers |
 | SeedsIntrospector | `:seeds` | Seed file analysis |
-| DatabaseStatsIntrospector | `:database_stats` | Table sizes, row counts, index stats |
+| DatabaseStatsIntrospector | `:database_stats` | Approximate row counts per table, plus dead rows on PostgreSQL |
 | MultiDatabaseIntrospector | `:multi_database` | Multi-database configuration |
 
 ### Frontend
@@ -114,14 +114,14 @@ end
 
 | Introspector | Key | What it extracts |
 |:-------------|:----|:-----------------|
-| ConfigIntrospector | `:config` | Database, cache, queue, Action Cable config |
+| ConfigIntrospector | `:config` | Cache store, session store, time zone, queue adapter, mailer settings, middleware stack, initializers, `Current` attributes, error monitoring |
 | GemIntrospector | `:gems` | Notable gems with versions and categories |
-| ConventionIntrospector | `:conventions` | Auth patterns, flash messages, test patterns |
+| ConventionIntrospector | `:conventions` | Architecture markers (service objects, Hotwire, GraphQL and others), model patterns (STI, soft delete, state machines and others), directory structure, config files |
 | I18nIntrospector | `:i18n` | Locale files, translation keys |
 | MiddlewareIntrospector | `:middleware` | Rack middleware stack. The static tier declares an alternate source rather than an empty stack: without a booted app it answers only the file facts it can read. `config.ru`'s top-level `use` and `map` calls (`rackup`) are read on both tiers with `ConditionalMacroListener`, each with the `if` it sits under; a `map` whose block runs the app itself is a path prefix, so the `use` calls inside it are listed instead of the map |
 | EngineIntrospector | `:engines` | Mounted engines |
 | EnvConfigIntrospector | `:env_config` | Per-environment config files: notable toggles (`force_ssl`, `eager_load`, caching, queue adapter), assigned config keys, plus the keys `config/application.rb` sets and each `config_for` file's keys |
-| DevopsIntrospector | `:devops` | Dockerfile, CI config, deployment |
+| DevOpsIntrospector | `:devops` | Puma config, Procfile, health check, Dockerfile, deployment tool |
 
 ### Jobs & Services
 
@@ -159,7 +159,7 @@ These introspectors map directly onto the internal RAILS_NERVOUS_SYSTEM checklis
 | Introspector | Key | Nervous-system § | What it extracts |
 |:-------------|:----|:---|:-----------------|
 | InitializerIntrospector | `:initializers` | §2 | `Rails.application.initializers` graph: name, owner, `before:`/`after:` edges, block `source_location`, per-file `config/initializers/*.rb` summary |
-| AutoloadIntrospector | `:autoload` | §3 | Zeitwerk presence, autoloaders (`:main` / `:once`) with collapsed + ignored dirs, `autoload_paths`, `eager_load_paths`, the root directories each loader holds (other engines' and `push_dir` roots, with the namespace they load under), custom inflections (`acronym`, `plural`, `singular`, `irregular`) |
+| AutoloadIntrospector | `:autoload` | §3 | Zeitwerk presence, autoloaders (`:main` / `:once`) with collapsed + ignored dirs, `autoload_paths`, `eager_load_paths`, the root directories each loader holds (other engines' and `push_dir` roots, with the namespace they load under), custom inflections (`acronym`, `plural`, `singular`, `irregular`, `uncountable`, `human`) |
 | ConnectionPoolIntrospector | `:connection_pool` | §10 | Per-database adapter config: pool size, `checkout_timeout`, `reaping_frequency`, `prepared_statements`, `advisory_locks`, replica flag, connection-handler roles, automatic shard selector detection |
 | ActiveSupportIntrospector | `:active_support` | §17 | Concerns in `app/**/concerns/` (ActiveSupport::Concern flags, `included do`/`class_methods do` blocks), deprecators registry, MessageEncryptor/Verifier usage, notification subscriptions read from source (`subscribe`, `monotonic_subscribe`, `attach_to`), TaggedLogging config, common on-load hooks, cache store options |
 | CredentialsIntrospector | `:credentials` | §30 | Default + per-env encrypted files, master-key source (`env:RAILS_MASTER_KEY` vs `file:config/master.key` vs missing), `require_master_key` flag, arbitrary encrypted configs (`config/*.yml.enc`), top-level key **names only** (never values) |
@@ -183,9 +183,9 @@ It runs a single-pass Dispatcher that walks the AST once and feeds events to all
 | ValidationsListener | `validates`, `validates_*_of`, custom `validate :method`, under the options of an enclosing `with_options` block |
 | ScopesListener | `scope :name, -> { ... }`, `lambda { ... }` and the block form |
 | EnumsListener | Rails 7+ and legacy enum syntax, prefix/suffix options |
-| 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 |
+| CallbacksListener | All AR callback types including `around_*`, `after_touch`, `after_initialize` and `after_find`; `after_commit` with `on:` resolution; a callback object as the source wrote it (`Normalizer`, `Normalizer.new`), a block as `[inline_block]`; `if:`/`unless:` kept as the source wrote them, and the options of an enclosing `with_options` block |
 | MacrosListener | (each attribute macro and `has_secure_password` with its keyword options as written, under `written`) `encrypts`, `normalizes`, `delegate`, `has_secure_password`, `serialize`, `store`, `has_one_attached`, `has_many_attached`, `has_rich_text`, `generates_token_for`, `attribute`, `alias_attribute`, `store_accessor`, `self.ignored_columns`, `has_secure_token`, `accepts_nested_attributes_for`, `attr_readonly`, `query_constraints`, `connects_to` as written (a child carries its base's, with the base's name under `declared_in`), the class settings `self.inheritance_column`/`store_full_sti_class`/`strict_loading_by_default`/`implicit_order_column`/`locking_column =` as written, an `aasm` block's states, initial state, events and transitions, and model gems' class macros (`GEM_MACROS`: `has_paper_trail`, `friendly_id`, `mount_uploader`, `monetize`, `pg_search_scope`, `acts_as_list` and others) as written, without their block |
-| MethodsListener | `def`/`def self.`, visibility tracking, parameter extraction, `class << self`, the methods `delegate` and Forwardable's `def_delegators`/`def_delegator` define (public unless `private: true`, and with no `end_location`, since a delegation has no body), and the methods `alias`, `alias_method`, `attr_*`, `define_method` with a literal name, `class_attribute` and `cattr_*`/`mattr_*` define (an alias keeps its original's visibility and parameters; Active Support's accessors are public on the class and, unless an option turns them off, on instances); each `def` carries `offset`/`end_offset`, which `SourceIntrospector.outside_defs` pairs against a call's `offset` to tell a call on the same line as a def from one inside it; a `Struct.new`/`Class.new`/`Module.new`/`Data.define` block assigned to a constant is that constant's body, and a `def self.x` in `included do` is marked `class_methods_block` like one in `class_methods do`; `include_initialize: true` adds the constructor a caller reports on its own |
+| MethodsListener | `def`/`def self.`, visibility tracking, parameter extraction, `class << self`, the methods `delegate` and Forwardable's `def_delegators`/`def_delegator` define (public unless `private: true`, and with no `end_location`, since a delegation has no body), and the methods `alias`, `alias_method`, `attr_*`, `define_method` with a literal name, `class_attribute` and `cattr_*`/`mattr_*` define (an alias keeps its original's visibility and parameters; Active Support's accessors are public on the class and, unless an option turns them off, on instances); each `def` carries `offset`/`end_offset`, which `SourceIntrospector.outside_defs` pairs against a call's `offset` to tell a call on the same line as a def from one inside it; a `Struct.new`/`Class.new`/`Module.new`/`Data.define` block assigned to a constant is that constant's body, and a `def self.x` in `included do` is marked `class_methods_block` like a `def x` in `class_methods do`; `include_initialize: true` adds the constructor a caller reports on its own |
 | 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. GitLab's `prepend_mod_with("Note")`, `include_mod_with`, `extend_mod_with` and their `_mod` forms record `EE::Note` and `JH::Note` flagged `edition`; `ConcernMembership.owned_by` keeps one only where the app has its file, and credits `Note.prepend X` to Note |
 
 ### The targeted-walk listeners
@@ -200,7 +200,7 @@ Passed to `SourceIntrospector.walk(path, key => Listener)` when a specific file
 | ConstructorMacroListener | Class-body macros that define a constructor: T::Struct `const`/`prop`, Dry::Struct `attribute`/`attribute?`, dry-initializer `param`/`option` (with `extend` recorded so a consumer can check for `Dry::Initializer`), and the attr_extras initializers, `method_object` and `static_facade`. Each record adds `owner`, the one-line `source`, and `params` as `[kind, name, default]` with lambda defaults read as the value they return. Used by `rails_get_service_pattern`, which keeps a record only when the class is that library's |
 | GrapeApiListener | A Grape API class body: each class with its superclass, `version` (with `using:`) and `prefix`, each verb endpoint with the namespaces around it (`namespace`, `resource(s)`, `group`, `segment`, `route_param` as `:id`) and the `requires`/`optional` names of the `params` block before it, and each `mount`. Calls inside an endpoint body are skipped. Used by `GrapeEndpoints`, which decides which classes reach `Grape::API` and builds each path the way Grape does, for `rails_get_routes` |
 | ChainedCallListener | Calls on a receiver: `ChainedCallListener.new(:includes)`, or `receiver: :inflect` to pin the receiver. Reports the receiver name |
-| ConfigAssignmentListener | `config.key = value` and `config.a.b = value` in initializers and `config/environments/*.rb`, plus bare `config.jwt do ... end` section references and settings written without `=` (`<<`, a call with arguments, `+=`/`||=`/`&&=`, a block), tagged `write:`. An assignment whose value is a `config_for` call carries `config_for:` (the YAML file it reads and its `env:`). An assignment whose value is a string or symbol written as one carries `literal: true`. An assignment whose value is not redacted carries the same `arguments:`, `computed:` and `constants:` MethodCallListener reports for the value as one argument. Takes a root name (`:config` by default, e.g. `:DatabaseCleaner`); the root `on_load(:active_record)` reads `self.x =` and `base.x =` for the block's first param inside that `ActiveSupport.on_load` block (not inside a nested class, def or `Foo.class_eval`; a `class_eval` on that self, that param or a root constant keeps the root), and a root named `Receiver.method` (`Apartment.configure`) binds that block's first param |
+| ConfigAssignmentListener | `config.key = value` and `config.a.b = value` in initializers and `config/environments/*.rb`, plus bare `config.jwt do ... end` section references and settings written without `=` (`<<`, a call with arguments, `+=`/`||=`/`&&=`, a block), tagged `write:`. An assignment whose value is a `config_for` call carries `config_for:` (the YAML file it reads and its `env:`). An assignment whose value is a string or symbol written as one carries `literal: true`. An assignment whose value is not redacted carries the same `arguments:`, `computed:` and `constants:` MethodCallListener reports for the value as one argument. Takes a root name (`:config` by default, e.g. `:DatabaseCleaner`); the root `on_load(:active_record)` reads `self.x =` and `base.x =` for the block's first param inside that `ActiveSupport.on_load` block (not inside a nested class or def; inside `Foo.class_eval` `self.x =` is not read while `base.x =` still is; a `class_eval` on that self, that param or a root constant keeps the root), and a root named `Receiver.method` (`Apartment.configure`) binds that block's first param |
 | ClassDefinitionListener | Class definitions with their superclass and the nesting a bare superclass is read in |
 | NestedConstantsListener | The offset ranges of the modules and classes a class body nests, so a filter declared inside one is not read as the outer class's own. Used by `ControllerFilters` |
 | ComponentStructureListener | ViewComponent and Phlex structure: `renders_one`/`renders_many`, slot methods, hash/array constant tables, `case @ivar` variant branching, `CONST[@ivar]` indexing |
@@ -210,11 +210,11 @@ Passed to `SourceIntrospector.walk(path, key => Listener)` when a specific file
 | AutoloadIgnoreListener | The lib subdirectories `autoload_lib(ignore:)` and `autoload_lib_once(ignore:)` keep out of autoloading, as `lib/<name>`. Literal strings and symbols only |
 | PreviewPathsListener | ViewComponent preview directories the config sets: `view_component.previews.paths`, `preview_paths`, `preview_path`, in the same literal forms as AutoloadPathsListener; with `framework: :action_mailer`, the mailer preview directories `action_mailer.preview_paths` and `preview_path` set |
 | I18nLoadPathListener | Locale files `config.i18n.load_path` or `I18n.load_path` adds: `+=`, `<<`, `push`, `append`, `concat`, with `Dir[]`/`Dir.glob` around the same literal forms as AutoloadPathsListener |
-| FixturePathsListener | Fixture directories a test helper sets: `fixture_paths =`/`<<`/`+=`/`push` and the older `fixture_path =`, on `self`, `config`, a constant or no receiver, in the same literal forms as AutoloadPathsListener plus `File.expand_path("x", __dir__)`, `File.expand_path("x", __FILE__)` and `File.join(__dir__, "x")` when given the helper's file; a write whose path it cannot read records `:unread` |
-| DefinitionFilePathsListener | Where a test helper points factory_bot: `FactoryBot.definition_file_paths =` (replaces the defaults) and `<<`/`+=`/`push`/`concat` (adds), each write as `{ replace:, paths: }` in the same forms as FixturePathsListener (`unread: true` and no paths when it cannot read them), and each `FactoryBot.find_definitions`/`FactoryBot.reload` as `{ load: }`, in source order; `::FactoryBot` counts |
+| FixturePathsListener | Fixture directories a test helper sets: `fixture_paths =`/`<<`/`+=`/`push` and the older `fixture_path =`, on `self`, `config` or a constant (`<<`/`push` with no receiver too), in the same literal forms as AutoloadPathsListener plus `File.expand_path("x", __dir__)`, `File.expand_path("x", __FILE__)` and `File.join(__dir__, "x")` when given the helper's file; a write whose path it cannot read records `:unread` |
+| DefinitionFilePathsListener | Where a test helper points factory_bot: `FactoryBot.definition_file_paths =` (replaces the defaults) and `<<`/`+=`/`push`/`concat` (adds), each write as `{ replace:, paths: }` in the same forms as FixturePathsListener (`unread: true` when it cannot read every path, with `paths` holding those it could), and each `FactoryBot.find_definitions`/`FactoryBot.reload` as `{ load: }`, in source order; `::FactoryBot` counts |
 | ViewPathsListener | View roots `config/application.rb` adds to `config.paths["app/views"]`: `unshift` puts one before app/views, `<<`/`push`/`concat` after it, in the same literal forms as AutoloadPathsListener; a write whose path it cannot read is left out |
 | NamespacedRootsListener | Roots `config/application.rb` or an initializer hands Zeitwerk under a namespace: `push_dir(path, namespace: Const)`, as phlex:install writes, in the same literal forms as AutoloadPathsListener; a write whose path it cannot read is left out |
-| SchemaDslListener | `schema.rb`: `create_table`, `t.string`, `t.column`, `t.index`, `add_foreign_key`, `create_enum`, `create_view`, `create_virtual_table`, and the comment the dumper writes for a table it could not describe |
+| SchemaDslListener | `schema.rb`: `create_table`, `t.string`, `t.column`, `t.index`, `add_foreign_key`, `create_enum`, `create_schema`, `create_view`, `create_virtual_table`, the `ActiveRecord::Schema[x.y]` version stamp (a nil one for the unstamped `Schema.define` of Rails before 7.0), and the comment the dumper writes for a table it could not describe. Names drop `public.` unless `raw_names:` is set, which SchemaReader uses to name them against the search path |
 | MigrationDslListener | Migration DSL: `create_table`, `add_column`, `add_index`, `add_reference`, and friends |
 | MigrationReplayListener | What a replay needs beside the DSL: `def down`, `down`/`revert` blocks, and `t.timestamps` |
 | RoutesDslListener | `config/routes.rb`, resolving namespace/scope/resources nesting into flat routes (a `controller:` with a leading slash is absolute, as in Rails); routing concerns (`concern` definitions replayed at each `concerns:` site), `with_options` defaults merged under each inner call, `match ... via:` (or the `via:` of an enclosing `scope`) as one route answering each verb it names (`GET|POST`, and `ANY` for `via: :all`, as the booted table has it), the controller a `scope(controller:)` or a route's own `controller:` names (with Rails' `a/b` shorthand when no action is given), and the `as:`, `param:`, `module:`, `path:` and `only:`/`except:` options. A block drawn through an app class (`ApiRouteSet::V1.draw(self) do`) takes the path and `as:` prefixes that class's `self.prefix` and `mapper_prefix` return as literals, or a literal prefix argument; a class whose prefix is not a literal, and that class's own `resources`, are counted as unexpanded. Routes drawn into an engine's table (`Spree::Core::Engine.routes.draw`) sit under the engine's namespace and carry `engine:`, which the route introspector files under that engine's mount, apart from the app's count. A file pulled in by `draw` is walked inside the scope its `draw` sits in, once per scope that draws it, so `draw :api` under `namespace :api` and `scope module: :v1` routes to `api/v1/...` at `/api/...` |
@@ -288,6 +288,14 @@ same wherever it is asked. Those live as their own modules under
 | `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_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 |
+| `SchemaReader` | What a `schema.rb` dump declares: tables, columns, defaults, indexes, foreign keys, enum types and check constraints. `SchemaReader.for(root)` answers from whichever source the app committed: `schema.rb`, `structure.sql`, or a migration replay |
+| `StructureSqlReader` | A `structure.sql` dump (PostgreSQL, MySQL or SQLite) as the same table shape the other static schema sources produce |
+| `MigrationReplay` | The tables of an app with no schema dump, replayed from its migrations in the dump readers' shape |
+| `SchemaConventions` | The Rails schema conventions every static source must agree on: the implicit `id` key and its type per adapter, what a reference declares, what `t.timestamps` expands to |
+| `PgNaming` | How Rails' PostgreSQL connection and `schema.rb` dumper name extensions, enum types and relations, by Rails version, so the static tier names them as the booted app does |
+| `SqliteVirtualTables` | SQLite's virtual tables and their shadow tables, read from `sqlite_master`. The schema and database stats introspectors ask it |
+| `RenderedRecord` | The records a bare `render @post.comments` hands to Rails, and the partial Rails renders for them. `rails_get_partial_interface` and the view template introspector ask it |
+| `NodeSource` | A node's source with the bodies of the heredocs it opens, which Prism's `slice` leaves out |
 
 ### Confidence tagging
 
@@ -305,7 +313,7 @@ has_many :posts, class_name: name  → [INFERRED]  (name is a variable)
 
 Thread-safe parse cache using `Concurrent::Map`:
 
-- Keyed by: file path + SHA256 content hash + mtime, so a changed file is parsed again
+- Keyed by: the SHA256 hash of the file's content, so a changed file is parsed again
 - A file whose stat (mtime, size, inode) matches the last read answers without reading or hashing it, but only once that file was already two seconds older than the read, so a same-size rewrite within one mtime tick is still read
 - Bounded at 500 parses; a recorded stat is dropped with its parse
 - Shared by all AST-based introspectors
@@ -325,7 +333,7 @@ Introspection results are cached at three levels:
 2. **AST cache** - Per-file parse results, invalidated by file content change (SHA256), with a stat shortcut for a file older than the read
 3. **Run cache** - File lists, stats and directory answers for one introspection run, dropped when it ends
 
-The **Fingerprinter** computes a composite SHA256 from all watched directories (`app/`, `config/`, `db/`, `lib/`, `rakelib/`, `test/`, `spec/`, `Gemfile.lock`, `config.ru`, the Rakefile). When the fingerprint changes, the introspection cache is invalidated even if TTL hasn't expired.
+The **Fingerprinter** computes a composite SHA256 from all watched directories (`app/`, `config/`, `db/`, `lib/`, `rakelib/`, `test/`, `spec/`, the Gemfile and `Gemfile.lock` (or `gems.rb` and `gems.locked`), `package.json`, `tsconfig.json`, `config.ru`, the Rakefile). When the fingerprint changes, the introspection cache is invalidated even if TTL hasn't expired.
 
 **Live Reload** watches these directories and calls `reset_all_caches!` when changes are detected, then notifies connected MCP clients via `notify_resources_list_changed`.
 

data/docs/QUICKSTART.md

@@ -22,13 +22,21 @@ rails generate rails_ai_context:install
 
 The generator asks two questions:
 
-1. **Which AI tools do you use?** - Claude Code, Cursor, GitHub Copilot, OpenCode, Codex CLI, or all
+1. **Which AI tools do you use?** - Claude Code, Cursor, GitHub Copilot, OpenCode, Codex CLI, or all. There is no "none" choice: an empty answer, or one with no valid number, selects all five.
 2. **What should rails-ai-context write?** - MCP config + context files (default), context files only (CLI mode), or MCP config only
 
 The third answer is MCP-only: the server and the CLI answer in full, and your
 own `CLAUDE.md`, `AGENTS.md` and rules files are left alone. Non-interactively
 that is `--mcp-only`.
 
+Three more prompts appear only when they apply:
+
+- **Remove their generated files?** - on a re-run that drops a tool you picked before. Default: keep them. A yes removes only what the gem generated, never a rule file or a line you wrote.
+- **Install a pre-commit hook that validates Rails references?** - in a git repo that has no pre-commit hook yet. Default: no.
+- **Delete them?** - in a terminal, when rule files left over from before v5.0.0 are found. Default: no.
+
+`--defaults` skips every prompt and takes each default: all five tools, keep the files, MCP config + context files, no hook, keep legacy files. Every step is listed in [What the install generator does](GUIDE.md#what-the-install-generator-does).
+
 That's it. Your AI tool now has live access to your schema, models, routes, controllers, views, and conventions.
 
 > [!TIP]
@@ -50,6 +58,8 @@ rails-ai-context init
 rails-ai-context serve
 ```
 
+`init` asks the same two questions, and the cleanup and legacy-file prompts when they apply. It has no pre-commit hook prompt and no `--defaults` flag, and it does not create `config/initializers/rails_ai_context.rb`.
+
 Works with every Ruby version manager (rbenv, rvm, asdf, mise, chruby, system). [Learn more about standalone mode →](STANDALONE.md)
 
 ## What just happened?
@@ -59,9 +69,10 @@ The install generator created:
 | File | Purpose |
 |:-----|:--------|
 | `.mcp.json` / `.cursor/mcp.json` / `.vscode/mcp.json` / `opencode.json` / `.codex/config.toml` | MCP auto-discovery - your AI tool detects these on project open |
-| `CLAUDE.md` / `.cursor/rules/` / `.cursorrules` / `.github/instructions/` / `AGENTS.md` | Static context rules your AI reads |
+| `CLAUDE.md` + `.claude/rules/` / `.cursor/rules/` + `.cursorrules` / `.github/copilot-instructions.md` + `.github/instructions/` / `AGENTS.md` | Static context rules your AI reads |
+| `.ai-context.json` | The same context as JSON (added to `.gitignore`) |
 | `config/initializers/rails_ai_context.rb` | All configuration options |
-| `.rails-ai-context.yml` | Config for standalone mode |
+| `.rails-ai-context.yml` | Your tool selection, and the config file for standalone mode |
 
 ## Verify it works
 

data/docs/RECIPES.md

@@ -49,15 +49,18 @@
 ```
 ## Table: users
 
+**Models:** User
+**Primary key:** id
+
 | Column | Type | Null | Default |
 |--------|------|------|---------|
-| id | integer | NO | |
-| email | string | NO | [unique] |
-| subscription_status | string | yes | "free" |
-| created_at | datetime | NO | |
+| id | integer | **NO** |  |
+| email | string | **NO** |  |
+| subscription_status | string | yes | free |
+| created_at | datetime | **NO** |  |
 
 ### Indexes
-- index_users_on_email (unique)
+- `index_users_on_email` on (email) (unique)
 ```
 
 </details>
@@ -66,7 +69,7 @@ AI sees `subscription_status` already exists - asks before proceeding instead of
 
 ```
 → rails_get_model_details(model: "User")
-→ rails_migration_advisor(action: "add_column", table: "users", columns: "subscription_tier:string")
+→ rails_migration_advisor(action: "add_column", table: "users", column: "subscription_tier", type: "string")
 ```
 
 **Without ground truth:** AI writes a migration blindly, possibly duplicating a column or missing an index.
@@ -88,7 +91,7 @@ rails_get_schema(table: "posts")
 # → Actual column names, types, constraints
 
 rails_diagnose(error: "ActiveRecord::RecordInvalid", file: "app/controllers/posts_controller.rb")
-# → Classification + context + git blame + log correlation
+# → Classification + context + recent git log + log correlation
 ```
 
 AI sees the full picture: the parent controller's `authenticate_user!` filter, the actual strong params whitelist, and the real column names. No guessing.
@@ -110,23 +113,24 @@ AI sees the full picture: the parent controller's `authenticate_user!` filter, t
 # Feature Analysis: notifications
 
 ## Models (1)
+
 ### Notification
-Table: notifications
-Columns: user_id:bigint, title:string, read_at:datetime
-Associations: belongs_to :user
+**Table:** `notifications`
+**Columns:** user_id:bigint, title:string, read_at:datetime
+**Associations:** belongs_to :user
 
 ## Controllers (1)
-### NotificationsController
-Actions: index, mark_read
-Filters: before_action authenticate_user!
 
-## Jobs (1)
-### NotificationBroadcastJob
-Queue: default | Retries: 3
+### NotificationsController
+- **Actions:** index, mark_read
+- **Filters:** before authenticate_user!
 
 ## Routes (2)
-GET  /notifications     → notifications#index
-POST /notifications/:id → notifications#mark_read
+- `GET` `/notifications` → notifications#index `notifications_path`
+- `POST` `/notifications/:id/mark_read` → notifications#mark_read `mark_read_notification_path(@record)`
+
+## Jobs (1)
+- `app/jobs/notification_broadcast_job.rb` (queue: default, retry_on StandardError, attempts: 3, perform(notification_id))
 ```
 
 </details>
@@ -157,31 +161,37 @@ AI scaffolds the feature matching your app's actual patterns - not generic Rails
 <details open>
 <summary>Example output</summary>
 
-```
-# Trace: publishable?
+````
+# Trace: `publishable?`
 
 ## Definition
-app/models/post.rb:45 in Post
+**app/models/post.rb:45** in `class Post`
+```ruby
   def publishable?
     title.present? && body.present? && approved?
   end
+```
 
-## Called from (4 sites)
-
-**Controllers** (2)
-  app/controllers/posts_controller.rb:12  before_action :ensure_publishable
-  app/controllers/admin/posts_controller.rb:8  if @post.publishable?
+## Calls internally
+- `title`
+- `body`
+- `approved?`
 
-**Views** (1)
-  app/views/posts/show.html.erb:8  <% if @post.publishable? %>
+## Called from (3 sites)
+### app/controllers/admin/posts_controller.rb (Controller)
+  8: render :draft unless @post.publishable?
+### app/controllers/posts_controller.rb (Controller)
+  12: redirect_to @post unless @post.publishable?
+### app/views/posts/show.html.erb (View)
+  8: <% if @post.publishable? %>
 
-**Tests** (1)
-  spec/models/post_spec.rb:92  expect(post.publishable?).to be true
-```
+## Tested by (1 reference)
+- `spec/models/post_spec.rb` (1 reference)
+````
 
 </details>
 
-One call. Definition + source + every caller grouped by type + tests. **Replaces 4-5 sequential file reads.**
+One call. Definition + source + every caller grouped by file and labelled by type + tests. **Replaces 4-5 sequential file reads.**
 
 ---
 
@@ -196,7 +206,7 @@ rails_onboard(detail: "full")
 rails_dependency_graph(format: "mermaid")
 # → Visual model relationship graph
 
-rails_get_gems(detail: "full")
+rails_get_gems()
 # → Every notable gem with version, category, and config location
 ```
 
@@ -226,7 +236,7 @@ AI generates tests that actually run, using your test helper setup, your factory
 **Ask your AI:** "The dashboard view is broken"
 
 ```bash
-rails_get_view(controller: "dashboard", action: "index")
+rails_get_view(path: "dashboard/index.html.erb")
 # → Template source with ivars, Turbo frames, Stimulus controllers, partial locals
 
 rails_get_partial_interface(partial: "dashboard/stats_card")
@@ -243,10 +253,10 @@ rails_get_stimulus(controller: "chart")
 **Ask your AI:** "Review the changes in this branch"
 
 ```bash
-rails_review_changes(ref: "HEAD~3..HEAD")
+rails_review_changes(ref: "HEAD~3")
 # → Per-file context + structural warnings
 
-rails_validate(files: "app/controllers/users_controller.rb,app/models/user.rb", level: "security")
+rails_validate(files: ["app/controllers/users_controller.rb", "app/models/user.rb"], level: "rails")
 # → Syntax + semantic + Brakeman scan
 
 rails_performance_check()
@@ -279,7 +289,7 @@ rails_query(sql: "SELECT * FROM orders JOIN users ON ...", explain: true)
 **Ask your AI:** "What does the Searchable concern do?"
 
 ```bash
-rails_get_concern(concern: "Searchable")
+rails_get_concern(name: "Searchable")
 # → Methods (including class_methods block), source code, which models include it
 
 rails_search_code(pattern: "include Searchable", match_type: "any")
@@ -310,7 +320,7 @@ rails_get_frontend_stack()
 rails_runtime_info(detail: "full")
 # → DB pool stats, table sizes, pending migrations, cache stats, queue depth
 
-rails_read_logs(level: "error", lines: 100)
+rails_read_logs(level: "ERROR", lines: 100)
 # → Recent errors with sensitive data redacted
 
 rails_security_scan()
@@ -329,8 +339,8 @@ rails_get_schema(table: "users")
 rails_get_model_details(model: "User")
 
 # Follow-up: "What context do I have so far?"
-rails_session_context()
-# → Lists all prior tool calls with params and summaries
+rails_session_context(action: "status")
+# → Lists all prior tool calls with params and when each ran
 ```
 
 This prevents redundant queries and helps AI maintain conversation context.

data/docs/SECURITY.md

@@ -49,11 +49,12 @@ flowchart LR
 
 Before any query reaches the database:
 
-- Strips comments: block (`/* */`), line (`--`), MySQL (`#` at line start)
+- Strips comments: block (`/* */`), line (`--`), and on MySQL `#`. A comment marker inside a quoted string or identifier is data and stays. The query that runs is this stripped text, never the raw input, so nothing the checks did not read reaches the database
 - **Blocks write keywords**: INSERT, UPDATE, DELETE, DROP, ALTER, TRUNCATE, CREATE, GRANT, REVOKE, SET, COPY, MERGE, REPLACE
 - **Blocks lock clauses**: FOR UPDATE, FOR SHARE, FOR NO KEY UPDATE
 - **Blocks dangerous SHOW**: GRANTS, PROCESSLIST, BINLOG, SLAVE, MASTER, REPLICAS
-- **Blocks SELECT INTO**: prevents table creation via SELECT
+- **Blocks SELECT INTO**: prevents table creation via SELECT, and `INTO OUTFILE` / `INTO DUMPFILE` writes to disk
+- **Blocks file and network functions**: `pg_read_file`, `pg_read_binary_file`, `pg_ls_dir`, `pg_stat_file`, `lo_import`, `lo_export`, `dblink*`, `LOAD DATA`, `LOAD_FILE`, `load_extension` and their relatives, checked before and after comment stripping
 - **Blocks multi-statements**: multiple semicolons
 - **Blocks injection patterns**: OR 1=1, OR true, OR ''='', UNION SELECT
 - **Allows only**: SELECT, WITH, SHOW, EXPLAIN, DESCRIBE, DESC
@@ -68,7 +69,7 @@ After validation, the query runs inside a transaction:
 | MySQL | `SET TRANSACTION READ ONLY` + `MAX_EXECUTION_TIME` hint |
 | 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).
+On PostgreSQL and MySQL the query executes inside a transaction, then rolls back (even if it could write, it can't). Any other adapter has no database-level guard: the query runs with Layer 1 validation and the row limit only.
 
 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
@@ -87,7 +88,8 @@ lock in WAL mode does not block it.
 
 - Default: 100 rows
 - Configurable: `config.query_row_limit` (hard cap: 1000)
-- Applied as `LIMIT` clause appended to query
+- Applied as a `LIMIT` clause appended to the query. A `LIMIT` or `FETCH FIRST` that ends the query is lowered to the cap, and one inside a subquery is left as written
+- The rows that come back are cut to the cap too, so the answer holds it whatever the database made of the text
 
 ### Layer 4 - Sensitive column rejection
 
@@ -95,7 +97,7 @@ A query that names a sensitive column is **rejected before execution**, not reda
 
 **Default redacted patterns:** `password_digest`, `encrypted_password`, `password_hash`, `reset_password_token`, `confirmation_token`, `unlock_token`, `otp_secret`, `session_data`, `secret_key`, `api_key`, `api_secret`, `access_token`, `refresh_token`, `jti`
 
-Matching is by name, case-insensitive and word-bounded, against both the defaults above and `config.query_redacted_columns`. `SELECT password_digest AS pd FROM users` is blocked outright: post-execution redaction reads the column names the database returns, which the caller controls through aliases and expressions, so it cannot be relied on.
+Those are the defaults of `config.query_redacted_columns`. A fixed built-in list is checked as well, which adds `password_reset_token`, `remember_token`, `secret` and `private_key`. Matching is by name, case-insensitive and word-bounded, against both lists. `SELECT password_digest AS pd FROM users` is blocked outright: post-execution redaction reads the column names the database returns, which the caller controls through aliases and expressions, so it cannot be relied on.
 
 If one of your own columns merely looks sensitive (an `oauth_applications.secret`, say), exempt it by name:
 
@@ -103,6 +105,11 @@ If one of your own columns merely looks sensitive (an `oauth_applications.secret
 config.query_allowed_columns = %w[secret]
 ```
 
+Results are redacted as well: a returned column comes back as `[FILTERED]` when
+its name is in `config.query_redacted_columns`, contains `password`, `secret` or
+`token`, or ends in `key`, `digest` or `hash`. `SHOW`, `DESCRIBE` and `EXPLAIN`
+output is not redacted.
+
 The exemption covers the results too: an allowed name comes back unredacted. A
 column declared with `encrypts` stays `[FILTERED]` either way.
 
@@ -120,13 +127,15 @@ The `rails_search_code` and file-reading tools block access to sensitive files:
 ### Default patterns
 
 ```text
-.env .env.*
+.env .env.* *.env .envrc
 config/master.key
 config/credentials.yml.enc config/credentials/*.yml.enc
-config/database.yml config/secrets.yml
+config/database.yml config/secrets*.yml config/secrets*.yml.enc
+config/application.yml
+config/settings.local.yml config/settings/*.local.yml
 config/cable.yml config/storage.yml
 config/mongoid.yml config/redis.yml
-*.pem *.key *.p12 *.pfx *.jks *.keystore
+*.pem *.key *.p8 *.p12 *.pfx *.jks *.keystore
 **/id_rsa **/id_ed25519 **/id_ecdsa **/id_dsa
 .ssh/* .aws/credentials .aws/config .netrc .pgpass .my.cnf
 ```
@@ -164,7 +173,8 @@ All file-reading operations validate paths against `Rails.root`:
 
 ```ruby
 real_path = File.realpath(requested_path)
-raise unless real_path.start_with?(Rails.root.to_s)
+root = File.realpath(Rails.root.to_s)
+raise unless real_path == root || real_path.start_with?(root + File::SEPARATOR)
 ```
 
 The VFS (`rails-ai-context://views/{path}`) applies the same protection for view template reads.
@@ -216,7 +226,7 @@ Search tools use array-based command execution (never shell strings):
 
 ```ruby
 # Safe: array form
-Open3.capture2("rg", "--no-heading", pattern, "--", directory)
+Open3.capture3("rg", "--no-heading", "--", pattern, directory)
 
 # Pattern injection prevented by -- separator
 ```
@@ -227,7 +237,7 @@ File type parameters accept only alphanumeric characters.
 
 ## Regex injection prevention
 
-On Ruby 3.2 and newer, user-supplied regex patterns have a 1-second timeout:
+On Ruby 3.2 and newer, user-supplied regex patterns have a 1-second timeout (2 seconds in the Ruby search fallback):
 
 ```ruby
 Regexp.new(pattern, timeout: 1)
@@ -319,7 +329,7 @@ The McpController uses thread-safe transport initialization with mutex synchroni
 ## Credential handling
 
 - `rails_get_env` returns credential **keys**, never values
-- Environment variable values are not exposed
+- The process's environment variable values are never read. A default written in code, and a placeholder from `.env.example`, `.env.sample` or `.env.template`, is shown after redaction
 - `config/credentials/*.yml.enc` is in the sensitive patterns list
 
 ---
@@ -328,7 +338,7 @@ The McpController uses thread-safe transport initialization with mutex synchroni
 
 Email crisjosephnahine@gmail.com. Response within 48 hours.
 
-Supported versions: 4.0.x and later (4.2.1+ includes security hardening). See the repo root `SECURITY.md` for the full policy.
+Supported versions: only the latest 5.x release gets security fixes. See the repo root `SECURITY.md` for the full policy.
 
 ---
 

data/docs/SETUP.md

@@ -31,18 +31,12 @@ flowchart TD
     A[Start] --> B{Can you modify\nthe Gemfile?}
     B -->|Yes| C[In-Gemfile]
     B -->|No| D[Standalone]
-    C --> E{Need MCP\nserver?}
-    D --> E
-    E -->|"Yes - best experience"| F[MCP Mode]
-    E -->|"No - terminal only"| G[CLI Mode]
-    F --> H{Which AI tools?}
-    G --> H
-    H --> I["Claude Code"]
-    H --> J["Cursor"]
-    H --> K["GitHub Copilot"]
-    H --> L["OpenCode"]
-    H --> M["Codex CLI"]
-    H --> N["All of them"]
+    C --> H{Which AI tools?}
+    D --> H
+    H -->|"Claude Code, Cursor, GitHub Copilot,\nOpenCode, Codex CLI, or all"| E{What should\nit write?}
+    E -->|"1 - default"| F[MCP config +\ncontext files]
+    E -->|"2 - no MCP server"| G[Context files only\nCLI mode]
+    E -->|"3 - keep your own files"| O[MCP config only]
 
     style C fill:#27ae60,stroke:#1e8449,color:#fff
     style D fill:#3498db,stroke:#2980b9,color:#fff
@@ -61,10 +55,11 @@ rails generate rails_ai_context:install  # Select "Claude Code"
 This creates:
 - `.mcp.json` - MCP auto-discovery config (auto-detected on project open)
 - `CLAUDE.md` - Root context file
-- `.claude/rules/rails-schema.md` - Schema rules (loaded when editing `db/` files)
+- `.claude/rules/rails-schema.md` - Schema rules (loaded when editing the schema dump or `db/migrate/` files)
 - `.claude/rules/rails-models.md` - Model rules (loaded when editing `app/models/`)
 - `.claude/rules/rails-context.md` - General context rules (always loaded)
 - `.claude/rules/rails-mcp-tools.md` - Tool reference (always loaded)
+- `.claude/rules/rails-components.md` - Component rules (loaded when editing `app/components/` or `app/views/components/`, written only when the app has view components)
 
 Keeping your own `CLAUDE.md`? Add `--mcp-only` and only `.mcp.json` is
 written; every context file is left alone. See
@@ -79,12 +74,14 @@ If you need to configure manually, create `.mcp.json`:
   "mcpServers": {
     "rails-ai-context": {
       "command": "bundle",
-      "args": ["exec", "rails", "ai:serve"]
+      "args": ["exec", "rails-ai-context", "serve"]
     }
   }
 }
 ```
 
+This is what the generator writes for an in-Gemfile install. A standalone install has no `bundle exec`: the command is `rails-ai-context` and the args are `["serve"]`. The same goes for the other tools below.
+
 ### Split rules with `paths:` frontmatter
 
 Claude Code loads `.claude/rules/` files conditionally based on YAML frontmatter:
@@ -92,12 +89,11 @@ Claude Code loads `.claude/rules/` files conditionally based on YAML frontmatter
 ```yaml
 ---
 paths:
-  - db/**
-  - app/models/**
+  - "app/models/**/*.rb"
 ---
 ```
 
-Schema and model rules use this to only load when relevant files are being edited.
+Schema, model and component rules use this to only load when relevant files are being edited.
 
 ---
 
@@ -115,7 +111,7 @@ This creates:
 - `.cursor/rules/rails-models.mdc` - Model rules (Type 2: glob `app/models/**/*.rb`)
 - `.cursor/rules/rails-controllers.mdc` - Controller rules (Type 2: glob `app/controllers/**/*.rb`)
 - `.cursor/rules/rails-mcp-tools.mdc` - Tool reference (Type 3: agent-requested)
-- `.cursorrules` - **legacy single-file fallback** at the project root. Cursor's chat agent doesn't always detect `.cursor/rules/*.mdc` (reported in v5.9.0 release QA); this file is parsed verbatim by every Cursor build and contains the same compact project context as `CLAUDE.md`.
+- `.cursorrules` - **legacy single-file fallback** at the project root. Cursor's chat agent doesn't always detect `.cursor/rules/*.mdc` (reported in v5.9.0 release QA); this file is parsed verbatim by every Cursor build and contains the same compact project context `CLAUDE.md` gets in the default compact mode. It stays compact when `context_mode` is `:full`.
 
 ### Manual MCP config
 
@@ -126,7 +122,7 @@ Create `.cursor/mcp.json`:
   "mcpServers": {
     "rails-ai-context": {
       "command": "bundle",
-      "args": ["exec", "rails", "ai:serve"]
+      "args": ["exec", "rails-ai-context", "serve"]
     }
   }
 }
@@ -138,7 +134,7 @@ The MCP tools rule uses `alwaysApply: false` with a descriptive `description:` f
 
 ```markdown
 ---
-description: 45 MCP tools for Rails introspection - schema, models, routes, controllers, views
+description: "Rails MCP tools reference - 45 tools for schema, models, routes, controllers, search, testing, and more"
 alwaysApply: false
 ---
 ```
@@ -170,7 +166,7 @@ Create `.vscode/mcp.json` (note: `servers` key, not `mcpServers`):
   "servers": {
     "rails-ai-context": {
       "command": "bundle",
-      "args": ["exec", "rails", "ai:serve"]
+      "args": ["exec", "rails-ai-context", "serve"]
     }
   }
 }
@@ -178,12 +174,13 @@ Create `.vscode/mcp.json` (note: `servers` key, not `mcpServers`):
 
 ### Frontmatter for agent discovery
 
-Copilot instruction files include `name:` and `description:` YAML frontmatter:
+Copilot instruction files include `applyTo:`, `name:` and `description:` YAML frontmatter:
 
 ```markdown
 ---
-name: Rails Models
-description: Model associations, validations, and schema for this Rails app
+applyTo: "app/models/**/*.rb"
+name: "Rails Models Reference"
+description: "ActiveRecord models - associations, validations, scopes, enums"
 ---
 ```
 
@@ -212,7 +209,7 @@ Create `opencode.json`:
   "mcp": {
     "rails-ai-context": {
       "type": "local",
-      "command": ["bundle", "exec", "rails", "ai:serve"]
+      "command": ["bundle", "exec", "rails-ai-context", "serve"]
     }
   }
 }
@@ -241,7 +238,7 @@ Create `.codex/config.toml`:
 ```toml
 [mcp_servers.rails-ai-context]
 command = "bundle"
-args = ["exec", "rails", "ai:serve"]
+args = ["exec", "rails-ai-context", "serve"]
 
 [mcp_servers.rails-ai-context.env]
 PATH = "/Users/you/.rbenv/shims:/usr/local/bin:/usr/bin"