spree_menu_chat 0.1.0

data/config/initializers/spree_admin_menu_chat_navigation.rb

@@ -0,0 +1,21 @@
+Rails.application.config.after_initialize do
+  # Position 71 — right after spree_doordash's own entries (68-70), which
+  # themselves sit right after spree_square's (65-67), so all three
+  # extensions' nav items sit together without colliding.
+  Spree.admin.navigation.sidebar.add :menu_chat_credential,
+    label: 'Menu Chat Connection',
+    url: :admin_menu_chat_credential_path,
+    icon: 'chat-circle',
+    position: 71,
+    active: -> { controller_name == 'menu_chat_credentials' },
+    if: -> { can?(:manage, SpreeMenuChat::Credential) }
+
+  # M6 — position 72, right after the credential page above.
+  Spree.admin.navigation.sidebar.add :menu_chat_conversations,
+    label: 'Menu Chat Conversations',
+    url: :admin_menu_chat_conversations_path,
+    icon: 'chat-text',
+    position: 72,
+    active: -> { controller_name == 'menu_chat_conversations' },
+    if: -> { can?(:manage, SpreeMenuChat::Conversation) }
+end

data/config/initializers/spree_admin_menu_chat_tables.rb

@@ -0,0 +1,61 @@
+Rails.application.config.after_initialize do
+  # new_resource: false — a read-only QA table (no `:new`/`:create` route
+  # exists; only: [:index] in config/routes.rb). The default (true) crashes
+  # with a routing error the moment the table is ever empty, because the
+  # "no resource found" empty-state partial builds a `new_object_url` link
+  # unconditionally unless told not to. The exact bug both spree_square and
+  # spree_doordash hit and fixed on their own read-only admin tables —
+  # applied here up front instead of waiting to hit it live a third time.
+  # link_to_action: :show, row_actions: false — a row links straight to
+  # the full conversation (config/routes.rb's :show route +
+  # app/views/.../show.html.erb) rather than the framework's default
+  # :edit (which doesn't exist here — nothing in this table is ever
+  # edited). Without this, rows render as plain, unclickable text and the
+  # only way to read a conversation is the always-truncated
+  # `first_question` preview column below.
+  Spree.admin.tables.register(:menu_chat_conversations, model_class: SpreeMenuChat::Conversation,
+                                                          search_param: :identifier_cont, new_resource: false,
+                                                          link_to_action: :show, row_actions: false)
+
+  Spree.admin.tables.menu_chat_conversations.add :identifier,
+    label: :identifier,
+    type: :string,
+    sortable: true,
+    filterable: true,
+    default: true,
+    position: 10
+
+  Spree.admin.tables.menu_chat_conversations.add :first_question,
+    label: :first_question,
+    type: :string,
+    sortable: false,
+    filterable: false,
+    default: true,
+    position: 20,
+    method: ->(conversation) { conversation.messages.where(role: 'user').order(:created_at).first&.content&.truncate(80) }
+
+  Spree.admin.tables.menu_chat_conversations.add :message_count,
+    label: :messages,
+    type: :number,
+    sortable: false,
+    filterable: false,
+    default: true,
+    position: 30,
+    method: ->(conversation) { conversation.messages.size }
+
+  Spree.admin.tables.menu_chat_conversations.add :created_at,
+    label: :started_at,
+    type: :datetime,
+    sortable: true,
+    filterable: false,
+    default: true,
+    position: 40
+
+  Spree.admin.tables.menu_chat_conversations.add :updated_at,
+    label: :last_message_at,
+    type: :datetime,
+    sortable: true,
+    filterable: false,
+    default: true,
+    position: 50
+end

data/config/routes.rb

