rails-ai-context 5.38.0 → 5.38.2

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 (56) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +84 -0
  3. data/README.md +2 -2
  4. data/docs/ARCHITECTURE.md +18 -16
  5. data/docs/COMPATIBILITY.md +1 -1
  6. data/docs/CONFIGURATION.md +7 -4
  7. data/docs/CUSTOM_TOOLS.md +1 -1
  8. data/docs/FAQ.md +11 -7
  9. data/docs/GUIDE.md +65 -46
  10. data/docs/PROMPTS.md +1 -1
  11. data/docs/QUICKSTART.md +1 -1
  12. data/docs/RECIPES.md +2 -2
  13. data/docs/SETUP.md +15 -14
  14. data/docs/TROUBLESHOOTING.md +4 -6
  15. data/lib/generators/rails_ai_context/install/install_generator.rb +4 -0
  16. data/lib/rails_ai_context/cli/tool_runner.rb +1 -1
  17. data/lib/rails_ai_context/configuration.rb +8 -2
  18. data/lib/rails_ai_context/context_file_report.rb +9 -3
  19. data/lib/rails_ai_context/doctor.rb +9 -5
  20. data/lib/rails_ai_context/initializer_settings.rb +16 -4
  21. data/lib/rails_ai_context/install/ai_tool.rb +52 -8
  22. data/lib/rails_ai_context/install/cleanup.rb +19 -2
  23. data/lib/rails_ai_context/install/program.rb +8 -1
  24. data/lib/rails_ai_context/introspectors/test_introspector.rb +18 -1
  25. data/lib/rails_ai_context/serializers/base.rb +5 -1
  26. data/lib/rails_ai_context/serializers/budget.rb +124 -0
  27. data/lib/rails_ai_context/serializers/claude_rules_serializer.rb +29 -119
  28. data/lib/rails_ai_context/serializers/compact_serializer_helper.rb +21 -148
  29. data/lib/rails_ai_context/serializers/context_file_serializer.rb +76 -62
  30. data/lib/rails_ai_context/serializers/copilot_instructions_serializer.rb +28 -71
  31. data/lib/rails_ai_context/serializers/cursor_rules_serializer.rb +30 -118
  32. data/lib/rails_ai_context/serializers/load_plan.rb +64 -0
  33. data/lib/rails_ai_context/serializers/markdown_serializer.rb +23 -120
  34. data/lib/rails_ai_context/serializers/model_section.rb +108 -0
  35. data/lib/rails_ai_context/serializers/opencode_rules_serializer.rb +15 -46
  36. data/lib/rails_ai_context/serializers/root_file.rb +16 -0
  37. data/lib/rails_ai_context/serializers/rule_scope.rb +73 -0
  38. data/lib/rails_ai_context/serializers/section_facts.rb +14 -4
  39. data/lib/rails_ai_context/serializers/section_marker_writer.rb +16 -2
  40. data/lib/rails_ai_context/serializers/stack_overview_helper.rb +119 -73
  41. data/lib/rails_ai_context/serializers/stack_sections.rb +63 -0
  42. data/lib/rails_ai_context/serializers/tool_guide_helper.rb +71 -170
  43. data/lib/rails_ai_context/server.rb +1 -1
  44. data/lib/rails_ai_context/tools/base_tool.rb +13 -1
  45. data/lib/rails_ai_context/tools/get_context.rb +1 -1
  46. data/lib/rails_ai_context/tools/safe_call.rb +34 -15
  47. data/lib/rails_ai_context/tools/search_code.rb +1 -1
  48. data/lib/rails_ai_context/tools/validate.rb +1 -1
  49. data/lib/rails_ai_context/version.rb +1 -1
  50. data/lib/rails_ai_context/watcher.rb +2 -0
  51. metadata +9 -8
  52. data/lib/rails_ai_context/serializers/claude_serializer.rb +0 -42
  53. data/lib/rails_ai_context/serializers/context_mode_dispatch.rb +0 -20
  54. data/lib/rails_ai_context/serializers/copilot_serializer.rb +0 -43
  55. data/lib/rails_ai_context/serializers/opencode_serializer.rb +0 -41
  56. data/lib/rails_ai_context/serializers/test_command_detection.rb +0 -15
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 0acee3a866c72246dbec681c5c4532cd734fd08924fae6962c38584fddc93006
4
- data.tar.gz: f5643f2c9126309fa571a4592873109b24f04e317546eb60c162486e30fb2cc5
3
+ metadata.gz: 51468955210c3dfe5b635691b5408be3f813f674380481115c098fab27973eae
4
+ data.tar.gz: 5fa9d2735c18d79c6bbd3f3e23205f9c5ffc8bd6728bae6feb0dcbf5cbdaaa1f
5
5
  SHA512:
6
- metadata.gz: c598ed0e7f4fababb8ae12e88a06d6f37b8f3ce7c053e431f89dd91af0648e6f43e504c0ba408f1b0c497c00deaef4f2cad99af66418b4126c893a281a041cb4
7
- data.tar.gz: de87233786cce3282bc3569c9e93e003ccb16b7ceb668c21c2fa43c64076b3f1ea1a1fbc44bc13d9fd3d59f38102d5160e17cdb89cff0794292e59c0bc343295
6
+ metadata.gz: 0bdc32c9fd9e5d09c666fc59690b38f5808383a676d3e40dbd026f0c97c2b3f00b79ad80c16b0defe34052df83a82e7e64c8e9f64195b376fb6190ba259c04a7
7
+ data.tar.gz: c5dedfae2bdbb103d435cc38673ac35a077ae60d6c480bded1c93b6ba4146bacfd7c98bf3c06b795e74261b86f51438c1b1a4b82dd525959213fc49b8ce6eb70
data/CHANGELOG.md CHANGED
@@ -5,6 +5,90 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [5.38.2] - 2026-10-29
9
+
10
+ ### Added
11
+
12
+ - **Every tool answer ends with one line** asking the AI to offer you a GitHub
13
+ issue when rails-ai-context itself answered wrong, missed something or
14
+ failed, or could do better. It comes once per answer (a composite tool's
15
+ parts leave it out), under a `_report` key in a JSON answer, and costs about
16
+ 40 tokens. `config.report_issue_line = false` leaves it out.
17
+ - **The root file says when model tests are not named the usual way.** An
18
+ app where more than a quarter of the model specs are named
19
+ `user_model_spec.rb` gets one clause on the test command line pointing at
20
+ `rails_get_test_info`. Agents had guessed `spec/models/user_spec.rb`; naming
21
+ both paths instead made them open the first without looking.
22
+
23
+ ### Changed
24
+
25
+ - **The root content is written once, into a file every chosen AI tool
26
+ reads.** Cursor reads `CLAUDE.md` and `AGENTS.md` as it reads its own
27
+ always-on rules, and VS Code Copilot attaches both beside
28
+ `copilot-instructions.md`, so a copy for each tool loaded the same text two
29
+ or three times in one session. `AGENTS.md` now carries it. `CLAUDE.md` holds
30
+ only `@AGENTS.md`, which Claude Code expands at launch, unless Claude Code is
31
+ the only tool chosen. `.github/copilot-instructions.md` stays a whole copy,
32
+ byte for byte the same as `AGENTS.md`, because most Copilot surfaces read no
33
+ other file. On a 149-model app the files Claude Code loads at session start
34
+ went from about 13,400 tokens to about 5,000.
35
+ - **`.cursorrules` is no longer written.** Cursor calls it legacy. A run
36
+ takes out the block an earlier release wrote and keeps your own lines; a
37
+ file that held only the block is deleted. Picking Cursor writes `AGENTS.md`.
38
+ - **The overview and tools rules are written only where no root file states
39
+ them,** that is with `generate_root_files = false`: `.claude/rules/rails-context.md`
40
+ and `rails-mcp-tools.md`, `.cursor/rules/rails-project.mdc` and
41
+ `rails-mcp-tools.mdc`, `.github/instructions/rails-context.instructions.md`
42
+ and `rails-mcp-tools.instructions.md`. A rules file an earlier run wrote and
43
+ this one does not is removed, and the run reports `Removed: <path>` or
44
+ `Removed the generated block from <path>`. `doctor` counts such a file as
45
+ out of date. The tools rule written then carries the root file's guide, loads
46
+ in every session in Cursor too, and no longer carries a table of every tool.
47
+ - **Every context file has a byte budget.** The compact root file stays within
48
+ 12,000 bytes as well as `claude_max_lines`, full mode within 24,000, a rules
49
+ file within 8,000 and a tools rule that stands in for the root file within
50
+ 12,000. A list line is at most 240 characters and ends with `...N more`; the
51
+ tools answer the rest, and a cut services or jobs list names the tool that has
52
+ it whole. A file cut to fit says so where the cut is. These files share the agent's context
53
+ with your own instructions, and Codex reads at most 32 KiB of project docs in
54
+ all.
55
+ - **The root file names its 10 most connected models,** each on one line, and
56
+ where a list is cut, says it is whole in `rails_get_model_details`.
57
+ - **The tools guide says each thing once and plainly.** Each example is in the
58
+ form the tool mode uses (MCP calls, or commands in CLI mode). There is one
59
+ Rules list, each rule with its reason, and no all-caps emphasis, which Claude
60
+ Code's docs say makes Claude over-apply a rule. Its first rule maps each
61
+ question a file read answers worse (a table's columns, a model's associations,
62
+ an action's filters, a model's tests) to the call that answers it. The tool
63
+ names are listed only in CLI mode, where `tool NAME --help` gives a command's
64
+ parameters, since an MCP client lists its tools itself. The six rules of the
65
+ protocol keep their wording minus the capitals, in the plugin's `rules.md` too.
66
+ - **The root file's app conventions are under `## Conventions`,** apart from
67
+ the tools guide's `### Rules`. The MCP fallback line says `tool --list` lists
68
+ the tools and `tool NAME --help` gives the parameters. A root file an earlier
69
+ run wrote for a tool the record does not name stays planned for, so it is
70
+ kept current instead of read stale beside a second copy.
71
+ - **Each rules file declares one scope** (always, by paths, or on request),
72
+ which one adapter per AI tool writes as `paths:`, `globs:` and `alwaysApply`,
73
+ or `applyTo`.
74
+
75
+ ### Fixed
76
+
77
+ - **On prism 1, an initializer that does not parse names the right line** for
78
+ an error that is not about a missing closer (an operator with nothing after
79
+ it named the `configure` line), and the `if` rather than its `elsif` for a
80
+ conditional left open.
81
+
82
+ ## [5.38.1] - 2026-10-29
83
+
84
+ ### Fixed
85
+
86
+ - **An app whose bundle resolves prism 2 can install this gem.** The gemspec
87
+ now takes `prism >= 1.4, < 3.0`, and a CI leg runs the suite on prism 2.1.0.
88
+ - **An initializer that does not parse names the line of the unclosed string,
89
+ heredoc, `def` or `if` under prism 2 too,** which reports a missing closer at
90
+ its opener. An error at the end of the input names the file's last line.
91
+
8
92
  ## [5.38.0] - 2026-10-27
9
93
 
10
94
  ### Security
data/README.md CHANGED
@@ -138,7 +138,7 @@ You catch it, fix it, re-prompt, and something next to it breaks. The tokens are
138
138
  | **35 read-only tools** | Schema, models, controllers, routes, views, Stimulus, Turbo, jobs, services, mailers, i18n, gems, config, tests, security, performance and more. Every answer comes from your app. |
139
139
  | **Answers it can trust** | Models are read with the Prism parser. A model and each scope carry `[VERIFIED]` or `[INFERRED]` (`[STATIC]` without a boot), so the assistant knows what still needs a runtime check. |
140
140
  | **Three ways in** | MCP over stdio, MCP mounted in your app over HTTP, or plain CLI in any terminal. |
141
- | **Context files per AI tool** | `CLAUDE.md`, Cursor rules, Copilot instructions, `AGENTS.md`, each with the MCP config its tool picks up, and six anti-hallucination rules up top. |
141
+ | **Context files per AI tool** | `CLAUDE.md`, Cursor rules, Copilot instructions, `AGENTS.md`, each with the MCP config its tool picks up, and six anti-hallucination rules. |
142
142
  | **Works on apps that won't boot** | Missing ENV vars, no database, a broken initializer: the tools answer from `config/routes.rb`, the schema dump and the source files, and say so. |
143
143
  | **Real app shapes** | Packwerk packs, in-repo engines, multi-database dumps, Mongoid, API-only apps, a folder holding several apps. |
144
144
  | **Read-only and careful** | SQL runs read-only with a timeout, a row limit and column redaction. Logs are redacted before they leave the process. Secrets files are never served. |
@@ -221,7 +221,7 @@ The legacy `rails://models/{name}` form is still accepted. Plus 9 static resourc
221
221
 
222
222
  <br>
223
223
 
224
- Each AI tool's main context file (`CLAUDE.md`, `AGENTS.md` for OpenCode and Codex, `.cursorrules` and `.cursor/rules/rails-mcp-tools.mdc` for Cursor, `.github/copilot-instructions.md`) starts with six rules the assistant reads before writing code, in compact and full mode alike. With `generate_root_files` off, `.claude/rules/rails-mcp-tools.md` and `.github/instructions/rails-mcp-tools.instructions.md` carry them instead:
224
+ The root context file carries six rules the assistant reads before writing code, in compact and full mode alike. That file is `AGENTS.md`, which Cursor, OpenCode and Codex read and `CLAUDE.md` imports, or `CLAUDE.md` itself when none of those three is chosen. Copilot reads its own copy in `.github/copilot-instructions.md`. With `generate_root_files` off, the `rails-mcp-tools` rules in `.claude/rules/`, `.cursor/rules/` and `.github/instructions/` carry them instead (Cursor loads its copy on request):
225
225
 
226
226
  1. Verify before you write. Never reference a column, association, route, helper, method, class, partial or gem that a tool call in this turn did not confirm.
227
227
  2. Mark every assumption with `[ASSUMPTION]`. "I'd need to check X first" is a good answer.
data/docs/ARCHITECTURE.md CHANGED
@@ -41,7 +41,7 @@ graph TD
41
41
  direction LR
42
42
  MCP["MCP Server\nstdio / HTTP\nResources\nVFS URIs"]
43
43
  CLI["CLI Runner\nRake / Thor\nSame 35 tools\nNo server needed"]
44
- S["Serializers\n18 modules\nStatic files\nPer-AI-tool"]
44
+ S["Serializers\n20 modules\nStatic files\nPer-AI-tool"]
45
45
  end
46
46
 
47
47
  style app fill:#4a9eff,stroke:#2d7ad4,color:#fff
@@ -196,28 +196,30 @@ Result: controller and view tools automatically include relevant schema informat
196
196
 
197
197
  ### Serializers (`lib/rails_ai_context/serializers/`)
198
198
 
199
- 18 modules that format introspection output for different AI tools:
199
+ 20 modules that format introspection output for different AI tools:
200
200
 
201
201
  | Serializer | Output |
202
202
  |:-----------|:-------|
