rails-ai-bridge 4.0.0 → 4.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a62e4a3003e8feb85f8ace7ec52c9ae89a2d0cd7c004673ca669cbacaf4fe665
-  data.tar.gz: cf85e1034658180a1530dde70fa4b2c724b9ad289451f216b6723f40e94f4bb7
+  metadata.gz: 24c9dd6461240b9d6864b35c171c465635f9fdacc3c76195915f43b995a27f18
+  data.tar.gz: e97756c625478c854f78f661393d26043ba36b07b8941bed7a2a2c09b3a62a4b
 SHA512:
-  metadata.gz: 95a1948e2f1ae02299f8b1505c83674f3172ea7da8fd384e17a9414c43ccee911a69e2f6713f320e8d520337c3cf8c343c082ad716ebb84d6128c64f4b2ceee9
-  data.tar.gz: f4c81faedfe64c9268c635409d049c9a2b128306bcc666a55d0ef2f6624775bb098f10378d16d4819c6163d48cd8da42ebbf973474cb24183e09280a27e3548d
+  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/.reek.yml

@@ -87,6 +87,7 @@ detectors:
     - RailsAiBridge::Serializers::RegenerationFooter
     - RailsAiBridge::Introspectors::SemanticIntrospector
     - RailsAiBridge::RubydexAdapter::IncrementalIndexer
+    - RailsAiBridge::Registry::RegistryManifest
   DuplicateMethodCall:
     exclude:
     - RailsAiBridge::Config::Introspection#excluded_table?
@@ -416,6 +417,7 @@ detectors:
     - RailsAiBridge::Tools::BaseTool
     - RailsAiBridge::Watcher::BridgeRegenerator
     - RailsAiBridge::Fingerprinter::CachedSnapshot
+    - RailsAiBridge::Registry::RegistryManifest
   NestedIterators:
     exclude:
     - RailsAiBridge::Fingerprinter#snapshot
@@ -495,6 +497,7 @@ detectors:
     - RailsAiBridge::Introspectors::TestIntrospector
     - RailsAiBridge::Introspectors::ViewIntrospector
     - RailsAiBridge::RubydexAdapter
+    - RailsAiBridge::Registry::RegistryManifest
     - RailsAiBridge::Tools::GetStimulus::ResponseFormatter
     - RailsAiBridge::Tools::SearchSemantic
   TooManyInstanceVariables:
@@ -502,6 +505,7 @@ detectors:
     - RailsAiBridge::Config::Introspection
     - RailsAiBridge::Config::Mcp
     - RailsAiBridge::Config::Output
