woods 2.0.0.beta3 → 2.0.0.beta4

data/lib/woods/extractors/declared_parent.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'prism'
+
+module Woods
+  module Extractors
+    # Reads only the selected declaration's explicit constant-path parent.
+    # Identity selection remains with the extractor; literals and unrelated
+    # declarations must never supply metadata for that identity.
+    module DeclaredParent
+      module_function
+
+      def call(source, identifier)
+        parsed = Prism.parse(source)
+        return nil unless parsed.success?
+
+        find(parsed.value, identifier, '')&.first
+      end
+
+      def find(node, identifier, namespace)
+        return unless node
+
+        if node.is_a?(Prism::ClassNode) || node.is_a?(Prism::ModuleNode)
+          name = constant_name(node.constant_path)
+          return unless name
+
+          qualified = name.start_with?('::') ? name.delete_prefix('::') : [namespace, name].reject(&:empty?).join('::')
+          if qualified == identifier
+            return [node.is_a?(Prism::ClassNode) ? constant_name(node.superclass) : nil]
+          end
+
+          return find(node.body, identifier, qualified)
+        end
+
+        node.compact_child_nodes.each do |child|
+          match = find(child, identifier, namespace)
+          return match if match
+        end
+        nil
+      end
+      private_class_method :find
+
+      def constant_name(node)
+        case node
+        when Prism::ConstantReadNode
+          node.name.to_s
+        when Prism::ConstantPathNode
+          parent = node.parent ? constant_name(node.parent) : ''
+          "#{parent}::#{node.name}" if parent
+        end
+      end
+      private_class_method :constant_name
+    end
+  end
+end

data/lib/woods/extractors/graphql_extractor.rb

@@ -441,11 +441,11 @@ module Woods
       # @param unit_type [Symbol]
       # @param runtime_class [Class, nil]
       # @return [Hash]
-      def build_metadata(source, _class_name, _unit_type, runtime_class)
+      def build_metadata(source, class_name, _unit_type, runtime_class)
         {
           # GraphQL classification
           graphql_kind: detect_graphql_kind(source, runtime_class),
-          parent_class: extract_parent_class(source),
+          parent_class: extract_parent_class(source, class_name),
 
           # Fields and arguments
           fields: extract_fields(source, runtime_class),
@@ -508,15 +508,6 @@ module Woods
         :object
       end
 
-      # Extract the parent class name from source
-      #
-      # @param source [String]
-      # @return [String, nil]
-      def extract_parent_class(source)
-        match = source.match(/class\s+\w+\s*<\s*([\w:]+)/)
-        match ? match[1] : nil
-      end
-
       # Extract field definitions from source and/or runtime
       #
       # @param source [String]

data/lib/woods/extractors/lib_extractor.rb

@@ -80,9 +80,11 @@ module Woods
           file_path: file_path
         )
 
+        parent_class = extract_parent_class(source, class_name)
+
         unit.namespace    = extract_namespace(class_name)
-        unit.source_code  = annotate_source(source, class_name)
-        unit.metadata     = extract_metadata(source, class_name)
+        unit.source_code  = annotate_source(source, class_name, parent_class)
+        unit.metadata     = extract_metadata(source, parent_class)
         unit.dependencies = extract_dependencies(source)
 
         unit
@@ -170,11 +172,11 @@ module Woods
       #
       # @param source [String] Ruby source code
       # @param class_name [String] The inferred constant name
+      # @param parent_class [String, nil] Selected explicit parent
       # @return [String] Annotated source
-      def annotate_source(source, class_name)
-        parent = extract_parent_class(source)
+      def annotate_source(source, class_name, parent_class)
         entry_points = detect_entry_points(source)
-        parent_label = parent || 'none'
+        parent_label = parent_class || 'none'
 
         annotation = <<~ANNOTATION
           # ╔═══════════════════════════════════════════════════════════════════════╗
@@ -195,14 +197,14 @@ module Woods
       # Build the metadata hash for a lib unit.
       #
       # @param source [String] Ruby source code
-      # @param class_name [String] The inferred constant name
+      # @param parent_class [String, nil] Selected explicit parent
       # @return [Hash] Lib unit metadata
