Handbook
This page and the handbook are maintained with the code. When a procedure changes, change it here; do not keep a separate document.
Cadence (trial, adjusted as we learn)
- Every Monday: the weekly sweep (below). Unchanged sources only update the sweep time; changed prices get a new record.
- Daily: the cloud price APIs (Azure, AWS, GCP) are part of the same sweep script and can be run alone on weekdays.
- Within 48 hours of a vendor announcement: add the new record. A promotional price shows up under “ending” 14 days before its end date.
- Review within 7 days: an independent second reader re-reads each new record within a week (blind re-read by Codex, below; people spot-check). Records not re-checked for 30 days are marked stale on the public pages, never hidden.
The weekly sweep, step by step
- On the server as
admin, rundev/claude/price-tools/sweep.sh. It fetches all 13 sources intodev/claude/price-snapshots/<date>/, records SHA-256, size and fetch time, and prints one line per source: unchanged, CHANGED (with the new dollar amounts it saw), NEW or PARSE ERROR. - For every CHANGED source: open the page or API response in that folder, find which model and channel moved, and add a new record to
quotes.jsonwithobserved_atequal to the sweep'sFETCHED_ATand a new entry insources.jsonpointing at the new snapshot. Never edit the old record. - For a PARSE ERROR: the page layout changed. Note it under coverage gaps rather than guessing, and tell Claude so the parser is fixed.
- Refresh the usage panel:
python3 -I dev/claude/price-tools/import-openrouter-usage.py dev/claude/price-snapshots/<date>(it readsor-rankings.htmlfrom that folder). - Update
last_sweep_atinmeta.jsonto the sweep's fetch time, runnode --import tsx --test tests/prices.test.ts, commit onclaude/public-site. Claude builds and deploys. - Snapshots stay on the server and must be archived to R2 before any are deleted.
Reviewing records: blind re-read by Codex, spot checks by people
- Generate the tasks:
python3 dev/claude/price-tools/verify-tasks.py <label>writesdev/claude/verify/<label>/tasks.jsonandPROMPT.md. Tasks name the snapshot file, model, channel and plan but carry no recorded prices. Aggregator and reseller channels are included. Records whose price was derived from a sentence on the page (not listed as a number) are routed to a person instead. - Run the reader:
codex exec --sandbox workspace-write -C dev/claude/verify/<label> "$(cat dev/claude/verify/<label>/PROMPT.md)". It reads each snapshot on its own and writesresults.json. It must not opendata/prices/or the live page. - Compare:
python3 dev/claude/price-tools/verify-compare.py <label>(dry run), then with--apply. Exact matches become VERIFIED (operator, cloud and reseller channels) or LISTED (aggregator channels) withreviewed_by=codex (agent)andreviewed_at; everything else lands inMISMATCHES.md. - A person handles
MISMATCHES.mdand the human-routed tasks: open the source link, compare, and either confirm (setreviewed_byto your name) or tell Claude the number you see. A changed page is a price change, not an error: the old record stays and a new record is added with a new snapshot. - Spot checks: each week a person re-checks a handful of VERIFIED records against the live page and notes the result here. The reviewer can never be the observer who recorded the record. Marketplace (aggregator) listings that match become LISTED, never VERIFIED; the checks refuse VERIFIED on them.
- Commit. Claude builds and deploys, and the queue here shrinks.
Adding a record
- Fetch the source page or API, save the raw response to the snapshot directory, note its SHA-256, size and fetch time.
- Add the source to
sources.json(or reuse the source from the same fetch) and the record toquotes.json.observed_atmust equal the source's fetch time. - Units are per 1M tokens in the channel's own currency. Fill cached and tier prices when the source lists them; leave them out otherwise, never write 0. A Batch, Flex, Priority or Ultrafast price is its own record with
service_planset, never a field on the standard record. - Run the tests. A record without a source, a reviewer equal to the recorder, or a VERIFIED aggregator price is refused.
Rules
- Records are appended, never edited or deleted. A correction is a new record.
- The reference price comes only from official channels: a verified one if there is one, otherwise the newest, shown as unverified.
- No number is shown without a source. Missing values are a dash, not 0 and not free.
- No resellers, no contract prices, no tax. Aggregator prices are labelled and never used as the reference.
- Snapshots live on the server under
dev/claude/price-snapshots/. They are not yet archived to R2; do not delete them before that.
Contact
Corrections: hello@auramatrix.ai. Code and data are on the claude/public-site branch; Claude deploys with am-deploy-public-site.