rails-ai-bridge 5.1.0 → 5.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 74d2175a281a2d2b0e3efb53e3970ffbf8658724241a9fcbf4a241e8a22375c8
-  data.tar.gz: e674ed5c5bf81c08d1b0c918c414ddafb518b48ac3f4843f6d25c8a173fdecfc
+  metadata.gz: 5b63548b24b25e5ccd6faa5fa898e999bbd750283b36f5e2cd4d27b83d073021
+  data.tar.gz: 49088ba707aa54af31f733a61a2d256137a58fd24cc26a4d3a30161bfdc0a10b
 SHA512:
-  metadata.gz: 9e5cc4ff68c3d003b228231504169c4dfab1b0baf2b8bbf4d057a97fd3a3d14ea8e689bec29056bb57a5c140f43017f3a07737c08469ecfe7b17d34d6c002641
-  data.tar.gz: d0b72a96954862bf6bde9b9e64945481ac4352a74f0403edebd3d0b1600445152f0d6b061fa177c9912276b571883da404347ad25d0f20e114b1a8d6bdf268ed
+  metadata.gz: 9054c6e37be79a49ed71137f308e6c63a9f0be5bc8c0f48f982ad99ddec54dcae518cc3f563b2052164fe7d6972060fceba9ced08e3befdedf473cb1857f3d30
+  data.tar.gz: 832b6f1ee08194ac6cc7bce3c36cb616da7ce5d8bf20e51bffb1a56d36957f2ad6cdd00f352ded5d7c87b8b79318f70d406ee8e6b74a08d0d905889908e39a83

data/.reek.yml

@@ -99,8 +99,8 @@ detectors:
     - RailsAiBridge::FreshnessHeader#extract_metadata_for
     - RailsAiBridge::Introspectors::MiddlewareIntrospector#categorize_middleware
     - RailsAiBridge::Mcp::HttpRateLimiter#initialize
-    - RailsAiBridge::ModelSemanticClassifier#classify_with_payload
-    - RailsAiBridge::ModelSemanticClassifier#classify_without_payload
+    - RailsAiBridge::Introspectors::ModelSemanticClassifier#classify_with_payload
+    - RailsAiBridge::Introspectors::ModelSemanticClassifier#classify_without_payload
     - RailsAiBridge::Registry::ContextAggregator#aggregate_status
     - RailsAiBridge::Registry::ContextProviderClient#find_tool
     - RailsAiBridge::Registry::PackResolver#initialize
@@ -197,7 +197,7 @@ detectors:
     - RailsAiBridge::Mcp::CacheRateLimiter#increment
     - RailsAiBridge::Mcp::HttpRateLimiter#allow?
     - RailsAiBridge::Mcp::HttpStructuredLog#target_logger
-    - RailsAiBridge::ModelSemanticClassifier#call
+    - RailsAiBridge::Introspectors::ModelSemanticClassifier#call
     - RailsAiBridge::Registry::ContextAggregator#fetch_all
     - RailsAiBridge::Registry::ContextAggregator#fetch_provider
     - RailsAiBridge::Registry::ContextAggregator#fetch_tool
@@ -390,7 +390,7 @@ detectors:
     - RailsAiBridge::Introspectors::TurboIntrospector#extract_model_broadcasts
     - RailsAiBridge::Introspectors::ViewIntrospector#detect_template_engines
     - RailsAiBridge::Mcp::CacheRateLimiter#fallback_increment
-    - RailsAiBridge::PathResolver#path_inside_real_root?
+    - RailsAiBridge::Introspectors::PathResolver#path_inside_real_root?
     - RailsAiBridge::Registry::Lockfile#to_json
     - RailsAiBridge::Registry::PackResolver#gather_active_packs
     - RailsAiBridge::Registry::PackResolver#trace_dependency_cycle
@@ -476,7 +476,7 @@ detectors:
     exclude:
     - RailsAiBridge::Generators::InstallGenerator
     - RailsAiBridge::Fingerprinter::CachedSnapshot
-    - RailsAiBridge::PathResolver
+    - RailsAiBridge::Introspectors::PathResolver
     - RailsAiBridge::RubydexAdapter
     - RailsAiBridge::Serializers::ContextFileSerializer::ManagedRegionLayout
     - RailsAiBridge::Serializers::Providers::ClaudeSerializer
@@ -592,8 +592,8 @@ detectors:
     - RailsAiBridge::Introspectors::SeedsIntrospector#detect_seeded_models
     - RailsAiBridge::Introspectors::TestIntrospector#detect_test_helpers
     - RailsAiBridge::Introspectors::TurboIntrospector#extract_turbo_frames
-    - RailsAiBridge::ModelSemanticClassifier#self.through_join_model_names
-    - RailsAiBridge::PathResolver#glob_for
+    - RailsAiBridge::Introspectors::ModelSemanticClassifier#self.through_join_model_names
+    - RailsAiBridge::Introspectors::PathResolver#glob_for
     - RailsAiBridge::Registry::Resolver#build_deprecated_index
     - RailsAiBridge::Registry::Resolver#build_summary_map
     - RailsAiBridge::Registry::Resolver#validate_dependencies
