rails-ai-context 5.32.0 → 5.32.2

data/lib/rails_ai_context/introspectors/structure_sql_reader.rb

@@ -11,17 +11,31 @@ module RailsAiContext
       module_function
 
       # @return [Hash] { dialect: Symbol, tables: { name => { columns:, indexes:, foreign_keys: } } }
-      def parse(content)
+      # search_path: the database's configured schema_search_path. rails_version: the app's,
+      # whose connection names extensions and enum types (PgNaming).
+      def parse(content, search_path: PgNaming::DEFAULT_SEARCH_PATH, rails_version: nil)
         tables = {}
+        # The tables the search path does not show bare, findable only by schema-qualified name.
+        qualified_tables = {}
         dialect = detect_sql_dialect(content)
         enums = enum_types(content)
+        # A short PostgreSQL dump can carry no marker detect_sql_dialect knows, so only MySQL and SQLite skip it.
+        created = %i[mysql sqlite].include?(dialect) ? [] : content.scan(CREATE_SCHEMA).map { |(name)| name.delete('"') }
+        path = PgNaming.existing_path(search_path, created)
+        creates = []
+        each_create_table(content) { |*create| creates << create }
+        view_matches = content.scan(VIEW)
+        virtual_matches = content.scan(VIRTUAL_TABLE)
+        relations = creates.map(&:first) + view_matches.map { |match| match[1] } + virtual_matches.map(&:first)
+        names = PgNaming.names(path, relations: relations.map { |name| qualified_name(name) }, types: enums.keys)
+        local = names.method(:relation)
 
         # Every table the file creates, by schema-qualified name, so a parent
         # outside the listed tables still resolves.
         all = {}
-        each_create_table(content) do |qualified, body, inherits, trailer|
+        creates.each do |qualified, body, inherits, trailer|
           name = qualified_name(qualified)
-          shown = shown_name(name)
+          shown = local.(name)
           next if shown.start_with?("ar_internal_metadata", "schema_migrations")
           # SQLite's own tables; Rails' data_sources leaves them out.
           next if dialect == :sqlite && shown.start_with?("sqlite_")
@@ -30,10 +44,14 @@ module RailsAiContext
           comment = trailer[/\bCOMMENT\s*=\s*'((?:[^']|'')*)'/i, 1]
           table[:comment] = comment.gsub("''", "'") if comment
           all[name] = { table: table, raw_types: raw_types, parents: inherits && split_top_level(inherits).map { |parent| qualified_name(parent) } }
-          tables[shown] = table if shown.match?(/\A\w+\z/)
+          if shown.match?(/\A\w+\z/)
+            tables[shown] = table
+          elsif shown.include?(".")
+            qualified_tables[shown] = table
+          end
         end
 
