rails-ai-bridge 4.1.0 → 4.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f7810f4efa4400b60d813b2344b82f38e0a731ccc89e68a3be51aabe2526a3d
-  data.tar.gz: 7faa7fe7f2f731d572806596a3f60d756d85b589ba46b6dfa7ef2e614bea8749
+  metadata.gz: 24c9dd6461240b9d6864b35c171c465635f9fdacc3c76195915f43b995a27f18
+  data.tar.gz: e97756c625478c854f78f661393d26043ba36b07b8941bed7a2a2c09b3a62a4b
 SHA512:
-  metadata.gz: 1d4cf0bdcf2dcf203a30b112ac940709dcf3222af18efaeb10625d08594197f38d49cfb23f5edc328fce6a4fd6242b02aa545cb6075c5c142ab81b3a5b89d1d5
-  data.tar.gz: 2f7dad1ecef89cc739b7a8031f16e753b0b4a55bdabbc52f8692f6b42f05f0cf7a14acc80700d819f401649eb384fc7109d98569372462f651eee2ea608d7767
+  metadata.gz: f453227c44348be19356eecb728dac22328abcb20a99cf0430f441c68557346d93576527716764cae4f68f404fcab524dd44c4454b27a4f9078955632be8937f
+  data.tar.gz: 10e975098f252c37f37108e04d0e370b03f469829f9e2520334b180e83a8844a8276b9f4ed60ae650e0f9bd47dd7361b42885dcbdf87880e37d56c04152720fa

data/.mutant.yml

@@ -0,0 +1,26 @@
+---
+# Mutant configuration for rails-ai-bridge critical paths.
+#
+# Run with: BUNDLE_GEMFILE=Gemfile-mutation bundle exec mutant run [subject expressions]
+# Example: BUNDLE_GEMFILE=Gemfile-mutation bundle exec mutant run RailsAiBridge::Registry::FrontmatterParser
+#
+# The open-source usage mode is used because rails-ai-bridge is an
+# open-source project. A commercial license is required for private
+# repositories or advanced features (full operator set, isolation).
+#
+# Target: >80% mutation coverage on registry/tools.
+#
+# Subject expressions are passed on the CLI to target critical paths:
+#   RailsAiBridge::Registry            — registry resolution
+#   RailsAiBridge::Tools               — MCP tools
+#   RailsAiBridge::Serializers         — output serializers
+usage: opensource
+integration: rspec
+includes:
+  - lib
+  - spec
+requires:
+  - spec_helper
+fail_fast: false
+mutation:
+  timeout: 5.0

data/.rubocop.yml

@@ -9,6 +9,7 @@ AllCops:
     - "vendor/**/*"
     - "spec/internal/**/*"
     - "gemfiles/**/*"
+    - ".mutant.yml"
 Naming/FileName:
   Exclude:
     - "lib/rails-ai-bridge.rb"
@@ -39,6 +40,8 @@ Layout/LineLength:
   Max: 180
 Metrics/ModuleLength:
   Max: 240
+  Exclude:
+    - "lib/rails_ai_bridge/resources.rb"
 Metrics/MethodLength:
   Max: 70
 RSpec/NestedGroups:
@@ -57,6 +60,12 @@ RSpec/MultipleDescribes:
   Enabled: false
 RSpec/MessageSpies:
   Enabled: false
+RSpec/Output:
+  Exclude:
+    - "spec/support/perf_baseline.rb"
+Rails/RakeEnvironment:
+  Exclude:
+    - "lib/tasks/*.rake"
 Metrics/PerceivedComplexity:
   Max: 35
   Exclude:

data/AGENTS.md

@@ -8,9 +8,9 @@ structure to AI assistants via the Model Context Protocol (MCP).
 - `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/` — 16 built-in MCP tools using the official mcp SDK (hosts can add more via `additional_tools`)