@@ -0,0 +1,26 @@
+Spree::Core::Engine.add_routes do
+  # `isolate_namespace Spree` means a bare `to: 'chat#create'` here would
+  # resolve to `Spree::ChatController` — the leading `/` makes the
+  # controller path absolute, same fix spree_square's webhook route
+  # already needed for the same reason (see that file's comment).
+  post 'menu_chat/chat', to: '/spree_menu_chat/chat#create'
+
+  namespace :admin do
+    # Plain credential-entry form (gemini_api_key/voyage_api_key), not an
+    # OAuth connect/disconnect flow — neither service has one. Explicit named
+    # routes rather than `resource :menu_chat_credential` since there's no
+    # `new`/`create` — just show the one row for the current store and
+    # update it in place, `find_or_initialize_by(store:)` style. Same
+    # pattern as spree_doordash's doordash_credential routes.
+    get 'menu_chat_credential' => 'menu_chat_credentials#show', as: :menu_chat_credential
+    patch 'menu_chat_credential' => 'menu_chat_credentials#update'
+
+    # M6 — read-only QA view: index + show, no :new/:create/:edit/:destroy
+    # (nothing here is ever created or edited through the admin UI). See
+    # spree_admin_menu_chat_tables.rb's `new_resource: false` comment for
+    # the real bug that omission avoids, and its `link_to_action: :show`
+    # for why :show needs to exist for a conversation row to be clickable
+    # at all.
+    resources :menu_chat_conversations, only: %i[index show]
+  end
+end

data/db/migrate/20260814000001_create_spree_menu_chat_credentials.rb

@@ -0,0 +1,16 @@
+class CreateSpreeMenuChatCredentials < ActiveRecord::Migration[8.1]
+  def change
+    create_table :spree_menu_chat_credentials do |t|
+      t.references :store, null: false, foreign_key: { to_table: :spree_stores }, index: { unique: true }
+
+      # Both are plain static API keys — no OAuth/refresh flow for either
+      # Gemini or Voyage AI. Encrypted at the application layer (see
+      # SpreeMenuChat::Credential), same as spree_doordash's credential
+      # columns.
+      t.text :gemini_api_key
+      t.text :voyage_api_key
+
+      t.timestamps
+    end
+  end
+end

data/db/migrate/20260816000001_enable_pgvector_extension.rb

@@ -0,0 +1,16 @@
+class EnablePgvectorExtension < ActiveRecord::Migration[8.1]
+  def change
+    # This extension's semantic search is fundamentally Postgres+pgvector —
+    # there is no SQLite/MySQL equivalent to fall back to (unlike, say,
+    # spree_square's json/jsonb split, which was a syntax difference for the
+    # same feature). On a non-Postgres adapter this migration — and the one
+    # that follows it, creating spree_menu_chat_embeddings — is a deliberate
+    # no-op rather than an error, so `bundle exec rake test_app` and the
+    # Credential/LlmClient specs still work on SQLite/MySQL; only the
+    # embeddings feature itself requires Postgres in the host app (see
+    # README.md's Requirements section).
+    return unless connection.adapter_name.match?(/postg/i)
+
+    enable_extension 'vector'
+  end
+end

data/db/migrate/20260816000002_create_spree_menu_chat_embeddings.rb