+    - RailsAiBridge::Config::Registry
     - RailsAiBridge::Config::Rubydex
     - RailsAiBridge::Config::Server
     - RailsAiBridge::Configuration

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/` — 14 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,7 +5,48 @@ 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]
+## [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
+
+- **JWT authentication docs for the HTTP MCP transport** (#129) — `docs/mcp-security.md` now documents the `mcp_jwt_decoder` pattern with a worked `JWT.decode` example, the decoder return-value contract, and a token rotation strategy (short expiry, signing-key overlap windows, revocation guidance).
+- **`rails_use_skill` / `rails_use_agent` MCP tools** (#133) — resolve a skill or agent via `Registry::Resolver` and return it framed for immediate in-context application: an intent header, the deprecation notice when the name was redirected, the full content, and a follow-through footer. Use these to *act on* a skill; `rails_resolve_skill` remains the read-only inspection tool (with `pack=` pinning).
+- **JSON output for the registry rake tasks** (#128) — `rails "ai:skills:list[json]"` (or `FORMAT=json rails ai:skills:list`) prints a stable `{"packs": [...], "skills": [...]}` catalog document for CI and custom tooling. `RakePresenter` gains `skills_json`, `packs_json`, and `catalog_json`; the default table output is unchanged.
+- **Transitive `depends_on` loading for skill packs** (#126) — opt in with `config.registry.auto_load_dependencies = true` (default `false`): `PackResolver` expands declared pack dependencies transitively (fixed-point iteration capped at 10 levels) and warns about circular dependency chains while still loading every pack in the cycle. Dependencies missing from the manifest are left to the existing warning, which now points at the new flag.
+- **Structured logging for registry git operations** (#131) — `SkillSourceResolver` accepts an optional `logger:` (defaults to `Rails.logger`, or a stderr logger outside Rails). Clone, pull, and checkout operations log `key=value` lines: DEBUG before the operation, INFO with `duration_ms` on success, ERROR with the failure message before raising.
+- **Context provider definitions in the registry manifest** (#134) — new `Registry::ContextProviderDefinition` and `Registry::ContextToolSpec` value objects (ported from the Rust runtime) parse an optional `context_providers` section of the registry manifest: provider `type`/`endpoint`, optional flag, and tool lists supporting both simple names and `{ name, field, arguments }` mappings. `RegistryManifest#context_providers` defaults to `{}` — parsing is preparatory and nothing consumes these definitions yet.
+- **Manifest schema validation** (#123) — new `RegistryManifest.validate!` raises a descriptive `RegistryManifest::ValidationError` for the first invalid field (missing/empty pack `source`; wrong types for `version`, `default_stack`, `ref`, `tile`, `depends_on`, `always_loaded`, `priority`; non-object `packs` entries). New `rails ai:registry:validate` rake task validates the configured manifest for CI/pre-commit use and exits non-zero on failure.
+
+### Changed (breaking)
+
+- **Full SHA-256 digests for skill-pack cache keys** (#122) — `SkillSourceResolver.compute_cache_key` now appends the full 64-character SHA-256 hex digest instead of a 16-character truncation, consistent with the gem's fingerprinting. Cache directories created under the old key format are orphaned; clear `~/.rails-ai-bridge/cache` to reclaim disk space.
 
 ## [4.0.0] - 2026-08-09
 

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/` — 14 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/GEMINI.md

@@ -9,7 +9,7 @@ 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: `Introspector::BUILTIN_INTROSPECTORS` (includes opt-in symbols such as `database_stats`, `non_ar_models` not listed in those presets).
-- `lib/rails_ai_bridge/tools/` — 11 built-in MCP tools using the official mcp SDK (hosts can add more via `additional_tools`)
+- `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 (claude, claude_rules, cursor_rules, windsurf, windsurf_rules, copilot, copilot_instructions, rules, markdown, JSON, gemini)
 - `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)

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 **13 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,7 +267,11 @@ The gem exposes **13 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.
 
@@ -304,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
@@ -540,13 +544,14 @@ 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 |
 | `registry.resolver_ttl` | `1800` | Seconds to cache the wired resolver in memory; `0` disables caching |
 | `registry.git_pull_ttl` | `86400` | Seconds between `git pull` refreshes per cached pack (24 h default). Set to `0` to pull on every resolver rebuild |
 | `registry.git_timeout` | `30` | Seconds before a git operation (clone, pull, checkout) is forcibly interrupted |
+| `registry.auto_load_dependencies` | `false` | Load declared `depends_on` packs transitively; circular chains warn but still load |
 
 Other HTTP MCP knobs live only on the nested object, for example `RailsAiBridge.configuration.mcp.authorize`, `mcp.mode`, `mcp.security_profile`, and `mcp.require_auth_in_production` — see [docs/GUIDE.md](docs/GUIDE.md) and [docs/mcp-security.md](docs/mcp-security.md).
 </details>
@@ -682,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
 {
@@ -831,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 **3.6.2**). 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

@@ -0,0 +1,152 @@
+# Plan 2: Port Registry Resolution from Rust Runtime to rails-ai-bridge
+
+**Status:** Complete ✅ — implemented via PRs #40–#45
+**Priority:** After Plan 1
+**Estimated effort:** 4 weeks
+**Depends on:** Plan 1 (agent-mcp-runtime archived)
+
+> **Completion note (2026-08-10):** All success criteria shipped. See
+> [`port-registry-resolution.md`](port-registry-resolution.md) for as-built decisions and deltas, and
+> [`registry-resolution.md`](registry-resolution.md) for user-facing documentation. Naming deltas from
+> this plan: rake tasks shipped as `ai:skills:list` / `ai:skills:resolve[pack,name]` (planned:
+> `ai:list_skills` / `ai:resolve_skill`); configuration lives under `config.registry.*`
+> (`Config::Registry`); the MCP surface is the unified `rails_list_registry` tool plus
+> `rails_resolve_skill`; git operations use `Open3` (stdlib) — no `git` gem dependency.
+
+## Objective
+
+Port the registry resolution logic from `agent-mcp-runtime` (Rust) into `rails-ai-bridge` (Ruby). This enables the bridge to resolve skill packs from git repositories, handle priority-based loading, and support deprecation redirects — all necessary for the future skill compiler feature.
+
+## Components to Port
+
+### 1. New module: `lib/rails_ai_bridge/registry/`
+
+#### `lib/rails_ai_bridge/registry/manifest.rb`
+- Port `RegistryManifest` struct from Rust (version, packs, default_stack, context_providers)
+- Port `PackDefinition` struct (source, tile, always_loaded, depends_on)
+- Port `ContextProviderDefinition` and `ContextToolSpec` (for future context provider integration)
+- Use JSON parsing with `json` gem (already in rails-ai-bridge dependencies)
+
+#### `lib/rails_ai_bridge/registry/tile_manifest.rb`
+- Port `TileManifest` struct (name, version, summary, depends_on, skills, agents, deprecated_skills)
+- Port `SkillEntry` and `AgentEntry` structs
+- Port `DeprecatedEntry` struct (moved_to, message, removed_in)
+
+#### `lib/rails_ai_bridge/registry/git_source_resolver.rb`
+- Port `SkillSourceResolver` from Rust
+- Implement git clone/pull using `git` gem or shell commands
+- Cache directory: `~/.rails-ai-bridge/cache/` (instead of `~/.agent-mcp-runtime/cache/`)
+- Support local path resolution (sibling directories for development)
+- Implement `GitRunner` trait pattern with a default implementation and test mock
+
+#### `lib/rails_ai_bridge/registry/pack_detector.rb`
+- Port `PackDetector` from Rust
+- Parse Gemfile to detect Rails vs Hanami
+- Return array of detected frameworks
+
+#### `lib/rails_ai_bridge/registry/pack_resolver.rb`
+- Port `PackResolverService` logic
+- Implement priority-based pack loading:
+  - Priority 0: Local registries (--registry flag)
+  - Priority 10: Framework packs (rails, hanami)
+  - Priority 20: Core pack (always_loaded)
+  - Priority 30: Default stack (planning)
+- Handle explicit pack overrides
+- Load tile.json manifests from resolved sources
+- Return `RegistryResolver` instance
+
+#### `lib/rails_ai_bridge/registry/resolver.rb`
+- Port `RegistryResolver` from Rust
+- Implement `LoadedPack` struct (name, tile, base_path, priority)
+- Implement `ResolvedSkill` struct (name, pack, path, content)
+- Implement `SkillSummary` struct (name, pack, description)
+- Implement `resolve_skill(name)` with deprecation redirect handling
+- Implement `resolve_agent(name)`
+- Implement `list_skills()` with deduplication by priority
+- Implement `validate_dependencies()` to warn on missing dependencies
+- Sort packs by priority (ascending = higher priority)
+
+#### `lib/rails_ai_bridge/registry.rb`
+- Main registry module that requires all submodules
+- Public API entry point
+
+### 2. Integration with rails-ai-bridge
+
+**Add to `lib/rails_ai_bridge.rb`:**
+- Require the new registry module
+- Add convenience method `RailsAiBridge.resolve_skill(pack_name, skill_name)`
+- Add convenience method `RailsAiBridge.list_skills()`
+
+**Create new Rake task: `lib/rails_ai_bridge/tasks/registry.rake`**
+
+```ruby
+namespace :rails_ai_bridge do
+  desc "List all available skills from configured packs"
+  task list_skills: :environment do
+    # Use registry resolver to list skills
+  end
+
+  desc "Resolve a specific skill"
+  task :resolve_skill, [:pack, :skill] => :environment do |t, args|
+    # Resolve and print skill content
+  end
+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`)
+- `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)
+
+### 4. Tests
+
+**Create spec directory: `spec/rails_ai_bridge/registry/`**
+- `manifest_spec.rb`
+- `tile_manifest_spec.rb`
+- `git_source_resolver_spec.rb` (with mock git runner)
+- `pack_detector_spec.rb`
+- `pack_resolver_spec.rb`
+- `resolver_spec.rb`
+
+Use the Rust tests in `agent-mcp-runtime/src/registry/pack_resolver.rs` and `resolver.rs` as reference for test cases.
+
+### 5. Documentation
+
+**Create `docs/registry-resolution.md`** inside rails-ai-bridge:
+- Explain the registry resolution system
+- Document priority rules
+- Provide example registry.json configuration
+- Document configuration options
+
+### 6. Dependencies
+
+Add to `rails-ai-bridge.gemspec` if not already present:
+- `git` gem (for git operations) — check if already present
+- Ensure `json` gem is available (standard library in Ruby 3+)
+
+## Implementation Order
+
+1. **Week 1:** Create manifest and tile_manifest structs with tests; create git_source_resolver with mock for tests
+2. **Week 2:** Create pack_detector and pack_resolver with tests
+3. **Week 3:** Create resolver with tests; integrate with rails-ai-bridge main module
+4. **Week 4:** Add Rake tasks, configuration, and documentation
+
+## Notes
+
+- The existing `ruby-skill-bench` has a `PackResolver` class that does similar work. Review it for patterns but don't directly copy — the bridge version needs git resolution and priority handling that the bench version lacks.
+- The Rust runtime uses async/await. Ruby doesn't have this — use synchronous git operations.
+- Cache directory should be `~/.rails-ai-bridge/cache/` to avoid conflicts with the archived runtime.
+- Framework detection: just check Gemfile for `'rails'` or `'hanami'` gems.
+- Deprecation handling is critical for the skill migration from `rails-agent-skills` to `ruby-core-skills` already in progress.
+
+## Success Criteria
+
+- [x] All 6 registry modules created with passing specs (323 registry/config/tool examples green, 2026-08-10)
+- [x] `rails ai:skills:list` Rake task works (shipped name; planned as `ai:list_skills`)
+- [x] `rails "ai:skills:resolve[pack,name]"` Rake task works (shipped name; planned as `ai:resolve_skill[pack,name]`)
+- [x] Documentation written (`docs/registry-resolution.md`)
+- [x] Priority-based resolution handles core/rails/hanami/planning correctly
+- [x] Deprecation redirects work (e.g., old skill name → new location)

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/mcp-security.md

@@ -12,6 +12,59 @@ By default, HTTP MCP allows anonymous access when no auth strategy is configured
 
 In non-production environments, the standalone HTTP MCP server prints a one-time stderr warning when it starts without authentication to make the default behavior visible.
 
+## JWT authentication with short-lived tokens
+
+`http_mcp_token` is a static bearer token: rotating it means redistributing a secret to every client. For deployments that need rotation or expiry, configure `config.mcp_jwt_decoder` instead — the highest-priority auth strategy. The gem carries **no JWT dependency**: you supply a lambda that decodes (and verifies) the token.
+
+```ruby
+# config/initializers/rails_ai_bridge.rb
+require "jwt" # the host app's own jwt gem
+
+RailsAiBridge.configure do |config|
+  config.mcp.require_http_auth = true
+
+  config.mcp_jwt_decoder = ->(token) do
+    payload, _header = JWT.decode(
+      token,
+      Rails.application.credentials.jwt_mcp_secret!,
+      true,                          # verify signature
+      algorithm: "HS256",
+      verify_expiration: true        # reject expired tokens (default when verifying)
+    )
+    payload                          # truthy payload => authenticated
+  rescue JWT::DecodeError, JWT::ExpiredSignature
+    nil                              # nil => 401 unauthorized
+  end
+end
+```
+
+Decoder contract:
+
+- Return a **truthy payload** (Hash recommended) — request is authenticated; the payload is exposed to authorization hooks.
+- Return **`nil`** or **`false`** — request is rejected with `401` (`:unauthorized`).
+- **Raise** — treated as `:decode_error`, also `401`; the exception never propagates.
+
+### Token rotation strategy
+
+- **Short expiry, frequent re-issue.** Issue MCP tokens with a 5–15 minute `exp` from your existing login/session flow. A leaked token expires on its own; there is nothing to rotate per incident.
+- **Signing-key rotation.** When rotating the HMAC secret (or moving to RS256/JWKS), accept both keys during the overlap window:
+
+  ```ruby
+  config.mcp_jwt_decoder = ->(token) do
+    keys = [Rails.application.credentials.jwt_mcp_secret!,
+            Rails.application.credentials.jwt_mcp_secret_previous!]
+    keys.lazy.filter_map do |key|
+      JWT.decode(token, key, true, algorithm: "HS256").first
+    rescue JWT::DecodeError, JWT::ExpiredSignature
+      nil
+    end.first
+  end
+  ```
+
+  Retire the previous key once all clients have re-issued tokens.
+- **Immediate revocation.** Stateless JWTs cannot be revoked; if you need it, combine short `exp` with your own denylist check inside the decoder (return `nil` for revoked subjects).
+- **Client capability note.** Some AI hosts cannot refresh tokens and work best with a long-lived static token or `mcp_token_resolver` (which can consult a secret manager per request). Pick the strategy per client: JWT for short-lived machine-to-machine auth, `mcp_token_resolver` when the credential lives in a vault, `http_mcp_token` only for local development.
+
 ## Rate limiting and proxies
 
 Built-in rate limiting keys off the Rack request IP. Behind reverse proxies, configure Rails `trusted_proxies` so `request.ip` reflects the real client; otherwise limits may apply to the wrong address or be bypassed.

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) |
@@ -200,9 +200,10 @@ Once a registry manifest is configured:
 
 | Task | Description |
 |------|-------------|
-| `rails ai:skills:list` | Print skill catalog to stdout |
+| `rails ai:skills:list` | Print skill catalog to stdout; `[json]` argument (or `FORMAT=json`) prints a `{"packs": [...], "skills": [...]}` document |
 | `rails "ai:skills:resolve[pack,skill_name]"` | Resolve and print a skill's full content |
 | `rails ai:skills:clear_cache` | Remove all cached pack git repositories and invalidate the resolver cache |
+| `rails ai:registry:validate` | Validate the registry manifest schema; exits non-zero on the first invalid field |
 
 Examples: