woods 2.0.0.beta3 → 2.0.0

data/lib/woods/extractor.rb

@@ -211,7 +211,6 @@ module Woods
       configuration: :extract_configuration_file,
       view_template: :extract_view_template_file,
       migration: :extract_migration_file,
-      rake_task: :extract_rake_file,
       decorator: :extract_decorator_file,
       database_view: :extract_view_file,
       caching: :extract_caching_file,
@@ -293,7 +292,7 @@ module Woods
                  method: :extract_from_runtime_type, reconcile_removals: false }
     }.freeze
 
-    # Extractors with no per-file entry point: they scan the whole app (or
+    # Extractors requiring a complete source set: they scan the whole app (or
     # introspect the whole runtime) in one pass, so an incremental run
     # replaces their output wholesale rather than per unit. Before #164
     # these types were simply skipped by incremental runs while
@@ -302,6 +301,7 @@ module Woods
     #
     # @return [Hash{Symbol => Symbol}] extractor key => unit type
     WHOLE_APP_EXTRACTORS = {
+      rake_tasks: :rake_task,
       routes: :route,
       middleware: :middleware,
       engines: :engine,
@@ -600,6 +600,7 @@ module Woods
                       ))
       end
 
+      raise_on_handled_extraction_failure!
       finalize_incremental_unit_json(affected_types)
 
       # Regenerate type indexes for affected types
@@ -662,6 +663,7 @@ module Woods
         acc.merge(replace_type_wholesale(key, affected_types))
       end
 
+      raise_on_handled_extraction_failure!
       finalize_incremental_unit_json(affected_types)
       profile_phase('type index') { affected_types.each { |type_key| regenerate_type_index(type_key) } }
       finalize_incremental_run(touched, reason: "refresh:#{known.sort.join(',')}")
@@ -889,6 +891,7 @@ module Woods
     # Capture before eager loading or extraction; only an explicit fresh-launch
     # handoff can additionally establish the pre-Bundler/Rails boot boundary.
     def begin_source_inputs(operation)
+      @failed_consumers = Set.new
       @source_inputs = SourceInputs::Session.new(root: Rails.root, output_dir: @output_dir,
                                                  baseline_path: source_input_baseline_path,
                                                  operation: operation)
@@ -911,6 +914,28 @@ module Woods
       failed
     end
 
+    # A rescued consumer error is not a successful empty result. Reset the
+    # per-call flag because one extractor instance serves several paths, but
+    # retain the failed scope for the run so a later success cannot authorize
+    # publication. Watch then carries the complete batch forward for retry.
+    def checked_extraction(key, consumer)
+      (@failed_consumers ||= Set.new).add(key) if SourceInputs::ConsumerErrors.failed?(consumer)
+      SourceInputs::ConsumerErrors.reset(consumer)
+      result = yield
+      return result unless source_consumer_failed?(key, consumer)
+
+      (@failed_consumers ||= Set.new).add(key)
+      nil
+    end
+
+    def raise_on_handled_extraction_failure!
+      return if @failed_consumers.nil? || @failed_consumers.empty?
+
+      raise Woods::ExtractionError,
+            "Extraction failed for #{@failed_consumers.to_a.sort.join(', ')}; " \
+            'the previous generation remains active. Fix the logged source errors and retry the complete batch.'
+    end
+
     def write_source_inputs
       return unless @source_inputs
 
@@ -2078,10 +2103,28 @@ module Woods
       end
 
       @git_available = complete_git_history?
+    rescue Errno::ENOENT
+      warn_missing_git_executable
+      @git_available = false
     rescue StandardError
       @git_available = false
     end
 
