rails-ai-bridge 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f8392971b0bc2f8bf98ebe626062b79e7ff271e8aa009ace229702948862eace
-  data.tar.gz: d3e358ef11eef6c9050289d73ab69ec5ad09684d7d8e7d8b25b5da4350306c9e
+  metadata.gz: 179af8f51240a13daa27c526299db931aaac585186cb55b4f1ca440c24cd66a8
+  data.tar.gz: 295dd64afcefc38f247612020fd9933246a1948123ca785293e5f2350bb39b58
 SHA512:
-  metadata.gz: d174446e69dddabd9f99457af197d607793f26b09ef346f2c27f124be15700fb1b7961e4ba76dd43959d32bfcfe108787c611505043ecf12e61ba7fd1735b7e9
-  data.tar.gz: 6bb2d7c5290441e76359de520d3e7e737890d3d6456b6e269bfba579c79540a900cccdd872ec580dc5d392c09c6f053e2f0516842aa8e222f0d994111de2b5de
+  metadata.gz: 98b696d49e6dfd9fffbac01d4cda299b2e0d518eea998bb703dafb71e5577b7d21e9f1024b6d126907808281f48f05cdb73b80c442a72c950c5a8db046198ab5
+  data.tar.gz: a0590ccdc592b161e289313d45f2820b9b793661201b318f68f89c8c4a3535c849d6422327879edd60b7e7a8c14356ab9ea35bcfb4ca9cb6caecf0fac908247d

data/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.1.0] - 2026-04-02
+
+### Added
+
+- **Gemini Support:** Added support for Google's Gemini AI assistant via `GEMINI.md`.
+- **New Rake Task:** Added `rails ai:bridge:gemini` to generate Gemini-specific context.
+- **Context Harmonization:** Refactored all provider serializers (Claude, Gemini, Codex, Copilot, Cursor, Windsurf) to use a shared `BaseProviderSerializer`.
+- **Enhanced AI Guidance:** All context files now feature directive headers, complexity-sorted model lists, and explicit behavioral rules to improve AI code generation.
+- **Improved Metadata:** Context files now include descriptions for key config files and standard maintenance commands (e.g., `rubocop`).
+
+### Changed
+
+- **Internal Refactor:** Extracted common rendering logic into `RailsAiBridge::Serializers::Providers::BaseProviderSerializer` to ensure consistency and maintainability across all AI assistants.
+
 ## [2.0.0] - 2026-03-31
 
 ### Added

data/GEMINI.md