@@ -644,7 +644,7 @@ detectors:
     - RailsAiBridge::Mcp::Auth::Strategies::Jwt#initialize
     - RailsAiBridge::Mcp::Authenticator#call
     - RailsAiBridge::Mcp::HttpStructuredLog#emit
-    - RailsAiBridge::PathResolver#max_files_per_path
+    - RailsAiBridge::Introspectors::PathResolver#max_files_per_path
     - RailsAiBridge::Registry::Lockfile#load
     - RailsAiBridge::Registry::RakePresenter#initialize
     - RailsAiBridge::Registry::SkillSourceResolver#pull_stale?
@@ -729,7 +729,7 @@ detectors:
     - RailsAiBridge::Introspectors::ModelIntrospector::SourceMacroExtractor
     - RailsAiBridge::Introspectors::ModelIntrospector
     - RailsAiBridge::Introspectors::Schema::StaticStructureSqlParser
-    - RailsAiBridge::PathResolver
+    - RailsAiBridge::Introspectors::PathResolver
     - RailsAiBridge::RubydexAdapter::IncrementalIndexer
     - RailsAiBridge::RubydexAdapter
     - RailsAiBridge::Serializers::Providers::BaseProviderSerializer
@@ -869,10 +869,10 @@ detectors:
     - RailsAiBridge::Mcp::Authenticator#resolve_strategy
     - RailsAiBridge::Mcp::HttpRateLimiter#allow?
     - RailsAiBridge::Mcp::HttpStructuredLog#emit
-    - RailsAiBridge::ModelSemanticClassifier#call
-    - RailsAiBridge::ModelSemanticClassifier#metadata_column_names
-    - RailsAiBridge::ModelSemanticClassifier#self.through_join_model_names
-    - RailsAiBridge::PathResolver#glob_for
+    - RailsAiBridge::Introspectors::ModelSemanticClassifier#call
+    - RailsAiBridge::Introspectors::ModelSemanticClassifier#metadata_column_names
+    - RailsAiBridge::Introspectors::ModelSemanticClassifier#self.through_join_model_names
+    - RailsAiBridge::Introspectors::PathResolver#glob_for
     - RailsAiBridge::Registry::FrontmatterParser#self.extract_frontmatter_lines
     - RailsAiBridge::Registry::Lockfile#load
     - RailsAiBridge::Registry::PackResolver#expand_transitive_dependencies
@@ -963,6 +963,7 @@ detectors:
     - RailsAiBridge::Serializers::Providers::CursorRulesSerializer#render_models_rule
     - RailsAiBridge::Serializers::Providers::DevinRulesSerializer#call
     - RailsAiBridge::Serializers::Providers::DevinSerializer#render
+    - RailsAiBridge::Serializers::RuleFileWriter#call
     - RailsAiBridge::Serializers::SharedAssistantGuidance#claude_full_footer_lines
     - RailsAiBridge::Serializers::SharedAssistantGuidance#compact_engineering_rules_footer_lines
     - RailsAiBridge::Serializers::SharedAssistantGuidance#cursor_engineering_mdc_body_lines
@@ -1033,7 +1034,7 @@ detectors:
     - RailsAiBridge::Tools::ListRegistry::RegistryCatalogFormatter#format_catalog
     - RailsAiBridge::Tools::ListRegistry::RegistryCatalogFormatter#format_packs
     - RailsAiBridge::Tools::ModelDetails::FullFormatter#call
-    - RailsAiBridge::Tools::ModelDetails::NonArModelsAppendix#append_markdown
+    - RailsAiBridge::Serializers::ModelDetails::NonArModelsAppendix#append_markdown
     - RailsAiBridge::Tools::ModelDetails::SingleModelFormatter#append_source_macros
     - RailsAiBridge::Tools::ModelDetails::SingleModelFormatter#call
     - RailsAiBridge::Tools::ModelDetails::StandardFormatter#call
@@ -1094,8 +1095,8 @@ detectors:
     - RailsAiBridge::Mcp::HttpRateLimiter#allow?
     - RailsAiBridge::Mcp::HttpRateLimiter#initialize
     - RailsAiBridge::Mcp::HttpStructuredLog#emit
-    - RailsAiBridge::ModelSemanticClassifier#call
-    - RailsAiBridge::ModelSemanticClassifier#metadata_column_names
+    - RailsAiBridge::Introspectors::ModelSemanticClassifier#call
+    - RailsAiBridge::Introspectors::ModelSemanticClassifier#metadata_column_names
     - RailsAiBridge::Registry::PackResolver#gather_active_packs
     - RailsAiBridge::Registry::PackResolver#warn_missing_dependencies
     - RailsAiBridge::RubydexAdapter#codebase_stats