@@ -0,0 +1,44 @@
+class CreateSpreeMenuChatEmbeddings < ActiveRecord::Migration[8.1]
+  def change
+    # See EnablePgvectorExtension's comment — Postgres-only, deliberate no-op
+    # elsewhere.
+    return unless connection.adapter_name.match?(/postg/i)
+
+    create_table :spree_menu_chat_embeddings do |t|
+      # Polymorphic so both Spree::Product (menu items) and Spree::Policy
+      # (hours/delivery-area/allergen content — see the plan's decision to
+      # reuse Spree::Policy rather than build a bespoke FAQ model) embed
+      # into the same table and get retrieved together by
+      # SpreeMenuChat::Retriever (M3).
+      # index: false — the unique composite index added below (one embedding
+      # row per source record) already covers lookups on these two columns;
+      # a separate non-unique index on the same pair would be redundant.
+      t.references :embeddable, polymorphic: true, null: false, index: false
+      t.references :store, null: false, foreign_key: { to_table: :spree_stores }
+
+      # The exact text that was embedded — kept alongside the vector so
+      # Retriever can inject it directly into the generation prompt without
+      # a second lookup, and so a content_hash mismatch (below) is easy to
+      # diff/debug.
+      t.text :content, null: false
+
+      # 1024 dims — Voyage's default output_dimension for voyage-4-lite (see
+      # SpreeMenuChat::Configuration). Column type/limit are Postgres-only
+      # (via the `vector` extension enabled above); the `neighbor` gem
+      # provides the ActiveRecord query interface (`has_neighbors` /
+      # `nearest_neighbors`) on top of it.
+      t.vector :embedding, limit: 1024
+
+      # SHA-256 of `content` — lets SpreeMenuChat::ReembedProductJob skip
+      # re-embedding (and re-billing Voyage) when a product was saved but
+      # none of its embeddable fields actually changed.
+      t.string :content_hash, null: false
+
+      t.timestamps
+    end
+
+    # One embedding row per source record — re-embedding upserts in place
+    # rather than accumulating duplicates.
+    add_index :spree_menu_chat_embeddings, %i[embeddable_type embeddable_id], unique: true, name: 'index_menu_chat_embeddings_on_embeddable_unique'
+  end
+end

data/db/migrate/20260816000003_create_spree_menu_chat_rate_limits.rb

@@ -0,0 +1,27 @@
+class CreateSpreeMenuChatRateLimits < ActiveRecord::Migration[8.1]
+  def change
+    create_table :spree_menu_chat_rate_limits do |t|
+      t.references :store, null: false, foreign_key: { to_table: :spree_stores }
+
+      # The requester — currently always request.remote_ip (see
+      # SpreeMenuChat::ChatController). A plain string rather than a
+      # belongs_to: there's no session/customer model to key off yet (the
+      # widget is anonymous), and an IP is what's actually available at the
+      # point rate limiting has to happen, before any answer is generated.
+      t.string :identifier, null: false
+
+      # Fixed-window counter, not a row-per-request log: one row per
+      # (store, identifier), reset when the window rolls over. Keeps this
+      # table's size bounded by unique requesters, not by message volume —
+      # same reasoning as SpreeMenuChat::EmbeddingClient's in-process
+      # throttle (M2) being a counter, not a log, just persisted instead of
+      # in-memory since this needs to survive across requests/processes.
+      t.integer :count, null: false, default: 0
+      t.datetime :window_started_at, null: false
+
+      t.timestamps
+    end
+
+    add_index :spree_menu_chat_rate_limits, %i[store_id identifier], unique: true, name: 'index_menu_chat_rate_limits_on_store_and_identifier'
+  end
+end

data/db/migrate/20260816000004_create_spree_menu_chat_token_usages.rb

@@ -0,0 +1,19 @@
+class CreateSpreeMenuChatTokenUsages < ActiveRecord::Migration[8.1]
+  def change
+    create_table :spree_menu_chat_token_usages do |t|
+      t.references :store, null: false, foreign_key: { to_table: :spree_stores }
+      t.date :date, null: false
+
+      # Gemini generation tokens only (see SpreeMenuChat::TokenBudget's
+      # class comment for why embedding tokens aren't folded in here yet)
+      # — a running total for the store-day, incremented after each real
+      # generation call using Gemini's own reported usageMetadata, not an
+      # estimate.
+      t.integer :tokens_used, null: false, default: 0
+
+      t.timestamps
+    end
+
+    add_index :spree_menu_chat_token_usages, %i[store_id date], unique: true, name: 'index_menu_chat_token_usages_on_store_and_date'
+  end
+end

data/db/migrate/20260816000005_create_spree_menu_chat_conversations.rb