@@ -0,0 +1,55 @@
+# GEMINI.md — rails-ai-bridge development guide
+
+This is a Ruby gem that auto-introspects Rails applications and exposes their
+structure to AI assistants via the Model Context Protocol (MCP).
+
+## Architecture
+
+- `lib/rails_ai_bridge.rb` — Main entry point, public API (Zeitwerk autoloaded)
+- `lib/rails_ai_bridge/configuration.rb` — User-facing config with presets (:standard, :full)
+- `lib/rails_ai_bridge/introspector.rb` — Orchestrates sub-introspectors
+- `lib/rails_ai_bridge/introspectors/` — 27 introspectors (schema, models, routes, jobs, gems, conventions, stimulus, database_stats, controllers, views, turbo, i18n, config, active_storage, action_text, auth, api, tests, rake_tasks, assets, devops, action_mailbox, migrations, seeds, middleware, engines, multi_database)
+- `lib/rails_ai_bridge/tools/` — 9 MCP tools using the official mcp SDK
+- `lib/rails_ai_bridge/serializers/` — Output formatters (claude, claude_rules, cursor_rules, windsurf, windsurf_rules, copilot, copilot_instructions, rules, markdown, JSON, gemini)
+- `lib/rails_ai_bridge/resources.rb` — MCP resources (static data AI clients read directly)
+- `lib/rails_ai_bridge/server.rb` — MCP server configuration (stdio + HTTP transports)
+- `lib/rails_ai_bridge/middleware.rb` — Rack middleware for auto-mounting MCP HTTP endpoint
+- `lib/rails_ai_bridge/fingerprinter.rb` — SHA256 file fingerprinting for cache invalidation
+- `lib/rails_ai_bridge/doctor.rb` — Diagnostic checks and AI readiness scoring
+- `lib/rails_ai_bridge/watcher.rb` — File watcher for auto-regenerating context files
+- `lib/rails_ai_bridge/engine.rb` — Rails Engine for auto-integration
+- `lib/generators/rails_ai_bridge/install/` — Install generator (creates .mcp.json, initializer, context files)
+
+## Key Design Decisions
+
+1. **Built on official mcp SDK** — not a custom protocol implementation
+2. **Zero-config** — Railtie auto-registers at boot, introspects without setup
+3. **Graceful degradation** — works without DB by parsing schema.rb as text
+4. **Read-only tools only** — all MCP tools are annotated as non-destructive
+5. **Dual output** — static files (GEMINI.md) + live MCP server (stdio/HTTP)
+6. **Diff-aware** — context regeneration skips unchanged files
+7. **Per-assistant serializers** — each AI tool gets tailored output format
+8. **Zeitwerk autoloading** — files loaded on-demand, not all upfront
+9. **Introspector presets** — `:standard` (9 core) default, `:full` (26) for power users
+10. **MCP auto-discovery** — `.mcp.json` generated by install generator
+11. **Compact by default** — context files ≤150 lines, MCP tools use `detail` parameter (summary/standard/full)
+12. **Per-tool split rules** — `.claude/rules/`, `.cursor/rules/`, `.windsurf/rules/`, `.github/instructions/`
+
+## Testing
+
+```bash
+bundle exec rspec           # Run specs (364 examples)
+bundle exec rubocop         # Lint
+```
+
+Uses combustion gem for testing Rails engine behavior in isolation.
+
+## Conventions
+
+- Ruby 3.2+ features OK (pattern matching, etc.)
+- Follow rubocop-rails-omakase style
+- Every introspector returns a Hash, never raises (wraps errors in `{ error: msg }`)
+- MCP tools return `MCP::Tool::Response` objects per SDK convention
+- All tools prefixed with `rails_` per MCP naming best practices
+- `generate_context` returns `{ written: [], skipped: [] }` hash
+- Zeitwerk autoloads all files — no `require_relative` needed for new classes

data/README.md