-        found_views = views(content)
+        found_views = views(view_matches, local)
         content.scan(/CREATE (UNIQUE )?INDEX\s+(?:CONCURRENTLY\s+)?(?:IF NOT EXISTS\s+)?[`"]?(\w+)[`"]?\s+ON\s+(?:ONLY\s+)?#{QUALIFIED_NAME}((?:(?!#{NEXT_STATEMENT})[^;])*)/m) do |unique, idx_name, table, rest|
           group = first_paren_group(rest)
           keys = index_keys(group)
@@ -47,7 +65,7 @@ module RailsAiContext
           include = options[/\A\s*INCLUDE\s*\(([^)]*)\)/i, 1]
           detail = SchemaConventions.index_detail(keys, using: rest[0, open][/\bUSING\s+(\w+)/i, 1]&.downcase, include: include && index_keys(include),
                                                         nulls_not_distinct: options.match?(/\bNULLS\s+NOT\s+DISTINCT\b/i), **key_options(group))
-          target = all.dig(qualified_name(table), :table) || found_views[shown_name(qualified_name(table))]
+          target = all.dig(qualified_name(table), :table) || found_views[local.(qualified_name(table))]
           (target[:indexes] ||= []) << { name: idx_name, columns: keys, unique: !!unique, where: where }.compact.merge(detail) if target
         end
 
@@ -66,7 +84,7 @@ module RailsAiContext
         # statement and attribute the FK to the wrong table.
         content.scan(/ALTER TABLE\s+(?:ONLY\s+)?#{QUALIFIED_NAME}\s+ADD CONSTRAINT[^;]*?FOREIGN KEY\s*\(([^)]*)\)\s*REFERENCES\s+#{QUALIFIED_NAME}\s*\(([^)]*)\)([^;]*)/m) do |from, cols, to, pks, tail|
           from = qualified_name(from)
-          all.dig(from, :table, :foreign_keys)&.push(SchemaConventions.foreign_key_entry(shown_name(from), shown_name(qualified_name(to)), cols.scan(/\w+/), pks.scan(/\w+/), **foreign_key_actions(tail)))
+          all.dig(from, :table, :foreign_keys)&.push(SchemaConventions.foreign_key_entry(local.(from), local.(qualified_name(to)), cols.scan(/\w+/), pks.scan(/\w+/), **foreign_key_actions(tail)))
         end
 
         alters = Hash.new { |h, k| h[k] = [] }
@@ -74,7 +92,10 @@ module RailsAiContext
           alters[qualified_name(table)] << [ column, change ]
         end
         resolved = {}
-        all.each_key { |name| resolve_columns(name, all, alters, resolved) }
+        all.each_key { |name| resolve_columns(name, all, alters, resolved, local) }
+        all.each_value do |entry|
+          entry[:table][:columns].each { |column| column[:enum_type] = names.type(column[:enum_type]) if column[:enum_type] }
+        end
 
         content.scan(/^COMMENT ON TABLE #{QUALIFIED_NAME} IS '((?:[^']|'')*)';/) do |table, text|
           table = all.dig(qualified_name(table), :table)
@@ -88,39 +109,44 @@ module RailsAiContext
 
         # pg_dump writes each partition as a table, then attaches it in exactly this form.
         content.scan(/^ALTER TABLE ONLY .+? ATTACH PARTITION #{QUALIFIED_NAME} /) do |(partition)|
-          name = qualified_name(partition)
-          tables.delete(shown_name(name)) if name.start_with?("public.")
+          shown = local.(qualified_name(partition))
+          (shown.include?(".") ? qualified_tables : tables).delete(shown)
         end
 
-        { dialect: dialect, tables: tables, enums: enums.map { |name, values| { name: name, values: values } },
-          views: found_views, virtual_tables: virtual_tables(content), extensions: extensions(content) }
+        { dialect: dialect, tables: tables, qualified_tables: qualified_tables, names: names, enums: PgNaming.enum_list(enums, path, rails_version),
+          views: found_views, virtual_tables: virtual_tables(virtual_matches, local), extensions: extensions(content, path, dialect, rails_version) }
       end
 
-      # As PostgreSQL's connection names them: qualified unless in the public schema.
-      def extensions(content)
-        content.scan(/^CREATE EXTENSION (?:IF NOT EXISTS )?("[^"]+"|\w+)(?: WITH SCHEMA ("[^"]+"|\w+))?/).map do |name, schema|
-          [ (schema.delete('"') unless schema.nil? || schema == "public"), name.delete('"') ].compact.join(".")
+      # As PostgreSQL's connection names them (PgNaming.extension_name).
+      def extensions(content, path, dialect, rails_version)
+        found = content.scan(/^CREATE EXTENSION (?:IF NOT EXISTS )?("[^"]+"|\w+)(?: WITH SCHEMA ("[^"]+"|\w+))?/).map do |name, schema|
+          [ name.delete('"'), schema&.delete('"') ]
+        end
+        # Every PostgreSQL database starts with plpgsql in pg_catalog, and pg_dump leaves it out.
+        if dialect == :postgresql && found.none? { |name, _| name == "plpgsql" } && !content.match?(/^DROP EXTENSION (?:IF EXISTS )?"?plpgsql\b/)
+          found.unshift([ "plpgsql", "pg_catalog" ])
         end
+        found.map { |name, schema| PgNaming.extension_name(name, schema, path, rails_version) }
       end
 
       # Each view by the name the app reads it under, a later definition of a name replacing a placeholder.
-      def views(content)
-        content.scan(VIEW).each_with_object({}) do |(materialized, name, sql), found|
-          name = qualified_name(name)
-          found[shown_name(name)] = { materialized: !materialized.nil?, sql: sql.strip } if shown_name(name).match?(/\A\w+\z/)
+      def views(view_matches, local)
+        view_matches.each_with_object({}) do |(materialized, name, sql), found|
+          name = local.(qualified_name(name))
+          found[name] = { materialized: !materialized.nil?, sql: sql.strip } if name.match?(/\A\w+\z/)
         end
       end
 
-      def virtual_tables(content)
-        content.scan(VIRTUAL_TABLE).to_h do |name, mod, arguments|
-          [ shown_name(qualified_name(name)), { module: mod, arguments: split_top_level(arguments.to_s) } ]
+      def virtual_tables(virtual_matches, local)
+        virtual_matches.to_h do |name, mod, arguments|
+          [ local.(qualified_name(name)), { module: mod, arguments: split_top_level(arguments.to_s) } ]
         end
       end
 
-      # PostgreSQL's enum types, by the name schema.rb gives them, with their labels.
+      # PostgreSQL's enum types by schema-qualified name, with their labels.
       def enum_types(content)
         content.scan(/CREATE TYPE\s+#{QUALIFIED_NAME}\s+AS\s+ENUM\s*\(([^;]*)\)\s*;/i).to_h do |name, labels|
-          [ shown_name(qualified_name(name)), split_top_level(labels).map { |label| label.delete_prefix("'").delete_suffix("'").gsub("''", "'") } ]
+          [ qualified_name(name), split_top_level(labels).map { |label| label.delete_prefix("'").delete_suffix("'").gsub("''", "'") } ]
         end
       end
 
@@ -190,6 +216,7 @@ module RailsAiContext
       INHERITS_KEYWORD = /\s*INHERITS\b/i
       # The optional INHERITS list after a CREATE TABLE body.
       INHERITS = /(?:#{INHERITS_KEYWORD}\s*\(([^)]*)\))?/
+      CREATE_SCHEMA = /^CREATE SCHEMA (?:IF NOT EXISTS )?("[^"]+"|\w+)/
       CREATE_TABLE = /CREATE TABLE\s+(?:IF NOT EXISTS\s+)?#{QUALIFIED_NAME}\s*(?=\()/i
       # mysqldump wraps the statement in version comments and names an algorithm, definer and security first;
       # sqlite3 closes it with a /* name(columns) */ comment.
@@ -203,13 +230,9 @@ module RailsAiContext
         parts.join(".")
       end
 
-      def shown_name(name)
-        SchemaConventions.local_name(name)
-      end
-
       # Each parent's columns, then the child's own. pg_dump writes only local
       # columns and sets an inherited one's NOT NULL and default by ALTER.
-      def resolve_columns(name, all, alters, resolved)
+      def resolve_columns(name, all, alters, resolved, local)
         entry = all[name]
         return entry if resolved[name]
 
@@ -219,11 +242,11 @@ module RailsAiContext
         unresolved = []
         entry[:parents]&.each do |parent|
           unless all[parent]
-            unresolved << shown_name(parent)
+            unresolved << local.(parent)
             next
           end
 
-          resolved_parent = resolve_columns(parent, all, alters, resolved)
+          resolved_parent = resolve_columns(parent, all, alters, resolved, local)
           resolved_parent[:table][:columns].each { |column| merge_column(columns, column.dup) }
           raw_types = resolved_parent[:raw_types].merge(raw_types)
           unresolved.concat(Array(resolved_parent[:table][:inherits_unresolved]))
@@ -432,7 +455,7 @@ module RailsAiContext
             nullable = !rest.match?(/\bNOT\s+NULL\b|\bPRIMARY\s+KEY\b/i)
             # An array is its element type with the flag, as schema.rb dumps it.
             type = normalize_sql_type(col_type.delete_suffix("[]"), dialect)
-            enum_type = shown_name(qualified_name(col_type.delete_suffix("[]"))) if col_type.match?(/\A(?:"[^"]+"|[\w.]+)(?:\[\])?\z/)
+            enum_type = qualified_name(col_type.delete_suffix("[]")) if col_type.match?(/\A(?:"[^"]+"|[\w.]+)(?:\[\])?\z/)
             type = "enum" if enum_type && enums.key?(enum_type)
             raw_types[col_name] = col_type
             column = { name: col_name, type: type, null: nullable }

data/lib/rails_ai_context/payload.rb

@@ -96,7 +96,7 @@ module RailsAiContext
     # A name in two databases answers `database`'s when given, else the primary's.
     def schema_table(schema, name, database: nil)
       found = table_holders(schema, name)
-      (found.find { |db, _, _| database && db == database.to_s } || found.first)&.last
+      (found.find { |db, _, _| database && db == database.to_s } || found.first)&.[](2)
     end
 
     # The table a model reads, from the database its `connects_to` writes to.
@@ -124,8 +124,31 @@ module RailsAiContext
       table_holders(schema, name).map { |db, _, _| db || "primary" }
     end
 
+    # A schema-qualified name the listing does not hold is looked up when asked for: a table outside
+    # the search path, or a listed one by its qualified name, as Rails resolves both.
     def table_holders(schema, name)
-      schema_tables(schema).select { |_, table, _| table.to_s == name.to_s }
+      found = schema_tables(schema).select { |_, table, _| table.to_s == name.to_s }
+      return found if found.any? || !name.to_s.include?(".") || !schema.is_a?(Hash)
+
+      secondary = schema[:secondary_databases].is_a?(Hash) ? schema[:secondary_databases].keys : []
+      [ nil, *secondary ].filter_map do |db|
+        live = db.nil? && !parsed_schema?(schema) && schema[:adapter].to_s.match?(/postg/i)
+        shown, data = Introspectors::SchemaIntrospector.qualified_table(name.to_s, database: db&.to_s, live: live)
+        # The fourth entry is the name the listing shows the table under, which its models read.
+        [ db&.to_s, name.to_s, data, shown ] if data
+      end
+    end
+
+    # Why the primary's dump leaves out a schema-qualified table, or nil.
+    def missing_qualified_table(schema, name)
+      return unless schema.is_a?(Hash) && parsed_schema?(schema) && name.to_s.include?(".")
+
+      Introspectors::SchemaIntrospector.qualified_table_note(name.to_s)
+    end
+
+    # Read from the dump: the context names the adapter and keeps "static_parse" under adapter_source.
+    def parsed_schema?(schema)
+      [ schema[:adapter], schema[:adapter_source] ].include?("static_parse")
     end
 
     def models(ctx)

data/lib/rails_ai_context/serializers/opencode_rules_serializer.rb

@@ -45,7 +45,7 @@ module RailsAiContext
         lines = [
           "# ActiveRecord Models (#{models.size})",
           "",
-          "> Auto-generated by rails-ai-context. Do not edit manually.",
+          "> #{Install::Cleanup::GENERATED_NOTE}",
           "> Check here first for scopes, constants, associations. Read model files for business logic/methods.",
           ""
         ]
@@ -87,7 +87,7 @@ module RailsAiContext
         lines = [
           "# Controllers (#{app_controllers.size})",
           "",
-          "> Auto-generated by rails-ai-context. Do not edit manually.",
+          "> #{Install::Cleanup::GENERATED_NOTE}",
           "> Read controller files directly when editing. Use MCP tools for reference only.",
           ""
         ]

data/lib/rails_ai_context/server.rb

@@ -274,7 +274,7 @@ module RailsAiContext
     end
 
     # Conditionally start live reload based on configuration.
-    # :auto  - try to load `listen`, skip silently with a tip if missing
+    # :auto  - try to load `listen`, print a tip to stderr if missing
     # true   - try to load `listen`, raise if missing
     # false  - skip entirely
     def maybe_start_live_reload(mcp_server)
@@ -291,7 +291,7 @@ module RailsAiContext
           raise LoadError, "Live reload requires the `listen` gem. Add to your Gemfile: gem 'listen', group: :development"
         end
 
-        # :auto mode - skip silently with a tip
+        # :auto mode - skip with a tip
         $stderr.puts "[rails-ai-context] Live reload unavailable (add `listen` gem for auto-refresh)"
       end
     end

data/lib/rails_ai_context/tasks/rails_ai_context.rake

@@ -77,14 +77,19 @@ def prompt_setup
   RailsAiContext::Install::Program.select_setup(install_surface)
 end unless defined?(prompt_setup)
 
+def say_conflict(key, status)
+  _level, text = RailsAiContext::Install::SelectionRecord.conflict_message(key, status)
+  puts "⚠️  #{text}" if text
+end unless defined?(say_conflict)
+
 def save_tool_mode_to_initializer(mode)
-  RailsAiContext::Install::SelectionRecord.write_tool_mode(mode, root: Rails.root)
+  say_conflict(:tool_mode, RailsAiContext::Install::SelectionRecord.write_tool_mode(mode, root: Rails.root))
 rescue => e
   RailsAiContext.debug_fail(e, nil, label: "save_tool_mode_to_initializer")
 end unless defined?(save_tool_mode_to_initializer)
 
 def save_context_files_to_initializer(value)
-  RailsAiContext::Install::SelectionRecord.write_context_files(value, root: Rails.root)
+  say_conflict(:context_files, RailsAiContext::Install::SelectionRecord.write_context_files(value, root: Rails.root))
 rescue => e
   RailsAiContext.debug_fail(e, nil, label: "save_context_files_to_initializer")
 end unless defined?(save_context_files_to_initializer)
@@ -100,7 +105,7 @@ rescue => e
 end unless defined?(ensure_mcp_configs)
 
 def tool_mode_configured?
-  !RailsAiContext::Install::SelectionRecord.tool_mode(root: Rails.root).nil?
+  RailsAiContext::Install::SelectionRecord.tool_mode_set?(root: Rails.root)
 rescue => e
   RailsAiContext.debug_fail(e, false, label: "tool_mode_configured?")
 end unless defined?(tool_mode_configured?)
@@ -295,7 +300,10 @@ namespace :ai do
   end
 
   namespace :context do
-    per_tool = RailsAiContext::Install::AiTool.all.to_h { |tool| [ tool.key, tool.files ] }
+    # The MCP config a tool's file list names is the installer's to write, not this task's.
+    per_tool = RailsAiContext::Install::AiTool.all.to_h { |tool|
+      [ tool.key, tool.files.split(" + ").reject { |file| file == tool.mcp_config[:path] }.join(" + ") ]
+    }
     per_tool.merge(json: ".ai-context.json").each do |fmt, file|
       desc "Generate #{file} context file"
       task fmt => :environment do

data/lib/rails_ai_context/test_helper.rb

@@ -4,6 +4,8 @@
 # Bundler.require never loads it in the test environment, so this file is
 # often the first (and only) entry point required from a test suite.
 require_relative "../rails_ai_context"
+# A custom tool subclasses MCP::Tool, and nothing else has loaded the SDK yet.
+require "mcp"
 
 module RailsAiContext
   # Reusable test helper for verifying MCP tools - both built-in and custom.

data/lib/rails_ai_context/tools/base_tool.rb

@@ -371,7 +371,9 @@ module RailsAiContext
         # the composers do not index into `content` themselves.
         def response_text(response)
           first = response.content.first
-          first.is_a?(Hash) ? first[:text].to_s : ""
+          text = first.is_a?(Hash) ? first[:text].to_s : ""
+          # The composing tool's own response carries the tier banner, once.
+          (banner = static_tier_banner) ? text.gsub(banner, "") : text
         end
 
         # One-line banner listing introspectors that failed during context

data/lib/rails_ai_context/tools/dependency_graph.rb

@@ -4,8 +4,8 @@ module RailsAiContext
   module Tools
     class DependencyGraph < BaseTool
       tool_name "rails_dependency_graph"
-      description "Generates a dependency graph showing how models, services, and controllers " \
-        "connect. Output as Mermaid diagram syntax or plain text. " \
+      description "Generates a dependency graph showing how models connect through their " \
+        "associations. Output as Mermaid diagram syntax or plain text. " \
         "Use when: understanding feature architecture, tracing data flow, planning refactors. " \
         "Key params: model (center graph on model), depth (1-3), format (mermaid/text)."
 

data/lib/rails_ai_context/tools/get_concern.rb

@@ -18,7 +18,7 @@ module RailsAiContext
             type: "string",
             description: "Filter by concern type, the name each section heading of the listing prints: model for app/models/concerns/, mailer for app/mailers/concerns/, and for a concern outside every concerns directory the root it lives in (service for app/services, lib for lib). other: app/concerns itself, or a configured directory. all: everything (default)."
           },
-          detail: RailsAiContext::DetailLevel.schema("Detail level. summary: concern names only. standard: names + method signatures (default). full: method signatures with source code.")
+          detail: RailsAiContext::DetailLevel.schema("Detail level, read when `name` is given. summary and standard (default): method signatures. full: method signatures with source code.")
         }
       )
 

data/lib/rails_ai_context/tools/get_env.rb

@@ -426,7 +426,7 @@ module RailsAiContext
       end
 
       private_class_method def self.scan_env_example(root)
-        # Only read .env.example or .env.sample - NEVER .env or .env.local
+        # Only the example files - NEVER .env or .env.local
         candidates = %w[.env.example .env.sample .env.template]
         vars = []
 

data/lib/rails_ai_context/tools/get_gems.rb

@@ -4,7 +4,7 @@ module RailsAiContext
   module Tools
     class GetGems < BaseTool
       tool_name "rails_get_gems"
-      description "Get notable gems from Gemfile.lock grouped by category: auth, jobs, frontend, API, database, testing, deploy. " \
+      description "Get notable gems from Gemfile.lock grouped by category (auth, jobs, frontend, API, database, testing, deploy and more). " \
         "Use when: checking what libraries are available before adding a dependency, or understanding the tech stack. " \
         "Filter with category:\"auth\" or category:\"database\". Omit for all categories."
 
@@ -12,7 +12,7 @@ module RailsAiContext
         properties: {
           category: {
             type: "string",
-            enum: %w[auth jobs frontend api database files testing deploy all],
+            enum: Introspectors::GemIntrospector::NOTABLE_GEMS.values.map { |gem| gem[:category].to_s }.uniq + %w[all],
             description: "Filter by category. Default: all."
           },
           offset: {

data/lib/rails_ai_context/tools/get_model_details.rb

@@ -212,6 +212,8 @@ module RailsAiContext
               end
             end
             lines << ignored_columns_line(ignored) if ignored.any?
+          elsif (why = Payload.missing_qualified_table(Payload.section(cached_context, :schema), data[:table_name]))
+            lines << "" << why
           end
         end
 

data/lib/rails_ai_context/tools/get_schema.rb

@@ -65,9 +65,9 @@ module RailsAiContext
             # "Post" and "Admin::ActionLog" are model names here, and the model
             # tier knows the table each of them reads.
             table_as_table = RailsAiContext::Introspectors::TableName.for_model_name(table, models_data)
-            _, table_key, table_data = Payload.schema_tables(schema).find { |_, k, _|
+            _, table_key, table_data, listed_as = Payload.schema_tables(schema).find { |_, k, _|
               k.downcase == table_down || k == table_as_table || k == table.underscore
-            }
+            } || Payload.table_holders(schema, table).first
             databases = table_data ? Payload.schema_databases(schema, table_key) : []
             database = databases.join(", ") unless databases == [ "primary" ]
             table_key ||= table
@@ -90,10 +90,11 @@ module RailsAiContext
 
               recovery = "Call rails_get_schema(detail:\"summary\") to see all tables"
               # Rails' own schema.rb dumper writes no view; only a gem such as scenic adds them.
-              if [ schema[:adapter], schema[:adapter_source] ].include?("static_parse")
+              if Payload.parsed_schema?(schema)
                 recovery += ". Without a connection a view is listed only when the dump records it: structure.sql does, schema.rb only through a gem such as scenic"
               end
-              return not_found_response("Table", table, Payload.schema_tables(schema).map { |_, name, _| name }.uniq.sort, recovery_tool: recovery)
+              return not_found_response("Table", table, Payload.schema_tables(schema).map { |_, name, _| name }.uniq.sort, recovery_tool: recovery,
+                                                                                                         note: Payload.missing_qualified_table(schema, table))
             end
             # Databases holding the same table read as one; ones that differ each show their own.
             groups = Payload.schema_tables(schema).select { |_, name, _| name == table_key }
@@ -103,16 +104,16 @@ module RailsAiContext
 
               output = groups.map do |dbs, data|
                 in_db = models_data.select { |_, model| model.is_a?(Hash) && model[:table_name] == table_key && Payload.model_databases(schema, model).intersect?(dbs) }
-                format_table_markdown(table_key, data, in_db, schema[:enum_types]).sub("\n\n", "\n\n**Database:** #{dbs.join(", ")}\n")
+                format_table_markdown(table_key, data, in_db, schema[:enum_types], schema[:search_path]).sub("\n\n", "\n\n**Database:** #{dbs.join(", ")}\n")
               end.join("\n\n")
             else
               return json_response(table_data.except(:unread_calls).merge({ database: database }.compact)) if format == "json"
 
-              output = format_table_markdown(table_key, table_data, models_data, schema[:enum_types])
+              output = format_table_markdown(table_key, table_data, models_data, schema[:enum_types], schema[:search_path], listed_as: listed_as)
               output = output.sub("\n\n", "\n\n**Database:** #{database}\n") if database
             end
             # Cross-reference hint for AI: suggest next tool call
-            model_refs = models_for_table(table_key, models_data)
+            model_refs = models_for_table([ table_key, listed_as ], models_data)
             if model_refs.any?
               output += "\n\n_Next: `rails_get_model_details(model:\"#{model_refs.first}\")` for associations, validations, scopes._"
             end
@@ -264,7 +265,7 @@ module RailsAiContext
             lines = [ "# Schema Full Detail (#{paginated.size} of #{Introspectors::SchemaConventions.relations_phrase(tables)})", "" ]
             lines.concat(note_lines(schema))
             paginated.each do |name|
-              lines << format_table_markdown(name, tables[name], models_data, schema[:enum_types])
+              lines << format_table_markdown(name, tables[name], models_data, schema[:enum_types], schema[:search_path])
               lines << ""
             end
             coverage = model_coverage_lines(tables, models_data)
@@ -342,8 +343,8 @@ module RailsAiContext
         RailsAiContext.debug_fail(e, Set.new, label: "declared_join_tables")
       end
 
-      private_class_method def self.models_for_table(table_name, models)
-        models.select { |_, d| d.is_a?(Hash) && d[:table_name] == table_name }.keys
+      private_class_method def self.models_for_table(table_names, models)
+        models.select { |_, d| d.is_a?(Hash) && Array(table_names).compact.include?(d[:table_name]) }.keys
       rescue => e
         RailsAiContext.debug_fail(e, [], label: "models_for_table")
       end
@@ -377,6 +378,8 @@ module RailsAiContext
       private_class_method def self.note_lines(schema)
         lines = schema[:note].to_s.empty? ? [] : [ "_#{schema[:note]}_" ]
         lines << "**Extensions:** #{schema[:extensions].join(', ')}" if schema[:extensions]&.any?
+        # The context keeps a search path only when it holds more than public.
+        lines << "**Search path:** #{schema[:search_path].join(', ')}" if schema[:search_path].is_a?(Array)
         lines
       end
 
@@ -522,12 +525,13 @@ module RailsAiContext
         end
       end
 
-      private_class_method def self.format_table_markdown(name, data, models, enum_types = nil)
+      # listed_as: the listing's name for a table asked for by its qualified name.
+      private_class_method def self.format_table_markdown(name, data, models, enum_types = nil, search_path = nil, listed_as: nil)
         columns = data[:columns] || []
         # Always show Nullable and Default - agents need these for migrations and validations
         has_defaults = columns.any? { |c| c.key?(:default) && !c[:default].nil? }
 
-        model_refs = models_for_table(name, models)
+        model_refs = models_for_table([ name, listed_as ], models)
         lines = [ "## #{RELATION_KINDS.fetch(data[:kind].to_s, "Table")}: #{name}", "" ]
         lines << "**Models:** #{model_refs.join(', ')}" if model_refs.any?
         lines << "**Module:** #{data[:module]}" if data[:module]
@@ -600,8 +604,7 @@ module RailsAiContext
           end
         end
 
-        used = columns.filter_map { |c| c[:enum_type] }
-        enums = Array(enum_types).select { |enum| used.include?(enum[:name]) }
+        enums = RailsAiContext::Introspectors::PgNaming.enums_used(enum_types, columns.filter_map { |c| c[:enum_type]&.to_s }, search_path)
         if enums.any?
           lines << "" << "### Enum types"
           enums.each { |enum| lines << "- `#{enum[:name]}`: #{Array(enum[:values]).join(', ')}" }