rails-ai-bridge 3.6.1 → 3.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ecc139c0066902b92342f732a9e9344b5aa5468153f6193708fa95815bbe0535
-  data.tar.gz: 05fe2c9d0ada4aa7a836b1dea1ec70f60ad75a94f87c4b4ff5b29e6c4fe9ca81
+  metadata.gz: eb96afa6948003790b0b563b8eef3730f2b438827727c153bcb785dadcc4174c
+  data.tar.gz: ab704409578f9717495b18007632dcd1730db3758e14e3af31f7e1683a99c58c
 SHA512:
-  metadata.gz: 73de5c66876b8b4ca8e7a50e3bdaaf8700984f23f884f492d7ebc880aee3fd3345efd847c4d4252012ac920c8e5450877767e79e48ecdc141f74b0d0d5dc5dd8
-  data.tar.gz: '08b0c68f5f5af762af8c87e937ba5360f5fa6732f07b3543d24bb000e118f5dad55ca4228984f7f88dc471ea70b8f3a75f8ae4b3a3dbd4eacbef205be1683cfa'
+  metadata.gz: 298fa9f82f3217c75701931742d9107dd9cf964a957740d120de309fe7fd56573124b06b425fe60529de35311792402611570eba579d4f6e7b98cd8af0f3e26f
+  data.tar.gz: 81464c5b6590fed85d45b87620bf7f8f3338336e2a9e83f36e6c584de86a7869abaad9430ef402bdda784e9d06fe2ad30ac3d8b89b62dafc80868ebc7ae74307

data/CHANGELOG.md

