vehicles 0.9.0 → 0.9.2

data/README.md

@@ -2,10 +2,12 @@
 
 [![Gem Version](https://badge.fury.io/rb/vehicles.svg)](https://badge.fury.io/rb/vehicles) [![Build Status](https://github.com/vehiclesdb/vehicles/workflows/Tests/badge.svg)](https://github.com/vehiclesdb/vehicles/actions)
 
+> **Get your free key, the integration guide and the credit snippet at [vehiclesdb.com](https://vehiclesdb.com/users/sign_up?for=app_saas&cta=readme_vehicles)**
+
 > [!TIP]
 > **🚀 Ship your next Rails app 10x faster!** I've built **[RailsFast](https://railsfast.com/?ref=vehicles)**, a production-ready Rails boilerplate template that comes with everything you need to launch a software business in days, not weeks. Go [check it out](https://railsfast.com/?ref=vehicles)!
 
-`vehicles` gives your Rails app a clean, curated list of vehicle makes and models — **~15k models across 850+ makes: cars, motorcycles, mopeds, vans, trucks and buses**, reconciled from official registers of 15 countries — ready for dropdowns, search, and validation. No API keys, no database table, no migration — it works **fully offline** the second you `bundle install`, because the data ships inside the gem. (Optionally, it can [refresh](#staying-current-optional) the data without a gem upgrade.)
+`vehicles` gives your Rails app a clean, curated list of vehicle makes and models — **every make and model in the VehiclesDB open dataset: cars, motorcycles, mopeds, vans, trucks and buses**, reconciled from the official vehicle registers of every country the dataset covers (current counts: [vehiclesdb.com/makes](https://vehiclesdb.com/makes), or `manifest.json` in the data repo) — ready for dropdowns, search, and validation. No API keys, no database table, no migration — it works **fully offline** the second you `bundle install`, because the data ships inside the gem. (Optionally, it can [refresh](#staying-current-optional) the data without a gem upgrade.)
 
 ✨ Perfect for marketplaces, carpooling & rideshare apps, fleet tools, parking & EV-charging apps, insurance and booking forms — anywhere a user has to pick their vehicle.
 
@@ -62,7 +64,7 @@ Two methods cover 90% of what you need:
 
 ```ruby
 Vehicles.makes
-# => ["Abarth", "Acura", "Alfa Romeo", ...]   (alphabetical, 850+ makes)
+# => ["Abarth", "Acura", "Alfa Romeo", ...]   (alphabetical, every make)
 
 Vehicles.models("Toyota")
 # => ["Yaris", "Corolla", "Aygo", "RAV4", "C-HR", "Prius", ...]
@@ -155,7 +157,24 @@ It tries, strongest first, and stops at the first rung that answers:
 - **No guessing from prefixes.** "C3 Aircr" is not "C3" (it's the C3 Aircross); only a curated form can say so.
 - **Ids stay exact.** Slug-, id- and path-shaped input (`"golf-gti"`, `"car/volkswagen/golf"`, symbols) only takes the exact rungs.
 
-`make.model(...)` and the `vehicle_model` validator stay strict — a form or a typo is not a valid model name to store. `kind:` works as in `model` (the car is preferred without it).
+`make.model(...)` and the `vehicle_model` validator stay strict — a form or a typo is not a valid model name to store.
+
+**Safe to write back without asking?** `confident?` is the recommended auto-apply threshold: an answer (not ambiguous) from a curated rung — the id, a former id, the name, a published alias, a curated form, or one of those after `:cleaned`. Never `:fuzzy`: a typo correction is a guess to *show* the user ("did you mean Touareg?"), not to store silently.
+
+```ruby
+m = Vehicles.match_model(row.make, row.model, kind: :car)
+row.update!(make: m.model.make, model: m.model.name, vehiclesdb_id: m.model.id) if m&.confident?
+```
+
+**Kinds.** One nameplate can be several records (Iveco's Daily is a van, a truck and a bus). That is not ambiguity: without a kind, every VehiclesDB surface (gem, API, SDKs, widget) applies the same rule — the record with the lowest `mass_decile`, then van → car → bus → truck → moped → motorcycle, then the id — so "Iveco Daily" is the van everywhere (`Vehicles::KindRule`; until 0.9.1 the gem preferred the car). Pass `kind:` to choose one, or `kinds:` to allow only some: a record outside `kinds:` never answers, on any rung, ids included.
+
+```ruby
+Vehicles.model("Iveco", "Daily")                     # => the van
+Vehicles.model("Iveco", "Daily", kind: :bus)          # => the bus
+Vehicles.match_model("Iveco", "Daily", kinds: [:car]) # => nil (there is no car Daily)
+Vehicles.identify("bus/iveco/daily", kinds: [:car])   # => nil (an id outside the scope too)
+Vehicles.identify("bus/iveco/daily", kind: :car).model # => the bus: `kind:` never overrides an explicit id
+```
 
 One free-text string instead of a pair? `identify` splits off the make (the longest leading run that is a make) and runs the same ladder. It also takes canonical ids (`:exact`, 1.0), ids a record has replaced (`:former_id`, 0.98), and a whole string that is exactly one model's published alias (`:alias`, 0.90). Apart from those, nothing resolves without a make:
 
@@ -180,13 +199,14 @@ Every `Vehicles::Model` reads like English and serializes cleanly:
 
 ```ruby
 car = Vehicles.find("seat leon")
+car.id          # => "car/seat/leon"   ← the canonical id: store this
 car.make        # => "SEAT"
-car.name        # => "Leon"
-car.full_name   # => "SEAT Leon"
+car.name        # => "León"
+car.full_name   # => "SEAT León"
 car.slug        # => "seat-leon"
-car.to_h        # => { make: "SEAT", model: "Leon", slug: "seat-leon",
+car.to_h        # => { id: "car/seat/leon", make: "SEAT", model: "León", slug: "seat-leon",
                 #      kind: :car, body_type: :hatchback, global_decile: 2,
-                #      availability: ["es", "fi", "gb", ...] }
+                #      availability: ["es", "fi", "gb", ...], ... }
 ```
 
 ## Kinds & body types
@@ -222,6 +242,15 @@ Vehicles.makes(kind: :motorcycle)             # => makes that build bikes
 Vehicles.search("golf").select(&:hatchback?)
 ```
 
+Labels for a kind or body type `<select>` ship in English and Spanish (you store the symbol):
+
+```ruby
+Vehicles.kind_options(locale: :es)          # => [["Autobús", "bus"], ["Camión", "truck"], ["Ciclomotor", "moped"], ["Coche", "car"], ...]
+Vehicles.kind_label(:van, locale: :es)      # => "Furgoneta"
+Vehicles.body_type_label(:wagon, locale: :es) # => "Familiar"
+Vehicles.body_type_options(locale: :es)     # => [["Compacto", "hatchback"], ["Berlina", "sedan"], ...]
+```
+
 > [!NOTE]
 > `body_type` is honest: cars always carry one; other kinds return `nil` until
 > an honest vocabulary exists for them (a truck is not a "hatchback"). The
@@ -262,6 +291,8 @@ imports count, because they're real vehicles on real roads.
 
 ## MCP server for AI agents
 
+> **Get your free key, the integration guide and the credit snippet at [vehiclesdb.com](https://vehiclesdb.com/users/sign_up?for=ai_app&cta=readme_vehicles_mcp)**
+
 The gem ships `vehicles-mcp` — a read-only [MCP](https://modelcontextprotocol.io)
 server over the bundled dataset, so your agents ground themselves in real
 vehicle data instead of hallucinating nameplates. No network, no keys:
@@ -290,11 +321,16 @@ Vehicles.color("navy")          # forgiving: synonyms, case, diacritics
 Vehicles.color("navy").slug     # => "blue"   ← the stable value you store
 Vehicles.color("navy").hex      # => "#27408B" (representative swatch)
 
-Vehicles.color_options          # => [["White", "white"], ["Black", "black"], ...]
+Vehicles.color_options               # => [["White", "white"], ["Black", "black"], ...]
+Vehicles.color_options(locale: :es)  # => [["Blanco", "white"], ["Negro", "black"], ["Gris", "grey"], ...]
+Vehicles.color("red").label(:es)     # => "Rojo"
+Vehicles.color("Marrón").slug        # => "brown"  — Spanish input resolves too ("rojo", "plateada", "granate")
+Vehicles.colors(locale: :es).first   # => #<Vehicles::Color white "Blanco" #F4F4F4>
 ```
 
-Names are English — store the **slug** and localize the label in your app (the
-slug is also what maps to image color-variants down the line).
+Store the **slug** (it is also what maps to the image color variants); labels
+ship in English and Spanish (`locale: "es-MX"` folds to `:es`; other locales
+fall back to English).
 
 ## Rails dropdowns
 
@@ -310,17 +346,25 @@ Vehicles.model_options("audi")
 
 ### Dependent make → model picker
 
-The whole dataset is small, so the simplest, snappiest way to wire a dependent
-picker is **client-side**: embed [`Vehicles.catalog`](#the-full-ruby-api) once and
-switch the model list with no request at all — **no route, no controller, no
-fetch.**
+Scope the picker to what your app serves and embed
+[`Vehicles.catalog`](#the-full-ruby-api) once: the model list switches with no
+request at all — **no route, no controller, no fetch.** For a one-country app,
+`country:` keeps it to the models with official evidence there, in that
+country's own popularity order (Spain's cars: ~140 makes, ~1,300 models, ~14 KB
+of JSON; the whole worldwide car catalog is ~63 KB):
+
+```ruby
+# app/helpers/vehicles_helper.rb
+PICKER = { kind: :car, country: :es }.freeze
+def vehicle_catalog = Vehicles.catalog(**PICKER)
+```
 
 ```erb
 <div data-controller="vehicle-picker"
-     data-vehicle-picker-catalog-value="<%= Vehicles.catalog.to_json %>">
-  <%= form.select :make,  Vehicles.makes,             { include_blank: "Make" },
+     data-vehicle-picker-catalog-value="<%= vehicle_catalog.to_json %>">
+  <%= form.select :make,  vehicle_catalog.keys,                    { include_blank: "Make" },
         data: { vehicle_picker_target: "make", action: "change->vehicle-picker#makeChanged" } %>
-  <%= form.select :model, Vehicles.models(@car&.make), { include_blank: "Model" },
+  <%= form.select :model, vehicle_catalog.fetch(@car&.make.to_s, []), { include_blank: "Model" },
         data: { vehicle_picker_target: "model" } %>
 </div>
 ```
@@ -346,7 +390,74 @@ export default class extends Controller {
 
 That's the whole picker — the gem ships the data, you keep your markup and ~12
 lines of JS. (Storing slugs instead of names? Swap the selects for
-`make_options` / `model_options` and key the catalog by slug.)
+`make_options` / `model_options` and key the catalog by slug.) The same scope
+also works on every list helper: `Vehicles.makes(kind: :car, country: :es)`,
+`Vehicles.models("SEAT", kind: :car, country: :es)`, `make_options` /
+`model_options(country:)`. Country evidence means *presence* in official data,
+not an exhaustive list of what is legal there — keep an "Other" option.
+
+### The make-model-dropdown widget, fed by your server
+
+The [make-model-dropdown](https://github.com/vehiclesdb/make-model-dropdown)
+widget (0.4.1+) does the picker for you: search, kept stored values, the
+canonical id. `Vehicles.dataset_slice` takes the same scope as `catalog` and
+returns the records behind the names, in the shape of the published
+`dist/vehicles.json`, so the widget resolves stored values (aliases, curated
+forms, former ids) and writes ids exactly as it would with the whole release.
+Embed it and the page makes **no request** for vehicle data — no CDN, no API
+key — and shows the release your server runs:
+
+```ruby
+# app/helpers/vehicles_helper.rb
+# Built once per data release (Spain's cars: ~360 KB of JSON, ~57 KB gzipped).
+def vehicles_dataset_json(**scope)
+  Rails.cache.fetch(["vehicles/dataset_slice", Vehicles.data_version, scope]) do
+    Vehicles.dataset_slice(**scope).to_json
+  end
+end
+```
+
+```erb
+<script type="application/json" id="vehicles-data"><%= json_escape(vehicles_dataset_json(kind: :car, country: :es)).html_safe %></script>
+
+<div data-controller="vehicle-picker">
+  <%= form.select :make,  [@car.make].compact,  {}, data: { vehicle_picker_target: "make" } %>
+  <%= form.select :model, [@car.model].compact, {}, data: { vehicle_picker_target: "model" } %>
+  <%= form.hidden_field :vehiclesdb_id, data: { vehicle_picker_target: "id" } %>
+</div>
+```
+
+```js
+// app/javascript/controllers/vehicle_picker_controller.js
+import { Controller } from "@hotwired/stimulus"
+import VehiclesDropdown from "make-model-dropdown"
+
+export default class extends Controller {
+  static targets = ["make", "model", "id"]
+
+  connect() {
+    const data = JSON.parse(document.getElementById("vehicles-data").textContent)
+    this.dropdown = VehiclesDropdown.attach({
+      data, kind: "car", country: "es", locale: "es", values: "name",
+      make: this.makeTarget, model: this.modelTarget, idInput: this.idTarget
+    })
+  }
+
+  disconnect() { this.dropdown.destroy() }
+}
+```
+
+Give the widget the same `kind`/`country` you sliced by. What the slice
+keeps: each make's `name`, `slug`, `kinds`, `aliases`, `former_slugs`; each
+model's `name`, `slug`, `kind`, `aliases`, `forms`, `former_ids`,
+`global_decile`, `mass_decile`, `availability`, `country_ranks` and
+`registration_years`, plus the release's `version`, `schema_version`,
+`license` and `attribution`. It leaves out `regions` and `body_type`, and with
+`country:` it keeps only that country in `availability` and `country_ranks`
+(every record in the slice is evidenced there; the other countries are most of
+the bytes). The ids are not stored: they are `kind/make-slug/model-slug`, as
+everywhere. The JS and Python SDKs read a slice too (dataset mode, when it is
+what they load as `dist/vehicles.json`).
 
 > [!TIP]
 > Prefer a server round-trip (huge/remote dataset, or you'd rather not embed it)?
@@ -373,9 +484,16 @@ Car.new(make: "Tesler",     model: "Model 3").valid?   # => false
 
 They're forgiving the same way the lookups are (aliases, case, slugs), and they never raise on blank/garbage input — they just add an error.
 
+Scope them like your picker, so a value the picker never offered (a truck, a model never seen in your market) fails too:
+
+```ruby
+validates :make,  vehicle_make:  { kind: :car, country: :es }
+validates :model, vehicle_model: { make: :make, kind: :car, country: :es }   # kinds: [:car, :van] also works
+```
+
 ### An "Other / not in the list" escape hatch
 
-Make/model dropdowns should never be a dead end — ~15k models is a lot, but
+Make/model dropdowns should never be a dead end — the full model list is a lot, but
 someone always shows up with the one car that isn't there. Turn on a first-class
 "Other" option and the pieces agree by construction: `include_other:` adds it to
 the picker, `allow_other:` lets it through validation.
@@ -424,17 +542,52 @@ specs/images) are *properties of that make+model* owned by the dataset — look
 them up via the gem, don't duplicate them per row (they'd just drift). So the
 schema is small and stable:
 
-| Column   | Type      | Store                                   | Example       |
-|----------|-----------|-----------------------------------------|---------------|
-| `make`   | `string`  | display name                            | `"Volkswagen"`|
-| `model`  | `string`  | display name                            | `"Golf"`      |
-| `year`   | `integer` | the year                                | `2022`        |
-| `color`  | `string`  | a canonical color **slug**              | `"blue"`      |
+| Column          | Type      | Store                                   | Example                 |
+|-----------------|-----------|-----------------------------------------|-------------------------|
+| `make`          | `string`  | display name                            | `"Volkswagen"`          |
+| `model`         | `string`  | display name                            | `"Golf"`                |
+| `vehiclesdb_id` | `string`  | the canonical **id** (`Model#id`), nullable | `"car/volkswagen/golf"` |
+| `year`          | `integer` | the year                                | `2022`                  |
+| `color`         | `string`  | a canonical color **slug**              | `"blue"`                |
 
-Everything else (`kind`, `body_type`, production years, images, …) is derived:
-`Vehicles.model(record.make, record.model)`. No `kind`/`body_type` columns, no
+Everything else (`kind`, `body_type`, images, …) is derived from the id:
+`Vehicles.by_id(record.vehiclesdb_id)`. No `kind`/`body_type` columns, no
 migration to add new metadata later — it lands in the dataset, not your schema.
 
+### Store the id
+
+Names are for people; the **id** (`"car/volkswagen/golf"` — kind/make/model) is
+what every VehiclesDB surface agrees on: the API, the JS/Python SDKs and the
+widget take the same string, and it survives dataset releases. When a release
+renames or merges a record, the new record lists the old id in `former_ids`, so a
+stored id never dead-ends:
+
+```ruby
+car = Vehicles.model(params[:make], params[:model], kind: :car)
+record.vehiclesdb_id = car&.id                      # nil for "Other" / unknown pairs
+
+Vehicles.by_id("car/volkswagen/golf")               # => #<Vehicles::Model "Volkswagen Golf">
+Vehicles.by_id(old_id)                              # => the record that replaced it (follow: true)
+Vehicles.by_id(old_id, follow: false)               # => nil
+Vehicles.live?(old_id)                              # => false
+Vehicles.successor(old_id)                          # => the id to store now ("car/…/…")
+```
+
+After each data refresh, migrate stored ids in one pass:
+
+```ruby
+Car.where.not(vehiclesdb_id: nil).find_each do |car|
+  now = Vehicles.successor(car.vehiclesdb_id)
+  next if now.nil? || now == car.vehiclesdb_id
+  model = Vehicles.by_id(now)
+  car.update!(vehiclesdb_id: now, make: model.make, model: model.name)
+end
+```
+
+Two records are equal when their ids are (`==`, `eql?`, `hash`): the van and the
+bus of one nameplate are different records. A make that is renamed or merged
+is followed too once the dataset publishes its `former_slugs`.
+
 **Store the display name.** The simplest, most readable thing to persist is the
 name itself (`"Volkswagen"`, `"Golf"`). Populate the selects with the plain
 **name lists**, where the option value *is* the name:
@@ -471,10 +624,17 @@ car&.suv?                                           # => false
 ```
 
 It reads what people actually type: case, accents and spacing don't matter
-(`"XCeed"` is Kia's `"X Ceed"`, `"A 5"` is `"A5"`), BMW's Spanish/Italian
+(`"X Ceed"` is Kia's `"XCeed"`, `"A 5"` is `"A5"`), BMW's Spanish/Italian
 `"Serie 3"` is the `"3 Series"`, and a name that exists as several kinds
-(Toyota's Land Cruiser: car, van, truck, bus) answers with the car unless you
-pass `kind:` — `Vehicles.model("Toyota", "Land Cruiser", kind: :bus)`.
+(Iveco's Daily: van, truck, bus) follows the [one kind rule](#matching-stored-make--model-pairs)
+unless you pass `kind:` — a car-only app passes `kind: :car` everywhere.
+
+**Year pickers.** `Model#registration_years` is a *hint* — `{ first:, last: }`, the first and last
+year the nameplate shows up in official registrations, when the dataset
+publishes it (nil until then) — good for ordering or pre-filling a year
+`<select>`, never a validation bound (imports and late registrations fall
+outside it legitimately). It is not production years: `Model#years` stays nil
+until VehiclesDB publishes those.
 
 **Only accept the kinds you support.** Filter every list/lookup by `kind:` so
 the picker only ever offers vehicles your app handles — and widening later (when
@@ -486,9 +646,9 @@ Vehicles.makes(kind: :car)                 # makes that build cars
 Vehicles.models("Toyota", kind: :car)      # ...their cars only
 ```
 
-No migration, no seed task, no API key — the data is bundled and read from
-memory. The whole integration is the markup above plus a 3-line endpoint for the
-dependent model list (see [Rails dropdowns](#rails-dropdowns)).
+No seed task, no API key — the data is bundled and read from memory. The
+whole integration is the markup above plus the embedded catalog (see
+[Rails dropdowns](#rails-dropdowns)).
 
 ## Country & region awareness
 
@@ -500,8 +660,8 @@ Vehicles.find("vw golf").available_in?(:nz)     # => true
 Vehicles.top_models(kind: :car, country: :es)   # country-scoped popularity
 ```
 
-The bundled snapshot is **global** (official registers of 15 countries across
-Europe, North America, South America, SE Asia, Oceania and Ukraine — see [Where the data
+The bundled snapshot is **global** (official registers of every covered country, across
+Europe, North America, South America, Asia, Oceania and Ukraine — see [Where the data
 comes from](#where-the-data-comes-from)), so the region gate accepts every
 region query — `region: :eu` callers from 0.1.x keep working unchanged:
 
@@ -512,7 +672,7 @@ Vehicles.region               # => :global
 
 ## License plates
 
-The gem bundles the VehiclesDB **registration-mark dataset** (PRD-PLATES): every plate series per jurisdiction, researched to the issuing authority's own documents — formats, eras, alphabets, designs. Ask it whether a typed registration is real:
+The gem bundles the VehiclesDB **registration-mark dataset**: every plate series per jurisdiction, researched to the issuing authority's own documents — formats, eras, alphabets, designs. Ask it whether a typed registration is real:
 
 ```ruby
 Vehicles.plate("12-GB-BD", jurisdiction: :nl).valid?    # => true — exact, as issued
@@ -520,11 +680,42 @@ Vehicles.plate("12gbbd", jurisdiction: :nl).suggestion  # => "12-GB-BD"  (did yo
 Vehicles.plate("12-AB-CD", jurisdiction: :nl).strict?   # => false — vowels aren't issued
 ```
 
-Matching is **two-tier**: exact as-issued first, then a separator-forgiving tier — `"1234XYZ"`, `"1234 xyz"` and `"1234-XYZ"` all resolve to the same serial, with `suggestion` giving the formatting the plate actually wears. Leniency forgives punctuation, **never the alphabet**: the strict regexes encode what the authority really issues (the Dutch vowel purge, the Spanish consonant-triplet rule…). `Match#strict?` separates authority-alphabet hits from recall-only catch-alls (export plates accept any current shape, by law).
+Matching is **two-tier**: exact as-issued first, then a separator-forgiving tier — `"1234XYZ"`, `"1234 xyz"` and `"1234-XYZ"` all resolve to the same serial, with `suggestion` giving the formatting the plate actually wears. Leniency forgives punctuation, **never the alphabet**: the strict regexes encode what the authority really issues (the Dutch vowel purge, the Spanish consonant-triplet rule…). `Match#strict?` separates validity claims from shape hits: it is true when a hit comes from a series the dataset marks `matching: strict` (the plates spec §2.7), and false for recall-only catch-alls (export plates accept any current shape, by law; Spain's 1900–1971 numeric era is one wide union). Validate user input with `strict?`.
+
+When a plate has a series' shape but breaks its alphabet, `near_misses` names that series, so a form can say why:
+
+```ruby
+m = Vehicles.plate("1234 ABC", jurisdiction: :es)
+m.valid?                                   # => false
+m.near_misses.map(&:id)                    # => ["es-national-2000"]
+m.jurisdiction.charset["excluded_letters"] # => ["A", "E", "I", "O", "U", "Ñ", "Q"]
+```
+
+One reason code per answer, for the error message (the hosted API answers the same codes):
+
+```ruby
+Vehicles.plate("1234 BCD", jurisdiction: :es).reason            # => :ok
+Vehicles.plate("1234 ABC", jurisdiction: :es).reason            # => :excluded_letters
+Vehicles.plate("1234 ABC", jurisdiction: :es).excluded_letters  # => ["A"]
+Vehicles.plate("12345", jurisdiction: :es).reason               # => :bad_shape
+# also :unverifiable (only a recall-only series has the shape), :empty, :unknown_jurisdiction
+```
+
+Moving people (ride sharing, rentals)? `passenger?` says whether a strictly valid
+plate belongs to a series issued to passenger-carrying vehicles — a trailer
+(`R-1234-BCD`) or tractor plate (`E-1234-BCD`) is valid but not that:
+
+```ruby
+Vehicles.plate("1234 BCD", jurisdiction: :es).passenger?     # => true
+Vehicles.plate("R-1234-BCD", jurisdiction: :es).passenger?   # => false (reason is still :ok)
+Vehicles.plates(:es).series.reject(&:passenger?).map(&:klass) # => ["agricultural", "trailer"]
+```
+
+A plate is personal data: the matcher is local, and nothing here sends it anywhere.
 
 ```ruby
 Vehicles.plates              # => every jurisdiction
-Vehicles.plates(:es).series  # => 18 series: formats, periods, sourced designs
+Vehicles.plates(:es).series  # => 19 series: formats, periods, sourced designs
 ```
 
 Pilot coverage (gate L0): 🇳🇱 🇪🇸 🇩🇪 + US-Florida, 73 series, corpus-proven in NL. Same posture as everything else here: bundled, offline, forgiving in, honest out.
@@ -565,21 +756,51 @@ end
 
 car = Vehicles.find("vw golf")
 
-# Rendered vehicle imagery — LIVE today. Mint a key at
+# Studio vehicle imagery — LIVE today. Mint a key at
 # https://vehiclesdb.com/settings/api-keys
 car.image                        # => "https://vehiclesdb.com/…/md.webp"  (640×360)
 car.image(size: :lg)             # :sm 320×180 · :md 640×360 · :lg 1280×720
-car.image(color: "red")          # color-accurate; un-rendered colors fall back honestly
+car.image(color: "red")          # color-accurate; unavailable colors fall back honestly
 car.images(color: "red")         # the full payload: every variant + dimensions,
-                                 #    rendered palette, served-vs-requested color
+                                 #    available palette, served-vs-requested color
 # color slugs are the gem's own canon — Vehicles.colors — so a stored
-# dropdown value maps 1:1 to the rendered imagery.
+# dropdown value maps 1:1 to the studio imagery.
+
+# Enrichment — the wired-up seam. nil today: the API does not serve these yet.
+car.years                        # production years (nil until published)
+car.segment                      # editorial segment (nil until published)
+```
+
+**Images in a Rails app.** Every served image is billed, so the gem caches
+whole payloads (in-process by default; share them with `Rails.cache`) and never
+raises. `image` answers nil on any failure; when you need to know **why**, ask
+`images_result`:
+
+```ruby
+Vehicles.configure do |config|
+  config.image_cache     = Rails.cache   # a hit is kept a day (capped by the payload's expiry), a 404 ten minutes
+  config.on_hosted_error = ->(result) { Rails.error.report(result.to_error, handled: true) }
+end
 
-# Enrichment — the wired-up seam; ships next. nil until then, same objects.
-car.years                        # => 1974..2024            production years
-car.segment                      # => :hatchback / :hot_hatch   editorial segment
+car = Vehicles.by_id(record.vehiclesdb_id)
+car.image(color: record.color, exact_color: true)  # nil instead of another color's image
+r = car.images_result(color: "red")
+r.ok?      # => false
+r.reason   # => :payment_required   (:no_api_key :not_found :unauthorized :rate_limited
+           #     :invalid_request :server_error :timeout :network :color_not_available …)
+r.error    # => "insufficient_credits"  (the API's own code, verbatim)
 ```
 
+- `on_hosted_error` (and a warn log line) fires for a bad key, an empty wallet,
+  rate limiting, server errors and timeouts — never for a plain "no image yet".
+- A record a dataset release renamed answers with a 301 to its successor; the gem
+  follows it (same host only, so your key never leaves it).
+- `year:` is sent to the API, which answers `422 unsupported_filter` until
+  year-accurate images ship (`image` → nil, `reason: :invalid_request`); until
+  0.9.1 the gem silently dropped it.
+- With `exact_color: true` a model's known palette is remembered, so a color it
+  is not available in costs no request at all.
+
 Under the hood this is a simple **provider** model: a `LocalProvider` (the bundled data) is always available, and a `HostedProvider` activates only when an API key is configured. Calls prefer the hosted data when it's there and **fall back to the local data otherwise — never raising, never blocking** your request:
 
 ```ruby
@@ -599,18 +820,19 @@ Vehicles.configure do |config|
   config.region    = :eu                          # default region for queries
   config.api_key   = ENV["VEHICLESDB_API_KEY"]    # optional hosted VehiclesDB data
   config.aliases   = { "Chevy" => "Chevrolet" }   # add your own make aliases
-  config.use_cache = true                         # prefer a refreshed dataset over the bundled one
+  config.use_cache = true                         # serve a refreshed dataset when it is usable
+  config.cache_dir = Rails.root.join("storage", "vehicles") # a shared volume for multi-container deploys
+  config.image_cache = Rails.cache                # hosted image payloads, shared across processes
 end
 ```
 
 ## Staying current (optional)
 
 The bundled snapshot works offline forever — but vehicle data changes (new
-makes, fixes), and you shouldn't have to ship a gem upgrade to every app just to
-get them. So `vehicles` can **refresh** from the published
-[dataset](https://github.com/vehiclesdb/vehiclesdb) into a local file cache;
-loads prefer the cache over the bundled copy. Data fixes reach your app **without
-a gem bump.**
+makes, fixes, renamed records), and you shouldn't have to ship a gem upgrade to
+every app just to get them. So `vehicles` can **refresh** from the published
+[dataset](https://github.com/vehiclesdb/vehiclesdb) into a file cache. Data
+fixes reach your app **without a gem bump.**
 
 `rails g vehicles:install` drops a `VehiclesRefreshJob` — schedule it (daily is
 plenty), e.g. with solid_queue:
@@ -622,16 +844,58 @@ vehicles_refresh:
   schedule: every day at 3am
 ```
 
-Or refresh manually:
+Or refresh by hand:
+
+```ruby
+result = Vehicles.refresh     # never raises
+result.status                 # => :updated | :current | :rejected | :failed
+result.message                # => "dataset 2026.11.2 → 2026.12.0"
+Vehicles.refresh!             # the same, as true/false (true when updated or already current)
+Vehicles.data_version         # => the version now in effect (cached, or bundled)
+```
+
+**Safe by construction.** A release is written only when all of these hold;
+otherwise your current data stays untouched and `result.reason` says why:
+
+1. The release **manifest** (a few KB, read first) announces a dataset schema
+   this gem reads and a version **newer** than the newest data you already have.
+   Same version → nothing is downloaded. Older → refused: never a downgrade.
+2. The payload is fetched **from that exact release**, parses, carries that
+   version and schema, and matches the manifest's per-kind model counts (and
+   its checksum, when the manifest publishes one).
+3. No kind, and no kind-in-a-country (e.g. Spain's cars), shrinks below
+   `config.refresh_min_ratio` (0.9) of the data in use — a broken release can
+   never empty your pickers.
+4. Your own `config.refresh_guard`, if set, accepts it:
+   `->(new_data, current) { … }` with two `Vehicles::Dataset`s.
+
+It is written atomically (temp file + rename). And the file a process serves is
+chosen just as carefully: a refreshed cache is used only while it is **not older
+than the gem's bundled data** and in a schema the gem reads — upgrading the gem
+always wins over an older download.
+
+**Every process picks it up on its own.** Each process re-checks the file at
+most every `config.reload_check_interval` seconds (default 5; one `File.stat`)
+and switches to a new one — no restart, no hook. A file that is corrupt or
+half-written never replaces the dataset in memory.
+
+**Deploying web and jobs as separate containers** (Kamal, Docker Compose,
+Kubernetes)? Give them one shared volume and point the gem at it, so the job's
+refresh reaches the web containers:
 
 ```ruby
-Vehicles.refresh!     # pull latest -> cache; true/false, never raises
-Vehicles.data_version # => the version now in effect (cached, or bundled)
+# config/initializers/vehicles.rb — or set VEHICLES_CACHE_DIR in both containers
+Vehicles.configure { |c| c.cache_dir = Rails.root.join("storage", "vehicles") }
 ```
 
-It's safe by design: a failed/partial download never replaces good data, and the
-gem keeps serving the cache (or the bundled snapshot) no matter what. Want it
-fully offline/deterministic? `config.use_cache = false`.
+```yaml
+# config/deploy.yml (Kamal): web and job already share the storage volume
+volumes:
+  - "myapp_storage:/rails/storage"
+```
+
+Run the refresh in ONE place (the job container); every container serves the
+result. Want it fully offline/deterministic instead? `config.use_cache = false`.
 
 ## The full Ruby API
 
@@ -639,8 +903,10 @@ fully offline/deterministic? `config.use_cache = false`.
 # Lists (strings — drop straight into a form)
 Vehicles.makes                          # => [String]
 Vehicles.makes(kind: :car, region: :eu)
+Vehicles.makes(kind: :car, country: :es) # only makes evidenced in that country
 Vehicles.models("Audi")                 # => [String]
 Vehicles.models("Audi", body_type: :suv)
+Vehicles.models("SEAT", kind: :car, country: :es) # in Spain's popularity order
 
 # Option pairs (for Rails `select`)
 Vehicles.make_options                   # => [[label, value]]
@@ -648,14 +914,24 @@ Vehicles.model_options("Audi")          # => [[label, value]]
 
 # Whole make => [models] map (embed once for a client-side dependent picker)
 Vehicles.catalog(kind: :car)            # => { "Audi" => ["A3", ...], ... }
+Vehicles.catalog(kind: :car, country: :es) # one country's picker list
+Vehicles.dataset_slice(kind: :car, country: :es) # the same scope as dist/vehicles.json records (widget `data`)
 
 # Objects
 Vehicles.make("Audi")                   # => Vehicles::Make | nil
 Vehicles.find("audi a3")                # => Vehicles::Model | nil  (one free-text string)
 Vehicles.model("Audi", "A3")            # => Vehicles::Model | nil  (a stored make+model pair)
-Vehicles.model("Toyota", "Land Cruiser", kind: :bus)  # pick a kind (default: the car)
+Vehicles.model("Iveco", "Daily", kind: :bus)  # pick a kind (default: the one kind rule)
+Vehicles.model("Iveco", "Daily", kinds: [:car, :van]) # allow only some kinds
 Vehicles.match_model("VW", "Tuareg")    # => Vehicles::ModelMatch | nil  (model, rung, confidence, via, candidates)
+Vehicles.match_model("VW", "Golf").confident? # => true: safe to auto-apply
 Vehicles.identify("vw tuareg")          # => Vehicles::ModelMatch | nil  (one free-text string)
+
+# Canonical ids
+Vehicles.by_id("car/volkswagen/golf")   # => Vehicles::Model | nil  (follows former ids)
+Vehicles.by_id(id, follow: false)       # exact only
+Vehicles.successor(id)                  # => the id to store now | nil
+Vehicles.live?(id)                      # => true when the id names a current record
 Vehicles.search("a3")                   # => [Vehicles::Model]
 
 # Popularity & availability (open data, measured from official registers)
@@ -672,26 +948,35 @@ model.aliases  model.forms                     # published alternate names; cura
 model.kind     model.body_type                 model.suv?    model.coupe?   # …predicates
 model.global_decile   model.popular?           # 1 = top 10% worldwide; nil-safe
 model.availability    model.available_in?(:nl) model.two_wheeler?
-model.years    model.segment  model.image(year:, color:)     # ← hosted VehiclesDB API
+model.id       model.former_ids                # "car/volkswagen/golf"; ids this record replaced
+model.registration_years                       # { first: 1998, last: 2026 } hint, or nil (never a validation bound)
+model.years    model.segment                   # production years / segment: nil until published
+model.image(color:, size:, exact_color:)  model.images(color:)  model.images_result(color:)  # ← hosted API
 
 # Colors (canonical palette)
 Vehicles.colors                         # => [Vehicles::Color]
 Vehicles.color("navy")                  # => Vehicles::Color | nil (forgiving)
-Vehicles.color_options                  # => [[name, slug]]  (for select)
-color.slug     color.name     color.hex
+Vehicles.color_options(locale: :es)     # => [[label, slug]]  (for select; :en default)
+color.slug     color.name     color.hex     color.label(:es)
+Vehicles.kind_options(locale: :es)      Vehicles.kind_label(:van, locale: :es)
+Vehicles.body_type_options(locale: :es) Vehicles.body_type_label(:wagon, locale: :es)
+
+# Plates
+Vehicles.plate("1234 BCD", jurisdiction: :es)  # => Plates::Match: valid? strict? reason passenger? suggestion
 
 # Meta
 Vehicles.data_version                   # => "2026.07.0"   (version in effect: cached or bundled)
 Vehicles.region                         # => :global
 
 # Refresh (optional — keep data current without a gem upgrade)
-Vehicles.refresh!                       # pull latest published data -> cache; true/false, never raises
-Vehicles.reload!                        # drop the in-memory dataset (reload from disk)
+Vehicles.refresh                        # => Vehicles::RefreshResult (status, reason, message); never raises
+Vehicles.refresh!                       # the same as true/false
+Vehicles.reload!                        # drop the in-memory dataset now (processes also re-check on their own)
 ```
 
 ## Where the data comes from
 
-The bundled dataset is [**VehiclesDB**](https://github.com/vehiclesdb/vehiclesdb) — an open dataset **reconciled from official vehicle registers of 15 countries on 5 continents** (the Dutch RDW, UK DfT, Spanish DGT, Finnish Traficom, German KBA, US EPA, New Zealand's Motor Vehicle Register, Thailand's DLT, Ukraine's MVS, and more — the exact list for the bundled 2026.10.0 snapshot is `countries` in the data repo's `manifest.json`). A model ships only when **two independent official sources corroborate it** — or one shows a registration count no typo could produce — so you get real nameplates without the registry noise.
+The bundled dataset is [**VehiclesDB**](https://github.com/vehiclesdb/vehiclesdb) — an open dataset **reconciled from the official vehicle registers of every covered country, on five continents** (the Dutch RDW, UK DfT, Spanish DGT, Finnish Traficom, German KBA, US EPA, New Zealand's Motor Vehicle Register, Thailand's DLT, Ukraine's MVS, and more — the exact list for the bundled 2026.11.6 snapshot is `countries` in the data repo's `manifest.json`). A model ships only when **two independent official sources corroborate it** — or one shows a registration count no typo could produce — so you get real nameplates without the registry noise.
 
 Every record is shaped like this:
 
@@ -725,15 +1010,14 @@ No magic, just good defaults:
 
 ## Roadmap
 
-Bundled today: ~15k models across 6 kinds and 15 countries, with popularity +
-availability, plus the MCP server. On the way:
+Bundled today: the full VehiclesDB catalog across all 6 kinds, with popularity +
+availability, plus the MCP server (the live counts are in the data repo's
+`manifest.json`; this README deliberately carries none). On the way:
 
-- 🌍 More **countries** (Switzerland next; the dataset grows monthly)
+- 🌍 More **countries** (the dataset grows monthly)
 - 📅 Production **years** in the local data
 - 🧬 **Generations & variants** layers (the schema already reserves them)
-- 🖼️ Model **images** (via VehiclesDB)
 - 🏷️ **Segments** (supercar, city car, hot hatch) and richer metadata
-- 🔎 A mountable **autocomplete endpoint** so the dependent-dropdown recipe becomes one line
 
 Want one of these sooner? Open an issue.