rails-ai-bridge 4.0.0 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a62e4a3003e8feb85f8ace7ec52c9ae89a2d0cd7c004673ca669cbacaf4fe665
-  data.tar.gz: cf85e1034658180a1530dde70fa4b2c724b9ad289451f216b6723f40e94f4bb7
+  metadata.gz: 2f7810f4efa4400b60d813b2344b82f38e0a731ccc89e68a3be51aabe2526a3d
+  data.tar.gz: 7faa7fe7f2f731d572806596a3f60d756d85b589ba46b6dfa7ef2e614bea8749
 SHA512:
-  metadata.gz: 95a1948e2f1ae02299f8b1505c83674f3172ea7da8fd384e17a9414c43ccee911a69e2f6713f320e8d520337c3cf8c343c082ad716ebb84d6128c64f4b2ceee9
-  data.tar.gz: f4c81faedfe64c9268c635409d049c9a2b128306bcc666a55d0ef2f6624775bb098f10378d16d4819c6163d48cd8da42ebbf973474cb24183e09280a27e3548d
+  metadata.gz: 1d4cf0bdcf2dcf203a30b112ac940709dcf3222af18efaeb10625d08594197f38d49cfb23f5edc328fce6a4fd6242b02aa545cb6075c5c142ab81b3a5b89d1d5
+  data.tar.gz: 2f7dad1ecef89cc739b7a8031f16e753b0b4a55bdabbc52f8692f6b42f05f0cf7a14acc80700d819f401649eb384fc7109d98569372462f651eee2ea608d7767

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/AGENTS.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/` — 14 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 (Codex, claude_rules, cursor_rules, devin, devin_rules, copilot, copilot_instructions, 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)

data/CHANGELOG.md

@@ -5,7 +5,21 @@ 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.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

@@ -12,7 +12,7 @@ structure to AI assistants via the Model Context Protocol (MCP).
   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
+- `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, devin, devin_rules, copilot, copilot_instructions, rules,

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

@@ -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 **16 built-in tools** via MCP that AI clients call on-demand (hosts can append more via `config.additional_tools`):
 
 | Tool | What it returns |
 |------|----------------|
