rails-ai-bridge 3.4.0 → 3.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 40f60ba64b6bd873a3cd1ebd9935e0c1b8250b9a8311135201bac1b66611f533
-  data.tar.gz: '08046f7af401786ad68cb95daaad9647eb2fec306b2dfb0a4b89987ccf8d081f'
+  metadata.gz: c78af79aba88ce31b9ea2d0f0c2de1e14782f5a0d2fbc9ccae9a879c86020ad8
+  data.tar.gz: 736de35b4fa3413752e77b3ebc37abf5628c697c7855561985031d7a06b53783
 SHA512:
-  metadata.gz: 4ecb06105c4587df9114b465c8db3c88b462182b6462e1f07f841e92093693edeb52720b1fce378191323e38054412fa7637cc6198b91b371911396ebbf2f967
-  data.tar.gz: 65ac9a5d50ccf9f89535eaab7e229c90b685f35ef35a85b5edc4afb23047ac22f6ce1bc90398a4c682f99d19611a6678ba24935fccdffdb27af0c49c63265b49
+  metadata.gz: f7204bde6b731db642cedb0d3748e413f3c8f6496633328f1450412fdce6aa1127ca7fbaef443b061068f8d66177c5878f35e72a4bd75b21f8ec20f496e6c261
+  data.tar.gz: 93f710a0ceeba7a6b55fe6323b22ae1b980424ac301877b13a9d8e2f8e63a064500e5db86db30330b7347649f2774ca9d0655e82704008d568fe4e858e2b33b2

data/.reek.yml

@@ -459,6 +459,7 @@ detectors:
     - RailsAiBridge::Tools::SearchSemantic#self.format_results
   NilCheck:
     exclude:
+    - RailsAiBridge::Registry::DeprecatedEntry#removed_in?
     - RailsAiBridge::AssistantFormatsPreference#formats_for_default_bridge_task
     - RailsAiBridge::Config::Introspection#excluded_table?
     - RailsAiBridge::RubydexAdapter#sanitize_index_path
@@ -523,6 +524,7 @@ detectors:
     - RailsAiBridge::Server
   TooManyStatements:
     exclude:
+    - RailsAiBridge::Registry::FrontmatterParser#self.extract_frontmatter_lines
     - RailsAiBridge#validate_auto_mount_configuration!
     - RailsAiBridge::AssistantFormatsPreference#formats_for_default_bridge_task
     - RailsAiBridge::AssistantFormatsPreference#write!

data/AGENTS.md

