rails-ai-context 5.32.2 → 5.34.0

data/lib/rails_ai_context/safe_path.rb

@@ -22,7 +22,9 @@ module RailsAiContext
     # relative: the caller's path, relative to `under`. root: the directory
     # the sensitive patterns are matched against (the app root for most tools).
     # listed: the path came from a listing of `under`, so it is spelled as on disk.
-    def locate(relative, under:, root: under, max_size: nil, listed: false)
+    # links: a path through a directory linked in from the repository holding
+    # `root` (linked_in) is one of `under`'s; off, only `under` itself holds.
+    def locate(relative, under:, root: under, max_size: nil, listed: false, links: true)
       relative = relative.to_s
       return refuse(:traversal) if traversal?(relative)
       return refuse(:sensitive) if sensitive?(relative)
@@ -30,22 +32,31 @@ module RailsAiContext
       path = File.join(under.to_s, relative)
       real = listed ? real_file(path) : File.realpath(path)
       real_under = real_base(under)
-      return refuse(:outside) unless contained?(real, real_under)
+      linked = links && !contained?(real, real_under) ? linked_in(path, real, under, root) : nil
+      return refuse(:outside) unless linked || contained?(real, real_under)
 
       real_root = real_base(root)
+      # `under` can itself be a linked-in directory, a pack's app/views, so the
+      # root's spelling of the path is asked for the link too.
+      linked ||= links && !contained?(real, real_root) ? linked_in(path, real, root, root) : nil
       root_relative = if real == real_root then ""
       elsif contained?(real, real_root) then real.delete_prefix(dir_prefix(real_root))
+      # Named the way the app spells it: packs/billing/app/models/invoice.rb.
+      elsif linked then spelled_relative(path, root)
       # A directory the caller trusts outside the root, such as the engine around a test/dummy.
       else Pathname.new(real).relative_path_from(Pathname.new(real_root)).to_s
       end
       return refuse(:sensitive) if sensitive?(root_relative)
+      # Read where the file is too: a name inside the linked directory.
+      return refuse(:sensitive) if linked && sensitive?(real.delete_prefix(dir_prefix(linked)))
       return refuse(:missing) unless File.file?(real)
 
       limit = max_size || RailsAiContext.configuration.max_file_size
       return refuse(:too_large, realpath: real, relative: root_relative) if File.size(real) > limit
 
       Resolution.new(realpath: real, relative: root_relative, refusal: nil)
-    rescue Errno::ENOENT, Errno::EACCES, Errno::ELOOP, Errno::ENAMETOOLONG, Errno::ENOTDIR
+    # EINVAL: Windows refuses a name holding `:`, `<`, `|` and the like.
+    rescue Errno::ENOENT, Errno::EACCES, Errno::ELOOP, Errno::ENAMETOOLONG, Errno::ENOTDIR, Errno::EINVAL
       refuse(:missing)
     end
 
@@ -63,6 +74,55 @@ module RailsAiContext
       File.join(real_base(File.dirname(path)), File.basename(path))
     end
 