-      def extract_metadata(source, _class_name)
+      def extract_metadata(source, parent_class)
         {
           public_methods: extract_public_methods(source),
           class_methods: extract_class_methods(source),
           initialize_params: extract_initialize_params(source),
-          parent_class: extract_parent_class(source),
+          parent_class: parent_class,
           loc: count_loc(source),
           method_count: source.scan(/def\s+(?:self\.)?\w+/).size,
           entry_points: detect_entry_points(source)

data/lib/woods/extractors/mailer_extractor.rb

@@ -116,12 +116,8 @@ module Woods
       # ──────────────────────────────────────────────────────────────────────
 
       def annotate_source(source, mailer)
-        actions = mailer.action_methods.to_a
-        default_from = begin
-          mailer.default[:from]
-        rescue StandardError
-          nil
-        end
+        actions = mailer.action_methods.sort
+        default_from = extract_defaults(mailer)[:from]
 
         <<~ANNOTATION
           # ╔═══════════════════════════════════════════════════════════════════════╗
@@ -139,7 +135,7 @@ module Woods
       # ──────────────────────────────────────────────────────────────────────
 
       def extract_metadata(mailer, source)
-        actions = mailer.action_methods.to_a
+        actions = mailer.action_methods.sort
 
         {
           # Actions (mail methods)
@@ -171,7 +167,7 @@ module Woods
 
       def extract_defaults(mailer)
         mailer_defaults = mailer.default
-        mailer_defaults.slice(:from, :reply_to, :cc, :bcc).compact
+        mailer_defaults.slice(:from, :reply_to, :cc, :bcc).compact.transform_values { |value| stable_filter(value) }
       rescue StandardError
         {}
       end
@@ -182,7 +178,7 @@ module Woods
 
           result = {
             type: :"#{cb.kind}_action",
-            filter: cb.filter.to_s
+            filter: callback_filter_label(cb)
           }
           result[:only] = only if only.any?
           result[:except] = except if except.any?
@@ -274,7 +270,7 @@ module Woods
       # ──────────────────────────────────────────────────────────────────────
 
       def build_action_chunks(mailer, _source)
-        mailer.action_methods.filter_map do |action|
+        mailer.action_methods.sort.filter_map do |action|
           action_source = extract_action_source(mailer, action)
           next if action_source.nil? || action_source.strip.empty?
 

data/lib/woods/extractors/model_extractor.rb

@@ -619,7 +619,7 @@ module Woods
             entry = {
               attribute: attribute,
               type: v.class.name.demodulize.underscore.sub(/_validator$/, ''),
-              options: v.options.except(:if, :unless, :on),
+              options: v.options.except(:if, :unless, :on).transform_values { |value| stable_filter(value) },
               conditions: format_validation_conditions(v)
             }
             entry[:implicit_belongs_to] = true if implicit_belongs_to_validator?(model, v)
@@ -650,20 +650,6 @@ module Woods
         end.compact
       end
 
-      # Preserve application labels; strip addresses only from Ruby's actual
-      # default representation. Nested identities occur for anonymous classes.
-      # These are descriptive labels, not serialization of callback object state.
-      def callback_filter_label(callback)
-        filter = callback_filter(callback)
-        label = filter.to_s
-        return label unless label.start_with?('#<')
-
-        owner = filter.is_a?(Module) ? Module : Kernel
-        return label unless label == owner.instance_method(:to_s).bind(filter).call
-
-        label.gsub(/:0x[0-9a-f]+(?=>)/i, '')
-      end
-
       # Extract scopes with their source if available.
       # Parses the full source with the AST layer to get accurate scope
       # boundaries, falling back to regex line-scanning on parse failure.

data/lib/woods/extractors/poro_extractor.rb

@@ -82,9 +82,11 @@ module Woods
           file_path: file_path
         )
 
+        parent_class = extract_parent_class(source, class_name)
+
         unit.namespace    = extract_namespace(class_name)
-        unit.source_code  = annotate_source(source, class_name)
-        unit.metadata     = extract_metadata(source, class_name)
+        unit.source_code  = annotate_source(source, class_name, parent_class)
+        unit.metadata     = extract_metadata(source, parent_class)
         unit.dependencies = extract_dependencies(source)
 
         unit
@@ -177,10 +179,10 @@ module Woods
       #
       # @param source [String] Ruby source code
       # @param class_name [String] The class name
+      # @param parent_class [String, nil] Selected explicit parent
       # @return [String] Annotated source
-      def annotate_source(source, class_name)
-        parent = extract_parent_class(source)
-        parent_label = parent || 'none'
+      def annotate_source(source, class_name, parent_class)
+        parent_label = parent_class || 'none'
 
         annotation = <<~ANNOTATION
           # ╔═══════════════════════════════════════════════════════════════════════╗
@@ -200,14 +202,14 @@ module Woods
       # Build the metadata hash for a PORO unit.
       #
       # @param source [String] Ruby source code
-      # @param class_name [String] The class name
+      # @param parent_class [String, nil] Selected explicit parent
       # @return [Hash] PORO metadata
-      def extract_metadata(source, _class_name)
+      def extract_metadata(source, parent_class)
         {
           public_methods: extract_public_methods(source),
           class_methods: extract_class_methods(source),
           initialize_params: extract_initialize_params(source),
-          parent_class: extract_parent_class(source),
+          parent_class: parent_class,
           loc: count_loc(source),
           method_count: source.scan(/def\s+(?:self\.)?\w+/).size
         }

data/lib/woods/extractors/shared_utility_methods.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'declared_parent'
+
 require_relative 'source_nesting'
 require_relative 'method_parameters'
 
@@ -125,10 +127,10 @@ module Woods
       # Extract the parent class name from a class definition.
       #
       # @param source [String] Ruby source code
-      # @return [String, nil] Parent class name or nil
-      def extract_parent_class(source)
-        match = source.match(/^\s*class\s+[\w:]+\s*<\s*([\w:]+)/)
-        match ? match[1] : nil
+      # @param class_name [String] Already selected extraction identity
+      # @return [String, nil] Explicit parent of that declaration, or nil
+      def extract_parent_class(source, class_name)
+        DeclaredParent.call(source, class_name)
       end
 
       # Count non-blank, non-comment lines of code.
@@ -243,7 +245,22 @@ module Woods
                end
         "#<#{filter.lambda? ? 'lambda' : 'Proc'} #{site}>"
       end
-      private :callback_filter, :stable_filter
+
+      # Preserve application labels; strip addresses only from Ruby's actual
+      # default representation. Nested identities occur for anonymous classes.
+      # These are descriptive labels, not serialization of callback object state.
+      def callback_filter_label(callback)
+        filter = callback_filter(callback)
+        label = filter.to_s
+        return label unless label.start_with?('#<')
+
+        owner = filter.is_a?(Module) ? Module : Kernel
+        return label unless label == owner.instance_method(:to_s).bind(filter).call
+
+        label.gsub(/:0x[0-9a-f]+(?=>)/i, '')
+      end
+
+      private :callback_filter, :stable_filter, :callback_filter_label
 
       # Human-readable label for a non-ActionFilter condition.
       #

data/lib/woods/mcp/bearer_auth.rb

@@ -54,7 +54,8 @@ module Woods
 
         expected = resolve_token
         header = env['HTTP_AUTHORIZATION'].to_s
-        presented = header.start_with?('Bearer ') ? header.sub(/\ABearer /, '') : nil
+        # Only the ASCII scheme changes case; do not normalize or trim the token.
+        presented = header.match?(/\A[Bb][Ee][Aa][Rr][Ee][Rr] /) ? header[7..] : nil
 
         if expected && presented && Rack::Utils.secure_compare(expected, presented)
           @app.call(env)

data/lib/woods/mcp/bootstrapper.rb

@@ -28,16 +28,19 @@ module Woods
       # @param argv [Array<String>] Command-line arguments
       # @return [String] Validated index directory path
       def self.resolve_index_dir(argv)
-        dir = argv[0] || ENV['WOODS_DIR'] || Dir.pwd
+        dir = argv[0] || ENV['WOODS_DIR'] || ENV['WOODS_OUTPUT'] || Dir.pwd
+        examined = dir.empty? ? '(empty path)' : File.expand_path(dir)
 
         unless Dir.exist?(dir)
-          warn "Error: Index directory does not exist: #{dir}"
+          warn "Error: Index directory does not exist: #{examined}"
+          warn index_path_remedy
           exit 1
         end
 
         unless manifest_present?(dir)
-          warn "Error: No manifest.json found in: #{dir}"
-          warn 'Run `bundle exec rake woods:extract` in your Rails app first.'
+          warn "Error: Could not resolve a published Woods index in: #{examined}"
+          warn 'Expected generation.json pointing to a payload manifest.json, or a legacy flat manifest.json.'
+          warn index_path_remedy
           exit 1
         end
 
@@ -61,9 +64,19 @@ module Woods
 
         generation = Woods::Generation.new(output_dir: dir)
         generation.payload_dir(generation.current).join('manifest.json').file?
+      rescue TypeError, NoMethodError
+        # A malformed marker must remain a startup failure, with the same
+        # selected-path guidance as a missing or unresolved payload.
+        false
       end
       private_class_method :manifest_present?
 
+      def self.index_path_remedy
+        'Point at the existing index with an explicit path, WOODS_DIR, or WOODS_OUTPUT. ' \
+          'If no index exists, run `bundle exec rake woods:extract` in your Rails app.'
+      end
+      private_class_method :index_path_remedy
+
       # Build a snapshot store for temporal tracking.
       #
       # Auto-enables when a SQLite database already exists in the index directory,

data/lib/woods/mcp/config_resolver.rb

@@ -295,7 +295,8 @@ module Woods
         unless resolved.embedding_provider
           warn '[woods-mcp] no woods.json and no embedding provider — serving ' \
                'pattern/structural tools only. Run `rake woods:embed`, or set ' \
-               'OPENAI_API_KEY / run Ollama, to enable semantic search.'
+               'OPENAI_API_KEY / run Ollama, to enable semantic search. For ranked discovery with no embeddings, ' \
+               'set WOODS_RETRIEVAL_MODE=lexical in the MCP process environment and restart the server.'
         end
         [resolved, :autodetect]
       end

data/lib/woods/mcp/index_reader.rb

@@ -60,11 +60,16 @@ module Woods
       # @param auto_refresh [Boolean] re-read the index when its published
       #   generation moves. On by default; specs that assert caching behaviour
       #   turn it off.
-      # @raise [ArgumentError] if directory doesn't exist or has no manifest.json
+      # @raise [ArgumentError] if directory doesn't exist or no published index resolves
       def initialize(index_dir, auto_refresh: true)
         @index_dir = Pathname.new(index_dir)
         raise ArgumentError, "Index directory does not exist: #{index_dir}" unless @index_dir.directory?
-        raise ArgumentError, "No manifest.json found in: #{index_dir}" unless manifest_present?
+        unless manifest_present?
+          raise ArgumentError, "Could not resolve a published Woods index in: #{@index_dir.expand_path}\n" \
+                               'Expected generation.json pointing to a payload manifest.json, or a legacy flat manifest.json. ' \
+                               'Point IndexReader at an existing index root. ' \
+                               'If no index exists, run `bundle exec rake woods:extract` in your Rails app.'
+        end
 
         @unit_cache = {}
         @unit_cache_signatures = {}
@@ -963,6 +968,10 @@ module Woods
 
         marker = Woods::Generation.new(output_dir: @index_dir).current
         resolve_payload_dir(marker).join('manifest.json').file?
+      rescue TypeError, NoMethodError
+        # Match Bootstrapper's startup preflight for malformed marker shapes.
+        # Keep this local: errors during later generation refresh still surface.
+        false
       end
 
       # The loaded generation's payload directory, without a freshness check.

data/lib/woods/mcp/renderers/markdown_renderer.rb

@@ -152,11 +152,11 @@ module Woods
             - **units_indexed** (manifest.json, `structure` tool) — total
               ExtractedUnits written by the extractor. Canonical count.
             - **graph_nodes** (`pagerank`, `dependencies`, `dependents`) —
-              units present in the dependency graph. Excludes orphans
-              that have no incoming or outgoing edges.
+              units present in the dependency graph, including isolated units
+              with no incoming or outgoing edges.
             - **searchable_entries** (`codebase_retrieve`) — retriever-store
-              entries, including per-chunk rows for units long enough to
-              be chunked. Always ≥ units_indexed.
+              entries. Semantic mode may include per-chunk rows; lexical mode
+              ranks published units. Coverage depends on the configured store.
           GLOSSARY
         end
 
@@ -177,7 +177,7 @@ module Woods
 
           GRAPH_ANALYSIS_SECTIONS.each do |section|
             items = fetch_key(data, section)
-            next unless items.is_a?(Array) && items.any?
+            next unless items.is_a?(Array) && (items.any? || fetch_key(data, "#{section}_total"))
 
             lines << "### #{section.tr('_', ' ').capitalize}"
             lines << ''
@@ -194,11 +194,11 @@ module Woods
             end
 
             total_key = "#{section}_total"
-            if data[total_key]
+            if fetch_key(data, total_key)
               lines << ''
               offset = fetch_key(data, "#{section}_offset", 0)
               position = offset.positive? ? " from offset #{offset}" : ''
-              lines << "_Showing #{items.size} of #{data[total_key]}#{position} (truncated)_"
+              lines << "_Showing #{items.size} of #{fetch_key(data, total_key)}#{position} (truncated)_"
             end
             lines << ''
           end
@@ -417,6 +417,8 @@ module Woods
             return lines.join("\n").rstrip
           end
 
+          lines.concat(traversal_coverage_lines(data))
+
           nodes.each do |id, info|
             depth = fetch_key(info, :depth) || 0
             deps = fetch_key(info, :deps, [])
@@ -438,7 +440,11 @@ module Woods
           if fetch_key(data, :partial)
             lines << "Partial traversal (#{fetch_key(data, :partial_reason)}); narrow depth/types/via or increase max_nodes/max_edges."
           end
-          lines << '' << truncation_note(data, nodes.size) if fetch_key(data, :nodes_total)
+          if (note = traversal_lower_bound_note(data, nodes.size))
+            lines << '' << "_#{note}_"
+          elsif fetch_key(data, :nodes_total)
+            lines << '' << truncation_note(data, nodes.size)
+          end
 
           lines.join("\n").rstrip
         end

data/lib/woods/mcp/renderers/plain_renderer.rb

@@ -126,9 +126,9 @@ module Woods
           lines << 'Denominators:'
           lines << '  units_indexed     (manifest, structure): total ExtractedUnits written.'
           lines << '  graph_nodes       (pagerank, dependencies, dependents): units in the graph'
-          lines << '                    (excludes orphans with no incoming/outgoing edges).'
-          lines << '  searchable_entries (codebase_retrieve): retriever-store entries including'
-          lines << '                    per-chunk rows. Always >= units_indexed.'
+          lines << '                    (includes isolated units with no incoming/outgoing edges).'
+          lines << '  searchable_entries (codebase_retrieve): retriever-store entries; semantic mode may include'
+          lines << '                    per-chunk rows; lexical mode ranks published units. Store coverage varies.'
 
           lines.join("\n").rstrip
         end
@@ -146,7 +146,7 @@ module Woods
 
           GRAPH_ANALYSIS_SECTIONS.each do |section|
             items = fetch_key(data, section)
-            next unless items.is_a?(Array) && items.any?
+            next unless items.is_a?(Array) && (items.any? || fetch_key(data, "#{section}_total"))
 
             lines << "#{section.tr('_', ' ').upcase}:"
             items.each do |item|
@@ -161,9 +161,9 @@ module Woods
 
             total_key = "#{section}_total"
             offset = fetch_key(data, "#{section}_offset", 0)
-            if data[total_key]
+            if fetch_key(data, total_key)
               position = offset.positive? ? " from offset #{offset}" : ''
-              lines << "  (showing #{items.size} of #{data[total_key]}#{position}; truncated)"
+              lines << "  (showing #{items.size} of #{fetch_key(data, total_key)}#{position}; truncated)"
             end
             lines << ''
           end
@@ -279,6 +279,8 @@ module Woods
             return lines.join("\n").rstrip
           end
 
+          lines.concat(traversal_coverage_lines(data))
+
           nodes.each do |id, info|
             depth = fetch_key(info, :depth) || 0
             deps = fetch_key(info, :deps, [])
@@ -294,7 +296,9 @@ module Woods
           if fetch_key(data, :partial)
             lines << "Partial traversal (#{fetch_key(data, :partial_reason)}); narrow depth/types/via or increase max_nodes/max_edges."
           end
-          if fetch_key(data, :nodes_total)
+          if (note = traversal_lower_bound_note(data, nodes.size))
+            lines << note
+          elsif fetch_key(data, :nodes_total)
             offset = fetch_key(data, :nodes_offset, 0)
             position = offset.positive? ? " from offset #{offset}" : ''
             lines << "  (showing #{nodes.size} of #{fetch_key(data, :nodes_total)}#{position}; truncated)"

data/lib/woods/mcp/server.rb

@@ -27,6 +27,7 @@ require_relative 'tasks/request_capture'
 require_relative 'tasks/store'
 require_relative 'tool_contract'
 require_relative 'tool_response_renderer'
+require_relative 'traversal_response'
 require_relative 'version_aware_tool_dispatch'
 
 module Woods
@@ -73,6 +74,7 @@ module Woods
       # controls that actually shrink the answer are `depth`, `types` and
       # `via`; `limit` and `offset` only page what those leave (B-183).
       DEFAULT_TRAVERSAL_LIMIT = 50
+      DEFAULT_GRAPH_ANALYSIS_LIMIT = 20
 
       class << self
         # Build a configured MCP::Server with all tools and resources.
@@ -161,7 +163,8 @@ module Woods
                                              'Narrow with depth, types and via first: they shrink the answer, ' \
                                              'while limit and offset only page it. Returns a BFS tree with ' \
                                              "depth, paged to #{DEFAULT_TRAVERSAL_LIMIT} nodes by default. " \
-                                             'max_nodes/max_edges bound the walk independently; partial_reason reports a budget cutoff. ' \
+                                             'max_nodes/max_edges bound the walk independently; partial_reason reports a budget cutoff and total_is_exact is false. ' \
+                                             'Published relationships are not exhaustive source-reference coverage. ' \
                                              'Use explain:true for recorded directed relationships and bounded witnesses; ambiguous types remain explicit.',
                                 reader_method: :traverse_dependencies,
                                 render_key: :dependencies)