@@ -32,7 +32,7 @@ flowchart LR
 ```
 
 1. **Up to 27 introspectors** scan schema, models, routes, controllers, jobs, gems, conventions, and more (preset `:standard` runs 9 core ones by default; `:full` runs all).
-2. **`rails ai:bridge`** writes bounded bridge files for Claude, Cursor, Copilot, Codex, Windsurf, and JSON.
+2. **`rails ai:bridge`** writes bounded bridge files for Claude, Cursor, Copilot, Codex, Windsurf, Gemini, and JSON.
 3. **`rails ai:serve`** exposes **9 MCP tools** so assistants pull detail on demand (`detail: "summary"` first, then drill down).
 
 ### Folder guides
@@ -301,6 +301,84 @@ Codex support is centered on **`AGENTS.md`** at the repository root.
 
 ---
 
+## Best Practices
+
+After testing with Cursor, Windsurf, Copilot, Codex, and Claude Code in real projects, these patterns consistently produce the best results.
+
+### Layer 1: Commit your static files
+
+The generated files (`.cursorrules`, `.cursor/rules/`, `AGENTS.md`, `.windsurfrules`, `CLAUDE.md`, `.github/copilot-instructions.md`) are loaded **passively** by AI tools on every session start — giving the assistant immediate project grounding before it reads a single line of your code.
+
+**Always commit these files.** The whole team benefits, not just the developer who ran `rails ai:bridge`.
+
+### Layer 2: Run the MCP server
+
+Static files cover overview. The MCP server covers depth. When an assistant needs full schema details, specific model associations, or a filtered route listing, the `rails_*` tools fetch live data on demand — without inflating your initial context window.
+
+The combination is additive:
+
+| Setup | What you get |
+|-------|-------------|
+| Static files only | Passive overview: project structure always loaded |
+| MCP server only | On-demand depth: accurate live data, no passive grounding |
+| **Both (recommended)** | **Passive overview + on-demand depth = best coverage** |
+
+This is the pattern that consistently outperforms either layer alone. The files reduce orientation overhead; the server handles the details when the assistant actually needs them.
+
+### Keep files fresh — regenerate after every significant change
+
+Static files are snapshots. An assistant working from a schema that is 20 commits out of date will still make assumptions based on the old structure. After any significant change — a new model, a migration, a refactor, a feature merged — run:
+
+```bash
+rails ai:bridge
+```
+
+**Rule of thumb:** treat `rails ai:bridge` the same way you treat `bundle install` after a `Gemfile` change — a routine step, not a one-time setup. Commit the regenerated files alongside the code change so the whole team stays in sync.
+
+#### Auto-regeneration during active development
+
+```bash
+rails ai:watch
+```
+
+Watches for file changes and regenerates relevant context files automatically. Useful when you are actively adding models, routes, or controllers and want the assistant to track along in the same session.
+
+### Use `detail: "summary"` first with the MCP server
+
+When the MCP server is running, start broad and drill down:
+
+```
+1. rails_get_schema(detail: "summary")      → all tables, no noise
+2. rails_get_schema(table: "orders")        → full detail for one table
+3. rails_get_model_details(model: "Order")  → associations, validations, scopes
+```
+
+This keeps token usage low and answer quality high. Requesting full detail on every table at once is rarely necessary and wastes context on data the assistant does not need yet.
+
+### Pick the right preset for your app
+
+| Preset | Introspectors | Best for |
+|--------|--------------|---------|
+| `:standard` (default) | 9 core | Most apps — schema, models, routes, jobs, gems, conventions |
+| `:full` | 27 | Full-stack apps where frontend, auth, API, and DevOps context matter |
+
+Add individual introspectors on top of a preset for targeted additions:
+
+```ruby
+config.preset = :standard
+config.introspectors += %i[views auth api]
+```
+
+### Check your readiness score
+
+```bash
+rails ai:doctor
+```
+
+Prints a 0–100 AI readiness score and flags anything missing: `.mcp.json`, generated context files, MCP token in production, and more. Run it after initial setup and after major configuration changes.
+
+---
+
 ## Configuration
 
 ```ruby
@@ -402,6 +480,7 @@ Frontend introspectors (views, Turbo, Stimulus, assets) degrade gracefully — t
 | `rails ai:bridge:cursor` | Generate Cursor files only |
 | `rails ai:bridge:windsurf` | Generate Windsurf files only |
 | `rails ai:bridge:copilot` | Generate Copilot files only |
+| `rails ai:bridge:gemini` | Generate Gemini files only |
 | `rails ai:serve` | Start MCP server (stdio) |
 | `rails ai:serve_http` | Start MCP server (HTTP) |
 | `rails ai:doctor` | Run diagnostics and AI readiness score (0-100) |

data/docs/roadmap-context-assistants.md