@@ -268,6 +268,9 @@ The gem exposes **13 built-in tools** via MCP that AI clients call on-demand (ho
 | `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_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) |
 
 All tools are **read-only** — they never modify your application or database.
 
@@ -547,6 +550,7 @@ end
 | `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>
@@ -831,7 +835,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.1.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/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/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/registry-resolution.md

@@ -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:
 

data/docs/skill-registry-guide.md

@@ -47,6 +47,31 @@ Create `config/rails_ai_bridge_registry.json` in your Rails app:
 
 The `source` field is a GitHub `owner/repo` shorthand. The `tile` field is optional — it defaults to `directory.json` at the root of the pack.
 
+#### Context providers (parsed, not yet consumed)
+
+An optional `context_providers` section can declare external context services. The bridge parses it into `Registry::ContextProviderDefinition` / `Registry::ContextToolSpec` value objects, but no integration consumes these definitions yet — this is preparatory for future context provider support.
+
+```json
+{
+  "version": "1.0.0",
+  "packs": {},
+  "default_stack": [],
+  "context_providers": {
+    "app_mcp": {
+      "type": "mcp",
+      "endpoint": "http://localhost:3000/mcp",
+      "optional": true,
+      "tools": [
+        "rails_get_schema",
+        { "name": "rails_get_model_details", "field": "models", "arguments": { "model": "User" } }
+      ]
+    }
+  }
+}
+```
+
+Each tool entry is either a simple tool-name string or a mapped object with `name`, `field`, and optional `arguments`.
+
 ### Step 2 — Configure the bridge
 
 In `config/initializers/rails_ai_bridge.rb`:
@@ -268,6 +293,15 @@ rails_list_registry type=packs
 
 Returns all loaded packs with name, version, priority, and summary. Use this to confirm which packs are active and what their priorities are.
 
+### Apply a skill or agent in-context
+
+```bash
+rails_use_skill name=code-review
+rails_use_agent name=tdd-workflow
+```
+
+Resolves the named skill/agent (priority ordering and deprecation redirects included) and returns it framed as a directive the assistant should **execute**, not just read: an intent header, any deprecation notice, the full content, and a follow-through footer. Use `rails_resolve_skill` instead when you only want to inspect content or pin a pack (`pack=`, `type=`).
+
 ---
 
 ## Rake task reference
@@ -280,6 +314,15 @@ rails ai:skills:list
 
 Prints a skills table to stdout with skill name, pack, and truncated description. Good for quickly checking what is loaded.
 
+For machine-readable output (CI, custom tooling), request JSON:
+
+```bash
+rails "ai:skills:list[json]"
+FORMAT=json rails ai:skills:list   # same via env var
+```
+
+The JSON document is `{ "packs": [...], "skills": [...] }` with pack summaries (`name`, `version`, `summary`, `priority`) and skill summaries (`name`, `pack`, `description`).
+
 ### Resolve a skill
 
 ```bash
@@ -305,6 +348,30 @@ Removes all locally cached pack repositories from the skill cache directory and
 - You want to free disk space
 - You changed the `skill_cache_dir` configuration
 
+### Validate the manifest
+
+```bash
+rails ai:registry:validate
+```
+
+Checks the registry manifest at `config.registry.registry_manifest_path` against the expected schema: pack `source` must be a non-empty string, `depends_on` an array of strings, `always_loaded` a boolean, and so on. Exits non-zero on the first invalid field, making it suitable for CI and pre-commit hooks.
+
+---
+
+## Transitive dependency loading (`auto_load_dependencies`)
+
+By default, a pack's `depends_on` entries are **not** loaded automatically — the resolver only warns when a dependency is missing from the active set. Enable transitive loading to have declared dependencies pulled in automatically:
+
+```ruby
+RailsAiBridge.configure do |config|
+  config.registry.auto_load_dependencies = true
+end
+```
+
+- Expansion is iterative (dependencies of dependencies), capped at 10 levels.
+- Only dependencies defined in the manifest are loaded; undefined ones still produce the missing-dependency warning.
+- Circular chains are detected and reported as a stderr warning (`Circular dependency detected: a -> b -> a`), but every pack in the cycle is still loaded.
+
 ---
 
 ## Git operation settings
@@ -381,7 +448,8 @@ initializer changes take effect immediately.
 | `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 |
 | 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 |
+| 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 |
 
 ---
 

data/lib/rails_ai_bridge/config/registry.rb

@@ -42,6 +42,10 @@ module RailsAiBridge
       #   :strict (default) raises, :warn logs but proceeds, :disabled skips verification.
       attr_accessor :lockfile_verification
 
+      # @return [Boolean] whether declared +depends_on+ packs are loaded transitively
+      #   (default: false — dependencies must be listed explicitly and missing ones only warn)
+      attr_accessor :auto_load_dependencies
+
       # Sets the git pull TTL.
       #
       # Coerces the value to a non-negative integer; raises +ArgumentError+ for
@@ -102,6 +106,7 @@ module RailsAiBridge
         @git_timeout = 30
         @lockfile_path = 'config/rails_ai_bridge/directory.lock'
         @lockfile_verification = :strict
+        @auto_load_dependencies = false
       end
     end
   end

data/lib/rails_ai_bridge/registry/context_provider_definition.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module RailsAiBridge
+  module Registry
+    # Immutable value object describing a context provider service declared in the
+    # registry manifest.
+    #
+    # Context providers are external services (currently MCP servers) that the
+    # bridge can query for project context. This definition is preparatory — the
+    # data structures mirror the Rust runtime's manifest format, but no
+    # integration consumes them yet.
+    #
+    # @!attribute [r] type
+    #   @return [String] provider type, e.g. "mcp"
+    # @!attribute [r] endpoint
+    #   @return [String] provider HTTP endpoint base URL
+    # @!attribute [r] optional
+    #   @return [Boolean] whether the provider may be skipped when unavailable
+    # @!attribute [r] tools
+    #   @return [Array<ContextToolSpec>] tools requested from the provider
+    ContextProviderDefinition = Data.define(:type, :endpoint, :optional, :tools) do
+      # Builds a {ContextProviderDefinition} from a parsed JSON hash.
+      #
+      # @param hash [Hash] parsed JSON object
+      # @return [ContextProviderDefinition]
+      # @raise [ArgumentError] when a required field is missing
+      def self.from_json(hash)
+        new(
+          type: hash.fetch('type'),
+          endpoint: hash.fetch('endpoint'),
+          optional: hash.fetch('optional', false),
+          tools: (hash['tools'] || []).map { |tool| ContextToolSpec.from_json(tool) }
+        )
+      rescue KeyError => error
+        raise ArgumentError, "Context provider definition missing required field: #{error.key}"
+      end
+
+      # @return [Boolean]
+      def optional? = optional
+    end
+  end
+end

data/lib/rails_ai_bridge/registry/context_tool_spec.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module RailsAiBridge
+  module Registry
+    # Immutable value object describing a single tool requested from a context provider.
+    #
+    # Mirrors the untagged +ContextToolSpec+ enum in the Rust runtime: a spec is
+    # either a plain tool name (simple) or a mapping that routes the tool output
+    # into a named context field, optionally with arguments (mapped).
+    #
+    # @!attribute [r] name
+    #   @return [String] name of the remote tool to execute
+    # @!attribute [r] field
+    #   @return [String, nil] target context field for mapped tools; nil for simple tools
+    # @!attribute [r] arguments
+    #   @return [Hash, nil] optional arguments passed when executing the tool
+    ContextToolSpec = Data.define(:name, :field, :arguments) do
+      # Builds a {ContextToolSpec} from a parsed JSON value.
+      #
+      # @param value [String, Hash] plain tool name or mapped tool object
+      # @return [ContextToolSpec]
+      # @raise [ArgumentError] when the value is neither a String nor a Hash,
+      #   or a mapped tool is missing a required field
+      def self.from_json(value)
+        return new(name: value, field: nil, arguments: nil) if value.is_a?(String)
+        return from_mapped_json(value) if value.is_a?(Hash)
+
+        raise ArgumentError, "Context tool spec must be a String or an object, got #{value.class.name}"
+      end
+
+      # @return [Boolean] true when the spec is a plain tool name
+      # :reek:NilCheck -- value-object predicate over an optional attribute
+      def simple? = field.nil?
+
+      # @return [Boolean] true when the spec maps tool output into a context field
+      # :reek:NilCheck -- value-object predicate over an optional attribute
+      def mapped? = !field.nil?
+
+      # @api private
+      def self.from_mapped_json(hash)
+        new(
+          name: hash.fetch('name'),
+          field: hash.fetch('field'),
+          arguments: hash['arguments']
+        )
+      rescue KeyError => error
+        raise ArgumentError, "Context tool spec missing required field: #{error.key}"
+      end
+
+      private_class_method :from_mapped_json
+    end
+  end
+end