rails-ai-bridge 5.3.0 → 5.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (34) hide show
  1. checksums.yaml +4 -4
  2. data/.reek.yml +1 -0
  3. data/CHANGELOG.md +58 -0
  4. data/README.md +14 -16
  5. data/SECURITY.md +3 -0
  6. data/UPGRADING.md +15 -0
  7. data/docs/BEST_PRACTICES.md +7 -10
  8. data/docs/EXAMPLES.md +3 -6
  9. data/docs/GUIDE.md +79 -24
  10. data/docs/devin-setup.md +5 -8
  11. data/docs/mcp-security.md +20 -1
  12. data/docs/ruby-version-support.md +58 -0
  13. data/lib/generators/rails_ai_bridge/install/command_help.rb +3 -3
  14. data/lib/generators/rails_ai_bridge/install/install_generator.rb +2 -2
  15. data/lib/rails_ai_bridge/config/output.rb +6 -0
  16. data/lib/rails_ai_bridge/configuration.rb +1 -0
  17. data/lib/rails_ai_bridge/instrumentation.rb +7 -2
  18. data/lib/rails_ai_bridge/introspectors/config_introspector.rb +21 -5
  19. data/lib/rails_ai_bridge/introspectors/timezone_introspector.rb +44 -0
  20. data/lib/rails_ai_bridge/mcp/http_rate_limiter.rb +24 -9
  21. data/lib/rails_ai_bridge/serializers/README.md +0 -1
  22. data/lib/rails_ai_bridge/serializers/context_file_serializer.rb +6 -0
  23. data/lib/rails_ai_bridge/serializers/legacy_agent_files.rb +60 -0
  24. data/lib/rails_ai_bridge/serializers/providers/codex_serializer.rb +0 -1
  25. data/lib/rails_ai_bridge/tasks/rails_ai_bridge.rake +5 -5
  26. data/lib/rails_ai_bridge/tool_result_cache.rb +24 -4
  27. data/lib/rails_ai_bridge/tools/query/payload_formatter.rb +9 -9
  28. data/lib/rails_ai_bridge/tools/query.rb +25 -10
  29. data/lib/rails_ai_bridge/tools/search_code/ruby_search.rb +1 -1
  30. data/lib/rails_ai_bridge/tools/search_code/validator.rb +20 -1
  31. data/lib/rails_ai_bridge/version.rb +1 -1
  32. data/lib/rails_ai_bridge.rb +1 -1
  33. data/server.json +1 -1
  34. metadata +4 -1
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 2fdc446dd143e92672029e1d06c7081ad870772236dbbf912443ca6bfcab8fb5
4
- data.tar.gz: edcfd12eabe928b0103bf3e241ae2393b0cd5836b433ffff72c1f454374f0540
3
+ metadata.gz: 0f4066d47a05fac81d54e926520b483bc043b73f29fb7a2ec118caf133e01559
4
+ data.tar.gz: 9bf88dda78fba7d798008dae187d89f34724ceb64b18e962f27eea0d7cfd3b74
5
5
  SHA512:
6
- metadata.gz: 6d8b295f8d78e7a4f037f2bb9437bc9281ff535c4d9f6951d848fcae4500c1fbe438675588a247cbff1e98abae6816c0a66dca547a16a09504bd6b3a27e8ed53
7
- data.tar.gz: 1f479fb9b30ff3a82a2c73f5692cae70f136baf73034b51d372c65fdb7ade96b318a155171b72630479aba4c6244535c73307ac4e0a123880a694ff6445f9439
6
+ metadata.gz: 36183d3adfadb44f8752bfdf75b499128f98796c4c726c5b615dd49300cac3c4c109b76066810f319712dab6130dc9dd5a06f2405511559d12f3256b09a08a33
7
+ data.tar.gz: 27f36fe2f926077a470f3e49631d3e0eac13bd77e0c788a9a828641f9314255af80a1fe104c02b78eb2e2dbfca1314233daf2173a046a7b52682aecc9fa1e755
data/.reek.yml CHANGED
@@ -49,6 +49,7 @@ detectors:
49
49
  - RailsAiBridge::Config::Output#codex_compact_model_list_limit
50
50
  - RailsAiBridge::Config::Output#context_mode
51
51
  - RailsAiBridge::Config::Output#copilot_compact_model_list_limit
52
+ - RailsAiBridge::Config::Output#legacy_agent_files
52
53
  - RailsAiBridge::Config::Output#managed_region
53
54
  - RailsAiBridge::Config::Output#max_tool_response_chars
54
55
  - RailsAiBridge::Config::Output#output_dir