@@ -8,13 +8,15 @@ This track is **separate** from [roadmap-mcp-v2.md](roadmap-mcp-v2.md) (MCP HTTP
 
 - Sharpen per-assistant formats (structure, length, cross-links) based on real usage feedback.
 - Reduce duplication and noise while keeping "always-on" rules discoverable.
-- Align tool references and workflow hints across Claude, Cursor, Copilot, Windsurf, Codex, etc.
+## Done
+
 - Separate LLM provider serializers from domain infrastructure (done: `Serializers::Providers::` namespace).
 - DRY the formatter hierarchy (done: `SectionFormatter` template method base).
+- Align tool references and workflow hints across Claude, Cursor, Copilot, Windsurf, Codex, and **Gemini** (v2.1.0).
+- Refactor provider serializers with a shared `BaseProviderSerializer` for consistent, high-fidelity output (v2.1.0).
 
 ## In progress
 
-- Refining per-provider serializer output (context quality improvements on `pr5-context-quality` branch)
 - Custom Rails directory introspection coverage gaps
 
 ## Relation to versioning

data/docs/roadmaps.md

@@ -33,8 +33,18 @@ Entry point to see **which tracks exist** and **what is left**. Details live in
 | `Mcp::Authenticator` consolidation | Done |
 | Provider serializers extracted to `Serializers::Providers::` | Done |
 | `SectionFormatter` template method base (DRY guard pattern) | Done |
-| Concrete tasks per assistant / format | **In progress** |
-| Major release (2.0.0) | **Deferred** until this track + communication plan |
+| Major release (2.0.0) | Done |
+
+---
+
+## v2.1.0 — Gemini & Harmonization
+
+| Area | Status |
+|------|--------|
+| Gemini Support (`GEMINI.md`, `GeminiSerializer`, Rake task) | Done |
+| Context Harmonization (Shared `BaseProviderSerializer`) | Done |
+| Enhanced directive guidance for all assistants | Done |
+| Release (2.1.0) | Done |
 
 ---
 

data/lib/generators/rails_ai_bridge/install/install_generator.rb

@@ -168,6 +168,7 @@ module RailsAiBridge
         say "  rails ai:bridge:claude   # Generate CLAUDE.md only"
         say "  rails ai:bridge:codex    # Generate AGENTS.md only"
         say "  rails ai:bridge:cursor   # Generate .cursorrules only"
+        say "  rails ai:bridge:gemini   # Generate GEMINI.md only"
         say "  rails ai:serve           # Start MCP server (stdio)"
         say "  rails ai:inspect         # Print introspection summary"
         say ""
@@ -177,6 +178,7 @@ module RailsAiBridge
         say "  Cursor         → .cursorrules + .cursor/rules/*.mdc (incl. rails-engineering.mdc)"
         say "  Windsurf       → .windsurfrules + .windsurf/rules/*.md"
         say "  GitHub Copilot → .github/copilot-instructions.md + .github/instructions/*.instructions.md"
+        say "  Gemini         → GEMINI.md"
         say ""
         say "MCP auto-discovery:", :yellow
         say "  .mcp.json is auto-detected by Claude Code and Cursor."

data/lib/rails_ai_bridge/assistant_formats_preference.rb

@@ -20,7 +20,7 @@ module RailsAiBridge
     RELATIVE_PATH = "config/rails_ai_bridge/install.yml"
 
     # All recognized format keys (order is not significant).
-    FORMAT_KEYS = %i[claude codex cursor windsurf copilot json].freeze
+    FORMAT_KEYS = %i[claude codex cursor windsurf copilot json gemini].freeze
 
     class << self
       # Absolute path to the preference file for the current Rails application.

data/lib/rails_ai_bridge/serializers/context_file_serializer.rb

@@ -14,7 +14,8 @@ module RailsAiBridge
         cursor:    ".cursorrules",
         windsurf:  ".windsurfrules",
         copilot:   ".github/copilot-instructions.md",
-        json:      ".ai-context.json"
+        json:      ".ai-context.json",
+        gemini:    "GEMINI.md"
       }.freeze
 
       def initialize(context, format: :all)
@@ -67,6 +68,7 @@ module RailsAiBridge
         when :codex    then Providers::CodexSerializer.new(context).call
         when :cursor   then Providers::RulesSerializer.new(context).call
         when :windsurf then Providers::WindsurfSerializer.new(context).call
+        when :gemini   then Providers::GeminiSerializer.new(context).call
         when :copilot  then Providers::CopilotSerializer.new(context).call
         else MarkdownSerializer.new(context).call
         end