@@ -0,0 +1,20 @@
+class CreateSpreeMenuChatConversations < ActiveRecord::Migration[8.1]
+  def change
+    create_table :spree_menu_chat_conversations do |t|
+      t.references :store, null: false, foreign_key: { to_table: :spree_stores }
+
+      # Same anonymous identifier SpreeMenuChat::RateLimiter keys on
+      # (request.remote_ip) — the widget has no session/customer model,
+      # so this is what's actually available. SpreeMenuChat::Conversation
+      # groups messages into one row per (store, identifier) within a
+      # short rolling window rather than per HTTP request — see that
+      # model's comment for why a time-window heuristic, not an explicit
+      # client-sent session id, was the M6 scope decision.
+      t.string :identifier, null: false
+
+      t.timestamps
+    end
+
+    add_index :spree_menu_chat_conversations, %i[store_id identifier updated_at], name: 'index_menu_chat_conversations_on_store_identifier_updated'
+  end
+end

data/db/migrate/20260816000006_create_spree_menu_chat_messages.rb

@@ -0,0 +1,18 @@
+class CreateSpreeMenuChatMessages < ActiveRecord::Migration[8.1]
+  def change
+    create_table :spree_menu_chat_messages do |t|
+      t.references :conversation, null: false, foreign_key: { to_table: :spree_menu_chat_conversations }
+
+      # "user" or "assistant" — SpreeMenuChat::ChatController logs one of
+      # each per real chat exchange (the customer's real question, and the
+      # full assembled answer once streaming completes). A plain string,
+      # not an enum: two known values, no real benefit to the extra
+      # migration ceremony an enum would add here.
+      t.string :role, null: false
+      t.text :content, null: false
+
+      t.datetime :created_at, null: false
+      # No updated_at — a logged message is never edited after the fact.
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+module SpreeMenuChat
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      class_option :migrate, type: :boolean, default: true
+
+      def add_migrations
+        run 'bundle exec rake railties:install:migrations FROM=spree_menu_chat'
+      end
+
+      def run_migrations
+        run_migrations = options[:migrate] || ['', 'y', 'Y'].include?(ask('Would you like to run the migrations now? [Y/n]'))
+        if run_migrations
+          run 'bin/rails db:migrate'
+        else
+          puts 'Skipping rails db:migrate, don\'t forget to run it!'
+        end
+      end
+    end
+  end
+end

data/lib/spree_menu_chat/configuration.rb