data/CHANGELOG.md CHANGED
@@ -7,6 +7,64 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [5.4.0] - 2026-10-23
11
+
12
+ ### Added
13
+
14
+ - `rails_ai_bridge.tool.call` notifications now include `success` and
15
+ `error_class`, while preserving the existing duration, tool name, and
16
+ arguments payload (#339).
17
+ - Ruby version support policy in `docs/ruby-version-support.md` (ticket #341).
18
+ - README Requirements and Ruby policy distinguish blocking Ruby 3.2–3.4 coverage
19
+ from the existing non-blocking Ruby 4.0 / Rails 8.1 canary. The historical Ruby
20
+ 3.5 preview is excluded from the matrix.
21
+ - `RailsAiBridge::Introspectors::TimezoneIntrospector` adds runtime confirmation
22
+ metadata to the existing config section (part of #342). `timezone_confirmed`
23
+ compares the IANA identifiers of `config.time_zone` and the current thread's
24
+ `Time.zone`, supporting both Rails names and IANA identifiers. It is false
25
+ when the runtime zone is unavailable or different. Static config introspection
26
+ remains unavailable; tool and serializer rendering is unchanged.
27
+
28
+ ### Changed
29
+
30
+ - `rails_query` enforces its row limit in SQL and fetches one sentinel row
31
+ before ActiveRecord materializes results. Summary responses now report the
32
+ same bounded `row_count` and `truncated` semantics as other detail levels
33
+ (#350).
34
+
35
+ ### Fixed
36
+
37
+ - Disable the review CLI's background auto-updater in CI so the pinned executable
38
+ cannot be replaced during an automated review.
39
+ - Bound the in-process tool response cache to 1,000 entries and the HTTP rate
40
+ limiter to 10,000 active client buckets. Expired entries are reclaimed
41
+ incrementally, and new clients fail closed when the limiter is full (#349).
42
+
43
+ ### Security
44
+
45
+ - Code search now skips symlinked files, rejects directory aliases into excluded
46
+ paths, and streams Ruby fallback reads up to the requested result cap (#347).
47
+ - Tool response cache keys now include the active Rails application, preventing
48
+ identical requests from reusing another application scope's response (#348).
49
+ - Refresh locked dependencies to include `crass` 1.0.8, which fixes
50
+ GHSA-pq4g-8rxf-4g29 in the CSS sanitizer dependency chain (#343).
51
+
52
+ ### Maintenance
53
+
54
+ - Refresh the mutation and demo-app lockfiles, including MCP 1.8.1, Rubydex
55
+ 0.4.2, Rails 8.1.4, SQLite 2.10.1, Faraday 2.15.0, Mutant 0.17.1,
56
+ RuboCop 1.92.1, and compatible transitive updates (#343). Skunk remains on
57
+ 0.5.4 because its 0.6 line conflicts with RubyCritic's `path_expander`
58
+ requirement; Reek remains on 6.5.x as required by RubyCritic 4.12.
59
+
60
+ ### Deprecated
61
+
62
+ - `.cursorrules`, `.devinrules`, and `.codex/README.md` are no longer written by default. Cursor reads
63
+ `.cursor/rules/` and `AGENTS.md`, Devin does not read `.devinrules`, and Codex reads only `AGENTS.md`.
64
+ `.cursor/rules/`, `.devin/rules/`, and `AGENTS.md` are unchanged. Set
65
+ `config.output.legacy_agent_files = true` to keep writing the three files; the first run prints a
66
+ deprecation notice. The option and the files are removed in 6.0. Existing copies are never deleted.
67
+
10
68
  ## [5.3.0] - 2026-10-08
11
69
 
12
70
  Confidence tags now reach controllers and the full view listing, and an opt-in Prism pass can upgrade
data/README.md CHANGED
@@ -206,12 +206,9 @@ your-rails-app/
206
206
  │ └── rails-mcp-tools.md full tool reference
207
207
  │
208
208
  ├── 🟡 OpenAI Codex
209
- │ ├── AGENTS.md project instructions for Codex
210
- │ └── .codex/
211
- │ └── README.md local Codex setup notes
209
+ │ └── AGENTS.md project instructions for Codex
212
210
  │
213
211
  ├── 🟢 Cursor
214
- │ ├── .cursorrules legacy compat
215
212
  │ └── .cursor/rules/
216
213
  │ ├── rails-engineering.mdc alwaysApply: true (rules first)
217
214
  │ ├── rails-project.mdc alwaysApply: true
@@ -220,7 +217,6 @@ your-rails-app/
220
217
  │ └── rails-mcp-tools.mdc alwaysApply: true
221
218
  │
222
219
  ├── 🔵 Devin
223
- │ ├── .devinrules ≤5,800 chars (6K limit)
224
220
  │ └── .devin/rules/
225
221
  │ ├── rails-context.md project overview
226
222
  │ └── rails-mcp-tools.md tool reference
@@ -374,10 +370,10 @@ rails-ai-bridge gives every client two things: **static context files** loaded a
374
370
  | Client | Static files loaded automatically | MCP wiring |
375
371
  |--------|----------------------------------|------------|
376
372
  | **Claude Code** | `CLAUDE.md`, `.claude/rules/*.md` | Auto — reads `.mcp.json` |
377
- | **Cursor** | `.cursorrules`, `.cursor/rules/*.mdc` | Auto — reads `.mcp.json` |
378
- | **Devin** | `.devinrules`, `.devin/rules/*.md`, `AGENTS.md` | Manual — create `.devin/mcp.json` |
373
+ | **Cursor** | `.cursor/rules/*.mdc`, `AGENTS.md` | Auto — reads `.mcp.json` |
374
+ | **Devin** | `.devin/rules/*.md`, `AGENTS.md` | Manual — create `.devin/mcp.json` |
379
375
  | **Copilot** | `.github/copilot-instructions.md`, `.github/instructions/` | Not supported natively |
380
- | **Codex** | `AGENTS.md`, `.codex/README.md` | Via `.codex/mcp_servers.json` |
376
+ | **Codex** | `AGENTS.md` | Via `.codex/mcp_servers.json` |
381
377
  | **Gemini** | `GEMINI.md` | Via Gemini CLI config |
382
378
 
383
379
  ### Claude Code
@@ -405,11 +401,11 @@ Start your Rails server and point Cursor to `http://localhost:3000/mcp` (type: S
405
401
 
406
402
  ### Devin
407
403
 
408
- Devin reads `.devinrules`, `.devin/rules/*.md`, and `AGENTS.md` automatically. MCP requires one manual step.
404
+ Devin reads `.devin/rules/*.md` and `AGENTS.md` automatically. MCP requires one manual step.
409
405
 
410
406
  **Step 1 — generate files:**
411
407
  ```bash
412
- rails ai:bridge # all formats, including .devinrules and AGENTS.md
408
+ rails ai:bridge # all formats, including .devin/rules/ and AGENTS.md
413
409
  ```
414
410
 
415
411
  **Step 2 — create `.devin/mcp.json`:**
@@ -437,7 +433,7 @@ MCP is not natively supported in the Copilot VS Code extension. The static files
437
433
 
438
434
  ### Codex
439
435
 
440
- 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).
436
+ 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`.
441
437
 
442
438
  ### HTTP transport (alternative for all clients)
443
439
 
@@ -605,6 +601,7 @@ The confidence and Prism settings also work on the `static_analysis` sub-object.
605
601
  | `watcher_formats` | `:all` | Formats regenerated by `rails ai:watch` (e.g. `%i[claude cursor]` to limit churn) |
606
602
  | `managed_region` | `false` | Confine generated output to a marked block so hand-authored content in `CLAUDE.md` & co. survives regeneration |
607
603
  | `anti_hallucination_rules` | `true` | Include the shared verify-before-write block in every generated context file (markdown near the top, `.ai-context.json` as an `anti_hallucination_rules` key) |
604
+ | `legacy_agent_files` | `false` | Also write the deprecated `.cursorrules`, `.devinrules`, and `.codex/README.md`. Cursor reads `.cursor/rules/` and `AGENTS.md`, Devin does not read `.devinrules`, and Codex reads only `AGENTS.md`. Removed in 6.0 |
608
605
  | `parallel_introspection` | `false` | Run introspectors concurrently (requires `concurrent-ruby`, which is already a Rails dependency) |
609
606
  | `parallel_pool_size` | `4` | Max threads in the parallel pool; capped at the number of active introspectors so no idle threads are created |
610
607
  | `parallel_timeout_seconds` | `10` | Per-introspector future timeout (seconds); timed-out introspectors return `{ error: "timed out after Ns" }` without blocking the others |
@@ -670,7 +667,7 @@ Always run `bin/rubocop` before committing.
670
667
  wrap the generated part in the markers by hand before your first run to keep it.
671
668
 
672
669
  Markdown provider files only (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`,
673
- `.github/copilot-instructions.md`, `.cursorrules`, `.devinrules`). `.ai-context.json` never
670
+ `.github/copilot-instructions.md`). `.ai-context.json` never
674
671
  receives markers. Freshness skipping and `ai:doctor` staleness both read through the region,
675
672
  so unchanged runs are still no-ops.
676
673
 
@@ -690,8 +687,8 @@ Every generated context file carries a short verify-before-write block so AI ass
690
687
  query the live app (via the `rails_*` MCP tools) instead of inventing structure:
691
688
 
692
689
  - Markdown files (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.github/copilot-instructions.md`,
693
- `.cursorrules`, `.devinrules`, and the split-rules files under `.claude/rules/`,
694
- `.cursor/rules/`, `.devin/rules/`, `.codex/`, `.github/instructions/`) open with a
690
+ and the split-rules files under `.claude/rules/`, `.cursor/rules/`, `.devin/rules/`,
691
+ `.github/instructions/`) open with a
695
692
  `## Anti-hallucination rules` section near the top — after the freshness header, before
696
693
  content sections — so it survives compact-mode trimming and stays inside the managed
697
694
  region on regeneration.
@@ -835,7 +832,7 @@ Frontend introspectors (views, Turbo, Stimulus, assets) degrade gracefully — t
835
832
  | `rails ai:bridge` | Generate all bridge files (skips unchanged) |
836
833
  | `rails ai:bridge:full` | Generate all files in full mode (dumps everything) |
837
834
  | `rails ai:bridge:claude` | Generate Claude Code files only |
838
- | `rails ai:bridge:codex` | Generate Codex files only (`AGENTS.md` + `.codex/README.md`) |
835
+ | `rails ai:bridge:codex` | Generate Codex files only (`AGENTS.md`) |
839
836
  | `rails ai:bridge:cursor` | Generate Cursor files only |
840
837
  | `rails ai:bridge:devin` | Generate Devin files only |
841
838
  | `rails ai:bridge:copilot` | Generate Copilot files only |
@@ -876,7 +873,8 @@ The gem parses `db/schema.rb` as text when no database is connected. Works in CI
876
873
 
877
874
  ## Requirements
878
875
 
879
- - Ruby >= 3.2, Rails >= 7.1
876
+ - Ruby **>= 3.2** (blocking CI on 3.2, 3.3, 3.4; Ruby 4.0 is a non-blocking canary). See the [Ruby support policy](docs/ruby-version-support.md) for tested combinations.
877
+ - Rails >= 7.1, < 10.0 (tested on 7.1, 7.2, 8.0, 8.1)
880
878
  - [mcp](https://github.com/modelcontextprotocol/ruby-sdk) gem (installed automatically)
881
879
  - Optional: `listen` gem for watch mode, `ripgrep` for fast code search
882
880
 
data/SECURITY.md CHANGED
@@ -29,6 +29,9 @@ please report it responsibly:
29
29
 
30
30
  - All MCP tools are **read-only** and never modify your application or database.
31
31
  - Code search (`rails_search_code`) uses `Open3.capture2` with array arguments to prevent shell injection.
32
+ Both backends skip symlinked files and reject directory aliases into excluded paths;
33
+ the Ruby fallback opens files with `File::NOFOLLOW` and streams lines so reaching
34
+ the result cap does not load the rest of a file.
32
35
  - Symbol explanation (`rails_explain_symbol`) uses `Open3.capture3` with array arguments against a local `.codegraph/` index only (timeout enforced; never contacts a network service).
33
36
  - File paths are validated against path traversal attacks, and invalid regex input
34
37
  now returns a controlled tool response in the Ruby fallback path.
data/UPGRADING.md CHANGED
@@ -1,5 +1,20 @@
1
1
  # Upgrading rails-ai-bridge
2
2
 
3
+ ## Upgrading from 5.3.x to the next release
4
+
5
+ **One behavior change.** `rails ai:bridge` no longer writes `.cursorrules`, `.devinrules`, or
6
+ `.codex/README.md`. No assistant needs them: Cursor reads `.cursor/rules/` and `AGENTS.md`, Devin does not
7
+ read `.devinrules`, and Codex reads only `AGENTS.md`. Nothing else changes, and the gem never deletes your
8
+ existing copies. Delete them when you are ready (and remove them from `.gitignore` or CI if you listed them).
9
+
10
+ To keep writing them until 6.0 removes the option:
11
+
12
+ ```ruby
13
+ RailsAiBridge.configure { |config| config.output.legacy_agent_files = true }
14
+ ```
15
+
16
+ ---
17
+
3
18
  ## Upgrading from 5.2.x to 5.3.0
4
19
 
5
20
  **No action is required.** One default changes what tools print.
@@ -50,17 +50,17 @@ Each AI client reads different files. Knowing which files matter for your tool h
50
50
  | Client | Passive context (always loaded) | Live MCP | Notes |
51
51
  |--------|---------------------------------|----------|-------|
52
52
  | **Claude Code** | `CLAUDE.md`, `.claude/rules/*.md` | `.mcp.json` auto-detected | Rules injected per-session; MCP auto-wired via `.mcp.json` |
53
- | **Cursor** | `.cursorrules`, `.cursor/rules/*.mdc` | `.mcp.json` auto-detected | `alwaysApply: true` rules loaded every turn; glob-scoped rules loaded per file |
54
- | **Devin** | `.devinrules`, `.devin/rules/*.md` | Manual MCP config required | 6K char limit on `.devinrules`; rules directory for overflow |
53
+ | **Cursor** | `.cursor/rules/*.mdc`, `AGENTS.md` | `.mcp.json` auto-detected | `alwaysApply: true` rules loaded every turn; glob-scoped rules loaded per file |
54
+ | **Devin** | `.devin/rules/*.md`, `AGENTS.md` | Manual MCP config required | Reads `AGENTS.md`, `CLAUDE.md`, and the rules directory |
55
55
  | **GitHub Copilot (VS Code)** | `.github/copilot-instructions.md`, `.github/instructions/*.instructions.md` | Not supported natively | `applyTo` glob patterns control which instructions file is injected |
56
- | **OpenAI Codex** | `AGENTS.md`, `.codex/README.md` | `.mcp.json` (when configured) | `AGENTS.md` at repo root is the primary context source |
56
+ | **OpenAI Codex** | `AGENTS.md` | `.mcp.json` (when configured) | `AGENTS.md` at repo root is the primary context source |
57
57
  | **Gemini (AI Studio / Code Assist)** | `GEMINI.md` | MCP via Gemini CLI | `GEMINI.md` provides the project briefing; MCP for live data |
58
58
 
59
59
  ### How MCP wiring works per client
60
60
 
61
61
  - **Claude Code & Cursor**: `.mcp.json` at the project root is auto-detected. No manual setup — the client spawns `rails ai:serve` automatically.
62
62
  - **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).
63
- - **Codex**: Configure in `.codex/mcp_servers.json` or equivalent. The generated `.codex/README.md` includes setup instructions.
63
+ - **Codex**: Configure in `.codex/mcp_servers.json` or equivalent.
64
64
  - **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.
65
65
 
66
66
  ### What "always loaded" means for token budgets
@@ -218,12 +218,12 @@ The gem only overwrites files it generated. Files you create with different name
218
218
  1. The five `.cursor/rules/*.mdc` files cover different scopes — don't collapse them into one big always-on file.
219
219
  2. `rails-engineering.mdc` and `rails-project.mdc` are the always-on rules. Keep them concise (< 100 lines each).
220
220
  3. `rails-models.mdc` and `rails-controllers.mdc` use glob scoping — they only fire when you have model/controller files open.
221
- 4. `.cursorrules` is generated for legacy compatibility only. Cursor 0.45+ uses `.cursor/rules/` exclusively. Both can coexist safely.
221
+ 4. `.cursorrules` is deprecated by Cursor and no longer generated by default. Delete an old copy; `.cursor/rules/` and `AGENTS.md` replace it.
222
222
  5. MCP is auto-wired via `.mcp.json`. Run `rails ai:serve` once; Cursor keeps it alive.
223
223
 
224
224
  ### Devin
225
225
 
226
- 1. `.devinrules` is capped at ~5,800 characters (Devin's 6K limit). The gem respects this — overflow goes into `.devin/rules/`.
226
+ 1. Devin does not read `.devinrules`, so the gem no longer generates it. Context goes into `AGENTS.md` and `.devin/rules/`.
227
227
  2. Devin also reads `AGENTS.md` — run `rails ai:bridge` (not just `rails ai:bridge:devin`) to keep both files current.
228
228
  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.
229
229
  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`).
@@ -240,7 +240,7 @@ The gem only overwrites files it generated. Files you create with different name
240
240
 
241
241
  1. `AGENTS.md` is the entry point — Codex reads this at task start.
242
242
  2. Keep personal preferences in `~/.codex/AGENTS.md`; use the repository `AGENTS.md` for shared guidance.
243
- 3. The `.codex/README.md` includes MCP setup instructions for connecting Codex to the live `rails_*` tools.
243
+ 3. Configure MCP in `.codex/mcp_servers.json` so Codex can call the live `rails_*` tools.
244
244
  4. Codex benefits most from explicit conventions (test patterns, service object structure) — make sure `overrides.md` is activated.
245
245
 
246
246
  ### Gemini
@@ -336,13 +336,10 @@ Use this ordering as a starting point, not a replacement for live checks. When a
336
336
  CLAUDE.md
337
337
  AGENTS.md
338
338
  GEMINI.md
339
- .cursorrules
340
339
  .cursor/rules/
341
- .devinrules
342
340
  .devin/rules/
343
341
  .github/copilot-instructions.md
344
342
  .github/instructions/
345
- .codex/README.md
346
343
  .mcp.json
347
344
  config/rails_ai_bridge/overrides.md ← commit even when stub; remove guard when ready
348
345
  ```
data/docs/EXAMPLES.md CHANGED
@@ -78,14 +78,11 @@ Captured output (abridged):
78
78
  📝 Writing bridge files...
79
79
  ✅ .../demo_app/CLAUDE.md
80
80
  ✅ .../demo_app/AGENTS.md
81
- ✅ .../demo_app/.cursorrules
82
- ✅ .../demo_app/.devinrules
83
81
  ✅ .../demo_app/.github/copilot-instructions.md
84
82
  ✅ .../demo_app/GEMINI.md
85
83
  ✅ .../demo_app/.claude/rules/rails-context.md
86
84
  ✅ .../demo_app/.claude/rules/rails-schema.md
87
85
  ✅ .../demo_app/.claude/rules/rails-models.md
88
- ⏭️ .../demo_app/.codex/README.md (unchanged)
89
86
  ...
90
87
 
91
88
  Done! Your AI assistants now understand your Rails app.
@@ -97,9 +94,9 @@ One run writes context for all 7 assistant targets. The committed files in
97
94
  | Assistant target | File(s) | Size |
98
95
  |---|---|---|
99
96
  | Claude Code | `CLAUDE.md` + `.claude/rules/*.md` | 111 lines (compact) |
100
- | OpenAI Codex | `AGENTS.md` + `.codex/README.md` | 98 lines |
101
- | Cursor | `.cursorrules` + `.cursor/rules/*.mdc` | 108 lines |
102
- | Devin | `.devinrules` + `.devin/rules/*.md` | 53 lines (≤5,800 chars) |
97
+ | OpenAI Codex | `AGENTS.md` | 98 lines |
98
+ | Cursor | `.cursor/rules/*.mdc` | 108 lines |
99
+ | Devin | `.devin/rules/*.md` | 53 lines |
103
100
  | GitHub Copilot | `.github/copilot-instructions.md` + `.github/instructions/*.md` | 136 lines |
104
101
  | Gemini | `GEMINI.md` | 111 lines |
105
102
  | JSON cache (not an assistant) | `.ai-context.json` (regenerable cache, not committed) | — |
data/docs/GUIDE.md CHANGED
@@ -80,7 +80,6 @@ rails ai:bridge
80
80
  ```
81
81
 
82
82
  - CLAUDE.md ≤150 lines
83
- - .devinrules ≤5,800 characters
84
83
  - copilot-instructions.md ≤500 lines
85
84
  - Files contain a project overview + MCP tool reference
86
85
  - AI uses MCP tools for detailed data on-demand
@@ -139,25 +138,31 @@ end
139
138
  | `.claude/rules/rails-models.md` | Model listing with associations | Includes `tier: …` per ActiveRecord model; adds **Non-ActiveRecord classes (POJO/Service)** for plain Ruby classes under `app/models`. |
140
139
  | `.claude/rules/rails-mcp-tools.md` | Full MCP tool reference | Parameters, detail levels, pagination, workflow guide. |
141
140
 
142
- ### Cursor (6 files)
141
+ ### Cursor (5 files)
143
142
 
144
143
  | File | Purpose | Notes |
145
144
  |------|---------|-------|
146
- | `.cursorrules` | Legacy context file | Compact mode: engineering rules + stack + MCP (aligned with Copilot order). |
147
145
  | `.cursor/rules/rails-engineering.mdc` | Engineering essentials | `alwaysApply: true` — strong params, auth, N+1, security; points to overrides + full docs. |
148
146
  | `.cursor/rules/rails-project.mdc` | Project overview | `alwaysApply: true` — stack counts, endpoint focus, gems (capped), `routes_stack_line`. |
149
147
  | `.cursor/rules/rails-models.mdc` | Model reference | `globs: app/models/**/*.rb` — auto-attaches when editing models; rows are ordered by task relevance. |
150
148
  | `.cursor/rules/rails-controllers.mdc` | Controller reference | `globs: app/controllers/**/*.rb` — auto-attaches when editing controllers. |
151
149
  | `.cursor/rules/rails-mcp-tools.mdc` | MCP tool reference | `alwaysApply: true` — always available. |
152
150
 
153
- ### Devin (3 files)
151
+ ### Devin (2 files)
154
152
 
155
153
  | File | Purpose | Notes |
156
154
  |------|---------|-------|
157
- | `.devinrules` | Main context file | Hard-capped at 5,800 chars (Devin's 6K limit). Truncated silently if exceeded. |
158
155
  | `.devin/rules/rails-context.md` | Project overview | New Devin rules format. |
159
156
  | `.devin/rules/rails-mcp-tools.md` | MCP tool reference | Compact — respects 6K per-file limit. |
160
157
 
158
+ ### Deprecated files
159
+
160
+ `.cursorrules`, `.devinrules`, and `.codex/README.md` are no longer written by default. Cursor reads
161
+ `.cursor/rules/` and `AGENTS.md`, Devin reads `AGENTS.md` and `.devin/rules/` (it does not read
162
+ `.devinrules`), and Codex reads only `AGENTS.md`. Copies you already have stay in place; delete them when
163
+ you are ready. Set `config.output.legacy_agent_files = true` to keep writing them until 6.0, which removes
164
+ the option. The first run with the option on prints a deprecation notice.
165
+
161
166
  ### GitHub Copilot (4 files)
162
167
 
163
168
  | File | Purpose | Notes |
@@ -197,7 +202,7 @@ query the `rails_*` MCP tools for columns, associations, and routes; mark guesse
197
202
  `RailsAiBridge::Serializers::AntiHallucinationRules` — a single source of truth.
198
203
 
199
204
  The block is injected into all markdown outputs (main context files **and** the
200
- split-rules files under `.claude/rules/`, `.cursor/rules/`, `.devin/rules/`, `.codex/`,
205
+ split-rules files under `.claude/rules/`, `.cursor/rules/`, `.devin/rules/`,
201
206
  `.github/instructions/`) near the top, so it survives compact-mode bottom-trimming and
202
207
  Devin's 5,800-character cap, and it is always inside the managed region when
203
208
  `config.output.managed_region` is enabled.
@@ -215,9 +220,9 @@ Disable with `config.output.anti_hallucination_rules = false` (default: `true`).
215
220
  | `rails ai:bridge` | compact | all | Generate all bridge files |
216
221
  | `rails ai:bridge:full` | full | all | Generate all files in full mode |
217
222
  | `rails ai:bridge:claude` | compact | Claude | CLAUDE.md + .claude/rules/ |
218
- | `rails ai:bridge:codex` | compact | Codex | AGENTS.md + .codex/README.md |
219
- | `rails ai:bridge:cursor` | compact | Cursor | .cursorrules + .cursor/rules/ |
220
- | `rails ai:bridge:devin` | compact | Devin | .devinrules + .devin/rules/ |
223
+ | `rails ai:bridge:codex` | compact | Codex | AGENTS.md |
224
+ | `rails ai:bridge:cursor` | compact | Cursor | .cursor/rules/ |
225
+ | `rails ai:bridge:devin` | compact | Devin | .devin/rules/ |
221
226
  | `rails ai:bridge:copilot` | compact | Copilot | copilot-instructions.md + .github/instructions/ |
222
227
  | `rails ai:bridge:json` | — | JSON | .ai-context.json |
223
228
  | `CONTEXT_MODE=full rails ai:bridge:claude` | full | Claude | Full dump for Claude only |
@@ -286,7 +291,7 @@ RailsAiBridge.generate_context(
286
291
  ```ruby
287
292
  # config/initializers/rails_ai_bridge.rb
288
293
  RailsAiBridge.configure do |config|
289
- # Regenerates CLAUDE.md + .claude/rules/* and .cursorrules + .cursor/rules/*
294
+ # Regenerates CLAUDE.md + .claude/rules/* and .cursor/rules/*
290
295
  # (split-rule directories are also churned when split_rules: true, the default)
291
296
  config.watcher_formats = %i[claude cursor]
292
297
  end
@@ -450,6 +455,22 @@ Returns application configuration. No parameters.
450
455
 
451
456
  **Returns:** cache store, session store, timezone, middleware stack, initializers, credentials keys, current attributes.
452
457
 
458
+ #### Timezone facts
459
+
460
+ The raw `:config` payload includes `timezone` (the configured `config.time_zone`)
461
+ and `timezone_confirmed`. Confirmation is `true` when the current thread's
462
+ `Time.zone` and the configured zone resolve to the same IANA identifier. Rails
463
+ names such as `Eastern Time (US & Canada)` and IANA names such as
464
+ `America/New_York` are both supported.
465
+
466
+ Confirmation is `false` when the runtime zone is unavailable or different, for
467
+ example inside `Time.use_zone` with another zone. It describes the introspecting
468
+ thread at the time of the read, not every request's timezone. `rails_get_config`
469
+ and serializers retain their existing timezone rendering; the flag is raw
470
+ metadata. Config introspection requires boot; static mode reports it as skipped
471
+ and does not infer timezone settings from `db/schema.rb`. Broader timezone
472
+ output and offline support remain tracked in #342.
473
+
453
474
  ```
454
475
  rails_get_config()
455
476
  → Cache: redis_cache_store, Session: cookie_store, TZ: UTC, ...
@@ -514,7 +535,7 @@ rails_search_code(pattern: "def create", path: "app/controllers", file_type: "rb
514
535
  → First 50 matches under app/controllers
515
536
  ```
516
537
 
517
- **Security:** Uses `Open3.capture2` with array arguments (no shell injection). Validates `file_type`. Blocks path traversal. Respects `excluded_paths`. Optional wall-clock limit per call: `config.search_code_timeout_seconds` (default 5; set `0` to disable).
538
+ **Security:** Uses `Open3.capture2` with array arguments (no shell injection). Validates `file_type`. Blocks path traversal. Both backends skip symlinked files and reject directory aliases into `excluded_paths`. The Ruby fallback streams lines and stops when the result cap is reached. Optional wall-clock limit per call: `config.search_code_timeout_seconds` (default 5; set `0` to disable).
518
539
 
519
540
  ### rails_search_semantic
520
541
 
@@ -551,14 +572,23 @@ Runs a single read-only SELECT statement on the app's established ActiveRecord c
551
572
 
552
573
  | Param | Type | Description |
553
574
  |-------|------|-------------|
554
- | `sql` | string | **Required.** A single plain SELECT statement. Semicolons, CTEs (`WITH`), and mutating/locking clauses are rejected. |
555
- | `row_limit` | integer | Max rows (hard cap 100). Defaults: 20 (standard), 100 (full). |
556
- | `detail` | string | `summary` (columns + row count), `standard` (default), `full`. |
575
+ | `sql` | string | **Required.** A single plain SELECT statement; one trailing semicolon is allowed. Multiple statements, CTEs (`WITH`), and mutating/locking clauses are rejected. |
576
+ | `row_limit` | integer | Max rows (hard cap 100). Defaults: 20 (standard), 100 (summary/full). |
577
+ | `detail` | string | `summary` (columns + bounded row count + truncation flag), `standard` (default), `full`. |
557
578
 
558
579
  **Opt-in:** registered only when `config.enable_data_tools = true` (default `false`).
559
580
 
560
581
  **Security:** SELECT-only allowlist (CTEs rejected in v1 — mutating CTEs allow writes inside `WITH`); `FOR UPDATE`/`FOR SHARE`/`LOCK IN SHARE MODE` and `SELECT ... INTO` (including `INTO OUTFILE`) rejected. On PostgreSQL the statement runs inside a `READ ONLY` transaction with `statement_timeout`; on other adapters the keyword guard is best-effort. Hard 100-row cap, 5s statement timeout. Credential-like columns (`password`, `token`, `secret`, `api_key`, `auth`, `password_digest`, `secret_access_key`, …) are replaced with `[redacted]` — best-effort: column aliases can bypass the match. Runs on the app's existing connection, so introspection exclusions (`excluded_models`/`excluded_tables`) do not restrict it.
561
582
 
583
+ The row cap is enforced in SQL before ActiveRecord materializes the result, fetching
584
+ at most `row_limit + 1` rows (maximum 101) to detect truncation. Existing SQL
585
+ `LIMIT`/`OFFSET` clauses are preserved. Use unique column aliases for portable
586
+ queries, because the SELECT runs as a derived table. `row_count` is the bounded count, not the
587
+ query's unrestricted total: it is exact when `truncated` is `false`; when `true`,
588
+ more rows matched than the reported count. Summary uses the same bound and
589
+ includes `truncated`, but omits `rows`. The cap bounds result materialization;
590
+ sorting, aggregation, and other database work remain subject to the timeout.
591
+
562
592
  ### rails_read_logs
563
593
 
564
594
  Returns a redacted tail of a log file under the app's `log/` directory as compact JSON.
@@ -775,7 +805,7 @@ Set `config.require_http_auth = true` if the endpoint must not accept anonymous
775
805
 
776
806
  ### Codex
777
807
 
778
- This fork adds Codex support through `AGENTS.md` and `.codex/README.md`.
808
+ This fork adds Codex support through `AGENTS.md`.
779
809
 
780
810
  - Run `rails ai:bridge:codex` to regenerate Codex guidance.
781
811
  - Commit `AGENTS.md` for shared repository instructions.
@@ -811,6 +841,7 @@ RailsAiBridge.configure do |config|
811
841
 
812
842
  # Anti-hallucination rules block in every generated file (default: true)
813
843
  # config.output.anti_hallucination_rules = true
844
+ # config.output.legacy_agent_files = false # true also writes deprecated .cursorrules, .devinrules, .codex/README.md
814
845
 
815
846
  # Formats regenerated by `rails ai:watch` (default: :all). Narrow to limit churn.
816
847
  # config.watcher_formats = %i[claude cursor]
@@ -823,7 +854,7 @@ RailsAiBridge.configure do |config|
823
854
  # Optional markdown merged into compact Copilot + Codex (default: config/rails_ai_bridge/overrides.md)
824
855
  # config.assistant_overrides_path = "config/rails_ai_bridge/overrides.md"
825
856
 
826
- # Model names shown in compact copilot-instructions / AGENTS / .cursorrules (0 = MCP pointer only)
857
+ # Model names shown in compact copilot-instructions / AGENTS (0 = MCP pointer only)
827
858
  # config.copilot_compact_model_list_limit = 5
828
859
  # config.codex_compact_model_list_limit = 3
829
860
 
@@ -918,10 +949,11 @@ The settings `confidence_tags_enabled`, `prism_enabled`, and `prism_max_files` w
918
949
  | `http_log_json` | Boolean | `false` | Structured JSON log line per HTTP MCP response |
919
950
  | `server_name` | String | `"rails-ai-bridge"` | MCP server name |
920
951
  | `assistant_overrides_path` | String | `nil` → `config/rails_ai_bridge/overrides.md` | Markdown merged into compact Copilot + Codex |
921
- | `copilot_compact_model_list_limit` | Integer | `5` | Max model rows in copilot-instructions / `.cursorrules` (`0` = none) |
952
+ | `copilot_compact_model_list_limit` | Integer | `5` | Max model rows in copilot-instructions (`0` = none) |
922
953
  | `codex_compact_model_list_limit` | Integer | `3` | Max model rows in `AGENTS.md` (`0` = none) |
923
954
  | `watcher_formats` | Symbol / Array | `:all` | Formats regenerated by `rails ai:watch`. Set to e.g. `%i[claude cursor]` to skip formats you don't use during active development. |
924
955
  | `anti_hallucination_rules` | Boolean | `true` | Include the shared `## Anti-hallucination rules` block in every generated context file (markdown near the top; `.ai-context.json` as an `anti_hallucination_rules` key) |
956
+ | `legacy_agent_files` | Boolean | `false` | Also write the deprecated `.cursorrules`, `.devinrules`, and `.codex/README.md`. Removed in 6.0. |
925
957
  | `parallel_introspection` | Boolean | `false` | Run introspectors concurrently using a `Concurrent::FixedThreadPool`. Requires `concurrent-ruby` (already a Rails transitive dep). Automatically disabled when the ActiveRecord connection pool has only one slot. |
926
958
  | `parallel_pool_size` | Integer | `4` | Upper bound on pool threads. Actual size is `min(introspector_count, parallel_pool_size)` — no idle threads are created. Only relevant when `parallel_introspection` is `true`. |
927
959
  | `parallel_timeout_seconds` | Integer | `10` | Seconds each future may run before being cancelled. Timed-out introspectors return `{ error: "timed out after Ns" }`. Also used as the `wait_for_termination` grace period. Only relevant when `parallel_introspection` is `true`. |
@@ -930,6 +962,32 @@ The settings `confidence_tags_enabled`, `prism_enabled`, and `prism_max_files` w
930
962
  | `prism_enabled` | Boolean | `false` | Turns on the Prism pass. Strong params that Prism finds as methods in the controller source render as `[VERIFIED]`. Needs Prism, a default gem on Ruby 3.3+. |
931
963
  | `prism_max_files` | Integer | `500` | Caps the files the Prism pass reads per introspection run. |
932
964
 
965
+ ### Tool-call observability
966
+
967
+ Every MCP invocation emits `rails_ai_bridge.tool.call` through
968
+ `ActiveSupport::Notifications`. Its payload keeps `tool_name` and `arguments` and
969
+ adds `success` plus `error_class`. `success` is false for an MCP error response or
970
+ a raised exception; `error_class` is populated only for raised exceptions. Use the
971
+ notification event's duration instead of adding timing labels, and avoid exporting
972
+ raw `arguments` because they may contain application data.
973
+
974
+ ```ruby
975
+ ActiveSupport::Notifications.subscribe("rails_ai_bridge.tool.call") do |*args|
976
+ event = ActiveSupport::Notifications::Event.new(*args)
977
+ payload = event.payload
978
+
979
+ Rails.logger.info(
980
+ event: event.name,
981
+ tool: payload[:tool_name],
982
+ success: payload[:success],
983
+ error_class: payload[:error_class],
984
+ duration_ms: event.duration.round(1)
985
+ )
986
+ end
987
+ ```
988
+
989
+ This example intentionally excludes `payload[:arguments]`.
990
+
933
991
  ---
934
992
 
935
993
  ## Introspectors — Full List
@@ -1028,7 +1086,6 @@ rails ai:bridge # all formats at once
1028
1086
  ### Cursor
1029
1087
 
1030
1088
  **Passive context (loaded automatically):**
1031
- - `.cursorrules` — legacy compat file, loaded at session start
1032
1089
  - `.cursor/rules/*.mdc` — MDC rules with activation modes:
1033
1090
 
1034
1091
  | Rule file | Activation |
@@ -1072,7 +1129,7 @@ Then start your Rails server (`bin/rails server`) and point Cursor to `http://lo
1072
1129
 
1073
1130
  **Regenerate context:**
1074
1131
  ```bash
1075
- rails ai:bridge:cursor # .cursorrules + .cursor/rules/
1132
+ rails ai:bridge:cursor # .cursor/rules/
1076
1133
  ```
1077
1134
 
1078
1135
  ---
@@ -1080,7 +1137,6 @@ rails ai:bridge:cursor # .cursorrules + .cursor/rules/
1080
1137
  ### Devin
1081
1138
 
1082
1139
  **Passive context (loaded automatically):**
1083
- - `.devinrules` — compact project overview, hard-capped at 5,800 chars (Devin's 6K limit)
1084
1140
  - `.devin/rules/rails-context.md` — project overview (full version, also capped at 5,800 chars)
1085
1141
  - `.devin/rules/rails-mcp-tools.md` — MCP tool reference
1086
1142
  - `AGENTS.md` — Devin also reads AGENTS.md as repo-level instructions
@@ -1089,7 +1145,7 @@ rails ai:bridge:cursor # .cursorrules + .cursor/rules/
1089
1145
 
1090
1146
  **Step 1 — Generate the Devin context files:**
1091
1147
  ```bash
1092
- rails ai:bridge:devin # .devinrules + .devin/rules/
1148
+ rails ai:bridge:devin # .devin/rules/
1093
1149
  rails ai:bridge:codex # AGENTS.md (Devin also reads this)
1094
1150
  # or generate everything at once:
1095
1151
  rails ai:bridge
@@ -1166,13 +1222,12 @@ rails ai:bridge:copilot # .github/copilot-instructions.md + .github/instructio
1166
1222
 
1167
1223
  **Passive context:**
1168
1224
  - `AGENTS.md` — primary context file, read by Codex at session start
1169
- - `.codex/README.md` — local Codex setup notes generated by the install generator
1170
1225
 
1171
- **MCP tools:** Configurable via `.codex/mcp_servers.json` or equivalent Codex MCP config. The generated `.codex/README.md` includes setup instructions.
1226
+ **MCP tools:** Configurable via `.codex/mcp_servers.json` or equivalent Codex MCP config.
1172
1227
 
1173
1228
  **Regenerate context:**
1174
1229
  ```bash
1175
- rails ai:bridge:codex # AGENTS.md + .codex/README.md
1230
+ rails ai:bridge:codex # AGENTS.md
1176
1231
  ```
1177
1232
 
1178
1233
  ---
data/docs/devin-setup.md CHANGED
@@ -19,14 +19,12 @@ Devin CLI reads the following files from your project root without any configura
19
19
 
20
20
  | File | Purpose |
21
21
  |------|---------|
22
- | `.devinrules` | Primary context file. Hard-capped at 5,800 characters (Devin enforces a 6K limit). Contains the most critical project overview. |
23
22
  | `.devin/rules/*.md` | Supplementary rule files. Devin reads all Markdown files in this directory. |
24
- | `AGENTS.md` | Codex-style instruction file. Devin reads this alongside `.devinrules`. |
23
+ | `AGENTS.md` | Repo-level instructions. Devin reads this alongside the rules directory. |
25
24
 
26
25
  The rails-ai-bridge generator produces:
27
26
 
28
- - `.devinrules` — main context, truncated to stay within the 5,800-character cap
29
- - `.devin/rules/rails-context.md` — project overview content that overflows from `.devinrules`
27
+ - `.devin/rules/rails-context.md` — project overview content
30
28
  - `.devin/rules/rails-mcp-tools.md` — MCP tool reference so Devin knows what tools are available
31
29
  - `AGENTS.md` — full project context and conventions in codex format
32
30
 
@@ -42,7 +40,7 @@ Run the Devin-specific generator:
42
40
  bundle exec rails ai:bridge:devin
43
41
  ```
44
42
 
45
- This writes `.devinrules`, `.devin/rules/rails-context.md`, `.devin/rules/rails-mcp-tools.md`, and `AGENTS.md`. Unchanged files are skipped (SHA256 fingerprinting prevents unnecessary writes).
43
+ This writes `.devin/rules/rails-context.md`, and `.devin/rules/rails-mcp-tools.md`. Run `rails ai:bridge:codex` as well to write `AGENTS.md`, which Devin also reads. Unchanged files are skipped (SHA256 fingerprinting prevents unnecessary writes).
46
44
 
47
45
  To generate context files for all supported AI tools at once:
48
46
 
@@ -132,13 +130,13 @@ If this command exits immediately with an error, the problem is in your Rails en
132
130
 
133
131
  Use the two layers for different purposes:
134
132
 
135
- **Static files for orientation** — at the start of a session, Devin reads `.devinrules` and `AGENTS.md` to understand the project structure, conventions, and domain. This costs no tool calls and happens automatically.
133
+ **Static files for orientation** — at the start of a session, Devin reads `AGENTS.md` and `.devin/rules/` to understand the project structure, conventions, and domain. This costs no tool calls and happens automatically.
136
134
 
137
135
  **MCP tools for drill-down** — when Devin needs specific information (the associations on a particular model, the routes for a namespace, test coverage for a controller), it calls the appropriate MCP tool. This returns current data directly from your running application.
138
136
 
139
137
  A typical session looks like:
140
138
 
141
- 1. Devin loads `.devinrules` and `AGENTS.md` — understands the project at a high level.
139
+ 1. Devin loads `AGENTS.md` and `.devin/rules/` — understands the project at a high level.
142
140
  2. Devin calls `rails_get_schema` to inspect the tables relevant to the task.
143
141
  3. Devin calls `rails_get_model_details` with `detail: full` for the specific model it is working on.
144
142
  4. Devin calls `rails_get_routes` to understand the routing structure.
@@ -257,7 +255,6 @@ Devin will call `rails_list_registry`, review the options, and call `rails_resol
257
255
 
258
256
  | File | Generator | Checked in? |
259
257
  |------|-----------|-------------|
260
- | `.devinrules` | `rails ai:bridge:devin` | Yes |
261
258
  | `.devin/rules/rails-context.md` | `rails ai:bridge:devin` | Yes |
262
259
  | `.devin/rules/rails-mcp-tools.md` | `rails ai:bridge:devin` | Yes |
263
260
  | `AGENTS.md` | `rails ai:bridge:devin` | Yes |