softmarshmallow · Oct 13, 2026 · Oct 12, 2026 · Oct 13, 2026 · Oct 13, 2026 · Oct 13, 2026
@@ -4,8 +4,8 @@ description: >
   Research, add, update, deprecate, or remove AI model catalogue entries —
   text, image, video, audio, 3D, image tools, and embedding models — with
   their capabilities, limits, provider bindings, and published prices.
-  Covers what an entry is, per-provider ID rules, pricing shapes, lifecycle
-  rules (steady-state pricing, deprecate vs. delete), and the verification
+  Covers what an entry is, per-provider ID rules, regular pricing, native
+  reference and provider coverage, public distribution, and the verification
   checklist. Use when bumping a model version, adding a model or provider
   binding, updating a price, or auditing entries against provider docs.
   Release dates are covered by $provenance.
@@ -37,13 +37,19 @@ An entry is a set of facts about one model, each traceable to a source:
 
 - **Identity:** `id`, `label`, `vendor`, family.
 - **Release:** see `$provenance`.
+- **Distribution:** official code and weight links, exact weight variants, access
+  conditions, and separately sourced code/weight licenses. Use the model-level
+  `distribution` shape in [`catalogue/README.md`](../../../catalogue/README.md#model-distribution).
+  Leave unknown facts omitted. Available weights do not establish a native hosted API;
+  public downloads do not establish an open-source classification or unrestricted use.
 - **Capabilities:** modalities, accepted image MIME types, tool calling, audio, transparent
   background, and so on. Never derive one capability from another (for example, image MIME
   types from `multimodal`); record each from its own source.
 - **Limits:** context window and output limit (text); sizes, size constraints, aspect ratios
   (image); durations and aspect ratios (video).
-- **Bindings:** for each provider that serves it, the provider's exact ID, its published
-  price, and optionally a URL and a deprecation flag.
+- **Bindings:** exact call IDs, sourced regular prices when known, and provider-specific
+  contracts. A native `reference_provider` is a presentation choice. Explicit
+  `provider_coverage` distinguishes listed providers from source-backed absence/exclusion.
 
 Facts are independent of products. Adding a verified fact does not list the model in any
 Grida product, and removing a product listing does not delete the fact.
@@ -52,12 +58,12 @@ Grida product, and removing a product listing does not delete the fact.
 
 The same model has different IDs, availability, and prices on different providers.
 
-- **Text, audio, image tools, 3D:** one entry per provider endpoint. The `id` is in that
-  provider's format, and the provider or namespace fixes the route.
+- **Text, audio, image tools, 3D:** retain existing endpoint-shaped IDs and direct-provider
+  facts. Add `providers` bindings without rewriting those existing identities.
 - **Image and video:** one canonical entry (`vendor/model`, e.g. `google/veo-3.1`) holding the
   model's intrinsic facts, plus a `providers` record keyed by provider. Each binding has its
-  own call ID and price. Bindings carry no preference order; choosing a provider is a
-  consumer's decision.
+  own call ID and price. `reference_provider` identifies the verified native API to show
+  first; choosing which provider to call remains a consumer decision.
 
 Preserve IDs exactly as the provider spells them. Never case-convert or normalize them.
 Per-provider ID formats, pricing pages, and known quirks are in
@@ -68,20 +74,22 @@ Per-provider ID formats, pricing pages, and known quirks are in
 The catalogue states what is true and useful **now**. Its shape must never record how
 recently someone got round to updating it.
 
-- **Price the steady state, not the promotion.** If a vendor runs an introductory or
-  time-limited rate, record the price that applies after it ends, and note the promotion and
-  its end date in `PROVENANCE.md`. Otherwise the promotion ending is a silent cost increase.
-  Recheck when the date passes: a promotion can become permanent, which changes the fact.
-- **Deprecate an entry that is still a real choice.** Mark it deprecated (Grida's
-  `legacy: true`) when someone might reasonably still pick it: same price as its successor,
-  or better at something.
-- **Delete an entry whose successor is strictly dominant:** never worse on any axis, better
-  on at least one. An entry nobody should choose is noise in every picker.
-- **A binding needs a usable, verified price.** If a provider exposes no billable unit for a
-  model (for example, a $0/MTok placeholder for video), leave that binding out rather than
-  inventing a price.
-- **Catalogue only what is used.** Do not add a capability, endpoint variant, or field for a
-  case nobody serves yet. Add it when the second case arrives.
+- **Regular, non-promotional prices only.** Record the provider's sourced regular rate,
+  even when an introductory or time-limited discount is active when adding or updating a
+  model. Do not track promotional rates, end dates, or expiry rechecks. A discounted live
+  feed does not establish the regular price; do not infer it from a discount percentage or
+  another provider's rate. If the regular rate cannot be verified, report the missing
+  evidence and leave the price unrecorded.
+- **Preserve existing entries during coverage work.** Do not delete a model because a
+  successor exists or because a consumer does not currently serve it. Lifecycle and
+  offering changes need separate review. Do not introduce product policy fields.
+- **Unknown prices remain unknown.** Verified endpoint existence can be recorded without
+  a price. A $0/MTok video placeholder is not a usable unit; omit that price and record
+  the qualification. If the contract itself cannot be represented reliably, use a
+  source-backed exclusion rather than inventing capabilities or amounts.
+- **Coverage is source-backed.** Add the native API and verified OpenRouter, Vercel and
+  fal media bindings. Add Grida only where its public service actually offers the model.
+  An unserved catalogue entry remains useful; do not invent a Grida binding.
 
 Removing an entry is a contract change for consumers: some embed the catalogue at build
 time and only see the change in their next release. Say so in the PR.
@@ -98,12 +106,16 @@ time and only see the change in their next release. Say so in the PR.
 - When two first-party sources conflict, first check they describe the same thing (variant,
   provider, region, tier, resolution, date). If they truly conflict, decide which wins and
   why (more specific page, dated changelog), record it in `catalogue/PROVENANCE.md`, and
-  never average. If it can't be resolved from public sources, leave the value and ask.
+  never average. If it cannot be resolved from public sources, leave the disputed fact
+  unrecorded and document the gap. Aggregate behavioral questions for a separately
+  approved probe; do not make paid inference calls as part of catalogue maintenance.
 
 ## Pricing
 
-Record the provider's published list price in the provider's own billing unit. Never
-convert to credits, add margin, or substitute a negotiated or account-specific rate. The
+Record the provider's advertised regular price in its published billing unit. Public
+Grida prices are provider facts too; they do not authorize disclosing internal economics
+or deriving a different price from another provider. Never convert to credits, add an
+internal margin, or substitute a negotiated/account-specific rate. The
 pricing shapes in use and their rules are in [`pricing.md`](./pricing.md).
 
 ## Workflow
@@ -128,17 +140,21 @@ pricing shapes in use and their rules are in [`pricing.md`](./pricing.md).
    homepage, and its official logo (see [`models/README.md`](../../../models/README.md#a-lab)).
    Fields are `lower_snake_case`; IDs keep their exact spelling. Run
    `uv run scripts/build.py`, then `uv run scripts/check.py`.
-5. **Record qualifications** that do not fit the JSON (promotions, long-context bands,
-   ambiguous units) in `catalogue/PROVENANCE.md`, with source URLs.
+5. **Record qualifications** that do not fit the JSON (regular-price evidence,
+   long-context bands, ambiguous units) in `catalogue/PROVENANCE.md`, with source URLs.
 
 ## After any update
 
 - [ ] Every new or changed fact has a first-party source, cited in the PR description
 - [ ] No value was estimated, rounded, or copied from an aggregator without verification
-- [ ] Prices are published list prices in the provider's own unit, at the steady state
+- [ ] Prices are sourced regular, non-promotional rates in the provider's own unit;
+      promotional rates and expiry tracking are excluded
 - [ ] IDs are exact; field names are `lower_snake_case`
+- [ ] Distribution links are official; code and weight licenses/access are independently
+      sourced, with no inferred hosted API or license permissions
 - [ ] Every entry has a complete `release` (`$provenance`)
-- [ ] Deprecated vs. deleted was decided by the lifecycle rules above
+- [ ] Native reference, canonical provider coverage and any exclusions are sourced; existing
+      model identities and unserved entries are preserved
 - [ ] `catalogue/models.json` was regenerated with `uv run scripts/build.py`, not edited by hand
 - [ ] `uv run scripts/check.py` passes
 - [ ] Nothing from a private source made it into the diff, the commit, or the PR (see `AGENTS.md`)
@@ -7,12 +7,20 @@ Supplements [`SKILL.md`](./SKILL.md). Load this when you add or change a price.
 - **Published list price, in the provider's unit.** Record what the provider's public
   pricing page says, in the unit it bills: per million tokens, per image, per second, per
   run, per 1,000 characters, or provider credits with their published USD rate. Do not
-  convert units or currencies.
+  convert currencies. Exact decimal unit normalization is allowed when both the source
+  unit and contract unit are explicit; it must not round or change billing semantics.
 - **A price belongs to a binding.** The same model can cost different amounts on different
-  providers. On canonical entries (image, video), each binding carries its own `pricing`.
-- **Steady state, not promotion.** See the lifecycle rules in [`SKILL.md`](./SKILL.md).
-- **No usable unit, no binding.** If a provider shows a placeholder price (for example,
-  $0/MTok for video), leave the binding out.
+  providers. Each binding or endpoint carries its own price without changing intrinsic
+  model facts. Public Grida service prices are eligible; its supplier selection, funding
+  fees, credit conversions and margin are not catalogue data.
+- **Regular, non-promotional rates only, even during an active promotion.** Do not
+  maintain promotional prices, expiry dates, or a promotion calendar. Verify the regular
+  rate from that provider's own source; a discounted feed or another provider's rate is
+  insufficient. See the lifecycle rules in [`SKILL.md`](./SKILL.md).
+- **No usable unit, no price.** If a provider shows a placeholder price (for example,
+  $0/MTok for video), leave that price out. A verified endpoint can still have a binding;
+  document unknown regular rates. Use a sourced exclusion only for a contract that cannot
+  be reliably listed, not to hide unfinished research.
 - **Estimates are not prices.** `avg_cost_usd` and `cost_usd` are coarse per-request
   estimates, not published facts. Keep them consistent with the published rates and never
   cite them as a source.
@@ -22,6 +30,19 @@ Supplements [`SKILL.md`](./SKILL.md). Load this when you add or change a price.
 These are the `pricing.type` values in the current authored data. Before adding a new
 shape, check whether an existing one can express the price without loss.
 
+`published_pricing` is an additive provider-neutral shape for publicly advertised
+USD meter components, conditions, request-wide quantity bands, and quantity
+rounding. Its contract is in
+[`catalogue/README.md`](../../../catalogue/README.md#published-service-prices-and-contracts).
+Use it only from the service's own public evidence. Its source is the advertised
+price, not assumptions about that service's suppliers or margins.
+
+`token_pricing` records exact decimal USD-per-token rates. Keep cache-write TTLs
+distinct: `input_cache_write_1h` records the one-hour rate when published;
+`scope` qualifies the standard tier and the base cache-write duration. A
+cache-storage-per-hour amount is a different unit and must not be inserted as
+a per-token write price.
+
 ### Text
 
 Text entries use a `cost` object instead of a typed `pricing` union. Values are USD per
@@ -90,7 +111,10 @@ silent output, omit those keys rather than copying another provider's rates.
 
 1. Open the provider's own pricing page or model page (see [`providers.md`](./providers.md)).
 2. Record the date you checked it in the PR description.
-3. If the page qualifies the price (region, tier, batch discount, promotion end date), note
-   the qualification and URL in `PROVENANCE.md`.
+3. Verify that the quoted rate is regular and non-promotional. Record its source and
+   applicable conditions (region, service tier, batch mode, billing unit) in
+   `PROVENANCE.md` when needed. Do not record promotional rates or end dates. If public
+   sources establish only a promotional rate, leave the regular price unrecorded and
+   document the verification gap; do not guess it.
 4. If two first-party pages disagree, follow "When sources disagree" in
    [`SKILL.md`](./SKILL.md).
@@ -22,6 +22,7 @@ change a `basis: "model"` release date.
 | fal               | Endpoint path: `fal-ai/veo3.1/image-to-video`, `fal-ai/flux-2-pro/edit` |
 | OpenRouter        | `vendor/model`: `google/veo-3.1`, `google/veo-3.1-fast`                 |
 | Replicate         | `owner/model`: `google/lyria-3`, `nightmareai/real-esrgan`              |
+| Grida             | Public model ID or model-specific operation ID from its API catalogue   |
 
 On fal, the capability is often part of the ID (`…/image-to-video`, `…/edit`). A different
 capability on fal is a different endpoint, so it is a different binding.
@@ -37,17 +38,27 @@ capability on fal is a different endpoint, so it is a different binding.
 | fal               | `https://fal.ai/models/<endpoint-id>`; pricing API: `https://fal.ai/docs/documentation/model-apis/pricing` |
 | OpenRouter        | `https://openrouter.ai/<vendor>/<model>`                                                                   |
 | Vercel AI Gateway | `https://vercel.com/ai-gateway/models/<model>`                                                             |
+| Grida             | `https://gateway.grida.ai/llms.txt`; linked discovery and operation schemas                                |
 | models.dev        | `https://models.dev/api.json`. **Discovery only**, never a source                                          |
 
 ## Known quirks
 
-- **Availability differs by provider.** A model can be on OpenRouter and fal but not on the
-  Vercel AI Gateway. A canonical entry simply omits the binding it does not have.
+- **Availability differs by provider.** A model can be on OpenRouter and fal but not on
+  Vercel. Verify native API, OpenRouter, Vercel and fal (media only) against first-party
+  sources; retain `provider_coverage` dispositions. Grida is required only when its
+  public service actually offers the model. Absence needs evidence, not an incomplete
+  search. A consistent spec/identity/pricing incompatibility may justify a sourced
+  per-model exclusion. Never use private routing preference as an exclusion reason.
 - **Metering differs by provider.** For one video model, one provider may meter audio and
   silent output and 4K, while another sells only audio-on output at 720p/1080p. Record each
   provider's own matrix.
 - **Placeholder prices.** OpenRouter can show `$0/MTok` for video models. That is not a
-  usable price: leave the binding out.
+  usable price: omit the price and document the qualification. Verify image/video
+  endpoints directly; a text feed does not describe those modalities.
+- **Native reference.** Set `reference_provider` to the actual native API binding, or an
+  existing direct native provider, after verification. Prefer one qualified Google API
+  unless another has a meaningful published contract difference. Open-weight code or
+  artifacts establish `distribution`, not a billable API run by the model lab.
 - **Namespaces differ from vendor IDs.** For example, image IDs may use a short namespace
   (`bfl/…`) while the vendor field is `black-forest-labs`. Keep whatever the authored data
   uses; do not "fix" an ID to match a vendor name.
@@ -77,7 +77,9 @@ history. Never fill in an approximate day.
 A JSON value cannot hold its own caveats. Write a note in
 [`catalogue/PROVENANCE.md`](../../../catalogue/PROVENANCE.md) when a fact needs one. For example:
 
-- A promotion: the steady-state price that was recorded, and the promotion's end date.
+- Regular-price evidence: the provider's source establishing its non-promotional rate,
+  or a verification gap when only a promotional rate is published. Do not track discounted
+  prices, promotion end dates, or expiry rechecks.
 - A pricing band, such as long-context multipliers, with its threshold and source.
 - A capability shared by a model family, with the page that states it.
 - A conflict between sources, and why one was chosen.

@@ -0,0 +1,2 @@
+# Catalogue and tooling changes require maintainer review.
+* @softmarshmallow
@@ -63,9 +63,13 @@ file, commit, branch name, or PR:
 
 - the name, URL, path, file, PR, or tooling of a private repository or service;
 - how a consumer routes requests (which provider for which model, fallback order);
-- negotiated, wholesale, or account-specific prices; margins, markups, credit conversions;
+- negotiated, wholesale, or account-specific prices; internal margins, funding fees, credit conversions;
 - provider account details, contract or rights reviews;
-- hostnames, account IDs, credential or environment variable names, budgets, roadmap.
+- private hostnames, account IDs, credential or environment variable names, budgets, roadmap.
+
+Published service contracts, public API URLs and advertised regular prices are public
+provider facts, including Grida's. Record them without disclosing supplier selection,
+internal tariff calculations or funding policy.
 
 Restate a need in neutral, public terms ("per-second video pricing keyed by resolution").
 When in doubt, leave it out and ask.
@@ -81,14 +85,24 @@ doesn't belong in the contract.
   See `$catalogue` and `$provenance`.
 - **Never fabricate.** If a value cannot be verified, leave it out and say so. Do not
   estimate a price, round a limit, or infer a release day.
-- **Published prices only.** No negotiated, wholesale, account-specific, or internal prices.
-  No markup, credit conversion, or margin.
+- **Published regular prices only.** Use sourced, non-promotional provider rates even
+  during an active promotion. Do not maintain promotional prices or expiry tracking.
+  No negotiated, wholesale, account-specific, or internal prices; no internal markup, credit
+  conversion, or internal margin. A provider's publicly advertised rate is eligible even
+  when its internal economics are unknown. Never infer an unknown regular rate.
 - **Preserve IDs exactly.** Model and provider IDs keep their exact spelling and casing.
   Authored field names are `lower_snake_case`.
 - **Additive by default.** Add fields; do not rename or repurpose them. A breaking change
   needs a new schema version, decided with the user.
 - **Facts are independent of products.** Being catalogued is not the same as being offered
-  by a Grida product.
+  by a Grida product. Keep existing entries when reviewing provider coverage; deleting a
+  model or expanding an offering requires a separate review.
+- **Provider coverage is explicit.** Qualify the native lab API as `reference_provider`
+  where it exists. It is a presentation reference, never a routing default. Record
+  OpenRouter, Vercel and fal (media only) where verified, and Grida where it serves the
+  model. Record source-backed absence or exclusion in `provider_coverage`; unfinished
+  research is not evidence of absence. Open weights do not imply a native hosted API.
+  See the catalogue skill for coverage and public price rules.
 
 ## Skills
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		# Catalogue and tooling changes require maintainer review.
		* @softmarshmallow