feat: extend Flux image automation, Gatus, and docs for VIN Decoder

Closes leeworks-agents/api-company#133
Closes leeworks-agents/api-company#134
Closes leeworks-agents/api-company#135
Closes leeworks-agents/api-company#136

- flux/image-automation/imagerepositories.yaml: add vin-decoder ImageRepository
  pointing at registry.leeworks.dev/vin-decoder/api (#133)
- flux/image-automation/imagepolicies.yaml: add vin-decoder ImagePolicy
  with semver range >=0.1.0 (#133)
- flux/monitoring/gatus-helmrelease.yaml: add VIN Decoder API endpoint check
  targeting https://vin.leeworks.dev/v1/health with Slack alert (#134)
- docs/pre-launch-checklist.md: add vin-decoder to Infrastructure, DNS & TLS,
  Functional Verification, and Legal sections; update status page line to
  reference all four APIs (#135)
- docs/secrets-checklist.md: add items #11-13 for vin-decoder GITEA_TOKEN,
  gitea-registry, and rapidapi-proxy-secret; add detail sections for each (#136)

kustomize build flux/ passes with zero errors.

docs-site/public/specs/vin-decoder.yaml

@@ -0,0 +1,405 @@
+openapi: 3.1.0
+info:
+  title: VIN Decoder API
+  version: 1.0.0
+  description: |
+    Decode any 17-character Vehicle Identification Number (VIN) into structured
+    vehicle data including make, model, year, trim, engine, body style, and more.
+    Powered by the NHTSA vPIC public-domain database.
+
+    **Data source:** NHTSA Product Information Catalog and Vehicle Listing (vPIC)
+    public API - US federal government data, public domain (17 U.S.C. 105).
+
+    **Coverage:** Model years 1981-present, all major manufacturers registered
+    with NHTSA (domestic and import).
+
+    **Caching:** Decoded results are cached for 90 days; cache status is
+    indicated by the X-Cache response header.
+  contact:
+    name: leeworks.dev API Support
+    url: https://docs.leeworks.dev
+  license:
+    name: MIT
+    url: https://opensource.org/licenses/MIT
+
+servers:
+  - url: https://vin.leeworks.dev/v1
+    description: Production
+
+security:
+  - RapidApiProxy: []
+
+tags:
+  - name: decode
+    description: VIN decoding endpoints
+  - name: health
+    description: Service health and observability
+
+paths:
+  /decode:
+    get:
+      operationId: decodeVin
+      summary: Decode a single VIN
+      description: |
+        Decodes a 17-character VIN and returns structured vehicle attributes.
+        Results are cached for 90 days; a cache hit is indicated by
+        X-Cache: HIT in the response headers.
+      tags:
+        - decode
+      parameters:
+        - name: vin
+          in: query
+          required: true
+          description: 17-character Vehicle Identification Number (uppercase, no I/O/Q).
+          schema:
+            type: string
+            minLength: 17
+            maxLength: 17
+            pattern: "^[A-HJ-NPR-Z0-9]{17}$"
+          example: 1HGCM82633A004352
+        - name: raw
+          in: query
+          required: false
+          description: If true, include raw NHTSA vPIC fields in the response.
+          schema:
+            type: boolean
+            default: false
+      responses:
+        "200":
+          description: VIN successfully decoded
+          headers:
+            X-Cache:
+              schema:
+                type: string
+                enum: [HIT, MISS]
+              description: Whether the result was served from cache
+            X-Data-Source:
+              schema:
+                type: string
+              description: Upstream data source identifier
+            X-Request-Id:
+              schema:
+                type: string
+              description: Unique request identifier
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/VinDecodeResult"
+        "400":
+          description: Invalid VIN format or missing parameter
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "403":
+          description: Missing or invalid RapidAPI proxy secret
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "429":
+          description: Rate limit exceeded for your plan
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "500":
+          description: Internal server error or upstream NHTSA API failure
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+
+  /batch:
+    post:
+      operationId: decodeVinBatch
+      summary: Decode up to 50 VINs in a single request
+      description: |
+        Accepts a JSON body with an array of VINs (1-50) and returns a decoded
+        result for each. Each VIN is processed independently; partial failures
+        return an error object in that position rather than failing the whole batch.
+      tags:
+        - decode
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - vins
+              properties:
+                vins:
+                  type: array
+                  minItems: 1
+                  maxItems: 50
+                  items:
+                    type: string
+                    minLength: 17
+                    maxLength: 17
+                    pattern: "^[A-HJ-NPR-Z0-9]{17}$"
+                  description: Array of 17-character VINs to decode
+            example:
+              vins:
+                - 1HGCM82633A004352
+                - WBABW33486PX01612
+      responses:
+        "200":
+          description: Batch decode results (one entry per input VIN, in order)
+          headers:
+            X-Request-Id:
+              schema:
+                type: string
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  results:
+                    type: array
+                    items:
+                      oneOf:
+                        - $ref: "#/components/schemas/VinDecodeResult"
+                        - $ref: "#/components/schemas/VinDecodeError"
+                  count:
+                    type: integer
+                    description: Total number of VINs processed
+                  cached_count:
+                    type: integer
+                    description: Number of results served from cache
+                  error_count:
+                    type: integer
+                    description: Number of VINs that could not be decoded
+        "400":
+          description: Invalid request body
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "403":
+          description: Missing or invalid RapidAPI proxy secret
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "429":
+          description: Rate limit exceeded
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "500":
+          description: Internal server error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+
+  /health:
+    get:
+      operationId: healthCheck
+      summary: Service health check
+      description: |
+        Returns health status of the VIN Decoder service including cache
+        statistics and NHTSA API reachability. Does not require X-RapidAPI-Proxy-Secret.
+      tags:
+        - health
+      security: []
+      responses:
+        "200":
+          description: Service is healthy
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HealthResponse"
+        "503":
+          description: Service is degraded (upstream unreachable or DB error)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HealthResponse"
+
+components:
+  securitySchemes:
+    RapidApiProxy:
+      type: apiKey
+      in: header
+      name: X-RapidAPI-Proxy-Secret
+      description: |
+        RapidAPI proxy secret injected automatically by RapidAPI on every
+        subscriber request. Direct callers must include this header manually.
+
+  schemas:
+    VinDecodeResult:
+      type: object
+      required:
+        - vin
+        - error_code
+      properties:
+        vin:
+          type: string
+          description: The input VIN (uppercased)
+          example: 1HGCM82633A004352
+        make:
+          type: ["string", "null"]
+          description: Vehicle manufacturer brand
+          example: HONDA
+        model:
+          type: ["string", "null"]
+          description: Vehicle model name
+          example: Accord
+        model_year:
+          type: ["string", "null"]
+          description: Model year as a 4-digit string
+          example: "2003"
+        trim:
+          type: ["string", "null"]
+          description: Trim level (e.g. EX, LX, Sport)
+          example: EX
+        series:
+          type: ["string", "null"]
+          description: Series designation if applicable
+        body_class:
+          type: ["string", "null"]
+          description: Body style classification
+          example: Sedan/Saloon
+        drive_type:
+          type: ["string", "null"]
+          description: Drive configuration
+          example: FWD/Front-Wheel Drive
+        engine_displacement_cc:
+          type: ["number", "null"]
+          description: Engine displacement in cubic centimetres
+          example: 2354
+        engine_displacement_l:
+          type: ["number", "null"]
+          description: Engine displacement in litres
+          example: 2.4
+        engine_cylinders:
+          type: ["integer", "null"]
+          description: Number of engine cylinders
+          example: 4
+        fuel_type_primary:
+          type: ["string", "null"]
+          description: Primary fuel type
+          example: Gasoline
+        transmission_style:
+          type: ["string", "null"]
+          description: Transmission type (Automatic, Manual, CVT, etc.)
+          example: Automatic
+        transmission_speeds:
+          type: ["string", "null"]
+          description: Number of transmission speeds as string
+          example: "5"
+        plant_city:
+          type: ["string", "null"]
+          description: Assembly plant city
+          example: MARYSVILLE
+        plant_state:
+          type: ["string", "null"]
+          description: Assembly plant state/province
+          example: OHIO
+        plant_country:
+          type: ["string", "null"]
+          description: Assembly plant country
+          example: UNITED STATES (USA)
+        manufacturer_name:
+          type: ["string", "null"]
+          description: Full legal name of the manufacturer
+          example: HONDA OF AMERICA MFG., INC.
+        vehicle_type:
+          type: ["string", "null"]
+          description: NHTSA vehicle type classification
+          example: PASSENGER CAR
+        error_code:
+          type: string
+          description: NHTSA decode error code. "0" means successful decode.
+          example: "0"
+        error_text:
+          type: ["string", "null"]
+          description: Human-readable decode error (null when error_code is "0")
+        cached:
+          type: boolean
+          description: Whether this result was served from the local cache
+          example: true
+
+    VinDecodeError:
+      type: object
+      required:
+        - vin
+        - error
+        - message
+      properties:
+        vin:
+          type: string
+          description: The VIN that could not be decoded
+        error:
+          type: string
+          description: Error code
+          example: INVALID_VIN
+        message:
+          type: string
+          description: Human-readable error description
+          example: VIN must be exactly 17 alphanumeric characters
+
+    Error:
+      type: object
+      required:
+        - error
+        - message
+        - status
+      properties:
+        error:
+          type: string
+          description: Machine-readable error code
+          example: BAD_REQUEST
+        message:
+          type: string
+          description: Human-readable error description
+          example: "Query parameter 'vin' is required"
+        status:
+          type: integer
+          description: HTTP status code
+          example: 400
+
+    HealthResponse:
+      type: object
+      required:
+        - status
+        - version
+      properties:
+        status:
+          type: string
+          enum: [ok, degraded]
+          description: Overall service health
+        version:
+          type: string
+          description: Service version
+          example: "1.0.0"
+        uptime_seconds:
+          type: integer
+          description: Seconds since the service started
+          example: 86400
+        cache:
+          type: object
+          properties:
+            entries:
+              type: integer
+              description: Number of cached VIN records
+            hit_rate_24h:
+              type: number
+              description: Cache hit rate over the last 24 hours (0.0-1.0)
+            size_mb:
+              type: number
+              description: SQLite cache file size in megabytes
+        upstream:
+          type: object
+          properties:
+            nhtsa_vpic:
+              type: string
+              enum: [reachable, unreachable]
+              description: NHTSA vPIC API reachability
+            last_check:
+              type: string
+              format: date-time
+              description: ISO-8601 timestamp of last upstream health check

docs-site/src/pages/blog/vin-decoder.mdx

@@ -0,0 +1,340 @@
+---
+title: "How to Decode a VIN Number with Node.js Using Free NHTSA Data"
+description: "Learn how to decode any 17-character Vehicle Identification Number (VIN) with Node.js using the free NHTSA vPIC database — or skip the plumbing and call the leeworks.dev VIN Decoder API directly."
+date: "2026-05-30"
+author: "leeworks.dev"
+tags: ["vin-decoder", "nodejs", "automotive", "api", "tutorial"]
+---
+
+import Base from '../../layouts/Base.astro';
+
+<Base title="How to Decode a VIN Number with Node.js Using Free NHTSA Data" description="Learn how to decode any 17-character Vehicle Identification Number (VIN) with Node.js using the free NHTSA vPIC database — or skip the plumbing and call the leeworks.dev VIN Decoder API directly.">
+
+<article style="max-width: 800px; margin: 0 auto; padding: 2rem; line-height: 1.75;">
+
+<script type="application/ld+json" set:html={JSON.stringify({
+  "@context": "https://schema.org",
+  "@type": "Article",
+  "headline": "How to Decode a VIN Number with Node.js Using Free NHTSA Data",
+  "datePublished": "2026-05-30",
+  "author": { "@type": "Organization", "name": "leeworks.dev" },
+  "publisher": { "@type": "Organization", "name": "leeworks.dev", "url": "https://docs.leeworks.dev" }
+})} />
+
+# How to Decode a VIN Number with Node.js Using Free NHTSA Data
+
+Every vehicle sold in the United States since 1981 carries a unique 17-character fingerprint stamped into the chassis: the **Vehicle Identification Number**, or VIN. Decode it and you unlock make, model, year, trim level, engine type, body class, transmission, plant of manufacture, and more — without paying Carfax $40 per report.
+
+In this tutorial you'll learn how VINs are structured, how to query the free NHTSA vPIC database directly in Node.js, and how to call the **leeworks.dev VIN Decoder API** for a production-ready solution that handles caching, error handling, and batch decoding out of the box.
+
+---
+
+## What Is a VIN?
+
+A VIN is a 17-character alphanumeric string divided into three logical sections:
+
+| Section | Characters | Name | What It Encodes |
+|---------|-----------|------|-----------------|
+| **WMI** | 1–3 | World Manufacturer Identifier | Country of origin + manufacturer |
+| **VDS** | 4–9 | Vehicle Descriptor Section | Model, body style, engine type, check digit |
+| **VIS** | 10–17 | Vehicle Identifier Section | Model year, plant, sequential serial number |
+
+### Breaking down a real VIN
+
+Take `1HGCM82633A004352` — a 2003 Honda Accord EX:
+
+- `1HG` → Manufactured in the USA by Honda
+- `CM826` → Accord EX 4-door sedan, 2.4L i-VTEC engine (position 9 = check digit `3`)
+- `3` → Model year 2003 (position 10)
+- `A` → Marysville, Ohio assembly plant (position 11)
+- `004352` → Sequential production number
+
+VIN characters deliberately exclude `I`, `O`, and `Q` to avoid confusion with `1`, `0`, and `0` respectively — something to remember when validating user input.
+
+---
+
+## Why NHTSA vPIC?
+
+The **NHTSA Product Information Catalog and Vehicle Listing (vPIC)** is a US federal government database maintained by the National Highway Traffic Safety Administration. It covers:
+
+- All model years 1981 to present
+- Every manufacturer registered with NHTSA (domestic and imported)
+- 70+ decoded attributes per VIN including engine displacement, fuel type, GVWR, and more
+- **No API key, no rate limits** (beyond fair-use throttling), **public domain** under 17 U.S.C. 105
+
+The base endpoint is:
+
+```
+https://vpic.nhtsa.dot.gov/api/vehicles/DecodeVinValues/{vin}?format=json
+```
+
+---
+
+## Calling NHTSA vPIC Directly in Node.js
+
+Here's a minimal Node.js script using the built-in `fetch` API (Node 18+):
+
+```js
+// decode-vin.js
+const VIN = process.argv[2] ?? '1HGCM82633A004352';
+
+async function decodeVin(vin) {
+  // Validate: 17 chars, no I/O/Q
+  if (!/^[A-HJ-NPR-Z0-9]{17}$/.test(vin)) {
+    throw new Error(`Invalid VIN format: ${vin}`);
+  }
+
+  const url = `https://vpic.nhtsa.dot.gov/api/vehicles/DecodeVinValues/${vin}?format=json`;
+  const res = await fetch(url);
+
+  if (!res.ok) {
+    throw new Error(`NHTSA returned HTTP ${res.status}`);
+  }
+
+  const json = await res.json();
+  const r = json.Results[0];
+
+  return {
+    vin: r.VIN,
+    make: r.Make,
+    model: r.Model,
+    modelYear: r.ModelYear,
+    trim: r.Trim,
+    series: r.Series,
+    bodyClass: r.BodyClass,
+    driveType: r.DriveType,
+    engineDisplacementL: r.DisplacementL,
+    engineCylinders: r.EngineCylinders,
+    fuelTypePrimary: r.FuelTypePrimary,
+    transmissionStyle: r.TransmissionStyle,
+    manufacturerName: r.Manufacturer,
+    plantCity: r.PlantCity,
+    plantState: r.PlantState,
+    plantCountry: r.PlantCountry,
+    errorCode: r.ErrorCode,
+    errorText: r.ErrorText,
+  };
+}
+
+decodeVin(VIN)
+  .then(data => console.log(JSON.stringify(data, null, 2)))
+  .catch(err => { console.error(err.message); process.exit(1); });
+```
+
+Run it:
+
+```bash
+node decode-vin.js 1HGCM82633A004352
+```
+
+Expected output (abridged):
+
+```json
+{
+  "vin": "1HGCM82633A004352",
+  "make": "HONDA",
+  "model": "Accord",
+  "modelYear": "2003",
+  "trim": "EX",
+  "bodyClass": "Sedan/Saloon",
+  "driveType": "FWD/Front-Wheel Drive",
+  "engineDisplacementL": "2.4",
+  "engineCylinders": "4",
+  "fuelTypePrimary": "Gasoline",
+  "transmissionStyle": "Automatic",
+  "manufacturerName": "HONDA OF AMERICA MFG., INC.",
+  "plantCity": "MARYSVILLE",
+  "plantState": "OHIO",
+  "plantCountry": "UNITED STATES (USA)"
+}
+```
+
+---
+
+## The Problem with Rolling Your Own
+
+Calling NHTSA directly works great for a quick script. But for a production application, you'll quickly run into friction:
+
+1. **No caching** — every request hits the NHTSA servers. At scale, this is slow (NHTSA p99 ≈ 800ms) and risks being throttled.
+2. **Raw NHTSA response** — the flat key/value array has 80+ fields, many empty; you need to map and filter these yourself.
+3. **No batch support** — decoding 50 VINs means 50 sequential round-trips.
+4. **No SLA** — the NHTSA API is a government service; it has no uptime guarantee.
+5. **Header boilerplate** — proxy-secret validation, request IDs, CORS headers — you write it every time.
+
+---
+
+## Using the leeworks.dev VIN Decoder API
+
+The **leeworks.dev VIN Decoder API** wraps NHTSA vPIC with a 90-day SQLite cache, pre-mapped response schema, and batch endpoint — all available on RapidAPI.
+
+### Single VIN decode
+
+```js
+// Using the leeworks.dev VIN Decoder API
+const VIN = '1HGCM82633A004352';
+const API_KEY = process.env.RAPIDAPI_KEY; // Your RapidAPI key
+
+const res = await fetch(`https://vin.leeworks.dev/v1/decode?vin=${VIN}`, {
+  headers: {
+    'X-RapidAPI-Key': API_KEY,
+    'X-RapidAPI-Host': 'vin.leeworks.dev',
+  },
+});
+
+const data = await res.json();
+console.log(`${data.make} ${data.model} (${data.model_year})`);
+// → HONDA Accord (2003)
+
+// Check cache status
+const cacheStatus = res.headers.get('X-Cache'); // "HIT" or "MISS"
+console.log(`Cache: ${cacheStatus}`);
+```
+
+### Batch decode (up to 50 VINs)
+
+```js
+const vins = [
+  '1HGCM82633A004352',  // 2003 Honda Accord
+  '1FTFW1ET5DFA18803',  // 2013 Ford F-150
+  'WBA3A5G59DNP26082',  // 2013 BMW 3 Series
+];
+
+const res = await fetch('https://vin.leeworks.dev/v1/batch', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'X-RapidAPI-Key': API_KEY,
+    'X-RapidAPI-Host': 'vin.leeworks.dev',
+  },
+  body: JSON.stringify({ vins }),
+});
+
+const { results, count, cached_count } = await res.json();
+console.log(`Decoded ${count} VINs, ${cached_count} from cache`);
+
+results.forEach(r => {
+  if (r.error) {
+    console.log(`${r.vin}: ERROR — ${r.error}`);
+  } else {
+    console.log(`${r.vin}: ${r.make} ${r.model} ${r.model_year}`);
+  }
+});
+```
+
+### Health check
+
+```js
+// No auth required on /health
+const health = await fetch('https://vin.leeworks.dev/v1/health').then(r => r.json());
+console.log(`Status: ${health.status}, Cache: ${health.cache.total_entries} entries`);
+```
+
+---
+
+## Real-World Use Cases
+
+### Automotive apps and dealership software
+
+Show instant vehicle details when a user types a VIN at checkout or trade-in. Cache the result — the same VIN is often looked up dozens of times across different users.
+
+```js
+async function enrichListing(listingVin) {
+  const vehicle = await decodeVinCached(listingVin);
+  return {
+    title: `${vehicle.model_year} ${vehicle.make} ${vehicle.model} ${vehicle.trim}`,
+    engine: `${vehicle.engine_displacement_l}L ${vehicle.engine_cylinders}-cyl ${vehicle.fuel_type_primary}`,
+    drivetrain: vehicle.drive_type,
+    body: vehicle.body_class,
+  };
+}
+```
+
+### Insurance tech and underwriting
+
+Premium calculators, claims systems, and underwriting platforms need reliable vehicle specs. A VIN decode call returns body class (sedan vs. SUV vs. pickup) and engine details in under 50ms with a cache hit — fast enough for real-time quote generation.
+
+### Fleet management platforms
+
+Decode entire fleets in a single batch call. The `/v1/batch` endpoint processes up to 50 VINs per request, making it practical to seed a database of 10,000 fleet vehicles with 200 API calls rather than 10,000 sequential hits.
+
+### Used car marketplaces
+
+User-generated listings often contain VIN typos or incorrect specs. Validate and auto-fill vehicle details server-side on listing creation:
+
+```js
+app.post('/listings', async (req, res) => {
+  const { vin, ...listing } = req.body;
+
+  // Validate + enrich
+  const vehicle = await vinApi.decode(vin);
+  if (vehicle.error_code !== '0') {
+    return res.status(422).json({ error: 'Invalid or unrecognised VIN' });
+  }
+
+  const enriched = { ...listing, vin, make: vehicle.make, model: vehicle.model, year: vehicle.model_year };
+  await db.listings.create(enriched);
+  res.status(201).json(enriched);
+});
+```
+
+---
+
+## VIN Validation
+
+Before calling any API, validate the VIN client-side to save an unnecessary round-trip:
+
+```js
+function isValidVin(vin) {
+  // 17 chars, alphanumeric excluding I, O, Q
+  if (!/^[A-HJ-NPR-Z0-9]{17}$/.test(vin)) return false;
+
+  // Optional: verify check digit (position 9)
+  const weights = [8,7,6,5,4,3,2,10,0,9,8,7,6,5,4,3,2];
+  const transliteration = { A:1,B:2,C:3,D:4,E:5,F:6,G:7,H:8,
+    J:1,K:2,L:3,M:4,N:5,P:7,R:9,S:2,T:3,U:4,V:5,W:6,X:7,Y:8,Z:9 };
+
+  const vals = vin.toUpperCase().split('').map(c =>
+    /\d/.test(c) ? parseInt(c) : transliteration[c]
+  );
+
+  const sum = vals.reduce((acc, v, i) => acc + v * weights[i], 0);
+  const check = sum % 11;
+  const expected = check === 10 ? 'X' : String(check);
+
+  return vin[8].toUpperCase() === expected;
+}
+
+console.log(isValidVin('1HGCM82633A004352')); // true
+console.log(isValidVin('1HGCM82633A00435X')); // false (bad check digit)
+```
+
+---
+
+## About the Data Source
+
+The NHTSA vPIC database is maintained by the US Department of Transportation under its statutory mandate (49 U.S.C. § 30111). Manufacturers are legally required to register VIN patterns with NHTSA, so coverage is comprehensive for vehicles sold in the US market.
+
+Key facts:
+- **Coverage**: Model years 1981–present; 1980 and earlier VINs were not standardised and are not covered
+- **Accuracy**: Authoritative for the original vehicle specification; does not reflect modifications, title brands, or recall status
+- **Update frequency**: NHTSA updates the database when new model variants are registered, typically months before vehicles reach dealerships
+- **Licence**: US federal government work, public domain under 17 U.S.C. 105 — free to use commercially with no attribution requirement
+
+---
+
+## Get Started
+
+The leeworks.dev VIN Decoder API is available on RapidAPI with a free tier (100 requests/month, no credit card required):
+
+👉 **[VIN Decoder API on RapidAPI](https://rapidapi.com/leeworks/api/vin-decoder)**
+
+Full API reference, including request/response schemas and error codes:
+
+👉 **[API Documentation](/vin-decoder)**
+
+---
+
+*Built with ❤️ by [leeworks.dev](https://docs.leeworks.dev) — production-ready data APIs powered by free public-domain data sources.*
+
+</article>
+</Base>

docs-site/src/pages/index.astro

@@ -20,7 +20,7 @@ import Base from '../layouts/Base.astro';
 
   <div class="hero">
     <h1>Simple. Reliable. APIs.</h1>
-    <p>Production-ready data APIs for ZIP enrichment, public holidays, and air quality. Available on RapidAPI.</p>
+    <p>Production-ready data APIs for ZIP enrichment, public holidays, air quality, and VIN decoding. Available on RapidAPI.</p>
     <a href="https://rapidapi.com/leeworks" class="cta" target="_blank" rel="noopener">Get API Key on RapidAPI</a>
   </div>
 
@@ -52,6 +52,15 @@ import Base from '../layouts/Base.astro';
         <a href="https://rapidapi.com/leeworks/api/air-quality" target="_blank" rel="noopener">RapidAPI</a>
       </div>
     </div>
+    <div class="api-card">
+      <span class="badge wip">In Development</span>
+      <h2>VIN Decoder API</h2>
+      <p>Decode any 17-character VIN into make, model, year, trim, engine, body class, and more. Powered by the NHTSA vPIC public-domain database.</p>
+      <div class="links">
+        <a href="/vin-decoder">Docs</a>
+        <a href="https://rapidapi.com/leeworks/api/vin-decoder" target="_blank" rel="noopener">RapidAPI</a>
+      </div>
+    </div>
   </div>
 
   <footer style="text-align: center; padding: 2rem; border-top: 1px solid #2d3748; margin-top: 3rem; color: #718096; font-size: 0.875rem;">

docs-site/src/pages/vin-decoder.astro

@@ -0,0 +1,27 @@
+---
+import Base from '../layouts/Base.astro';
+
+const apiName = 'vin-decoder';
+const title = 'VIN Decoder API';
+const description = 'Decode any 17-character VIN into make, model, year, trim, engine, body class, and more. Powered by the NHTSA vPIC public-domain database.';
+---
+<Base title={title} description={description}>
+  <style>
+    #redoc-container { background: #fff; }
+  </style>
+  <div id="redoc-container"></div>
+  <script is:inline define:vars={{ specUrl: `/specs/${apiName}.yaml` }}>
+    // Load Redoc from CDN
+    var script = document.createElement('script');
+    script.src = 'https://cdn.jsdelivr.net/npm/redoc@latest/bundles/redoc.standalone.js';
+    script.onload = function () {
+      Redoc.init(specUrl, {
+        theme: {
+          colors: { primary: { main: '#667eea' } },
+          typography: { fontFamily: 'system-ui, sans-serif' },
+        },
+      }, document.getElementById('redoc-container'));
+    };
+    document.head.appendChild(script);
+  </script>
+</Base>

docs/dns.md

@@ -1,6 +1,6 @@
 # DNS Configuration
 
-**Last updated:** 2026-05-24  
+**Last updated:** 2026-05-30  
 **Status:** Planned (Phase 6 pre-launch)
 
 ---
@@ -28,6 +28,7 @@ kubectl get svc -n ingress-nginx ingress-nginx-controller -o jsonpath='{.status.
 | `status.leeworks.dev` | A | `<cluster-ingress-ip>` | Gatus status page | Yes (cert-manager) |
 | `registry.leeworks.dev` | A | `<cluster-ingress-ip>` | Container registry (Gitea) | Yes (cert-manager) |
 | `grafana.leeworks.dev` | A | `<cluster-ingress-ip>` | Grafana (internal/restricted) | Yes (cert-manager) |
+| `vin.leeworks.dev` | A | `<cluster-ingress-ip>` | VIN Decoder API | Yes (cert-manager) |
 
 ---
 
@@ -103,6 +104,7 @@ dig docs.leeworks.dev +short
 dig status.leeworks.dev +short
 dig registry.leeworks.dev +short
 dig grafana.leeworks.dev +short
+dig vin.leeworks.dev +short
 
 # Check TLS certificates (once services are deployed)
 curl -v https://zip.leeworks.dev/health 2>&1 | grep -E "SSL|certificate|issuer"
@@ -126,7 +128,7 @@ The following actions require human operator access to the DNS provider:
 
 1. Log into the DNS provider managing `leeworks.dev`
 2. Find the cluster ingress IP: `kubectl get svc -n ingress-nginx ingress-nginx-controller`
-3. Create/update the 7 A records listed in the table above
+3. Create/update the 8 A records listed in the table above
 4. Verify propagation: `dig +trace zip.leeworks.dev`
 
 DNS propagation typically takes 5–60 minutes.
@@ -143,4 +145,5 @@ DNS propagation typically takes 5–60 minutes.
 - [ ] `status.leeworks.dev` → DNS record created
 - [ ] `registry.leeworks.dev` → DNS record created
 - [ ] `grafana.leeworks.dev` → DNS record created
-- [ ] TLS certificates issued and valid for all 7 subdomains
+- [ ] `vin.leeworks.dev` → DNS record created
+- [ ] TLS certificates issued and valid for all 8 subdomains

docs/launch-announcement.md

@@ -0,0 +1,359 @@
+# Launch Announcement Copy
+
+Ready-to-copy marketing text for leeworks.dev API launch day.
+
+**Status key:**
+- **DRAFT** — copy is written and ready; needs final RapidAPI URLs inserted once issue #44 is complete
+- **READY** — all placeholders filled; copy-paste ready to publish
+
+All sections are currently **DRAFT** pending RapidAPI listing URLs from issue #44.
+
+---
+
+## Placeholder Reference
+
+When issue #44 is complete, replace these placeholders throughout this document:
+
+| Placeholder | Replace with |
+|---|---|
+| `[RAPIDAPI_ZIP_URL]` | RapidAPI listing URL for ZIP Code Enrichment API |
+| `[RAPIDAPI_HOLIDAYS_URL]` | RapidAPI listing URL for Holidays API |
+| `[RAPIDAPI_AQI_URL]` | RapidAPI listing URL for Air Quality Index API |
+| `[RAPIDAPI_PROFILE_URL]` | Your RapidAPI provider profile URL |
+
+---
+
+## 1. Hacker News — Show HN Post [DRAFT]
+
+**Title:**
+```
+Show HN: I built 3 free-data APIs on Kubernetes — ZIP enrichment, public holidays, air quality
+```
+
+**Body (paste into the "text" field):**
+```
+Three small APIs I've been building over the past few months, deployed via Flux GitOps on a self-hosted Kubernetes cluster.
+
+**What they do:**
+
+1. ZIP Code Enrichment API — turn any US ZIP code into city, state, county, timezone, area codes, and coordinates. Backed by USPS/Census public data, refreshed monthly. [RAPIDAPI_ZIP_URL]
+
+2. Public Holidays API — query official public holidays for any country and year. 90+ countries, ISO 3166 codes. Backed by Nager.Date / public government calendars. [RAPIDAPI_HOLIDAYS_URL]
+
+3. Air Quality Index API — current and historical AQI by city or coordinates. PM2.5, PM10, O3, NO2, SO2, CO. Backed by OpenAQ public dataset. [RAPIDAPI_AQI_URL]
+
+**Tech stack:** Fastify (Node.js), SQLite (data cache), Flux GitOps on Talos Linux, cert-manager + ingress-nginx, Prometheus + Grafana for metrics, Gatus for status page.
+
+**Business model:** Free tier (100 req/mo) + paid tiers ($9/$19/$49/mo) on RapidAPI. All three APIs use only public-domain data sources with no redistribution restrictions, so operating costs are cluster hosting only.
+
+**Why I built this:** I wanted to learn GitOps/Kubernetes end-to-end, build something that generates real revenue, and ship entirely on open data. The stack is overkill for 3 simple APIs — but that's the point.
+
+Code is private (it's a product), but happy to answer questions about the architecture.
+```
+
+---
+
+## 2. Reddit Posts [DRAFT]
+
+### r/webdev
+
+**Title:**
+```
+I built a ZIP code enrichment API on public Census data — city, state, county, timezone from a single lookup
+```
+
+**Body:**
+```
+Been working on a simple utility API for the past few months. ZIP Code Enrichment takes any US ZIP code and returns:
+
+- City name + state (abbreviation and full name)
+- County + FIPS code
+- Timezone (IANA name + UTC offset)
+- Area codes
+- Latitude/longitude centroid
+- ZIP type (standard, PO Box, military, unique)
+
+**The data source** is a monthly-refreshed dataset from USPS/Census Bureau — entirely public domain, no scraping.
+
+**Code example:**
+
+```javascript
+const response = await fetch('https://zip.leeworks.dev/v1/lookup?zip=10001', {
+  headers: { 'X-RapidAPI-Proxy-Secret': process.env.RAPIDAPI_KEY }
+});
+const data = await response.json();
+// { zip: "10001", city: "New York", state: "NY", county: "New York County",
+//   timezone: "America/New_York", lat: 40.7484, lon: -73.9967, ... }
+```
+
+Free tier is 100 requests/month. Paid plans start at $9/mo for 10,000 req/mo.
+
+RapidAPI listing: [RAPIDAPI_ZIP_URL]
+
+Happy to answer any questions about the stack (Fastify + SQLite + Kubernetes/Flux).
+```
+
+---
+
+### r/SideProject
+
+**Title:**
+```
+Launched 3 data APIs on RapidAPI — ZIP enrichment, public holidays, air quality. $0 → targeting $100/mo MRR
+```
+
+**Body:**
+```
+Finally shipped the thing I've been building on weekends for the past few months.
+
+**What I built:**
+Three utility APIs on RapidAPI, all backed by free public-domain data:
+
+1. **ZIP Code Enrichment** — city/state/county/timezone from a ZIP code ([RAPIDAPI_ZIP_URL])
+2. **Public Holidays** — official holidays for 90+ countries ([RAPIDAPI_HOLIDAYS_URL])
+3. **Air Quality Index** — current + historical AQI by city or coordinates ([RAPIDAPI_AQI_URL])
+
+**Stack:** Fastify + SQLite + Kubernetes (Talos Linux) + Flux GitOps + Prometheus/Grafana
+
+**Business model:**
+- Free tier: 100 req/month (marketing + trial)
+- Basic: $9/mo — 10,000 req/mo
+- Pro: $19/mo — 50,000 req/mo
+- Ultra: $49/mo — 250,000 req/mo
+
+**Data cost: $0.** All three APIs use US government / OpenAQ public datasets with no licensing fees.
+
+**Revenue so far:** $0 (launched today). Target: $100/mo net within 90 days, which is roughly 12 Basic subscribers across all three APIs.
+
+The whole build — from first commit to Kubernetes deployment — is documented in a private research log. Happy to share architecture details.
+
+What would you do differently for the pricing?
+```
+
+---
+
+### r/learnprogramming
+
+**Title:**
+```
+I used free US government data to build a ZIP code API — here's how the data pipeline works
+```
+
+**Body:**
+```
+A walkthrough of the data layer behind the ZIP Code Enrichment API I just launched.
+
+**The problem:** ZIP codes change. Cities merge. New ZIPs are added. Any ZIP lookup service needs to stay fresh.
+
+**The solution:** A monthly seed script that:
+1. Downloads the latest US ZIP code dataset from USPS/Census Bureau (public domain)
+2. Parses and normalizes ~43,000 records
+3. Inserts into SQLite with upsert logic (new ZIPs added, old ones retired)
+4. Runs automatically via a Kubernetes CronJob on the 1st of each month
+
+**The API itself** is a Fastify (Node.js) server that queries SQLite. Cold query: ~5ms. The whole thing runs in a 128MB container.
+
+**Code snippet** (the seed script core logic):
+
+```javascript
+// Fetch and parse Census ZIP dataset
+const stream = await fetch(CENSUS_ZIP_URL);
+const records = await parseCSV(stream.body);
+
+// Upsert into SQLite
+const stmt = db.prepare(`
+  INSERT INTO zips (zip, city, state, county, lat, lon, timezone, type)
+  VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+  ON CONFLICT(zip) DO UPDATE SET
+    city=excluded.city, state=excluded.state,
+    updated_at=CURRENT_TIMESTAMP
+`);
+
+for (const record of records) {
+  stmt.run([record.zip, record.city, record.state, record.county,
+            record.lat, record.lon, record.timezone, record.type]);
+}
+```
+
+The API is live on RapidAPI with a free tier: [RAPIDAPI_ZIP_URL]
+
+Happy to answer questions about SQLite performance, the seed pipeline, or the Kubernetes/Flux deployment.
+```
+
+---
+
+## 3. Indie Hackers Milestone Post [DRAFT]
+
+**Title:**
+```
+Launched 3 data APIs on RapidAPI: $0 MRR, targeting $100/mo in 90 days
+```
+
+**Body:**
+```
+### What I built
+
+Three utility APIs backed entirely by free public-domain data:
+
+- **ZIP Code Enrichment** — city/state/county/timezone/coordinates from any US ZIP ([RAPIDAPI_ZIP_URL])
+- **Public Holidays** — official holidays for 90+ countries + year ([RAPIDAPI_HOLIDAYS_URL])
+- **Air Quality Index** — current + historical AQI by city or coordinates ([RAPIDAPI_AQI_URL])
+
+### Revenue: $0 → targeting $100/mo
+
+The $100/mo target is ~12 Basic subscribers ($9/mo) across all three APIs after RapidAPI's 25% cut. Stretch: 4 Pro subscribers ($19/mo each).
+
+### Stack
+
+- **API servers:** Fastify (Node.js) + SQLite for data cache
+- **Infrastructure:** Talos Linux Kubernetes cluster (self-hosted, single-node)
+- **GitOps:** Flux CD — everything is declared in YAML, zero manual kubectl
+- **Observability:** Prometheus + Grafana, Gatus status page at status.leeworks.dev
+- **Data sources:** USPS/Census (ZIP), Nager.Date (Holidays), OpenAQ (AQI) — all public domain, $0 licensing cost
+
+### What I learned
+
+1. **GitOps is excellent for solo projects.** Flux means my cluster is always in sync with git. I've done zero manual deploys.
+2. **SQLite is underrated for read-heavy APIs.** Sub-5ms query times for cached lookups, zero infrastructure overhead vs PostgreSQL.
+3. **Public-domain data has a moat.** Anyone can build this, but most people don't bother. The data is stable, legal, and free forever.
+4. **Kubernetes is overkill — and that's fine.** I did it to learn. I now know Talos, Flux, cert-manager, ingress-nginx, Prometheus, Grafana from first principles.
+
+### What's next
+
+- Monitor first 30 days for subscriber growth
+- Build VIN Decoder as API #4 (NHTSA vPIC data, also public domain)
+- Add batch endpoints to ZIP and Holidays
+
+Would love feedback on pricing — is $9/mo entry too high or too low for a utility API with a free tier?
+```
+
+---
+
+## 4. Product Hunt Listing [DRAFT]
+
+### Tagline (60 chars max)
+```
+3 utility APIs on public data — ZIP, Holidays, Air Quality
+```
+*(58 characters ✓)*
+
+### Description (260 chars max)
+```
+Look up ZIP codes, public holidays for 90+ countries, and air quality index data — all via clean REST APIs backed by free government datasets. Free tier included. No API keys to generate — available on RapidAPI.
+```
+*(211 characters ✓)*
+
+### First Comment (Maker Note)
+```
+Hey Product Hunt! 👋
+
+I'm the developer behind leeworks.dev — three utility APIs I've been building over the past few months:
+
+**ZIP Code Enrichment** [RAPIDAPI_ZIP_URL]
+Turn any US ZIP code into city, state, county, timezone, area codes, and GPS coordinates. 43,000+ ZIP codes, refreshed monthly from USPS/Census Bureau public data.
+
+**Public Holidays API** [RAPIDAPI_HOLIDAYS_URL]
+Query official public holidays for any country and year. 90+ countries, ISO 3166 codes, backed by government calendar data. Great for payroll software, scheduling tools, and calendar apps.
+
+**Air Quality Index API** [RAPIDAPI_AQI_URL]
+Current and historical AQI readings by city or coordinates. PM2.5, PM10, O3, NO2, SO2, CO — backed by the OpenAQ public dataset covering thousands of monitoring stations worldwide.
+
+**What makes these different:**
+- All data is 100% public domain — no licensing fees, no terms restrictions
+- Free tier (100 req/mo) to try before you buy
+- Paid plans start at $9/mo for 10,000 requests/month
+- Running on Kubernetes with Prometheus monitoring and a public status page at status.leeworks.dev
+
+Happy to answer questions about the data sources, the tech stack (Fastify + SQLite + Flux GitOps), or the pricing model. Thanks for checking it out!
+```
+
+### Gallery / Screenshot URL Placeholders
+```
+1. docs-site homepage: https://docs.leeworks.dev (screenshot)
+2. Grafana dashboard: https://grafana.leeworks.dev (screenshot)
+3. status.leeworks.dev (screenshot)
+4. Example API response (ZIP lookup): code screenshot
+5. RapidAPI listing page: [RAPIDAPI_PROFILE_URL] (screenshot)
+```
+
+---
+
+## 5. Email Waitlist Message [DRAFT]
+
+**Subject line:**
+```
+leeworks.dev APIs are live — here's your free tier access
+```
+
+**Body:**
+```
+Hi there,
+
+The three APIs I've been building are now live on RapidAPI. Here's what's available and how to get started:
+
+---
+
+**ZIP Code Enrichment API**
+Turn any US ZIP code into city, state, county, timezone, area codes, and GPS coordinates — in a single API call.
+→ [RAPIDAPI_ZIP_URL]
+
+**Public Holidays API**
+Query official public holidays for any country and year. 90+ countries, ISO 3166 codes.
+→ [RAPIDAPI_HOLIDAYS_URL]
+
+**Air Quality Index API**
+Current and historical AQI by city or coordinates. PM2.5, PM10, O3, NO2, SO2, CO.
+→ [RAPIDAPI_AQI_URL]
+
+---
+
+**How to try for free:**
+1. Click any link above
+2. Subscribe to the **Free tier** (100 requests/month, no credit card needed)
+3. Copy your RapidAPI key from the dashboard
+4. Make your first request — full docs at https://docs.leeworks.dev
+
+---
+
+**Quick start (ZIP enrichment):**
+
+```bash
+curl "https://zip.leeworks.dev/v1/lookup?zip=90210" \
+  -H "X-RapidAPI-Key: YOUR_KEY" \
+  -H "X-RapidAPI-Host: zip-enrichment.p.rapidapi.com"
+```
+
+---
+
+**Want more than 100 requests/month?**
+Paid plans start at $9/mo for 10,000 requests. See the full pricing table on each API's RapidAPI listing page.
+
+Questions? Reply to this email or open an issue at https://docs.leeworks.dev/support.
+
+Thanks for your interest,
+Wyatt
+leeworks.dev
+
+---
+
+*You're receiving this because you signed up for early access. To unsubscribe, reply with "unsubscribe".*
+```
+
+---
+
+## Checklist Before Publishing
+
+Before changing any section from DRAFT to READY:
+
+- [ ] Issue #44 complete — RapidAPI listing URLs obtained
+- [ ] Replace all `[RAPIDAPI_ZIP_URL]` placeholders
+- [ ] Replace all `[RAPIDAPI_HOLIDAYS_URL]` placeholders
+- [ ] Replace all `[RAPIDAPI_AQI_URL]` placeholders
+- [ ] Replace all `[RAPIDAPI_PROFILE_URL]` placeholders
+- [ ] Verify code examples work against live endpoints
+- [ ] Confirm free tier limit is accurate (currently documented as 100 req/mo)
+- [ ] Confirm all three APIs pass pre-launch-checklist.md
+- [ ] Product Hunt gallery screenshots captured
+- [ ] Email list exported from whatever signup form was used
+
+Once all items above are checked, update the Status key at the top of this document from DRAFT to READY for each section.

docs/pre-launch-checklist.md

@@ -11,6 +11,7 @@ Use this checklist as the final go-live gate — run through every item the day
   - [ ] `zip-enrichment` pod `READY=1/1` (`kubectl get pods -n zip-enrichment`)
   - [ ] `holidays` pod `READY=1/1` (`kubectl get pods -n holidays`)
   - [ ] `air-quality` pod `READY=1/1` (`kubectl get pods -n air-quality`)
+  - [ ] `vin-decoder` pod `READY=1/1` (`kubectl get pods -n vin-decoder`)
 - [ ] `docs-site` pod Running and READY (`kubectl get pods -n docs-site`)
 - [ ] Prometheus scraping all three API services (check Prometheus Targets UI)
 - [ ] Grafana dashboard accessible at `grafana.leeworks.dev`
@@ -25,8 +26,9 @@ Use this checklist as the final go-live gate — run through every item the day
 - [ ] `docs.leeworks.dev` → cluster ingress IP
 - [ ] `status.leeworks.dev` → cluster ingress IP
 - [ ] `registry.leeworks.dev` → cluster ingress IP
+- [ ] `vin.leeworks.dev` → cluster ingress IP (`dig vin.leeworks.dev +short` + `curl -I https://vin.leeworks.dev`)
 - [ ] `grafana.leeworks.dev` → cluster ingress IP
-- [ ] TLS certificates issued for all 7 subdomains (`kubectl get certificates -A`)
+- [ ] TLS certificates issued for all 8 subdomains (`kubectl get certificates -A`)
 
 ---
 
@@ -38,9 +40,12 @@ Use this checklist as the final go-live gate — run through every item the day
 - [ ] `GET /zip/{zip}` returns correct data for a sample ZIP code (e.g. `curl https://zip.leeworks.dev/zip/10001`)
 - [ ] `GET /holidays/{year}` returns correct data (e.g. `curl https://holidays.leeworks.dev/holidays/2026`)
 - [ ] `GET /aqi/{city}` returns correct data (e.g. `curl https://aqi.leeworks.dev/aqi/New%20York`)
+- [ ] `GET /v1/health` returns HTTP 200 on **vin-decoder** (`curl https://vin.leeworks.dev/v1/health`)
+- [ ] `GET /v1/decode?vin=1HGCM82633A004352` returns correct make/model/year data
+- [ ] Request **without** `X-RapidAPI-Proxy-Secret` returns HTTP 403 on **vin-decoder** (`curl https://vin.leeworks.dev/v1/decode?vin=1HGCM82633A004352`)
 - [ ] Request **without** `X-RapidAPI-Proxy-Secret` returns HTTP 403 on all three APIs
 - [ ] `docs.leeworks.dev/pricing` loads correctly
-- [ ] `status.leeworks.dev` shows all three APIs as **UP**
+- [ ] `status.leeworks.dev` shows all **four** APIs as **UP**
 
 ---
 
@@ -50,6 +55,8 @@ Use this checklist as the final go-live gate — run through every item the day
 - [ ] `docs/legal/privacy-policy.md` committed and reachable at `docs.leeworks.dev/legal/privacy-policy`
 - [ ] `docs/legal/acceptable-use-policy.md` committed and reachable at `docs.leeworks.dev/legal/acceptable-use-policy`
 - [ ] All three APIs listed on RapidAPI with **Free + 3 paid tiers** (leeworks-agents/api-company#44)
+- [ ] VIN Decoder listed on RapidAPI with Free + 3 paid tiers (leeworks-agents/api-company#131)
+- [ ] `rapidapi-proxy-secret` updated with real RapidAPI value in `vin-decoder` namespace (leeworks-agents/api-company#128)
 - [ ] PayPal linked to RapidAPI (leeworks-agents/api-company#19)
 - [ ] `rapidapi-proxy-secret` updated with **real** RapidAPI values in all 3 namespaces (leeworks-agents/api-company#81)
 

docs/rapidapi-listings.md

@@ -193,6 +193,77 @@ air quality, AQI, PM2.5, PM10, air pollution, smog, ozone, nitrogen dioxide, env
 
 ---
 
+---
+
+## 4. VIN Decoder API
+
+### API Name
+VIN Decoder API
+
+### Tagline
+Decode any vehicle VIN into make, model, year, engine, and trim — powered by NHTSA vPIC.
+
+### Short Description (≤ 300 chars)
+Decode any 17-character Vehicle Identification Number into structured vehicle data: make, model, year, trim, body style, engine specs, transmission, and assembly plant. Backed by the NHTSA vPIC public database with 90-day result caching.
+
+### Long Description
+
+Unlock the full story behind any Vehicle Identification Number with a single API call.
+
+**What you get per VIN:**
+- Make, model, model year, and trim level
+- Body class (Sedan, SUV, Pickup, etc.) and drive type (FWD, RWD, AWD, 4WD)
+- Engine displacement (CC and litres) and cylinder count
+- Primary fuel type (Gasoline, Diesel, Electric, Hybrid, etc.)
+- Transmission style (Automatic, Manual, CVT) and speed count
+- Assembly plant city, state, and country
+- Full manufacturer name and NHTSA vehicle type classification
+- NHTSA decode error code and text for non-standard VINs
+
+**Data source:** NHTSA Product Information Catalog and Vehicle Listing (vPIC) — US federal government public-domain data, always current. No licensing fees.
+
+**Coverage:** Model years 1981–present. All major domestic and import manufacturers registered with NHTSA.
+
+**Caching:** Decoded VINs are cached for 90 days in a local SQLite store. The `X-Cache: HIT/MISS` response header tells you whether the result came from cache or a live NHTSA lookup.
+
+**Use cases:**
+- Used-car marketplaces — enrich listings with decoded specs at scale
+- Insurance platforms — auto-populate vehicle details from VIN at quote time
+- Fleet management — maintain structured vehicle inventories without manual entry
+- Automotive valuation tools — feed year/make/model/trim into pricing algorithms
+- Recall & warranty systems — match VINs to manufacturer service campaigns
+- Registration & titling apps — validate and enrich VIN data in DMV workflows
+
+**Endpoints:**
+- `GET /v1/decode` — decode a single VIN
+- `POST /v1/batch` — decode up to 50 VINs in one request
+- `GET /v1/health` — service health check (no auth required)
+
+### Category
+Data / Automotive / Transportation
+
+### Plan Table
+
+| Tier | Price/month | Requests/month | Rate limit |
+|------|-------------|----------------|------------|
+| Free | $0 | 100 req/mo | 5 req/min |
+| Basic | $9 | 5,000 req/mo | 60 req/min |
+| Pro | $19 | 20,000 req/mo | 200 req/min |
+| Ultra | $49 | 100,000 req/mo | 500 req/min |
+
+### Endpoint Descriptions
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /v1/decode?vin={vin}` | Decodes a single 17-character VIN. Returns structured vehicle attributes including make, model, year, engine, body, drivetrain, and plant info. Optional `?raw=true` includes the full NHTSA vPIC response. |
+| `POST /v1/batch` | Accepts a JSON body with a `vins` array (1–50 VINs). Returns one decoded result (or error) per VIN in input order, plus aggregate counts for `cached_count` and `error_count`. |
+| `GET /v1/health` | Returns service status, uptime, cache stats (entries, hit rate, size), and NHTSA upstream reachability. No `X-RapidAPI-Proxy-Secret` required. |
+
+### Keywords
+VIN decoder, vehicle identification number, car lookup, NHTSA, make model year, automotive API, vehicle data, VIN lookup, auto specs, fleet management
+
+---
+
 ## Tagline Length Validation
 
 Run to confirm all taglines are ≤ 120 characters:

docs/secrets-checklist.md

@@ -19,6 +19,9 @@ Follow this list top-to-bottom; each step unblocks the next.
 - [ ] 8. `gitea-registry` (zip-enrichment, holidays, air-quality, docs-site) — imagePullSecret for pods pulling from `registry.leeworks.dev`
 - [ ] 9. `gitea-image-automation-token` (flux-system) — write-scoped token for Flux ImageUpdateAutomation to push image-tag commits
 - [ ] 10. `rapidapi-proxy-secret` (zip-enrichment, holidays, air-quality) — RapidAPI Proxy Secret for server-side request validation
+- [ ] 11. `GITEA_TOKEN` Actions secret in `leeworks-agents/vin-decoder` repo — enables CI image push for VIN Decoder (leeworks-agents/api-company#126)
+- [ ] 12. `gitea-registry` imagePullSecret in `vin-decoder` namespace — enables pod image pulls from `registry.leeworks.dev` (leeworks-agents/api-company#127)
+- [ ] 13. `rapidapi-proxy-secret` in `vin-decoder` namespace — enables RapidAPI proxy-secret header validation (leeworks-agents/api-company#128)
 
 ---
 
@@ -194,6 +197,68 @@ done
 ```
 
 
+### 11. `GITEA_TOKEN` Actions secret in `leeworks-agents/vin-decoder`
+
+| Field    | Value |
+|----------|-------|
+| Name     | `GITEA_TOKEN` |
+| Scope    | Gitea Actions Secret — set in repo Settings |
+| Purpose  | CI workflow pushes container image to `registry.leeworks.dev/vin-decoder/api:<sha>` |
+| Source   | Gitea token with `write:packages` scope (reuse from item #5 if it has `write:packages`) |
+| Tracked  | leeworks-agents/api-company#126 |
+| Unblocks | CI image push for VIN Decoder |
+
+Path: **Gitea → leeworks-agents/vin-decoder → Settings → Secrets → `GITEA_TOKEN`**
+
+---
+
+### 12. `gitea-registry` imagePullSecret in `vin-decoder` namespace
+
+| Field     | Value |
+|-----------|-------|
+| Name      | `gitea-registry` |
+| Namespace | `vin-decoder` |
+| Type      | `kubernetes.io/dockerconfigjson` |
+| Purpose   | Allows VIN Decoder pods to pull images from `registry.leeworks.dev` without ImagePullBackOff |
+| Tracked   | leeworks-agents/api-company#127 |
+
+```bash
+kubectl create namespace vin-decoder --dry-run=client -o yaml | kubectl apply -f -
+kubectl create secret docker-registry gitea-registry \
+  --namespace=vin-decoder \
+  --docker-server=registry.leeworks.dev \
+  --docker-username=leeworks-agents \
+  --docker-password=<GITEA_TOKEN_WITH_READ_PACKAGES> \
+  --docker-email=agent@leeworks.dev
+```
+
+---
+
+### 13. `rapidapi-proxy-secret` in `vin-decoder` namespace
+
+| Field     | Value |
+|-----------|-------|
+| Name      | `rapidapi-proxy-secret` |
+| Namespace | `vin-decoder` |
+| Purpose   | VIN Decoder validates `X-RapidAPI-Proxy-Secret` header; returns HTTP 403 if missing/wrong |
+| Source    | RapidAPI dashboard → VIN Decoder listing → Settings → Security → Proxy Secret |
+| Tracked   | leeworks-agents/api-company#128 |
+
+```bash
+# Placeholder (unblocks deploy testing):
+kubectl create secret generic rapidapi-proxy-secret \
+  --namespace=vin-decoder \
+  --from-literal=X-RapidAPI-Proxy-Secret=PLACEHOLDER_REPLACE_AFTER_RAPIDAPI_LISTING
+
+# Update with real value after RapidAPI listing (#131) is live:
+kubectl create secret generic rapidapi-proxy-secret \
+  -n vin-decoder \
+  --from-literal=X-RapidAPI-Proxy-Secret=<VIN_RAPIDAPI_PROXY_SECRET> \
+  --save-config --dry-run=client -o yaml | kubectl apply -f -
+```
+
+---
+
 ## Dependency Order
 
 ```

flux/image-automation/imagepolicies.yaml

@@ -40,6 +40,18 @@ spec:
 ---
 apiVersion: image.toolkit.fluxcd.io/v1beta2
 kind: ImagePolicy
+metadata:
+  name: vin-decoder
+  namespace: flux-system
+spec:
+  imageRepositoryRef:
+    name: vin-decoder
+  policy:
+    semver:
+      range: ">=0.1.0"
+---
+apiVersion: image.toolkit.fluxcd.io/v1beta2
+kind: ImagePolicy
 metadata:
   name: docs-site
   namespace: flux-system

flux/image-automation/imagerepositories.yaml

@@ -35,6 +35,17 @@ spec:
 ---
 apiVersion: image.toolkit.fluxcd.io/v1beta2
 kind: ImageRepository
+metadata:
+  name: vin-decoder
+  namespace: flux-system
+spec:
+  image: registry.leeworks.dev/vin-decoder/api
+  interval: 5m
+  secretRef:
+    name: gitea-leeworks-agents-token
+---
+apiVersion: image.toolkit.fluxcd.io/v1beta2
+kind: ImageRepository
 metadata:
   name: docs-site
   namespace: flux-system

flux/monitoring/gatus-helmrelease.yaml

@@ -68,6 +68,15 @@ spec:
               description: "Air Quality API is down"
               send-on-resolved: true
 
+
+        - name: VIN Decoder API
+          url: https://vin.leeworks.dev/v1/health
+          interval: 1m
+          conditions:
+            - "[STATUS] == 200"
+            - "[RESPONSE_TIME] < 1000"
+          alerts:
+            - type: slack
         - name: Docs Site
           url: https://docs.leeworks.dev
           interval: 5m