# AGENTS.md

## DO NOT EDIT - Auto-generated Files

These 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 (a logged-in API key required). `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 the runtime keeps serving them for a 2-week grace period, then evicts them. |
| `README.md` (model table) | The table under `## Available Models` is replaced in place by `update-models.js`. |

## Correct Files to Edit

| File | Purpose |
|------|---------|
| `patch.json` | Per-model overrides keyed by model ID (reasoning, compat, pricing, thinking level maps). Applied on top of `models.json` at runtime and for README. |
| `custom-models.json` | Models that don't exist in the provider API (hidden/alias/extra models). Merged after patch. |
| `index.ts` | Provider extension code. |
| `models.ts` | Pure model pipeline (transform/patch/merge) - offline unit-testable. |
| `usage.ts` | Pure subscription/plan parser (Free/Builder/Pro) - offline unit-testable. |
| `scripts/update-models.js` | The sync script itself. |

## 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` - models not in the API (EDIT THIS for new models)
4. README table - rendered from all three (auto-generated, DO NOT EDIT)

## TL;DR

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