vehicles 0.6.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d31bdc07c2c1c97fe6e2f3f6de9bd94545f75cd69629a0ecc49171d369d7fee6
-  data.tar.gz: afc63731709c038bd56171d50a30ddb8a06253f5fc51e86d2b3f7d36c0540c05
+  metadata.gz: c9ab45bf3b30e2ab2688becf7e36d4c67a1f40267324cec67b3df7955eb874db
+  data.tar.gz: 2fac8f7b9d499000730c0ecb3e4fa98d2555a06ce1c7ce8e5d82a1c730ef9573
 SHA512:
-  metadata.gz: 2e0b37318a2131f1c35ecaaca88e72d4d967d9ad134c8777a6f0c2dda0d4105792c7eb2bd749ba0891a94dbac2761b60c947004376b478a3bb66f78e6f01bf2b
-  data.tar.gz: 6a215001415080252d699ee3a202043c9685f6286a8763896db3371a81f9458ab01afcb58ca253e2f8a4cac652782564050246fc493911854c4c3756154a089d
+  metadata.gz: a2ac35c05cbd762cd5f818291c30792c1b8e69c18efe699f5b9408f9a35b23bd2646217f4333ca09ca7ef75c54c464eb2dedfdf4433cb7a9563712d69116c90c
+  data.tar.gz: bfcc408a806116de713664e4acf300edc515e9bf0a98075f4fa943520683e13b1b0700fa616635e2cf3cc2e73d08db8f97ba4e3dd606ed726ef0b5d653827076

data/.rubocop_todo.yml