+    # Where a directory link inside the app may lead and still be the app's:
+    # the git work tree holding `root`, so a monorepo's shared package counts
+    # and a home directory does not. Outside any repository nothing marks
+    # where the project ends, so only `root` itself.
+    def link_bound(root)
+      RunCache.fetch([ :safe_path_link_bound, root.to_s ]) do
+        real_root = real_base(root)
+        repo = git_root(real_root)
+        repo ? File.realpath(repo) : real_root
+      end
+    end
+
+    # The real path of the linked-in directory that holds `real`: a directory
+    # link on `path`'s spelling below `base` that leads inside link_bound(root).
+    # Nil when no such link leads to it, as for a file linked out on its own.
+    # A spelled `..` is read lexically, so it cannot climb out through a link.
+    def linked_in(path, real, base, root)
+      spelled = File.expand_path(path.to_s)
+      prefix = dir_prefix(File.expand_path(base.to_s))
+      return nil unless spelled.start_with?(prefix)
+
+      bound = link_bound(root)
+      segments = spelled.delete_prefix(prefix).split(File::SEPARATOR)
+      segments.size.downto(1) do |depth|
+        linked = linked_dir(File.join(prefix, *segments.first(depth)), bound)
+        return linked if linked && contained?(real, linked)
+      end
+      nil
+    end
+
+    # A directory link's real path when it leads inside `bound`, else nil.
+    def linked_dir(dir, bound)
+      RunCache.fetch([ :safe_path_linked_dir, dir, bound ]) do
+        real = File.symlink?(dir) && File.directory?(dir) && File.realpath(dir)
+        real if real && contained?(real, bound)
+      end
+    rescue SystemCallError
+      nil
+    end
+
+    # `path` relative to `root` as both are spelled.
+    def spelled_relative(path, root)
+      spelled = File.expand_path(path.to_s)
+      spelled_root = File.expand_path(root.to_s)
+      return spelled.delete_prefix(dir_prefix(spelled_root)) if spelled.start_with?(dir_prefix(spelled_root))
+
+      Pathname.new(spelled).relative_path_from(Pathname.new(spelled_root)).to_s
+    end
+
     def read(relative, under:, root: under, max_size: nil)
       resolution = locate(relative, under: under, root: root, max_size: max_size)
       return [ nil, resolution ] unless resolution.ok?
@@ -75,7 +135,21 @@ module RailsAiContext
     # that resolve a directory rather than a file and so cannot use `locate`.
     def traversal?(relative)
       relative = relative.to_s
-      relative.include?("..") || relative.start_with?("/") || relative.include?("\0")
+      relative.include?("\0") || relative.include?("..") || absolute?(relative)
+    end
+
+    # Whether a path names its place whatever directory it is joined to:
+    # `/x` everywhere, and on Windows `C:/x`, `C:\x` and `\\server\share`,
+    # which File.absolute_path? answers there, as well as `\x` (the current
+    # drive's root) and `C:x` (that drive's current directory). A NUL byte
+    # names no file at all, and File.absolute_path? raises on one.
+    def absolute?(path)
+      path = path.to_s
+      return true if path.start_with?("/")
+      return false if path.include?("\0")
+      return true if File.absolute_path?(path)
+
+      !File::ALT_SEPARATOR.nil? && path.match?(/\A(?:\\|[A-Za-z]:)/)
     end
 
     PLACEHOLDER_SUFFIXES = %w[.example .sample .template .dist].freeze
@@ -102,6 +176,29 @@ module RailsAiContext
       real == real_dir || real.start_with?(dir_prefix(real_dir))
     end
 
+    # One spelling of a place whatever links lead to it, for comparing two
+    # paths: the real path, or for a path not there yet its nearest existing
+    # ancestor's real path with the rest appended. Stdlib only, so it serves
+    # before the gem entry loads too.
+    #
+    # Worked in bytes: a name that is not UTF-8 arrives as a broken UTF-8
+    # string, which Ruby 3.1's delete_prefix leaves whole, and realpath
+    # answers it as bytes, which File.join will not mix with a UTF-8 rest.
+    def canonical(path)
+      path = File.expand_path(path.to_s)
+      existing = path
+      existing = File.dirname(existing) until File.exist?(existing) || File.dirname(existing) == existing
+      rest = path.b.delete_prefix(existing.b)
+      real = File.realpath(existing)
+      return real if rest.empty?
+
+      joined = File.join(real.b, rest)
+      text = joined.dup.force_encoding(Encoding::UTF_8)
+      text.valid_encoding? ? text : joined
+    rescue SystemCallError
+      path
+    end
+
     # The nearest directory at or above `dir` that holds `.git` (a directory, or a
     # file in a worktree or submodule), or nil outside any repository.
     def git_root(dir)

data/lib/rails_ai_context/schema_adapter.rb

@@ -96,6 +96,14 @@ module RailsAiContext
       database_label(primary)
     end
 
