/vendor-listing

name: vendor-listing
description: >
  Onboard a vendor who wants their API listed in the treg catalog. Use whenever someone asks
  "how do we get listed on treg", a vendor sends their API details, or a listing PR/issue needs
  review. Walks the whole pipeline: eligibility gate → registry entry → platform-key slot → logo
  → tests → LIVE bogus-key test → core catalog YAML → verify → scrub → validate → evidence
  ledger in the PR. Every listing ships tier-4 wiring and a per-endpoint verification table.
  The vendor-facing doc this skill implements is docs/VENDORS.md.
metadata:
  internal: true  # repo tooling: hidden from `npx skills add superdesigndev/treg`

Vendor listing — add a provider to the catalog

A listing has **three parts**, and all three ship in the same PR:

1. **Registry entry** (`src/treg/oauth_providers.py`) — how a team connects a credential for the provider, and how treg verifies that credential is real. 2. **Core catalog file** (`src/treg/catalog/<service>.yaml`) — what an agent can *do*: 8–15 curated endpoints with capability mapping, inputs, cost + provenance, and verified examples. 3. **Platform-key slot** (`config.py` + `render.yaml` + `fx.yaml`) — so treg can serve the endpoints on its own key (tier 4). **Always aim for this.** A listing that is BYOK-only is the exception and needs a stated reason (no self-serve pricing, `own_account` data, sales-gated).

And every listing PR carries a **verification evidence ledger** (Step 7b). No ledger, no merge.

Deep references (read before non-trivial work; do not duplicate them here):

• `docs/context/guides/expanding-a-category.md` — the add-a-provider playbook, verify toolbox, traps
• `docs/context/architecture/catalog.md` — catalog schema, cost provenance, verify pipeline, PII rules
• `docs/VENDORS.md` — what we told the vendor to prepare (their checklist)
• `src/treg/web/vendor-listing.md` — the HOSTED instructions (served at `/vendor-listing`) that a

vendor's own coding agent follows to raise a listing PR; the dashboard's "List as vendor" modal (connections view, `vendorAsk` in `index.html`) hands vendors a prompt pointing at it. Keep the three vendor-facing surfaces (doc, hosted page, modal prompt) telling one story.

Step 0 — intake: collect the vendor facts

Before touching code, you need ALL of these. If the vendor's submission is missing any, ask — do not guess ("unconfirmed" beats a wrong path shipped):

• **A contact email for the vendor's team** — required in the PR/issue description. It is how a

test credential gets arranged for live verification; without it the listing stalls at step 7.

• `service` id (lowercase slug), display name, one-line summary (what an agent can DO)
• `base_url` (exact API root)
• Auth: where the key rides (header name + format, or query param name). Key **in the URL path is

not supported** — decline or defer.

• A **free or near-free probe endpoint** where a valid key returns 2xx and an invalid key does NOT

— plus the exact bad-key behavior (status code, or the JSON field that signals invalid)

• Pricing page URL, per-endpoint prices, and the billing model (`per_call` / `per_success` /

`per_result` / credits / quota). Machine-readable rate-card endpoint if they have one.

• Docs URL; OpenAPI spec URL if published
• The 8–15 endpoints they consider their core surface, with example parameter *values*
• A test credential (or credits grant) for verification — read it from env only, never write it

into any file

Step 1 — eligibility gate

Reject decisively, with a recorded reason, when:

• The key **cannot be validated** (API returns success for garbage keys) — e.g. ScrapeCreators
• Key rides in the **URL path** (`/v3/{key}/…`) — injectors do header/query only
• **Sales-gated** signup (no self-serve key breaks the fast path)
• Legal/shutdown risk, or deprecated/absorbed products

Step 2 — registry entry

Add an `OAuthProvider(auth_kind="key", …)` in `oauth_providers.py` and append it to `REGISTRY`. Model it on `HUNTER` (a clean key provider). Pick the verify fields from the toolbox table in `expanding-a-category.md` (`token_header`/`token_format`, `token_location="query"`+`token_param`, `probe_url`, `probe_method`+`probe_json`, `token_verify_field`, `token_ok_field`+`token_ok_value`, `token_reject_field`, `probe_reject_statuses`, …). Prefer a header over a query key so the secret never lands in a logged URL. Set `category` (add to `CATEGORY_ORDER` only if genuinely new), `summary`, `base_url`, `docs_url`, `probe_path`, and `setup_url`/`setup_steps` so a user can find their key.

**Provider-required constant headers** (Crustdata's `x-api-version: 2025-11-01`): declare them in `required_headers=(("name", "value"),)` on the `OAuthProvider` and in the `providers.py` CATALOG row — never in the proxy. They become constant-format bindings. Trap (PR #191): a binding whose `format` has no `{secret}` must NOT be fed to `_secret_renderings` — otherwise the literal value (a date!) joins the redaction set and gets masked out of error evidence. Check the constant does not appear in `_secret_renderings`' output, and add a test.

Step 2b — platform-key slot (do this for every listing)

The tier-4 wiring is part of the listing, not a follow-up:

• `src/treg/config.py`: `platform_key_<service>: str = ""` with a one-line comment (auth shape,

what a top-up buys). Pairs (key+secret) use `platform_extra_setting`; see Tomba.

• `render.yaml`: `- key: TREG_PLATFORM_KEY_<SERVICE>` + `sync: false` + a comment. **No value.**
• `src/treg/catalog/fx.yaml` `credit_rates_usd`: the USD-per-credit treg actually pays, with

`basis` naming the real top-up/receipt (not the pricing page's headline tier), `source`, `checked`.

• A test asserting `cat.platform_eligible(ep)` for every endpoint in the file (see

`test_crustdata_and_aviato_catalogs_are_platform_priced`); every cost must therefore be `confidence: documented|verified` with a computable USD figure.

• If the platform key