rate-card 0.1.5 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 21c45d1eea2e85a47a9f268250611d10548eb3b812d4d5dd27716506c9802e3e
-  data.tar.gz: c209d3d667be368253081ded2e7aab44f9138cefebeb086d27257f137b92538d
+  metadata.gz: 26756dd90159acde8bf444c7b7a4de2ee99c4b7b05c87a01a3f4946b3e920bb8
+  data.tar.gz: 0a2f73702f26ef311b8c729951f21e72b9641893b566de5928dbb5ba2aacd5b0
 SHA512:
-  metadata.gz: 0ae5c80051382299425a11519bf0f8fa8132906f58cbf34c971480cb28989857fb12aff2f7099a1709187109a1e6bb530c778a2b5da3e6c1309bbede94cee8d6
-  data.tar.gz: b90f381a9eb2f54c2b69a5653ca1c71e909210787040fe7e67e5872fd759efda0eca6a7a5b66e8df58fb9d9b615d718bac6aaeb062befad1e61d62cebb643463
+  metadata.gz: 1c891d9491881bad2b00b8c5b143ef3118699c6607e12449f653129d9d94e5a716f61b655f26988f0a53a01eaada736bf3e5d12afce72fcd685479d025179b1c
+  data.tar.gz: 06aec0434e85290036bfae0f3a672c597770d5519ecf89330751b16e53f44017bf5fdd271ed9e74e6e978653c57d0c358dbc9a87066eb024a1bfd42dffe1b37e

data/lib/rate_card/constants/addresses.rb

@@ -106,6 +106,75 @@ module RateCard
       # mode sweeps surcharge types instead of zones — see RunSpec#address_for.
       UPS_RURAL = { edas: UPS_EDAS_EXCEPTION, rdas: UPS_RDAS_EXCEPTION }.freeze
 
+      # UNVERIFIED — real public post-office addresses, one per origin ZIP3
+      # that Usps::IntlGroup1ZoneCalculator (ehub app/services/usps/
+      # intl_group1_zone_calculator.rb, backed by
+      # files/usps_intl_canada_zones.json.gz) maps to each zone 1-8.
+      #
+      # USPS's Canada rate is origin-driven, not destination-driven like the
+      # domestic charts above: the zone comes from the FROM zip's first 3
+      # digits, and the destination only needs to be a real address in
+      # Canada (see the spec fixtures in usps/rate_calculator_spec.rb, which
+      # call rate(from_zip, 'CA', ...) - no street-level destination enters
+      # the calculation at all). That inverts RunSpec#address_for's usual
+      # "vary destination, fix origin" shape for this one carrier/country
+      # pair - see #origin_for.
+      #
+      # Addresses are real (each is a public USPS post office and its ZIP3
+      # was confirmed against the actual origin table, not just "a nearby
+      # city"), but UNVERIFIED means the ZIP3 -> zone mapping itself hasn't
+      # been re-derived from files/usps_intl_canada_zones.json.gz by a
+      # second person - do this before trusting a rate card built from it.
+      USPS_CANADA_ORIGINS = {
+        1 => { address1: '1040 Waverly Ave', city: 'Holtsville', state: 'NY', postal_code: '00501', country: 'US' },
+        2 => { address1: '600 Suffield St', city: 'Agawam', state: 'MA', postal_code: '01001', country: 'US' },
+        3 => { address1: '462 Washington St', city: 'Woburn', state: 'MA', postal_code: '01801', country: 'US' },
+        4 => { address1: '73 Hammond St Ste 9998', city: 'Bangor', state: 'ME', postal_code: '04401', country: 'US' },
+        5 => { address1: '83 Broad St', city: 'Charleston', state: 'SC', postal_code: '29401', country: 'US' },
+        6 => { address1: '50 Carr 459', city: 'Aguadilla', state: 'PR', postal_code: '00603', country: 'US' },
+        7 => { address1: '709 W 9th St', city: 'Juneau', state: 'AK', postal_code: '99801', country: 'US' },
+        8 => { address1: '99-040 Kauhale St', city: 'Aiea', state: 'HI', postal_code: '96701', country: 'US' }
+      }.freeze
+
+      # UNVERIFIED — the fixed Canadian destination for every USPS_CANADA_ORIGINS
+      # zone. Ported from INTERNATIONAL_UNVERIFIED zone 0 below. Safe to reuse
+      # across all 8 zones only because USPS's Canada rate doesn't depend on
+      # destination specifics - see USPS_CANADA_ORIGINS above. Do not reuse
+      # this reasoning for any other carrier without checking that carrier's
+      # own calculator the same way.
+      USPS_CANADA_DESTINATION = { address1: '6990 Victoria Dr', city: 'Vancouver', state: 'BC',
+                                   postal_code: 'V5P 3Y8', country: 'CA' }.freeze
+
+      # UNVERIFIED — ported as-is from ../rate_table_builder/constants/address_constants.rb
+      # (INTL_ADDRESSES, originally commented "# International?"). Not
+      # confirmed against any carrier's actual international zone chart, and
+      # not carrier-specific: the source file left international: nil for
+      # USPS, UPS, and FedEx alike, so these zone numbers are not known to
+      # correspond to DHL Express, DHL eCommerce, or USPS Priority Mail
+      # International zone boundaries. Do not wire this into BY_CARRIER or
+      # for_carrier until each entry is hand-verified against a real
+      # carrier zone chart, the way the domestic addresses above are.
+      INTERNATIONAL_UNVERIFIED = [
+        { zone: 0, address1: '6990 Victoria Dr', city: 'Vancouver', state: 'Vancouver', postal_code: 'V5P 3Y8', country: 'CA' },
+        { zone: 1, address1: '1249 Metcalfe St', city: 'Montreal', state: 'Montreal', postal_code: 'H3B 2V5', country: 'CA' },
+        { zone: 2, address1: '10416 80 Ave NW', city: 'Edmonton', state: 'Edmonton', postal_code: 'T6E 5T7', country: 'CA' },
+        { zone: 3, address1: '4910 52 St', city: 'Yellowknife', state: 'Yellowknife', postal_code: 'X1A 1T3', country: 'CA' },
+        { zone: 4, address1: '179 Shaftesbury Ave', city: 'London', state: 'London', postal_code: 'WC2H 8JR', country: 'GB' },
+        { zone: 5, address1: 'R Sao Joaquim, 381 - Liberdade', city: 'Sao Paulo', state: 'Sao Paulo', postal_code: '01508-001', country: 'BR' },
+        { zone: 6, address1: '10 Bligh St', city: 'Sydney', state: 'Sydney', postal_code: '2000', country: 'AU' },
+        { zone: 7, address1: 'Rudi-Dutschke-Strasse 26', city: 'Berlin', state: 'Berlin', postal_code: '10969', country: 'DE' },
+        { zone: 8, address1: '107 Rue de Rivoli', city: 'Paris', state: 'Paris', postal_code: '75001', country: 'FR' },
+        { zone: 9, address1: 'Colima 150, Roma Nte.', city: 'Mexico City', state: 'Mexico City', postal_code: '06700', country: 'MX' },
+        { zone: 10, address1: '18 Merrion Row', city: 'Dublin', state: 'Dublin', postal_code: 'D02 A316', country: 'IE' },
+        { zone: 11, address1: '3 Chome-4 Kagurazaka', city: 'Tokyo', state: 'Tokyo', postal_code: '162-0825', country: 'JP' },
+        { zone: 12, address1: '90 Wellesley Street West', city: 'Auckland', state: 'Auckland', postal_code: '1010', country: 'NZ' },
+        { zone: 13, address1: 'Munsterhof 12,', city: 'Zurich', state: 'Zurich', postal_code: '8001', country: 'CH' },
+        { zone: 14, address1: 'Daniel Stalpertstraat 103', city: 'Amsterdam', state: 'Amsterdam', postal_code: '1072', country: 'NL' },
+        { zone: 15, address1: '404 Crescent Business Park Link Road Andheri', city: 'Mumbai', state: 'Maharashtra', postal_code: '400072', country: 'IN' },
+        { zone: 16, address1: 'C. del Prado, 16', city: 'Madrid', state: 'Madrid', postal_code: '28014', country: 'ES' },
+        { zone: 17, address1: 'Piazza Pasquale Paoli 15', city: 'Roma', state: 'Roma', postal_code: '00186', country: 'IT' }
+      ].freeze
+
       module_function
 
       # Raises rather than falling back. The old USPS default meant asking for

