vehicles 0.4.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 99ccb43a3ef0091206a4e6a7445c48333886f0a26cfd9a1764397e0c5ec46516
-  data.tar.gz: b2a878137e3861323aaf59f12c0f5f44052b5ed064bc2f519b7247aaca916027
+  metadata.gz: c9ab45bf3b30e2ab2688becf7e36d4c67a1f40267324cec67b3df7955eb874db
+  data.tar.gz: 2fac8f7b9d499000730c0ecb3e4fa98d2555a06ce1c7ce8e5d82a1c730ef9573
 SHA512:
-  metadata.gz: c7c2b0995cb72a450f91ab1c7d37e8c1d0ebb439358a09572e467d4786dd0edca211c904d9194ef42f3e6563ba1719b32041c645d0d25bd2f85c663607e58840
-  data.tar.gz: 0a3c8914e5d5fc681ef7b83b2062746b382f0281c0ae75475120acb3227d8d2d7349e1c2f0c2769f62e6f8f6130733430f4d2b25db3ce27780989bf9326f4bba
+  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,327 @@ 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
+
+- `Model#former_ids` — the full canonical ids a record absorbed through the
+  dataset's append-only migration contract (e.g. `car/alfa-romeo/159sw`).
+  The field was already in the bundled snapshot; the reader now surfaces it,
+  so integrators can migrate stored ids without re-parsing the raw JSON.
+  Also included in `Model#to_h`.
+
+## [0.6.0] - 2026-07-27
+
+License plates become a first-class citizen: the PRD-PLATES registration-mark
+dataset ships in the gem, bundled and offline like everything else.
+
+### Added
+- `Vehicles.plate(input, jurisdiction:)` — two-tier plate validation:
+  exact as-issued, then separator-forgiving ("1234XYZ" == "1234 XYZ" ==
+  "1234-xyz") with `Match#suggestion` returning the as-issued formatting.
+  Leniency forgives punctuation, never the alphabet — strict regexes encode
+  what each authority really issues. `Match#strict?` separates
+  authority-alphabet hits from recall-only catch-alls (export plates etc.).
+- `Vehicles.plates` / `Vehicles.plates(:nl)` — the full series data:
+  73 series across NL/ES/DE/US-FL (gate L0, NL corpus-proven), each with
+  pattern, period, class, categories, sourced design facts and citations.
+- Bundled data under `data/plates/` (CC-BY, pinned upstream commit in
+  `data/plates/PROVENANCE.md`).
+
+The hosted images API is **live** — this release points the wired-up provider
+seam at the real thing.
+
+### Added
+- `Model#image(color:, size:)` returns a rendered variant URL from the live
+  VehiclesDB images API (`:sm` 320×180, `:md` 640×360, `:lg` 1280×720, webp).
+  Mint a key at <https://vehiclesdb.com/settings/api-keys> and set
+  `config.api_key`; without a key it stays nil, as always.
+- `Model#images(color:)` returns the full payload: every variant with
+  dimensions, the rendered palette for the model, served-vs-requested color
+  (un-rendered colors fall back honestly instead of 404ing), provenance.
+
+### Changed
+- `config.api_base_url` default is now `https://vehiclesdb.com` (the live API
+  origin; endpoint paths carry `/v1`). It must be an ORIGIN — no path suffix.
+- `Model#image` accepts `year:` but does not send it: `year`/`trim` are
+  reserved filters server-side (the API 422s on them by contract) until
+  year-accurate renders ship.
+
 ## [0.4.1] - 2026-07-26
 
 Data-only refresh to VehiclesDB dataset **2026.07.4** — the July correction