@@ -0,0 +1,63 @@
+module SpreeMenuChat
+  class Configuration < Spree::Preferences::Configuration
+    # Generation model — the "flash-lite-latest" alias, not a pinned dated
+    # model. Confirmed live (2026-08-16): the pinned `gemini-2.5-flash-lite`
+    # already 404s for new API keys ("no longer available to new users"),
+    # despite still being listed by the models.list endpoint — Google's
+    # ListModels catalog does not reflect real per-account availability, so
+    # a pinned model string silently rots. The `-latest` alias resolves to
+    # whatever Google currently recommends (confirmed live: currently
+    # `gemini-3.5-flash-lite`) and is the more robust default. Grounded,
+    # low-stakes menu/FAQ Q&A over retrieved context doesn't need a larger
+    # model, and the free tier (no billing account required) keeps this
+    # project's running cost at $0 during development. Override to a larger
+    # Gemini model (or a different provider entirely, by swapping
+    # SpreeMenuChat::LlmClient) if quality on compound questions proves
+    # insufficient.
+    preference :generation_model, :string, default: 'gemini-flash-lite-latest'
+
+    # Embedding model — voyage-4-lite: cheapest model still explicitly
+    # covered by Voyage's free tier (confirmed against their own pricing
+    # docs: voyage-4-large/voyage-4/voyage-4-lite/voyage-context-4/
+    # voyage-code-3 get the first 200M tokens free; voyage-3-lite is not
+    # among the models Voyage's current docs even list anymore — same kind
+    # of model-catalog rot as Gemini's, checked live before picking this
+    # default rather than assumed). Output dimension defaults to 1024 (see
+    # SpreeMenuChat::Embedding's migration) — plenty for a restaurant-sized
+    # corpus, no need to request the smaller 256/512 options.
+    preference :embedding_model, :string, default: 'voyage-4-lite'
+
+    # Minimum cosine similarity a retrieved chunk must clear to be used as
+    # context. Below this, SpreeMenuChat::Retriever returns nothing and
+    # SpreeMenuChat::AnswerGenerator skips the LLM call entirely rather than
+    # answering from a weak/irrelevant match — see M3's guardrail note.
+    #
+    # 0.35, not the originally-planned 0.7 — corrected after live
+    # calibration against the real synced catalog (M3 implementation,
+    # 2026-08-16): 0.7 was a speculative default picked before ever
+    # querying real embeddings, and it was badly miscalibrated. Real
+    # Voyage cosine distances for genuinely correct, on-topic matches
+    # against real menu-item/policy content ranged 0.32-0.63 across 7 real
+    # test questions ("what comes with the buffalo wings?" -> Buffalo
+    # Wings at 0.32, "do you deliver?" -> Shipping Policy at 0.63, etc.) —
+    # a 0.7 similarity floor (max distance 0.3) rejected nearly every one
+    # of them, meaning the assistant would have given the canned
+    # "I don't have that" fallback for almost all real, answerable
+    # questions. A genuinely off-topic/unanswerable question ("what are
+    # your hours?", with no Hours policy actually seeded) landed at 0.76 —
+    # comfortably excluded by this floor with margin to spare.
+    preference :similarity_floor, :decimal, default: 0.35
+
+    # How many chunks to retrieve as context per question.
+    preference :retrieval_top_k, :integer, default: 5
+
+    # Rate limiting (M5) — per-session-or-IP, per rolling hour.
+    preference :rate_limit_per_hour, :integer, default: 20
+
+    # Daily token budget across the whole store, generation + embedding
+    # combined. Once exhausted, the chat falls back to the "contact us"
+    # response for the rest of the day rather than continuing to spend.
+    # Business decision, not a technical one — tune per store.
+    preference :daily_token_budget, :integer, default: 200_000
+  end
+end

data/lib/spree_menu_chat/engine.rb

@@ -0,0 +1,45 @@
+module SpreeMenuChat
+  class Engine < Rails::Engine
+    require 'spree/core'
+    isolate_namespace Spree
+    engine_name 'spree_menu_chat'
+
+    config.generators do |g|
+      g.test_framework :rspec
+    end
+
+    initializer 'spree_menu_chat.environment', before: :load_config_initializers do |_app|
+      SpreeMenuChat::Config = SpreeMenuChat::Configuration.new
+    end
+
+    # Same ordering requirement as spree_square's and spree_doordash's
+    # identical initializer — must run before Active Record's own
+    # "active_record_encryption.configuration" initializer reads
+    # config.active_record.encryption, or Credential's encrypted columns
+    # fail with "Missing Active Record encryption credential" the first
+    # time they're touched. Shares the same ACTIVE_RECORD_ENCRYPTION_* keys
+    # the sibling extensions already set up (one encryption key set per
+    # Rails app, not per extension).
+    initializer 'spree_menu_chat.active_record_encryption', before: 'active_record_encryption.configuration' do |app|
+      next if ENV['ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY'].blank?
+
+      app.config.active_record.encryption.primary_key = ENV['ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY']
+      app.config.active_record.encryption.deterministic_key = ENV['ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY']
+      app.config.active_record.encryption.key_derivation_salt = ENV['ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT']
+    end
+
+    # Force-loads decorator files (the Spree::Product after_commit re-embed
+    # hook, added in M2) the same way spree_square's/spree_doordash's engines
+    # do — Zeitwerk lazy-autoloading never triggers a decorator file's
+    # `prepend` line otherwise. Kept here from the start even though M1 has
+    # no decorator yet, so adding one later doesn't require remembering this
+    # step.
+    def self.activate
+      Dir.glob(File.join(File.dirname(__FILE__), '../../app/**/*_decorator*.rb')) do |c|
+        Rails.application.config.cache_classes ? require(c) : load(c)
+      end
+    end
+
+    config.to_prepare(&method(:activate).to_proc)
+  end
+end