data/lib/rate_card/constants/carriers.rb

@@ -7,7 +7,8 @@ module RateCard
     module Carriers
       OTHER = 'Other'
 
-      DISPLAY_ORDER = ['USPS', 'UPS', 'FedEx', 'DHL', 'OSM', 'Amazon', OTHER].freeze
+      DISPLAY_ORDER = ['USPS', 'UPS', 'FedEx', 'DHL', 'OSM', 'CDL', 'GLS', 'SpeedX',
+                       'UniUni', 'Veho', 'Dragonfly', 'Amazon', OTHER].freeze
 
       # Every /services entry carries a lowercase carrier_code. Anything not
       # listed here keeps its own code, upcased: an unrecognised carrier is
@@ -27,7 +28,10 @@ module RateCard
       # silently inherit the wrong zone chart.
       CARRIER_CODES = {
         'usps' => 'USPS', 'ups' => 'UPS', 'fedex' => 'FedEx',
-        'dhl' => 'DHL Express', 'dhl_ecommerce' => 'DHL', 'osm' => 'OSM', 'amazon' => 'Amazon'
+        'dhl' => 'DHL Express', 'dhl_ecommerce' => 'DHL', 'osm' => 'OSM',
+        'cdl' => 'CDL', 'gls' => 'GLS', 'speedx' => 'SpeedX',
+        'uniuni' => 'UniUni', 'veho' => 'Veho', 'dragonfly' => 'Dragonfly',
+        'amazon' => 'Amazon'
       }.freeze
 
       # Carriers with a rural/DAS surcharge test address in Constants::Addresses.
@@ -35,6 +39,32 @@ module RateCard
       # chart and no rural chart at all.
       RURAL_AWARE = %w[USPS UPS].freeze
 
+      # Carriers with no entry in Addresses::BY_CARRIER — their zone chart would
+      # be fetched live per run via Providers::EHub::Client#fetch_zone_addresses
+      # instead of read from a hand-verified constant. See
+      # 2026-09-03-dynamic-zone-addresses-design.md. OLX is deliberately not
+      # here — no live OLX rating API exists in ehub.
+      #
+      # Disabled for now: the zone_addresses endpoint does not exist yet in
+      # ehub-api, so these carriers report as unsupported (like any other
+      # carrier with no chart) rather than attempting a call that always 404s.
+      # Restore this list once the endpoint ships.
+      LIVE_CHART = [].freeze
+
+      # Carriers with an international destination in Constants::Addresses
+      # (USPS_CANADA_ORIGINS/USPS_CANADA_DESTINATION today). Kept explicit
+      # rather than inferring from chart presence, same reasoning as
+      # RURAL_AWARE — a carrier can support domestic long before any
+      # international country is verified for it.
+      #
+      # Empty for now: USPS_CANADA_ORIGINS' ZIP3 -> zone mapping is still
+      # UNVERIFIED (see Constants::Addresses), so the Destination prompt is
+      # hidden from the wizard until a second person re-derives it against
+      # files/usps_intl_canada_zones.json.gz. Add 'USPS' back once that's
+      # done — country_field, zones_field, and RunSpec#origin_for are
+      # already wired and need no other change.
+      INTERNATIONAL_AWARE = [].freeze
+
       module_function
 
       # OTHER is only for a malformed entry with no code at all, so a service is
@@ -53,6 +83,14 @@ module RateCard
       def rural_aware?(carrier)
         RURAL_AWARE.include?(carrier.to_s)
       end
+
+      def live_chart?(carrier)
+        LIVE_CHART.include?(carrier.to_s)
+      end
+
+      def international_aware?(carrier)
+        INTERNATIONAL_AWARE.include?(carrier.to_s)
+      end
     end
   end
 end

data/lib/rate_card/grid.rb

@@ -71,7 +71,8 @@ module RateCard
     end
 
     def fetch_cell(client, weight, zone, retry_sleeper)
-      payload = provider.build_payload(spec: spec, weight: weight, address: spec.address_for(zone))
+      payload = provider.build_payload(spec: spec, weight: weight, address: spec.address_for(zone),
+                                        origin: spec.origin_for(zone))
       result = fetch_with_transient_retry(client, payload, retry_sleeper)
       record_response(result, weight, zone)
       @mutex.synchronize { @succeeded += 1 }

data/lib/rate_card/providers/ehub/client.rb

@@ -16,10 +16,15 @@ module RateCard
       # full of blank cells instead of one clear error — do not do that.
       class Client
         BASE_URL = 'https://api.ehub.com'