@@ -9,8 +9,8 @@ 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/serializers/` — Output formatters (Codex, claude_rules, cursor_rules, windsurf, windsurf_rules, copilot, copilot_instructions, rules, markdown, JSON)
+- `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/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
@@ -33,7 +33,7 @@ structure to AI assistants via the Model Context Protocol (MCP).
 9. **Introspector presets** — `:standard` (9 core) default, `:full` (26 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/`, `.windsurf/rules/`, `.github/instructions/`
+12. **Per-tool split rules** — `.Codex/rules/`, `.cursor/rules/`, `.devin/rules/`, `.github/instructions/`
 
 ## Testing
 

data/CHANGELOG.md

@@ -5,6 +5,161 @@ 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]
+
+### Added
+
+- **`git_timeout` for git operations** — `Config::Registry#git_timeout` (default `30` seconds) is
+  now passed to `DefaultGitRunner`, which wraps every git subprocess (`clone`, `pull`, `checkout`)
+  in `Timeout.timeout`. A slow or unreachable remote can no longer block the calling thread
+  indefinitely; a descriptive `RuntimeError` (e.g. `"git clone timed out after 30s"`) is raised
+  instead. `DefaultGitRunner#timeout` exposes the configured value for introspection.
+- **`git_pull_ttl` — per-pack pull freshness window** — `Config::Registry#git_pull_ttl` (default
+  `86400` seconds = 24 h) controls how often `SkillSourceResolver` issues a `git pull` for an
+  already-cached pack. Successive `resolve` calls within the TTL window skip the pull entirely,
+  removing the previous behaviour of pulling on every resolver rebuild. Set to `0` to restore
+  pull-on-every-resolve. Pull timestamps are tracked in a thread-safe, in-memory `Mutex`-guarded
+  hash; they reset when the process restarts.
+- **`checkout_ref` timeout** — `git checkout <ref>` is now also subject to `git_timeout`.
+  A `SkillSourceResolver::ResolutionError` is raised on timeout with the ref name and pack source
+  in the message.
+- **`Registry::Truncatable` shared module** (`lib/rails_ai_bridge/registry/truncatable.rb`) —
+  extracts the `truncate(text, max)` helper that was duplicated between `RakePresenter` and
+  `RegistryCatalogFormatter`. Both classes now `include Truncatable` and the private duplicates
+  are removed.
+- **`Engine.to_prepare` hook** — the Rails Engine now registers a `config.to_prepare` block that
+  calls `Registry.invalidate_resolver_cache!`. This discards the cached resolver on every
+  Zeitwerk code reload in development, preventing stale config after an initializer change.
+  In production it fires once after eager load and is effectively a no-op.
+- **`depends_on` missing-dependency warning** — `PackResolver` now emits a clear `[rails-ai-bridge]`
+  warning to stderr when an active pack declares `depends_on` entries that are not in the active
+  pack set. The warning names each missing dependency and tells the user which manifest field to
+  update. Packs still load; this is an advisory warning, not an abort. Transitive dependency
+  loading remains unimplemented (see `docs/gem-general-improvements.md`).
+- **Stable local pack names** — local registry packs previously received names like `local_0`,
+  `local_1` based on array index, so reordering `local_registry_paths` silently shifted pack
+  identities. Names are now derived from a SHA256 digest of the path
+  (`local_<first 8 hex chars>`), making them stable regardless of ordering.
+- **`docs/offline-mode.md`** — design plan for a future `offline:` config flag that prevents
+  all git operations and serves the local cache as-is; includes rake pull task design, vendored
+  snapshot pattern, and CI caching guidance.
+- **`docs/gem-general-improvements.md`** — roadmap of eight broader improvements: manifest
+  schema validation, pack version lock file, agent-facing JSON output from rake tasks, full
+  SHA-256 cache keys, transitive `depends_on` loading, structured logging, and more.
+
+### Changed
+
+- **`PackResolver` errors raised as `ResolutionError`** — the two bare `raise "..."` calls in
+  `PackResolver` (unknown pack name, missing tile manifest) and the one in `load_local_registries`
+  now raise `SkillSourceResolver::ResolutionError` instead of a plain `RuntimeError`. Callers
+  that rescue `ResolutionError` from `SkillSourceResolver` will now also catch pack-level failures
+  without needing a separate `rescue RuntimeError`.
+- **`SourceParser` rejects `http://` URLs** — plain HTTP was previously accepted as a git source.
+  It is now rejected because cloning over unencrypted HTTP exposes credentials and pack content in
+  transit. Use `https://` or `git@` (SSH) instead. The error message and module docstring are
+  updated to explain the reason and list the supported formats.
+- **`ListRegistry` type-guard comment** — the `unless %w[skills agents packs].include?(type)`
+  guard is retained as a defence-in-depth fallback (the MCP SDK enum constraint catches invalid
+  values first) and now carries an explanatory comment to prevent future confusion.
+- **`Registry.build_resolver_uncached`** — wires `git_timeout` and `git_pull_ttl` from
+  `Config::Registry` into `DefaultGitRunner` and `SkillSourceResolver` respectively, so
+  configuration changes take effect on the next resolver rebuild.
+
+### Fixed
+
+- **`validate_cache_dir` documentation clarified** — the YARD docstring now explains why the
+  lexical `Pathname#cleanpath` check (rather than `File.realpath`) is used: the cache directory
+  may not exist yet at validation time. The security guarantee is stated explicitly: cache keys
+  are SHA256-derived and not attacker-controlled, so even an unexpected symlink target is safe.
+
+### Tests
+
+- **`checkout_ref` — 8 new examples** covering: successful checkout returns the cache path;
+  git checkout called with the correct ref; non-zero exit raises `ResolutionError`; error message
+  includes ref name, source pack name, and stderr text; timeout raises `ResolutionError` with
+  `"timed out"` and ref name in message; nil ref skips `git checkout` entirely.
+- **Pull freshness — 3 new examples**: TTL=0 always pulls on every resolve; large TTL skips
+  the second pull within the window; second resolve after TTL expiry re-pulls (verified by
+  backdating `@last_pulled` via instance variable access).
+- **`DefaultGitRunner` timeout — 4 new examples**: `#timeout` defaults to 30; configurable
+  via constructor; clone timeout raises `RuntimeError` with duration; pull timeout same.
+- **`ResolverCache` TTL spec** — replaced `sleep(0.01)` (wall-clock dependency) with an
+  injectable `monotonic_clock:` lambda that returns `0` on the first call and `99_999` thereafter,
+  making the TTL-expiry test deterministic and instant.
+- **Total: 2043 examples, 0 failures, 94.67% line coverage** (up from 94.53%)
+
+- **Registry data structures (PR 1)** — new `RailsAiBridge::Registry` module with immutable value objects
+  porting the Rust `agent-mcp-runtime` registry types to Ruby:
+  - `Registry::RegistryManifest` — root manifest (version, packs, default\_stack); `from_json` / `from_file`
+  - `Registry::PackDefinition` — single pack descriptor (source, tile, always\_loaded, depends\_on)
+  - `Registry::TileManifest` — pack skill/agent catalog; `from_json` / `from_file`
+  - `Registry::SkillEntry`, `Registry::AgentEntry` — metadata entries for skills and agents
+  - `Registry::DeprecatedEntry` — deprecation redirect (moved\_to, message, removed\_in)
+  - `Registry::FrontmatterParser` — internal YAML frontmatter extractor for skill markdown files;
+    used when a `SkillEntry` carries no description in `tile.json`
+- **Git source resolver + pack detector (PR 2)** — git repository caching and framework auto-detection:
+  - `Registry::GitRunner` — module interface for git operations (injectable for tests)
+  - `Registry::DefaultGitRunner` — Open3-based implementation using stdlib git commands
+  - `Registry::SkillSourceResolver` — resolves remote git sources to local cache directories;
+    clones if missing, pulls if cached; cache dir defaults to `~/.rails-ai-bridge/cache/`
+    (env override: `RAILS_AI_BRIDGE_CACHE_DIR`); cache key uses sanitized source + SHA256 hash
+  - `Registry::DetectedFramework` — enum-like value object (Rails, Hanami)
+  - `Registry::PackDetector` — detects Rails/Hanami frameworks from Gemfile content;
+    supports single/double quotes, version constraints, ignores commented lines
+- **Pack resolver + registry resolver (PR 3)** — priority-based pack loading and skill/agent resolution:
+  - `Registry::PackResolver` — service object that resolves and loads skill packs from the registry manifest;
+    handles always\_loaded packs, explicit pack selection, framework auto-detection, and local registry overrides;
+    returns a `Registry::Resolver` with all packs loaded and prioritized
+  - `Registry::Resolver` — core resolver that aggregates active packs and resolves queries;
+    provides priority-based resolution of skills and agents, handles deprecation redirects,
+    validates dependencies, and guards against path traversal attacks
+  - `Registry::LoadedPack` — value object representing a loaded pack (name, tile, base\_path, priority)
+  - `Registry::ResolvedSkill` — value object representing a resolved skill/agent (name, pack, path, content)
+  - `Registry::SkillSummary` — value object for skill/agent catalogs (name, pack, description)
+  - Priority assignment: local=0, rails/hanami=10, core=20, other=30 (lower is higher priority)
+  - Path traversal guard using canonical path comparison to prevent directory escape attacks
+  - Dependency validation with warnings for unsatisfied pack dependencies
+- **Registry configuration (PR 4)** — configuration object for registry resolution:
+  - `Config::Registry` — configuration sub-object for registry resolution settings
+  - `registry.registry_manifest_path` — path to registry manifest JSON (default: `config/rails_ai_bridge_registry.json`)
+  - `registry.skill_cache_dir` — directory for caching git repositories (default: `~/.rails-ai-bridge/cache`)
+  - `registry.skill_packs` — explicit pack names to load, or `nil` for auto-detection based on framework
+  - `registry.local_registry_paths` — local registry directory paths for skill pack overrides
+  - Registry module required in main `rails_ai_bridge.rb` for configuration availability
+- **Registry tools, cache, source formats, and docs (PR 5 → PR 6)** — user-visible entry points
+  plus three production-quality refinements:
+  - `Tools::ListRegistry` (`rails_list_registry`) — single MCP tool replacing the previous
+    `rails_list_skills`, `rails_list_agents`, and `rails_list_packs`; required `type:` param
+    (`"skills"` | `"agents"` | `"packs"`); optional `pack:` filter for skills/agents;
+    inner `RegistryCatalogFormatter` class owns all markdown rendering (SRP)
+  - `Registry::ResolverCache` — thread-safe in-memory cache for the wired `Resolver`;
+    configurable TTL via `config.registry.resolver_ttl` (default 1800 s = 30 min);
+    nil results never cached so manifest-missing setup retries on next call;
+    `Registry.invalidate_resolver_cache!` for explicit invalidation
+  - `Config::Registry#resolver_ttl` — new accessor with 1800 s default
+  - `Registry::SourceParser` — new single-responsibility parser that classifies source strings
+    into `:local_path`, `:git_url`, or `:github_shorthand` and resolves canonical URLs;
+    raises `ResolutionError` naming all three valid formats for invalid inputs;
+    `SkillSourceResolver#resolve` now delegates to `SourceParser` and returns local paths
+    directly without git operations
+  - `PackDefinition#ref` — new optional field for git version pinning (branch, tag, or SHA);
+    `SkillSourceResolver` runs `git checkout ref` after clone/pull when set
+  - `PackResolver` — default pack catalog filename changed from `tile.json` to `directory.json`;
+    priority matching is now case-insensitive
+  - `Registry::RakePresenter` — extracted from inline rake task logic; owns all CLI formatting
+    for skill tables and resolve output
+  - `rails ai:skills:list` — delegates to `RakePresenter`
+  - `rails "ai:skills:resolve[pack,skill_name]"` — delegates to `RakePresenter`
+  - `rails ai:skills:clear_cache` — new rake task; removes cached pack repositories and
+    invalidates the in-memory resolver cache
+  - `docs/skill-registry-guide.md` — new user guide covering concepts, quick start, source
+    formats, priority rules, version pinning, `directory.json` format, MCP tool reference,
+    rake task reference, resolver cache, troubleshooting, and security model
+  - `docs/registry-resolution.md` — updated to "Registry Resolution Reference"; all
+    `tile.json` references updated to `directory.json`; new source formats table; new
+    `ref` field; `resolver_ttl` config option; cache management section; security section
+    updated for `SourceParser`
+
 ## [3.4.0] - 2026-05-21
 
 ### Added

data/CLAUDE.md

@@ -12,10 +12,10 @@ 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/` — 11 built-in MCP tools using the official mcp SDK
+- `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 (claude, claude_rules,
-  cursor_rules, windsurf, windsurf_rules, copilot, copilot_instructions, 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)
@@ -39,7 +39,7 @@ structure to AI assistants via the Model Context Protocol (MCP).
 9. **Introspector presets** — `:standard` (9 core) default, `:full` (26 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/`, `.windsurf/rules/`, `.github/instructions/`
+12. **Per-tool split rules** — `.claude/rules/`, `.cursor/rules/`, `.devin/rules/`, `.github/instructions/`
 
 ## Testing
 

data/README.md

@@ -21,7 +21,7 @@ rails-ai-bridge turns a Rails app into an AI-readable project map:
 
 - **Static context files** give assistants an immediate overview of your app, conventions, schema shape, routes, and important models.
 - **A read-only MCP server** lets assistants ask for exact details only when needed, such as one model, one table, one controller, or one route group.
-- **Assistant-specific output** keeps Claude Code, Cursor, Codex, Copilot, Windsurf, Gemini, and JSON consumers aligned without making you hand-write context files.
+- **Assistant-specific output** keeps Claude Code, Cursor, Codex, Copilot, Devin, Gemini, and JSON consumers aligned without making you hand-write context files.
 
 The goal is simple: help AI assistants produce code that fits your Rails app instead of generic Rails code.
 
@@ -33,9 +33,12 @@ Use the README as the shortest path to understanding and setup. Jump to deeper d
 |---|---|
 | Understand the idea in 3 minutes | [How it works](#how-it-works) |
 | Install and generate files | [Quick start](#quick-start) |
+| Connect Claude Code or Cursor | [Connect your AI client — Claude Code](#claude-code) |
+| Connect Devin | [Connect your AI client — Devin](#devin) and [docs/devin-setup.md](docs/devin-setup.md) |
+| Connect Copilot / Codex / Gemini | [Connect your AI client](#connect-your-ai-client) |
 | Check what the AI learns | [What Your AI Learns](#what-your-ai-learns) |
 | Choose `:standard`, `:full`, or opt-ins | [Pick the right preset for your app](#pick-the-right-preset-for-your-app) |
-| Use MCP safely | [MCP Server Setup](#mcp-server-setup) and [mcp-security.md](docs/mcp-security.md) |
+| Use MCP safely | [HTTP transport](#http-transport-alternative-for-all-clients) and [mcp-security.md](docs/mcp-security.md) |
 | Improve day-to-day AI results | [Best Practices](docs/BEST_PRACTICES.md) |
 
 ## When this helps
@@ -123,7 +126,7 @@ The generator prompts you to pick a profile (or pass `--profile` to skip the pro
 | Profile | What it generates | Split rule dirs |
 |---------|-------------------|-----------------|
 | `custom` *(default)* | Per-format prompts — pick exactly what you need | Yes |
-| `minimal` | Claude, Cursor, Windsurf, Copilot, Gemini shims | No |
+| `minimal` | Claude, Cursor, Devin, Copilot, Gemini shims | No |
 | `full` | Every format | Yes |
 | `mcp` | Only `.mcp.json` — generate files later with `rails ai:bridge` | — |
 
@@ -155,7 +158,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 — 11 read-only `rails_*` tools (extensible) | Yes | No |
+| Live MCP tools | Yes — 13 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.*
@@ -191,9 +194,9 @@ your-rails-app/
 │       ├── rails-controllers.mdc                         globs: app/controllers/**
 │       └── rails-mcp-tools.mdc                           alwaysApply: true
 │
-├── 🔵 Windsurf
-│   ├── .windsurfrules                                    ≤5,800 chars (6K limit)
-│   └── .windsurf/rules/
+├── 🔵 Devin
+│   ├── .devinrules                                       ≤5,800 chars (6K limit)
+│   └── .devin/rules/
 │       ├── rails-context.md                              project overview
 │       └── rails-mcp-tools.md                            tool reference
 │
@@ -247,7 +250,7 @@ This keeps context focused and avoids unnecessary token usage while still allowi
 
 ## MCP Tools
 
-The gem exposes **12 built-in tools** via MCP that AI clients call on-demand (hosts can append more via `config.additional_tools`):
+The gem exposes **13 built-in tools** via MCP that AI clients call on-demand (hosts can append more via `config.additional_tools`):
 
 | Tool | What it returns |
 |------|----------------|
@@ -263,6 +266,7 @@ The gem exposes **12 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` |
 
 All tools are **read-only** — they never modify your application or database.
 
@@ -303,7 +307,7 @@ This is expected: compact assistant-specific files and the summary-first MCP wor
 
 Observed benefits so far:
 - Less exploratory reading before the assistant reaches the relevant files
-- Faster first useful response in Cursor and Windsurf trials
+- Faster first useful response in Cursor and Devin trials
 - Similar or slightly better answer quality with clearer project grounding
 - More predictable drill-down via `detail:"summary"` first, then focused lookups
 
@@ -311,68 +315,114 @@ Results will vary by client, model, project size, and task type. More formal ben
 
 ---
 
-## MCP Server Setup
+## Connect your AI client
 
-The install generator creates `.mcp.json` for MCP-capable clients. Claude Code and Cursor can auto-detect it, while Codex can use the generated `AGENTS.md` plus your local Codex configuration.
+rails-ai-bridge gives every client two things: **static context files** loaded at session start (snapshots of your app), and **live MCP tools** called on-demand (always current). Both matter — files orient the assistant, tools answer specific questions without bloating context.
 
-This project keeps [`server.json`](server.json) aligned with GitHub metadata for MCP registry packaging when you choose to publish a release artifact.
+| Client | Static files loaded automatically | MCP wiring |
+|--------|----------------------------------|------------|
+| **Claude Code** | `CLAUDE.md`, `.claude/rules/*.md` | Auto — reads `.mcp.json` |
+| **Cursor** | `.cursorrules`, `.cursor/rules/*.mdc` | Auto — reads `.mcp.json` |
+| **Devin** | `.devinrules`, `.devin/rules/*.md`, `AGENTS.md` | Manual — create `.devin/mcp.json` |
+| **Copilot** | `.github/copilot-instructions.md`, `.github/instructions/` | Not supported natively |
+| **Codex** | `AGENTS.md`, `.codex/README.md` | Via `.codex/mcp_servers.json` |
+| **Gemini** | `GEMINI.md` | Via Gemini CLI config |
 
-To start manually: `rails ai:serve`
+### Claude Code
 
-<details>
-<summary><strong>Claude Desktop setup</strong></summary>
+No MCP setup needed. Claude Code auto-detects `.mcp.json` at the project root and spawns `bundle exec rails ai:serve` automatically. Ask Claude "What rails_* MCP tools do you have?" to confirm — it should list `rails_get_schema`, `rails_get_routes`, and the rest.
 
-Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
+If the connection fails: verify `.mcp.json` exists and that `bundle exec rails ai:serve` runs cleanly in your terminal.
+
+### Cursor
+
+No MCP setup needed. Cursor auto-detects `.mcp.json`. If it does not pick it up, open **Settings > MCP** and add the server manually with `BUNDLE_GEMFILE: "${workspaceFolder}/Gemfile"` in the `env` block.
+
+**Ruby version manager issue (rbenv/rvm):** Cursor may not inherit your shell environment when launching sub-processes. Fix: enable the HTTP transport instead.
+
+```ruby
+# config/initializers/rails_ai_bridge.rb
+RailsAiBridge.configure do |config|
+  config.auto_mount = true
+  config.http_path  = "/mcp"
+  config.http_bind  = "127.0.0.1"
+end
+```
+
+Start your Rails server and point Cursor to `http://localhost:3000/mcp` (type: SSE) in Settings > MCP.
+
+### Devin
 
+Devin reads `.devinrules`, `.devin/rules/*.md`, and `AGENTS.md` automatically. MCP requires one manual step.
+
+**Step 1 — generate files:**
+```bash
+rails ai:bridge    # all formats, including .devinrules and AGENTS.md
+```
+
+**Step 2 — create `.devin/mcp.json`:**
 ```json
 {
   "mcpServers": {
     "rails-ai-bridge": {
       "command": "bundle",
       "args": ["exec", "rails", "ai:serve"],
-      "cwd": "/path/to/your/rails/app"
+      "cwd": "/absolute/path/to/your/rails/app"
     }
   }
 }
 ```
-</details>
 
-<details>
-<summary><strong>HTTP transport (for remote clients)</strong></summary>
+Use the absolute path in `cwd` — Devin does not inherit your terminal's working directory. Commit this file so your team gets the same setup.
+
+**Step 3 — verify:** In a Devin session ask "What MCP tools do you have available?" — it should list the `rails-ai-bridge` server and all `rails_*` tools.
+
+**Ruby version manager issue:** If `bundle` is not on `PATH`, use the absolute shim path (e.g. `/Users/you/.rbenv/shims/bundle`) or switch to the HTTP transport. See [docs/devin-setup.md](docs/devin-setup.md) for the full guide including HTTP transport, skills, and troubleshooting.
+
+### GitHub Copilot
+
+MCP is not natively supported in the Copilot VS Code extension. The static files (`CLAUDE.md`, `.github/copilot-instructions.md`, path-scoped `.github/instructions/`) give Copilot project grounding, and the MCP tools are documented in the generated files so Copilot knows what to ask — but it cannot call them automatically. For tasks that need live schema or route lookups, use Claude Code or Cursor.
+
+### Codex
+
+Codex reads `AGENTS.md` at the repository root. MCP can be configured in `.codex/mcp_servers.json`. Run `rails ai:bridge:codex` to regenerate `AGENTS.md` and `.codex/README.md` (which includes Codex-specific setup notes).
+
+### HTTP transport (alternative for all clients)
+
+If stdio MCP fails (usually a Ruby version manager PATH issue), start the HTTP server instead:
 
 ```bash
-rails ai:serve_http  # Starts at http://127.0.0.1:6029/mcp
+rails ai:serve_http   # http://127.0.0.1:6029/mcp
 ```
 
-Or auto-mount inside your Rails app:
+Or auto-mount inside your running Rails app:
 
 ```ruby
 RailsAiBridge.configure do |config|
   config.auto_mount = true
-  config.http_mcp_token = "generate-a-long-random-secret" # or ENV["RAILS_AI_BRIDGE_MCP_TOKEN"]
-  # Production only: explicit opt-in + token required (see SECURITY.md)
-  # config.allow_auto_mount_in_production = true
+  config.http_mcp_token = ENV["RAILS_AI_BRIDGE_MCP_TOKEN"]   # required in production
   config.http_path  = "/mcp"
-  # Optional: reject HTTP requests when no Bearer/JWT/static auth is configured (safer beyond localhost)
-  # config.mcp.require_http_auth = true
+  config.http_bind  = "127.0.0.1"
 end
 ```
 
-Clients must send `Authorization: Bearer <token>` when a token is configured.
-
-Security note: keep the HTTP transport bound to `127.0.0.1` unless you add your own network and authentication controls. The tools are read-only, but they can still expose sensitive application structure. Generated context and the built-in conventions resource filter secret-bearing config paths, but MCP access should still be treated as internal. In **production**, `rails ai:serve_http` and `auto_mount` require a configured MCP token; `auto_mount` also requires `allow_auto_mount_in_production = true`. For operational hardening (tokens, proxies, `require_http_auth`, stdio threat model), see **[docs/mcp-security.md](docs/mcp-security.md)** and **[SECURITY.md](SECURITY.md)**.
-</details>
-
----
+Point your AI client to `http://localhost:3000/mcp` (or whichever port your Rails server uses) using transport type `SSE`. Keep the endpoint bound to localhost unless you add authentication. See [docs/mcp-security.md](docs/mcp-security.md) for production hardening.
 
-## Codex Setup
+### Claude Desktop (standalone app)
 
-Codex support is centered on **`AGENTS.md`** at the repository root.
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
 
-- Run `rails ai:bridge:codex` to regenerate `AGENTS.md` and `.codex/README.md`.
-- Keep `AGENTS.md` committed so Codex sees project-specific instructions.
-- Keep personal preferences in `~/.codex/AGENTS.md`; use the repository `AGENTS.md` for shared guidance.
-- When Codex is connected to the generated MCP server, prefer the `rails_*` tools and start with `detail:"summary"`.
+```json
+{
+  "mcpServers": {
+    "rails-ai-bridge": {
+      "command": "bundle",
+      "args": ["exec", "rails", "ai:serve"],
+      "env": { "BUNDLE_GEMFILE": "/absolute/path/to/your/rails/app/Gemfile" }
+    }
+  }
+}
+```
 
 ---
 
@@ -488,6 +538,13 @@ 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.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 |
 
 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>
@@ -569,6 +626,35 @@ To customize it in your initializer (`config/initializers/rails_ai_bridge.rb`):
 
 ---
 
+### Skill Packs
+
+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"
+```
+
+Quick example manifest (`config/rails_ai_bridge_registry.json`):
+
+```json
+{
+  "version": "1.0.0",
+  "packs": {
+    "rails": { "source": "igmarin/rails-agent-skills" },
+    "core":  { "source": "igmarin/ruby-core-skills", "always_loaded": true }
+  },
+  "default_stack": ["core"]
+}
+```
+
+Pack sources accept local paths, HTTPS URLs (`https://`), SSH URLs (`git@`), or `owner/repo` GitHub shorthands. Plain `http://` URLs are rejected. Packs can be pinned to a specific version with `"ref": "v1.2.0"`.
+
+To prevent network timeouts from blocking your server, set `config.registry.git_timeout` (default: 30 s). To control how often cached packs are refreshed, set `config.registry.git_pull_ttl` (default: 24 h; `0` to always pull).
+
+See [docs/skill-registry-guide.md](docs/skill-registry-guide.md) for the full setup guide.
+
+---
+
 ## Stack Compatibility
 
 Works with every Rails architecture — auto-detects what's relevant:
@@ -594,7 +680,7 @@ Frontend introspectors (views, Turbo, Stimulus, assets) degrade gracefully — t
 | `rails ai:bridge:claude` | Generate Claude Code files only |
 | `rails ai:bridge:codex` | Generate Codex files only (`AGENTS.md` + `.codex/README.md`) |
 | `rails ai:bridge:cursor` | Generate Cursor files only |
-| `rails ai:bridge:windsurf` | Generate Windsurf files only |
+| `rails ai:bridge:devin` | Generate Devin files only |
 | `rails ai:bridge:copilot` | Generate Copilot files only |
 | `rails ai:bridge:gemini` | Generate Gemini files only |
 | `rails ai:serve` | Start MCP server (stdio) |
@@ -602,6 +688,9 @@ Frontend introspectors (views, Turbo, Stimulus, assets) degrade gracefully — t
 | `rails ai:doctor` | Run diagnostics and AI readiness score (0-100) |
 | `rails ai:watch` | Auto-regenerate bridge files on code changes |
 | `rails ai:inspect` | Print introspection summary to stdout |
+| `rails ai:skills:list` | Print skill catalog from loaded skill packs |
+| `rails "ai:skills:resolve[pack,name]"` | Resolve and print a skill's full content |
+| `rails ai:skills:clear_cache` | Remove locally cached pack repositories |
 
 > **Bridge modes:**
 > ```bash
@@ -655,7 +744,12 @@ The docs are layered so new users do not need to read everything at once.
 | A quick install and mental model | This README |
 | How to get better AI output day to day | [docs/BEST_PRACTICES.md](docs/BEST_PRACTICES.md) |
 | Every command, config option, generated file, and MCP parameter | [docs/GUIDE.md](docs/GUIDE.md) |
+| Complete Devin setup — MCP wiring, skills, troubleshooting | [docs/devin-setup.md](docs/devin-setup.md) |
 | HTTP MCP hardening and production safety | [docs/mcp-security.md](docs/mcp-security.md) and [SECURITY.md](SECURITY.md) |
+| Skill packs: setup, sources, pinning, cache, troubleshooting | [docs/skill-registry-guide.md](docs/skill-registry-guide.md) |
+| Skill registry technical reference | [docs/registry-resolution.md](docs/registry-resolution.md) |
+| Offline mode design plan | [docs/offline-mode.md](docs/offline-mode.md) |
+| Gem improvement roadmap | [docs/gem-general-improvements.md](docs/gem-general-improvements.md) |
 | Upgrade notes between major versions | [UPGRADING.md](UPGRADING.md) |
 | Release history | [CHANGELOG.md](CHANGELOG.md) |
 | Development and contribution workflow | [CONTRIBUTING.md](CONTRIBUTING.md) |

data/docs/BEST_PRACTICES.md

@@ -3,7 +3,7 @@
 > For installation and a quick overview, see the [README](../README.md).
 > For the full command and configuration reference, see the [Guide](GUIDE.md).
 
-This document consolidates the patterns that consistently produce the best results when using rails-ai-bridge across Cursor, Windsurf, Copilot, Codex, and Claude Code — informed by real-world usage and feedback from multiple AI assistants evaluating the gem.
+This document consolidates the patterns that consistently produce the best results when using rails-ai-bridge across Cursor, Devin, Copilot, Codex, and Claude Code — informed by real-world usage and feedback from multiple AI assistants evaluating the gem.
 
 ---
 
@@ -51,17 +51,17 @@ Each AI client reads different files. Knowing which files matter for your tool h
 |--------|---------------------------------|----------|-------|
 | **Claude Code** | `CLAUDE.md`, `.claude/rules/*.md` | `.mcp.json` auto-detected | Rules injected per-session; MCP auto-wired via `.mcp.json` |
 | **Cursor** | `.cursorrules`, `.cursor/rules/*.mdc` | `.mcp.json` auto-detected | `alwaysApply: true` rules loaded every turn; glob-scoped rules loaded per file |
-| **Windsurf / Cascade** | `.windsurfrules`, `.windsurf/rules/*.md` | Manual MCP config required | 6K char limit on `.windsurfrules`; rules directory for overflow |
+| **Devin** | `.devinrules`, `.devin/rules/*.md` | Manual MCP config required | 6K char limit on `.devinrules`; rules directory for overflow |
 | **GitHub Copilot (VS Code)** | `.github/copilot-instructions.md`, `.github/instructions/*.instructions.md` | Not supported natively | `applyTo` glob patterns control which instructions file is injected |
 | **OpenAI Codex** | `AGENTS.md`, `.codex/README.md` | `.mcp.json` (when configured) | `AGENTS.md` at repo root is the primary context source |
 | **Gemini (AI Studio / Code Assist)** | `GEMINI.md` | MCP via Gemini CLI | `GEMINI.md` provides the project briefing; MCP for live data |
 
 ### How MCP wiring works per client
 
-- **Claude Code & Cursor**: `.mcp.json` at the project root is auto-detected. Run `rails ai:serve` or let the client spawn it.
-- **Windsurf**: MCP servers must be configured manually in Windsurf settings. Add `bundle exec rails ai:serve` as a stdio MCP server.
+- **Claude Code & Cursor**: `.mcp.json` at the project root is auto-detected. No manual setup — the client spawns `rails ai:serve` automatically.
+- **Devin**: MCP is not auto-detected. Create `.devin/mcp.json` manually (see [docs/devin-setup.md](devin-setup.md) for the exact JSON and full walkthrough).
 - **Codex**: Configure in `.codex/mcp_servers.json` or equivalent. The generated `.codex/README.md` includes setup instructions.
-- **Copilot**: MCP is not natively supported via `.mcp.json` as of this writing. The `rails_*` tools are documented in `.github/instructions/rails-mcp-tools.instructions.md` but cannot be invoked automatically.
+- **Copilot**: MCP is not natively supported via `.mcp.json`. The `rails_*` tools are documented in `.github/instructions/rails-mcp-tools.instructions.md` so Copilot knows about them, but cannot call them automatically.
 
 ### What "always loaded" means for token budgets
 
@@ -73,7 +73,7 @@ Files marked as `alwaysApply: true` (Cursor) or loaded at session start are incl
 
 ### Built-in tools and HTTP MCP
 
-There are **11** read-only built-in `rails_*` tools (hosts can add more via configuration). For Hotwire-heavy work, include `:views` and `:stimulus` in your introspectors so `rails_get_view` and `rails_get_stimulus` return live data. If MCP is served over HTTP beyond a locked-down localhost setup, configure authentication and read [mcp-security.md](mcp-security.md) and the repository [SECURITY.md](../SECURITY.md).
+There are **14** read-only built-in `rails_*` tools (hosts can add more via configuration). For Hotwire-heavy work, include `:views` and `:stimulus` in your introspectors so `rails_get_view` and `rails_get_stimulus` return live data. If MCP is served over HTTP beyond a locked-down localhost setup, configure authentication and read [mcp-security.md](mcp-security.md) and the repository [SECURITY.md](../SECURITY.md).
 
 ---
 
@@ -198,7 +198,7 @@ If `overrides.md` still has the omit-merge guard after initial setup, the gem in
 | Team-wide conventions (all clients) | `config/rails_ai_bridge/overrides.md` |
 | Claude Code-specific guidance | Append to `CLAUDE.md` after regeneration |
 | Cursor-specific rules | Add a `.cursor/rules/my-rules.mdc` that won't be overwritten |
-| Windsurf-specific | Add a `.windsurf/rules/my-rules.md` that won't be overwritten |
+| Devin-specific | Add a `.devin/rules/my-rules.md` that won't be overwritten |
 
 The gem only overwrites files it generated. Files you create with different names are safe.
 
@@ -221,11 +221,13 @@ The gem only overwrites files it generated. Files you create with different name
 4. `.cursorrules` is generated for legacy compatibility only. Cursor 0.45+ uses `.cursor/rules/` exclusively. Both can coexist safely.
 5. MCP is auto-wired via `.mcp.json`. Run `rails ai:serve` once; Cursor keeps it alive.
 
-### Windsurf / Cascade
+### Devin
 
-1. `.windsurfrules` is capped at ~5,800 characters (Windsurf's 6K limit). The gem respects this — overflow goes into `.windsurf/rules/`.
-2. MCP must be configured manually in Windsurf's MCP settings. Add: command `bundle exec rails ai:serve`, cwd: your project path.
-3. Cascade is good at following the "summary first, drill down" pattern — the generated `.windsurf/rules/rails-mcp-tools.md` teaches it this workflow.
+1. `.devinrules` is capped at ~5,800 characters (Devin's 6K limit). The gem respects this — overflow goes into `.devin/rules/`.
+2. Devin also reads `AGENTS.md` — run `rails ai:bridge` (not just `rails ai:bridge:devin`) to keep both files current.
+3. MCP requires a manual one-time step: create `.devin/mcp.json` with an absolute `cwd` path. See [docs/devin-setup.md](devin-setup.md) for the exact JSON.
+4. If `bundle` is not on `PATH` (common with rbenv/rvm in Devin's environment), use the absolute shim path or switch to the HTTP transport (`rails ai:serve_http`).
+5. Devin follows the "summary first, drill down" pattern well — the generated `.devin/rules/rails-mcp-tools.md` teaches it this workflow automatically.
 
 ### GitHub Copilot
 
@@ -336,8 +338,8 @@ AGENTS.md
 GEMINI.md
 .cursorrules
 .cursor/rules/
-.windsurfrules
-.windsurf/rules/
+.devinrules
+.devin/rules/
 .github/copilot-instructions.md
 .github/instructions/
 .codex/README.md