+    # An explicit Git directory still requests history when .git is not mounted
+    # at Rails.root. Ordinary source archives remain a supported, quiet path.
+    #
+    # @return [void]
+    def warn_missing_git_executable
+      configured = [GitCommand::OVERRIDE_KEY, 'GIT_DIR'].any? { |key| !ENV[key].to_s.empty? }
+      return unless configured || File.exist?(File.join(Rails.root.to_s, '.git'))
+
+      Rails.logger.warn(
+        '[Woods] Git history unavailable: git executable was not found in PATH. ' \
+        'Extraction continues without per-unit Git metadata. Install Git in the extraction environment ' \
+        'and run a full extraction to refresh Git metadata.'
+      )
+    end
+
     # A shallow HEAD resolves but represents an incomplete ancestry. Do not
     # turn that boundary into apparent one-commit/new-file churn facts.
     def complete_git_history?
@@ -2109,19 +2152,19 @@ module Woods
       cause = error.to_s.lines.first.to_s.strip
       Rails.logger.warn(
         '[Woods] git cannot resolve HEAD for this working tree, so no unit will carry git ' \
-        "metadata: #{cause}. Over a linked worktree in a container, mount the canonical git " \
-        'directory and point WOODS_GIT_DIR at it; GIT_DIR alone is not enough, because the ' \
-        "worktree's private git directory reaches the shared one through a relative pointer."
+        "metadata: #{cause}. For a linked worktree, mount the complete shared .git directory " \
+        'at its original path, or set WOODS_GIT_DIR to /mounted-common/worktrees/<id> within ' \
+        'the relocated complete layout. Derive <id> from the worktree Git metadata, not its branch name; ' \
+        "selecting /mounted-common itself uses the primary checkout's HEAD."
       )
     end
 
     # The git command line every enrichment call runs.
     #
     # `-C <root>` keeps the result independent of the process working
-    # directory. `WOODS_GIT_DIR` wins when set: it names the canonical git
-    # directory directly, which is the escape hatch for a container that can
-    # mount that directory but not the host path a worktree pointer names
-    # (B-181).
+    # directory. `WOODS_GIT_DIR` wins when set and selects that git directory's
+    # HEAD. A relocated linked worktree needs its worktree-specific directory
+    # inside the complete shared Git layout (B-181).
     #
     # @param args [Array<String>] git arguments
     # @return [Array<String>] full argv
@@ -2760,10 +2803,11 @@ module Woods
     #
     # This is the fix for #164 gap 1 (a path the index has never seen routed
     # nowhere, so new files were silently ignored) and the per-path half of
-    # gap 3 (a file that defines several units — a `.rake` file with multiple
-    # tasks, an i18n YAML — could only ever resolve to one identifier).
-    # Reconciling the whole path at once means a task deleted from a
-    # multi-task file is removed rather than left behind.
+    # gap 3 (a file defining several units could only ever resolve to one
+    # identifier). Rake tasks need the wholesale path because definitions
+    # of one task can span several files.
+    # Reconciling the whole path removes definitions deleted from a surviving
+    # file rather than leaving them behind.
     #
     # Removal is scoped to the unit types the matching rules could have
     # produced, so a class-based unit sharing the path (the `User` model unit
@@ -2837,7 +2881,7 @@ module Woods
       end
       return [] unless extractor.respond_to?(rule.method_name)
 
-      result =
+      result = checked_extraction(rule.extractor_key, extractor) do
         if rule.extractor_key == :poros
           # PoroExtractor needs the AR name set to reject persisted models;
           # its default is an empty set, which would misfile every model
@@ -2846,6 +2890,8 @@ module Woods
         else
           extractor.public_send(rule.method_name, absolute_path)
         end
+      end
+      return nil if result.nil? && SourceInputs::ConsumerErrors.failed?(extractor)
 
       Array(result).compact
     rescue StandardError => e
@@ -3172,7 +3218,10 @@ module Woods
       return Set.new unless extractor.respond_to?(:extract_all)
 
       @wholesale_mutations = 0