@@ -0,0 +1,164 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config --no-exclude-limit`
+# on 2026-10-10 04:04:37 UTC using RuboCop version 1.91.0.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 5
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: with_first_argument, with_fixed_indentation
+Layout/ArgumentAlignment:
+  Exclude:
+    - 'lib/vehicles/plates/series.rb'
+    - 'test/plates_test.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EmptyLineBetweenMethodDefs, EmptyLineBetweenClassDefs, EmptyLineBetweenModuleDefs, DefLikeMacros, AllowAdjacentOneLineDefs, NumberOfEmptyLines.
+Layout/EmptyLineBetweenDefs:
+  Exclude:
+    - 'test/plates_test.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowForAlignment, AllowBeforeTrailingComments, ForceEqualSignAlignment.
+Layout/ExtraSpacing:
+  Exclude:
+    - 'lib/vehicles/plates/series.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: aligned, indented, indented_relative_to_receiver
+Layout/MultilineMethodCallIndentation:
+  Exclude:
+    - 'lib/vehicles/plates/jurisdiction.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: aligned, indented
+Layout/MultilineOperationIndentation:
+  Exclude:
+    - 'lib/vehicles/plates/series.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowForAlignment, EnforcedStyleForExponentOperator, EnforcedStyleForRationalLiterals.
+# SupportedStylesForExponentOperator: space, no_space
+# SupportedStylesForRationalLiterals: space, no_space
+Layout/SpaceAroundOperators:
+  Exclude:
+    - 'lib/vehicles/plates/series.rb'
+
+# Offense count: 58
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, EnforcedStyleForEmptyBrackets.
+# SupportedStyles: space, no_space, compact
+# SupportedStylesForEmptyBrackets: space, no_space
+Layout/SpaceInsideArrayLiteralBrackets:
+  Exclude:
+    - 'lib/vehicles/plates.rb'
+    - 'lib/vehicles/plates/jurisdiction.rb'
+    - 'lib/vehicles/plates/series.rb'
+    - 'test/plates_test.rb'
+
+# Offense count: 1
+# This cop supports unsafe autocorrection (--autocorrect-all).
+Lint/RedundantDirGlobSort:
+  Exclude:
+    - 'lib/vehicles/plates.rb'
+
+# Offense count: 4
+# Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
+Metrics/AbcSize:
+  Exclude:
+    - 'lib/vehicles/plates/series.rb'
+
+# Offense count: 1
+# Configuration parameters: CountBlocks, CountModifierForms, Max.
+Metrics/BlockNesting:
+  Exclude:
+    - 'lib/vehicles/plates/series.rb'
+
+# Offense count: 1
+# Configuration parameters: CountComments, Max, CountAsOne.
+Metrics/ClassLength:
+  Exclude:
+    - 'lib/vehicles/mcp_server.rb'
+    - 'lib/vehicles/plates/series.rb'
+
+# Offense count: 2
+# Configuration parameters: CountComments, Max, CountAsOne, AllowedMethods, AllowedPatterns.
+Metrics/MethodLength:
+  Exclude:
+    - 'lib/vehicles/plates/series.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Minitest/AssertPredicate:
+  Exclude:
+    - 'test/model_test.rb'
+
+# Offense count: 11
+# This cop supports safe autocorrection (--autocorrect).
+Minitest/EmptyLineBeforeAssertionMethods:
+  Exclude:
+    - 'test/model_test.rb'
+    - 'test/plates_test.rb'
+
+# Offense count: 13
+# Configuration parameters: MinSize.
+Performance/CollectionLiteralInLoop:
+  Exclude:
+    - 'lib/vehicles/plates/series.rb'
+    - 'test/plates_test.rb'
+
+# Offense count: 1
+# This cop supports unsafe autocorrection (--autocorrect-all).
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: always, always_true, never
+Style/FrozenStringLiteralComment:
+  Exclude:
+    - '**/*.arb'
+    - 'rakelib/plates_refresh.rake'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Style/NestedTernaryOperator:
+  Exclude:
+    - 'lib/vehicles/plates/series.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Style/PerlBackrefs:
+  Exclude:
+    - 'lib/vehicles/plates/series.rb'
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, ConsistentQuotesInMultiline.
+# SupportedStyles: single_quotes, double_quotes
+Style/StringLiterals:
+  Exclude:
+    - 'test/plates_test.rb'
+
+# Offense count: 3
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: single_quotes, double_quotes
+Style/StringLiteralsInInterpolation:
+  Exclude:
+    - 'lib/vehicles/plates.rb'
+    - 'lib/vehicles/plates/series.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: WordRegex.
+# SupportedStyles: percent, brackets
+Style/WordArray:
+  EnforcedStyle: percent
+  MinSize: 3

data/CHANGELOG.md

@@ -7,6 +7,280 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-11-08
+
+### Added
+
+- **Plate art without sending the plate.** `Vehicles::Plates.render(registration,
+  jurisdiction:, region: nil, label: nil)` draws a registration on its series'
+  real VehiclesDB plate as an SVG, and nothing personal leaves the machine: the
+  gem picks the series locally (the bundled matcher; the only standard-class
+  hit, else the only hit — ambiguous plates such as German `MAB1234` answer
+  nil instead of the wrong plate), derives the shape (`NNNN LLL`), fetches the
+  BLANK template `GET {api_base_url}/plates/:code/:series_id/template.svg?shape=&region=`
+  and fills it here. No API key is sent (the route is public). Returns nil on
+  any failure, never raises.
+- `Vehicles::Plates.template(code:, series:, shape: nil, region: nil)`: the
+  blank template, or nil. Client-side fences refuse a shape that is not pure
+  N/L classes and separators, so a registration passed by mistake never
+  reaches the wire. Cached in-process by default; `config.plate_template_cache`
+  takes any `read` / `write(key, value, expires_in:)` store (e.g. `Rails.cache`)
+  and `config.plate_template_ttl` (default one day) the lifetime. Failures are
+  remembered for five minutes, so an unreachable server costs one timeout per
+  template per window, not one per call. Keys carry the template schema and
+  gem version.
+- `Vehicles::Plates::TemplateFill`: the reference filler, moved verbatim from
+  vehiclesdb-web (`fill`, `metadata`, `groups`, and the shared fit formulas
+  `fit_size` / `recentered_baseline` the VehiclesDB renderer will call from
+  here), plus `shape_of` and a `label:` option for a localized accessible
+  name. Standard library only; the file loads on its own in a gem-less Ruby.
+- Templates are inlined into host pages, so both the fetch and
+  `TemplateFill.fill` itself refuse a template carrying anything active or
+  external (`<script>`, event handlers including `<svg/onload=…>`,
+  `javascript:`, non-`data:` hrefs and `url()`s): `TemplateFill.inert?`.
+- `region:` takes subdivision keys only (`75`, `2A`, `971`, `44-bzh`, `BY`,
+  `ZH`, `9`), so a registration passed there by mistake is refused locally
+  and never sent.
+
+### Changed
+
+- The HTTP plumbing (timeout, no silent retry, nil on failure) moved from
+  `HostedProvider` into `Vehicles::HTTP`, shared by images and plate
+  templates. Behaviour of the images calls is unchanged.
+
+## [0.7.9] - 2026-11-08
+
+### Fixed
+
+- **Hosted images now reach the API.** `HostedProvider` requested
+  `https://vehiclesdb.com/v1/vehicles/…/images`, but the VehiclesDB API lives
+  under **`/api/v1`**: `/v1/…` is the website's HTML 404, so `Model#image` /
+  `Model#images` returned nil for every key since 0.5.0. Requests now go to
+  `GET {api_base_url}/api/v1/vehicles/:kind/:make_slug/:model_slug/images`
+  (`HostedProvider::API_PREFIX`). `config.api_base_url` is still the origin
+  and still overridable (`"http://localhost:3030"` for a local server); a
+  trailing slash or a proxy path prefix on it is now kept as written
+  instead of being dropped by `URI.join`. Pinned by tests over a real local
+  socket: the exact request line, the Bearer header, and nil on a 404 HTML
+  page, a 401, a non-JSON 200 and a refused connection.
+- **One hosted request is one request.** Net::HTTP re-sends an idempotent
+  GET once after a read timeout, so a slow images response was asked for
+  twice: double the latency `api_timeout` promises to cap, and two billed
+  calls when the second one is served (seen against a cold local server).
+  `max_retries` is now 0; pinned by a socket test that counts connections.
+- **A name that exists as several kinds answers with the car.**
+  `Vehicles.model("Toyota", "Land Cruiser")` returned the **bus** (the first
+  record of four kinds). Without `kind:`, `Make#model` / `Vehicles.model` /
+  `Vehicles.find` now prefer the `:car` record and keep the first record
+  when there is no car. Over every model name and slug in the bundled data
+  this moves 51 names from bus to car — same make and model, never a
+  different one.
+
+### Added
+
+- `kind:` on `Vehicles.model` and `Make#model` to pick the kind explicitly:
+  `Vehicles.model("Toyota", "Land Cruiser", kind: :bus)`.
+- **Spacing-blind model names.** When no name matches exactly, `Make#model`
+  compares letters and digits only, so `"XCeed"` is Kia's `"X Ceed"`, `"A 5"`
+  is Audi `"A5"`, `"CX5"` is `"CX-5"`, `"XC 90"` is `"XC90"` — but only when
+  that lands on ONE name (never a guess between two), and never partially
+  (`"X Cee"` stays nil). The model validator answers the same way: spacing
+  is not a typo.
+- **BMW's Spanish/Italian `"Serie N"`** reads as `"N Series"`
+  (`Vehicles.model("BMW", "Serie 3")` → 3 Series); a real `"Serie …"` name
+  (`"Serie X1"`) still wins.
+- Measured on a Spanish carpooling app's 1,329 free-text vehicles (make/model
+  typed or picked in Spanish): 17 more make/model pairs (23 vehicles) now
+  resolve, and the 3 Land Cruisers resolve to the car. Internal double
+  spaces were already collapsed by `Vehicles.normalize`; now pinned by a test.
+
+### Changed
+
+- `Model#years` / `Model#segment` no longer spend a request: the API serves
+  no endpoint for them yet (the old `/v1/models/:slug` never existed), so
+  the hosted provider answers nil without touching the network and the
+  chain falls through to the local data, exactly as before. They light up
+  when the API ships them. `HostedProvider.reset!` (its per-process cache)
+  is gone with it.
+- README: the plates endpoints are `/api/v1/plates/…`.
+
+## [0.7.8] - 2026-10-10
+
+### Added
+
+- **Typo-tolerant make lookup.** `Vehicles.make`, `Vehicles.models` and
+  every make-taking helper now fall back to the closest make by edit
+  distance when nothing matches exactly: `"marcedes"` → Mercedes-Benz,
+  `"volkswagon"` → Volkswagen, `"DeLorean"` → De Lorean. Bounded
+  (Levenshtein 1 for 4-5 characters, 2 from 6 up, never under 4), stdlib
+  only, and never a guess: when two different makes are equally close
+  (`"Acra"`: Acura / Acma) the answer is `nil`. Exact, alias and slug
+  matches always win; `Vehicles.find` runs its exact pass over every
+  make/model split before retrying a misspelled make, so no answer that
+  resolved in 0.7.7 changes. Opt out per call with `fuzzy: false`
+  (`make`, `models`, `model`, `model_options`, `find`). Guards: optimal
+  string alignment (an adjacent swap is one edit — `"telsa"` ties Tesla/
+  Temsa → nil, never Temsa); a candidate never has fewer words than the
+  query (`"Volvo V 60"` cannot become Volvo "60"); every word keeps its
+  first letter (`"citroen e"` is not Citroën DS); the configured
+  `other_label` is never fuzzy-matched. Verified: 0 changed / 0 lost
+  answers over 37,050 `find` and 65,871 web-resolver-style queries.
+- `Model#country_ranks` / `Model#rank_in(country)` — the model's rank
+  among all models of its kind in that country (dataset key
+  `country_ranks`, from `catalog/` `popularity.by_country[cc].rank`).
+- `Model#mass_decile` — per-kind registration-mass decile (1 = heaviest),
+  the dataset's `popularity.mass_decile` (2026.10.1+, pipeline#255 /
+  ruling R3); nil-safe on older snapshots (the bundled 2026.10.0 has none).
+  `global_decile` stays what it is — a presence average.
+  `top_models(by: :mass_decile)` ranks by it (records without it are
+  excluded, so it is `[]` on 2026.10.0 data); `by:` defaults to
+  `:global_decile`; anything else raises ArgumentError. With `country:`
+  the country's rank still sorts first (the decile breaks ties).
+  `Model#to_h` gains `:mass_decile`.
+- `rake "data:refresh[<tag>]"` — refreshes `data/vehicles.json` from a
+  dataset release tag and writes `data/PROVENANCE-vehicles.md`; fills
+  `country_ranks` from the same tag's catalog until the projection ships
+  the key natively (then it asserts equality instead).
+
+### Changed
+
+- **`top_models(country:)` orders by that country's own rank.** Until now a
+  country-filtered list kept the GLOBAL order (`global_decile`, a
+  presence-weighted average across countries), so the UK top-10 read in
+  everybody else's order. Models available there without a rank there
+  follow in the old order; data without `country_ranks` degrades to the
+  0.7.7 order. Ranks are per kind — pass `kind:` for a clean ranking.
+- Bundled dataset refreshed 2026.07.4 → **2026.10.0** (14,997 models, 15
+  countries; `dist/vehicles.json` at tag v2026.10.0 + `country_ranks`).
+- The make and model validators stay EXACT (`fuzzy: false`): a typo never
+  validates as a stored make.
+
+- Fuzzy matching is for human-typed names only: Symbols, input containing
+  `/`, `_`, `+` or `\` (ids, paths), hyphen-edged strings and single-case
+  hyphenated slugs (`marcedes-benz`, `MARCEDES-BENZ`) resolve exactly or
+  not at all; the MCP server's tools are exact-only.
+- CI: the 111 rubocop offenses inherited from main are frozen (110 in a
+  generated `.rubocop_todo.yml`, plus `plates/series.rb` in `.rubocop.yml`'s
+  own ClassLength Exclude, which overrides the todo) — no code changes — so
+  the Lint job is green again; new code is fully linted.
+
+### Upgrade notes
+
+- Apps that route or 404 on `Vehicles.make(param)`: slug-shaped params
+  (`marcedes-benz`, anything with `/`, `_`, `+`, a Symbol) never fuzz, but
+  a single-word param still does (`/makes/marcedes` → param `"marcedes"` →
+  Mercedes-Benz). If a misspelled URL must 404 (or 301 to the canonical
+  slug), call `Vehicles.make(param, fuzzy: false)` there.
+
+## [0.7.7] - 2026-08-03
+
+### Changed
+
+- Plates dataset refreshed — the overnight swarm passes' settlements
+  land: the Cypriot centre date mark, Brazil's square-dot printed form
+  and photographed moto split, San Marino's structured legend/sigla
+  fields, Ukraine's statutory line counts, California's pixel-sampled
+  colours and corner-sticker guides, the Texas exempt restatement,
+  Korea's corporate characters block, Thailand's seven-photo
+  cross-check, and China's two-row trailer + NEV dedicated-mark flips
+  (#288-#290).
+
+## [0.7.5] - 2026-08-03
+
+### Added
+
+- `Plates.decode_table(name)` — the _decode lookups (district/office/
+  use-mark tables) exposed to consumers, enabling serial-driven
+  subregion resolution (renderers picking the right Land arms from a
+  district prefix).
+
+## [0.7.4] - 2026-08-03
+
+### Added
+
+- South Korea (21 series + hangul decode tables) — corpus: 124
+  jurisdictions / 1,381 series.
+
+## [0.7.3] - 2026-08-03
+
+### Fixed
+
+- Pattern-language literal escapes: ca-nb-truck-2003 introduced "\L"
+  (a literal L, vs the any-letter placeholder). New Series#display_pattern
+  resolves escapes for display and slot walks; the round-trip test
+  substitutes placeholders escape-aware. Escape convention flagged to the
+  data maintainers for a ruling.
+
+## [0.7.2] - 2026-08-03
+
+### Added
+
+- The L3 wave: 28 jurisdiction files across five continents (jp cn in
+  th my br mx ar nz za ua + Australia's 8 states + Canada's 13
+  provinces/territories), 415 series and 10 more decode tables incl.
+  Japan's 138-mark statutory office table. Corpus now: 123
+  jurisdictions / 1,360 series / 34 decode tables.
+
+## [0.7.1] - 2026-08-02
+
+### Added
+
+- Plates corpus refreshed to 91 jurisdictions (the EU/EEA wave-2 landing:
+  ie dk no is pt lu pl cz sk hu ro si hr ee lv lt gr cy mt + microstates)
+  with 22 decode tables.
+
+## [0.7.0] - 2026-08-02
+
+### Added
+
+- The FULL plates corpus ships in the gem: 67 jurisdictions / 606 series
+  (the 8-country L1 EU wave, all 50 US states + DC + 5 territories, and
+  the redated pilots) + 10 decode tables — up from the 4 pilot files.
+  The art tier stays in the data repo; the gem bundles format data.
+
+## [0.6.4] - 2026-08-02
+
+### Changed
+
+- Bundled plates data refreshed from the redate pass: es-provincial is now
+  1971-2000 pinned to Decreto 2046/1971 at both ends (was a 1999-2000
+  instrument window), plus the 1900-1971 Spanish numeric era, the German
+  1956-2000 DIN era, 11 German and 10 Florida period corrections — all
+  cited to gazette primaries.
+- `approximate_start?` covers the two new honesty vocabularies
+  (instrument-in-force-upper-bound, secondary-locator-unverified), so
+  upper-bounded and uncited-secondary starts render with the "~".
+
+## [0.6.3] - 2026-08-02
+
+### Changed
+
+- Plate period labels read naturally: open series say "2000 → today", and
+  instrument-dated starts mark approximation as "~1999" instead of the
+  cryptic "≤1999". New `Series#approximate_start?` so displays can explain
+  the tilde ("documented from this year; the format may be older").
+
+## [0.6.2] - 2026-08-02
+
+### Fixed
+
+- `Plates::Series#format_serial` reconstructed variable-length serials by
+  walking the fixed display pattern, misplacing separators ("M1234LA" came
+  back as "M1-234L-A" instead of "M-1234-LA"). The pattern walk now applies
+  only when the serial exactly fills the pattern; length-mismatched serials
+  reconstruct from the regex segmented at its separators (new
+  `Series.segment_separators`, riding the dataset separator contract), and
+  a serial neither path can place comes back untouched rather than
+  mis-punctuated.
+
+### Changed
+
+- `Plates::Series#period_label` no longer presents instrument-dated starts
+  as the series era: rows whose `period_evidence` is `instrument-in-force`
+  or `instrument-window` label as "≤1999–2000" ("began by", not "began
+  in"). New `Series#period_evidence`, `#issued_regexp`,
+  `#issued_separators` readers for consumers mirroring the reconstruction.
+
 ## [0.6.1] - 2026-08-01
 
 ### Added

data/README.md

@@ -5,7 +5,7 @@
 > [!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 — **~17k models across 850+ makes: cars, motorcycles, mopeds, vans, trucks and buses**, reconciled from official registers of 14 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 — **~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.)
 
 ✨ Perfect for marketplaces, carpooling & rideshare apps, fleet tools, parking & EV-charging apps, insurance and booking forms — anywhere a user has to pick their vehicle.
 
@@ -75,12 +75,15 @@ Vehicles.models("toyota")     # case-insensitive
 Vehicles.models("VW")         # => Volkswagen   (common abbreviation)
 Vehicles.models("merc")       # => Mercedes-Benz
 Vehicles.models("alfa-romeo") # slug form
+Vehicles.models("marcedes")   # => Mercedes-Benz (typo: one make is clearly closest)
 ```
 
+Typos resolve too: when nothing matches exactly, the closest make within a small edit distance wins (1 edit up to 5 characters, 2 from 6 up, none under 4) — but only if ONE make is closest, so `"Acra"` (one edit from both Acura and Acma) stays `nil` rather than guessing. Pass `fuzzy: false` (`Vehicles.make("marcedes", fuzzy: false) # => nil`) when you need exact-only matching; the validators always do, so a typo never validates as a stored make. Three more guards keep it from guessing: a swap of two neighbouring letters counts as one edit (`"telsa"` is equally close to Tesla and Temsa, so it stays `nil`); a match may not drop a whole word (so `"Volvo V 60"` never turns into Volvo "60"); and every word keeps its first letter (so `"citroen e"` is not Citroën DS). Your configured `other_label` never fuzzy-matches a real make. Machine input never fuzzes either: Symbols, anything with `/`, `_`, `+` or `\` (ids like `car/mercedes-benz/c-class`, paths like `/makes/marcedes`), and single-case hyphenated slugs (`marcedes-benz`, `MARCEDES-BENZ`) resolve exactly or return `nil` — so routes and stored ids can never land on a guessed make. The MCP server tools are exact-only.
+
 Unknown make? You get an empty array, never an exception:
 
 ```ruby
-Vehicles.models("DeLorean")   # => []
+Vehicles.models("Zzyzx Motors")   # => []
 ```
 
 ## Smart lookup & search
@@ -179,8 +182,18 @@ car.popular?           # => true     decile ≤ 2 (and `false` when unranked —
 car.availability       # => ["es", "fi", "gb", ...]   countries with official evidence
 car.available_in?(:th) # => true
 
-# The most popular models — perfect for "common choices" pre-filled pickers:
-Vehicles.top_models(kind: :car, country: :nl, limit: 10)   # => [Model, ...]
+# The most popular models — perfect for "common choices" pre-filled pickers.
+# With `country:`, ordered by THAT country's own registration rank (ranks are per kind,
+# so pass `kind:`; countries whose sources record presence only — us, ca for cars —
+# have no ranks and keep the global order):
+Vehicles.top_models(kind: :car, country: :gb, limit: 3).map(&:name)  # => ["Fiesta", "Golf", "Corsa"]
+Vehicles.find("vw golf").rank_in(:gb)   # => 2    rank among all GB cars (nil where unranked)
+
+# Two different "popularity" questions — pick the one you mean:
+car.global_decile      # presence average: "popular in MANY countries" (equal country weight)
+car.mass_decile        # registration mass per kind: "how many EXIST" (1 = heaviest 10%)
+                       #   nil until your data is 2026.10.1+ (refresh! or a newer gem)
+Vehicles.top_models(kind: :car, by: :mass_decile, limit: 10)  # [] on older snapshots
 Vehicles.top_models(kind: :motorcycle, limit: 10).map(&:full_name)
 ```
 
@@ -303,7 +316,7 @@ They're forgiving the same way the lookups are (aliases, case, slugs), and they
 
 ### An "Other / not in the list" escape hatch
 
-Make/model dropdowns should never be a dead end — ~17k models is a lot, but
+Make/model dropdowns should never be a dead end — ~15k models 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.
@@ -398,6 +411,12 @@ car&.body_type                                      # => :hatchback
 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
+`"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)`.
+
 **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
 new kind packs ship, or when you decide to accept them) is a one-word change, not