@@ -171,7 +174,8 @@ module Woods
                                              'Narrow with depth, types and via first: they shrink the answer, ' \
                                              'while limit and offset only page it. Returns a BFS tree with ' \
                                              "depth, paged to #{DEFAULT_TRAVERSAL_LIMIT} nodes by default. " \
-                                             'max_nodes/max_edges bound the walk independently; partial_reason reports a budget cutoff. ' \
+                                             'max_nodes/max_edges bound the walk independently; partial_reason reports a budget cutoff and total_is_exact is false. ' \
+                                             'Published relationships are not exhaustive source-reference coverage. ' \
                                              'Use explain:true for recorded directed relationships and bounded witnesses; ambiguous types remain explicit.',
                                 reader_method: :traverse_dependents,
                                 render_key: :dependents)
@@ -247,9 +251,9 @@ module Woods
           !token.nil? && ids && !ids.empty?
         end
 
-        def text_response(text)
+        def text_response(text, data: nil)
           structured = { text: text }
-          structured[:data] = JSON.parse(text)
+          structured[:data] = data.nil? ? JSON.parse(text) : data
           ::MCP::Tool::Response.new(
             [{ type: 'text', text: text }],
             structured_content: structured
@@ -393,7 +397,7 @@ module Woods
 
           sliced = offset.positive? ? original.drop(offset) : original
           container[key] = limit ? truncate_section(sliced, limit) : sliced
-          if original.size > offset + (limit || original.size)
+          if offset.positive? || container[key].size < original.size
             container["#{key}_total"] = original.size
             container["#{key}_truncated"] = true
           end
@@ -403,12 +407,11 @@ module Woods
         # Page a traversal result's `nodes` hash in place, in BFS order.
         #
         # Mirrors {#paginate_section}'s metadata keys (`nodes_total`,
-        # `nodes_truncated`, `nodes_offset`) so both renderers print the one
-        # truncation line they already had for `graph_analysis`. A page that
-        # holds every node adds no keys at all, so a small result renders
-        # exactly as it did before the bound existed (B-183).
+        # `nodes_truncated`, `nodes_offset`). A page that holds every admitted
+        # node adds no pagination keys (B-183). TraversalResponse separately
+        # annotates scope and total exactness before pagination.
         #
-        # `nodes_total` marks *any* partial answer, not only one with more
+        # `nodes_total` marks *any* paged answer, not only one with more
         # behind it. Keying it on `total > offset + limit` left the last page
         # of a walk indistinguishable from a complete one: 21 nodes of 121,
         # with nothing saying 100 were skipped. `nodes_truncated` still means
@@ -656,9 +659,10 @@ module Woods
               result[:message] =
                 "Identifier '#{identifier}' not found in the index. Use 'search' to find valid identifiers."
             end
+            TraversalResponse.annotate(result)
             paginate_nodes.call(result, limit || DEFAULT_TRAVERSAL_LIMIT, offset || 0)
             TraversalEvidencePage.apply(result)
-            respond.call(renderer.render(render_key, result))
+            respond.call(renderer.render(render_key, result), data: result)
           end
         end
 
@@ -698,32 +702,20 @@ module Woods
                   enum: ToolResponseRenderer::GRAPH_ANALYSIS_SECTIONS + %w[all],
                   description: 'Which analysis to return. Default: all'
                 },
