# AGENTS.md

## DO NOT EDIT — Auto-generated Files

The following files are **idempotent** and regenerated by `scripts/update-models.js`. Never edit them directly — your changes will be overwritten on the next model sync.

| File | Why it's auto-generated |
|------|------------------------|
| `models.json` | Built from the provider API. `update-models.js` fetches models, preserves curated data for known IDs, and writes this file. |
| `deprecated-models.json` | Graveyard for models the API delisted. update-models.js stamps them with deprecatedAt and pi keeps serving them for a 2-week grace period, then evicts them. Never edit by hand. |
| `README.md` (model table) | The table under `## Available Models` is replaced in-place by `update-models.js` after merging base models → patch → custom models. |

## Correct Files to Edit

When a model needs overrides, new properties, or corrections, edit the appropriate source file below. These are the **source of truth** that the update script reads but never writes.

| File | Purpose |
|------|---------|
| `patch.json` | Per-model overrides keyed by model ID. Add reasoning flags, compat settings, pricing corrections, etc. Applied on top of `models.json` at runtime and for README generation. Only needs a `thinkingLevelMap` when deliberately deviating from the API's `metadata.reasoning` derivation (a matching map is dead weight — the sync's advisory report flags those). |
| `custom-models.json` | Models that don't exist in the provider API (hidden models, router endpoints, cross-provider aliases). Merged after patch. Format: array of full model objects (same schema as `models.json` entries). |
| `index.ts` | Provider extension code. |
| `scripts/update-models.js` | The sync script itself (edit only if changing how models are fetched/transformed). |

## Data Flow

```
Provider API  ──fetch──►  models.json  ──apply──►  patch.json  ──merge──►  custom-models.json
                                    │                            │                      │
                                    └────────────────────────────┴──────────────────────┘
                                                      │
                                              README model table
```

1. `models.json` — base data from the provider API (auto-generated, DO NOT EDIT)
2. `patch.json` — overrides applied on top (EDIT THIS for corrections/enrichments)
3. `custom-models.json` — additional models not in the API (EDIT THIS for new models)
4. README table — rendered from the merged result of all three (auto-generated, DO NOT EDIT)

## Common Tasks

### Add a compat setting or override pricing for an existing model
→ Edit `patch.json`. Add an entry keyed by the model's `id`.

### Add a model not available in the provider API
→ Edit `custom-models.json`. Add a full model object to the array.

### Update models from the provider API
→ Run `node scripts/update-models.js` (may require an API key env var).

### Regenerate the README model table
→ Run `node scripts/update-models.js` — it updates both `models.json` and the README table.

## TL;DR

- **Never edit `models.json`** — edit `patch.json` instead.
- **Never edit the README model table** — run the update script instead.
- `patch.json` and `custom-models.json` are the source files you should modify.