-      units = Array(extractor.extract_all).compact.uniq(&:identifier)
+      result = checked_extraction(key, extractor) { extractor.extract_all }
+      return Set.new if SourceInputs::ConsumerErrors.failed?(extractor)
+
+      units = Array(result).compact.uniq(&:identifier)
       Rails.logger.info "[Woods] Re-ran #{key} wholesale: #{units.size} units"
 
       touched = register_and_write(key, units, affected_types)
@@ -3723,10 +3772,12 @@ module Woods
         return nil
       end
 
-      # File-based extractors can return several units from one file (a .rake
-      # file defining multiple tasks, etc.); class-based extractors return one.
-      units = Array(re_extracted_units(extractor, type, unit_id, file_path, extractor_key)).compact
-      source_consumer_failed?(extractor_key, extractor)
+      # File-based extractors can return several units from one file;
+      # class-based extractors return one.
+      result = checked_extraction(extractor_key, extractor) do
+        re_extracted_units(extractor, type, unit_id, file_path, extractor_key)
+      end
+      units = Array(result).compact
       return nil if units.empty?
 
       register_and_write(extractor_key, units, affected_types)

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/git_command.rb

@@ -7,18 +7,17 @@ module Woods
   # than at the process working directory, so extraction launched from another
   # checkout never reports that checkout's history.
   #
-  # `WOODS_GIT_DIR` wins when set. It is the escape hatch for a container over
-  # a linked worktree: `.git` there is a file naming an absolute host path that
-  # may not be mounted, and git's own `GIT_DIR` is not enough, because a
-  # worktree's private git directory reaches the shared object store through a
-  # relative `commondir` pointer that resolves outside the mount, which
-  # `GIT_COMMON_DIR` does not override (B-181, B-186).
+  # `WOODS_GIT_DIR` wins when set and selects HEAD exactly as `--git-dir`
+  # does. For a container over a linked worktree, select its private directory
+  # within the complete mounted Git layout (shared objects, refs and worktrees).
+  # Selecting the shared root instead selects the primary checkout's HEAD.
+  # A same-path mount that resolves the worktree's .git pointer needs no override.
   #
   # Three call sites use this, and the documentation promises all three:
   # per-unit enrichment (`Extractor`), manifest provenance (`GitProvenance`),
   # and the `woods:incremental` diff range (`lib/tasks/woods.rake`).
   module GitCommand
-    # Environment variable naming the canonical git directory.
+    # Environment variable naming the explicitly selected git directory.
     OVERRIDE_KEY = 'WOODS_GIT_DIR'
 
     module_function

data/lib/woods/git_provenance.rb

@@ -85,12 +85,10 @@ module Woods
       ''
     end
 
-    # +WOODS_GIT_DIR+ names the canonical git directory outright and wins when
-    # set. It is the escape hatch for a container that can mount that
-    # directory but not the host path a linked worktree's +.git+ file points
-    # at; git's own +GIT_DIR+ is not enough there, because a worktree's
-    # private git directory reaches the shared one through a relative
-    # +commondir+ pointer that resolves outside the mount.
+    # +WOODS_GIT_DIR+ selects a git directory and its HEAD outright and wins when
+    # set. A relocated linked worktree needs its private directory inside the
+    # complete mounted Git layout, preserving access to shared objects and refs.
+    # Selecting the shared root instead uses the primary checkout's HEAD.
     #
     # @param args [Array<String>] git arguments
     # @return [Array<String>] full argv

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,
@@ -163,7 +176,9 @@ module Woods
         retriever = build_retriever_from_config(config, resolved, artifact, state)
         probe_and_mark_state(config, state)
         derive_state_from_store_health(state)
-        warn "[woods-mcp] semantic search: #{state.status} (#{config.embedding_provider})"
+        corpus = retriever.corpus_status(include_types: false) if retriever.respond_to?(:corpus_status)
+        corpus_note = corpus ? "; corpus: #{corpus[:state]}" : ''
+        warn "[woods-mcp] semantic search: #{state.status} (#{config.embedding_provider})#{corpus_note}"
 
         [retriever, state]
       end

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.