+    # A secondary database's adapter: its database.yml entry, else the dialect
+    # its structure.sql is in. nil when neither says; schema.rb does not.
+    def secondary_label(context, name, schema)
+      multi = context.is_a?(Hash) ? context[:multi_database] : nil
+      databases = Tools::SectionFetch.usable?(multi) ? Array(multi[:databases]) : []
+      database_label(databases.find { |db| db.is_a?(Hash) && db[:name].to_s == name.to_s }) || from_dialect(schema)
+    end
+
     # These are ActiveRecord adapter names (`postgresql`), not gem names; the two
     # overlap only at sqlite3/mysql2/trilogy.
     #

data/lib/rails_ai_context/schema_version.rb

@@ -51,6 +51,15 @@ module RailsAiContext
       format, path = Introspectors::SchemaDumpPath.present(root)
       return nil unless format == :sql
 
+      recorded(format, path)
+    end
+
+    # What one dump records as applied: structure.sql's whole set, schema.rb's
+    # newest version. A secondary database's dump answers for that database.
+    def self.recorded(format, path)
+      return nil unless path && File.exist?(path)
+      return from_schema_rb(path) unless format == :sql
+
       content = RailsAiContext::SafeFile.read(path, max_size: RailsAiContext.configuration.max_schema_file_size)
       return nil unless content
 

data/lib/rails_ai_context/serializers/claude_rules_serializer.rb

@@ -16,6 +16,9 @@ module RailsAiContext
         "rails-components.md" => { renderer: :render_components_reference, reason: "no view components" }
       }.freeze
 
+      # Per database; the tools have the rest.
+      TABLES_SHOWN = 30
+
       # @param output_dir [String] Rails root path
       # @return [Hash] { written: [paths], skipped: [paths], not_applicable: { path => reason } }
       def call(output_dir)
@@ -36,44 +39,78 @@ module RailsAiContext
         lines.concat(overview_lines(gems: false, architecture: false, app_dirs: false))
 
         lines << ""
-        lines << "ALWAYS use MCP tools for context - do NOT read reference files directly."
-        lines << "Start with `detail:\"summary\"`. Read files ONLY when you will Edit them."
+        lines << "ALWAYS use #{tools_noun} for context - do NOT read reference files directly."
+        lines << "Start with `#{param_text("detail", "summary")}`. Read files ONLY when you will Edit them."
 
         lines.join("\n")
       end
 
+      # Every database's tables, the primary's first. With more than one, each
+      # gets a heading, since a table name can be in two of them. A database
+      # a Rails framework keeps to itself (Rails 8's queue, cache and cable)
+      # is no part of it: its tables are the framework's, CLAUDE.md names it,
+      # and its dump says nothing this listing would help with.
       def render_schema_reference
         schema = Payload.section(context, :schema)
         return nil unless schema
-        tables = schema[:tables] || {}
-        return nil if tables.empty?
 
-        lines = [
-          "---",
-          "paths:",
-          # The glob has to name the dump the app committed, or the rule never
-          # triggers on a :sql app: db/schema.rb is never opened there.
-          "  - \"#{schema_dump_path}\"",
-          '  - "db/migrate/**"',
-          "---",
-          "",
-          "# Database Tables (#{tables.size})",
-          ""
-        ]
-        lines.concat(SectionFacts.static_notice_lines(context))
-        lines << "_Snapshot - may be stale after migrations. Use `rails_get_schema(table:\"name\")` for live data._"
+        secondary = Payload.app_databases(schema)
+        databases = [ [ nil, schema[:tables] || {} ] ] + secondary.map { |name, db| [ name, db[:tables] ] }
+        databases.reject! { |_, tables| tables.empty? }
+        return nil if databases.empty?
+
+        lines = [ "---", "paths:", *schema_rule_paths(secondary).map { |path| "  - \"#{path}\"" }, "---", "" ]
+        lines << "# Database Tables (#{databases.sum { |_, tables| tables.size }})"
         lines << ""