203
- | `ClaudeSerializer` | `CLAUDE.md` |
203
+ | `ContextFileSerializer` | Writes a run's files: the root files the `LoadPlan` picks, each AI tool's rules, and the JSON dump |
204
+ | `LoadPlan` | Which root files the chosen AI tools get and what each holds: the root content, an `@AGENTS.md` import, or nothing, so the content is written once into a file every chosen tool reads (`AiTool#reads`) |
205
+ | `RootFile` | The root context file, the same bytes at every path it lands at (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`): compact, or full through `MarkdownSerializer` |
204
206
  | `ClaudeRulesSerializer` | `.claude/rules/*.md` |
205
- | `CursorRulesSerializer` | `.cursor/rules/*.mdc` AND `.cursorrules` (legacy chat-agent fallback) |
206
- | `CopilotSerializer` | `.github/copilot-instructions.md` |
207
+ | `CursorRulesSerializer` | `.cursor/rules/*.mdc`, and takes the block an earlier release wrote out of `.cursorrules` |
207
208
  | `CopilotInstructionsSerializer` | `.github/instructions/*.instructions.md` |
208
- | `OpencodeSerializer` | `AGENTS.md` (root) |
209
- | `OpencodeRulesSerializer` | `app/models/AGENTS.md`, `app/controllers/AGENTS.md` |
209
+ | `OpencodeRulesSerializer` | `app/models/AGENTS.md`, `app/controllers/AGENTS.md` (OpenCode and Codex) |
210
210
  | `JsonSerializer` | `.ai-context.json` |
211
- | `MarkdownSerializer` | Base formatting |
212
- | `ContextFileSerializer` | Atomic file writes with section markers |
213
- | `CompactSerializerHelper` | Compact mode (≤150 lines) |
214
- | `StackOverviewHelper` | Stack overview sections, and the rule-file write path four serializers share |
215
- | `ToolGuideHelper` | MCP/CLI tool reference sections |
216
- | `TestCommandDetection` | Test framework detection |
211
+ | `MarkdownSerializer` | The full-mode root file |
212
+ | `CompactSerializerHelper` | The compact root file's sections |
213
+ | `RuleScope` | When a rules file loads (every session, by path, or on request), written as each AI tool's frontmatter |
214
+ | `Budget` | Every size rule: the bytes per kind of file, the 240-character list line, and how many of each list a file names |
215
+ | `ModelSection` | The model list, rendered once at the density its file takes |
216
+ | `StackSections` | The header, gems, architecture and global before_actions, each rendered once at the density its file takes |
217
+ | `StackOverviewHelper` | Stack overview lines, the test command, and the rule-file write path four serializers share |
218
+ | `ToolGuideHelper` | The tools guide, each example in the one form the tool mode uses |
219
+ | `GuideExamples` | The model, controller and files the guide's examples name, the app's own where it has them |
217
220
  | `SectionFacts` | The facts every surface states about an app - auth, assets, associations, the filter chain, an unread entry's row, the static-tier notice - each rendered in one place |
218
- | `SectionMarkerWriter` | Writes a managed section into a file the user also owns |
219
- | `ContextModeDispatch` | Picks full or compact rendering for a run |
220
- | `Base` | Holds the context hash a serializer renders |
221
+ | `SectionMarkerWriter` | Writes a managed section into a file the user also owns, and takes one out |
222
+ | `Base` | Holds the context hash a serializer renders, and the run's `LoadPlan` |
221
223
 
222
224
  ### CLI (`exe/rails-ai-context`, `lib/rails_ai_context/cli/`)
223
225
 
@@ -20,7 +20,7 @@ document is aspirational.
20
20
  - **mcp gem:** `>= 0.13, < 2.0`
21
21
  - **thor:** `>= 1.2, < 3.0` (1.0 and 1.1 fail to load on Ruby 3.1+: they
22
22
  reference `DidYouMean::SPELL_CHECKERS`, which did_you_mean removed)
23
- - **prism:** `>= 1.4, < 2.0` (a CI leg pins the floor exactly and runs the suite against it)
23
+ - **prism:** `>= 1.4, < 3.0` (CI legs pin 1.4.0 and 2.1.0 exactly on Ruby 3.2 and run the suite against each)
24
24
  - **concurrent-ruby:** `>= 1.2, < 3.0`
25
25
  - **zeitwerk:** `~> 2.5` (2.5 is what railties 7.0 allows; a CI leg pins 2.5.0 on Rails 7.0 and Ruby 3.1)
26
26
  - **json:** unconstrained by this gem, but `json >= 3.0` and Rails 7.0 to 8.0 do
@@ -87,11 +87,12 @@ empty list wrote every tool's files.
87
87
  | Option | Type | Default | Description |
88
88
  |:-------|:-----|:--------|:------------|
89
89
  | `preset` | Symbol | `:full` | `:full` (40 introspectors) or `:standard` (17 introspectors) |
90
- | `context_mode` | Symbol | `:compact` | `:compact` (context files capped at ~150 lines) or `:full` (no line cap). Any other value is refused, and so is any other `CONTEXT_MODE` on a rake task |
90
+ | `context_mode` | Symbol | `:compact` | `:compact` (the root file within `claude_max_lines` lines and 12,000 bytes) or `:full` (no line cap, all introspection data within 24,000 bytes). Any other value is refused, and so is any other `CONTEXT_MODE` on a rake task |
91
91
  | `introspectors` | Array of symbols | (from preset) | Override the introspector list directly |
92
- | `generate_root_files` | Boolean | `true` | Set `false` to generate split rules only: no CLAUDE.md, AGENTS.md, .cursorrules or copilot-instructions.md (`.ai-context.json` is still written) |
92
+ | `generate_root_files` | Boolean | `true` | Set `false` to generate split rules only: no CLAUDE.md, AGENTS.md or copilot-instructions.md, and the overview and tools rules are written in their place (`.ai-context.json` is still written) |
93
93
  | `anti_hallucination_rules` | Boolean | `true` | Embed 6-rule verification protocol in generated context files |
94
- | `claude_max_lines` | Integer | `150` | Budget for the non-blank lines of a compact context file's gem-managed block, the `<!-- BEGIN/END rails-ai-context -->` markers included. Over budget, the data sections (Stack, Key models, Gems, Architecture) are cut first, down to none; the title and the Commands, Warnings, Rules and Tools sections are never cut, so they set the smallest file a budget can give (about 110 lines with the anti-hallucination protocol). Must be positive |
94
+ | `report_issue_line` | Boolean | `true` | End every tool answer with one line asking the AI to offer you a GitHub issue when rails-ai-context answered wrong, missed something or failed |
95
+ | `claude_max_lines` | Integer | `150` | Budget for the non-blank lines of the compact root file's gem-managed block, the `<!-- BEGIN/END rails-ai-context -->` markers included, beside its 12,000 bytes. Over budget, the data sections (Stack, Key models, Gems, Architecture) are cut from the bottom, down to none; the title and the Commands, Warnings, Rules and Tools sections are never cut, so they set the smallest file a budget can give (about 70 lines with the anti-hallucination protocol). Must be positive |
95
96
 
96
97
  ### MCP Server
97
98
 
@@ -296,11 +297,13 @@ Lightweight subset for faster generation:
296
297
  | AI Tool | Root File | Split Rules | MCP Config |
297
298
  |:--------|:----------|:------------|:-----------|
298
299
  | Claude Code | `CLAUDE.md` | `.claude/rules/*.md` | `.mcp.json` |
299
- | Cursor | `.cursorrules` (legacy fallback) | `.cursor/rules/*.mdc` | `.cursor/mcp.json` |
300
+ | Cursor | `AGENTS.md` | `.cursor/rules/*.mdc` | `.cursor/mcp.json` |
300
301
  | GitHub Copilot | `.github/copilot-instructions.md` | `.github/instructions/*.instructions.md` | `.vscode/mcp.json` |
301
302
  | OpenCode | `AGENTS.md` | `app/models/AGENTS.md`, `app/controllers/AGENTS.md` | `opencode.json` |
302
303
  | Codex CLI | (shares `AGENTS.md`) | (shares OpenCode rules) | `.codex/config.toml` |
303
304
 
305
+ The root content is written once, into a file every chosen tool reads: `AGENTS.md` when Cursor, OpenCode or Codex CLI is chosen, with `CLAUDE.md` holding only `@AGENTS.md`, and Copilot's identical copy beside it. With `generate_root_files` off, the Claude Code, Cursor and Copilot rules carry the overview and the tools guide instead. See [Generated Files](GUIDE.md#generated-files).
306
+
304
307
  ---
305
308
 
306
309
  ## Examples
data/docs/CUSTOM_TOOLS.md CHANGED
@@ -80,7 +80,7 @@ if defined?(RailsAiContext) && RailsAiContext.respond_to?(:configure)
80
80
  end
81
81
  ```
82
82
 
83
- Custom tools appear alongside built-in tools in the MCP server and CLI, and in the tool counts and lists of the generated context files. The tools table gives a custom tool its own row, described by the first sentence of its `description`.
83
+ Custom tools appear alongside built-in tools in the MCP server and CLI, and in the tool counts of the generated context files. In CLI mode the root file's list of commands names them too; in MCP mode the client lists them with their descriptions.
84
84
 
85
85
  Use the class *name* as a string: classes under `app/` (including
86
86
  `app/mcp_tools/`) are not autoloadable while initializers run, so a bare
data/docs/FAQ.md CHANGED
@@ -65,7 +65,7 @@ Yes. Run `rails-ai-context init` in that folder. It asks once, gives each app it
65
65
 
66
66
  **Yes, commit these:**
67
67
  - `.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`, `opencode.json` - so teammates get the MCP server after approving it once in their AI tool
68
- - `CLAUDE.md`, `.claude/rules/`, `.cursor/rules/`, `.cursorrules`, `.github/copilot-instructions.md`, `.github/instructions/`, `AGENTS.md` - so AI has context
68
+ - `CLAUDE.md`, `.claude/rules/`, `.cursor/rules/`, `.github/copilot-instructions.md`, `.github/instructions/`, `AGENTS.md` - so AI has context
69
69
  - `config/initializers/rails_ai_context.rb`, `.rails-ai-context.yml` - so config is shared
70
70
 
71
71
  **Don't commit:**
@@ -133,8 +133,8 @@ PostgreSQL, MySQL (with MariaDB) and SQLite. Each gets database-specific safety
133
133
 
134
134
  ### What's `:compact` vs `:full` context mode?
135
135
 
136
- - **`:compact`** (default) - context files capped at ~150 lines. Optimized for AI context windows.
137
- - **`:full`** - no line cap. All introspection data included.
136
+ - **`:compact`** (default) - the root file stays within 150 non-blank lines (`claude_max_lines`) and 12,000 bytes, and names the 10 most connected models. The tools answer the rest.
137
+ - **`:full`** - no line cap. All introspection data, within 24,000 bytes, cut from the bottom when it does not fit.
138
138
 
139
139
  ### Can I use YAML config with the Gemfile approach?
140
140
 
@@ -142,7 +142,7 @@ Yes. The file is applied first and a `configure` block wins only the keys it ass
142
142
 
143
143
  ### What's `generate_root_files`?
144
144
 
145
- When `true` (default), generates the root files: CLAUDE.md, AGENTS.md, .cursorrules and copilot-instructions.md. Set to `false` to only generate split rules (.claude/rules/, .cursor/rules/, etc.). `.ai-context.json` is written either way.
145
+ When `true` (default), generates the root files the chosen AI tools read: AGENTS.md, CLAUDE.md and copilot-instructions.md. Set to `false` to only generate split rules (.claude/rules/, .cursor/rules/, etc.), which then carry the project overview and the tools guide too. `.ai-context.json` is written either way.
146
146
 
147
147
  ---
148
148
 
@@ -155,11 +155,13 @@ Depends on your `ai_tools` config. For all tools:
155
155
  | AI Tool | Files |
156
156
  |:--------|:------|
157
157
  | Claude | CLAUDE.md, .claude/rules/*.md |
158
- | Cursor | .cursor/rules/*.mdc AND .cursorrules (legacy fallback for chat agent) |
158
+ | Cursor | AGENTS.md, .cursor/rules/*.mdc |
159
159
  | Copilot | .github/copilot-instructions.md, .github/instructions/*.instructions.md |
160
160
  | OpenCode | AGENTS.md, app/models/AGENTS.md, app/controllers/AGENTS.md |
161
161
  | Codex | Shares AGENTS.md and OpenCode rules |
162
162
 
163
+ The root content is written once, into a file every chosen tool reads. `AGENTS.md` carries it when Cursor, OpenCode or Codex is chosen, and `CLAUDE.md` then holds only `@AGENTS.md`, which Claude Code expands at launch. Copilot keeps an identical copy in `.github/copilot-instructions.md`. `.cursorrules` is no longer written, and a run with root files on takes out the block an earlier release wrote there and keeps your own lines. See [Generated Files](GUIDE.md#generated-files).
164
+
163
165
  ### How do I regenerate context files?
164
166
 
165
167
  ```bash
@@ -255,13 +257,15 @@ Check that your Rails app boots (`rails runner "puts 'ok'"`) and that schema/mod
255
257
 
256
258
  ### Context files are too large
257
259
 
258
- Use compact mode (default) or disable root files:
260
+ Use compact mode (default), and lower `claude_max_lines` for a shorter root file:
259
261
 
260
262
  ```ruby
261
263
  config.context_mode = :compact
262
- config.generate_root_files = false
264
+ config.claude_max_lines = 100
263
265
  ```
264
266
 
267
+ Every file already has a byte budget ([Generated Files](GUIDE.md#generated-files)). Turning root files off does not shrink what Claude Code and Copilot load: the overview and the whole tools guide move into rules files they load in every session.
268
+
265
269
  ---
266
270
 
267
271
  <div align="center" markdown="1">
data/docs/GUIDE.md CHANGED
@@ -97,7 +97,7 @@ No Gemfile entry, no initializer, no files in your project besides config and co
97
97
 
98
98
  ```
99
99
  1. Claude Code -> CLAUDE.md + .claude/rules/
100
- 2. Cursor -> .cursor/rules/ + .cursorrules (legacy fallback)
100
+ 2. Cursor -> AGENTS.md + .cursor/rules/
101
101
  3. GitHub Copilot -> .github/copilot-instructions.md + .github/instructions/
102
102
  4. OpenCode -> AGENTS.md
103
103
  5. Codex CLI -> AGENTS.md + .codex/config.toml
@@ -120,7 +120,7 @@ No Gemfile entry, no initializer, no files in your project besides config and co
120
120
  6. **Writes `.rails-ai-context.yml`** with `ai_tools`, `tool_mode` and `context_files`. Only a key whose value changed is rewritten, where it stands; your comments and other keys are kept, and a run that changes no value leaves the file as it was.
121
121
  7. **Adds lines to `.gitignore`**, if the file exists: `.ai-context.json` (not for choice 3) and `.codex/config.toml` (always, because it holds this machine's Ruby paths). A line that is already there is not added again.
122
122
  8. **Asks about a pre-commit hook:** `Install a pre-commit hook that checks staged Ruby, ERB and JavaScript files for syntax errors? (y/N)`. Only `y` installs it. The hook runs `bundle exec rails-ai-context tool validate` (`rails-ai-context tool validate` in a standalone install) on the staged `.rb`, `.erb`, `.js`, `.mjs` and `.cjs` files and stops a commit whose files do not parse (JavaScript is parsed by `node`, as [`rails_validate`](TOOLS.md#rails_validate) describes); the Rails-reference checks (`level=rails`) are left to the tool, as Brakeman would slow every commit. An app that cannot boot (an initializer that needs a variable the shell lacks, say) is still checked, from its source, and the hook shows why it did not boot; it shows whatever else the check prints to stderr too, so a check that cannot run says why. Every staged name is read whole, one with characters outside ASCII included; a name holding a comma, which the files list cannot carry, is named and left unchecked. It goes where git runs hooks (`git rev-parse --git-path hooks`), so an app checked out as a submodule, an app inside a monorepo and a repo with `core.hooksPath` set all get it where git will run it. The hook names the apps it covers and validates each one's staged files (deleted ones aside) from inside that app; installing in a second app of the same monorepo adds it to the hook, unless the hook was changed by hand, which it says, and for an app below the top of the repository the question names the repository. A hook an earlier version wrote, and nobody changed since, is brought up to date without asking again: the oldest handed validate the files a commit deletes too, and the commit failed on them, and later ones ran `rails 'ai:tool[validate]'`, which has to boot the app, with its errors thrown away, so an app that could not boot failed every commit with no reason given. Any other hook that runs `rails-ai-context` - one changed by hand, or a team's own that calls it among other checks - is left as it is, with a message. No hook is offered for an app the repository does not track yet (an app under a dotfiles repository at `$HOME`, say), nor into a `core.hooksPath` outside the repository, which every repository using it shares; both say why. No question is asked outside a git repository or when the hook already covers the app. When another `pre-commit` hook exists there it prints `Skipped pre-commit hook (existing hook found - add manually)` and moves on.
123
- 9. **Generates the context files** for the selected tools. Skipped for choice 3. If files that v5.0.0 stopped generating are still there (`.claude/rules/rails-ui-patterns.md`, `.claude/rules/rails-accessibility.md`, `.cursor/rules/rails-ui-patterns.mdc`, `.github/instructions/rails-ui-patterns.instructions.md`), it lists them first and asks `Delete them? [y/N]:`. Without a terminal, or under `--defaults`, it prints the `rm` command and does not ask; under `--prune` it deletes them without asking.
123
+ 9. **Generates the context files** for the selected tools. Skipped for choice 3. If files that v5.0.0 stopped generating are still there (`.claude/rules/rails-ui-patterns.md`, `.claude/rules/rails-accessibility.md`, `.cursor/rules/rails-ui-patterns.mdc`, `.github/instructions/rails-ui-patterns.instructions.md`), it lists them first and asks `Delete them? [y/N]:`. Without a terminal, or under `--defaults`, it prints the `rm` command and does not ask; under `--prune` it deletes them without asking. Files an earlier run wrote that this run no longer writes go without a question, and the output names them: the block in `.cursorrules`, and an overview or tools rule the root file states ([Generated Files](#generated-files)).
124
124
  10. **Prints a summary:** the files each selected tool got, the commands to run next, and, in the MCP setup, each tool's next step: the approval or trust step that tool asks for before it starts a project's MCP server (approve the server in Claude Code, turn it on in Cursor, trust the folder in VS Code and Codex CLI, restart OpenCode).
125
125
 
126
126
  Every question has a flag, so an AI tool or a script can run the install to the end with nobody at the keyboard (the [copy-paste prompts](PROMPTS.md) are built on them):
@@ -173,11 +173,18 @@ The gem has two context modes that control how much data goes into the generated
173
173
  rails ai:context
174
174
  ```
175
175
 
176
- - CLAUDE.md, AGENTS.md, .cursorrules and copilot-instructions.md ≤150 non-blank
177
- lines (`claude_max_lines`). Over budget, the data sections are cut first; the
178
- title and the Commands, Warnings, Rules and Tools sections are never cut, so a
179
- budget smaller than they are (about 110 lines) leaves just them
180
- - Files contain a project overview + MCP tool reference
176
+ - The root file (AGENTS.md, CLAUDE.md or copilot-instructions.md) stays within
177
+ 12,000 bytes and `claude_max_lines` (150) non-blank lines. Over budget, the
178
+ data sections are cut from the bottom; the title and the Commands, Warnings,
179
+ Rules and Tools sections are never cut, so a budget smaller than they are
180
+ (about 70 lines) leaves just them
181
+ - It names the 10 most connected models. A list names what fits a 240-character
182
+ line and ends with "...N more"; the tools answer the rest
183
+ - It holds a project overview and the tools guide. The guide gives each example
184
+ in the one form the tool mode uses (an MCP call, or a command in `:cli` mode)
185
+ and has one Rules list with no ALL-CAPS emphasis, since Claude Code's docs say
186
+ piled-on emphasis makes Claude over-apply a rule. It lists the tool names only
187
+ in `:cli` mode: an MCP client lists the tools itself
181
188
  - AI uses MCP tools for detailed data on-demand
182
189
  - **Best for:** all apps, especially large ones (30+ models)
183
190
 
@@ -189,22 +196,24 @@ rails ai:context:full
189
196
  CONTEXT_MODE=full rails ai:context
190
197
  ```
191
198
 
192
- - Dumps everything into the root files CLAUDE.md, AGENTS.md and copilot-instructions.md: every table with its column types, defaults, indexes and foreign keys; every model with its associations, validations, scopes, callbacks, enum values and constants; the app's own routes (the framework's are counted, not listed); Stimulus controllers; and the rest of the introspection. The split rule files and Cursor's files are the same in both modes
193
- - Each root file ends with the same tools guide and anti-hallucination protocol the compact files carry, so OpenCode and Codex, which read AGENTS.md alone, get them too
199
+ - Puts the whole introspection into the root file: every table with its column types, defaults, indexes and foreign keys; every model with its associations, validations, scopes, callbacks, enum values and constants; the app's own routes (the framework's are counted, not listed); Stimulus controllers; and the rest of the introspection. The rules files are the same in both modes
200
+ - The file stays within 24,000 bytes. A large app's data sections are cut from the bottom, with a note that the tools answer the rest; the header, the rules, the tools guide and the last line are never cut
201
+ - The root file ends with the same tools guide and anti-hallucination protocol the compact file carries, so OpenCode and Codex, which read AGENTS.md alone, get them too
194
202
  - A plain `rails ai:context` writes compact files again unless `config.context_mode` is `:full`, so each file's last line names the command that keeps full mode: `CONTEXT_MODE=full rails ai:context`, or for a standalone install `rails-ai-context context`, which reads `context_mode` from `.rails-ai-context.yml`
195
- - Can produce thousands of lines for large apps
196
- - **Best for:** small apps (<30 models) where the full dump fits in context
203
+ - **Best for:** small apps (<30 models), whose full dump fits the budget
197
204
 
198
205
  ### Per-format with mode override
199
206
 
200
207
  ```bash
201
- # Full dump for Claude only, compact for everything else
208
+ # Full dump in the root file Claude Code reads
202
209
  CONTEXT_MODE=full rails ai:context:claude
203
210
 
204
211
  # Full dump for Copilot only
205
212
  CONTEXT_MODE=full rails ai:context:copilot
206
213
  ```
207
214
 
215
+ Where `CLAUDE.md` imports `AGENTS.md`, the first command writes the full dump into `AGENTS.md`, which Cursor, OpenCode and Codex read too.
216
+
208
217
  ### Set mode in configuration
209
218
 
210
219
  ```ruby
@@ -220,26 +229,32 @@ end
220
229
 
221
230
  ## Generated Files
222
231
 
223
- `rails ai:context` generates **20 files** across all AI assistants:
232
+ `rails ai:context` generates **19 files** across all AI assistants. No run writes all of them: the three root files are written while `generate_root_files` is on (the default), and the six overview and tools rules only when it is off, since the root file states them otherwise.
233
+
234
+ The root content is written once, into a file every chosen AI tool reads. `AGENTS.md` carries it when Cursor, OpenCode or Codex is chosen: Cursor reads `AGENTS.md` and `CLAUDE.md` as it reads its own always-on rules ([Cursor](https://cursor.com/help/customization/rules#how-does-claudemd-work-in-cursor)). `CLAUDE.md` then holds only `@AGENTS.md`, an import Claude Code expands at launch ([Claude Code](https://code.claude.com/docs/en/memory#import-additional-files)); without those three, `CLAUDE.md` carries the content itself. `.github/copilot-instructions.md` gets an identical copy, since github.com chat, Visual Studio, JetBrains, Xcode and code review read no other file ([GitHub](https://docs.github.com/en/copilot/reference/custom-instructions-support)), and Copilot CLI drops identical copies.
235
+
236
+ Every file has a byte budget: 12,000 bytes for a compact root file, 24,000 in full mode, 8,000 for a rule file, and 12,000 for a tools rule that stands in for the root file. It is low on purpose, since these files share the agent's context with your own instructions, and Codex reads at most 32 KiB of project docs in all. A list names what fits a 240-character line and ends with "...N more"; the tools answer the rest.
224
237
 
225
- A file whose section has nothing in it is not written. An app with no models gets no `.claude/rules/rails-models.md`, and every surface names the file and the reason so a deliberate omission is not mistaken for a failed run. `rails ai:context` and the installer print `➖ .claude/rules/rails-models.md (no models)`; the CLI and the watcher print `Not applicable: .claude/rules/rails-models.md (no models)`.
238
+ A file whose section has nothing in it is not written. An app with no models gets no `.claude/rules/rails-models.md`, and every surface names the file and the reason so a deliberate omission is not mistaken for a failed run. `rails ai:context` and the installer print `➖ .claude/rules/rails-models.md (no models)`; the CLI and the watcher print `Not applicable: .claude/rules/rails-models.md (no models)`. A rule the root file states is named the same way, with the reason `in the root file`.
239
+
240
+ A run removes the files an earlier run wrote that it no longer writes. The CLI and the watcher print `Removed: PATH`, or `Removed the generated block from PATH` where your own lines stay; `rails ai:context` and the installer mark it `(removed)` or `(generated block removed)`. `doctor` counts a file a run would remove as out of date.
226
241
 
227
242
  ### Claude Code (6 files)
228
243
 
229
244
  | File | Purpose | Notes |
230
245
  |------|---------|-------|
231
- | `CLAUDE.md` | Main context file | ≤150 lines in compact mode. Claude Code reads this automatically. |
232
- | `.claude/rules/rails-schema.md` | Database table listing | Every database's tables, each database under its own heading when the app has more than one. A database of Solid Queue, Solid Cache or Solid Cable tables only, as Rails 8's queue, cache and cable are, is named in CLAUDE.md instead (`queue: Solid Queue (13 tables)`). Loaded when Claude Code opens a schema dump or a migration. |
233
- | `.claude/rules/rails-models.md` | Model listing with associations | Auto-loaded by Claude Code alongside CLAUDE.md. |
234
- | `.claude/rules/rails-context.md` | Project context and conventions | Auto-loaded by Claude Code alongside CLAUDE.md. |
235
- | `.claude/rules/rails-mcp-tools.md` | Tool reference | Detail levels and the table of every tool. Loaded beside CLAUDE.md, which carries the protocol, the workflows and the rules, so they are not read twice; with `generate_root_files` off it carries them itself. |
236
- | `.claude/rules/rails-components.md` | View component listing | Written only when the app has view components. |
246
+ | `CLAUDE.md` | Root context file | Holds only `@AGENTS.md` where `AGENTS.md` carries the root content, and the content itself otherwise. Claude Code reads it at launch. |
247
+ | `.claude/rules/rails-schema.md` | Database table listing | Every database's tables, each database under its own heading when the app has more than one. A database of Solid Queue, Solid Cache or Solid Cable tables only, as Rails 8's queue, cache and cable are, is named in the root file instead (`queue: Solid Queue (13 tables)`). Loaded when Claude Code opens a schema dump or a migration. |
248
+ | `.claude/rules/rails-models.md` | Model listing with associations | Loaded when Claude Code opens a file in `app/models/`. |
249
+ | `.claude/rules/rails-context.md` | Project overview | Written only with `generate_root_files` off. Loaded in every session. |
250
+ | `.claude/rules/rails-mcp-tools.md` | Tools guide | Written only with `generate_root_files` off. Loaded in every session: the protocol, the workflows and the rules, as the root file carries them. |
251
+ | `.claude/rules/rails-components.md` | View component listing | Written only when the app has view components. Loaded when Claude Code opens a file in `app/components/` or `app/views/components/`. |
237
252
 
238
253
  ### OpenCode (3 files)
239
254
 
240
255
  | File | Purpose | Notes |
241
256
  |------|---------|-------|
242
- | `AGENTS.md` | Main context file | Native OpenCode format. ≤150 lines in compact mode. OpenCode also reads CLAUDE.md as fallback. |
257
+ | `AGENTS.md` | Root context file | Carries the root content for OpenCode, Codex and Cursor, and for Claude Code through the import in `CLAUDE.md`. OpenCode reads CLAUDE.md only where there is no AGENTS.md. |
243
258
  | `app/models/AGENTS.md` | Model reference | Auto-loaded by OpenCode when reading files in `app/models/`. One you wrote yourself keeps its text, with the listing added between markers. |
244
259
  | `app/controllers/AGENTS.md` | Controller reference | Auto-loaded by OpenCode when reading files in `app/controllers/`. One you wrote yourself keeps its text, with the listing added between markers. |
245
260
 
@@ -247,21 +262,23 @@ A file whose section has nothing in it is not written. An app with no models get
247
262
 
248
263
  | File | Purpose | Notes |
249
264
  |------|---------|-------|
250
- | `.cursor/rules/rails-project.mdc` | Project overview | `alwaysApply: true` - loaded in every conversation. |
265
+ | `AGENTS.md` | Root context file | The file OpenCode and Codex read too. Cursor reads it, and `CLAUDE.md`, like an always-on rule. |
266
+ | `.cursor/rules/rails-project.mdc` | Project overview | `alwaysApply: true` - loaded in every conversation. Written only with `generate_root_files` off. |
251
267
  | `.cursor/rules/rails-models.mdc` | Model reference | `globs: app/models/**/*.rb` - auto-attaches when editing models. |
252
268
  | `.cursor/rules/rails-controllers.mdc` | Controller reference | `globs: app/controllers/**/*.rb` - auto-attaches when editing controllers. |
253
- | `.cursor/rules/rails-mcp-tools.mdc` | MCP tool reference | `alwaysApply: false` - agent-requested when relevant. |
254
- | `.cursorrules` | Legacy fallback | Read by older Cursor clients. Wrapped in markers, so hand-written content around it survives. |
269
+ | `.cursor/rules/rails-mcp-tools.mdc` | Tools guide | `alwaysApply: false` - agent-requested when relevant. Written only with `generate_root_files` off. |
270
+
271
+ `.cursorrules` is no longer written: Cursor calls it legacy, and reads the content from `AGENTS.md`. With root files on, a run takes out the block an earlier release wrote there and keeps your own lines; a file that held only the block is deleted. Cleanup and `doctor` still know the file.
255
272
 
256
273
  ### GitHub Copilot (5 files)
257
274
 
258
275
  | File | Purpose | Notes |
259
276
  |------|---------|-------|
260
- | `.github/copilot-instructions.md` | Repo-wide instructions | ≤`claude_max_lines` (150) non-blank lines in compact mode, markers included. |
277
+ | `.github/copilot-instructions.md` | Root context file | An identical copy where `AGENTS.md` or `CLAUDE.md` carries the root content too, since github.com chat, Visual Studio, JetBrains, Xcode and code review read no other file. |
261
278
  | `.github/instructions/rails-models.instructions.md` | Model context | `applyTo: app/models/**/*.rb` - loaded when editing models. |
262
279
  | `.github/instructions/rails-controllers.instructions.md` | Controller context | `applyTo: app/controllers/**/*.rb` - loaded when editing controllers. |
263
- | `.github/instructions/rails-context.instructions.md` | Project context and conventions | `applyTo: **/*` - loaded everywhere. |
264
- | `.github/instructions/rails-mcp-tools.instructions.md` | Tool reference | `applyTo: **/*` - loaded everywhere. Detail levels and the table; the protocol and workflows are in copilot-instructions.md, or here too with `generate_root_files` off. |
280
+ | `.github/instructions/rails-context.instructions.md` | Project overview | `applyTo: **/*` - loaded everywhere. Written only with `generate_root_files` off. |
281
+ | `.github/instructions/rails-mcp-tools.instructions.md` | Tools guide | `applyTo: **/*` - loaded everywhere but code review. Written only with `generate_root_files` off. |
265
282
 
266
283
  ### Generic (1 file)
267
284
 
@@ -290,19 +307,19 @@ unmarked file was generated with the app running.
290
307
 
291
308
  | Command | Mode | Format | Description |
292
309
  |---------|------|--------|-------------|
293
- | `rails ai:context` | compact | all | Generate all 20 context files |
310
+ | `rails ai:context` | compact | all | Generate all 19 context files |
294
311
  | `rails ai:context:full` | full | all | Generate all files in full mode |
295
- | `rails ai:context:claude` | compact | Claude | CLAUDE.md + .claude/rules/ |
312
+ | `rails ai:context:claude` | compact | Claude | CLAUDE.md + .claude/rules/, and the AGENTS.md it imports when Cursor, OpenCode or Codex is selected too |
296
313
  | `rails ai:context:opencode` | compact | OpenCode | AGENTS.md + per-directory AGENTS.md |
297
314
  | `rails ai:context:codex` | compact | Codex | AGENTS.md + per-directory AGENTS.md (same files as OpenCode), and `.codex/config.toml` in MCP mode |
298
- | `rails ai:context:cursor` | compact | Cursor | .cursor/rules/ |
315
+ | `rails ai:context:cursor` | compact | Cursor | AGENTS.md + .cursor/rules/ |
299
316
  | `rails ai:context:copilot` | compact | Copilot | copilot-instructions.md + .github/instructions/ |
300
317
  | `rails ai:context:json` | - | JSON | .ai-context.json |
301
- | `CONTEXT_MODE=full rails ai:context:claude` | full | Claude | Full dump for Claude only |
302
- | `CONTEXT_MODE=full rails ai:context:opencode` | full | OpenCode | Full dump in AGENTS.md, which Codex reads too |
318
+ | `CONTEXT_MODE=full rails ai:context:claude` | full | Claude | Full dump in the root file Claude Code reads |
319
+ | `CONTEXT_MODE=full rails ai:context:opencode` | full | OpenCode | Full dump in AGENTS.md, which Codex and Cursor read too |
303
320
  | `CONTEXT_MODE=full rails ai:context:copilot` | full | Copilot | Full dump for Copilot only |
304
321
 
305
- Cursor's files are the same in both modes, so `CONTEXT_MODE=full` changes nothing for `rails ai:context:cursor`.
322
+ The rules files are the same in both modes, so `CONTEXT_MODE=full` changes only the root file.
306
323
 
307
324
  Each `rails ai:context:<tool>` adds its tool to the recorded selection and, in MCP mode, writes that tool's MCP config too (`.cursor/mcp.json` for Cursor), since its files tell the AI to call the MCP tools.
308
325
 
@@ -430,10 +447,10 @@ if defined?(RailsAiContext) && RailsAiContext.respond_to?(:configure)
430
447
  end
431
448
  ```
432
449
 
433
- - **`:mcp`** - context files show MCP tool syntax (e.g. `rails_get_schema(table: "users")`). CLI tools still available as fallback.
434
- - **`:cli`** - context files show CLI syntax (e.g. `rails 'ai:tool[schema]' table=users`). No MCP server required. Every file follows it: the root files, the split rule files and OpenCode's per-directory `AGENTS.md`, whose tools rule files then describe the CLI tools.
450
+ - **`:mcp`** - context files show MCP tool syntax (e.g. `rails_get_schema(table: "users")`), each example in that form alone. The root file names the CLI fallback once and lists no tool names, since the MCP client lists the tools itself.
451
+ - **`:cli`** - context files show CLI syntax (e.g. `rails 'ai:tool[schema]' table=users`). No MCP server required. Every file follows it: the root files, the split rule files and OpenCode's per-directory `AGENTS.md`, whose tools rule files then describe the CLI tools. The root file lists the tool names, since nothing else does.
435
452
 
436
- Every tool count and list in the generated files is the set the server serves: the built-in tools `skip_tools` leaves, plus `custom_tools`. A custom tool gets a row in the tools table with the first sentence of its description. A workflow step, rule or pointer whose tool is skipped is left out, or said without the tool (with `rails_get_context` skipped, the model workflow starts from `rails_get_model_details`), so no file sends the AI to a tool the server does not serve.
453
+ Every tool count and list in the generated files is the set the server serves: the built-in tools `skip_tools` leaves, plus `custom_tools`. In CLI mode the root file's list of commands names a custom tool too; in MCP mode the client lists every tool itself. A workflow step, rule or pointer whose tool is skipped is left out, or said without the tool (with `rails_get_context` skipped, the model workflow starts from `rails_get_model_details`), so no file sends the AI to a tool the server does not serve.
437
454
 
438
455
  The workflow examples name the app's own most connected model, one of its controllers, a template and a partial it renders. An app with none of one gets an obvious placeholder (`YourModel`, `shared/your_partial`) rather than a name that reads like the app's.
439
456
 
@@ -1296,7 +1313,7 @@ if defined?(RailsAiContext) && RailsAiContext.respond_to?(:configure)
1296
1313
  # Context mode: :compact (default) or :full
1297
1314
  config.context_mode = :compact
1298
1315
 
1299
- # Max lines for CLAUDE.md in compact mode
1316
+ # Max non-blank lines for the root file in compact mode
1300
1317
  config.claude_max_lines = 150
1301
1318
 
1302
1319
  # Output directory for context files (default: Rails.root)
@@ -1410,7 +1427,7 @@ end
1410
1427
  | `preset` | Symbol | `:full` | Introspector preset (`:full` or `:standard`) |
1411
1428
  | `introspectors` | Array | 40 (full preset) | Which introspectors to run |
1412
1429
  | `context_mode` | Symbol | `:compact` | `:compact` or `:full` |
1413
- | `claude_max_lines` | Integer | `150` | Budget for the non-blank lines of a compact context file's gem-managed block, the `<!-- BEGIN/END rails-ai-context -->` markers included. Over budget, the data sections (Stack, Key models, Gems, Architecture) are cut first, down to none; the title and the Commands, Warnings, Rules and Tools sections are never cut, so they set the smallest file a budget can give (about 110 lines with the anti-hallucination protocol) |
1430
+ | `claude_max_lines` | Integer | `150` | Budget for the non-blank lines of the compact root file's gem-managed block, the `<!-- BEGIN/END rails-ai-context -->` markers included, beside its 12,000 bytes. Over budget, the data sections (Stack, Key models, Gems, Architecture) are cut from the bottom, down to none; the title and the Commands, Warnings, Rules and Tools sections are never cut, so they set the smallest file a budget can give (about 70 lines with the anti-hallucination protocol) |
1414
1431
  | `max_tool_response_chars` | Integer | `200_000` | Safety cap for MCP tool responses and resource payloads |
1415
1432
  | `cache_ttl` | Integer | `60` | Cache TTL in seconds for introspection results |
1416
1433
  | `custom_tools` | Array | `[]` | Additional MCP tool classes to register alongside built-in tools |
@@ -1430,8 +1447,9 @@ end
1430
1447
  | `live_reload_debounce` | Float | `1.5` | Debounce interval in seconds for live reload |
1431
1448
  | `server_name` | String | `"rails-ai-context"` | The MCP server name the server announces. When it is left at the default, the `RAILS_AI_CONTEXT_SERVER_NAME` environment variable takes its place for one process, which is how a workspace's entries announce their app |
1432
1449
  | `server_version` | String | gem version | MCP server version. Read-only, there is no setter |
1433
- | `generate_root_files` | Boolean | `true` | Set `false` to generate split rules only: no CLAUDE.md, AGENTS.md, .cursorrules or copilot-instructions.md (`.ai-context.json` is still written) |
1450
+ | `generate_root_files` | Boolean | `true` | Set `false` to generate split rules only: no CLAUDE.md, AGENTS.md or copilot-instructions.md, and the overview and tools rules are written in their place (`.ai-context.json` is still written) |
1434
1451
  | `anti_hallucination_rules` | Boolean | `true` | Embed 6-rule Anti-Hallucination Protocol in generated context files - set `false` to skip |
1452
+ | `report_issue_line` | Boolean | `true` | End every tool answer with one line asking the AI to offer you a GitHub issue when rails-ai-context answered wrong - set `false` to leave it out |
1435
1453
  | `hydration_enabled` | Boolean | `true` | Inject schema hints into controller/view tool responses |
1436
1454
  | `hydration_max_hints` | Integer | `5` | Max schema hints per tool response |
1437
1455
  | `max_file_size` | Integer | `5_000_000` | Per-file read limit for tools (5MB) |
@@ -1476,7 +1494,7 @@ if defined?(RailsAiContext) && RailsAiContext.respond_to?(:configure)
1476
1494
  end
1477
1495
  ```
1478
1496
 
1479
- The Claude Code, Cursor and Copilot rule sets each keep an app overview file (`rails-context.md`, `rails-project.mdc`, `rails-context.instructions.md`). The Claude Code one leaves out gems, architecture, services and jobs, which it expects in CLAUDE.md. OpenCode and Codex have no overview outside AGENTS.md: their split files hold only the model and controller listings.
1497
+ With root files off, the Claude Code, Cursor and Copilot rule sets each get an app overview (`rails-context.md`, `rails-project.mdc`, `rails-context.instructions.md`) and the tools guide (`rails-mcp-tools.md`, `rails-mcp-tools.mdc`, `rails-mcp-tools.instructions.md`) in the root file's place; Cursor loads its guide on request. With root files on, a run removes those six, since the root file states them. OpenCode and Codex have no overview outside AGENTS.md: their split files hold only the model and controller listings.
1480
1498
 
1481
1499
  ---
1482
1500
 
@@ -1562,8 +1580,8 @@ config.introspectors = %i[schema models routes gems auth api]
1562
1580
  **Auto-discovery:** Reads `.mcp.json` when a session starts in the folder, and asks you to approve the `rails-ai-context` server once (`claude mcp reset-project-choices` asks again).
1563
1581
 
1564
1582
  **Context files loaded:**
1565
- - `CLAUDE.md` - read at conversation start
1566
- - `.claude/rules/*.md` - auto-loaded alongside CLAUDE.md (schema, models, and components rules use `paths:` frontmatter for conditional loading)
1583
+ - `CLAUDE.md` - read at conversation start. Where it holds `@AGENTS.md`, Claude Code expands the import and reads `AGENTS.md` with it
1584
+ - `.claude/rules/*.md` - the schema, models and components rules load when Claude Code opens a file their `paths:` frontmatter matches; the overview and tools rules, written only with `generate_root_files` off, load in every session
1567
1585
 
1568
1586
  **MCP tools:** Available once the server is approved. `/mcp` lists it.
1569
1587
 
@@ -1572,14 +1590,15 @@ config.introspectors = %i[schema models routes gems auth api]
1572
1590
  **Auto-discovery:** Reads `.cursor/mcp.json`. Restart Cursor after the install, and turn `rails-ai-context` on under MCP in Customize if it is off.
1573
1591
 
1574
1592
  **Context files loaded:**
1593
+ - `AGENTS.md` and `CLAUDE.md` - read like an always-on rule, so the root content reaches Cursor from `AGENTS.md`
1575
1594
  - `.cursor/rules/*.mdc` - loaded based on `alwaysApply` and `globs` settings
1576
1595
 
1577
1596
  **MDC rule activation modes:**
1578
1597
  | Mode | When it activates |
1579
1598
  |------|-------------------|
1580
- | `alwaysApply: true` | Every conversation (project overview) |
1599
+ | `alwaysApply: true` | Every conversation (project overview, root files off) |
1581
1600
  | `globs: ["app/models/**/*.rb"]` | When editing files matching the glob pattern |
1582
- | `alwaysApply: false` + `description` | Agent-requested - loaded when AI decides it's relevant (MCP tools rule) |
1601
+ | `alwaysApply: false` + `description` | Agent-requested - loaded when AI decides it's relevant (tools guide, root files off) |
1583
1602
 
1584
1603
  ### OpenCode
1585
1604
 
@@ -1624,7 +1643,7 @@ OpenCode uses **per-directory lazy-loading**: when the agent reads a file, it wa
1624
1643
  **Auto-discovery:** `.vscode/mcp.json` is auto-generated by the install generator.
1625
1644
 
1626
1645
  **Context files loaded:**
1627
- - `.github/copilot-instructions.md` - repo-wide instructions
1646
+ - `.github/copilot-instructions.md` - repo-wide instructions, the root content. github.com chat, Visual Studio, JetBrains, Xcode and code review read no other root file
1628
1647
  - `.github/instructions/*.instructions.md` - path-specific, activated by `applyTo` glob (with `name:` and `description:` frontmatter)
1629
1648
 
1630
1649
  **applyTo patterns:**
@@ -1632,7 +1651,7 @@ OpenCode uses **per-directory lazy-loading**: when the agent reads a file, it wa
1632
1651
  |---------|-------------------|
1633
1652
  | `app/models/**/*.rb` | Editing model files |
1634
1653
  | `app/controllers/**/*.rb` | Editing controller files |
1635
- | `**/*` | All files (MCP tool reference) |
1654
+ | `**/*` | All files (project overview and tools guide, root files off) |
1636
1655
 
1637
1656
  ### Codex CLI
1638
1657
 
data/docs/PROMPTS.md CHANGED
@@ -147,7 +147,7 @@ Set up rails-ai-context for me only in this Rails app: nothing it writes may sho
147
147
  2. Pick TOOL, the key for the AI tool you are: claude (Claude Code), cursor (Cursor), copilot (GitHub Copilot in VS Code), opencode (OpenCode), codex (Codex CLI). If you are another AI tool, stop and tell me to use the "Another MCP client" prompt instead.
148
148
  3. Run `git status --porcelain` and remember its output.
149
149
  4. Run `gem install rails-ai-context -v '>= 5.35.0'`, then `rails-ai-context init --tools TOOL --defaults`.
150
- 5. Run `git status --porcelain --untracked-files=all` again. Restore every tracked file that now shows as modified and did not in step 3 with `git checkout -- PATH` (.gitignore is one when the repo has it). If one of them is a context file the repo already had (CLAUDE.md, AGENTS.md, .cursorrules or .github/copilot-instructions.md), also add the line `generate_root_files: false` to .rails-ai-context.yml and run `rails-ai-context context`: the gem then writes its rules into its own rules files instead of that one. Then run `git status --porcelain --untracked-files=all` once more (restoring .gitignore makes files it ignored show up) and add every path that is new compared with step 3 to .git/info/exclude, one per line (create the file if it is missing).
150
+ 5. Run `git status --porcelain --untracked-files=all` again. Restore every tracked file that now shows as modified or deleted and did not in step 3 with `git checkout -- PATH` (.gitignore is one when the repo has it). If one of them is a context file the repo already had (CLAUDE.md, AGENTS.md, .cursorrules or .github/copilot-instructions.md), also add the line `generate_root_files: false` to .rails-ai-context.yml and run `rails-ai-context context`: the gem then writes its rules into its own rules files instead of that one. Then run `git status --porcelain --untracked-files=all` once more (restoring .gitignore makes files it ignored show up) and add every path that is new compared with step 3 to .git/info/exclude, one per line (create the file if it is missing).
151
151
  6. Run `git status --porcelain` once more and confirm it matches step 3.
152
152
  7. Tell me the "Next step" lines the install printed for TOOL, word for word.
153
153
  ```