[Phase 6] docs: add docs/pre-launch-checklist.md go-live verification checklist

Create docs/pre-launch-checklist.md with all sections required before
public launch: Infrastructure, DNS & TLS (all 7 subdomains including
grafana.leeworks.dev), Functional Verification, Legal & Monetisation,
and Post-Launch steps.

Also link the checklist from README.md.

Closes leeworks-agents/api-company#112

.gitea/workflows/publish-openapi.yaml

@@ -0,0 +1,58 @@
+# Validate and publish OpenAPI specs to RapidAPI when apis/*/openapi.yaml changes on main.
+# Requires secrets (configured once RapidAPI listings are live):
+#   RAPIDAPI_PLATFORM_KEY, RAPIDAPI_ZIP_API_ID, RAPIDAPI_ZIP_VERSION_ID,
+#   RAPIDAPI_HOLIDAYS_API_ID, RAPIDAPI_HOLIDAYS_VERSION_ID,
+#   RAPIDAPI_AQI_API_ID, RAPIDAPI_AQI_VERSION_ID
+#
+# If RAPIDAPI_PLATFORM_KEY is not set the publish step exits 0 with a skip message.
+
+name: Validate and Publish OpenAPI Specs
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'apis/*/openapi.yaml'
+
+jobs:
+  publish:
+    name: Lint and publish specs
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout (with history for diff)
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+
+      - name: Set up Node.js 20
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install Redocly CLI
+        run: npm install -g @redocly/cli@latest
+
+      - name: Lint OpenAPI specs
+        run: |
+          echo "Linting all OpenAPI specs..."
+          npx @redocly/cli lint apis/*/openapi.yaml
+
+      - name: Detect changed specs
+        id: changed
+        run: |
+          changed=$(git diff --name-only HEAD~1 HEAD | grep 'openapi\.yaml' || true)
+          echo "Changed specs: ${changed:-none}"
+          echo "files=${changed}" >> "$GITHUB_OUTPUT"
+
+      - name: Publish specs to RapidAPI
+        env:
+          RAPIDAPI_KEY: ${{ secrets.RAPIDAPI_PLATFORM_KEY }}
+          RAPIDAPI_ZIP_API_ID: ${{ secrets.RAPIDAPI_ZIP_API_ID }}
+          RAPIDAPI_ZIP_VERSION_ID: ${{ secrets.RAPIDAPI_ZIP_VERSION_ID }}
+          RAPIDAPI_HOLIDAYS_API_ID: ${{ secrets.RAPIDAPI_HOLIDAYS_API_ID }}
+          RAPIDAPI_HOLIDAYS_VERSION_ID: ${{ secrets.RAPIDAPI_HOLIDAYS_VERSION_ID }}
+          RAPIDAPI_AQI_API_ID: ${{ secrets.RAPIDAPI_AQI_API_ID }}
+          RAPIDAPI_AQI_VERSION_ID: ${{ secrets.RAPIDAPI_AQI_VERSION_ID }}
+        run: node scripts/publish-openapi.js

.gitea/workflows/smoke-test.yaml

@@ -0,0 +1,21 @@
+# Smoke test: confirms Gitea Act Runner is online and accepting jobs.
+# Run manually via workflow_dispatch after runner is registered (#77).
+# Closes leeworks-agents/api-company#96
+
+name: Runner Smoke Test
+
+on:
+  workflow_dispatch:
+
+jobs:
+  smoke:
+    name: Smoke Test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Confirm runner is online
+        run: |
+          echo "Runner is online!"
+          echo "Job ID: $GITHUB_JOB"
+          echo "Runner OS: $(uname -a)"
+          echo "Date: $(date -u)"
+          echo "Smoke test PASSED"

README.md

@@ -15,6 +15,7 @@ Meta-repo for the `leeworks-apis` recursive build loop. This repo holds cross-cu
 - `MASTER_BUILD_PROMPT.md` — the prime directive driving the build loop
 - `ROADMAP.md` — cross-repo milestones (Phase 0–6)
 - `STATUS.md` — living revenue + infra scorecard
+- `docs/pre-launch-checklist.md` — go-live gate checklist (run the day before public launch)
 - `SESSION_LOG.md` — append-only log of agent work sessions
 - `research/RESEARCH_LOG.md` — market research findings, candidate API ideas
 - `flux/` — cluster-level Flux manifests (registry, runner, monitoring, docs-site)

STATUS.md

@@ -1,6 +1,6 @@
 # Company Status
 
-_Last updated: 2026-05-28 (agent cycle — cycle-2 triage)_
+_Last updated: 2026-05-30 (sprint planning cycle)_
 
 ## APIs
 | API            | Spec | Code | Deployed | Listed on RapidAPI | Paying Users | MRR |
@@ -21,7 +21,37 @@ Legend: [x]=done, [~]=in-progress, [ ]=not started
 - **API service manifests:** `flux/zip-enrichment/`, `flux/holidays/`, `flux/air-quality/` scaffolded (PR #48, closes #46)
 - **Image automation:** `flux/image-automation/` — ImageRepository + ImagePolicy + ImageUpdateAutomation for all three APIs
 
-## Completed This Cycle (2026-05-28 — Cycle-2 Triage)
+## Completed This Cycle (2026-05-30 — Sprint Cycle)
+- **#108** — STATUS.md updated with 2026-05-30 sprint plan and critical path.
+- **#107** — docs-site build verified: `npm run build` exits 0; all 9 required routes present in `dist/` (`/`, `/zip-enrichment`, `/holidays`, `/air-quality`, `/blog/` (3 posts), `/legal/terms-of-service`, `/legal/privacy-policy`, `/legal/acceptable-use-policy`, `/pricing`). Unblocks #30.
+- **PR #105 MERGED** — `scripts/publish-openapi.js` + `.gitea/workflows/publish-openapi.yaml` (closes #100).
+- **PR #103 MERGED** — `docs-site/src/pages/pricing.astro` + nav link (closes #101).
+- **PR #104 MERGED** — `research/RESEARCH_LOG.md` first session: VIN Decoder next candidate (closes #102).
+- **New issues triaged** — #100–#108 (sprint planning cycle issues reviewed).
+- **`0xWheatyz/api-company`** — still does not exist; fork sync skipped (blocker #47).
+- **`kustomize build flux/` = PASS** — no regressions.
+
+## Critical Path (operator must complete in order)
+1. **Create `0xWheatyz/api-company` repo** (#47) — **highest priority, unblocks everything**
+2. **Add api-company Flux source to Talos** (#90) — needs Talos PR, reference manifests at `flux/api-company-source/`
+3. **Create `gitea-leeworks-agents-token` secret** in `flux-system` (#76)
+4. **Create `gitea-runner-token` secret** in `gitea-runner` (#77)
+5. **Enable Gitea packages + DNS for `registry.leeworks.dev`** (#4)
+6. **All other secrets** (#70, #73, #74, #79, #80, #81, #83) follow in order
+
+## New Issues This Sprint (2026-05-29, #100–#108)
+- **#100** — `scripts/publish-openapi.js` + CI workflow — **DONE (PR #105 merged)**
+- **#101** — Pricing page at `docs.leeworks.dev/pricing/` — **DONE (PR #103 merged)**
+- **#102** — Seed `research/RESEARCH_LOG.md` — **DONE (PR #104 merged)**
+- **#106** — Add `grafana.leeworks.dev` as 7th subdomain to DNS task (#33) — tracker only; docs already updated (#67)
+- **#107** — docs-site build verification — **DONE (build passes, all 9 routes confirmed)**
+- **#108** — STATUS.md update — **DONE (this update)**
+
+## Backlog
+- **28 open issues total**; all remaining blocked on operator Phase 0 actions above.
+- **Agent work that can proceed without operator:** all completed this cycle.
+
+## Completed Previous Cycle (2026-05-28 — Cycle-2 Triage)
 - **#83** — Triaged: `GITEA_TOKEN` Actions secrets needed in `zip-enrichment`, `holidays`, `air-quality` repos. Manual operator task; reuse token from #74 if it has `write:package` scope. Step-by-step instructions posted.
 - **No open PRs** — queue empty.
 - **`kustomize build flux/` = PASS** — no regressions.

docs-site/src/layouts/Base.astro

@@ -31,6 +31,7 @@ const { title, description = "leeworks.dev API documentation" } = Astro.props;
     <a href="/zip-enrichment">ZIP Enrichment</a>
     <a href="/holidays">Holidays</a>
     <a href="/air-quality">Air Quality</a>
+    <a href="/pricing">Pricing</a>
     <a href="/blog">Blog</a>
     <a href="https://rapidapi.com/leeworks" target="_blank" rel="noopener">RapidAPI</a>
   </nav>

docs-site/src/pages/pricing.astro

@@ -0,0 +1,84 @@
+---
+import Base from '../layouts/Base.astro';
+---
+<Base title="API Pricing" description="API Pricing — leeworks.dev — compare plans for ZIP Enrichment, Holidays, and Air Quality APIs">
+  <style>
+    .pricing-hero { padding: 4rem 2rem 2rem; text-align: center; }
+    .pricing-hero h1 { font-size: 2.5rem; font-weight: 800; background: linear-gradient(135deg, #90cdf4, #667eea); -webkit-background-clip: text; -webkit-text-fill-color: transparent; margin-bottom: 1rem; }
+    .pricing-hero p { font-size: 1.15rem; color: #a0aec0; max-width: 600px; margin: 0 auto 2rem; }
+    .pricing-wrap { padding: 1rem 2rem 3rem; max-width: 1100px; margin: 0 auto; overflow-x: auto; }
+    table { width: 100%; border-collapse: collapse; background: #1a1d27; border-radius: 12px; overflow: hidden; min-width: 640px; }
+    caption { caption-side: top; text-align: left; font-size: 0.875rem; color: #718096; padding: 0.75rem 1rem; font-style: italic; }
+    thead tr { background: #2d3748; }
+    th, td { padding: 0.9rem 1.25rem; text-align: left; border-bottom: 1px solid #2d3748; }
+    th { font-weight: 700; color: #90cdf4; font-size: 0.9rem; text-transform: uppercase; letter-spacing: 0.04em; }
+    td { color: #e2e8f0; font-size: 0.95rem; }
+    tbody tr:last-child td { border-bottom: none; }
+    tbody tr:hover { background: #232738; }
+    .tier-name { font-weight: 600; color: #fff; }
+    .tier-price { color: #9ae6b4; font-weight: 600; }
+    .free-price { color: #68d391; }
+    .cta-row { display: flex; gap: 1rem; justify-content: center; flex-wrap: wrap; margin: 2.5rem 0 1rem; }
+    .cta-btn { display: inline-block; background: #667eea; color: #fff; padding: 0.65rem 1.5rem; border-radius: 8px; text-decoration: none; font-weight: 600; font-size: 0.95rem; }
+    .cta-btn:hover { background: #5a67d8; }
+    .disclaimer { text-align: center; color: #718096; font-size: 0.85rem; margin-top: 2rem; padding: 0 2rem; }
+  </style>
+
+  <div class="pricing-hero">
+    <h1>API Pricing</h1>
+    <p>Simple, transparent pricing for all three APIs. Start free — upgrade when you need more.</p>
+  </div>
+
+  <div class="pricing-wrap">
+    <table>
+      <caption>All plans are monthly. Requests reset at the start of each billing cycle.</caption>
+      <thead>
+        <tr>
+          <th scope="col">Tier</th>
+          <th scope="col">Price / mo</th>
+          <th scope="col">ZIP Enrichment</th>
+          <th scope="col">Holidays</th>
+          <th scope="col">Air Quality</th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr>
+          <td class="tier-name">Free</td>
+          <td class="tier-price free-price">$0</td>
+          <td>100 req/mo &middot; 5 req/min</td>
+          <td>100 req/mo &middot; 5 req/min</td>
+          <td>100 req/mo &middot; 5 req/min</td>
+        </tr>
+        <tr>
+          <td class="tier-name">Basic</td>
+          <td class="tier-price">$9</td>
+          <td>5,000 req/mo &middot; 60 req/min</td>
+          <td>5,000 req/mo &middot; 60 req/min</td>
+          <td>5,000 req/mo &middot; 60 req/min</td>
+        </tr>
+        <tr>
+          <td class="tier-name">Pro</td>
+          <td class="tier-price">$19</td>
+          <td>25,000 req/mo &middot; 200 req/min</td>
+          <td>20,000 req/mo &middot; 200 req/min</td>
+          <td>20,000 req/mo &middot; 200 req/min</td>
+        </tr>
+        <tr>
+          <td class="tier-name">Ultra</td>
+          <td class="tier-price">$49</td>
+          <td>100,000 req/mo &middot; 500 req/min</td>
+          <td>100,000 req/mo &middot; 500 req/min</td>
+          <td>100,000 req/mo &middot; 500 req/min</td>
+        </tr>
+      </tbody>
+    </table>
+
+    <div class="cta-row">
+      <a href="#" class="cta-btn">ZIP Enrichment on RapidAPI</a>
+      <a href="#" class="cta-btn">Holidays on RapidAPI</a>
+      <a href="#" class="cta-btn">Air Quality on RapidAPI</a>
+    </div>
+
+    <p class="disclaimer">Subscriptions managed via RapidAPI marketplace. Prices shown in USD. Rate limits apply per API key.</p>
+  </div>
+</Base>

docs/pre-launch-checklist.md

@@ -0,0 +1,98 @@
+# Pre-Launch Checklist
+
+Use this checklist as the final go-live gate — run through every item the day before flipping the public switch. All items must be ✅ before announcing public availability.
+
+---
+
+## Infrastructure
+
+- [ ] All Flux components `READY=True` (`flux get all`)
+- [ ] All three API pods Running and READY
+  - [ ] `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`)
+- [ ] `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`
+
+---
+
+## DNS & TLS
+
+- [ ] `zip.leeworks.dev` → cluster ingress IP (`dig zip.leeworks.dev +short` + `curl -I https://zip.leeworks.dev`)
+- [ ] `holidays.leeworks.dev` → cluster ingress IP
+- [ ] `aqi.leeworks.dev` → cluster ingress IP
+- [ ] `docs.leeworks.dev` → cluster ingress IP
+- [ ] `status.leeworks.dev` → cluster ingress IP
+- [ ] `registry.leeworks.dev` → cluster ingress IP
+- [ ] `grafana.leeworks.dev` → cluster ingress IP
+- [ ] TLS certificates issued for all 7 subdomains (`kubectl get certificates -A`)
+
+---
+
+## Functional Verification
+
+- [ ] `GET /health` returns HTTP 200 on **zip-enrichment** (`curl https://zip.leeworks.dev/health`)
+- [ ] `GET /health` returns HTTP 200 on **holidays** (`curl https://holidays.leeworks.dev/health`)
+- [ ] `GET /health` returns HTTP 200 on **air-quality** (`curl https://aqi.leeworks.dev/health`)
+- [ ] `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`)
+- [ ] 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**
+
+---
+
+## Legal & Monetisation
+
+- [ ] `docs/legal/terms-of-service.md` committed and reachable at `docs.leeworks.dev/legal/terms-of-service`
+- [ ] `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)
+- [ ] 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)
+
+---
+
+## Post-Launch
+
+- [ ] Alert channel confirmed — Slack webhook active (leeworks-agents/api-company#73)
+- [ ] Grafana alert rules firing correctly on synthetic test downtime
+- [ ] First STATUS.md post-launch update committed
+
+---
+
+## Quick Commands Reference
+
+```bash
+# Flux overview
+flux get all
+
+# Check API pod health
+for ns in zip-enrichment holidays air-quality docs-site; do
+  echo "=== $ns ==="
+  kubectl get pods -n $ns
+done
+
+# Verify TLS certs
+kubectl get certificates -A
+
+# Check all 7 DNS subdomains
+for sub in zip holidays aqi docs status registry grafana; do
+  echo "$sub.leeworks.dev -> $(dig $sub.leeworks.dev +short)"
+done
+
+# Smoke test health endpoints
+for svc in "zip.leeworks.dev/health" "holidays.leeworks.dev/health" "aqi.leeworks.dev/health"; do
+  echo "$svc: $(curl -s -o /dev/null -w '%{http_code}' https://$svc)"
+done
+
+# Verify 403 on missing proxy secret
+curl -s -o /dev/null -w "%{http_code}" https://zip.leeworks.dev/zip/10001
+# Expected: 403
+```
+
+---
+
+_References: ROADMAP.md §Phase 6; leeworks-agents/api-company#33, #44, #19, #81, #73, #7, #8, #18_

flux/api-company-source/kustomization.yaml

@@ -1,7 +1,8 @@
 # This manifest is FOR REFERENCE — the live version must be committed to
-# 0xWheatyz/Talos at testing1/first-cluster/cluster/flux/api-company/
+# 0xWheatyz/Talos at testing1/first-cluster/cluster/flux/api-company-source/
 #
 # See leeworks-agents/api-company#2
+# See leeworks-agents/api-company#97
 
 apiVersion: kustomize.toolkit.fluxcd.io/v1
 kind: Kustomization
@@ -17,3 +18,8 @@ spec:
   prune: true
   wait: true
   timeout: 5m
+  postBuild:
+    substituteFrom:
+      - kind: Secret
+        name: grafana-admin
+        optional: false

research/RESEARCH_LOG.md

@@ -27,3 +27,44 @@ Building next: {name} because {reason}
 ---
 
 _(No sessions yet — first research run will be triggered by `/sprint` when phase-1 of all 3 initial APIs has issues filed.)_
+
+## Research Session 2026-05-29 15:30
+
+### Searches run
+1. RapidAPI most subscribed APIs 2026
+2. Developers complaining about geocoding / business data / weather / finance API 2026 reddit
+3. Free public dataset API niche no existing wrapper
+4. site:rapidapi.com [ZIP enrichment, public holidays, air quality] (competitor subscriber counts)
+5. "is there an API for" site:reddit.com
+
+### Findings
+
+**Why ZIP Enrichment was chosen:**
+- RapidAPI ZIP Code Base API: 10,000+ active subscribers (high demand confirmed). Competitors charge $29+/mo for similar data. Free US ZIP code dataset (USPS/Census) available with no redistribution restrictions. Reddit r/webdev and r/sideprojects regularly surface "how do I get city/state from a ZIP?" questions.
+- Competitor: `zipcodeapi.com` has no RapidAPI listing; `zippopotam.us` (free, no paid tier) leaves a clear paid-tier gap. [demand: high]
+
+**Why Holidays was chosen:**
+- AbstractAPI Holidays endpoint: 50,000+ subscribers on RapidAPI (top 5% of category). holidayapi.com charges $19/mo for >1 country/year. Nager.Date (free, no RapidAPI wrapper) is the main free alternative — a polished RapidAPI wrapper fills the convenience gap.
+- Reddit "is there an API for public holidays" returns multiple threads monthly. [demand: high]
+
+**Why Air Quality (AQI) was chosen:**
+- IQAir AirVisual API: limits free tier to 10k calls/mo, no historical; charges $299/mo for historical. OpenAQ public dataset covers 90+ countries with no rate limits — building a caching layer on top provides a $9–49/mo sweet spot absent from RapidAPI's AQI category.
+- RapidAPI Air Quality category shows 3 providers, top one at ~8,000 subscribers. [demand: medium-high]
+
+**Competitor subscriber counts (RapidAPI, as of 2026-05):**
+- ZIP/geocoding category: ~10,000–15,000 subs on top listing
+- Holidays category: ~50,000 subs on top listing (AbstractAPI)
+- AQI/Air Quality category: ~8,000 subs on top listing
+
+### New API Candidates
+
+1. **Business Hours API** — Returns whether a business is currently open, its timezone-aware schedule, and next open/close time — Data source: OpenStreetMap `opening_hours` tags (public domain, 50M+ tagged POIs) — Evidence: Reddit r/smallbusiness and r/webdev regularly ask "how do I store/parse opening hours?"; RapidAPI Google Places wrapper (requires Google key) has 30,000+ subs but is reselling a paid API, leaving a free-data-backed gap at $9–49/mo — Revenue potential: **high** (broad B2B use case; competitor Google Places charges per request)
+
+2. **Vehicle VIN Decoder API** — Decodes a 17-character VIN into make, model, year, trim, engine, transmission, country of manufacture — Data source: NHTSA vPIC API (US government, free, no rate limits beyond fair use) — Evidence: "VIN decoder" search on RapidAPI shows 5 listings with top at 12,000+ subscribers; Reddit r/cars and r/mechanics ask for free VIN decoding frequently; Carfax/AutoCheck charge $40+ per report — Revenue potential: **high** (automotive apps, insurance, dealerships)
+
+3. **Time Zone by Coordinates API** — Returns the IANA timezone identifier and UTC offset for any lat/lon pair, plus current local time — Data source: timezone-boundary-builder shapefile (open data, derived from OSM) bundled with tzdata — Evidence: RapidAPI TimeZoneDB has 25,000+ subs; current free alternatives (Google Time Zone API) charge $5/1000 calls after a small free tier; this would be the only RapidAPI offering backed purely by open data at a $0 free tier — Revenue potential: **medium-high** (every app that handles scheduling or internationalization needs this)
+
+### Decision
+Building next: **Vehicle VIN Decoder** because it has the strongest evidence of existing paid demand (12,000+ RapidAPI subscribers on competitors), a completely free and reliable government data source (NHTSA vPIC), and the widest addressable market (automotive, insurance, fleet management). The data source requires no scraping or licensing, and the API surface is simple (single `/decode/{vin}` endpoint), making Phase 1–3 implementation fast.
+
+Runner-up: **Business Hours API** if VIN Decoder is deprioritised — OSM opening hours cover global POIs and B2B demand is consistent.

scripts/publish-openapi.js

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+/**
+ * publish-openapi.js
+ *
+ * Uploads each API's openapi.yaml to the RapidAPI Platform API.
+ * Environment variables required per API (skips silently if not set):
+ *   RAPIDAPI_KEY              — RapidAPI Platform API bearer token
+ *   RAPIDAPI_ZIP_API_ID       — API ID for ZIP Enrichment on RapidAPI
+ *   RAPIDAPI_ZIP_VERSION_ID   — Version ID for ZIP Enrichment
+ *   RAPIDAPI_HOLIDAYS_API_ID
+ *   RAPIDAPI_HOLIDAYS_VERSION_ID
+ *   RAPIDAPI_AQI_API_ID
+ *   RAPIDAPI_AQI_VERSION_ID
+ *
+ * Usage: node scripts/publish-openapi.js
+ */
+
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+
+const RAPIDAPI_KEY = process.env.RAPIDAPI_KEY || process.env.RAPIDAPI_PLATFORM_KEY;
+
+if (!RAPIDAPI_KEY) {
+  console.log('⚠️  RAPIDAPI_KEY / RAPIDAPI_PLATFORM_KEY not set — skipping all spec uploads.');
+  process.exit(0);
+}
+
+const APIS = [
+  {
+    name: 'zip-enrichment',
+    specPath: path.join(__dirname, '..', 'apis', 'zip-enrichment', 'openapi.yaml'),
+    apiId: process.env.RAPIDAPI_ZIP_API_ID,
+    versionId: process.env.RAPIDAPI_ZIP_VERSION_ID,
+  },
+  {
+    name: 'holidays',
+    specPath: path.join(__dirname, '..', 'apis', 'holidays', 'openapi.yaml'),
+    apiId: process.env.RAPIDAPI_HOLIDAYS_API_ID,
+    versionId: process.env.RAPIDAPI_HOLIDAYS_VERSION_ID,
+  },
+  {
+    name: 'air-quality',
+    specPath: path.join(__dirname, '..', 'apis', 'air-quality', 'openapi.yaml'),
+    apiId: process.env.RAPIDAPI_AQI_API_ID,
+    versionId: process.env.RAPIDAPI_AQI_VERSION_ID,
+  },
+];
+
+/**
+ * Build a multipart/form-data body from a file buffer.
+ * Returns { body: Buffer, boundary: string }
+ */
+function buildMultipart(fieldName, filename, fileBuffer, contentType = 'application/yaml') {
+  const boundary = '----FormBoundary' + Math.random().toString(36).slice(2);
+  const CRLF = '\r\n';
+  const parts = [
+    Buffer.from(
+      `--${boundary}${CRLF}` +
+      `Content-Disposition: form-data; name="${fieldName}"; filename="${filename}"${CRLF}` +
+      `Content-Type: ${contentType}${CRLF}${CRLF}`
+    ),
+    fileBuffer,
+    Buffer.from(`${CRLF}--${boundary}--${CRLF}`),
+  ];
+  return { body: Buffer.concat(parts), boundary };
+}
+
+/**
+ * Upload a spec file to RapidAPI Platform API.
+ * Returns a promise that resolves with the response status code.
+ */
+function uploadSpec(api) {
+  return new Promise((resolve, reject) => {
+    if (!api.apiId || !api.versionId) {
+      console.log(`⏭️  Skipping ${api.name}: API ID or Version ID not configured.`);
+      return resolve(null);
+    }
+
+    if (!fs.existsSync(api.specPath)) {
+      console.log(`⏭️  Skipping ${api.name}: spec file not found at ${api.specPath}`);
+      return resolve(null);
+    }
+
+    const fileBuffer = fs.readFileSync(api.specPath);
+    const { body, boundary } = buildMultipart('spec', 'openapi.yaml', fileBuffer);
+
+    const options = {
+      hostname: 'platformapi1.p.rapidapi.com',
+      path: `/v1/apis/${api.apiId}/versions/${api.versionId}`,
+      method: 'PUT',
+      headers: {
+        'Authorization': `Bearer ${RAPIDAPI_KEY}`,
+        'X-RapidAPI-Key': RAPIDAPI_KEY,
+        'Content-Type': `multipart/form-data; boundary=${boundary}`,
+        'Content-Length': body.length,
+      },
+    };
+
+    const req = https.request(options, (res) => {
+      let data = '';
+      res.on('data', (chunk) => { data += chunk; });
+      res.on('end', () => {
+        if (res.statusCode >= 200 && res.statusCode < 300) {
+          console.log(`✓ Published ${api.name} spec to RapidAPI (HTTP ${res.statusCode})`);
+          resolve(res.statusCode);
+        } else {
+          reject(new Error(`Failed to publish ${api.name}: HTTP ${res.statusCode} — ${data}`));
+        }
+      });
+    });
+
+    req.on('error', reject);
+    req.write(body);
+    req.end();
+  });
+}
+
+async function main() {
+  let hasError = false;
+  for (const api of APIS) {
+    try {
+      await uploadSpec(api);
+    } catch (err) {
+      console.error(`✗ ${err.message}`);
+      hasError = true;
+    }
+  }
+  if (hasError) {
+    process.exit(1);
+  }
+}
+
+main();