-                limit: { type: 'integer', description: 'Limit results per section (default: 20)' },
+                limit: { type: 'integer', description: "Limit results per section (default: #{DEFAULT_GRAPH_ANALYSIS_LIMIT})" },
                 offset: { type: 'integer', description: 'Skip this many results per section (default: 0)' }
               }
             }
           ) do |server_context:, analysis: nil, limit: nil, offset: nil|
-            limit = coerce_int.call(limit)
+            limit = coerce_int.call(limit) || DEFAULT_GRAPH_ANALYSIS_LIMIT
             offset = coerce_int.call(offset)
             data = reader.graph_analysis
             section = analysis || 'all'
             effective_offset = offset || 0
 
-            result = if section == 'all'
-                       if limit || effective_offset.positive?
-                         truncated = data.dup
-                         ToolResponseRenderer::GRAPH_ANALYSIS_SECTIONS.each do |key|
-                           paginate.call(truncated, key, limit, effective_offset)
-                         end
-                         truncated
-                       else
-                         data
-                       end
-                     else
-                       single = { section => data[section] || [], 'stats' => data['stats'] }
-                       paginate.call(single, section, limit, effective_offset) if limit || effective_offset.positive?
-                       single
-                     end
+            result = section == 'all' ? data.dup : { section => data[section] || [], 'stats' => data['stats'] }
+            sections = section == 'all' ? ToolResponseRenderer::GRAPH_ANALYSIS_SECTIONS : [section]
+            sections.each { |key| paginate.call(result, key, limit, effective_offset) }
 
             respond.call(renderer.render(:graph_analysis, result))
           end
@@ -1072,6 +1064,8 @@ module Woods
                 'Semantic search is disabled — no embedding provider is configured. ' \
                 'To enable: set OPENAI_API_KEY, or run Ollama locally ' \
                 '(brew install ollama && ollama serve && ollama pull nomic-embed-text). ' \
+                'For ranked discovery with no embeddings, set WOODS_RETRIEVAL_MODE=lexical in the MCP process ' \
+                'environment and restart the server. See docs/RETRIEVAL_GUIDE.md#embedding-free-lexical-retrieval. ' \
                 'Use the `search` tool for pattern-based matching in the meantime.',
                 code: :not_configured,
                 config_key: 'embedding_provider',