+        lines.concat(SectionFacts.static_notice_lines(context))
+        live = " Use #{tool_ref("rails_get_schema", 'table:"name"', "table=name")} for live data." if served?("rails_get_schema")
+        lines << "_Snapshot - may be stale after migrations.#{live}_"
+
+        databases.each do |name, tables|
+          lines << ""
+          lines.concat(database_heading_lines(name, tables, secondary)) if secondary.any?
+          lines.concat(table_reference_lines(tables, name, schema))
+        end
+
+        lines.join("\n")
+      end
+
+      # The dumps and migrations the tables are read from, each database's, so
+      # opening any of them brings the rule in. The primary's has to name the
+      # dump the app committed, or the rule never triggers on a :sql app:
+      # db/schema.rb is never opened there.
+      def schema_rule_paths(secondary)
+        paths = [ schema_dump_path, "db/migrate/**" ]
+        secondary.each_value do |db|
+          paths << db[:dump] if db[:dump]
+          Array(db[:migrations_paths]).each { |dir| paths << "#{dir}/**" }
+        end
+        paths.uniq
+      end
 
+      def database_heading_lines(name, tables, secondary)
+        relations = Introspectors::SchemaConventions.relations_phrase(tables)
+        return [ "## primary (#{SchemaAdapter.label(context)}, #{relations})", "" ] unless name
+
+        db = secondary[name]
+        adapter = SchemaAdapter.secondary_label(context, name, db)
+        lines = [ "## #{name} (#{[ adapter, relations ].compact.join(', ')})", "" ]
+        # Where the snapshot comes from: a booted run reads the primary live, this from its files.
+        lines.push("_#{db[:note]}._", "") if db[:note]
+        lines
+      end
+
+      def table_reference_lines(tables, database, schema)
+        lines = []
         skip_cols = %w[id created_at updated_at]
         keep_cols = %w[type deleted_at discarded_at]
         # Get enum values from models introspection if available
         models = Payload.models(context)
 
-        tables.keys.sort.first(30).each do |name|
+        tables.keys.sort.first(TABLES_SHOWN).each do |name|
           data = tables[name]
           columns = data[:columns] || []
           col_count = columns.size
-          pk_display = Introspectors::SchemaConventions.primary_key_label(data[:primary_key])
 
           # Show column names WITH types for key columns
           # Skip standard Rails FK columns (like user_id, account_id) but keep
@@ -118,8 +155,7 @@ module RailsAiContext
           lines << "- **#{name}** (#{count_phrase(col_count, 'col')})#{col_str}#{fk_str}#{idx_str}"
 
           # Include enum values if model has them
-          model_name = name.classify
-          model_data = models[model_name]
+          model_data = table_model(models, name, database, schema)
           if model_data.is_a?(Hash) && model_data[:enums]&.any?
             model_data[:enums].each do |attr, values|
               lines << "  #{attr}: #{SectionFacts.enum_values(values)}"
@@ -127,11 +163,24 @@ module RailsAiContext
           end
         end
 
-        if tables.size > 30
-          lines << "- ...#{count_phrase(tables.size - 30, "more table")} (use `rails_get_schema` MCP tool)"
+        if tables.size > TABLES_SHOWN
+          use = " (use #{tool_named("rails_get_schema")})" if served?("rails_get_schema")
+          lines << "- ...#{count_phrase(tables.size - TABLES_SHOWN, "more table")}#{use}"
         end
 
-        lines.join("\n")
+        lines
+      end
+
+      # The model named after the table. Another database's table of that name
+      # is some other model's: the one that reads from that database.
+      def table_model(models, table, database, schema)
+        named = models[table.classify]
+        return named unless database
+        return named if named.is_a?(Hash) && Payload.model_databases(schema, named).include?(database)
+
+        models.keys.sort.map { |name| models[name] }.find do |data|
+          data.is_a?(Hash) && data[:table_name] == table && Payload.model_databases(schema, data).include?(database)
+        end
       end
 
       def render_models_reference
@@ -148,7 +197,11 @@ module RailsAiContext
           ""
         ]
         lines.concat(SectionFacts.static_notice_lines(context))
-        lines << "_Quick reference - use `rails_get_model_details(model:\"Name\")` for live data with resolved concerns and callbacks._"
+        lines << if served?("rails_get_model_details")
+          "_Quick reference - use #{tool_ref("rails_get_model_details", 'model:"Name"', "model=Name")} for live data with resolved concerns and callbacks._"
+        else
+          "_Quick reference._"
+        end
         lines << ""
 
         models.keys.sort.each do |name|