@@ -1244,9 +1245,9 @@ detectors:
     - RailsAiBridge::Introspectors::StimulusIntrospector#extract_values
     - RailsAiBridge::Mcp::Auth::BaseStrategy#extract_bearer
     - RailsAiBridge::Mcp::Auth::Strategies::BearerToken#secure_compare
-    - RailsAiBridge::ModelSemanticClassifier#metadata_column_names
-    - RailsAiBridge::ModelSemanticClassifier#safe_column_names
-    - RailsAiBridge::ModelSemanticClassifier#tier
+    - RailsAiBridge::Introspectors::ModelSemanticClassifier#metadata_column_names
+    - RailsAiBridge::Introspectors::ModelSemanticClassifier#safe_column_names
+    - RailsAiBridge::Introspectors::ModelSemanticClassifier#tier
     - RailsAiBridge::Registry::PackResolver#auto_load_dependencies?
     - RailsAiBridge::Registry::PackResolver#compute_priority
     - RailsAiBridge::Registry::PackResolver#default_lockfile

data/.rubocop.yml

@@ -11,6 +11,13 @@ AllCops:
     - "spec/internal/**/*"
     - "gemfiles/**/*"
     - ".mutant.yml"
+    # Generated/rails-boilerplate demo files (rails new, db/schema.rb, bin/,
+    # config boot files) — rails generators emit double-quoted strings and
+    # long blocks by design; keeping them excluded means `rubocop -A` never
+    # rewrites files the demo intentionally shows as generated output.
+    - "examples/demo_app/bin/**/*"
+    - "examples/demo_app/config/**/*"
+    - "examples/demo_app/db/**/*"
 Naming/FileName:
   Exclude:
     - "lib/rails-ai-bridge.rb"

data/AGENTS.md

@@ -8,8 +8,8 @@ committed context files. It does not write to the host database.
 - `lib/rails_ai_bridge.rb` — Main entry point, public API (Zeitwerk autoloaded)
 - `lib/rails_ai_bridge/configuration.rb` — User-facing config with presets (:standard, :full)
 - `lib/rails_ai_bridge/introspector.rb` — Orchestrates sub-introspectors
-- `lib/rails_ai_bridge/introspectors/` — Built-in introspector classes; `:standard` preset runs **9**, `:full` runs **27** (see `Configuration::PRESETS`). Registry: `Introspector::BUILTIN_INTROSPECTORS` (includes opt-in symbols such as `database_stats`, `non_ar_models` not listed in those presets).
-- `lib/rails_ai_bridge/tools/` — 20 built-in MCP tools using the official mcp SDK (hosts can add more via `additional_tools`)
+- `lib/rails_ai_bridge/introspectors/` — Built-in introspector classes; `:standard` preset runs **9**, `:full` runs **27** (see `Configuration::PRESETS`). Registry: `Introspector::BUILTIN_INTROSPECTORS` (`:full` already includes `non_ar_models`; opt-in-only symbols not in any preset: `database_stats`, `semantic`).
+- `lib/rails_ai_bridge/tools/` — 22 built-in MCP tools using the official mcp SDK (hosts can add more via `additional_tools`)
 - `lib/rails_ai_bridge/serializers/` — Output formatters (claude, claude_rules, codex, cursor_rules, devin, devin_rules, copilot, copilot_instructions, gemini, rules, markdown, JSON)
 - `lib/rails_ai_bridge/resources.rb` — MCP resources (static data AI clients read directly)
 - `lib/rails_ai_bridge/server.rb` — MCP server configuration (stdio + HTTP transports)
@@ -32,7 +32,7 @@ committed context files. It does not write to the host database.
 6. **Diff-aware** — context regeneration skips unchanged files
 7. **Per-assistant serializers** — each AI tool gets tailored output format
 8. **Zeitwerk autoloading** — files loaded on-demand, not all upfront
-9. **Introspector presets** — `:standard` (9 core) default, `:full` (27 introspectors; optional extras such as `database_stats`, `non_ar_models`) for power users
+9. **Introspector presets** — `:standard` (9 core) default, `:full` (27 introspectors, includes `non_ar_models`) with opt-in extras such as `database_stats` and `semantic` for power users
 10. **MCP auto-discovery** — `.mcp.json` generated by install generator
 11. **Outbound context providers (v5)** — `rails_get_provider_context` fetches from declared external MCP services. Disabled by default, exact host allowlist, read-only tool enforcement, `ToolResultCache::NON_CACHEABLE` exclusion. Separate from local `rails_get_context`.
 12. **Compact by default** — context files ≤150 lines, MCP tools use `detail` parameter (summary/standard/full)
@@ -50,7 +50,7 @@ Uses combustion gem for testing Rails engine behavior in isolation.
 ## Conventions
 
 - Ruby 3.2+ features OK (pattern matching, etc.)