-- `lib/rails_ai_bridge/serializers/` — Output formatters (Codex, claude_rules, cursor_rules, devin, devin_rules, copilot, copilot_instructions, rules, markdown, JSON)
+- `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/` — 17 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
@@ -30,10 +30,10 @@ structure to AI assistants via the Model Context Protocol (MCP).
 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` (26 introspectors; optional extras such as `database_stats`, `non_ar_models`) for power users
+9. **Introspector presets** — `:standard` (9 core) default, `:full` (27 introspectors; optional extras such as `database_stats`, `non_ar_models`) for power users
 10. **MCP auto-discovery** — `.mcp.json` generated by install generator
 11. **Compact by default** — context files ≤150 lines, MCP tools use `detail` parameter (summary/standard/full)
-12. **Per-tool split rules** — `.Codex/rules/`, `.cursor/rules/`, `.devin/rules/`, `.github/instructions/`
+12. **Per-tool split rules** — `.codex/`, `.cursor/rules/`, `.devin/rules/`, `.github/instructions/`
 
 ## Testing
 

data/CHANGELOG.md

@@ -5,6 +5,33 @@ 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).
 
+## [4.2.0] - 2026-08-13
+
+### Added
+
+- **`rails_list_context_providers` MCP tool and dynamic resources** (#147) — new tool reads the registry manifest's `context_providers` section and returns formatted markdown with provider name, type, endpoint, optional flag, and tool specs. Context providers are also registered as dynamic MCP resources (URI template `rails://context-providers/{name}`), bringing the tool count from 16 to 17.
+- **Registry health checker for Doctor** (#145) — new `Doctor::Checkers::RegistryChecker` validates manifest existence, JSON parsing, `RegistryManifest.validate!`, resolver construction, and lockfile presence (when configured). Returns pass/warn/fail with actionable fix hints. Doctor check count: 17.
+- **Request-level resolver memoization** (#159) — `Registry.with_request_resolver` wraps each tool invocation in a thread-local request scope so `build_resolver` is called once per request instead of once per tool. Nil results are never memoized; thread-local storage is always cleaned up (even on error).
+- **Dependabot configuration** (#153) — `.github/dependabot.yml` with grouped updates for bundler, github-actions, and gomod ecosystems, plus automatic PR labeling.
+- **Rails 8.1 in release workflow matrix** (#164) — `.github/workflows/release.yml` now includes Rails 8.1 alongside 7.1, 7.2, and 8.0.
+- **Skunk score threshold CI job** (#157) — advisory CI job runs `skunk lib/` after tests generate coverage data, fails if the SkunkScore average exceeds 30. Threshold to be ratcheted down over time.
+- **Performance regression baseline** (#160) — `spec/support/perf_baseline.json` with three metrics (introspection, context generation, MCP tool response). `rake perf:compare` fails on >20% regression. CI uploads the baseline as a 30-day artifact.
+- **Mutation testing for critical paths** (#163) — `mutant-rspec` via separate `Gemfile-mutation` (eval'd from the main Gemfile) to avoid breaking Ruby 3.2 CI resolution. Advisory CI job targets `Registry::Resolver`, `FrontmatterParser`, `RegistryManifest`, `PackResolver`, `SkillSourceResolver`, and key tools/serializers. Initial coverage: 94.39% on `FrontmatterParser`.
+- **YARD documentation for 9 uncovered files** (#156) — `@param`/`@return` tags added to `search_code.rb`, all 6 introspectors, `json_serializer.rb`, and `usage_formatter.rb`. `yard stats` now 100% for `lib/`.
+- **Dedicated `UsageFormatter` spec** (#151) — comprehensive spec coverage for `Tools::UsageFormatter` formatting logic.
+- **Registry server specs and integration tests** (#149, #150) — `server_spec.rb` extended with registry tool assertions; new `mcp/registry_integration_spec.rb` covers `rails_list_registry`, `rails_resolve_skill`, and `rails_use_skill` end-to-end through the MCP server.
+- **Documentation parity guard spec** — `spec/lib/rails_ai_bridge/doc_parity_spec.rb` fails when README/AGENTS/CLAUDE tool or introspector counts drift from the actual constants.
+
+### Changed
+
+- **Standardized registry manifest and lockfile paths** (#155) — defaults changed from `config/rails_ai_bridge_registry.json` / `config/rails_ai_bridge_registry.lock` to `config/rails_ai_bridge/registry.json` / `config/rails_ai_bridge/registry.lock`. Backward-compat fallback: when the new path doesn't exist but the legacy path does, the getter returns the legacy path. Custom user paths are never overridden.
+- **Documentation humanization and Windsurf purge** (#144, #148) — README, AGENTS.md, CLAUDE.md, CONTRIBUTING.md, and SECURITY.md updated: tool count 16→17, introspector count 26→27, serializer list humanized (alphabetical with Claude/Codex/Gemini), bogus `.Codex/rules/` path fixed to `.codex/`, Windsurf support claims removed (no serializer will be implemented), Mermaid diagrams added to docs.
+
+### Fixed
+
+- **`Instrumentation::InstrumentedTool` server_context parameter translation** — tools without caching received `server_context:` but expected `_server_context:`, causing `ArgumentError` when caching was disabled. `InstrumentedTool` now detects the tool's parameter name and translates accordingly.
+- **`ContextProvider` cache key fork safety** (#162) — replaced `object_id`-based cache key with a stable digest, preventing stale cache hits after `Process.fork`.
+
 ## [4.1.0] - 2026-08-11
 
 ### Added

data/CLAUDE.md

@@ -9,14 +9,14 @@ structure to AI assistants via the Model Context Protocol (MCP).
 - `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:
+  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/` — 16 built-in MCP tools using the official mcp SDK
+- `lib/rails_ai_bridge/tools/` — 17 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, devin, devin_rules, copilot, copilot_instructions, rules,
-  markdown, JSON)
+  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
@@ -36,7 +36,7 @@ structure to AI assistants via the Model Context Protocol (MCP).
 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` (26 introspectors; optional extras such as `database_stats`, `non_ar_models`) for power users
+9. **Introspector presets** — `:standard` (9 core) default, `:full` (27 introspectors; optional extras such as `database_stats`, `non_ar_models`) for power users
 10. **MCP auto-discovery** — `.mcp.json` generated by install generator
 11. **Compact by default** — context files ≤150 lines, MCP tools use `detail` parameter (summary/standard/full)
 12. **Per-tool split rules** — `.claude/rules/`, `.cursor/rules/`, `.devin/rules/`, `.github/instructions/`

data/CONTRIBUTING.md

@@ -19,13 +19,13 @@ 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/                  # 11 built-in MCP tools (detail levels, pagination, extensible)
+├── tools/                  # 17 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, …)
 │   ├── indexer.rb           # Graph building + source file scanning
 │   └── method_counter.rb    # Flat method counting pipeline (no nested conditionals)
-├── serializers/            # Per-assistant formatters (claude, cursor, windsurf, copilot, JSON)
+├── serializers/            # Per-assistant formatters (claude, codex, cursor, devin, copilot, gemini, JSON)
 ├── server.rb               # MCP server setup (stdio + HTTP)
 ├── engine.rb               # Rails Engine for auto-integration
 └── configuration.rb        # User-facing config (presets, context_mode, limits)

data/README.md

@@ -83,7 +83,7 @@ This creates two complementary layers:
 | Static files | Give the assistant passive project orientation at session start | Fewer cold starts and fewer generic assumptions |
 | MCP tools | Return exact live details when requested | Less context bloat and fewer schema/route hallucinations |
 
-Compact files are ordered for usefulness: primary domain models, busy endpoints, recently migrated tables, and optional hot-table signals appear before lower-signal supporting details.
+Compact files are ordered for usefulness: primary domain models, busy endpoints, recently migrated tables, and optional hot-table hints appear before less important details.
 
 ## Safety model
 
@@ -159,7 +159,7 @@ Optional: `gem install rails-ai-bridge` installs the gem into your Ruby environm
 | Zero config | Yes — Railtie + install generator | No — per-project `projects.yml` | No |
 | Token optimization | Yes — compact files + `detail:"summary"` workflow | Varies | No |
 | Codex-oriented repo files | Yes — `AGENTS.md`, `.codex/README.md` | No | DIY |
-| Live MCP tools | Yes — 13 read-only `rails_*` tools (extensible) | Yes | No |
+| Live MCP tools | Yes — 17 read-only `rails_*` tools (extensible) | Yes | No |
 | Auto-introspection | Yes — up to **27** domains (`:full`) | No — server points at projects you configure | DIY |
 
 *Comparison reflects typical documented setups; verify against each project before treating any row as absolute.*
@@ -251,7 +251,7 @@ This keeps context focused and avoids unnecessary token usage while still allowi
 
 ## MCP Tools
 
-The gem exposes **16 built-in tools** via MCP that AI clients call on-demand (hosts can append more via `config.additional_tools`):
+The gem exposes **17 built-in tools** via MCP that AI clients call on-demand (hosts can append more via `config.additional_tools`):
 
 | Tool | What it returns |
 |------|----------------|
@@ -267,10 +267,11 @@ The gem exposes **16 built-in tools** via MCP that AI clients call on-demand (ho
 | `rails_get_view` | View layouts, templates, partials; optional per-file detail under the configured `app/views` path |
 | `rails_search_semantic` | Semantic code search using rubydex — find declarations by name with types, locations, and relationships |
 | `rails_get_stimulus` | Stimulus controllers: targets, values, actions, outlets (requires `:stimulus` introspector) |
-| `rails_list_registry` | Skill pack catalog — list skills, agents, or active packs; requires `config/rails_ai_bridge_registry.json` |
+| `rails_list_registry` | Skill pack catalog — list skills, agents, or active packs; requires `config/rails_ai_bridge/registry.json` |
 | `rails_resolve_skill` | Full content of a named skill or agent from the registry (priority ordering + deprecation redirects); optional `pack=` pin and `type=agent` |
 | `rails_use_skill` | Loads a skill framed as an application directive (apply it step by step to the current task) |
 | `rails_use_agent` | Loads an agent/workflow framed as an activation directive (follow it end to end) |
+| `rails_list_context_providers` | Context providers declared in the registry manifest — external services (e.g. MCP servers) the bridge can query for project context; shows type, endpoint, optional flag, and tool specs |
 
 All tools are **read-only** — they never modify your application or database.
 
@@ -307,7 +308,7 @@ A safety net (`max_tool_response_chars`, default 120K) truncates oversized respo
 
 Early project-level trials suggest the biggest improvement is not always dramatic token reduction by itself. In several runs, `rails-ai-bridge` led to faster, more focused responses even when total token usage only dropped modestly.
 
-This is expected: compact assistant-specific files and the summary-first MCP workflow reduce orientation overhead, help the model navigate the codebase earlier, and improve the quality of the initial context.
+This makes sense: compact assistant-specific files and the summary-first MCP workflow help the model find relevant code faster and start with better context.
 
 Observed benefits so far:
 - Less exploratory reading before the assistant reaches the relevant files
@@ -543,7 +544,7 @@ end
 | `parallel_introspection` | `false` | Run introspectors concurrently (requires `concurrent-ruby`, which is already a Rails dependency) |
 | `parallel_pool_size` | `4` | Max threads in the parallel pool; capped at the number of active introspectors so no idle threads are created |
 | `parallel_timeout_seconds` | `10` | Per-introspector future timeout (seconds); timed-out introspectors return `{ error: "timed out after Ns" }` without blocking the others |
-| `registry.registry_manifest_path` | `"config/rails_ai_bridge_registry.json"` | Path to the registry manifest JSON file for skill pack resolution |
+| `registry.registry_manifest_path` | `"config/rails_ai_bridge/registry.json"` | Path to the registry manifest JSON file for skill pack resolution |
 | `registry.skill_cache_dir` | `"~/.rails-ai-bridge/cache"` | Directory for caching git repositories containing skill packs |
 | `registry.skill_packs` | `nil` | Explicit pack names to load, or `nil` for auto-detection based on framework |
 | `registry.local_registry_paths` | `[]` | Local directory paths (must contain `directory.json`) loaded at priority 0 |
@@ -686,10 +687,10 @@ To customize it in your initializer (`config/initializers/rails_ai_bridge.rb`):
 rails-ai-bridge can load **skill packs** — shared collections of agent instructions — from versioned git repositories and surface them through `rails_list_registry` and rake tasks.
 
 ```ruby
-config.registry.registry_manifest_path = "config/rails_ai_bridge_registry.json"
+config.registry.registry_manifest_path = "config/rails_ai_bridge/registry.json"
 ```
 
-Quick example manifest (`config/rails_ai_bridge_registry.json`):
+Quick example manifest (`config/rails_ai_bridge/registry.json`):
 
 ```json
 {
@@ -835,7 +836,7 @@ Bug reports and pull requests: [github.com/igmarin/rails-ai-bridge/issues](https
 
 ## Acknowledgments & Origins
 
-This gem ships as **rails-ai-bridge** (Ruby **`RailsAiBridge`**, version **4.1.0**). Earlier iterations of the same codebase were distributed as `rails-ai-context`.
+This gem ships as **rails-ai-bridge** (Ruby **`RailsAiBridge`**, version **4.2.0**). Earlier iterations of the same codebase were distributed as `rails-ai-context`.
 
 RailsMCP evolved from 
 [crisnahine/rails-ai-context](https://github.com/crisnahine/rails-ai-context),

data/Rakefile

@@ -5,4 +5,6 @@ require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
+Dir.glob('lib/tasks/*.rake').each { |task| load task }
+
 task default: :spec

data/SECURITY.md

@@ -4,10 +4,10 @@
 
 | Version | Supported          |
 |---------|--------------------|
-| 3.6.x   | :white_check_mark: |
-| 3.5.x   | :white_check_mark: |
-| 3.0.x–3.4.x | :white_check_mark: (security fixes best-effort) |
-| 2.x     | :x: (end of life — upgrade to 3.x) |
+| 4.x     | :white_check_mark: |
+| 3.6.x   | :white_check_mark: (security fixes best-effort) |
+| 3.0.x–3.5.x | :warning: (best-effort) |
+| 2.x     | :x: (end of life — upgrade to 4.x) |
 | 1.x     | :x: |
 | < 1.0   | :x: |
 

data/docs/02-port-registry-resolution.md

@@ -96,7 +96,7 @@ end
 ### 3. Configuration
 
 **Add to `lib/rails_ai_bridge/configuration.rb`:**
-- `registry_manifest_path` — Path to registry.json (default: `config/rails_ai_bridge_registry.json`)
+- `registry_manifest_path` — Path to registry.json (default: `config/rails_ai_bridge/registry.json`)
 - `skill_cache_dir` — Path to git cache directory (default: `~/.rails-ai-bridge/cache`)
 - `skill_packs` — Array of explicit pack names to load (optional)
 - `local_registry_paths` — Array of local registry directories (optional)

data/docs/devin-setup.md

@@ -226,7 +226,7 @@ rails-ai-bridge supports a skill registry — a collection of reusable AI skills
 
 The `rails_list_registry` tool returns all available skills. The `rails_resolve_skill` tool retrieves the full content of a named skill so Devin can apply it.
 
-Skills are configured via `config/rails_ai_bridge_registry.json` in your Rails application. A minimal registry file looks like:
+Skills are configured via `config/rails_ai_bridge/registry.json` in your Rails application. A minimal registry file looks like:
 
 ```json
 {
@@ -261,4 +261,4 @@ Devin will call `rails_list_registry`, review the options, and call `rails_resol
 | `.devin/rules/rails-mcp-tools.md` | `rails ai:bridge:devin` | Yes |
 | `AGENTS.md` | `rails ai:bridge:devin` | Yes |
 | `.devin/mcp.json` | Manual | Yes |
-| `config/rails_ai_bridge_registry.json` | Manual | Yes |
+| `config/rails_ai_bridge/registry.json` | Manual | Yes |

data/docs/port-registry-resolution.md

@@ -119,7 +119,7 @@ necessary for the future skill compiler feature.
 
 **Files:**
 - `lib/rails_ai_bridge/config/registry.rb` — `Config::Registry` sub-object
-  - `registry_manifest_path` (default: `config/rails_ai_bridge_registry.json`)
+  - `registry_manifest_path` (default: `config/rails_ai_bridge/registry.json`)
   - `skill_cache_dir` (default: `~/.rails-ai-bridge/cache`)
   - `skill_packs` (default: `nil` — triggers auto-detection)
   - `local_registry_paths` (default: `[]`)

data/docs/registry-resolution.md

@@ -16,7 +16,7 @@ When a pack is loaded, its skills and agents appear in `rails_list_registry`, an
 
 ## Quick start
 
-**1. Create the registry manifest** at `config/rails_ai_bridge_registry.json`:
+**1. Create the registry manifest** at `config/rails_ai_bridge/registry.json`:
 
 ```json
 {
@@ -39,7 +39,7 @@ When a pack is loaded, its skills and agents appear in `rails_list_registry`, an
 
 ```ruby
 RailsAiBridge.configure do |config|
-  config.registry.registry_manifest_path = "config/rails_ai_bridge_registry.json"
+  config.registry.registry_manifest_path = "config/rails_ai_bridge/registry.json"
 end
 ```
 
@@ -102,7 +102,7 @@ All options live under `config.registry.*`:
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `registry_manifest_path` | `"config/rails_ai_bridge_registry.json"` | Path to the registry manifest JSON |
+| `registry_manifest_path` | `"config/rails_ai_bridge/registry.json"` | Path to the registry manifest JSON |
 | `skill_cache_dir` | `~/.rails-ai-bridge/cache` | Directory for caching cloned git repositories |
 | `skill_packs` | `nil` | Explicit list of pack names to load, or `nil` for auto-detection |
 | `local_registry_paths` | `[]` | Local directory paths containing a `directory.json` (loaded at priority 0) |

data/docs/skill-registry-guide.md

@@ -18,7 +18,7 @@ A **skill pack** is a git repository containing:
 - **Markdown files** for each skill (e.g. `skills/code-review.md`)
 - Optional **deprecation redirects** when skills are renamed
 
-The skill registry in your Rails app is a **`config/rails_ai_bridge_registry.json`** manifest that tells rails-ai-bridge which packs to load, where to find them, and how to prioritize them when two packs define a skill with the same name.
+The skill registry in your Rails app is a **`config/rails_ai_bridge/registry.json`** manifest that tells rails-ai-bridge which packs to load, where to find them, and how to prioritize them when two packs define a skill with the same name.
 
 ---
 
@@ -26,7 +26,7 @@ The skill registry in your Rails app is a **`config/rails_ai_bridge_registry.jso
 
 ### Step 1 — Create the registry manifest
 
-Create `config/rails_ai_bridge_registry.json` in your Rails app:
+Create `config/rails_ai_bridge/registry.json` in your Rails app:
 
 ```json
 {
@@ -78,7 +78,7 @@ In `config/initializers/rails_ai_bridge.rb`:
 
 ```ruby
 RailsAiBridge.configure do |config|
-  config.registry.registry_manifest_path = "config/rails_ai_bridge_registry.json"
+  config.registry.registry_manifest_path = "config/rails_ai_bridge/registry.json"
 end
 ```
 
@@ -195,13 +195,13 @@ This protects against:
 rails ai:registry:lockfile
 ```
 
-The file is written to `config/rails_ai_bridge/directory.lock` by default. Commit it alongside your manifest.
+The file is written to `config/rails_ai_bridge/registry.lock` by default. Commit it alongside your manifest.
 
 ### Configuration
 
 ```ruby
 RailsAiBridge.configure do |config|
-  config.registry.lockfile_path = "config/rails_ai_bridge/directory.lock"
+  config.registry.lockfile_path = "config/rails_ai_bridge/registry.lock"
   config.registry.lockfile_verification = :strict  # :strict (default), :warn, or :disabled
 end
 ```
@@ -438,7 +438,7 @@ initializer changes take effect immediately.
 
 | Symptom | Likely cause | Fix |
 |---------|-------------|-----|
-| `rails ai:skills:list` shows "No registry manifest found" | Manifest file does not exist or path is wrong | Create `config/rails_ai_bridge_registry.json` or check `config.registry.registry_manifest_path` |
+| `rails ai:skills:list` shows "No registry manifest found" | Manifest file does not exist or path is wrong | Create `config/rails_ai_bridge/registry.json` or check `config.registry.registry_manifest_path` |
 | Git clone fails with "not found" | Pack source URL is wrong or repo is private | Check the `source` field; for private repos use a full SSH URL `git@github.com:org/repo.git` |
 | `Invalid source format` error mentioning `http://` | Pack source uses plain HTTP | Change `source` to `https://` or `git@` — plain HTTP is not accepted |
 | Pack loads but shows 0 skills | `directory.json` is missing or has wrong path | Check the root of the cloned pack for `directory.json`; set `tile:` field if the file is elsewhere |
@@ -446,7 +446,7 @@ initializer changes take effect immediately.
 | Stale skills after pack update | Resolver cache is warm or pull TTL has not elapsed | Run `rails ai:skills:clear_cache` to force a re-clone on the next build |
 | Pack is not re-fetched even after `resolver_ttl` expired | Pack was cloned recently — `git_pull_ttl` (24 h) is still fresh | Run `rails ai:skills:clear_cache` or set `git_pull_ttl: 0` temporarily |
 | `git checkout <ref>` failed | Invalid ref or detached HEAD issue | Verify the `ref` value matches a branch, tag, or SHA in the remote repo |
-| `Lockfile mismatch for pack '…'` | Resolved pack commit differs from `directory.lock` | Run `rails ai:registry:lockfile` to update the lockfile after reviewing the pack changes |
+| `Lockfile mismatch for pack '…'` | Resolved pack commit differs from `registry.lock` | Run `rails ai:registry:lockfile` to update the lockfile after reviewing the pack changes |
 | Git operation hangs / server request times out | Slow or unreachable remote | Reduce `git_timeout` to fail faster; check network connectivity to the remote |
 | Warning: "Pack '…' depends on '…' which is not in the active pack set" | A loaded pack has an unsatisfied `depends_on` entry | Add the missing pack name to `always_loaded` or `skill_packs` in your manifest, or enable `config.registry.auto_load_dependencies` |
 | Warning: "Circular dependency detected: …" | Two or more active packs depend on each other | Break the cycle in the manifests; packs still load, but the cycle usually indicates a mistake |
@@ -462,5 +462,5 @@ initializer changes take effect immediately.
 - **Timeout protection**: all git operations are bounded by `git_timeout` (default 30 s) so a slow remote cannot block the calling thread indefinitely.
 - **Cache key sanitization**: local cache directory names are derived from a sanitized source string plus a SHA256 hash suffix to prevent filesystem collisions.
 - **Stable local pack names**: local registry pack names use a SHA256 digest of the directory path, so reordering `local_registry_paths` cannot silently shift pack identities.
-- **Lockfile verification**: a `directory.lock` records the expected commit SHA for each remote pack. The resolver fails closed when the cloned commit does not match, preventing a compromised or unexpectedly modified pack from injecting instructions.
+- **Lockfile verification**: a `registry.lock` records the expected commit SHA for each remote pack. The resolver fails closed when the cloned commit does not match, preventing a compromised or unexpectedly modified pack from injecting instructions.
 - **Local path trust**: local paths are used directly without git operations. The path traversal guard in the Resolver still applies to file reads within a local pack.

data/lib/rails_ai_bridge/config/registry.rb

@@ -11,8 +11,20 @@ module RailsAiBridge
     # @see RailsAiBridge::Registry::PackResolver
     # @see RailsAiBridge::Registry::Resolver
     class Registry
+      # Default path for the registry manifest (4.2.0+ standard location).
+      DEFAULT_REGISTRY_MANIFEST_PATH = 'config/rails_ai_bridge/registry.json'
+
+      # Legacy manifest path used before 4.2.0; kept for backward-compat fallback.
+      LEGACY_REGISTRY_MANIFEST_PATH = 'config/rails_ai_bridge_registry.json'
+
+      # Default path for the skill pack lockfile (4.2.0+ standard location).
+      DEFAULT_LOCKFILE_PATH = 'config/rails_ai_bridge/registry.lock'
+
+      # Legacy lockfile path used before 4.2.0; kept for backward-compat fallback.
+      LEGACY_LOCKFILE_PATH = 'config/rails_ai_bridge/directory.lock'
+
       # @return [String] path to the registry manifest JSON file
-      attr_accessor :registry_manifest_path
+      attr_writer :registry_manifest_path
 
       # @return [String] directory for caching git repositories
       attr_accessor :skill_cache_dir
@@ -36,7 +48,38 @@ module RailsAiBridge
       attr_reader :git_timeout
 
       # @return [String, nil] path to the skill pack lockfile. nil disables lockfile verification.
-      attr_accessor :lockfile_path
+      attr_writer :lockfile_path
+
+      # Returns the configured registry manifest path, applying a backward-compatibility
+      # fallback when the default path does not exist but the legacy path does.
+      #
+      # @return [String] resolved manifest path
+      def registry_manifest_path
+        return @registry_manifest_path unless @registry_manifest_path == DEFAULT_REGISTRY_MANIFEST_PATH
+
+        File.exist?(DEFAULT_REGISTRY_MANIFEST_PATH) ? DEFAULT_REGISTRY_MANIFEST_PATH : legacy_manifest_path
+      end
+
+      # Returns the configured lockfile path, applying a backward-compatibility
+      # fallback when the default path does not exist but the legacy path does.
+      # Returns +nil+ when lockfile verification is disabled.
+      #
+      # @return [String, nil] resolved lockfile path
+      def lockfile_path
+        return @lockfile_path unless @lockfile_path == DEFAULT_LOCKFILE_PATH
+
+        File.exist?(DEFAULT_LOCKFILE_PATH) ? DEFAULT_LOCKFILE_PATH : legacy_lockfile_path
+      end
+
+      # @api private
+      def legacy_manifest_path
+        File.exist?(LEGACY_REGISTRY_MANIFEST_PATH) ? LEGACY_REGISTRY_MANIFEST_PATH : DEFAULT_REGISTRY_MANIFEST_PATH
+      end
+
+      # @api private
+      def legacy_lockfile_path
+        File.exist?(LEGACY_LOCKFILE_PATH) ? LEGACY_LOCKFILE_PATH : DEFAULT_LOCKFILE_PATH
+      end
 
       # @return [Symbol] how to behave when the lockfile differs from the resolved pack:
       #   :strict (default) raises, :warn logs but proceeds, :disabled skips verification.
@@ -97,14 +140,14 @@ module RailsAiBridge
       end
 
       def initialize
-        @registry_manifest_path = 'config/rails_ai_bridge_registry.json'
+        @registry_manifest_path = DEFAULT_REGISTRY_MANIFEST_PATH
         @skill_cache_dir = File.expand_path('~/.rails-ai-bridge/cache')
         @skill_packs = nil
         @local_registry_paths = []
         @resolver_ttl = 1800
         @git_pull_ttl = 86_400
         @git_timeout = 30
-        @lockfile_path = 'config/rails_ai_bridge/directory.lock'
+        @lockfile_path = DEFAULT_LOCKFILE_PATH
         @lockfile_verification = :strict
         @auto_load_dependencies = false
       end

data/lib/rails_ai_bridge/context_provider.rb

@@ -108,7 +108,7 @@ module RailsAiBridge
       end
 
       def cache_key(app)
-        app.object_id
+        "#{app.class.name}:#{defined?(Rails) && Rails.respond_to?(:env) ? Rails.env : 'development'}"
       end
 
       def metadata_key?(section_name)

data/lib/rails_ai_bridge/doctor/checkers/registry_checker.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module RailsAiBridge
+  class Doctor
+    module Checkers
+      # Verifies the registry manifest is present, valid, and resolvable.
+      #
+      # Checks (in order):
+      # 1. The configured +registry_manifest_path+ exists.
+      # 2. The manifest JSON parses successfully.
+      # 3. +RegistryManifest.validate!+ passes schema validation.
+      # 4. +Registry.build_resolver+ returns a non-nil resolver.
+      # 5. The lockfile exists and matches (when +lockfile_path+ is configured).
+      #
+      # Each failure short-circuits with an actionable fix hint so the user can
+      # resolve the first problem before chasing downstream symptoms.
+      class RegistryChecker < BaseChecker
+        # @return [Doctor::Check] +:pass+, +:warn+, or +:fail+
+        def call
+          return missing_manifest_check unless manifest_path_exists?
+
+          return invalid_json_check unless manifest_parses?
+
+          return validation_failed_check unless manifest_validates?
+
+          resolver = build_resolver
+          return resolver_failed_check(resolver) unless resolver
+
+          return lockfile_check if lockfile_configured? && !lockfile_exists?
+
+          new_check(name: 'Registry', status: :pass, message: 'Registry manifest is valid and resolvable', fix: nil)
+        end
+
+        private
+
+        def registry_config
+          RailsAiBridge.configuration.registry
+        end
+
+        def manifest_path
+          registry_config.registry_manifest_path
+        end
+
+        def manifest_path_exists?
+          File.exist?(manifest_path)
+        end
+
+        def missing_manifest_check
+          new_check(
+            name: 'Registry',
+            status: :warn,
+            message: "Registry manifest not found at `#{manifest_path}`",
+            fix: 'Create a registry manifest file — see docs/skill-registry-guide.md'
+          )
+        end
+
+        def manifest_parses?
+          parsed_manifest
+          true
+        rescue ArgumentError
+          false
+        end
+
+        def invalid_json_check
+          new_check(
+            name: 'Registry',
+            status: :fail,
+            message: "Registry manifest at `#{manifest_path}` contains invalid JSON or could not be read",
+            fix: "Fix the JSON syntax in the manifest file — run `ruby -rjson -e 'JSON.parse(File.read(ARGV[0]))' #{manifest_path}` to see the parse error"
+          )
+        end
+
+        def parsed_manifest
+          @parsed_manifest ||= RailsAiBridge::Registry::RegistryManifest.from_file(manifest_path)
+        end
+
+        def manifest_validates?
+          RailsAiBridge::Registry::RegistryManifest.validate!(raw_manifest_hash)
+          true
+        rescue RailsAiBridge::Registry::RegistryManifest::ValidationError
+          false
+        end
+
+        def raw_manifest_hash
+          JSON.parse(File.read(manifest_path))
+        end
+
+        def validation_failed_check
+          new_check(
+            name: 'Registry',
+            status: :fail,
+            message: "Registry manifest at `#{manifest_path}` failed schema validation",
+            fix: 'Check the manifest structure — see docs/skill-registry-guide.md for the expected schema'
+          )
+        end
+
+        def build_resolver
+          RailsAiBridge::Registry.build_resolver(registry_config)
+        end
+
+        def resolver_failed_check(resolver)
+          new_check(
+            name: 'Registry',
+            status: :warn,
+            message: "Registry manifest parsed but resolver returned nil#{resolver_reason(resolver)}",
+            fix: 'Check that all pack sources are reachable and git is available — see logs for details'
+          )
+        end
+
+        def resolver_reason(resolver)
+          return '' unless resolver.nil?
+
+          ' (manifest missing or pack sources could not be resolved)'
+        end
+
+        def lockfile_configured?
+          registry_config.lockfile_path
+        end
+
+        def lockfile_exists?
+          File.exist?(registry_config.lockfile_path)
+        end
+
+        def lockfile_check
+          new_check(
+            name: 'Registry',
+            status: :warn,
+            message: "Lockfile not found at `#{registry_config.lockfile_path}`",
+            fix: 'Run `rails ai:registry:lock` to generate the lockfile, or set lockfile_path to nil to disable verification'
+          )
+        end
+      end
+    end
+  end
+end