feat(v1.5): contribution CTA + auto-gen tables + MCP server + agent docs + charts

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,18 +1,33 @@
-<!-- Title format: "add: Name (type)" / "fix: Name — what" / "status: Name → inactive" -->
+<!-- Title format examples:
+       add: NewRelay (mixed)
+       fix: SomeRelay — price update
+       status: GPTGOD → inactive
+       feat: add UiUiAPI fetcher
+-->
 
 ## What this changes
 
 <!-- One line. -->
 
 ## Checklist
 
-- [ ] Edited `data/providers.yaml` (not the README tables directly)
+- [ ] Edited `data/providers.yaml` only (not the README tables — they auto-regenerate)
 - [ ] Followed [`data/schema.md`](../data/schema.md)
-- [ ] `status` honest (`unverified` if I couldn't verify it myself)
-- [ ] No referral/affiliate links, no marketing copy
+- [ ] `status: unverified` if I cannot independently verify (self-submissions default to this)
+- [ ] No referral / affiliate links, no marketing copy
+- [ ] `notes` is one factual sentence
 - [ ] Claims have a dated source where non-obvious
-- [ ] Bumped `last_reviewed` if this was a broad pass
+- [ ] If adding a price fetcher: created `fetchers/<id>.py`, registered in `fetchers/__init__.REGISTRY`, added aliases to `data/canonical-models.yaml`
 
 ## Source / verification
 
 <!-- How did you verify? Link or short description. -->
+
+## Are you the operator of this station? (Optional)
+
+<!-- Self-submissions are welcome. Disclose for transparency; it doesn't change acceptance. -->
+
+---
+
+> **Schema CI ([pr-validate.yml](../.github/workflows/pr-validate.yml)) runs on every change to `data/`, `fetchers/`, `scripts/`, or `pyproject.toml`.**
+> If you see a red ✗, scroll to the action log — it usually points to the exact field. Fix and push; CI re-runs automatically.

.github/workflows/pr-validate.yml

@@ -0,0 +1,32 @@
+name: Validate PR
+
+# Runs scripts/validate.py on every PR touching the data layer or tooling.
+# Catches typos / invalid schema / bad units before a human maintainer sees the PR.
+
+on:
+  pull_request:
+    paths:
+      - "data/**"
+      - "fetchers/**"
+      - "scripts/**"
+      - "pyproject.toml"
+  workflow_dispatch:
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+
+      - name: Validate schemas
+        run: python -m scripts.validate

.github/workflows/price-refresh.yml

@@ -28,15 +28,21 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -e .
+          pip install -e ".[charts]"
 
       - name: Scrape all fetchers
         id: scrape
         run: python -m scripts.scrape
 
-      - name: Build prices
+      - name: Build prices (+ CSV/Parquet exports)
         run: python -m scripts.build_prices
 
+      - name: Build charts (SVG)
+        run: python -m scripts.build_charts
+
+      - name: Build provider tables (READMEs from providers.yaml)
+        run: python -m scripts.build_provider_tables
+
       - name: Validate
         run: python -m scripts.validate
 

CONTRIBUTING.md

@@ -24,17 +24,25 @@ went stale; the goal here is to stay current.
 
 ## How to add or edit a provider
 
-1. **Edit [`data/providers.yaml`](data/providers.yaml)** — the README tables are
-   generated from it. Do **not** edit the README tables directly; they will be
-   overwritten.
+1. **Edit [`data/providers.yaml`](data/providers.yaml) only** — the README
+   tables in all three languages are auto-generated by
+   [`scripts/build_provider_tables.py`](scripts/build_provider_tables.py). Do
+   **not** edit the README tables directly; they will be overwritten on the
+   next CI run.
 2. Follow the [field schema](data/schema.md). Required: `name`, `url`, `type`,
    `status`.
 3. Mark anything you could not personally verify as `status: unverified` and say
    so in `notes`.
-4. Bump `last_reviewed` in `providers.yaml` if you did a broad pass.
-5. Open a Pull Request. Use a clear title, e.g.
+4. **`notes` may be a string OR a bilingual dict** `{en, zh-TW, zh-CN}`. New
+   entries can ship English-only — translations can be added later by anyone.
+5. Bump `last_reviewed` in `providers.yaml` if you did a broad pass.
+6. Open a Pull Request. Use a clear title, e.g.
    `add: ExampleAPI (mixed)` or `status: GPTGOD → inactive (ran away 2026-05)`.
 
+> **Tip:** The schema CI runs on every PR — if you mis-spell a field or set an
+> invalid `type` / `status`, the bot tells you exactly which line before a
+> human reviews. Push a fix and CI re-runs automatically.
+
 Not comfortable with a PR? Open an issue with the
 [provider template](.github/ISSUE_TEMPLATE/new-provider.md) and a maintainer
 will add it.

README.md

@@ -22,6 +22,7 @@ Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md)
 - [Global gateways & aggregators](#global-gateways--aggregators)
 - [Self-hosted alternatives](#self-hosted-alternatives)
 - [Comparison & monitoring tools](#comparison--monitoring-tools)
+- [Want your relay listed?](#want-your-relay-listed)
 - [Price snapshot (weekly)](#price-snapshot-weekly)
 - [How to choose one safely](#how-to-choose-one-safely)
 - [For AI agents & programmatic use](#for-ai-agents--programmatic-use)
@@ -72,33 +73,41 @@ market, not a workaround niche.
 
 ## China / Asia relay stations
 
-> Status: `active` = independently reachable · `unverified` = community-sourced,
-> not independently confirmed. **Last verified** = date the maintainer last
-> visited the site; absent on unverified entries. Prices change constantly —
-> verify on-site. Generated from [`data/providers.yaml`](data/providers.yaml).
-
-| Station | Type | Payment | Status | Last verified | Entity | Notes |
-|---|---|---|---|---|---|---|
-| [云雾 API (YUNWU)](https://yunwu.ai) | mixed | Alipay/WeChat | active | 2026-05-26 | unknown | Marketed on speed/stability; widely cited top-tier station. |
-| [柏拉图 AI (bltcy)](https://api.bltcy.ai) | mixed | Alipay/WeChat | active | 2026-05-26 | unknown | Azure-backed channel; positions as lowest-price. |
-| [No.1-API](https://api.rcouyi.com) | aggregator | Alipay/WeChat | active | 2026-05-26 | unknown | One-stop aggregation + relay platform. |
-| [UiUiAPI](https://uiuiapi.com) | official-relay | Alipay/WeChat | active | 2026-05-26 | unknown | Claims official channels + official multipliers; ~49% cheaper (claimed), 300+ models. |
-| [DMXAPI](https://dmxapi.cn) | mixed | Alipay/WeChat | unverified | — | unknown | Community-listed; homepage not independently verified. |
-| [MKEAI](https://mkeai.com) | mixed | Alipay/WeChat | unverified | — | unknown | Community-forum + relay hybrid; pushes DeepSeek. |
-| [GPTGOD](https://gptgod.online) | reverse | Alipay | unverified | — | unknown | Reverse-engineered; cheap, stability not guaranteed. |
-| [CloseAI](https://www.closeai-asia.com) | official-relay | Alipay/WeChat/Invoice | active | 2026-05-26 | registered | Issues enterprise invoices; self-describes as largest enterprise-grade relay in Asia. |
+> **Trust** = status + last-verified date + `· registered` when a company
+> entity is publicly visible. `active` = independently reachable;
+> `unverified` = community-sourced, not independently confirmed.
+> Prices change fast — verify on-site. Full per-entry fields (payment, models,
+> supports_tools, etc.) in [`data/providers.yaml`](data/providers.yaml);
+> tables below are auto-generated by [`scripts/build_provider_tables.py`](scripts/build_provider_tables.py).
+
+<!-- providers:china_relays:start -->
+| Station | Type | Payment | Trust | Notes |
+|---|---|---|---|---|
+| [云雾 API (YUNWU)](https://yunwu.ai) | mixed | Alipay/WeChat | active · 2026-05-26 | Marketed on speed/stability; widely cited as a top-tier station. |
+| [柏拉图 AI (bltcy)](https://api.bltcy.ai) | mixed | Alipay/WeChat | active · 2026-05-26 | Azure-backed channel; positions as lowest-price. |
+| [No.1-API](https://api.rcouyi.com) | aggregator | Alipay/WeChat | active · 2026-05-26 | One-stop aggregation + relay platform. |
+| [UiUiAPI](https://uiuiapi.com) | official-relay | Alipay/WeChat | active · 2026-05-26 | Claims official channels + official multipliers; rare quantified discount. |
+| [DMXAPI](https://dmxapi.cn) | mixed | Alipay/WeChat | unverified | Listed in community sources; homepage not independently verified. |
+| [MKEAI](https://mkeai.com) | mixed | Alipay/WeChat | unverified | Community-forum + relay hybrid; pushes DeepSeek heavily. |
+| [GPTGOD](https://gptgod.online) | reverse | Alipay | unverified | Reverse-engineered; among cheapest, stability not guaranteed. |
+| [CloseAI](https://www.closeai-asia.com) | official-relay | Alipay/WeChat/Invoice | active · 2026-05-26 · registered | Issues enterprise invoices; self-describes as largest enterprise-grade relay in Asia. |
+<!-- providers:china_relays:end -->
 
 > **Inclusion ≠ endorsement.** Listing documents the market. Always run the
 > [evaluation checklist](docs/evaluation.md) before sending money or data.
 
 ## Global gateways & aggregators
 
+<!-- providers:global_gateways:start -->
 | Service | Type | Payment | Notes |
 |---|---|---|---|
-| [OpenRouter](https://openrouter.ai) | aggregator | Card/Crypto | Official-authorized routing, ~5% markup; 400+ models, 60+ providers. ARR reportedly ~$5M (2025-05) → ~$50M (early 2026). |
-| [LiteLLM](https://litellm.ai) | gateway-oss | — | Open-source gateway (100+ providers) + enterprise tier. Self-hosted, bring your own keys. |
-| [Helicone](https://helicone.ai) | observability | — | LLM observability gateway; logging/cost analytics. |
-| [AIMLAPI](https://aimlapi.com) | aggregator | Card/Crypto | 400+ models, prepaid from $20; crypto support implies payment-friction workaround. |
+| [OpenRouter](https://openrouter.ai) | aggregator | Card/Crypto | Official-authorized routing, ~5% markup. ARR reportedly $5M (2025-05) to ~$50M (early 2026). Public JSON API at /api/v1/models with normalized per-token pricing. |
+| [Atlas Cloud](https://www.atlascloud.ai) | aggregator | Card | Multi-modal aggregator; image/video heavy (Grok Imagine, Kling, ByteDance, Vidu). Public OpenAI-compatible /v1/models endpoint exposes per-token pricing including cache-read. |
+| [Relaydance](https://relaydance.com) | mixed | Alipay/WeChat/Card | 新-API (Calcium-Ion fork) operator focused on xAI Grok + ByteDance Doubao. Public /api/pricing returns ratio-based pricing (model_ratio × $2 / 1M tokens). |
+| [LiteLLM](https://litellm.ai) | gateway-oss | — | Open-source gateway + enterprise tier. Self-hosted; not retail. |
+| [Helicone](https://helicone.ai) | observability | — | LLM observability gateway; logging/analytics focus. |
+| [AIMLAPI](https://aimlapi.com) | aggregator | Card/Crypto | Prepaid from $20; crypto support implies payment-friction workaround. |
+<!-- providers:global_gateways:end -->
 
 ## Self-hosted alternatives
 
@@ -108,22 +117,45 @@ don't want a third party in the request path. You bring your own upstream keys
 data on your side. Most Chinese relay stations are themselves built on these
 templates.
 
+<!-- providers:self_hosted_alternatives:start -->
 | Project | Type | Notes |
 |---|---|---|
-| [One-API](https://github.com/songquanpeng/one-api) | gateway-oss | Popular Go-based multi-vendor gateway; the de-facto OSS template behind many relay stations. |
+| [One-API](https://github.com/songquanpeng/one-api) | gateway-oss | Popular Go-based self-hosted multi-vendor gateway; the de-facto OSS template behind many relay stations. |
 | [new-api](https://github.com/Calcium-Ion/new-api) | gateway-oss | Fork of One-API with extra channel types; same self-hosted model — you supply keys. |
-| [LiteLLM](https://litellm.ai) | gateway-oss | Listed above. Python-first, 100+ providers, used by enterprises. |
+<!-- providers:self_hosted_alternatives:end -->
+
+> [LiteLLM](https://litellm.ai) (in the global table above) is also self-hosted (Python, 100+ providers, used by enterprises).
 
 **When to choose self-hosted over a relay:** regulated data, production
 workloads, you already have foreign-card billing, or you want auditable logs.
 You give up the relay's Alipay/WeChat convenience and accept ops overhead.
 
 ## Comparison & monitoring tools
 
+<!-- providers:comparison_tools:start -->
 | Tool | Notes |
 |---|---|
 | [中轉站競技場 (AI API PK)](https://www.aiapipk.com) | Price wall across OpenAI / Reverse / Claude / DeepSeek for ~40 stations. |
-| [awesome-ai-proxy (mn-api)](https://github.com/mn-api/awesome-ai-proxy) | The original list (~31 stations). **Unmaintained as of 2026** — this repo aims to continue the effort. |
+| [awesome-ai-proxy (mn-api, unmaintained)](https://github.com/mn-api/awesome-ai-proxy) | Original list (~31 stations); no longer maintained as of 2026. |
+| [CoderPlan](https://coderplan.ai) | Community-submitted; claims 50+ models incl. OpenAI/Anthropic/Google/DeepSeek/xAI. |
+<!-- providers:comparison_tools:end -->
+
+## Want your relay listed?
+
+We accept community submissions, **including from relay operators themselves**.
+Two paths — pick whichever is easier:
+
+- **One-click issue:** [Open a new-provider issue](https://github.com/howardpen9/awesome-ai-api-proxy/issues/new?template=new-provider.md) — fill the form, a maintainer adds it.
+- **Direct PR:** edit [`data/providers.yaml`](data/providers.yaml) only (READMEs auto-regenerate). See [CONTRIBUTING.md](CONTRIBUTING.md) for the schema; the [PR template](.github/pull_request_template.md) has a one-glance checklist.
+
+**Default status is `unverified`** until a maintainer runs a canary against your station.
+That's not a rejection — it just means the entry says "community-listed, not independently confirmed."
+After verification (typically <2 weeks) status flips to `active` with `last_verified` set.
+
+We never accept referral links or marketing copy. We do accept honest entries
+from operators — one factual sentence in `notes`, no superlatives.
+
+> **Schema CI runs on every PR** ([pr-validate workflow](.github/workflows/pr-validate.yml)) — if you mis-spell a field or use an invalid `type`, the bot will tell you before a human gets there.
 
 ## Price snapshot (weekly)
 
@@ -140,6 +172,10 @@ You give up the relay's Alipay/WeChat convenience and accept ops overhead.
 <!-- prices:start -->
 _Snapshot date: **2026-06-07**. 1024 price records across 3 fetched providers. **Reference column** is OpenRouter (officially-authorized, ~5% markup). ⚠ = relay quotes <50% of OpenRouter — verify with [canary prompts](docs/canary-prompts.md) before trusting._
 
+![Tier-ladder input pricing](assets/charts/tier-ladder-input.svg)
+
+_More charts (output pricing, cost-spread heatmaps): [`assets/charts/`](assets/charts/). Interactive dashboard: <https://howardpen9.github.io/awesome-ai-api-proxy/>._
+
 ### Tier 1 — cheapest viable (routine, batch summaries) — USD per 1M input tokens
 
 | Model | OpenRouter (ref) | Atlas Cloud | Relaydance |