@@ -422,8 +441,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 14 countries across
-Europe, North America, SE Asia, Oceania and Ukraine — see [Where the data
+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
 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:
 
@@ -451,6 +470,31 @@ Vehicles.plates(:es).series  # => 18 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.
 
+**Prefer HTTP?** The same matcher and the full format corpus are hosted endpoints on the [VehiclesDB API](https://vehiclesdb.com/api): `GET /api/v1/plates/{code}` (a jurisdiction's every series, with 1:1 SVG render URLs) and `GET /api/v1/plates/{code}/match?plate=…` (validity + as-issued formatting + a render of *that* registration on the real plate design). Free API keys at [vehiclesdb.com](https://vehiclesdb.com).
+
+### Drawing a plate without sending it anywhere
+
+A registration is personal data. To show a user their own plate on the real VehiclesDB plate art, the gem fetches a **blank template** (the series, the registration's *shape* — `NNNN LLL`, character classes only — and an optional region) and fills it **locally**:
+
+```ruby
+Vehicles::Plates.render("1234 BCD", jurisdiction: :es)
+# => "<svg … aria-label=\"Spain plate 1234 BCD\">…</svg>"  (nil when it can't)
+
+Vehicles::Plates.render("1234 BCD", jurisdiction: :es, label: "Matrícula 1234 BCD") # your language
+Vehicles::Plates.render("AB-123-CD", jurisdiction: :fr, region: "75")             # FR département band
+```
+
+Only `GET {api_base_url}/plates/es/es-national-2000/template.svg?shape=NNNN_LLL` goes on the wire: no registration, no API key (the route is public). Anything ambiguous (a German `MAB1234` could be `M-AB` or `MA-B`) or unreachable answers `nil` — keep drawing whatever you drew before. Templates are cached in-process; share them across processes with any store that has `read` / `write(key, value, expires_in:)`:
+
+```ruby
+Vehicles.configure do |config|
+  config.plate_template_cache = Rails.cache
+  config.plate_template_ttl   = 7 * 24 * 3600 # templates are public and change only with the plate art
+end
+```
+
+The pieces are public too: `Vehicles::Plates.template(code:, series:, shape:, region:)` returns the blank SVG, and `Vehicles::Plates::TemplateFill.fill(svg, registration)` is the dependency-free filler (stdlib `json` only) if you fetch templates yourself — in a browser, say.
+
 ## 🔓 More with VehiclesDB
 
 `vehicles` is the free, open-source SDK for [**VehiclesDB**](https://vehiclesdb.com) — a hosted API for richer vehicle data. The gem is **fully standalone and always will be**; pointing it at VehiclesDB is purely additive. Drop in an API key and the same objects you already use light up with more:
@@ -550,6 +594,7 @@ Vehicles.catalog(kind: :car)            # => { "Audi" => ["A3", ...], ... }
 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.search("a3")                   # => [Vehicles::Model]
 
 # Popularity & availability (open data, measured from official registers)
@@ -584,7 +629,7 @@ Vehicles.reload!                        # drop the in-memory dataset (reload fro
 
 ## Where the data comes from
 
-The bundled dataset is [**VehiclesDB**](https://github.com/vehiclesdb/vehiclesdb) — an open dataset **reconciled from official vehicle registers of 14 countries on 4 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). 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 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.
 
 Every record is shaped like this:
 
@@ -602,7 +647,7 @@ Every record is shaped like this:
 - **Nameplate-level, on purpose.** "Golf" covers the GTI, the Variant, the R — that's what a dropdown wants. Two-wheelers keep displacement granularity ("Wave110i", "CBR600RR") because that's how riders and registers both speak. Per-trim and per-generation detail is a VehiclesDB API concern.
 - **Popularity is measured**, from real registration/fleet counts — never scraped rankings. **Availability is evidence** (a country appears because an official source shows the model there), not marketing history.
 - **Source data:** openly-licensed government sources only, every license pinned and verified at build time — [full source list](https://github.com/vehiclesdb/vehiclesdb/blob/main/SOURCES.md) and [attribution notices](https://github.com/vehiclesdb/vehiclesdb/blob/main/ATTRIBUTION.md).
-- **This dataset** (`data/vehicles.json`): **CC-BY 4.0**. Attribution: *"Vehicle data by VehiclesDB (CC-BY 4.0), built from official public registers."*
+- **This dataset** (`data/vehicles.json`): **CC-BY 4.0**. Visible credit with a link is a condition of the license (§3(a)). The form we request: *"Vehicle data by [VehiclesDB](https://vehiclesdb.com)"* — on websites, a followable link (deep links to the make/model page you used are even better); in apps, name us in an about/credits screen. Ready-made snippets (HTML, Markdown, BibTeX, badge): [vehiclesdb.com/attribution](https://vehiclesdb.com/attribution). Prefer not to credit, or need the enriched paid layer? [Commercial license](https://vehiclesdb.com) — it waives only OUR credit, never the upstream register notices.
 - **The gem code:** MIT.
 
 The data is versioned (`Vehicles.data_version`). Each gem release bundles a known snapshot — the offline, deterministic floor. To get newer data, either upgrade the gem or enable [refresh](#staying-current-optional) (which pulls published releases without a gem bump). Either way it's explicit and versioned — no silent mutations.
@@ -618,7 +663,7 @@ No magic, just good defaults:
 
 ## Roadmap
 
-Bundled today: 19k models across 6 kinds and 14 countries, with popularity +
+Bundled today: ~15k models across 6 kinds and 15 countries, with popularity +
 availability, plus the MCP server. On the way:
 
 - 🌍 More **countries** (Switzerland next; the dataset grows monthly)

data/data/PROVENANCE-vehicles.md

@@ -0,0 +1,12 @@
+# Bundled vehicles dataset
+
+`data/vehicles.json` is the public data repo's `dist/vehicles.json`
+(the gem projection) at a release tag:
+
+- **Source**: https://github.com/vehiclesdb/vehiclesdb `dist/vehicles.json`
+- **Tag**: `v2026.10.0` (commit `794c27b1881fe561182ff2ee797683cc96047f20`), dataset version `2026.10.0`
+- **country_ranks**: 0 model(s) carried it natively; 14880 merged from
+  the same tag's `catalog/<kind>/models.json` `popularity.by_country[cc].rank`
+- **License**: CC-BY 4.0 (see the data repo's LICENSE + ATTRIBUTION.md)
+
+Refresh: `rake "data:refresh[<tag>]"` (this file is generated by it).

data/data/plates/PROVENANCE.md

@@ -1,9 +1,10 @@
-# Bundled plates dataset (PRD-PLATES L0)
+# Bundled plates dataset (PRD-PLATES, full corpus)
 
-Copy of `plates/` from the public data repo, refreshed on gem releases:
+Copy of `plates/` from the public data repo (EXCLUDING `_art/`),
+refreshed on gem releases:
 
 - **Source**: https://github.com/vehiclesdb/vehiclesdb `plates/`
-- **Commit**: `69c8dab39424cf50ff8d1a526216551c8a9cb12f`
+- **Commit**: `c7dd65c6f4144d39c62706b7be10231a12bc27e1`
 - **License**: CC-BY 4.0 (see the data repo's LICENSE + ATTRIBUTION.md)
 
-Refresh: copy the source tree over this directory and update the commit line.
+Refresh: `rake plates:refresh` (this file is generated by it).