data/lib/rails_ai_bridge/serializers/formatters/gemini_footer_formatter.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module RailsAiBridge
+  module Serializers
+    module Formatters
+      # Renders the Gemini footer with behavioral rules and regeneration note.
+      class GeminiFooterFormatter < Base
+        # Renders the footer for the GEMINI.md file.
+        #
+        # @return [String] The rendered footer.
+        def call
+          arch = context.dig(:conventions, :architecture)
+          arch_summary = arch&.any? ? arch.join(", ") : nil
+
+          lines = [
+            "## Behavioral Rules",
+            "",
+            "- **Adhere to Conventions:** Strictly follow the existing patterns and conventions outlined in this document.",
+            "- **Schema as Source of Truth:** Always use the database schema as the definitive source for column names, types, and relationships.",
+            "- **Respect Existing Logic:** Ensure all new code respects existing associations, validations, and service objects.",
+            "- **Write Tests:** All new features and bug fixes must be accompanied by corresponding tests."
+          ]
+          lines << "- **Match Architecture:** Align with the project's architectural style (#{arch_summary})." if arch_summary
+          lines << "- **Verify Correctness:** Run `#{ContextSummary.test_command(context)}` and `bundle exec rubocop` after making changes to ensure correctness and style adherence."
+          lines << ""
+          lines << "---"
+          lines << "_This context file is auto-generated. Run `rails ai:bridge` to regenerate._"
+          lines.join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/rails_ai_bridge/serializers/formatters/gemini_header_formatter.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module RailsAiBridge
+  module Serializers
+    module Formatters
+      # Renders the Gemini-specific document header.
+      class GeminiHeaderFormatter < Base
+        # Renders the header for the GEMINI.md file.
+        #
+        # @return [String] The rendered header.
+        def call
+          <<~MD
+            # #{context[:app_name]} — AI Context
+
+            > Auto-generated by rails-ai-bridge v#{RailsAiBridge::VERSION}
+            > Generated: #{context[:generated_at]}
+            > Rails #{context[:rails_version]} | Ruby #{context[:ruby_version]}
+
+            This file provides a high-level overview of this Rails application's
+            structure, patterns, and conventions. As an AI assistant, use this context
+            to quickly understand the project and generate idiomatic code that
+            adheres to its design decisions. For deeper dives, use the live
+            MCP tools referenced throughout this document.
+          MD
+        end
+      end
+    end
+  end
+end

