earnrate 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Collin Wasley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,217 @@
-# Temporary Holding Version
+# earnrate
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/cwasley/earnrate/actions/workflows/ci.yml/badge.svg)](https://github.com/cwasley/earnrate/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/earnrate)](https://www.npmjs.com/package/earnrate)
+[![Code: MIT](https://img.shields.io/badge/code-MIT-blue)](LICENSE)
+[![Data: CC BY-NC 4.0](https://img.shields.io/badge/data-CC%20BY--NC%204.0-lightgrey)](data/LICENSE)
+
+I wanted a ghost card: one card that always charges the best of my cards. The card networks won't allow one, so I built the next best thing.
+
+**earnrate is the best-card decision layer for people and AI agents.** Give it a merchant, and it tells you which card in your wallet earns the most there, and why. It's stateful (it knows your caps and chosen categories), valuation-aware, and transparent about its assumptions. It never sees a card number.
+
+- Runs on your machine. No account, no telemetry, no affiliate links.
+- US cards and US merchants, for now.
+
+> **Status:** early, and it works: the engine, CLI, optional Claude merchant lookup and MCP server. See [the benchmark](docs/benchmark.md) for how it compares to an existing card-picking MCP server.
+
+## Try it
+
+Needs Node 24 or later.
+
+```sh
+npm install -g earnrate
+mkdir -p ~/.earnrate
+curl -o ~/.earnrate/wallet.yaml https://raw.githubusercontent.com/cwasley/earnrate/main/wallet.example.yaml
+earnrate whole foods 80
+```
+
+Then edit `~/.earnrate/wallet.yaml` to list your own cards (see [Your wallet](#your-wallet)).
+
+```
+Whole Foods Market · $80
+
+Use Blue Cash Preferred: 6% back, about $4.80. High confidence.
+
+  1. Blue Cash Preferred  6%  $4.80
+     6% cash back from its "us-supermarkets" rule. ...
+  2. Prime Visa           5%  $4.00
+     5% cash back from its "whole-foods" rule. Online or in-store.
+  3. Amex Gold            4%  $3.20
+     4x Amex Membership Rewards from its "us-supermarkets" rule. ...
+     Valued at 1¢ per point: 4% back.
+  + 6 more cards (--all lists them)
+
+Amex Gold beats Blue Cash Preferred here if Amex Membership Rewards (MR) points are worth 1.5¢ or more (you value them at 1¢).
+
+Assumes Whole Foods Market codes as supermarkets (MCC 5411).
+```
+
+Options: `--online` or `--in-store`, `--valuation flat|points-heavy`, `--all`, `--json`, `--date`, `--country`. Run `earnrate --help` for details. To keep the wallet somewhere else, set `EARNRATE_WALLET` to its path.
+
+### Your wallet
+
+The wallet is a YAML file listing your cards by ID, which is each card's file name in [`data/cards/`](data/cards). Only the cards are required:
+
+```yaml
+valuations:
+  UR: 1.5 # cents per point; leave out to use earnrate's defaults
+memberships: [amazon-prime] # unlocks Prime Visa's 5%
+cards:
+  - id: chase-sapphire-preferred
+  - id: chase-prime-visa
+  - id: chase-freedom-flex
+    activated: [q4-2026-grocery] # rotating 5% categories you've activated
+  - id: usbank-cash-plus
+    chosen: # categories you picked for the quarter
+      period: 2026-Q4
+      picks:
+        five-percent: [tv-internet-streaming, movie-theaters]
+        two-percent: [gas-ev-charging]
+```
+
+Rule IDs for `activated` and the choice slots for `chosen` are in each card's file. Currencies and their default values are in [`data/currencies.yaml`](data/currencies.yaml). Spending caps fill up as you record purchases from an AI agent or import a statement with `--apply`, and reset with each period.
+
+### Merchants earnrate doesn't know
+
+earnrate ships with a curated list of merchants. For anything else it falls back to each card's base rate and says so. Pass `--llm` (or set `EARNRATE_LLM=on`) to have Claude guess the category instead:
+
+- It uses your own `ANTHROPIC_API_KEY` and sends only the merchant text you typed. Amounts, cards and wallet contents never leave your machine.
+- Each answer is saved in `~/.earnrate/merchant-cache.json`, so a merchant is only looked up once.
+- The answer is labeled as Claude's guess, shows its reasoning, and is never higher than medium confidence.
+- Curated merchants never reach Claude.
+
+### Welcome bonuses
+
+When you're working toward a card's sign-up bonus, add it to that card in your wallet:
+
+```yaml
+- id: chase-sapphire-preferred
+  bonus: { opened: 2026-10-01, spend: 5000, by: 2026-12-31, points: 75000 }
+```
+
+While the bonus is open, that card wins wherever it's accepted, and the answer says how much is left, the weekly pace to finish on time, what the bonus is worth at your point values, and what using it costs compared with your best earner. Spend counts up as you record purchases from an AI agent or import a statement with `--apply`; refunds count down. Once it's met or the deadline passes, the card goes back to the normal ranking. With two open bonuses, the one needing more spend per day comes first.
+
+`spend`, `by` and the reward (`points`, or `dollars` for cash back) default to the card's published offer once earnrate has one; set them when your offer was different.
+
+### Which new card?
+
+```sh
+earnrate offers --cash
+```
+
+Ranks the welcome offers on cards you don't have by first-year value: the bonus at your point values minus the first year's annual fee. `--points`, `--no-fee` and `--business` narrow it down. Each offer is the public one on the issuer's page, checked weekly like the earning rules, with the issuer's eligibility rules in its note. Offers can differ by person and by how you apply, and it covers only the cards earnrate knows. There are no affiliate or apply links.
+
+### Import a statement
+
+See what your purchases would have earned on earnrate's picks, using your cards' activity downloads:
+
+```sh
+earnrate import activity.csv --card amex-gold
+earnrate import gold.csv:amex-gold sapphire.csv:chase-sapphire-preferred
+```
+
+It totals what each card earned against the best card in your wallet for each purchase, lists the merchants where another card would have earned the most, and flags merchants your issuer codes differently than earnrate assumes. Name several statements, each with its card, to get one report across them. It reads Amex and Chase activity CSVs. Download the CSV rather than a PDF statement: Chase's PDFs print the full card number in the payment coupon, and earnrate never handles card numbers.
+
+- It's a dry run unless you pass `--apply`, which records cap usage for the current period in your wallet. Refunds lower it.
+- Only the date, description, amount, category and (for Chase) transaction type columns are read. The statements themselves are never stored: `--apply` writes cap totals plus a hash of each recorded purchase to `~/.earnrate/imported.json`, so importing the same file twice never counts twice.
+- For a merchant earnrate doesn't know, it uses the statement's category and marks the row, since another issuer may code it differently.
+- `--valuation points-heavy` values points at transfer rates instead of your wallet's values, which can change which card wins.
+
+## Supported cards
+
+56 cards, each modeled from the issuer's own terms and checked weekly against them:
+
+- **American Express:** Gold, Platinum, Blue Cash Preferred, Blue Cash Everyday, Blue Business Plus
+- **Chase:** Sapphire Preferred, Sapphire Reserve, Freedom Unlimited, Freedom Flex, Ink Business Cash, Ink Business Preferred, Prime Visa
+- **Chase airline and hotel:** United Gateway, Explorer, Quest, Club, Business, Club Business; Southwest Plus, Premier, Priority, Premier Business, Performance Business; Aeroplan; IHG One Rewards, Premier, Premier Select, Business
+- **Citi:** Strata Elite, Strata Premier, Double Cash, Custom Cash, My Best Buy Visa, Costco Anywhere Visa (personal and business); AAdvantage MileUp, Platinum Select, Globe, Executive, Business
+- **Capital One:** Venture X, Venture, Savor, Kohl's Card, Kohl's Rewards Visa
+- **Wells Fargo:** Active Cash, Autograph
+- **Bank of America:** Atmos Rewards Ascent, Summit, Business
+- **TD Bank:** Target Circle Card, Nordstrom card, Nordstrom Visa
+- **Others:** U.S. Bank Cash+, Bilt Obsidian, SoFi Unlimited 2%
+
+Store cards (Target, Kohl's, Nordstrom) only come up at their own stores. Airline and hotel cards count only what the card itself earns, not the points a program gives members however they pay, and their perks (bags, free nights, lounges) aren't counted.
+
+Something the format can't express yet (Bilt's rent earning, Citi Nights) is listed as a `todo:` in that card's file rather than guessed.
+
+Spotted a wrong rate, or want a card added? [Open an issue](https://github.com/cwasley/earnrate/issues) with a link to the issuer's own page.
+
+## Use it from an AI agent (MCP)
+
+`earnrate mcp` runs earnrate as a local MCP server over stdio, with five tools:
+
+- `best_card_for_purchase`: which card to use, with reasons
+- `resolve_merchant`: how a merchant was identified
+- `list_wallet`: your cards, caps left this period, chosen categories and welcome-bonus progress
+- `compare_welcome_offers`: the best public sign-up offers on cards you don't have
+- `record_purchase`: books a purchase against its cap and any open welcome bonus in your wallet file, keeping your comments
+
+For a merchant earnrate doesn't know, the calling model can pass a `category` (e.g. `grocery.supermarket`). It's used only for unknown merchants and is labeled in the answer. The command line takes the same thing as `--category`.
+
+To add it to Claude Code:
+
+```sh
+claude mcp add --scope user earnrate -- npx -y earnrate mcp
+```
+
+Other MCP clients take the same command in their config:
+
+```json
+{
+  "mcpServers": {
+    "earnrate": { "command": "npx", "args": ["-y", "earnrate", "mcp"] }
+  }
+}
+```
+
+It reads the same wallet as the command line (`~/.earnrate/wallet.yaml`, or `EARNRATE_WALLET` set in the server's `env`).
+
+## How it works
+
+```
+merchant text
+  → resolve    category, channel, and the assumption behind them
+  → evaluate   every rule on every card: network, dates, caps, picks, activations
+  → value      your cents per point, with pooling
+  → rank       winner, runner-ups, flip points, warnings, confidence
+```
+
+- **Card terms are data, not code.** Each card is a YAML file of rules (category, rate, cap, channel, dates, activation, required membership), validated with Zod. Every rule carries a short quote from the issuer's own page, and a test fails if one is missing. The engine has no card-specific branches.
+- **Merchants resolve to a category plus the assumption behind it.** "Whole Foods codes as a supermarket (MCC 5411)" is stated in the answer, and venues that can code more than one way (a restaurant inside a stadium or hotel) come back at medium confidence with the alternative spelled out. Unknown merchants fall back to base rates, or to an opt-in, cached and labeled Claude guess.
+- **The engine is pure and deterministic.** Given a purchase, a date and a wallet, it checks every rule against network acceptance, the date window, caps already used (split when a purchase straddles one), quarterly picks and activations, then values points at your cents-per-point, including pooling (Freedom Unlimited points are worth Sapphire points when you hold both). Ties, the valuation at which the runner-up would win, and stale data all show up in the answer.
+- **Wallet edits keep your file intact.** Recording a purchase rewrites only the numbers that changed, so comments and formatting in your YAML survive.
+- **Drift detection.** A weekly GitHub Action opens each issuer page in a headless browser, checks every quote is still there, and opens an issue when terms move. It stores only hashes of issuer text.
+- **Tested end to end.** Golden cases written from issuer terms, CLI snapshot tests, an MCP round trip over real stdio, an install test that packs and installs the npm package, and a check that no committed file contains a card number. CI runs all of it on every push.
+
+The code is TypeScript run directly by Node 24 (`src/`), with the engine in `src/engine/`, merchant resolution in `src/merchants/`, and the CLI and MCP server as thin layers over them.
+
+## Keeping card data current
+
+Every rule in `data/cards/` carries a short quote from the issuer's own page. In a clone of this repo, `yarn check-sources` opens each issuer page in a headless browser and reports:
+
+- rules whose quote is no longer on the page, which usually means the rule changed
+- earning lines that appeared or disappeared since the last baseline, such as a new perk
+
+A GitHub Action runs it every Monday and opens a "Card source changes" issue when something moved. After updating a card file, run `yarn check-sources --update` to record the new baseline. Some issuers block headless browsers on shared servers; those pages are listed as "couldn't check", and running the command locally covers them. The first run needs `yarn playwright install chromium`.
+
+## Working on earnrate
+
+```sh
+git clone https://github.com/cwasley/earnrate.git && cd earnrate
+yarn install
+yarn earnrate whole foods 80   # runs src/ directly, no build
+yarn validate                  # typecheck, lint, format check and tests
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.
+
+## Licensing
+
+- **Code** (everything outside `data/`) is [MIT](LICENSE).
+- **Data** (card rules, merchants, categories and currencies under `data/`) is [CC BY-NC 4.0](data/LICENSE). It's free for personal and non-commercial use, with attribution.
+- **Commercial use of the data needs a license.** That includes serving it through your own API or MCP server, or using it in a paid product. Contact licensing@earnrate.dev.
+
+Not legal advice; this is a good-faith structure.
+
+earnrate isn't financial advice. Issuers change their terms, and every answer names the rule it used, so check the card's issuer page (linked in its file) before a big purchase.

package/data/CHANGELOG.md

@@ -0,0 +1,210 @@
+# Data changelog
+
+Every change to card rules, merchants, categories or currencies under `data/`. Bump `data/VERSION` (`YYYY.MM.DD`, plus `.N` for a second release on the same day) and add a section here in the same commit. Each row cites the issuer page the new value came from.
+
+## 2026.10.28.1
+
+Collin reviewed the family-cards and offers packets and kept every value as recorded, including the open calls: no Peloton rule on Sapphire Preferred yet, My Best Buy Visa's fee at the top of Citi's $0–59 range, and Amex "as high as" offers at the public figure. All 56 cards are now `verified_by: collin`.
+
+| Card                               | Field       | Old → new       | Source |
+| ---------------------------------- | ----------- | --------------- | ------ |
+| the 31 cards added in 2026.10.26.6 | verified_by | claude → collin | n/a    |
+
+## 2026.10.27.1
+
+Annual fees and public welcome offers, with `business: true` on the 11 business cards. Each value is backed by a quote from the card's own product page, so a changed offer fails the weekly check. Cards stay at their existing `verified_by` until Collin reviews them.
+
+| Card                                                                                                                                                                   | Field                      | Old → new                                                                     | Source                   |
+| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | ----------------------------------------------------------------------------- | ------------------------ |
+| all cards except citi-custom-cash                                                                                                                                      | annual_fee, first_year_fee | new                                                                           | each card's product page |
+| 48 cards                                                                                                                                                               | welcome_offer              | new; Amex "as high as" offers recorded at the public figure                   | each card's product page |
+| bilt-obsidian, citi-costco-anywhere-visa(-business), citi-my-best-buy-visa, sofi-unlimited-2, citi-custom-cash, capital-one-kohls-card, capital-one-kohls-rewards-visa | welcome_offer              | none: no fixed public offer, or closed to new applicants (each has a `todo:`) | each card's product page |
+| chase-southwest-premier-business, chase-southwest-performance-business                                                                                                 | source_urls                | adds the product pages; the existing ones are cardmember-benefits pages       | creditcards.chase.com    |
+
+## 2026.10.26.7
+
+Collin's review of the family-cards packet, first pass.
+
+| Card                                                   | Field      | Old → new                                                                                                                          | Source                                                       |
+| ------------------------------------------------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| capital-one-kohls-card, capital-one-kohls-rewards-visa | unverified | removed: the 5% every Kohl's Rewards member earns is confirmed on Kohl's page (checked by hand; kohls.com blocks the weekly check) | [Kohl's Rewards](https://www.kohls.com/feature/rewards.jsp)  |
+| ihg (merchant)                                         | aliases    | adds Garner, Ruby and HUALUXE; the brand list is now confirmed against IHG's brands page                                           | [IHG brands](https://www.ihg.com/content/us/en/about/brands) |
+
+## 2026.10.26.6
+
+31 new cards, all `verified_by: claude` until Collin reviews them. Every rule cites the issuer's own page in the card file's `evidence`. Co-brand cards model only the card's own earning; program member and status points and perks aren't counted.
+
+| Card                                                                                | Field | Old → new                                 | Source                                    |
+| ----------------------------------------------------------------------------------- | ----- | ----------------------------------------- | ----------------------------------------- |
+| citi-costco-anywhere-visa, citi-costco-anywhere-visa-business                       | new   | Costco cash back cards                    | citi.com                                  |
+| citi-aadvantage-mileup, -platinum-select, -globe, -executive, -business             | new   | AAdvantage miles cards                    | citi.com                                  |
+| chase-united-gateway, -explorer, -quest, -club, -business, -club-business           | new   | United MileagePlus cards                  | creditcards.chase.com                     |
+| chase-southwest-plus, -premier, -priority, -premier-business, -performance-business | new   | Rapid Rewards cards                       | creditcards.chase.com                     |
+| chase-aeroplan                                                                      | new   | Aeroplan card                             | creditcards.chase.com                     |
+| chase-ihg-one-rewards, -premier, -premier-select, -business                         | new   | IHG One Rewards cards                     | creditcards.chase.com                     |
+| bank-of-america-atmos-rewards-ascent, -summit, -business                            | new   | Atmos Rewards cards                       | bankofamerica.com                         |
+| td-bank-target-circle-card, capital-one-kohls-card, td-bank-nordstrom-credit-card   | new   | store cards (`network: store`, `only_at`) | target.com, capitalone.com, nordstrom.com |
+| capital-one-kohls-rewards-visa, td-bank-nordstrom-visa                              | new   | the stores' Visa cards                    | capitalone.com, nordstrom.com             |
+
+New currencies: `united-miles`, `aadvantage-miles`, `southwest-rapid-rewards`, `aeroplan`, `atmos-points` (1¢ default) and `ihg-points` (0.5¢), none of which has a published fixed value, with TPG's October 2026 valuation as the range top; `kohls-rewards` and `nordy-club` at their stated 1¢ conversion.
+
+New merchants: `ihg` (with brand aliases), `air-canada`, `hawaiian-airlines`, `nordstrom-rack`, `costco-travel`, `aadvantage-hotels`, `aadvantage-cars`, `renowned-hotels-chase-travel`; domains added to `nordstrom` and `kohls`.
+
+## 2026.10.26.5
+
+Merchant fix found by importing Chase statements. No card rules changed.
+
+| Merchant | Field   | Old → new                                                          | Source |
+| -------- | ------- | ------------------------------------------------------------------ | ------ |
+| amazon   | aliases | adds `amzn mktp`, how marketplace orders appear on card statements | n/a    |
+
+## 2026.10.26.4
+
+Merchant fixes found by importing an Amex statement. No card rules changed.
+
+| Merchant    | Field   | Old → new                                                                                              | Source |
+| ----------- | ------- | ------------------------------------------------------------------------------------------------------ | ------ |
+| whole-foods | aliases | adds `wholefds`, how Whole Foods appears on card statements                                            | n/a    |
+| uber-one    | new     | Uber One membership, category `other`, so it no longer resolves to Uber rides (Amex codes it as taxis) | n/a    |
+
+## 2026.10.26.3
+
+| Card                               | Field       | Old → new                                                                                                                                | Source |
+| ---------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------ |
+| the 16 cards added in 2026.10.26.1 | verified_by | claude → collin. Collin reviewed the new-cards packet and its open decisions; every rule is backed by a quote found on the issuer's page | n/a    |
+
+All 25 cards are now `verified_by: collin`.
+
+## 2026.10.26.2
+
+Collin's call on pooling, after checking what Chase and Citi say: all four no-fee cards pool into their family's transferable points. `pools_into` now needs an evidence quote like a rule.
+
+| Card                                        | Field      | Old → new                                                                                                                                       | Source                                                                                                                                                 |
+| ------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| chase-freedom-unlimited, chase-freedom-flex | pools_into | now backed by Chase's own page; also pools when you hold Ink Business Preferred (and Freedom Unlimited when you hold Sapphire Reserve)          | [Chase: combining points](https://www.chase.com/personal/credit-cards/education/rewards-benefits/how-to-combine-chase-credit-card-points-in-household) |
+| chase-ink-business-cash                     | pools_into | new: into UR with Sapphire Preferred, Sapphire Reserve or Ink Business Preferred                                                                | [Chase: combining points](https://www.chase.com/personal/credit-cards/education/rewards-benefits/how-to-combine-chase-credit-card-points-in-household) |
+| citi-double-cash, citi-custom-cash          | pools_into | now backed by Citi's terms (combined ThankYou accounts run on one set of terms); todos removed                                                  | Citi ThankYou terms ([Double Cash](https://www.thankyou.com/dcterms), [Custom Cash](https://www.thankyou.com/ccterms))                                 |
+| several new cards                           | todo       | removed lines about categories, merchants and currencies that now exist; Blue Cash Everyday's todo now says Amazon earns its online-retail rate | n/a                                                                                                                                                    |
+
+## 2026.10.26.1
+
+Sixteen popular cards, chosen for power users. Each was drafted from the issuer's own pages, every rule carries a quote found on that page, and all are `verified_by: claude` until Collin reviews them.
+
+| Card                                                                                              | Field                                                                                                                                                                                                 | Old → new                                                                                                                                                 | Source                                                                             |
+| ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| chase-sapphire-reserve, chase-freedom-flex, chase-ink-business-cash, chase-ink-business-preferred | new                                                                                                                                                                                                   | Freedom Flex includes Q4 2026 and Q1 2027 rotating categories                                                                                             | each card's `source_urls` (creditcards.chase.com, Chase rewards FAQ)               |
+| citi-strata-elite, citi-strata-premier, citi-double-cash, citi-custom-cash                        | new                                                                                                                                                                                                   | Custom Cash closed to new applicants on 2026-05-28; its rules come from Citi's terms on thankyou.com                                                      | citi.com, thankyou.com                                                             |
+| capital-one-venture-x, capital-one-venture, capital-one-savor                                     | new                                                                                                                                                                                                   |                                                                                                                                                           | capitalone.com                                                                     |
+| bilt-obsidian                                                                                     | new                                                                                                                                                                                                   | Bilt Card 2.0 (Column N.A.); Obsidian is the tier with category bonuses                                                                                   | bilt.com                                                                           |
+| wells-fargo-active-cash, wells-fargo-autograph                                                    | new                                                                                                                                                                                                   |                                                                                                                                                           | creditcards.wellsfargo.com                                                         |
+| amex-blue-cash-everyday, amex-blue-business-plus                                                  | new                                                                                                                                                                                                   | Blue Business Plus comes from its card page; its terms page blocks automated reads                                                                        | americanexpress.com                                                                |
+| (currencies)                                                                                      | C1, TYP, WFR, BILT                                                                                                                                                                                    | new. Each defaults to the issuer's own floor value (1¢; Bilt publishes none, so 1¢ is assumed), with TPG's October 2026 valuation as the top of the range | issuer pages, [TPG](https://thepointsguy.com/loyalty-programs/monthly-valuations/) |
+| (categories)                                                                                      | online_retail, office_supply, shipping, online_advertising                                                                                                                                            | new                                                                                                                                                       | Amex and Chase terms                                                               |
+| (merchants)                                                                                       | Capital One, Citi and Bilt travel sites by booking type; Capital One Entertainment; 15 streaming services; Peloton; American Red Cross; Staples, Office Depot, UPS, FedEx, USPS, Google Ads, Meta ads | new                                                                                                                                                       | n/a (merchant names)                                                               |
+| (merchants)                                                                                       | amex-travel-hotels, -flights, -car-rentals, -cruises                                                                                                                                                  | category → `travel`: other issuers see a bank's travel site as a travel agency, not a direct hotel or airline booking                                     | Chase rewards FAQ, Citi terms                                                      |
+| (merchants)                                                                                       | amazon                                                                                                                                                                                                | category other → online_retail, so Blue Cash Everyday's 3% on U.S. online retail applies                                                                  | Amex BCE terms                                                                     |
+| amex-gold, amex-platinum                                                                          | flights-amex-travel                                                                                                                                                                                   | new rule, so Amex Travel flights keep their rate now that the merchant is a travel agency. Platinum's $500,000 cap is shared by both flight rules         | Gold and Platinum terms                                                            |
+
+## 2026.10.26
+
+| Card        | Field                                                                | Old → new                                                                                                  | Source               |
+| ----------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -------------------- |
+| (merchants) | stater-bros, pavilions, gelsons, bristol-farms, erewhon, food-4-less | new Southern California supermarkets, after "Stater Bros" fell through to base rates in the first MCP test | n/a (merchant names) |
+
+## 2026.10.24.7
+
+| Card                     | Field                 | Old → new                                                                                                                       | Source                                                                                                                                      |
+| ------------------------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| all nine cards           | evidence              | new: a short quote from the issuer page for every rule and base rate (55 in all), checked weekly by `yarn check-sources`        | each card's `source_urls`                                                                                                                   |
+| amex-blue-cash-preferred | source_urls           | terms page moved to `/en-us/credit-cards/apply/terms/personal/blue-cash-preferred-credit-card/25330-10-0`; the old address 404s | [BCP terms](https://www.americanexpress.com/en-us/credit-cards/apply/terms/personal/blue-cash-preferred-credit-card/25330-10-0#offer-terms) |
+| citi-my-best-buy-visa    | source_urls, evidence | dropped Best Buy's page (it times out for automated checks); evidence now quotes Citi's page                                    | [Citi My Best Buy page](https://www.citi.com/credit-cards/citi-best-buy-credit-cards)                                                       |
+| chase-prime-visa         | source_urls           | dropped Amazon's page (it blocks automated checks); Chase's page is the source                                                  | [Chase Prime Visa page](https://creditcards.chase.com/cash-back-credit-cards/amazon-prime-rewards)                                          |
+
+## 2026.10.24.6
+
+Prime Visa and My Best Buy Visa re-checked against the issuers' own pages (Chase and Citi); they were sourced from Amazon's and Best Buy's pages before.
+
+| Card                                    | Field                          | Old → new                                                                                                              | Source                                                                                                                                                                                    |
+| --------------------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| chase-prime-visa                        | amazon-without-prime           | new rule: 3% at Amazon.com, Amazon Fresh, Whole Foods and Audible without Prime (was the 1% base)                      | [Chase Prime Visa page](https://creditcards.chase.com/cash-back-credit-cards/amazon-prime-rewards)                                                                                        |
+| chase-prime-visa                        | chase-travel-without-prime     | new rule: 3% on Chase Travel without Prime                                                                             | [Chase Prime Visa page](https://creditcards.chase.com/cash-back-credit-cards/amazon-prime-rewards)                                                                                        |
+| chase-prime-visa                        | audible                        | new rule: 5% at Audible.com with Prime                                                                                 | [Chase Prime Visa page](https://creditcards.chase.com/cash-back-credit-cards/amazon-prime-rewards)                                                                                        |
+| chase-prime-visa                        | amazon.note, chase-travel.note | added the exclusions: Amazon Pay at other sites, international Amazon sites, and travel booked directly with suppliers | [Chase Prime Visa page](https://creditcards.chase.com/cash-back-credit-cards/amazon-prime-rewards)                                                                                        |
+| (merchants)                             | audible, pacific-kitchen-home  | new                                                                                                                    | [Chase Prime Visa page](https://creditcards.chase.com/cash-back-credit-cards/amazon-prime-rewards), [Citi My Best Buy page](https://www.citi.com/credit-cards/citi-best-buy-credit-cards) |
+| citi-my-best-buy-visa                   | best-buy.match                 | adds Pacific Kitchen & Home                                                                                            | [Citi My Best Buy page](https://www.citi.com/credit-cards/citi-best-buy-credit-cards)                                                                                                     |
+| (currencies)                            | best-buy-rewards.note          | 250 points = a $5 certificate, confirming 2¢ a point                                                                   | [Citi My Best Buy page](https://www.citi.com/credit-cards/citi-best-buy-credit-cards)                                                                                                     |
+| chase-prime-visa, citi-my-best-buy-visa | verified_by                    | claude → collin                                                                                                        | n/a                                                                                                                                                                                       |
+
+## 2026.10.24.5
+
+Read from Amex's own offer terms after Collin flagged the October 22, 2026 Amex–Airbnb partnership.
+
+| Card                     | Field                                                                                                     | Old → new                                                                                                                                                                                                     | Source                                                                                                                                                                                                                                                 |
+| ------------------------ | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| (merchants)              | amex-travel-hotels, amex-travel-flights, airbnb-amex-travel, amex-travel-car-rentals, amex-travel-cruises | new: one merchant per Amex Travel booking type. The old Amex Travel rules required both the Amex Travel merchant and a hotel/car/cruise category, which the generic merchant never had, so they never matched | [Gold terms](https://www.americanexpress.com/en-us/credit-cards/apply/terms/personal/gold-card/25330-10-0#offer-terms), [Platinum terms](https://www.americanexpress.com/en-us/credit-cards/apply/terms/personal/platinum-card/25330-10-0#offer-terms) |
+| (merchants)              | amex-travel, airbnb                                                                                       | new `booked_via`: answers say when booking through Amex Travel would earn more                                                                                                                                | n/a                                                                                                                                                                                                                                                    |
+| amex-gold                | airbnb-amex-travel                                                                                        | new rule: 2x on prepaid Airbnb stays booked through Amex Travel (was a todo)                                                                                                                                  | [Gold terms](https://www.americanexpress.com/en-us/credit-cards/apply/terms/personal/gold-card/25330-10-0#offer-terms)                                                                                                                                 |
+| amex-gold                | restaurants.exclude                                                                                       | new: no 4x at restaurants inside hotels, casinos or event venues (Dodger Stadium, Bellagio) or at bars (MCC 5813)                                                                                             | [Gold terms](https://www.americanexpress.com/en-us/credit-cards/apply/terms/personal/gold-card/25330-10-0#offer-terms)                                                                                                                                 |
+| amex-gold                | restaurants.note, flights.note                                                                            | reworded to the terms; dropped the unsourced "other travel sites earn 1x"                                                                                                                                     | [Gold terms](https://www.americanexpress.com/en-us/credit-cards/apply/terms/personal/gold-card/25330-10-0#offer-terms)                                                                                                                                 |
+| amex-platinum            | airbnb-amex-travel                                                                                        | new rule: 5x on prepaid Airbnb stays booked through Amex Travel (was a todo)                                                                                                                                  | [Platinum terms](https://www.americanexpress.com/en-us/credit-cards/apply/terms/personal/platinum-card/25330-10-0#offer-terms)                                                                                                                         |
+| amex-platinum            | cruises-amex-travel                                                                                       | new rule: 2x on cruises booked through Amex Travel                                                                                                                                                            | [Platinum terms](https://www.americanexpress.com/en-us/credit-cards/apply/terms/personal/platinum-card/25330-10-0#offer-terms)                                                                                                                         |
+| amex-platinum            | flights.note                                                                                              | "scheduled" means not charter or private jet; flights in tours, cruises or packages are excluded                                                                                                              | [Platinum terms](https://www.americanexpress.com/en-us/credit-cards/apply/terms/personal/platinum-card/25330-10-0#offer-terms)                                                                                                                         |
+| amex-gold, amex-platinum | verified_by                                                                                               | claude → collin, after Collin's review and the terms check above                                                                                                                                              | n/a                                                                                                                                                                                                                                                    |
+
+## 2026.10.24.4
+
+| Card                                                                                                            | Field       | Old → new                                                                                                                                          | Source |
+| --------------------------------------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
+| amex-blue-cash-preferred, usbank-cash-plus, chase-sapphire-preferred, chase-freedom-unlimited, sofi-unlimited-2 | verified_by | claude → collin. Collin reviewed the flagged items from the 2026-10-24 rule-by-rule re-check; the rest were backed by quotes from the issuer pages | n/a    |
+
+Still `claude`: amex-gold and amex-platinum (Airbnb rules and "scheduled" flights wait on reading Amex's terms), chase-prime-visa and citi-my-best-buy-visa (sourced from the co-brand partner's page, not the issuer's).
+
+## 2026.10.24.3
+
+From Collin's review of the yellow rows in the card re-check.
+
+| Card                     | Field                                                                                                                                | Old → new                                                                                                                                                      | Source                                                                                                                                                                                                                                     |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| (categories)             | gas.grocery_store, gas.superstore                                                                                                    | new: gas sold by grocery stores, and by superstores and warehouse clubs. "Kroger gas" or "Walmart fuel" now resolves to these instead of to the store itself   | [BCP terms](https://www.americanexpress.com/us/credit-cards/card-application/apply/prospect/terms/blue-cash-preferred-credit-card/25330-10-0#offer-terms), [Cash+ sample merchants](https://cashplus.usbank.com/cash-plus/samplemerchants) |
+| (merchants)              | costco-gas, sams-club-gas                                                                                                            | category gas → gas.superstore                                                                                                                                  | [BCP terms](https://www.americanexpress.com/us/credit-cards/card-application/apply/prospect/terms/blue-cash-preferred-credit-card/25330-10-0#offer-terms)                                                                                  |
+| amex-blue-cash-preferred | us-gas.exclude                                                                                                                       | Costco and Sam's Club gas → all grocery-store, superstore and warehouse-club gas                                                                               | [BCP terms](https://www.americanexpress.com/us/credit-cards/card-application/apply/prospect/terms/blue-cash-preferred-credit-card/25330-10-0#offer-terms)                                                                                  |
+| usbank-cash-plus         | two-percent.exclude                                                                                                                  | Costco and Sam's Club gas → all superstore and warehouse-club gas. Grocery-store gas still counts; U.S. Bank lists Kroger Fuel Center as a sample gas merchant | [Cash+ page](https://www.usbank.com/credit-cards/cash-plus-visa-signature-credit-card.html), [Cash+ sample merchants](https://cashplus.usbank.com/cash-plus/samplemerchants)                                                               |
+| usbank-cash-plus         | select-clothing-stores                                                                                                               | every clothing store → only the 13 stores U.S. Bank lists ("This category includes only the merchants listed below")                                           | [Cash+ sample merchants](https://cashplus.usbank.com/cash-plus/samplemerchants)                                                                                                                                                            |
+| (merchants)              | aeropostale, american-eagle, ann-taylor, banana-republic, eddie-bauer, express, forever-21, j-crew, jos-a-bank, talbots, the-limited | new, for the Cash+ clothing list                                                                                                                               | [Cash+ sample merchants](https://cashplus.usbank.com/cash-plus/samplemerchants)                                                                                                                                                            |
+| chase-sapphire-preferred | online-grocery.exclude                                                                                                               | Costco and Sam's Club → all warehouse clubs                                                                                                                    | [CSP page](https://creditcards.chase.com/rewards-credit-cards/sapphire/preferred)                                                                                                                                                          |
+| chase-freedom-unlimited  | pools_into                                                                                                                           | kept: the card page doesn't say it, but Collin has combined these points before                                                                                | Collin (cardholder)                                                                                                                                                                                                                        |
+| chase-prime-visa         | amazon-fresh.note                                                                                                                    | added: the physical stores closed or became Whole Foods in 2026                                                                                                | Collin                                                                                                                                                                                                                                     |
+
+## 2026.10.24.2
+
+From a rule-by-rule re-check of every card file against its issuer's pages. Still `verified_by: claude`.
+
+| Card                     | Field                                  | Old → new                                                                                                                             | Source                                                                                            |
+| ------------------------ | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| chase-sapphire-preferred | vacation-homes                         | new rule: 3x on direct bookings with Airbnb, Vrbo/HomeAway, Vacasa, Plum Guide and Homestay.com (was a todo)                          | [Chase rewards FAQ](https://www.chase.com/personal/credit-cards/rewards-category-faq)             |
+| chase-sapphire-preferred | lyft                                   | new rule: 5x on Lyft rides through 2027-09-30                                                                                         | [CSP page](https://creditcards.chase.com/rewards-credit-cards/sapphire/preferred)                 |
+| chase-sapphire-preferred | transit-as-travel.unverified           | flag removed: Chase's travel category lists trains, buses, taxis, ferries, tolls and parking                                          | [Chase rewards FAQ](https://www.chase.com/personal/credit-cards/rewards-category-faq)             |
+| chase-freedom-unlimited  | lyft                                   | new rule: 2% total on Lyft app purchases through 2027-09-30                                                                           | [CFU page](https://creditcards.chase.com/cash-back-credit-cards/freedom/unlimited)                |
+| (merchants)              | vrbo, vacasa, plum-guide, homestay-com | new, for the vacation-homes rule                                                                                                      | [Chase rewards FAQ](https://www.chase.com/personal/credit-cards/rewards-category-faq)             |
+| (currencies)             | sofi-rewards.note                      | removed "statement-credit value isn't published": redeeming into the SoFi Credit Card account is 1¢ a point, like other SoFi accounts | [SoFi rewards terms](https://www.sofi.com/card/rewards?cardtype=c)                                |
+| (currencies)             | best-buy-rewards.note                  | dropped "usable only at Best Buy", which the page doesn't say                                                                         | [Best Buy rewards page](https://www.bestbuy.com/site/misc/financing-rewards/pcmcat102500050032.c) |
+| citi-my-best-buy-visa    | best-buy.note                          | Plus/Total wording now matches the page: membership rewards are counted separately                                                    | [Best Buy rewards page](https://www.bestbuy.com/site/misc/financing-rewards/pcmcat102500050032.c) |
+
+## 2026.10.24.1
+
+| Card         | Field                                | Old → new                                                                                 | Source              |
+| ------------ | ------------------------------------ | ----------------------------------------------------------------------------------------- | ------------------- |
+| (categories) | superstore.name, warehouse_club.name | dropped the example merchants in parentheses, which read badly inside engine explanations | n/a (display names) |
+
+## 2026.10.24
+
+First release. Nine cards, each checked against its issuer's page (`verified_by: claude`, not yet reviewed by Collin): Amex Gold, Blue Cash Preferred and Platinum; Chase Sapphire Preferred, Freedom Unlimited and Prime Visa; U.S. Bank Cash+; My Best Buy Visa; SoFi Unlimited 2%. 91 merchants, 32 categories, 5 currencies.
+
+Corrections made before release, after reading Amex's offer terms:
+
+| Card                     | Field                      | Old → new                                                                        | Source                                                                                                                                                    |
+| ------------------------ | -------------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| amex-blue-cash-preferred | us-supermarkets.exclude    | removed `specialty_food` (it came from review sites; Amex's terms don't list it) | [BCP terms](https://www.americanexpress.com/us/credit-cards/card-application/apply/prospect/terms/blue-cash-preferred-credit-card/25330-10-0#offer-terms) |
+| amex-blue-cash-preferred | us-supermarkets.unverified | cap period confirmed as calendar year, flag removed                              | BCP terms                                                                                                                                                 |
+| amex-gold                | us-supermarkets.exclude    | removed `specialty_food`                                                         | [Gold terms](https://www.americanexpress.com/en-us/credit-cards/apply/terms/personal/gold-card/25330-10-0#offer-terms)                                    |
+| amex-gold, amex-platinum | todo                       | added: Airbnb via Amex Travel (2x Gold, 5x Platinum) not modeled                 | Gold and [Platinum terms](https://www.americanexpress.com/en-us/credit-cards/apply/terms/personal/platinum-card/25330-10-0#offer-terms)                   |