data/lib/spree_menu_chat/factories.rb

@@ -0,0 +1,48 @@
+FactoryBot.define do
+  # Define your Spree extensions Factories within this file to enable applications, and other extensions to use and override them.
+  #
+  # Example adding this to your spec_helper will load these Factories for use:
+  # require 'spree_menu_chat/factories'
+
+  factory :menu_chat_credential, class: 'SpreeMenuChat::Credential' do
+    store
+    gemini_api_key { 'test-gemini-api-key' }
+    voyage_api_key { 'test-voyage-api-key' }
+  end
+
+  factory :menu_chat_embedding, class: 'SpreeMenuChat::Embedding' do
+    embeddable factory: :product
+    store
+    content { 'Test Product\n\nA product used for specs.' }
+    content_hash { SpreeMenuChat::Embedding.content_hash_for(content) }
+    # 1024 dims to match the migration's vector(1024) column (Voyage's
+    # default output_dimension for voyage-4-lite) — a fixed, deterministic
+    # vector rather than random noise, so distance-based spec assertions
+    # (nearest_neighbors ordering) are reproducible.
+    embedding { Array.new(1024) { 0.001 } }
+  end
+
+  factory :menu_chat_rate_limit, class: 'SpreeMenuChat::RateLimit' do
+    store
+    identifier { '127.0.0.1' }
+    count { 0 }
+    window_started_at { Time.current }
+  end
+
+  factory :menu_chat_token_usage, class: 'SpreeMenuChat::TokenUsage' do
+    store
+    date { Date.current }
+    tokens_used { 0 }
+  end
+
+  factory :menu_chat_conversation, class: 'SpreeMenuChat::Conversation' do
+    store
+    identifier { '127.0.0.1' }
+  end
+
+  factory :menu_chat_message, class: 'SpreeMenuChat::Message' do
+    conversation factory: :menu_chat_conversation
+    role { 'user' }
+    content { 'what comes with the burrito bowl?' }
+  end
+end

data/lib/spree_menu_chat/version.rb

@@ -0,0 +1,7 @@
+module SpreeMenuChat
+  VERSION = '0.1.0'.freeze
+
+  def gem_version
+    Gem::Version.new(VERSION)
+  end
+end

data/lib/spree_menu_chat.rb

@@ -0,0 +1,30 @@
+require 'spree'
+# Required explicitly here, not left to Bundler.require: neighbor is only a
+# gemspec dependency of this gem (a transitive dependency from a host app's
+# point of view), and Bundler.require only auto-requires gems listed
+# directly in the Gemfile. Without this, `t.vector` in migrations and
+# `has_neighbors` on SpreeMenuChat::Embedding both raise NoMethodError —
+# confirmed live: neighbor's Railtie (which registers the `vector` column
+# type) never ran, even though `bundle install` had it installed and
+# `Gem.loaded_specs.key?('neighbor')` was true. Loaded here, in the gem's
+# main entry file, rather than lazily inside the Embedding model, because
+# the Railtie needs to be in place before migrations run, not just before
+# the model is first autoloaded.
+require 'neighbor'
+# Same rationale as neighbor above — kramdown is only a gemspec
+# (transitive) dependency, not auto-required by Bundler.require.
+# SpreeMenuChat::Message#rendered_content would raise NameError without
+# this, in exactly the same "works under Zeitwerk eager-load, fails under
+# rails runner/real request lazy autoloading" shape neighbor's bug had.
+require 'kramdown'
+require 'spree_menu_chat/engine'
+require 'spree_menu_chat/version'
+require 'spree_menu_chat/configuration'
+
+module SpreeMenuChat
+  mattr_accessor :queue
+
+  def self.queue
+    @@queue ||= Spree.queues.default
+  end
+end

data/lib/tasks/spree_menu_chat.rake