@@ -161,8 +214,9 @@ module RailsAiContext
           assocs = (data[:associations] || []).size
           vals = (data[:validations] || []).size
           table = data[:table_name]
+          note = SectionFacts.table_note(Payload.section(context, :schema), data)
           line = "- #{name}"
-          line += " (table: #{table})" if table
+          line += note ? " (table #{note})" : (" (table: #{table})" if table).to_s
           line += " - #{count_phrase(assocs, "assoc")}, #{count_phrase(vals, "validation")}"
           lines << line
 
@@ -218,11 +272,9 @@ module RailsAiContext
           ""
         ]
         lines.concat(SectionFacts.static_notice_lines(context))
-        lines.concat([
-          "ViewComponent and Phlex components available for reuse.",
-          "Use `rails_get_component_catalog(component:\"Name\")` for full details.",
-          ""
-        ])
+        lines << "ViewComponent and Phlex components available for reuse."
+        lines << "Use #{tool_ref("rails_get_component_catalog", 'component:"Name"', "component=Name")} for full details." if served?("rails_get_component_catalog")
+        lines << ""
 
         components.each do |c|
           slots = (c[:slots] || []).map { |s| s[:name] }
@@ -235,8 +287,11 @@ module RailsAiContext
         lines.join("\n")
       end
 
+      # Always loaded beside CLAUDE.md, which carries the guide whenever root
+      # files are on; without CLAUDE.md this is the only place for the guide.
       def render_mcp_tools_reference
-        render_tools_guide.join("\n")
+        guide = RailsAiContext.configuration.generate_root_files ? render_tools_reference("CLAUDE.md") : render_tools_guide
+        guide.join("\n")
       end
     end
   end

data/lib/rails_ai_context/serializers/compact_serializer_helper.rb

@@ -4,9 +4,10 @@ module RailsAiContext
   module Serializers
     # Shared rendering methods for compact-mode serializers (Claude, OpenCode).
     # Include in any serializer that has a `context` reader and includes
-    # StackOverviewHelper, ToolGuideHelper, and TestCommandDetection.
+    # StackOverviewHelper and TestCommandDetection.
     module CompactSerializerHelper
       include CountPhrase
+      include ToolGuideHelper
 
       private
 
@@ -40,11 +41,7 @@ module RailsAiContext
         end
 
         routes = Payload.section(context, :routes)
-        if routes
-          lines << "- Routes: #{count_phrase(RouteCoverage.app_route_count(routes), "app route")} across " \
-                   "#{RouteCoverage.controller_phrase(routes)} " \
-                   "(#{routes[:total_routes]} total incl. framework#{RouteCoverage.suffix(routes)})"
-        end
+        lines << "- Routes: #{RouteCoverage.summary(routes)}" if routes
 
         jobs = Payload.section(context, :jobs)
         if jobs
@@ -60,11 +57,8 @@ module RailsAiContext
           lines << "- Async: #{parts.join(', ')}" if parts.any?
         end
 
-        migrations = Payload.section(context, :migrations)
-        if migrations
-          line = "- Migrations: #{migrations[:total]} total"
-          line += ", #{Payload.pending_migrations(context).size} pending" if migrations.key?(:pending)
-          lines << line
+        if (migrations_line = SectionFacts.migrations_line(context))
+          lines << migrations_line
         end
 
         lines.concat(full_preset_stack_lines)
@@ -97,7 +91,10 @@ module RailsAiContext
           extras = model_extras_line(data)
           lines << extras if extras
         end
-        lines << "- _...#{models.size - max_show} more (use `rails_get_model_details` tool)_" if models.size > max_show
+        if models.size > max_show
+          use = " (use #{tool_named("rails_get_model_details")})" if served?("rails_get_model_details")
+          lines << "- _...#{models.size - max_show} more#{use}_"
+        end
         lines << ""
         lines
       end
@@ -130,23 +127,28 @@ module RailsAiContext
         SectionFacts.warnings(context)
       end
 