+        # Zone-addresses defaults to the local server that has the fix in
+        # progress, while rates/services stay on production. Override with
+        # RATE_CARD_ZONE_ADDRESSES_URL (e.g. back to BASE_URL once the fix ships).
+        ZONE_ADDRESSES_BASE_URL = ENV.fetch('RATE_CARD_ZONE_ADDRESSES_URL', 'http://localhost:9000')
         # No trailing slash: that is the documented path, and a trailing slash would
         # rely on a redirect — which can drop the POST body.
         RATES_PATH = '/api/v2/rates'
         SERVICES_PATH = '/api/v2/services'
+        ZONE_ADDRESSES_PATH = '/api/v2/services/%<service_id>s/zone_addresses'
         # 'ecommerce' services are storefront integrations, not shippable rates.
         SERVICES_CATEGORY = 'shipping'
 
@@ -42,7 +47,8 @@ module RateCard
           @token = token
           @stubs = stubs
           @sleeper = sleeper
-          @connection = build_connection
+          @connection = build_connection(BASE_URL)
+          @zone_addresses_connection = ZONE_ADDRESSES_BASE_URL == BASE_URL ? @connection : build_connection(ZONE_ADDRESSES_BASE_URL)
         end
 
         # Returns the parsed response body as a Hash.
@@ -54,7 +60,18 @@ module RateCard
         # Discovery uses this rather than a rate call: it costs nothing, and it lists
         # services that would not have quoted at the single probe weight and zone.
         def fetch_services
-          request('service list call') { get(SERVICES_PATH, category: SERVICES_CATEGORY) }
+          request('service list call') { get(SERVICES_PATH, { category: SERVICES_CATEGORY }) }
+        end
+
+        # Returns the parsed { "zones" => { "1" => {address1:, city:, ...}, ... } }
+        # body for one service's live zone chart. from_postal_code is only
+        # meaningful for a fixed-origin carrier (e.g. GLS) — omitted params
+        # means the server resolves the origin from account configuration.
+        def fetch_zone_addresses(service_id, from_postal_code: nil)
+          params = from_postal_code ? { from_postal_code: from_postal_code } : {}
+          request('zone addresses call') do
+            get(format(ZONE_ADDRESSES_PATH, service_id: service_id), params, connection: @zone_addresses_connection)
+          end
         end
 
         private
@@ -89,8 +106,8 @@ module RateCard
           raise RequestFailed, "rate call failed: #{e.message}"
         end
 
-        def get(path, params)
-          response = @connection.get(path, params)
+        def get(path, params, connection: @connection)
+          response = connection.get(path, params)
           [response.status, parse(response.body)]
         rescue Faraday::Error => e
           raise RequestFailed, "service list call failed: #{e.message}"
@@ -109,8 +126,8 @@ module RateCard
           message ? " (#{message})" : ''
         end
 
-        def build_connection
-          Faraday.new(url: BASE_URL) do |f|
+        def build_connection(url)
+          Faraday.new(url: url) do |f|
             f.headers['Authorization'] = "Bearer #{@token}"
             f.headers['Content-Type'] = 'application/json'
             f.options.timeout = 30

data/lib/rate_card/providers/ehub/provider.rb

@@ -35,8 +35,8 @@ module RateCard
           ServiceCatalog.from_response(body)
         end
 
-        def build_payload(spec:, weight:, address:)
-          Shipment.new(spec: spec, weight: weight, address: address).payload
+        def build_payload(spec:, weight:, address:, origin: nil)
+          Shipment.new(spec: spec, weight: weight, address: address, origin: origin).payload
         end
 
         # Normalizes one /rates response into what Grid needs to record a cell:

data/lib/rate_card/providers/ehub/shipment.rb

@@ -14,16 +14,21 @@ module RateCard
         ITEM_VALUE = 18.99
         HS_TARIFF_CODE = '1704.90.3000'
 
-        def initialize(spec:, weight:, address:)
+        # origin: nil for every carrier except USPS->Canada, where the zone is
+        # a property of the origin rather than the destination — see
+        # RunSpec#origin_for. Falls back to the usual fixed shipment origin
+        # when nil, so every other carrier is unaffected.
+        def initialize(spec:, weight:, address:, origin: nil)
           @spec = spec
           @weight = weight
           @address = address