data/lib/rails_ai_bridge/serializers/providers/base_provider_serializer.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+module RailsAiBridge
+  module Serializers
+    module Providers
+      # Base class for AI assistant provider serializers (Claude, Copilot, Gemini, Codex, Cursor, Windsurf).
+      # Shared compact-mode sections: header, stack, models, gems, architecture, MCP guide, commands, footer.
+      class BaseProviderSerializer
+        attr_reader :context, :config
+
+        # @param context [Hash] Introspection hash from {Introspector#call}.
+        # @param config [RailsAiBridge::Configuration] Bridge configuration.
+        def initialize(context, config: RailsAiBridge.configuration)
+          @context = context
+          @config = config
+        end
+
+        # Renders the default compact AI context document (newline-joined sections).
+        # Enforces {RailsAiBridge::Configuration#claude_max_lines} by trimming with an MCP pointer when exceeded.
+        # Subclasses may override entirely or compose with individual `#render_*` helpers.
+        #
+        # @return [String] Compact markdown body.
+        def render_compact
+          lines = []
+          lines.concat(render_header)
+          lines.concat(render_stack_overview)
+          lines.concat(render_key_models)
+          lines.concat(render_notable_gems)
+          lines.concat(render_architecture)
+          lines.concat(render_key_considerations)
+          lines.concat(Formatters::McpGuideFormatter.new(context).call.split("\n"))
+          lines.concat(render_key_config_files)
+          lines.concat(render_commands)
+          lines.concat(render_footer)
+
+          # Enforce max lines (config.claude_max_lines is a generic max line setting)
+          max = @config.claude_max_lines
+          if lines.size > max
+            lines = lines.first(max - 2)
+            lines << ""
+            lines << "_Context trimmed. Use MCP tools for full details._"
+          end
+
+          lines.join("\n")
+        end
+
+        # Renders the header section of the context file.
+        # @return [Array<String>] Lines for the header.
+        def render_header
+          [
+            "# #{context[:app_name]} — AI Context",
+            "",
+            "> Auto-generated by rails-ai-bridge v#{RailsAiBridge::VERSION}",
+            "> Generated: #{context[:generated_at]}",
+            "> Rails #{context[:rails_version]} | Ruby #{context[:ruby_version]}",
+            "",
+            "This file provides a high-level overview of this Rails application's",
+            "structure, patterns, and conventions. As an AI assistant, use this context",
+            "to quickly understand the project and generate idiomatic code that",
+            "adheres to its design decisions. For deeper dives, use the live",
+            "MCP tools referenced throughout this document."
+          ]
+        end
+
+        # Renders the stack overview section.
+        # @return [Array<String>] Lines for the stack overview.
+        def render_stack_overview
+          lines = [ "## Stack" ]
+
+          schema = context[:schema]
+          if schema && !schema[:error]
+            lines << "- Database: #{schema[:adapter]} — #{schema[:total_tables]} tables"
+          end
+
+          models = context[:models]
+          if models.is_a?(Hash) && !models[:error]
+            lines << "- Models: #{models.size}"
+          end
+
+          line = ContextSummary.routes_stack_line(context)
+          lines << line if line
+
+          auth = context[:auth]
+          if auth.is_a?(Hash) && !auth[:error]
+            parts = []
+            parts << "Devise" if auth.dig(:authentication, :devise)&.any?
+            parts << "Rails 8 auth" if auth.dig(:authentication, :rails_auth)
+            parts << "Pundit" if auth.dig(:authorization, :pundit)&.any?
+            parts << "CanCanCan" if auth.dig(:authorization, :cancancan)
+            lines << "- Auth: #{parts.join(' + ')}" if parts.any?
+          end
+
+          jobs = context[:jobs]
+          if jobs.is_a?(Hash) && !jobs[:error]
+            job_count = jobs[:jobs]&.size || 0
+            mailer_count = jobs[:mailers]&.size || 0
+            channel_count = jobs[:channels]&.size || 0
+            parts = []
+            parts << "#{job_count} jobs" if job_count > 0
+            parts << "#{mailer_count} mailers" if mailer_count > 0
+            parts << "#{channel_count} channels" if channel_count > 0
+            lines << "- Async: #{parts.join(', ')}" if parts.any?
+          end
+
+          migrations = context[:migrations]
+          if migrations.is_a?(Hash) && !migrations[:error]
+            pending = migrations[:pending]
+            lines << "- Migrations: #{migrations[:total]} total, #{pending&.size || 0} pending"
+          end
+
+          lines << ""
+          lines
+        end
+
+        # Renders the key models section.
+        # @return [Array<String>] Lines for the key models.
+        def render_key_models
+          models = context[:models]
+          return [] unless models.is_a?(Hash) && !models[:error] && models.any?
+
+          schema_tables = context.dig(:schema, :tables) || {}
+          migrations    = context[:migrations]
+          max_show = 15
+
+          lines = [ "## Key Models", "The following are the most architecturally significant models, ordered by complexity:" ]
+          sorted_names = models.sort_by { |_name, data| -ContextSummary.model_complexity_score(data) }.map(&:first)
+          sorted_names.first(max_show).each do |name|
+            data = models[name]
+            assoc_count = (data[:associations] || []).size
+            val_count   = (data[:validations] || []).size
+            enum_names  = (data[:enums] || {}).keys
+            top_assocs  = (data[:associations] || []).first(3).map { |a| "#{a[:type]} :#{a[:name]}" }.join(", ")
+            table_name  = data[:table_name]
+
+            line = "- **#{name}**"
+            line += " (#{assoc_count}a, #{val_count}v)" if assoc_count > 0 || val_count > 0
+            line += " [enums: #{enum_names.join(', ')}]" if enum_names.any?
+
+            cols = ContextSummary.top_columns(schema_tables[table_name])
+            line += " [cols: #{cols.map { |c| "#{c[:name]}:#{c[:type]}" }.join(', ')}]" if cols.any?
+
+            line += " [recently migrated]" if table_name && ContextSummary.recently_migrated?(table_name, migrations)
+            line += " — #{top_assocs}" if top_assocs && !top_assocs.empty?
+            lines << line
+          end
+          lines << "- _...#{models.size - max_show} more (use `rails_get_model_details` tool)_" if models.size > max_show
+          lines << ""
+          lines
+        end
+
+        # Renders the notable gems section.
+        # @return [Array<String>] Lines for the notable gems.
+        def render_notable_gems
+          gems = context[:gems]
+          return [] unless gems.is_a?(Hash) && !gems[:error]
+          notable = gems[:notable_gems] || gems[:notable] || gems[:detected] || []
+          return [] if notable.empty?
+
+          lines = [ "## Gems", "Key gems, categorized by their primary function:" ]
+          grouped = notable.group_by { |g| g[:category]&.to_s || "other" }
+          grouped.each do |category, gem_list|
+            names = gem_list.map { |g| g[:name] }.join(", ")
+            lines << "- **#{category}**: #{names}"
+          end
+          lines << ""
+          lines
+        end
+
+        # Renders the architecture section.
+        # @return [Array<String>] Lines for the architecture.
+        def render_architecture
+          conv = context[:conventions]
+          return [] unless conv.is_a?(Hash) && !conv[:error]
+
+          arch = conv[:architecture] || []
+          patterns = conv[:patterns] || []
+          return [] if arch.empty? && patterns.empty?
+
+          lines = [ "## Architecture", "Detected architectural styles and common patterns:" ]
+          arch.each { |p| lines << "- #{p}" }
+          patterns.first(8).each { |p| lines << "- #{p}" }
+          lines << ""
+          lines
+        end
+
+        # Renders the key considerations for performance and security.
+        # @return [Array<String>] Lines for performance and security considerations.
+        def render_key_considerations
+          [
+            "## Key Considerations",
+            "- **Performance:** For large or frequently accessed tables, always consider database performance. Use the `rails_get_schema` tool to verify indexes and be mindful of N+1 queries by using `includes` and other ActiveRecord optimizations.",
+            "- **Security:** Treat all user-provided input as untrusted. Always use strong parameters in controllers and be aware of potential security vulnerabilities when using gems like `ransack` or `pg_search`.",
+            "- **Data Drift:** This document is a snapshot. For the most up-to-date information, especially regarding schema and routes, use the live MCP tools.",
+            "- **MCP Exposure:** The MCP tools are read-only but expose sensitive application structure. Avoid exposing the HTTP transport on untrusted networks.",
+            ""
+          ]
+        end
+
+        # Renders the key configuration files section.
+        # @return [Array<String>] Lines for the key config files.
+        def render_key_config_files
+          conv = context[:conventions]
+          return [] unless conv.is_a?(Hash) && !conv[:error]
+
+          config_files = conv[:config_files] || []
+          return [] if config_files.empty?
+
+          lines = [ "## Key Config Files", "Core configuration files for this application:" ]
+          config_files.first(5).each { |f| lines << "- `#{f}`" }
+          lines << ""
+          lines
+        end
+
+        # Renders the command reference section.
+        # @return [Array<String>] Lines for the commands.
+        def render_commands
+          [
+            "## Commands",
+            "- `bin/dev` — start dev server",
+            "- `#{ContextSummary.test_command(context)}` — run tests",
+            "- `bundle exec rubocop` — run linter",
+            "- `rails db:migrate` — run pending migrations",
+            ""
+          ]
+        end
+
+        # Renders the closing rules and regeneration footer.
+        # @return [Array<String>] Lines for the rules section and trailing attribution.
+        def render_footer
+          arch = context.dig(:conventions, :architecture)
+          arch_summary = arch&.any? ? arch.join(", ") : nil
+
+          lines = [
+            "## Rules",
+            "",
+            "- **Adhere to Conventions:** Strictly follow the existing patterns and conventions outlined in this document.",
+            "- **Schema as Source of Truth:** Always use the database schema as the definitive source for column names, types, and relationships.",
+            "- **Respect Existing Logic:** Ensure all new code respects existing associations, validations, and service objects.",
+            "- **Write Tests:** All new features and bug fixes must be accompanied by corresponding tests."
+          ]
+          lines << "- **Match Architecture:** Align with the project's architectural style (#{arch_summary})." if arch_summary
+          lines << "- **Verify Correctness:** Run `#{ContextSummary.test_command(context)}` and `bundle exec rubocop` after making changes to ensure correctness and style adherence."
+          lines << ""
+          lines << "---"
+          lines << "_This context file is auto-generated. Run `rails ai:bridge` to regenerate._"
+          lines
+        end
+      end
+    end
+  end
+end