@@ -0,0 +1,93 @@
+namespace :spree_menu_chat do
+  # M1 verification: proves the API key this extension is given is actually
+  # accepted by a real Gemini endpoint, not just wired up correctly per the
+  # documented request shape (already covered by
+  # spec/services/spree_menu_chat/llm_client_spec.rb).
+  #
+  # Reads a real key from .env.local (gitignored, never committed — see that
+  # file's own comment) rather than the encrypted SpreeMenuChat::Credential
+  # row, so this can run standalone against the gem's own dummy app without
+  # needing a full spree_host install first.
+  #
+  # Usage:
+  #   bin/rails spree_menu_chat:verify_connection
+  desc 'Verify the Gemini API key by requesting one real generation'
+  task verify_connection: :environment do
+    env_path = File.expand_path('../../.env.local', __dir__)
+    unless File.exist?(env_path)
+      abort "No .env.local found at #{env_path} — copy .env.local.example, fill in GEMINI_API_KEY, and try again."
+    end
+
+    require 'dotenv'
+    Dotenv.load(env_path)
+
+    abort 'GEMINI_API_KEY is blank in .env.local — fill it in first.' if ENV['GEMINI_API_KEY'].blank?
+
+    credential = SpreeMenuChat::Credential.new(gemini_api_key: ENV['GEMINI_API_KEY'])
+    client = SpreeMenuChat::LlmClient.new(credential: credential)
+
+    puts "Requesting a real Gemini completion (#{SpreeMenuChat::Config.generation_model})..."
+    begin
+      result = client.generate(
+        'Reply with exactly one short sentence confirming this connection works.',
+        system_instruction: 'You are a connectivity test. Be brief.'
+      )
+      text = result.dig('candidates', 0, 'content', 'parts', 0, 'text')
+      puts '✅ Success — Gemini accepted the key and generated a real response:'
+      puts text || JSON.pretty_generate(result)
+    rescue SpreeMenuChat::RequestError => e
+      puts "❌ Gemini rejected the request (HTTP #{e.status}):"
+      puts JSON.pretty_generate(e.body)
+      exit 1
+    end
+  end
+
+  # M2 verification: proves the Voyage API key actually works against a
+  # real endpoint (same rationale as verify_connection above) before
+  # trusting reembed_all to spend real API calls across a whole catalog.
+  #
+  # Usage:
+  #   bin/rails spree_menu_chat:verify_embeddings
+  desc 'Verify the Voyage AI API key by requesting one real embedding'
+  task verify_embeddings: :environment do
+    env_path = File.expand_path('../../.env.local', __dir__)
+    unless File.exist?(env_path)
+      abort "No .env.local found at #{env_path} — copy .env.local.example, fill in VOYAGE_API_KEY, and try again."
+    end
+
+    require 'dotenv'
+    Dotenv.load(env_path)
+
+    abort 'VOYAGE_API_KEY is blank in .env.local — fill it in first.' if ENV['VOYAGE_API_KEY'].blank?
+
+    credential = SpreeMenuChat::Credential.new(voyage_api_key: ENV['VOYAGE_API_KEY'])
+    client = SpreeMenuChat::EmbeddingClient.new(credential: credential)
+
+    puts "Requesting a real Voyage embedding (#{SpreeMenuChat::Config.embedding_model})..."
+    begin
+      vectors = client.embed('Spicy black bean burrito bowl with pickled onions', input_type: 'document')
+      vector = vectors.first
+      puts '✅ Success — Voyage accepted the key and returned a real embedding:'
+      puts "#{vector.length} dimensions, first 5 values: #{vector.first(5).inspect}"
+    rescue SpreeMenuChat::RequestError => e
+      puts "❌ Voyage rejected the request (HTTP #{e.status}):"
+      puts JSON.pretty_generate(e.body)
+      exit 1
+    end
+  end
+
+  # M2 backfill / admin "rebuild index" action — embeds every non-deleted,
+  # non-archived product plus every Spree::Policy for the given store (or
+  # Spree::Store.default). Safe to re-run: SpreeMenuChat::Embedder skips
+  # anything whose content hasn't actually changed since it was last
+  # embedded.
+  #
+  # Usage:
+  #   bin/rails spree_menu_chat:reembed_all
+  #   bin/rails "spree_menu_chat:reembed_all[store_id]"
+  desc 'Re-embed every product and policy for a store (default: the default store)'
+  task :reembed_all, %i[store_id] => :environment do |_t, args|
+    SpreeMenuChat::ReembedCatalogJob.perform_now(args[:store_id])
+    puts "✅ Re-embedded #{SpreeMenuChat::Embedding.count} record(s)."
+  end
+end