+          @origin = origin
         end
 
         def payload
           {
             shipment: {
-              from_location: Constants::Addresses::ORIGIN,
+              from_location: origin || Constants::Addresses::ORIGIN,
               to_location: to_location,
               parcels: [parcel]
             }
@@ -32,7 +37,7 @@ module RateCard
 
         private
 
-        attr_reader :spec, :weight, :address
+        attr_reader :spec, :weight, :address, :origin
 
         def to_location
           {

data/lib/rate_card/run_spec.rb

@@ -17,6 +17,8 @@ module RateCard
     :token, :customer_name, :customer_id, :carrier, :services, :zones,
     :weight_unit, :weights, :package_type, :rate_keys, :output_base,
     :show_table, :started_at, :rate_mode, :cubic_tiers, :rural,
+    :zone_chart, # nil for the 5 static-chart carriers, populated for the live ones
+    :country, # nil for domestic; e.g. 'CA' for USPS->Canada — see #origin_for
     keyword_init: true
   )
     # Our rate-key name => the field it arrives as in service_rates. Getting
@@ -54,6 +56,13 @@ module RateCard
       !!rural
     end
 
+    # true only for USPS->Canada today. nil (domestic, or any other carrier)
+    # is falsy here — every existing caller keeps seeing plain domestic
+    # behavior.
+    def international?
+      !!country
+    end
+
     # [1,2,3,5] => "1-3,5". Runs of three or more collapse; a pair stays listed,
     # since "4,5" is no longer than "4-5" and reads as what the user typed.
     #
@@ -124,13 +133,34 @@ module RateCard
     # disambiguates from a real zone number without needing to check carrier
     # or rural separately. USPS rural mode keeps integer zones, just against
     # the rural chart instead of the normal one.
+    # USPS->Canada is destination-fixed, origin-varies — the opposite of
+    # every other chart here (see #origin_for) — so this returns the one
+    # Canadian destination for every zone rather than looking one up per
+    # zone.
     def address_for(zone)
       return Constants::Addresses::UPS_RURAL[zone] if zone.is_a?(Symbol)
       return Constants::Addresses::USPS_RURAL_DAS[zone] if carrier == 'USPS' && rural?
+      return Constants::Addresses::USPS_CANADA_DESTINATION if usps_canada?
+      return zone_chart[zone] if zone_chart
 
       Constants::Addresses.for_carrier(carrier)[zone]
     end
 
+    # nil for every carrier/zone except USPS->Canada, where the zone is a
+    # property of the origin ZIP3 (Usps::IntlGroup1ZoneCalculator), not the
+    # destination — see Constants::Addresses::USPS_CANADA_ORIGINS. Shipment
+    # falls back to the usual fixed Constants::Addresses::ORIGIN when this
+    # is nil, so every other carrier is unaffected.
+    def origin_for(zone)
+      return nil unless usps_canada?
+
+      Constants::Addresses::USPS_CANADA_ORIGINS[zone]
+    end
+
+    def usps_canada?
+      carrier == 'USPS' && country == 'CA'
+    end
+
     def rate_key_label(key)
       RATE_KEY_LABELS.fetch(key, key.to_s.tr('_', ' '))
     end
@@ -168,6 +198,7 @@ module RateCard
     # run_dir. USPS rural mode sweeps real zones as usual, so it just gets
     # the generic suffix.
     def rural_suffix
+      return "_#{country}" if international?
       return '' unless rural?
 
       surcharge = zones.find { |zone| zone.is_a?(Symbol) }
@@ -188,9 +219,9 @@ module RateCard
       end
 
       zones.each do |zone|
-        next if address_for(zone)
+        next if address_for(zone) && (!usps_canada? || origin_for(zone))
 
-        raise ArgumentError, "no address for zone #{zone} on carrier #{carrier}"
+        raise ArgumentError, "no address for zone #{zone} on carrier #{carrier}#{" (#{country})" if country}"
       end
 
       self

data/lib/rate_card/tui/app.rb

@@ -24,8 +24,8 @@ module RateCard
 
       # No :token stage — see TokenPrompt for why it cannot live in the loop.
       STAGES = %i[
-        loading rate_mode carrier rural rural_surcharges services zones unit weights
-        package_type rate_keys confirm fetching
+        loading rate_mode carrier rural rural_surcharges services country gls_origin zones unit weights
+        package_type rate_keys add_another confirm fetching
       ].freeze
 
       # #spec/#grid hold the most recently finished pass, for every caller that
@@ -49,7 +49,7 @@ module RateCard
         @field = nil
         @cancelled = false
         @error = nil
-        @spinner = Bubbles::Spinner.new
+        @spinner = Bubbles::Spinner.new(style: Lipgloss::Style.new.foreground(Theme::ACCENT))
         @progress = Bubbles::Progress.new(width: 32)
         @completed = 0
         @failed = 0
@@ -58,6 +58,11 @@ module RateCard
         @failure_sparkline.style = Lipgloss::Style.new.foreground(Theme::WARNING)
         @log = []
         @results = []
+        @queued_specs = []
+        @queued_scenarios = []
+        @scenario = 1
+        @fresh_scenario_start = false
+        @log << { stage: :scenario_header, line: scenario_header_line(@scenario) }
       end
 
       def cancelled? = @cancelled
@@ -86,8 +91,9 @@ module RateCard
         transcript = @log.filter_map { |entry| entry[:line] }
         sections = []
         sections << transcript.join("\n") unless transcript.empty?
+        sections << Theme.divider unless transcript.empty?
         sections << stage_view
-        "#{sections.compact.join("\n\n")}\n"
+        "#{Theme.panel(sections.compact.join("\n\n"))}\n#{Theme.footer(footer_text)}\n"
       end
 
       private
@@ -114,6 +120,7 @@ module RateCard
         value = @field.value
         # The recap's own Back row, which is the esc key by another name.
         return retreat if @stage == :confirm && value == :back
+        return add_another_chosen(value) if @stage == :add_another
 
         record(@stage, value)
         advance
@@ -135,6 +142,7 @@ module RateCard
       def record(stage, value)
         @answers[stage] = value
         @log << { stage: stage, line: answered_line(stage, value) }
+        @fresh_scenario_start = false
       end
 
       def advance
@@ -148,6 +156,8 @@ module RateCard
           break unless @field.nil?
         end
         nil
+      rescue RequestFailed, UnsupportedCarrier => e
+        fail_with(e).last
       end
 
       # Steps back to the nearest earlier stage that actually asked something,
@@ -155,6 +165,9 @@ module RateCard
       # revisited seeds the field, and every answer after it is forgotten —
       # they were given against a choice that may be about to change.
       def retreat
+        return confirm_back if @stage == :confirm
+        return cancel_fresh_scenario if @fresh_scenario_start
+
         index = STAGES.index(@stage)
         loop do
           index -= 1
@@ -171,6 +184,80 @@ module RateCard
         end
       end
 
+      # Esc from confirm must not re-run the wizard's forget-forward logic -
+      # the scenario just chosen at add_another is already queued and its
+      # answers already cleared (#confirm_or_queue), so there is nothing left
+      # to forget. It simply reopens the add_another question.
+      def confirm_back
+        @stage = :add_another
+        @field = field_for(:add_another)
+        nil
+      end
+
+      # Esc on the very first field of a scenario just started via "Yes, add
+      # another" — nothing has been answered yet for it, so there is nothing
+      # to walk back through. Treated as if "No" had been chosen instead: the
+      # new scenario is abandoned and the queue (already holding the prior
+      # scenario, committed by #confirm_or_queue) goes straight to confirm.
+      def cancel_fresh_scenario
+        @fresh_scenario_start = false
+        @log.pop if @log.last && @log.last[:stage] == :scenario_header
+        @scenario -= 1
+        advance_to_confirm
+      end
+
+      # add_another is now asked as soon as every field is filled in, before
+      # the run is ever confirmed. Either choice queues the just-answered
+      # scenario. Yes clears @answers and jumps back to the wizard's first
+      # real question for a fresh scenario; No moves on to the confirm
+      # screen, which then asks to run the whole queue.
+      def add_another_chosen(value)
+        confirm_or_queue
+        return advance_to_confirm if value == :no
+
+        @scenario += 1
+        @log << { stage: :scenario_header, line: scenario_header_line(@scenario) }
+        @fresh_scenario_start = true
+
+        @stage = STAGES.first
+        loop do
+          @stage = STAGES[STAGES.index(@stage) + 1]
+          @field = field_for(@stage)
+          break unless @field.nil?
+        end
+        nil
+      rescue RequestFailed, UnsupportedCarrier => e
+        fail_with(e).last
+      end
+
+      def advance_to_confirm
+        @stage = :confirm
+        @field = field_for(:confirm)
+        nil
+      end
+
+      def scenario_header_line(number)
+        "\n#{Theme.title("Scenario #{number}")}"
+      end
+
+      # Commits the just-confirmed scenario's specs (today's build_specs,
+      # unchanged) to the queue and clears @answers so the next pass through
+      # the wizard, or #start_fetch, starts from a blank slate. Also grouped
+      # under @queued_scenarios, one entry per wizard pass, so the confirm
+      # recap can show each scenario as its own block rather than one flat
+      # list of specs.
+      def confirm_or_queue
+        specs = build_specs
+        @queued_specs.concat(specs)
+        @queued_scenarios << specs
+        @log << { stage: :add_another, line: queued_summary_line(specs) }
+        @answers = {}
+      end
+
+      def queued_summary_line(specs)
+        "  #{Theme.ok(Theme::TICK)} queued: #{Theme.bold(specs.first.carrier)} — #{specs.sum(&:call_count)} calls"
+      end
+
       def forget_from(stage)
         dropped = STAGES[STAGES.index(stage)..]
         dropped.each { |name| @answers.delete(name) }
@@ -184,22 +271,40 @@ module RateCard
         when :rural            then rural_field
         when :rural_surcharges then rural_surcharges_field
         when :services         then services_field
+        when :country          then country_field
+        when :gls_origin       then gls_origin_field
         when :zones        then zones_field
         when :unit         then unit_field
         when :weights      then weights_field
         when :package_type then package_type_field
         when :rate_keys    then rate_keys_field
+        when :add_another  then add_another_field
         when :confirm      then confirm_field
         end
       end
 
       # --------------------------------------------------------------- fields
 
+      # Reached as soon as every field for the current scenario is filled in.
+      # Yes clears @answers and jumps back to the top of the wizard for a
+      # fresh scenario; No moves on to the confirm screen for the whole queue.
+      def add_another_field
+        Fields::Select.new(
+          label: 'Add another scenario?',
+          choices: [['Yes, add another', :yes],
+                    ["No, continue to run #{@queued_specs.length + 1} scenario(s)", :no]],
+          selected: 0
+        )
+      end
+
       # The last gate before production is touched. It opens on Back, not on
       # Run: the field before it is also confirmed with enter, so a held-down
       # return key must not be able to start 128 production calls by itself.
+      # The label names the whole queue once there is more than one scenario
+      # in it, so "Run" is never ambiguous about how many cards it fires off.
       def confirm_field
-        Fields::Select.new(label: 'Run this rate card?',
+        label = @queued_scenarios.length > 1 ? "Run all #{@queued_scenarios.length} scenarios?" : 'Run this rate card?'
+        Fields::Select.new(label: label,
                            choices: [['Run', :run], ['Back', :back]], selected: 1)
       end
 
@@ -210,7 +315,7 @@ module RateCard
       def rate_mode_field
         return nil unless @services.any? { |service| service.carrier == 'USPS' }
 
-        choices = [['Weight', :weight], ['Cubic dimensions', :cubic]]
+        choices = [['Weight', :weight], ['Cubic', :cubic]]
         Fields::Select.new(label: 'Rate by', choices: choices,
                            selected: choices.index { |_, mode| mode == @answers[:rate_mode] } || 0)
       end
@@ -229,7 +334,9 @@ module RateCard
       def selectable_carriers
         carriers = Service.group_by_carrier(@services)
                                  .keys
-                                 .select { |carrier| Constants::Addresses.supported?(carrier) }
+                                 .select do |carrier|
+                                   Constants::Addresses.supported?(carrier) || Constants::Carriers.live_chart?(carrier)
+                                 end
         return carriers & ['USPS'] if @answers[:rate_mode] == :cubic
 
         carriers
@@ -252,8 +359,8 @@ module RateCard
       def rural_field
         return nil unless Constants::Carriers.rural_aware?(carrier)
 
-        choices = [['Normal', false], ['Rural (DAS)', true]]
-        Fields::Select.new(label: 'Rural / DAS', choices: choices,
+        choices = [['Standard', false], ['Rural/DAS', true]]
+        Fields::Select.new(label: 'Address Type', choices: choices,
                            selected: choices.index { |_, v| v == @answers[:rural] } || 0)
       end
 
@@ -274,10 +381,23 @@ module RateCard
         )
       end
 
+      # Only offered for international-aware carriers (USPS today, via
+      # USPS_CANADA_ORIGINS/USPS_CANADA_DESTINATION), and dropped whenever
+      # rural mode is on - USPS rural DAS is its own fixed domestic chart,
+      # not something international mode should combine with.
+      def country_field
+        return nil unless Constants::Carriers.international_aware?(carrier)
+        return nil if @answers[:rural]
+
+        choices = [['Domestic', nil], ['Canada', 'CA']]
+        Fields::Select.new(label: 'Destination', choices: choices,
+                           selected: choices.index { |_, v| v == @answers[:country] } || 0)
+      end
+
       def zones_field
         return nil if ups_rural?
 
-        available = usps_rural? ? Constants::Addresses::USPS_RURAL_DAS.keys.sort : Constants::Addresses.available_zones(carrier)
+        available = live_zones_for(carrier)
         full = "#{available.first}-#{available.last}"
         answered = @answers[:zones]
 
@@ -301,6 +421,64 @@ module RateCard
         carrier == 'UPS' && @answers[:rural] == true
       end
 
+      # Only asked for GLS: a fixed-origin carrier whose live zone chart is
+      # computed from the shipment's origin postal code rather than an
+      # account-configured hub, same reasoning as USPS/UPS/FedEx's shipment
+      # origin — but that origin only feeds fetch_zone_addresses' lookup, it
+      # is not itself a shipment field.
+      def gls_origin_field
+        return nil unless carrier == 'GLS'
+
+        Fields::Text.new(
+          label: 'GLS origin postal code',
+          default: @answers[:gls_origin] || Constants::Addresses::ORIGIN[:postal_code],
+          hint: 'GLS zone is computed from this origin, not your account',
+          parse: lambda { |raw|
+            raise ArgumentError, 'enter a postal code' if raw.strip.empty?
+
+            raw.strip
+          }
+        )
+      end
+
+      def live_zones_for(carrier)
+        return Constants::Addresses::USPS_CANADA_ORIGINS.keys.sort if carrier == 'USPS' && @answers[:country] == 'CA'
+        return Constants::Addresses.available_zones(carrier) unless Constants::Carriers.live_chart?(carrier)
+
+        live_chart(carrier).keys.sort
+      end
+
+      # Memoized per (carrier, run) — the endpoint gets hit once even though
+      # zones_field, and later address_for per selected zone, both need the chart.
+      def live_chart(carrier)
+        @live_charts ||= {}
+        @live_charts[carrier] ||= fetch_live_chart(carrier)
+      end
+
+      def fetch_live_chart(carrier)
+        service = @services.find { |s| s.carrier == carrier }
+        raise UnsupportedCarrier, "no service_id found for #{carrier}" unless service
+
+        client = @client_factory.call(@token)
+        body = client.fetch_zone_addresses(service.id, from_postal_code: gls_origin_for(carrier))
+        chart = (body['zones'] || {}).transform_keys(&:to_i)
+                                      .transform_values { |address| symbolize(address) }
+        if chart.empty?
+          raise UnsupportedCarrier,
+                "eHub found no real address for any zone for #{carrier} on this account yet"
+        end
+
+        chart
+      end
+
+      def gls_origin_for(carrier)
+        carrier == 'GLS' ? (@answers[:gls_origin] || Constants::Addresses::ORIGIN[:postal_code]) : nil
+      end
+
+      def symbolize(hash)
+        hash.to_h { |k, v| [k.to_sym, v] }
+      end
+
       # Weight is fixed per cubic tier, so asking for a display unit is
       # meaningless in cubic mode — decided as :oz (unused) and skipped.
       def unit_field
@@ -400,7 +578,9 @@ module RateCard
       end
 
       def with_supported_carrier(services)
-        services.select { |service| Constants::Addresses.supported?(service.carrier) }
+        services.select do |service|
+          Constants::Addresses.supported?(service.carrier) || Constants::Carriers.live_chart?(service.carrier)
+        end
       end
 
       def unsupported_message(services)
@@ -425,7 +605,7 @@ module RateCard
       # grid:} in #results before the next pass starts. Every other carrier
       # and mode has exactly one pass, same as before this existed.
       def start_fetch
-        @pending_specs = build_specs
+        @pending_specs = @queued_specs.dup
         # Before the first call, so a bad path is not discovered after 128 of them.
         begin
           @pending_specs.each { |spec| CsvWriter.ensure_writable!(spec.output_base) }
@@ -522,8 +702,10 @@ module RateCard
           cubic_tiers: cubic ? @answers[:weights] : [],
           rate_mode: @answers[:rate_mode] || :weight,
           rural: @answers[:rural],
+          country: @answers[:country],
           package_type: @answers[:package_type],
           rate_keys: @answers[:rate_keys],
+          zone_chart: Constants::Carriers.live_chart?(carrier) ? live_chart(carrier) : nil,
           output_base: @output_base,
           show_table: true,
           started_at: Time.now
@@ -545,42 +727,78 @@ module RateCard
         end
       end
 
-      # Everything the run will do, gathered in one block. The answers are also
-      # in the transcript above, but they arrived one at a time over eight
-      # screens; this is the only place they can be read against each other.
-      #
-      # Built from real RunSpecs (build_specs) rather than raw @answers, so a
-      # UPS rural run with both surcharge types checked recaps as the two
-      # separate cards it will actually produce, one line each.
+      # Loading and fetching have no field to ask a keybinding of — the only
+      # live key on either screen is Ctrl-C — so they fall back to that.
+      QUIT_BINDING = [Bubbles::Key.binding(keys: ['ctrl+c'], help: ['ctrl+c', 'quit'])].freeze
+
+      def footer_text
+        @field&.keymap_hint || Theme.help_view(QUIT_BINDING)
+      end
+
+      # Everything every queued scenario will do, gathered in one block. By
+      # the time confirm is reached, add_another has already queued the
+      # current scenario and cleared @answers (#confirm_or_queue), so this
+      # reads from @queued_scenarios/@queued_specs rather than @answers -
+      # unlike the single-scenario recap this replaces, it has to summarize
+      # everything already queued, not just what was just answered.
       def recap_view
-        specs = build_specs
-        carrier_line = "  #{Theme.bold(carrier)}#{rural_recap} · #{@answers[:services].map(&:name).join(', ')}"
+        scenarios = @queued_scenarios.map { |specs| scenario_recap_block(specs) }.join("\n\n")
+        Lipgloss.join_vertical(Lipgloss::LEFT, scenarios, '', summary_block)
+      end
+
+      # The production warning and call total, pulled into their own box so
+      # the one fact that actually gates the run — this is about to hit
+      # production N times — reads as a distinct decision, not another line
+      # buried under the scenario details on its left.
+      def summary_block
+        calls = @queued_specs.sum(&:call_count)
+        cards = @queued_specs.length > 1 ? "#{@queued_specs.length} separate cards" : '1 card'
+        lines = [
+          Theme.bold('Summary'),
+          '',
+          "#{Theme.bold(calls.to_s)} calls",
+          cards,
+          '',
+          Theme.danger("#{Theme::ALERT} production")
+        ]
+        Lipgloss::Style.new
+                        .border(Lipgloss::ROUNDED_BORDER)
+                        .border_foreground(Theme::DANGER)
+                        .padding(0, 2)
+                        .render(lines.join("\n"))
+      end
+
+      # One block per queued wizard pass. Almost always one spec; more than
+      # one only for UPS rural mode with several surcharge types checked, in
+      # which case every spec in the block shares carrier/services/package/
+      # rate_keys and differs only in zones (see #build_specs).
+      def scenario_recap_block(specs)
+        first = specs.first
         [
-          carrier_line,
-          *specs.map { |spec| "  zones #{spec.zone_summary} · #{rows_recap} · #{@answers[:package_type]}" },
-          "  columns: #{@answers[:rate_keys].map { |k| RunSpec::RATE_KEY_LABELS.fetch(k) }.join(', ')}",
-          "  #{Theme.bold(specs.sum(&:call_count).to_s)} rate calls against #{Theme.danger('production')}" \
-            "#{specs.length > 1 ? " (#{specs.length} separate cards)" : ''}"
+          "  #{Theme.bold(first.carrier)}#{spec_rural_recap(first)} · #{first.services.map(&:name).join(', ')}",
+          *specs.map { |spec| "  zones #{spec.zone_summary} · #{spec_rows_recap(spec)} · #{first.package_type}" },
+          "  columns: #{first.rate_keys.map { |k| RunSpec::RATE_KEY_LABELS.fetch(k) }.join(', ')}"
         ].join("\n")
       end
 
-      def rural_recap
-        return '' unless @answers[:rural]
+      def spec_rural_recap(spec)
+        return '' unless spec.rural
 
-        " (#{rural_label(@answers[:rural])})"
+        " (#{rural_label(spec.rural)})"
       end
 
-      def rows_recap
-        if @answers[:rate_mode] == :cubic
-          "cubic tiers #{RunSpec.compact_range(@answers[:weights])}"
+      def spec_rows_recap(spec)
+        if spec.rate_mode == :cubic
+          "cubic tiers #{RunSpec.compact_range(spec.cubic_tiers)}"
         else
-          "weights #{RunSpec.compact_range(@answers[:weights])} #{@answers[:unit]}"
+          "weights #{RunSpec.compact_range(spec.weights)} #{spec.weight_unit}"
         end
       end
 
       def fetch_view
         total = @spec.call_count
         percent = total.zero? ? 0.0 : @completed.to_f / total
+        @progress.full_color = progress_color(percent)
         title = @total_passes > 1 ? "fetching rates (pass #{@pass_index}/#{@total_passes})" : 'fetching rates'
         line = "  #{@progress.view_as(percent)}  #{@completed}/#{total}"
         line += "  #{Theme.warning("#{Theme::ALERT} #{@failed} failed")}" if @failed.positive?
@@ -589,6 +807,16 @@ module RateCard
         view
       end
 
+      # Warning early, accent through the middle stretch, ok once the run is
+      # nearly done — so a glance at the bar's colour alone tells you roughly
+      # how far along it is, without reading the fraction next to it.
+      def progress_color(percent)
+        return Theme::OK if percent >= 0.75
+        return Theme::ACCENT if percent >= 0.34
+
+        Theme::WARNING
+      end
+
       # Only drawn once a failure has happened: a spark line of zeroes for a
       # clean run would be noise, not signal. It stays once shown even if
       # later ticks are all clean — the failure already happened.
@@ -602,7 +830,8 @@ module RateCard
       # what is already visible rather than the first chance to check it.
       def answered_line(stage, value)
         label = { rate_mode: 'rate by', carrier: 'carrier', rural: 'rural / DAS',
-                  rural_surcharges: 'surcharge types', services: 'services', zones: 'zones',
+                  rural_surcharges: 'surcharge types', services: 'services',
+                  country: 'destination', gls_origin: 'GLS origin', zones: 'zones',
                   unit: 'unit', weights: 'weights', package_type: 'package',
                   rate_keys: 'columns' }[stage]
         label = 'cubic tiers' if stage == :weights && @answers[:rate_mode] == :cubic
@@ -618,6 +847,7 @@ module RateCard
         when :weights           then RunSpec.compact_range(value)
         when :rural             then rural_label(value)
         when :rural_surcharges  then value.map { |v| v.to_s.upcase }.join(', ')
+        when :country           then value || 'Domestic'
         when :rate_keys         then value.map { |k| RunSpec::RATE_KEY_LABELS.fetch(k) }.join(', ')
         else value.to_s
         end

data/lib/rate_card/tui/fields/multi_select.rb

@@ -15,6 +15,13 @@ module RateCard
       class MultiSelect
         WINDOW = 8
 
+        HELP_BINDINGS = [
+          Bubbles::Key.binding(keys: [' '], help: %w[space toggle]),
+          Bubbles::Key.binding(keys: ['a'], help: %w[a all]),
+          Bubbles::Key.binding(keys: ['enter'], help: ['enter', 'confirm']),
+          Bubbles::Key.binding(keys: ['esc'], help: ['esc', 'back'])
+        ].freeze
+
         attr_reader :label, :error
 
         # choices: Array<[display String, value]>
@@ -30,6 +37,13 @@ module RateCard
 
         def done? = @done
 
+        # Pulled out of #view so App can draw it in a persistent footer bar
+        # instead of repeating it under every single field.
+        def keymap_hint
+          counter = Theme.muted("#{@checked.length}/#{@choices.length} selected")
+          "#{Theme.help_view(HELP_BINDINGS)}  #{counter}"
+        end
+
         def value
           @choices.each_with_index
                   .select { |_choice, index| @checked.include?(index) }
@@ -56,7 +70,6 @@ module RateCard
         def view
           lines = ["#{Theme.accent(Theme::CURSOR)} #{Theme.bold(@label)}"]
           window.each { |index| lines << choice_line(index) }
-          lines << "  #{Theme.muted(hint)}"
           lines << "  #{Theme.danger(Theme::CROSS)} #{Theme.danger(@error)}" if @error
           lines.join("\n")
         end
@@ -71,11 +84,6 @@ module RateCard
           "  #{pointer} #{box} #{text}"
         end
 
-        def hint
-          counter = "#{@checked.length}/#{@choices.length} selected"
-          "space toggle · a all · enter confirm · esc back · #{counter}"
-        end
-
         # The spacebar arrives as KEY_SPACE from some terminals and as a plain
         # ' ' rune from others; KeyMessage#space? only recognises the first, so
         # relying on it alone makes the toggle key dead on half of them.

data/lib/rate_card/tui/fields/select.rb

@@ -10,6 +10,12 @@ module RateCard
       class Select
         WINDOW = 8
 
+        HELP_BINDINGS = [
+          Bubbles::Key.binding(keys: %w[up down k j], help: ['↑↓', 'move']),
+          Bubbles::Key.binding(keys: ['enter'], help: ['enter', 'confirm']),
+          Bubbles::Key.binding(keys: ['esc'], help: ['esc', 'back'])
+        ].freeze
+
         attr_reader :label
 
         # choices: Array<[display String, value]>
@@ -26,6 +32,15 @@ module RateCard
         def done? = @chosen
         def value = @value
 
+        # Pulled out of #view so App can draw it in a persistent footer bar
+        # instead of repeating it under every single field.
+        def keymap_hint
+          hint = Theme.help_view(HELP_BINDINGS)
+          return hint if @choices.length <= WINDOW
+
+          "#{hint}  #{Theme.muted("#{@cursor + 1}/#{@choices.length}")}"
+        end
+
         def update(message)
           return nil unless message.is_a?(Bubbletea::KeyMessage)
 
@@ -50,7 +65,6 @@ module RateCard
                        "    #{display}"
                      end
           end
-          lines << "  #{Theme.muted(hint)}"
           lines.join("\n")
         end
 
@@ -68,12 +82,6 @@ module RateCard
           start = [[@cursor - (WINDOW / 2), 0].max, @choices.length - WINDOW].min
           (start...(start + WINDOW))
         end
-
-        def hint
-          parts = ['↑↓ move', 'enter confirm', 'esc back']
-          parts << "#{@cursor + 1}/#{@choices.length}" if @choices.length > WINDOW
-          parts.join(' · ')
-        end
       end
     end
   end

data/lib/rate_card/tui/fields/text.rb

@@ -11,6 +11,11 @@ module RateCard
       # mistyped zone list or a mangled paste of a JWT costs a keystroke rather
       # than the run — the same guarantee the tty-prompt wizard made.
       class Text
+        HELP_BINDINGS = [
+          Bubbles::Key.binding(keys: ['enter'], help: ['enter', 'confirm']),
+          Bubbles::Key.binding(keys: ['esc'], help: ['esc', 'back'])
+        ].freeze
+
         attr_reader :label, :error
 
         # parse: String -> value, raising ArgumentError with a message to show.
@@ -35,6 +40,10 @@ module RateCard
         def done? = !@value.nil?
         def value = @value
 
+        # Pulled out of #view so App can draw it in a persistent footer bar
+        # instead of repeating it under every single field.
+        def keymap_hint = Theme.help_view(HELP_BINDINGS)
+
         def update(message)
           if message.is_a?(Bubbletea::KeyMessage) && message.enter?
             submit
@@ -47,7 +56,7 @@ module RateCard
 
         def view
           lines = ["#{Theme.accent(Theme::CURSOR)} #{Theme.bold(@label)} #{@input.view}"]
-          lines << "  #{Theme.muted("#{@hint} · esc back")}" if @hint
+          lines << "  #{Theme.muted(@hint)}" if @hint
           lines << "  #{Theme.danger(Theme::CROSS)} #{Theme.danger(@error)}" if @error
           lines.join("\n")
         end

data/lib/rate_card/tui/theme.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'lipgloss'
+require 'bubbles'
 
 module RateCard
   module TUI
@@ -9,11 +10,12 @@ module RateCard
     # Pastel/TTY pairing this replaced, where only Pastel was gated and the
     # spinner and bar leaked escapes into a pipe.
     module Theme
-      ACCENT  = Lipgloss::AdaptiveColor.new(dark: '#00D3FF', light: '#0072B5')
-      OK      = Lipgloss::AdaptiveColor.new(dark: '#2ECC71', light: '#1E8449')
-      WARNING = Lipgloss::AdaptiveColor.new(dark: '#F5A623', light: '#B7791F')
-      DANGER  = Lipgloss::AdaptiveColor.new(dark: '#FF5C5C', light: '#C0392B')
-      MUTED   = Lipgloss::AdaptiveColor.new(dark: '#8A8A8A', light: '#6B6B6B')
+      ACCENT    = Lipgloss::AdaptiveColor.new(dark: '#00D3FF', light: '#0072B5')
+      SECONDARY = Lipgloss::AdaptiveColor.new(dark: '#B388FF', light: '#6A3FBF')
+      OK        = Lipgloss::AdaptiveColor.new(dark: '#2ECC71', light: '#1E8449')
+      WARNING   = Lipgloss::AdaptiveColor.new(dark: '#F5A623', light: '#B7791F')
+      DANGER    = Lipgloss::AdaptiveColor.new(dark: '#FF5C5C', light: '#C0392B')
+      MUTED     = Lipgloss::AdaptiveColor.new(dark: '#8A8A8A', light: '#6B6B6B')
 
       CURSOR      = '❯'
       CHECKED     = '◉'
@@ -23,6 +25,16 @@ module RateCard
       BULLET      = '▸'
       ALERT       = '⚠'
 
+      # The canonical Charm keybinding legend (bubbles/help) instead of a
+      # hand-built "a · b · c" string — it colours the key apart from its
+      # description and truncates to width on its own rather than wrapping
+      # mid-word in a narrow terminal.
+      HELP = Bubbles::Help.new.tap do |help|
+        help.key_style = Lipgloss::Style.new.foreground(ACCENT).bold(true)
+        help.desc_style = Lipgloss::Style.new.foreground(MUTED)
+        help.separator_style = Lipgloss::Style.new.foreground(MUTED)
+      end
+
       module_function
 
       def style = Lipgloss::Style.new
@@ -34,8 +46,11 @@ module RateCard
       def muted(text)   = style.foreground(MUTED).render(text)
       def bold(text)    = style.bold(true).render(text)
 
+      # Section/scenario headings use SECONDARY rather than ACCENT so they
+      # read as structure, not as something the cursor is sitting on — ACCENT
+      # is reserved for the interactive element the user's eye should track.
       def title(text)
-        style.bold(true).foreground(ACCENT).render(text)
+        style.bold(true).foreground(SECONDARY).render(text)
       end
 
       # The run targets production and cannot be pointed elsewhere, so the
@@ -46,6 +61,35 @@ module RateCard
              .padding(0, 1)
              .render("#{bold('eHub Rate Card Builder')}\n#{danger('●')} production · api.ehub.com")
       end
+
+      # Frames the live wizard body (transcript + current field) as one card
+      # instead of loose scrolling text, so every stage reads as part of the
+      # same surface rather than a fresh block of terminal output.
+      def panel(content)
+        style.border(Lipgloss::ROUNDED_BORDER)
+             .border_foreground(MUTED)
+             .padding(1, 2)
+             .render(content)
+      end
+
+      # A quiet rule between the answered-questions transcript and whatever
+      # is being asked right now, so the eye has a fixed place to land on
+      # "what's next" without re-reading everything above it.
+      def divider(width = 44)
+        muted('─' * width)
+      end
+
+      # Renders a row of Bubbles::Key::Binding as the short help legend.
+      def help_view(bindings)
+        HELP.short_help_view(bindings)
+      end
+
+      # Drawn once, below the panel, instead of every field repeating its own
+      # keybinding line — the keys on offer rarely change shape from field to
+      # field, so giving them a fixed home lets the eye stop re-reading them.
+      def footer(text)
+        "  #{text}"
+      end
     end
   end
 end

data/lib/rate_card/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RateCard
-  VERSION = '0.1.5'
+  VERSION = '0.1.6'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rate-card
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.6
 platform: ruby
 authors:
 - eHub
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-02 00:00:00.000000000 Z
+date: 2026-09-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64