Merge pull request '[Phase 5] docs-site: VIN Decoder Redoc page, index card, and SEO blog post' (#125) from feature/issue-123-124-vin-decoder-docs-blog into main

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>