-      TRIM_NOTE = "_Context trimmed. Use MCP tools for full details._"
+      # Where the cut detail is: the tools, as the mode reaches them.
+      def trim_note
+        "_Context trimmed. Use #{tools_noun} for full details._"
+      end
 
-      # Counts non-blank physical lines. `keep` holds the trailing how-to-behave sections, so an
-      # over-budget file loses the data above them, which the MCP tools answer in full.
-      def enforce_max_lines(lines, keep: [])
+      # Counts non-blank physical lines. `head` (the title block) and `keep`
+      # (the trailing how-to-behave sections: commands, warnings, rules, the
+      # tools guide and its protocol) are never cut. An over-budget file
+      # loses the data between them, which the tools answer in full, down to
+      # none of it, so a budget smaller than the kept sections leaves just
+      # them: the guide is what makes a compact file worth reading.
+      def enforce_max_lines(lines, head: [], keep: [])
         # The BEGIN/END markers the writer adds count against the budget.
         max = RailsAiContext.configuration.claude_max_lines - SectionMarkerWriter::MARKER_LINES
+        head = physical(head)
         body = physical(lines)
         tail = physical(keep)
-        return (body + tail).join("\n") if content_count(body) + content_count(tail) <= max
-
-        # A hard cap: a tail too big to fit is trimmed from the end like any other overflow.
-        budget = max - 1 - content_count(tail)
-        return truncate(body + tail, max - 1).join("\n") if budget <= 0
+        fixed = content_count(head) + content_count(tail)
+        return (head + body + tail).join("\n") if fixed + content_count(body) <= max
 
         separator = tail.empty? ? [] : [ "" ]
-        (truncate(body, budget) + separator + tail).join("\n")
+        (head + truncate(body, max - 1 - fixed) + separator + tail).join("\n")
       end
 
       def physical(lines)
@@ -176,7 +178,7 @@ module RailsAiContext
         # nested headings and separators included.
         kept.pop while kept.any? && (kept.last.strip.empty? || heading?(kept.last))
         kept << "" if kept.any?
-        kept << TRIM_NOTE
+        kept << trim_note
       end
 
       def heading?(line)
@@ -202,11 +204,17 @@ module RailsAiContext
 
         # The scan decides, so services under a configured extra path show wherever
         # the conventions walk looked.
+        names = []
         services = service_names
-        lines << "" << "**Services:** #{services.join(', ')}" if services.any?
-
+        names << "**Services:** #{services.join(', ')}" if services.any?
         jobs = job_names
-        lines << "**Jobs:** #{jobs.join(', ')}" if jobs.any?
+        names << "**Jobs:** #{jobs.join(', ')}" if jobs.any?
+
+        # The blank line sets the names apart from a pattern list. With no list
+        # above them - the static tier reads no conventions - it left the
+        # heading standing over nothing.
+        lines << "" if lines.any? && names.any?
+        lines.concat(names)
         return [] if lines.empty?
 
         [ "## Architecture", *lines, "" ]
@@ -246,15 +254,9 @@ module RailsAiContext
 
       # The compact pipeline behind CLAUDE.md, AGENTS.md, .cursorrules and copilot-instructions.md.
       def render_compact_rules
-        lines = []
-        lines.concat(render_header)
-        lines.concat(render_stack_overview)
-        lines.concat(render_key_models)
-        lines.concat(render_notable_gems)
-        lines.concat(render_architecture)
-
+        data = render_stack_overview + render_key_models + render_notable_gems + render_architecture
         instructions = render_commands + render_warnings + render_footer + render_tools_guide_compact
-        enforce_max_lines(lines, keep: instructions)
+        enforce_max_lines(data, head: render_header, keep: instructions)
       end
     end
   end

data/lib/rails_ai_context/serializers/context_file_serializer.rb

@@ -55,14 +55,19 @@ module RailsAiContext
       end
 
       # Callers that pay for an introspection before writing check the format