-- Follow rubocop-rails-omakase style
+- Follow RuboCop with the project's custom limits (see `.rubocop.yml` — plugins performance/rails/rspec; method length, ABC size and class length limits are deliberately more permissive than the omakase defaults)
 - Every introspector returns a Hash, never raises (wraps errors in `{ error: msg }`)
 - MCP tools return `MCP::Tool::Response` objects per SDK convention
 - All tools prefixed with `rails_` per MCP naming best practices

data/Archspec.rb

@@ -2,10 +2,10 @@
 
 # ArchSpec architecture specification for rails-ai-bridge.
 #
-# Defines eight components and the dependency directions the gem is expected to
-# follow. Lower layers (config, introspectors, registry, rubydex, serializers)
-# must not reach up into transport or tooling layers. Cross-component cycles are
-# forbidden.
+# Defines ten components and the dependency directions the gem is expected to
+# follow. Lower layers (core, config, introspectors, registry, rubydex,
+# serializers) must not reach up into transport or tooling layers.
+# Cross-component cycles are forbidden.
 #
 # Run locally with:
 #
@@ -15,6 +15,17 @@
 
 source 'lib/rails_ai_bridge/**/*.rb'
 
+# Core primitives — dependency-free value types and pure helpers (Service,
+# Service::Result, ExclusionHelper, DatabaseSize) that every layer may use.
+# Extracted per the #250 diagnosis "durable alternative".
+component :core, in: %w[
+  lib/rails_ai_bridge/service.rb
+  lib/rails_ai_bridge/service/**/*.rb
+  lib/rails_ai_bridge/exclusion_helper.rb
+  lib/rails_ai_bridge/database_size.rb
+  lib/rails_ai_bridge/service_errors.rb
+]
+
 # Configuration layer — user-facing settings and presets.
 # Must stay free of upper-layer dependencies so it can be loaded in isolation.
 component :config, in: %w[
@@ -31,27 +42,15 @@ component :introspectors, in: %w[
 ]
 
 # Runtime context — supporting infrastructure shared by tools and serializers
-# (context providers, fingerprinting, doctor checks, watchers, services, etc.).
+# (context providers, fingerprinting, watcher, tasks, errors).
 component :runtime_context, in: %w[
   lib/rails_ai_bridge/assistant_formats_preference.rb
   lib/rails_ai_bridge/cache_warmer.rb
   lib/rails_ai_bridge/context_provider.rb
-  lib/rails_ai_bridge/database_size.rb
-  lib/rails_ai_bridge/doctor.rb
-  lib/rails_ai_bridge/doctor/**/*.rb
-  lib/rails_ai_bridge/engine.rb
-  lib/rails_ai_bridge/exclusion_helper.rb
   lib/rails_ai_bridge/fingerprinter.rb
   lib/rails_ai_bridge/fingerprinter/**/*.rb
   lib/rails_ai_bridge/freshness_header.rb
   lib/rails_ai_bridge/instrumentation.rb
-  lib/rails_ai_bridge/model_semantic_classifier.rb
-  lib/rails_ai_bridge/path_resolver.rb
-  lib/rails_ai_bridge/resources.rb
-  lib/rails_ai_bridge/service.rb
-  lib/rails_ai_bridge/service/**/*.rb
-  lib/rails_ai_bridge/service_errors.rb
-  lib/rails_ai_bridge/services/**/*.rb
   lib/rails_ai_bridge/tasks/**/*.rb
   lib/rails_ai_bridge/tool_result_cache.rb
   lib/rails_ai_bridge/view_file_analyzer.rb
@@ -59,7 +58,20 @@ component :runtime_context, in: %w[
   lib/rails_ai_bridge/watcher/**/*.rb
 ]
 
-# MCP tools — the 19 built-in tools exposed over the MCP protocol.
+# Host integration — Rails engine wiring, diagnostics, MCP resources that
+# AI clients read directly, plus service orchestrators that sit above the
+# formatting and transport layers. Entry-point glue: it may use every other
+# component (engine wires middleware, doctor checkers reach downward, service
+# orchestrators call serializers); nothing may depend on it. The gem entry
+# point (lib/rails_ai_bridge.rb) sits outside all components.
+component :host_integration, in: %w[
+  lib/rails_ai_bridge/engine.rb
+  lib/rails_ai_bridge/doctor.rb
+  lib/rails_ai_bridge/doctor/**/*.rb
+  lib/rails_ai_bridge/services/**/*.rb
+]
+
+# MCP tools — the 20 built-in tools exposed over the MCP protocol.
 component :tools, in: 'lib/rails_ai_bridge/tools/**/*.rb'
 
 # Output formatters — serialize introspection payloads to per-assistant files.
@@ -73,12 +85,15 @@ component :registry, in: %w[
   lib/rails_ai_bridge/registry/**/*.rb
 ]
 
-# MCP transport — the server, Rack middleware, HTTP app, and auth/rate-limiting.
+# MCP transport — the server, Rack middleware, HTTP app, auth/rate-limiting, and
+# the MCP resources registry (resources are part of the MCP protocol surface;
+# Server wires Resources at construction).
 component :mcp_transport, in: %w[
   lib/rails_ai_bridge/server.rb
   lib/rails_ai_bridge/middleware.rb
   lib/rails_ai_bridge/http_transport_app.rb
   lib/rails_ai_bridge/mcp/**/*.rb
+  lib/rails_ai_bridge/resources.rb
 ]
 
 # Rubydex integration — optional semantic code analysis adapter.
@@ -90,22 +105,33 @@ component :rubydex, in: %w[
 
 # --- Dependency direction rules ---
 
-# Config is the lowest layer; it must not reach up into any upper layer.
-config.cannot_use :tools, :serializers, :mcp_transport, :introspectors
+# Core is the bottom of the stack; every layer may use it, it uses nothing.
+core.cannot_use :config, :introspectors, :runtime_context, :tools, :serializers,
+                :registry, :mcp_transport, :rubydex, :host_integration
+
+# Config sits directly above core; it must not reach up into any upper layer.
+config.cannot_use :runtime_context, :tools, :serializers, :mcp_transport, :introspectors,
+                  :host_integration
+
+# Runtime context, tools, and transport sit below host integration wiring;
+# they must not reach up into it.
+runtime_context.cannot_use :host_integration
+tools.cannot_use :host_integration
+mcp_transport.cannot_use :host_integration
 
 # Registry and rubydex are leaf adapters; they must not depend on the
 # tooling, formatting, or transport layers.
-registry.cannot_use :tools, :serializers, :mcp_transport
-rubydex.cannot_use :tools, :serializers, :mcp_transport
+registry.cannot_use :tools, :serializers, :mcp_transport, :host_integration
+rubydex.cannot_use :tools, :serializers, :mcp_transport, :host_integration
 
 # Introspectors produce plain data and must not depend on tools, formatters,
 # or transport.
-introspectors.cannot_use :tools, :serializers, :mcp_transport
+introspectors.cannot_use :tools, :serializers, :mcp_transport, :host_integration
 
 # Serializers format data handed to them; they must not invoke introspection
 # or reach into the transport layer.
-serializers.cannot_use :introspectors, :mcp_transport
+serializers.cannot_use :introspectors, :mcp_transport, :host_integration
 
 # Cross-component cycles are forbidden across all defined components.
-no_cycles among: %i[config introspectors runtime_context tools serializers
-                    registry mcp_transport rubydex]
+no_cycles among: %i[core config introspectors runtime_context tools serializers
+                    registry mcp_transport rubydex host_integration]

data/CHANGELOG.md

@@ -5,7 +5,150 @@ 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).
 
-## [Unreleased]
+## [5.2.1] - 2026-09-23
+
+### Changed
+
+- Updated the GitHub Pages documentation workflow to `actions/upload-pages-artifact@v5`
+  and `actions/deploy-pages@v5` (Dependabot PRs #289 and #290).
+- Updated mutation testing to `mutant-rspec` 0.17.0 and refreshed its lockfile
+  to current compatible releases, including `mcp` 1.6.0. Refreshed the demo
+  app lockfile as well; runtime dependency requirements are unchanged.
+
+## [5.2.0] - 2026-09-14
+
+### Added
+
+- `rails ai:doctor` warns when HTTP MCP is auto-mounted (`config.auto_mount`)
+  but `config.mcp.http_log_json` is still false, so 401/403/429/handled
+  outcomes from `HttpTransportApp` would not emit structured JSON lines.
+- **Anti-hallucination rules in every generated context file (#252/#253/#254).** All
+  generated outputs now carry a shared verify-before-write block (heading
+  `## Anti-hallucination rules`, rendered by the single
+  `RailsAiBridge::Serializers::AntiHallucinationRules` collaborator and controlled by
+  `config.output.anti_hallucination_rules`, default `true`): the 7 main context files
+  (`CLAUDE.md`, `AGENTS.md`, `.cursorrules`, `.devinrules`, `.github/copilot-instructions.md`,
+  `GEMINI.md`, and `.ai-context.json`, which gains an `anti_hallucination_rules` array
+  key) plus the 5 split-rules serializers (`.claude/rules/`, `.cursor/rules/`,
+  `.devin/rules/`, `.codex/`, `.github/instructions/`). The block sits near the top —
+  after the freshness header / document intro — so compact-mode trimming and Devin's
+  character cap cannot drop it, and it is always inside the managed region when
+  `config.output.managed_region` is enabled.
+- **`rails_query` MCP tool** — runs a single read-only SELECT statement on the app's established ActiveRecord connection. SELECT-only allowlist (CTEs rejected in v1), single-statement enforcement, hard 100-row cap, 5-second statement timeout, and credential-like column redaction via `MessageSanitizer`. Errors follow the `{ error }` contract.
+- **`rails_read_logs` MCP tool** — returns a redacted tail of a log file under `Rails.root/log`. Traversal-safe path allowlist (expanded-path prefix check), 400-line and 2000-byte-per-line caps, `summary`/`standard`/`full` detail levels, and `MessageSanitizer` redaction on every line.
+- Built-in MCP tools: 20 → 22. Both data-access tools are documented in `docs/mcp-security.md`.
+- MCP Registry submission readiness: `server.json` passes
+  `mcp-publisher validate` (verification steps and captured output in
+  `docs/mcp-registry-submission.md`), plus that guide's exact maintainer
+  publish steps (fixes #261).
+- Hosted YARD API documentation: a `docs` workflow publishes generated
+  YARD docs to GitHub Pages on every `v*` tag push (same checkout/setup-ruby
+  pinning style as the existing workflows, reuses the `docs:yard` coverage
+  gate); README gains an "API Documentation" link (fixes #262).
+- Positioning page `docs/COMPARISON.md` comparing rails-ai-bridge with
+  rails-ai-context, rails-mcp-server, woods, and rails-hyperdrive
+  (feature table, download counts, when-to-choose-which), plus a short
+  "How it compares" section in the README (fixes #263).
+- Runnable example app under `examples/demo_app` — a minimal Rails 8 app
+  (3 models, 3 controllers, 3 tables) that boots without a database and
+  demonstrates install, context generation for all 7 assistant targets, and
+  MCP tool calls against the static schema parser. `docs/EXAMPLES.md` walks
+  through it with real captured output (fixes #260).
+
+### Changed
+
+- **`rails_query` and `rails_read_logs` are now opt-in and disabled by default**
+  via `config.enable_data_tools` (default `false`). Both tools read live
+  application data — `rails_query` runs on the app's database connection and can
+  read tables excluded from MCP introspection, and `rails_read_logs` returns raw
+  log contents — so an upgrade no longer registers them silently. To keep using
+  them after upgrading, set `config.enable_data_tools = true` in the
+  `rails_ai_bridge` initializer. See `docs/mcp-security.md` for the residual
+  risks (best-effort keyword guard on non-PostgreSQL adapters, best-effort
+  redaction that column aliases can bypass).
+- `rails_query` redaction: values under credential-like columns (including
+  `password_digest`, `encrypted_password`, `secret_access_key`) are now replaced
+  with `[redacted]` unconditionally instead of only when the value itself looks
+  secret-like. Non-credential author-metadata columns (`author`, `author_id`)
+  keep their values; `authorization`-style columns are redacted.
+- `rails_query` keyword guard now also rejects MySQL `LOCK IN SHARE MODE`
+  (alongside the existing `FOR UPDATE`/`FOR SHARE` and `SELECT ... INTO`
+  rejections). On PostgreSQL, execution runs inside `SET TRANSACTION READ ONLY`
+  with `SET LOCAL statement_timeout`; on other adapters the Ruby
+  `Timeout.timeout` fallback remains a documented residual risk.
+- `rails_read_logs` streams the log file in a single bounded pass instead of
+  materializing the whole file into memory (tail buffer stays capped at
+  `MAX_LINES`), scrubs invalid UTF-8 at the per-line byte cap (replacement
+  characters instead of `invalid byte sequence in UTF-8` errors), and returns
+  sanitized error responses without writing to the application log. The
+  internal-only `ReadLogs.respond`, `error_response`, and `execution_failure`
+  helpers are private class methods.
+- `rails_query` now requires the statement to start with `SELECT` (leading
+  whitespace only). `EXPLAIN`, `SHOW`, `VALUES`, comment-prefixed SQL, and
+  other non-SELECT verbs are rejected. On PostgreSQL the tool uses
+  `SET LOCAL statement_timeout` plus `SET TRANSACTION READ ONLY` instead of
+  Ruby `Timeout.timeout`. Other adapters keep the Ruby timeout.
+- Compact Claude and Gemini output previously placed the anti-hallucination block in the
+  footer under the heading `## Anti-hallucination`; it now uses the consistent named
+  section (`## Anti-hallucination rules`) at the top of the file. The rule lines are
+  unchanged.
+- **Architecture: broke the 6-component dependency cycle (#250).** Extracted a
+  dependency-free `:core` component (`Service`, `Service::Result`,
+  `ServiceErrors`, `ExclusionHelper`, `DatabaseSize`); introduced a
+  `host_integration` component for `engine.rb`, `doctor/**`, and the service
+  orchestrators (`services/**`); grouped `resources.rb` under `mcp_transport`
+  (resources are part of the MCP protocol surface that `Server` wires at
+  construction). Moved `NonArModelsAppendix` to
+  `RailsAiBridge::Serializers::ModelDetails::NonArModelsAppendix`,
+  `PathResolver` and `ModelSemanticClassifier` to
+  `RailsAiBridge::Introspectors::` (`PathResolver` is now
+  `RailsAiBridge::Introspectors::PathResolver`), and `ModelSemanticClassifier`
+  to `RailsAiBridge::Introspectors::ModelSemanticClassifier`. Removed the
+  `RailsAiBridge::Service` superclass from
+  `RubydexAdapter::IncrementalIndexer` (duck-types the Result contract) and
+  gave `ContextFileSerializer` a caller-supplied required `fingerprint:` kwarg
+  (`ContextGenerationService` computes and passes it; custom serializer
+  classes must now accept `fingerprint:`; the remaining write options
+  (`format:`, `split_rules:`, `on_conflict:`, `managed_region:`) are accepted
+  as a `**write_options` group). `ContextGenerationService.call` no longer
+  takes a `fingerprint:` override — the fingerprint is always computed at
+  call time; inject one via `.new`. Unknown serializer write options now
+  raise `ArgumentError` (matching the previous explicit-keyword behavior).
+  The archspec todo baseline and all
+  36 inline `archspec:disable` suppressions are gone;
+  `bundle exec archspec check` reports zero violations.
+- **Docs cleanup (#246).** README quick start no longer says the gem is
+  "once published" (it ships on RubyGems as 5.1.0). The three registry/port
+  planning docs are consolidated into the canonical
+  `docs/port-registry-resolution.md` (as-built record + user-facing
+  "Registry Resolution Reference"); `docs/02-port-registry-resolution.md` and
+  `docs/registry-resolution.md` are deleted. Completed planning docs
+  `docs/gem-general-improvements.md` and `docs/review-workflow-report.md`
+  moved to `docs/archive/`. Junk file `test_table.md` removed.
+- **Docs truth (#247).** AGENTS.md, CLAUDE.md, and CONTRIBUTING.md no longer
+  claim the project follows the `rubocop-rails-omakase` style — `.rubocop.yml`
+  uses its own custom limits (performance/rails/rspec plugins; method length,
+  ABC size and class length limits deliberately more permissive). AGENTS.md
+  and CLAUDE.md no longer describe `non_ar_models` as opt-in-only — it ships
+  in the `:full` preset; only `database_stats` and `semantic` are opt-in-only
+  (fixed the same claim in the `Introspector::BUILTIN_INTROSPECTORS` YARD
+  comment). `doc_parity_spec.rb` gains guard examples for both claims.
+
+### Fixed
+
+- `DatabaseSize.bucket` and `DatabaseSize.bucket_for_table` no longer classify
+  invalid row counts as the `hot` bucket. Negative counts, including negative
+  fractional counts (e.g. stale or unanalyzed PostgreSQL statistics sentinels),
+  and non-numeric values now return `nil` instead of being bucketed as `hot`
+  (fallback) or `small` (`to_i` truncation/coercion). Callers already treat
+  `nil` as "no size data".
+- `server.json` no longer drifts from the released gem: its `version` now
+  matches `RailsAiBridge::VERSION` (was stale at `3.0.0`) and the description
+  reports the real 20 read-only tools (was 13). `CONTRIBUTING.md`, `GEMINI.md`,
+  and `docs/GUIDE.md` tool counts corrected from 19 to 20; `GEMINI.md` also
+  documents the `:full` preset as 27 introspectors (was a corrupted 26/27
+  mix). Parity and release-consistency specs now guard the `server.json`
+  version and tool counts (fixes #245).
 
 ## [5.1.0] - 2026-09-11
 

data/CLAUDE.md

@@ -10,9 +10,10 @@ committed context files. It does not write to the host database.
 - `lib/rails_ai_bridge/introspector.rb` — Orchestrates sub-introspectors
 - `lib/rails_ai_bridge/introspectors/` — Built-in introspector classes; `:standard` preset
   runs **9**, `:full` runs **27** (see `Configuration::PRESETS`). Registry:
-  `Introspector::BUILTIN_INTROSPECTORS` (includes opt-in symbols such as
-  `database_stats`, `non_ar_models` not listed in those presets).
-- `lib/rails_ai_bridge/tools/` — 20 built-in MCP tools using the official mcp SDK
+  `Introspector::BUILTIN_INTROSPECTORS` (`:full` already includes
+  `non_ar_models`; opt-in-only symbols not in any preset: `database_stats`,
+  `semantic`).
+- `lib/rails_ai_bridge/tools/` — 22 built-in MCP tools using the official mcp SDK
   (hosts can add more via `additional_tools`)
 - `lib/rails_ai_bridge/serializers/` — Output formatters (claude, claude_rules,
   codex, cursor_rules, devin, devin_rules, copilot, copilot_instructions,
@@ -38,7 +39,7 @@ committed context files. It does not write to the host database.
 6. **Diff-aware** — context regeneration skips unchanged files
 7. **Per-assistant serializers** — each AI tool gets tailored output format
 8. **Zeitwerk autoloading** — files loaded on-demand, not all upfront
-9. **Introspector presets** — `:standard` (9 core) default, `:full` (27 introspectors; optional extras such as `database_stats`, `non_ar_models`) for power users
+9. **Introspector presets** — `:standard` (9 core) default, `:full` (27 introspectors, includes `non_ar_models`) with opt-in extras such as `database_stats` and `semantic` for power users
 10. **MCP auto-discovery** — `.mcp.json` generated by install generator
 11. **Outbound context providers (v5)** — `rails_get_provider_context` fetches from declared external MCP services. Disabled by default, exact host allowlist, read-only tool enforcement, `ToolResultCache::NON_CACHEABLE` exclusion. Separate from local `rails_get_context`.
 12. **Compact by default** — context files ≤150 lines, MCP tools use `detail` parameter (summary/standard/full)
@@ -56,7 +57,7 @@ Uses combustion gem for testing Rails engine behavior in isolation.
 ## Conventions
 
 - Ruby 3.2+ features OK (pattern matching, etc.)
-- Follow rubocop-rails-omakase style
+- Follow RuboCop with the project's custom limits (see `.rubocop.yml` — plugins performance/rails/rspec; method length, ABC size and class length limits are deliberately more permissive than the omakase defaults)
 - Every introspector returns a Hash, never raises (wraps errors in `{ error: msg }`)
 - MCP tools return `MCP::Tool::Response` objects per SDK convention
 - All tools prefixed with `rails_` per MCP naming best practices

data/CONTRIBUTING.md

@@ -19,7 +19,7 @@ The test suite uses [Combustion](https://github.com/pat/combustion) to boot a mi
 ```
 lib/rails_ai_bridge/
 ├── introspectors/          # Built-in introspectors (schema, models, non_ar_models, routes, …)
-├── tools/                  # 19 built-in MCP tools (detail levels, pagination, extensible)
+├── tools/                  # 22 built-in MCP tools (detail levels, pagination, extensible)
 ├── rubydex_adapter.rb       # Rubydex API wrapper (singleton + query interface + stats)
 ├── rubydex_adapter/         # Extracted collaborators (one concern each)
 │   ├── serializer.rb        # Hash serialization (declaration_to_hash, definition_to_hash, …)
@@ -49,7 +49,7 @@ lib/rails_ai_bridge/
 
 ## Code Style
 
-- Follow `rubocop-rails-omakase` style (run `bundle exec rubocop`)
+- Follow RuboCop with the project's custom limits (see `.rubocop.yml` — plugins performance/rails/rspec; method length, ABC size and class length limits are deliberately more permissive than the omakase defaults); run `bundle exec rubocop`
 - Optional complexity check: `bundle exec skunk lib/rails_ai_bridge/…` (gem in `:development`/`:test`) — keep new or refactored files lean (project goal: Skunk score around **≤ 25** where practical).
 
 - Ruby 3.2+ features welcome (pattern matching, etc.)

data/GEMINI.md

@@ -8,10 +8,9 @@ committed context files. It does not write to the host database.
 - `lib/rails_ai_bridge.rb` — Main entry point, public API (Zeitwerk autoloaded)
 - `lib/rails_ai_bridge/configuration.rb` — User-facing config with presets (:standard, :full)
 - `lib/rails_ai_bridge/introspector.rb` — Orchestrates sub-introspectors
-- `lib/rails_ai_bridge/introspectors/` — Built-in introspector classes; `:standard` preset runs **9**, `:full` runs **26** (see `Configuration::PRESETS`). Registry: `Introspector::BUILTIN_INTROSPECTORS` (includes opt-in symbols such as `database_stats`, `non_ar_models` not listed in those presets).
-- `lib/rails_ai_bridge/tools/` — 19 built-in MCP tools using the official mcp SDK (hosts can add more via `additional_tools`)
-- `lib/rails_ai_bridge/serializers/` — Output formatters (claude, claude_rules, cursor_rules, windsurf, windsurf_rules, copilot, copilot_instructions, rules, markdown, JSON, gemini)
-  runs **9**, `:full` runs **27** (see `Configuration::PRESETS`). Registry:
+- `lib/rails_ai_bridge/introspectors/` — Built-in introspector classes; `:standard` preset runs **9**, `:full` runs **27** (see `Configuration::PRESETS`). Registry: `Introspector::BUILTIN_INTROSPECTORS` (includes opt-in symbols such as `database_stats`, `non_ar_models` not listed in those presets).
+- `lib/rails_ai_bridge/tools/` — 22 built-in MCP tools using the official mcp SDK (hosts can add more via `additional_tools`)
+- `lib/rails_ai_bridge/serializers/` — Output formatters (claude, claude_rules, codex, cursor_rules, devin, devin_rules, copilot, copilot_instructions, gemini, rules, markdown, JSON)
 - `lib/rails_ai_bridge/resources.rb` — MCP resources (static data AI clients read directly)
 - `lib/rails_ai_bridge/server.rb` — MCP server configuration (stdio + HTTP transports)
 - `lib/rails_ai_bridge/middleware.rb` — Rack middleware for auto-mounting MCP HTTP endpoint