data/spree_menu_chat.gemspec

@@ -0,0 +1,63 @@
+# encoding: UTF-8
+lib = File.expand_path('../lib/', __FILE__)
+$LOAD_PATH.unshift lib unless $LOAD_PATH.include?(lib)
+
+require 'spree_menu_chat/version'
+
+Gem::Specification.new do |s|
+  s.platform    = Gem::Platform::RUBY
+  s.name        = 'spree_menu_chat'
+  s.version     = SpreeMenuChat::VERSION
+  s.summary     = 'Spree Commerce Menu & FAQ Chat Assistant'
+  s.description = 'A read-only, retrieval-grounded chat assistant for Spree storefronts — answers ' \
+                   'customer questions about the menu, ingredients, dietary info, hours, and policies ' \
+                   'using the store\'s own synced catalog and Spree::Policy content. No cart or order ' \
+                   'mutation capability of any kind. Companion extension to spree_square, reused via a ' \
+                   'soft dependency for modifier-list grounding when present.'
+  s.required_ruby_version = '>= 3.2'
+
+  s.author    = 'Amit Solanki'
+  s.email     = 'amit@prayantr.com'
+  s.homepage  = 'https://github.com/amitkssolanki/spree_menu_chat'
+  s.license   = 'MIT'
+
+  s.metadata = {
+    'homepage_uri' => s.homepage,
+    'source_code_uri' => s.homepage,
+    'changelog_uri' => "#{s.homepage}/blob/main/CHANGELOG.md",
+    'bug_tracker_uri' => "#{s.homepage}/issues"
+  }
+
+  s.files = `git ls-files -z`.split("\x0").reject do |f|
+    f.start_with?('spec/') && !f.start_with?('spec/fixtures')
+  end
+  s.require_path = 'lib'
+  s.requirements << 'none'
+
+  spree_version = '>= 5.4.0.beta'
+  s.add_dependency 'spree', spree_version
+  s.add_dependency 'spree_admin', spree_version
+
+  # Neither Gemini (generation) nor Voyage AI (embeddings) has an official
+  # Google/Voyage-maintained Ruby SDK — both are called directly over their
+  # REST APIs via Faraday, the same "no SDK, plain REST" pattern
+  # spree_doordash already uses for DoorDash's Drive API (see
+  # SpreeDoordash::Client). pgvector similarity queries go through the
+  # `neighbor` gem (adds `nearest_neighbors`/cosine-distance query support
+  # on top of a plain `vector` column — no ActiveRecord adapter of its own
+  # to maintain).
+  s.add_dependency 'faraday', '~> 2.0'
+  s.add_dependency 'neighbor', '~> 0.5'
+
+  # Gemini's real answers regularly come back with markdown (bold
+  # ingredient names, bullet lists of menu items) — used to render both
+  # the admin conversation view (SpreeMenuChat::Message#content, plain
+  # text as stored) and, via the storefront's own react-markdown, the
+  # widget itself. Pure Ruby, no native extension — kramdown's own stated
+  # design goal, unlike redcarpet's C extension.
+  s.add_dependency 'kramdown', '~> 2.4'
+
+  s.add_development_dependency 'spree_dev_tools'
+  s.add_development_dependency 'webmock'
+  s.add_development_dependency 'gem-release'
+end