@@ -7,6 +7,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [4.0.0] - 2026-08-08 (planned)
+
+### Changed (breaking)
+
+- **`mcp` gem raised to 1.x** (#104/#118) — gemspec now requires `mcp >= 1.0, < 2.0` (was `>= 0.25, < 1.0`). Full suite green on **mcp 1.1.0** with no production code changes. Hosts must run `bundle update mcp` after upgrading. See [UPGRADING.md](UPGRADING.md) for details.
+
+### Fixed
+
+- **Ruby 4.0 test timing** (#104/#118) — ReDoS and perf specs use `Process.clock_gettime` instead of the `benchmark` gem (no longer a default gem on Ruby 4.0+).
+
+## [3.7.0] - 2026-08-08
+
+### Added
+
+- **Managed regions preserve hand-authored content in provider files** (#98/#119) — opt in with `config.output.managed_region = true` (or `MERGE=1 rails ai:bridge`) and generated context is confined to a `<!-- BEGIN rails-ai-bridge: … -->` / `<!-- END rails-ai-bridge -->` block. Prose written above or below the block survives every regeneration. A pre-existing hand-authored file gets the block **appended** rather than clobbered; a file this gem previously generated (detected via its leading freshness header) is replaced, so opting in never leaves a stale second copy of the context above the block. Markdown provider files only (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.github/copilot-instructions.md`, `.cursorrules`, `.devinrules`); `.ai-context.json` never receives markers. Default behavior is unchanged — files are still rewritten in full unless you opt in.
+- **`ai:doctor` reads freshness from inside the managed region** (#98/#119) — files whose freshness header is preceded by hand-authored prose are no longer misreported as stale. `.ai-context.json` is still read whole, since it never carries markers.
+
+### Fixed
+
+- **Decoupled `ManagedRegionLayout` from `FreshnessHeader::HEADER_PATTERN`** (#120) — extracted a public `FreshnessHeader.gem_generated?` predicate so the layout doesn't reach into a private constant. Memoized `whole_file_output` to avoid duplicate header checks per write cycle.
+- **Trailing blank lines on append** (#120) — `ManagedRegion.merge` now uses `rstrip` instead of `chomp`, so appending to a file with multiple trailing newlines doesn't produce extra blank lines.
+- **Documented marker edge cases** (#120) — README now warns about marker-shaped lines in hand-authored prose and about deleting both markers.
+
+## [3.6.2] - 2026-08-07
+
+### Added
+
+- **`structure.sql` support in offline/static schema introspection** (#96/#97/#116) — apps using `config.active_record.schema_format = :sql` (no `db/schema.rb`) now get table, column, index, and foreign-key context offline via `Introspectors::Schema::StaticStructureSqlParser`. The live-connection path was already format-agnostic. Output shape matches the live introspector so formatters work unchanged. Partition-child tables (`CREATE TABLE … PARTITION OF …`) are not expanded (follow-up).
+
+### Fixed
+
+- **`ai:doctor` schema check for `schema_format = :sql`** (#96/#97/#116) — Schema check passes when `db/structure.sql` is present; fix hint points at `rails db:migrate` (or `rails db:schema:dump`).
+
 ## [3.6.1] - 2026-08-07
 
 ### Security

data/README.md

@@ -536,6 +536,7 @@ end
 | `http_port` | `6029` | HTTP server port |
 | `cache_ttl` | `30` | Cache TTL in seconds |
 | `watcher_formats` | `:all` | Formats regenerated by `rails ai:watch` (e.g. `%i[claude cursor]` to limit churn) |
+| `managed_region` | `false` | Confine generated output to a marked block so hand-authored content in `CLAUDE.md` & co. survives regeneration |
 | `parallel_introspection` | `false` | Run introspectors concurrently (requires `concurrent-ruby`, which is already a Rails dependency) |
 | `parallel_pool_size` | `4` | Max threads in the parallel pool; capped at the number of active introspectors so no idle threads are created |
 | `parallel_timeout_seconds` | `10` | Per-introspector future timeout (seconds); timed-out introspectors return `{ error: "timed out after Ns" }` without blocking the others |
@@ -550,6 +551,55 @@ end
 Other HTTP MCP knobs live only on the nested object, for example `RailsAiBridge.configuration.mcp.authorize`, `mcp.mode`, `mcp.security_profile`, and `mcp.require_auth_in_production` — see [docs/GUIDE.md](docs/GUIDE.md) and [docs/mcp-security.md](docs/mcp-security.md).
 </details>
 
+### Keeping your own notes in `CLAUDE.md`
+
+By default every `rails ai:bridge` run rewrites each provider file in full, so hand-authored
+guidance is lost. Opt into **managed regions** to keep it:
+
+```ruby
+RailsAiBridge.configure do |config|
+  config.output.managed_region = true
+end
+```
+
+or per run: `MERGE=1 rails ai:bridge` (and `MERGE=0` to force a full rewrite).
+
+Generated content is then confined to a marked block, and anything you write around it is
+left alone:
+
+```markdown
+# House rules
+
+Always run `bin/rubocop` before committing.
+
+<!-- BEGIN rails-ai-bridge: generated. Edits inside this block are overwritten on `rails ai:bridge`. -->
+…generated context…
+<!-- END rails-ai-bridge -->
+```
+
+- **No file yet** → the marked block is written on its own.
+- **Markers present** → only the block is replaced; content above and below is untouched.
+- **Existing file, no markers** → the block is **appended**; your file is not clobbered.
+- **Existing file that this gem generated** (its first line is the `<!-- Generated at: … -->`
+  header) → replaced, not appended, so turning the flag on doesn't leave a stale second
+  copy of the context above the block. If you had appended prose to that generated file,
+  wrap the generated part in the markers by hand before your first run to keep it.
+
+Markdown provider files only (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`,
+`.github/copilot-instructions.md`, `.cursorrules`, `.devinrules`). `.ai-context.json` never
+receives markers. Freshness skipping and `ai:doctor` staleness both read through the region,
+so unchanged runs are still no-ops.
+
+**Caveats:**
+
+- Avoid writing marker-shaped lines (`<!-- BEGIN rails-ai-bridge: … -->` or
+  `<!-- END rails-ai-bridge -->`) in your own prose — the first BEGIN and the first
+  following END delimit the managed region, so a stray marker in hand-authored content
+  would truncate or misidentify the block.
+- If you delete both markers from a file, the old generated content is treated as your
+  own prose on the next run and a new block is appended. Re-add markers around the
+  generated part before your next run, or delete it manually.
+
 ### Extending the built-ins
 
 If you need host-app or companion-gem extensions, register them explicitly in the initializer:
@@ -781,7 +831,7 @@ Bug reports and pull requests: [github.com/igmarin/rails-ai-bridge/issues](https
 
 ## Acknowledgments & Origins
 
-This gem ships as **rails-ai-bridge** (Ruby **`RailsAiBridge`**, version **3.6.1**). Earlier iterations of the same codebase were distributed as `rails-ai-context`.
+This gem ships as **rails-ai-bridge** (Ruby **`RailsAiBridge`**, version **3.6.2**). Earlier iterations of the same codebase were distributed as `rails-ai-context`.
 
 RailsMCP evolved from 
 [crisnahine/rails-ai-context](https://github.com/crisnahine/rails-ai-context),

data/UPGRADING.md

@@ -1,5 +1,16 @@
 # Upgrading rails-ai-bridge
 
+## Upgrading from 3.6.1 to 3.6.2
+
+**No configuration changes required.**
+
+If your app uses `config.active_record.schema_format = :sql`, offline schema
+introspection and `rails ai:doctor` now use `db/structure.sql` automatically
+(no need for `db/schema.rb`). Live DB introspection was already format-agnostic.
+
+---
+
+
 ## Upgrading from 3.6.0 to 3.6.1
 
 **One action required if you are pinned to `rubydex` 0.2.x:**

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

@@ -146,6 +146,14 @@ module RailsAiBridge
             # from config/rails_ai_bridge/overrides.md before this has any effect.
             # config.assistant_overrides_path = "config/rails_ai_bridge/overrides.md"
 
+            # Keep hand-authored prose inline in CLAUDE.md / AGENTS.md / GEMINI.md.
+            # When true, generated content is confined to a marked block:
+            #   <!-- BEGIN rails-ai-bridge: generated ... -->  ...  <!-- END rails-ai-bridge -->
+            # Anything you write above or below that block survives every regeneration, and an
+            # existing file without markers gets the block appended rather than overwritten.
+            # Never applies to .ai-context.json. Per-run override: `MERGE=1 rails ai:bridge`.
+            # config.output.managed_region = true
+
             # Model list size caps for compact output (0 = show no names, only MCP pointer):
             # Reduce these for apps with large model counts to keep files within size limits.
             # config.copilot_compact_model_list_limit = 15   # default

data/lib/rails_ai_bridge/config/output.rb

@@ -29,6 +29,11 @@ module RailsAiBridge
       #   Defaults to +:all+. Set to e.g. +%i[claude cursor]+ to limit churn.
       attr_accessor :watcher_formats
 
+      # @return [Boolean] when +true+, generated output is confined to a marked region
+      #   in each markdown provider file so hand-authored content around it survives
+      #   regeneration. Never applies to +.ai-context.json+. Defaults to +false+.
+      attr_accessor :managed_region
+
       def initialize
         @output_dir                     = nil
         @context_mode                   = :compact
@@ -38,6 +43,7 @@ module RailsAiBridge
         @copilot_compact_model_list_limit = 5
         @codex_compact_model_list_limit   = 3
         @watcher_formats                  = :all
+        @managed_region                   = false
       end
 
       # Resolve the effective output directory.

data/lib/rails_ai_bridge/configuration.rb

@@ -151,6 +151,7 @@ module RailsAiBridge
                    :copilot_compact_model_list_limit, :copilot_compact_model_list_limit=,
                    :codex_compact_model_list_limit, :codex_compact_model_list_limit=,
                    :watcher_formats, :watcher_formats=,
+                   :managed_region, :managed_region=,
                    :output_dir_for
   end
 end

data/lib/rails_ai_bridge/doctor/checkers/bridge_freshness_checker.rb

@@ -95,18 +95,37 @@ module RailsAiBridge
 
         # Checks whether a single file's embedded fingerprint matches the current one.
         #
+        # Reads through the managed region when one is present, so files generated with
+        # +config.output.managed_region+ (where hand-authored prose precedes the freshness
+        # header) are not misreported as stale.
+        #
         # @param fmt [Symbol] format key
         # @param filepath [String] absolute file path
         # @param current_fp [String] current source fingerprint
         # @return [Boolean] +true+ if the file is stale or unreadable
         # :reek:UtilityFunction
         def stale?(fmt, filepath, current_fp)
-          content = File.read(filepath)
+          content = read_generated_payload(fmt, filepath)
           RailsAiBridge::FreshnessHeader.extract_fingerprint_for(fmt, content) != current_fp
         rescue StandardError
           true
         end
 
+        # Reads a bridge file, narrowing to the managed region for formats that can carry
+        # one. JSON never gets markers, so it is read whole — narrowing it on a stray
+        # marker-shaped string value would truncate valid JSON.
+        #
+        # @param fmt [Symbol] format key
+        # @param filepath [String] absolute file path
+        # @return [String] content to read freshness metadata from
+        # :reek:UtilityFunction
+        def read_generated_payload(fmt, filepath)
+          content = File.read(filepath)
+          return content if RailsAiBridge::Serializers::ContextFileSerializer::UNMANAGEABLE_FORMATS.include?(fmt)
+
+          RailsAiBridge::Serializers::ManagedRegion.generated_payload(content)
+        end
+
         # Builds the diagnostic outcome from a scan result.
         #
         # @param scan [ScanResult] file scan results

data/lib/rails_ai_bridge/doctor/checkers/schema_checker.rb

@@ -3,18 +3,31 @@
 module RailsAiBridge
   class Doctor
     module Checkers
-      # Verifies +db/schema.rb+ exists for schema-driven AI context.
+      # Verifies a schema file exists for schema-driven AI context. Accepts
+      # either +db/schema.rb+ (+schema_format = :ruby+) or +db/structure.sql+
+      # (+schema_format = :sql+).
       class SchemaChecker < BaseChecker
-        # @return [Doctor::Check] +:pass+ when the schema file exists; +:warn+ otherwise
+        # @return [Doctor::Check] +:pass+ when a schema file exists; +:warn+ otherwise
         def call
-          schema_path = File.join(app.root, 'db/schema.rb')
+          schema_file = present_schema_file
           check(
             'Schema',
-            File.exist?(schema_path),
-            pass: { message: 'db/schema.rb found' },
-            fail: { status: :warn, message: 'db/schema.rb not found', fix: 'Run `rails db:schema:dump` to generate it' }
+            schema_file,
+            pass: { message: "#{schema_file} found" },
+            fail: {
+              status: :warn,
+              message: 'db/schema.rb or db/structure.sql not found',
+              fix: 'Run `rails db:migrate` (or `rails db:schema:dump`) to generate one'
+            }
           )
         end
+
+        private
+
+        # @return [String, nil] the schema file that exists (schema.rb preferred), or +nil+
+        def present_schema_file
+          %w[db/schema.rb db/structure.sql].find { |rel| File.exist?(File.join(app.root, rel)) }
+        end
       end
     end
   end

data/lib/rails_ai_bridge/freshness_header.rb

@@ -84,6 +84,17 @@ module RailsAiBridge
         match ? match[3] : nil
       end
 
+      # Returns +true+ when +content+ starts with the gem's freshness header,
+      # indicating it is prior whole-file output from this gem (not hand-authored).
+      #
+      # @param content [String, nil]
+      # @return [Boolean]
+      def gem_generated?(content)
+        return false unless content
+
+        HEADER_PATTERN.match?(content)
+      end
+
       private
 
       # Embeds freshness metadata into JSON content via a +_meta+ key.

data/lib/rails_ai_bridge/introspectors/schema/static_structure_sql_parser.rb

@@ -0,0 +1,293 @@
+# frozen_string_literal: true
+
+module RailsAiBridge
+  module Introspectors
+    module Schema
+      # Parses a +db/structure.sql+ file as plain text, without a live database
+      # connection. This is the +schema_format = :sql+ counterpart to
+      # {StaticSchemaParser}: apps that keep their schema as SQL (common on
+      # Postgres, where +schema.rb+ cannot represent partitions, views,
+      # extensions, or custom SQL) have no +db/schema.rb+ to fall back to in
+      # offline environments (CI, Claude Code, agent contexts).
+      #
+      # Each instance is single-use: construct it with the file content and a
+      # configuration object, call {#call}, and discard. No mutable state
+      # escapes the instance.
+      #
+      # == Supported DDL (pg_dump / structure.sql form)
+      #
+      # * +CREATE TABLE [IF NOT EXISTS] [schema.]name (+ — opens a table context
+      # * +<name> <type> ...+ — a column line inside the table body; the leading
+      #   identifier is the column and the remainder (minus +NOT NULL+/+DEFAULT+)
+      #   is the SQL type. Table-level constraint lines (+CONSTRAINT+,
+      #   +PRIMARY KEY+, +FOREIGN KEY+, …) are skipped.
+      # * +);+ — closes the current table context
+      # * +CREATE [UNIQUE] INDEX name ON [schema.]table USING method (cols)+ —
+      #   adds an index entry (first simple column) to the named table.
+      #   Functional/expression indexes (e.g. +lower(email)+) are skipped.
+      # * +ALTER TABLE [ONLY] table ADD CONSTRAINT ... FOREIGN KEY (col)
+      #   REFERENCES ref_table (pk)+ — adds a foreign-key entry to +table+
+      #   (pg_dump emits these in a separate constraints section).
+      #
+      # Unlike {StaticSchemaParser} (whose +schema.rb+ static form leaves foreign
+      # keys empty), +structure.sql+ spells foreign keys out as parseable DDL, so
+      # this parser populates them offline — matching what the live
+      # {SchemaIntrospector} path reports.
+      #
+      # Internal Rails tables (+ar_internal_metadata+, +schema_migrations+) and
+      # any table matching {Config::Introspection#excluded_tables} are silently
+      # skipped.
+      #
+      # @example
+      #   content = File.read("db/structure.sql")
+      #   result  = StaticStructureSqlParser.new(content: content, config: RailsAiBridge.configuration).call
+      #   # => { adapter: "static_parse", tables: { ... }, total_tables: N, note: "..." }
+      #
+      # @see RailsAiBridge::Introspectors::SchemaIntrospector
+      # @see RailsAiBridge::Introspectors::Schema::StaticSchemaParser
+      class StaticStructureSqlParser
+        # Regex matching a +CREATE TABLE+ declaration, tolerating +IF NOT EXISTS+,
+        # a schema qualifier (+public.+), and optional quoting of either part.
+        TABLE_LINE = /\ACREATE TABLE (?:IF NOT EXISTS\s+)?(?:[\w"]+\.)?"?([A-Za-z_]\w*)"?\s*\(/
+
+        # Regex matching the end of a table body (+);+ at column zero).
+        TABLE_END_LINE = /\A\)/
+
+        # Regex matching a column definition inside a table body: leading
+        # whitespace, an identifier (optionally quoted), then the type/modifiers.
+        COLUMN_LINE = /\A\s+"?([A-Za-z_]\w*)"?\s+(.+)/
+
+        # Regex matching a +CREATE INDEX+ statement. Captures the target table
+        # and the raw parenthesised column list; only the first column is kept
+        # (parity with {StaticSchemaParser}).
+        INDEX_LINE = /\ACREATE\s+(?:UNIQUE\s+)?INDEX\s+.+?\s+ON\s+(?:[\w"]+\.)?"?([A-Za-z_]\w*)"?\s+(?:USING\s+\w+\s+)?\(([^)]+)\)/
+
+        # Regex matching an +ALTER TABLE [ONLY] [schema.]table+ statement, which
+        # in pg_dump precedes an +ADD CONSTRAINT+ line. Captures the target table.
+        ALTER_TABLE_LINE = /\AALTER TABLE (?:ONLY\s+)?(?:[\w"]+\.)?"?([A-Za-z_]\w*)"?/
+
+        # Regex matching an +ADD CONSTRAINT ... FOREIGN KEY (cols) REFERENCES
+        # [schema.]ref_table (pk)+ clause. Captures local columns, referenced
+        # table, and referenced columns.
+        FOREIGN_KEY_LINE = /FOREIGN KEY\s*\(([^)]+)\)\s*REFERENCES\s+(?:[\w"]+\.)?"?([A-Za-z_]\w*)"?\s*\(([^)]+)\)/
+
+        # Regex matching an +ON DELETE <action>+ clause on a foreign-key line.
+        ON_DELETE = /ON DELETE ([A-Z ]+?)(?=\s+ON UPDATE|\s+(?:NOT\s+)?(?:DEFERRABLE|VALID)|[,;)]|\z)/i
+
+        # Regex matching an +ON UPDATE <action>+ clause on a foreign-key line.
+        ON_UPDATE = /ON UPDATE ([A-Z ]+?)(?=\s+(?:NOT\s+)?(?:DEFERRABLE|VALID)|[,;)]|\z)/i
+
+        # Rails-managed tables that must never appear in introspection output.
+        INTERNAL_TABLES = %w[ar_internal_metadata schema_migrations].freeze
+
+        # Table-level constraint keywords that share a column line's shape but
+        # are not columns.
+        CONSTRAINT_KEYWORDS = %w[CONSTRAINT PRIMARY FOREIGN UNIQUE CHECK EXCLUDE LIKE DEFERRABLE].freeze
+
+        # @param content [String] full text of +db/structure.sql+
+        # @param config  [RailsAiBridge::Config::Introspection, RailsAiBridge::Configuration]
+        #   any object that responds to +#excluded_table?+
+        def initialize(content:, config:)
+          @content       = content
+          @config        = config
+          @tables        = {}
+          @current_table = nil
+          @in_table      = false
+          @alter_target  = nil
+        end
+
+        # Parse the structure.sql content and return the tables hash. Never
+        # raises — malformed or non-UTF-8 input is caught and reported as an
+        # error hash, per the introspector contract.
+        #
+        # @return [Hash{Symbol => Object}] with keys +:adapter+, +:tables+,
+        #   +:total_tables+, and +:note+; or +{ error: }+ on failure
+        def call
+          @content.each_line { |line| parse_line(line) }
+
+          {
+            adapter: 'static_parse',
+            tables: @tables,
+            total_tables: @tables.size,
+            note: 'Parsed from db/structure.sql (no DB connection)'
+          }
+        rescue StandardError => error
+          { error: "Failed to parse db/structure.sql: #{error.message}" }
+        end
+
+        private
+
+        # Dispatches a single line to the table-body handler or the top-level
+        # (create/index/alter/foreign-key) handlers.
+        #
+        # @param line [String]
+        # @return [void]
+        def parse_line(line)
+          return parse_body_line(line) if @in_table
+          return if parse_table_line?(line)
+          return if parse_index_line?(line)
+          return if parse_alter_table_line?(line)
+
+          parse_foreign_key_line?(line)
+        end
+
+        # Opens a table context on a +CREATE TABLE+ line. Sets +@current_table+
+        # to +nil+ for skipped tables while still tracking that we are inside a
+        # body, so the closing +);+ is honoured.
+        #
+        # @param line [String]
+        # @return [Boolean] +true+ if the line matched
+        def parse_table_line?(line)
+          match = TABLE_LINE.match(line)
+          return false unless match
+
+          name = match[1]
+          @in_table = true
+          @current_table = skip_table?(name) ? nil : name
+          @tables[@current_table] = { columns: [], indexes: [], foreign_keys: [] } if @current_table
+          true
+        end
+
+        # Handles a line while inside a table body: either the closing paren or a
+        # column definition (constraint lines are ignored).
+        #
+        # @param line [String]
+        # @return [void]
+        def parse_body_line(line)
+          if TABLE_END_LINE.match?(line)
+            @in_table = false
+            @current_table = nil
+            return
+          end
+
+          parse_column_line(line) if @current_table
+        end
+
+        # Appends a column to the current table unless the line is a table-level
+        # constraint.
+        #
+        # @param line [String]
+        # @return [void]
+        def parse_column_line(line)
+          match = COLUMN_LINE.match(line)
+          return unless match
+          return if constraint_keyword?(match[1])
+
+          @tables[@current_table][:columns] << { name: match[1], type: normalize_type(match[2]) }
+        end
+
+        # Adds an index entry (first column only) to the matching table. No-ops
+        # when the table is not present in +@tables+.
+        #
+        # @param line [String]
+        # @return [Boolean] +true+ if the line matched
+        def parse_index_line?(line)
+          match = INDEX_LINE.match(line)
+          return false unless match
+
+          column = first_index_column(match[2])
+          @tables[match[1]]&.dig(:indexes)&.push({ columns: column }) if column
+          true
+        end
+
+        # Records the target table of an +ALTER TABLE+ statement so a following
+        # +ADD CONSTRAINT ... FOREIGN KEY+ line can attach to it. Sets
+        # +@alter_target+ to +nil+ for skipped/unknown tables.
+        #
+        # @param line [String]
+        # @return [Boolean] +true+ if the line matched
+        def parse_alter_table_line?(line)
+          match = ALTER_TABLE_LINE.match(line)
+          return false unless match
+
+          @alter_target = @tables.key?(match[1]) ? match[1] : nil
+          true
+        end
+
+        # Appends a foreign-key entry to the current +@alter_target+ table. Mirrors
+        # the live introspector's shape (+from_table+, +to_table+, +column+,
+        # +primary_key+, +on_delete+, +on_update+), keeping the first column of a
+        # composite key for parity with index handling. No-ops without a target.
+        #
+        # @param line [String]
+        # @return [Boolean] +true+ if the line matched
+        def parse_foreign_key_line?(line)
+          match = FOREIGN_KEY_LINE.match(line)
+          return false unless match
+          return true unless @alter_target
+
+          @tables[@alter_target][:foreign_keys] << {
+            from_table: @alter_target,
+            to_table: match[2],
+            column: first_identifier(match[1]),
+            primary_key: first_identifier(match[3]),
+            on_delete: fk_action(line, ON_DELETE),
+            on_update: fk_action(line, ON_UPDATE)
+          }.compact
+          true
+        end
+
+        # Strips a trailing comma and the +DEFAULT ...+ / +NOT NULL+ / +NULL+
+        # modifiers to leave the bare SQL type.
+        #
+        # @param raw [String] everything after the column name
+        # @return [String] the SQL type (e.g. +"character varying"+, +"bigint"+)
+        def normalize_type(raw)
+          raw.strip
+             .sub(/,\s*\z/, '')
+             .sub(/\s+DEFAULT\b.*\z/i, '')
+             .sub(/\s+NOT\s+NULL\s*\z/i, '')
+             .sub(/\s+NULL\s*\z/i, '')
+             .strip
+        end
+
+        # Extracts the first column identifier from an index's parenthesised
+        # column list. Keeps plain and opclass-qualified columns
+        # (+col varchar_pattern_ops+ → +col+) but returns +nil+ for functional
+        # or expression indexes (+lower(email)+) so they are skipped rather than
+        # mis-attributed to the function name.
+        #
+        # @param columns [String] raw text between the index parentheses
+        # @return [String, nil]
+        def first_index_column(columns)
+          first = columns.split(',').first&.strip
+          return nil if first.nil? || first.include?('(')
+
+          first.slice(/[A-Za-z_]\w*/)
+        end
+
+        # Returns the first identifier from a (possibly composite) column list.
+        #
+        # @param columns [String] comma-separated column list
+        # @return [String, nil]
+        def first_identifier(columns)
+          columns.split(',').first&.slice(/[A-Za-z_]\w*/)
+        end
+
+        # Extracts a normalized foreign-key referential action (e.g. +CASCADE+,
+        # +SET NULL+) from a line, or +nil+ when the clause is absent.
+        #
+        # @param line [String]
+        # @param pattern [Regexp] {ON_DELETE} or {ON_UPDATE}
+        # @return [String, nil]
+        def fk_action(line, pattern)
+          match = pattern.match(line)
+          match && match[1].strip.squeeze(' ').upcase
+        end
+
+        # @param name [String]
+        # @return [Boolean] +true+ when +name+ is a table-level constraint keyword
+        def constraint_keyword?(name)
+          CONSTRAINT_KEYWORDS.include?(name.upcase)
+        end
+
+        # @param name [String]
+        # @return [Boolean] +true+ when +name+ is internal or excluded by config
+        def skip_table?(name)
+          INTERNAL_TABLES.any? { |t| name.start_with?(t) } ||
+            @config.excluded_table?(name)
+        end
+      end
+    end
+  end
+end

data/lib/rails_ai_bridge/introspectors/schema_introspector.rb

@@ -4,11 +4,13 @@ module RailsAiBridge
   module Introspectors
     # Extracts database schema information — tables, columns, indexes, and
     # foreign keys — from a live ActiveRecord connection when available, or by
-    # falling back to text-parsing +db/schema.rb+ via
-    # {Schema::StaticSchemaParser} when no connection is present (CI, Claude
-    # Code, offline environments).
+    # text-parsing the schema file when no connection is present (CI, Claude
+    # Code, offline environments). The static fallback prefers +db/schema.rb+
+    # ({Schema::StaticSchemaParser}) and falls back to +db/structure.sql+
+    # ({Schema::StaticStructureSqlParser}) for +schema_format = :sql+ apps.
     #
     # @see Schema::StaticSchemaParser
+    # @see Schema::StaticStructureSqlParser
     class SchemaIntrospector
       # @return [Rails::Application]
       attr_reader :app
@@ -127,15 +129,27 @@ module RailsAiBridge
         File.join(app.root, 'db', 'schema.rb')
       end
 
-      # Fallback: parse db/schema.rb as text when the DB is not connected.
-      # Delegates all parsing to {Schema::StaticSchemaParser}.
+      def structure_sql_path
+        File.join(app.root, 'db', 'structure.sql')
+      end
+
+      # Fallback used when the DB is not connected. Prefers +db/schema.rb+
+      # (Ruby DSL) and falls back to +db/structure.sql+ (raw SQL) so
+      # +schema_format = :sql+ apps still get schema context offline.
       #
-      # @return [Hash] parsed schema result, or +{ error: }+ when the file is absent
+      # @return [Hash] parsed schema result, or +{ error: }+ when neither file exists
       def static_schema_parse
-        path = schema_file_path
-        return { error: "No schema.rb found at #{path}" } unless File.exist?(path)
-
-        Schema::StaticSchemaParser.new(content: File.read(path), config: config).call
+        if File.exist?(schema_file_path)
+          Schema::StaticSchemaParser.new(content: File.read(schema_file_path), config: config).call
+        elsif File.exist?(structure_sql_path)
+          Schema::StaticStructureSqlParser.new(content: File.read(structure_sql_path), config: config).call
+        else
+          { error: "No db/schema.rb or db/structure.sql found in #{File.join(app.root, 'db')}" }
+        end
+      rescue StandardError => error
+        # Guards the exist?/read race (file removed between check and read) and
+        # any other read failure, honouring the introspector never-raise contract.
+        { error: "Failed to read schema file: #{error.message}" }
       end
     end
   end

data/lib/rails_ai_bridge/path_resolver.rb

@@ -9,7 +9,7 @@ module RailsAiBridge
   # PathResolver is deliberately used by every introspector that needs to
   # locate files on disk (controller, model, view, stimulus, turbo, auth,
   # api, config, action_text, activeStorage, nonArModels — 11 callers as of
-  # v3.6.1). It is NOT a god class despite high betweenness centrality in
+  # v3.6.2). It is NOT a god class despite high betweenness centrality in
   # graph analyses: a foundational path-resolution utility is expected to
   # sit at the centre of the introspector graph. Splitting it would spread
   # path-safety logic (traversal guards, safe joins) across multiple files

data/lib/rails_ai_bridge/serializers/context_file_serializer.rb

@@ -20,18 +20,24 @@ module RailsAiBridge
 
       VALID_ON_CONFLICT_SYMBOLS = %i[overwrite skip prompt].freeze
 
+      # Managed regions are markdown-comment delimited, so JSON output never participates.
+      UNMANAGEABLE_FORMATS = %i[json].freeze
+
       # @param context [Hash] introspection context from {RailsAiBridge.introspect}
       # @param format [Symbol, Array<Symbol>] format(s) to generate
       # @param split_rules [Boolean] whether to generate per-assistant rule directories
       # @param on_conflict [:overwrite, :skip, :prompt, #call] conflict resolution strategy;
       #   any object responding to +:call+ is invoked with the filepath and must return a
       #   truthy value to allow overwriting
+      # @param managed_region [Boolean, nil] confine generated output to a marked region so
+      #   hand-authored content in the file survives; +nil+ inherits +config.output.managed_region+
       # @raise [ArgumentError] when +on_conflict+ is not a recognised symbol or callable
-      def initialize(context, format: :all, split_rules: true, on_conflict: :overwrite)
+      def initialize(context, format: :all, split_rules: true, on_conflict: :overwrite, managed_region: nil)
         @context     = context
         @format      = format
         @split_rules = split_rules
         @conflict_policy = ConflictPolicy.build(on_conflict)
+        @managed_region = managed_region.nil? ? RailsAiBridge.configuration.managed_region : managed_region
       end
 
       # Write context files to the configured output directory, skipping unchanged ones.
@@ -70,10 +76,22 @@ module RailsAiBridge
         filepath = File.join(output_dir, filename)
         FileUtils.mkdir_p(File.dirname(filepath))
 
-        writer = FreshnessWriter.new(fmt, serialize(fmt), fingerprint, timestamp_now)
+        writer = FreshnessWriter.new(fmt, serialize(fmt), fingerprint, timestamp_now, layout: layout_for(fmt))
         writer.write_to(filepath, @conflict_policy, written, skipped)
       end
 
+      # @param fmt [Symbol] format key
+      # @return [WholeFileLayout, ManagedRegionLayout] how the payload occupies the file
+      def layout_for(fmt)
+        managed_region?(fmt) ? ManagedRegionLayout.new : WholeFileLayout.new
+      end
+
+      # @param fmt [Symbol] format key
+      # @return [Boolean] +true+ when this format should write into a marked region
+      def managed_region?(fmt)
+        @managed_region && UNMANAGEABLE_FORMATS.exclude?(fmt)
+      end
+
       # @param filepath [String] candidate output path
       # @return [Boolean] +true+ when the file should be overwritten
       def overwrite?(filepath)
@@ -99,6 +117,56 @@ module RailsAiBridge
         end
       end
 
+      # Default layout: the generated payload is the entire file.
+      class WholeFileLayout
+        # @param existing [String, nil] current file content
+        # @return [String, nil] previously generated payload
+        def previous_payload(existing) = existing
+
+        # @param _existing [String, nil] current file content (discarded)
+        # @param payload [String] freshly generated content
+        # @return [String] content to write
+        def compose(_existing, payload) = payload
+      end
+
+      # Managed-region layout: only the marked block belongs to the gem; anything the
+      # user wrote above or below it is carried through untouched.
+      class ManagedRegionLayout
+        # @param existing [String, nil] current file content
+        # @return [String, nil] payload inside the markers, the whole file when it is
+        #   unmarked gem output, or +nil+ when the file is hand-authored
+        def previous_payload(existing)
+          ManagedRegion.extract(existing) || whole_file_output(existing)
+        end
+
+        # @param existing [String, nil] current file content
+        # @param payload [String] freshly generated content
+        # @return [String] content to write
+        def compose(existing, payload)
+          ManagedRegion.merge(whole_file_output(existing) ? nil : existing, payload)
+        end
+
+        private
+
+        # A file led by the freshness header is prior whole-file output from this gem, so
+        # none of it is hand-authored. Replacing it keeps the first run after opting in
+        # from appending a second copy of the context below the stale one — a duplicate
+        # that would then never refresh, because it now reads as user content.
+        #
+        # Memoized per instance so the header check runs once per write cycle, not twice
+        # (previous_payload + compose both call it).
+        #
+        # @param existing [String, nil] current file content
+        # @return [String, nil] +existing+ when it is unmarked gem output
+        def whole_file_output(existing)
+          return @cached_result if @cached_for == existing
+
+          @cached_for = existing
+          @cached_result = existing if existing && !ManagedRegion.markers?(existing) && FreshnessHeader.gem_generated?(existing)
+        end
+      end
+      private_constant :WholeFileLayout, :ManagedRegionLayout
+
       # Encapsulates format-specific freshness metadata embedding and file write logic.
       # Separating this from ContextFileSerializer removes ControlParameter and UtilityFunction
       # reek warnings from the serializer (the fmt-branching now lives in the right class).
@@ -107,11 +175,13 @@ module RailsAiBridge
         # @param raw_content [String] serialized content before freshness embedding
         # @param fingerprint [String] 12-char source fingerprint
         # @param timestamp_now [String] ISO 8601 UTC timestamp
-        def initialize(fmt, raw_content, fingerprint, timestamp_now)
+        # @param layout [#previous_payload, #compose] how the payload occupies the file
+        def initialize(fmt, raw_content, fingerprint, timestamp_now, layout: WholeFileLayout.new)
           @fmt         = fmt
           @raw_content = raw_content
           @fingerprint = fingerprint
           @timestamp_now = timestamp_now
+          @layout = layout
         end
 
         # Writes the file to disk, skipping if unchanged or blocked by the conflict policy.
@@ -124,13 +194,13 @@ module RailsAiBridge
         # :reek:LongParameterList
         def write_to(filepath, conflict_policy, written, skipped)
           existing_content = read_existing(filepath)
-          timestamp_to_use = resolve_timestamp(existing_content)
-          candidate = build_candidate_content(timestamp_to_use)
+          timestamp_to_use = resolve_timestamp(@layout.previous_payload(existing_content))
+          candidate = compose(existing_content, timestamp_to_use)
 
           if skip?(filepath, existing_content, candidate, conflict_policy)
             skipped << filepath
           else
-            write_file(filepath, candidate, timestamp_to_use)
+            write_file(filepath, existing_content, candidate, timestamp_to_use)
             written << filepath
           end
         end
@@ -141,10 +211,11 @@ module RailsAiBridge
           File.exist?(filepath) ? File.read(filepath) : nil
         end
 
-        def resolve_timestamp(existing_content)
-          return @timestamp_now unless existing_content
+        # @param previous_payload [String, nil] the gem-owned portion of the existing file
+        def resolve_timestamp(previous_payload)
+          return @timestamp_now unless previous_payload
 
-          embedded_fp, embedded_ts = FreshnessHeader.extract_metadata_for(@fmt, existing_content)
+          embedded_fp, embedded_ts = FreshnessHeader.extract_metadata_for(@fmt, previous_payload)
           embedded_fp == @fingerprint && embedded_ts ? embedded_ts : @timestamp_now
         end
 
@@ -152,12 +223,19 @@ module RailsAiBridge
           FreshnessHeader.embed_for(@fmt, @raw_content, timestamp, @fingerprint)
         end
 
+        # Full file content for the given timestamp, including any hand-authored
+        # content the layout preserves.
+        def compose(existing_content, timestamp)
+          @layout.compose(existing_content, build_candidate_content(timestamp))
+        end
+
         def skip?(filepath, existing_content, candidate, conflict_policy)
           existing_content && (existing_content == candidate || !conflict_policy.overwrite?(filepath))
         end
 
-        def write_file(filepath, candidate, timestamp_to_use)
-          final_content = timestamp_to_use == @timestamp_now ? candidate : build_candidate_content(@timestamp_now)
+        # :reek:LongParameterList
+        def write_file(filepath, existing_content, candidate, timestamp_to_use)
+          final_content = timestamp_to_use == @timestamp_now ? candidate : compose(existing_content, @timestamp_now)
           File.write(filepath, final_content)
         end
       end

data/lib/rails_ai_bridge/serializers/managed_region.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module RailsAiBridge
+  module Serializers
+    # Delimits the gem-owned portion of a generated provider file so hand-authored
+    # content around it survives regeneration.
+    #
+    # A managed file looks like:
+    #
+    #   House rules the team wrote by hand.
+    #
+    #   <!-- BEGIN rails-ai-bridge: generated. Edits inside this block are overwritten on `rails ai:bridge`. -->
+    #   …generated context…
+    #   <!-- END rails-ai-bridge -->
+    #
+    # Only the first region is treated as managed; everything else in the file belongs
+    # to the user and is never rewritten. An unterminated BEGIN marker (a truncated or
+    # hand-edited file) is treated as running to end of file, so the next run heals it
+    # rather than nesting a second block inside the first.
+    module ManagedRegion
+      BEGIN_MARKER = '<!-- BEGIN rails-ai-bridge: generated. Edits inside this block are overwritten on `rails ai:bridge`. -->'
+      END_MARKER   = '<!-- END rails-ai-bridge -->'
+
+      # Tolerant of marker-text drift (older gem versions worded the notice differently)
+      # and of trailing whitespace, so a region written by any version is still recognised.
+      BEGIN_PATTERN  = /^<!-- BEGIN rails-ai-bridge:[^\n]*-->[^\S\n]*\n/
+      END_PATTERN    = /^<!-- END rails-ai-bridge -->[^\S\n]*(?:\n|\z)/
+      REGION_PATTERN = /#{BEGIN_PATTERN}(.*?)(?:#{END_PATTERN}|\z)/m
+
+      class << self
+        # Wraps generated content in the managed-region markers.
+        #
+        # @param payload [String] generated content
+        # @return [String] marked block, newline-terminated
+        def wrap(payload)
+          "#{BEGIN_MARKER}\n#{payload.to_s.chomp}\n#{END_MARKER}\n"
+        end
+
+        # @param content [String, nil] file content to inspect
+        # @return [Boolean] +true+ when a managed region is present
+        def markers?(content)
+          return false unless content
+
+          REGION_PATTERN.match?(content)
+        end
+
+        # Extracts the generated payload from a managed file.
+        #
+        # @param content [String, nil] file content to inspect
+        # @return [String, nil] payload without markers, or +nil+ when unmarked
+        def extract(content)
+          return nil unless content
+
+          content[REGION_PATTERN, 1]&.chomp
+        end
+
+        # Returns the gem-owned portion of a file: the managed region when one is
+        # present, otherwise the whole file. Lets callers that only care about the
+        # generated payload (freshness metadata, staleness checks) stay agnostic
+        # about whether managed regions are enabled.
+        #
+        # @param content [String, nil] file content to inspect
+        # @return [String, nil]
+        def generated_payload(content)
+          extract(content) || content
+        end
+
+        # Combines existing file content with a freshly generated payload.
+        #
+        # * no existing content → the marked block alone
+        # * existing content with markers → only the region is replaced
+        # * existing content without markers → the block is appended, preserving the file
+        #
+        # @param existing [String, nil] current file content
+        # @param payload [String] generated content
+        # @return [String] content to write
+        def merge(existing, payload)
+          block = wrap(payload)
+          return block if existing.nil? || existing.strip.empty?
+          # Block form: a String replacement would interpret backslash escapes in the payload.
+          return existing.sub(REGION_PATTERN) { block } if markers?(existing)
+
+          "#{existing.rstrip}\n\n#{block}"
+        end
+      end
+    end
+  end
+end

data/lib/rails_ai_bridge/tasks/rails_ai_bridge.rake

@@ -41,6 +41,20 @@ module RailsAiBridge
       puts "📐 Context mode: #{mode}"
     end
 
+    # Overrides managed-region output from the +MERGE+ env var when it is set.
+    # +MERGE=1+ confines generated content to a marked block in each markdown provider
+    # file, preserving hand-authored prose around it. +MERGE=0+ forces whole-file writes
+    # even when the initializer turns managed regions on.
+    #
+    # @return [void]
+    def self.apply_managed_region_override
+      return unless ENV.key?('MERGE')
+
+      enabled = TRUTHY_ENV_VALUES.include?(ENV['MERGE'].to_s.downcase.strip)
+      RailsAiBridge.configuration.managed_region = enabled
+      puts enabled ? '🧩 Managed region: on (hand-authored content preserved)' : '🧩 Managed region: off (files rewritten in full)'
+    end
+
     # Returns :prompt when CONFIRM is one of "1", "true", "yes", "y" so rake tasks
     # ask before overwriting changed files. CONFIRM=0 or CONFIRM=false stays silent.
     # Resolves the conflict strategy from the +CONFIRM+ env var.
@@ -81,6 +95,7 @@ namespace :ai do
     require 'rails_ai_bridge'
 
     RailsAiBridge::RakeHelpers.apply_context_mode_override
+    RailsAiBridge::RakeHelpers.apply_managed_region_override
     RailsAiBridge::RakeHelpers.run_pre_generation_checks
 
     puts "🔍 Introspecting #{Rails.application.class.module_parent_name}..."
@@ -104,6 +119,7 @@ namespace :ai do
     require 'rails_ai_bridge'
 
     RailsAiBridge::RakeHelpers.apply_context_mode_override
+    RailsAiBridge::RakeHelpers.apply_managed_region_override
     RailsAiBridge::RakeHelpers.run_pre_generation_checks
 
     format = (args[:format] || ENV['FORMAT'] || 'claude').to_sym
@@ -128,6 +144,7 @@ namespace :ai do
         require 'rails_ai_bridge'
 
         RailsAiBridge::RakeHelpers.apply_context_mode_override
+        RailsAiBridge::RakeHelpers.apply_managed_region_override
         RailsAiBridge::RakeHelpers.run_pre_generation_checks
 
         puts "🔍 Introspecting #{Rails.application.class.module_parent_name}..."
@@ -148,6 +165,7 @@ namespace :ai do
       require 'rails_ai_bridge'
 
       RailsAiBridge::RakeHelpers.apply_context_mode_override
+      RailsAiBridge::RakeHelpers.apply_managed_region_override
       RailsAiBridge.configuration.context_mode = :full
       RailsAiBridge::RakeHelpers.run_pre_generation_checks
 

data/lib/rails_ai_bridge/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RailsAiBridge
-  VERSION = '3.6.1'
+  VERSION = '3.7.0'
 end

data/lib/rails_ai_bridge.rb

@@ -55,6 +55,8 @@ module RailsAiBridge
     # @option options [:overwrite, :skip, :prompt, #call] :on_conflict behaviour when a file exists with
     #   different content. +:overwrite+ (default) silently replaces; +:skip+ keeps the existing file;
     #   +:prompt+ asks via stdin; any callable receives the filepath and returns truthy to overwrite.
+    # @option options [Boolean] :managed_region confine generated output to a marked region in each
+    #   markdown provider file so hand-authored content survives; defaults to +config.output.managed_region+
     # @return [Hash{Symbol => Array<String>}] files grouped under +:written+ and +:skipped+
     # @raise [ArgumentError] when an unknown option key is passed
     def generate_context(app = nil, **options)
@@ -99,7 +101,7 @@ module RailsAiBridge
     private
 
     def validate_generate_context_options!(options)
-      allowed = %i[format split_rules on_conflict].to_set
+      allowed = %i[format split_rules on_conflict managed_region].to_set
       unknown = options.keys.to_set - allowed
       return if unknown.empty?
 
@@ -110,7 +112,8 @@ module RailsAiBridge
       Serializers::ContextFileSerializer.new(context,
                                              format: options.fetch(:format, :all),
                                              split_rules: options.fetch(:split_rules, true),
-                                             on_conflict: options.fetch(:on_conflict, :overwrite))
+                                             on_conflict: options.fetch(:on_conflict, :overwrite),
+                                             managed_region: options.fetch(:managed_region, nil))
     end
 
     public

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-ai-bridge
 version: !ruby/object:Gem::Version
-  version: 3.6.1
+  version: 3.7.0
 platform: ruby
 authors:
 - Ismael Marin
@@ -218,6 +218,7 @@ files:
 - lib/rails_ai_bridge/introspectors/rake_task_introspector.rb
 - lib/rails_ai_bridge/introspectors/route_introspector.rb
 - lib/rails_ai_bridge/introspectors/schema/static_schema_parser.rb
+- lib/rails_ai_bridge/introspectors/schema/static_structure_sql_parser.rb
 - lib/rails_ai_bridge/introspectors/schema_introspector.rb
 - lib/rails_ai_bridge/introspectors/seeds_introspector.rb
 - lib/rails_ai_bridge/introspectors/semantic_introspector.rb
@@ -304,6 +305,7 @@ files:
 - lib/rails_ai_bridge/serializers/formatters/sections/turbo_formatter.rb
 - lib/rails_ai_bridge/serializers/formatters/sections/views_formatter.rb
 - lib/rails_ai_bridge/serializers/json_serializer.rb
+- lib/rails_ai_bridge/serializers/managed_region.rb
 - lib/rails_ai_bridge/serializers/markdown_serializer.rb
 - lib/rails_ai_bridge/serializers/provider_document_header.rb
 - lib/rails_ai_bridge/serializers/providers/base.rb