-      # first, so a name nothing can write is refused before the work.
+      # first, so a name nothing can write is refused before the work. The
+      # names come in the order the CLI's help lists them, and a single name
+      # (a command's --format or argument) may also be `all`; a list, which
+      # is config.ai_tools, may not.
       def self.validate_format!(format)
         return if format.nil? || format == :all
 
         unknown = Array(format).reject { |fmt| ALL_FORMATS.include?(fmt) }
         return if unknown.empty?
 
-        raise ArgumentError, "Unknown format: #{unknown.first}. Valid formats: #{ALL_FORMATS.map(&:to_s).join(', ')}"
+        valid = (Install::AiTool.all.map(&:key) & ALL_FORMATS) | ALL_FORMATS
+        valid += [ :all ] unless format.is_a?(Array)
+        raise ArgumentError, "Unknown format: #{unknown.first}. Valid formats: #{valid.join(', ')}"
       end
 
       # Write context files, skipping unchanged ones.
@@ -85,9 +90,7 @@ module RailsAiContext
         # - a different path from a boot that started and failed.
         output_dir = RailsAiContext.configuration.output_dir_for(RailsAiContext.default_app)
         generate_root = RailsAiContext.configuration.generate_root_files
-        written = []
-        skipped = []
-        not_applicable = {}
+        result = { written: [], skipped: [], not_applicable: {} }
 
         seen_root_files = Set.new
 
@@ -105,7 +108,7 @@ module RailsAiContext
           # generate_root_files = false is a deliberate omission, so it is
           # reported rather than dropped. The JSON dump is no tool's root file.
           unless generate_root || fmt == :json
-            not_applicable[filepath] = "root files disabled"
+            result[:not_applicable][filepath] = "root files disabled"
             next
           end
 
@@ -113,16 +116,16 @@ module RailsAiContext
           content = serialize(fmt)
 
           if fmt == :json
-            write_plain(filepath, content, written, skipped)
+            write_plain(filepath, content, result)
           else
-            write_with_markers(filepath, content, written, skipped)
+            SectionMarkerWriter.report(SectionMarkerWriter.write_with_markers(filepath, content), filepath, result)
           end
         end
 
         # Split rules are always generated regardless of generate_root_files
-        generate_split_rules(formats, output_dir, written, skipped, not_applicable)
+        generate_split_rules(formats, output_dir, result)
 
-        { written: written, skipped: skipped, not_applicable: not_applicable }
+        result
       end
 
       private
@@ -132,12 +135,12 @@ module RailsAiContext
       end
 
       # JSON and other formats that don't support HTML comments
-      def write_plain(filepath, content, written, skipped)
+      def write_plain(filepath, content, result)
         if File.exist?(filepath) && same_payload?(File.read(filepath), content)
-          skipped << filepath
+          result[:skipped] << filepath
         else
           RailsAiContext::SafeFile.atomic_write(filepath, content)
-          written << filepath
+          result[:written] << filepath
         end
       end
 
@@ -154,25 +157,14 @@ module RailsAiContext
         false
       end
 
-      # Wrap content in section markers so user content is preserved.
-      # Delegates to SectionMarkerWriter (also used by CursorRulesSerializer
-      # for .cursorrules) so the marker contract is implemented in exactly
-      # one place.
-      def write_with_markers(filepath, content, written, skipped)
-        case SectionMarkerWriter.write_with_markers(filepath, content)
-        when :written then written << filepath
-        when :skipped then skipped << filepath
-        end
-      end
-
-      def generate_split_rules(formats, output_dir, written, skipped, not_applicable)
+      def generate_split_rules(formats, output_dir, result)
         serializers = formats.filter_map { |fmt| RULES_SERIALIZERS[fmt] }.uniq
 
         serializers.each do |serializer|
-          result = serializer.new(context).call(output_dir)
-          written.concat(result[:written])
-          skipped.concat(result[:skipped])
-          not_applicable.merge!(result[:not_applicable] || {})
+          rules = serializer.new(context).call(output_dir)
+          result[:written].concat(rules[:written])
+          result[:skipped].concat(rules[:skipped])
+          result[:not_applicable].merge!(rules[:not_applicable] || {})
         end
       end
     end