earnrate 0.2.3 → 0.2.4

package/README.md

@@ -65,6 +65,7 @@ Options: `--online` or `--in-store`, `--valuation flat|points-heavy`, `--all`, `
 The wallet is a YAML file (`~/.earnrate/wallet.yaml`) listing your cards by ID, which is each card's file name in [`data/cards/`](data/cards). `earnrate add`, `update`, `remove` and `memberships` write it for you and keep your comments, or you can edit it by hand. Only the cards are required:
 
 ```yaml
+version: 1 # the file's format; earnrate writes it
 valuations:
   UR: 1.5 # cents per point; leave out to use earnrate's defaults
 memberships: [amazon-prime] # unlocks Prime Visa's 5%
@@ -81,7 +82,7 @@ cards:
         two-percent: [gas-ev-charging]
 ```
 
-Rule IDs for `activated`, the choice slots for `chosen` and the membership IDs that unlock bonuses (such as `bofa-rewards-premier` for a BofA Rewards tier) 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 assistant or import a statement with `--apply`, and reset with each period.
+Rule IDs for `activated`, the choice slots for `chosen` and the membership IDs that unlock bonuses (such as `bofa-rewards-premier` for a BofA Rewards tier) are in each card's file. Add `costco` if you have a Costco membership: Costco Anywhere needs one, and spending answers count its $65 a year unless you have it, hold the card or spend at Costco. Currencies and their default values are in [`data/currencies.yaml`](data/currencies.yaml). Spending caps fill up as you record purchases from an AI assistant or import a statement with `--apply`, and reset with each period.
 
 ### Merchants earnrate doesn't know
 
@@ -107,7 +108,7 @@ Or tell your AI assistant ("I opened my Sapphire Preferred on October 1"), or ch
   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 assistant or the website) 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.
+While the bonus is open and you're behind an even pace to the deadline, 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. On pace, it's the pick only where it earns as much as your best card, and it's mentioned where it comes within a point; otherwise your best card wins. Spend counts up as you record purchases from an AI assistant 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, one behind pace comes first, then the one needing more spend per day.
 
 `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.
 
@@ -121,13 +122,13 @@ earnrate simulate groceries=600 dining=300 other=1000 # best cards and pairs for
 earnrate simulate groceries=600 other=1000 --wallet   # what a new card would add to yours
 ```
 
-`best` ranks every card earnrate knows for a merchant or a category, each set up at its best (the right category pick, activated, cap unused), with its annual fee and what earning the rate takes. Rates that need a membership like Amazon Prime are listed separately unless you pass `--member amazon-prime`. `simulate` spends your monthly amounts for a year, applying caps as they fill and reset, and ranks single cards and two-card pairs by rewards minus annual fees. Both take `--no-fee`, `--cash` or `--points`, `--issuer`, `--business` and `--valuation`. Welcome bonuses are left out of both; for those:
+`best` ranks every card earnrate knows for a merchant or a category, each set up at its best (the right category pick, activated, cap unused), with its annual fee and what earning the rate takes. Rates that need a membership like Amazon Prime are listed separately unless you pass `--member amazon-prime`, and a card that needs a membership to get (Costco Anywhere) says so. `simulate` spends your monthly amounts for a year, applying caps as they fill and reset, and ranks single cards and two-card pairs by rewards minus annual fees, counting the cost of a membership a card needs (Costco's, for Costco Anywhere) unless you pass `--member costco` or spend at Costco. Both take `--no-fee`, `--cash` or `--points`, `--issuer`, `--business` and `--valuation`. Welcome bonuses are left out of both; for those:
 
 ```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.
+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 (and a membership the card needs, if you don't have it). An offer the issuer rules out because of a card in your wallet is marked "likely not eligible" and listed last. `--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
 
@@ -140,8 +141,8 @@ 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.
+- It's a dry run unless you pass `--apply`, which records cap usage for the current period and spending toward an open welcome bonus in your wallet. Refunds lower both.
+- Only the date, description, amount, category and (for Chase) transaction type columns are read. The statements themselves are never stored: `--apply` writes cap and bonus 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.
 
@@ -175,7 +176,7 @@ claude mcp add --transport http earnrate https://mcp.earnrate.dev
 
 Or install it as a Claude Code plugin, which connects Claude Code and Cowork to the same server: `/plugin marketplace add cwasley/earnrate`, then `/plugin install earnrate@earnrate`.
 
-**Or run it on your computer:** `earnrate mcp` runs earnrate as a local MCP server over stdio, with 13 tools (the connector has the same ones, plus `export_wallet`, `import_wallet` and `delete_wallet` for its saved wallets):
+**Or run it on your computer:** `earnrate mcp` runs earnrate as a local MCP server over stdio, with 13 tools (the connector has the same ones, plus `export_wallet`, `import_wallet`, `delete_wallet` and `switch_wallet` for its saved wallets):
 
 - `best_card_for_purchase`: which card to use, with reasons
 - `best_cards_for` and `simulate_spending`: compare every card earnrate knows, for one purchase or a year of spending, with no wallet needed
@@ -224,7 +225,7 @@ merchant text
 - **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 set of cards (yours, or every card), 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, stale data, and a rotating card whose new quarter isn't in the data yet all show up in the answer.
 - **Wallet edits keep your file intact.** Adding or changing a card, or recording a purchase, splices in only the lines that changed and checks the result before saving, 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.
+- **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. A daily one checks earnrate.dev and the hosted server end to end (sign in, ask, save a card, delete the wallet) and opens an issue if anything fails.
 - **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. `site/` is earnrate.dev, which runs the same engine in the browser, and `remote/` is the hosted server at mcp.earnrate.dev.
@@ -242,14 +243,14 @@ Rotating categories (Freedom Flex) are added each quarter once the issuer posts
 
 ## Privacy Policy
 
-earnrate needs no account. The local version has no telemetry; the hosted server counts requests by tool name only. The full policy is at [earnrate.dev/privacy](https://earnrate.dev/privacy); in short:
+earnrate needs no account. The local version has no telemetry; the hosted server counts requests by method and tool name only. The full policy is at [earnrate.dev/privacy](https://earnrate.dev/privacy); in short:
 
-- **The Claude connector:** earnrate's server at mcp.earnrate.dev receives each question Claude asks it (a store or kind of purchase, and any amount, spending or cards you gave) and answers without keeping it; request logging is off. It counts requests by tool name only. A saved wallet is optional and anonymous (a recovery code, no email), holds card IDs and the details you gave, never card numbers, and is encrypted with its own key that only your recovery code or your connected apps can unlock. Delete it any time; it's deleted automatically after 13 months unused, or a week if it's never used.
+- **The Claude connector:** earnrate's server at mcp.earnrate.dev receives each question Claude asks it (a store or kind of purchase, and any amount, spending or cards you gave) and answers without keeping it; request logging is off. It counts requests by method and tool name only. Connecting it starts an anonymous wallet (a recovery code, no email). It holds cards only if you save some: card IDs and the details you gave, never card numbers, and is encrypted with its own key that only your recovery code or your connected apps can unlock. Delete it any time; it's deleted automatically after 13 months unused, or a week if it's never used.
 - **What it stores locally:** your wallet, a YAML file on your computer (`~/.earnrate/wallet.yaml` unless you set `EARNRATE_WALLET`). It lists cards by product ID, like `amex-gold`, plus your category picks, activations and how much you've spent toward caps. earnrate never asks for or stores card numbers, expiry dates, security codes or bank logins.
 - **What the local version sends:** nothing, by default. The optional merchant lookup (off unless you turn it on with your own Anthropic API key) sends only the name of a store earnrate doesn't recognize to Anthropic's API, and saves the answer in `~/.earnrate/merchant-cache.json`.
 - **AI assistants:** when you use earnrate through Claude or another assistant, that assistant's provider sees the conversation, including earnrate's answers, under its own privacy policy.
 - **earnrate.dev:** everything you enter on the site stays in your browser. The site counts visits with Cloudflare Web Analytics, without cookies.
-- **Retention:** locally, your data lives only in files you control, for as long as you keep them. Delete the wallet file, or clear the site's data in your browser, to remove it. A saved wallet on mcp.earnrate.dev lasts until you delete it or leave it unused for 13 months.
+- **Retention:** locally, your data lives only in files you control, for as long as you keep them. Delete the wallet file, or clear the site's data in your browser, to remove it. A saved wallet on mcp.earnrate.dev lasts until you delete it or leave it unused for 13 months (a week, if it's never used); the record that an app is connected goes after 90 days unused.
 - **Terms:** [earnrate.dev/terms](https://earnrate.dev/terms).
 - **Contact:** [hello@earnrate.dev](mailto:hello@earnrate.dev).
 

package/data/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 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.11.01.3
+
+Welcome offers can name other cards whose holders the issuer rules out (`welcome_offer.not_with`), so offer comparisons mark them and list them last for a wallet holding one. No rates changed.
+
+| Card                                                                    | Field                  | Old → new                                            | Source                                                                                                                                                                                                                                     |
+| ----------------------------------------------------------------------- | ---------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| amex-blue-cash-everyday                                                 | welcome_offer.not_with | amex-blue-cash-preferred                             | [offer terms](https://www.americanexpress.com/en-us/credit-cards/apply/terms/personal/blue-cash-everyday-credit-card/25330-10-0)                                                                                                           |
+| chase-southwest-plus, chase-southwest-priority, chase-southwest-premier | welcome_offer.not_with | the other two personal Southwest cards               | [Plus](https://creditcards.chase.com/travel-credit-cards/southwest/plus), [Priority](https://creditcards.chase.com/travel-credit-cards/southwest/priority), [Premier](https://creditcards.chase.com/travel-credit-cards/southwest/premier) |
+| amex-blue-cash-everyday                                                 | welcome_offer evidence | card page headline now "As High As $200"; same offer | [card page](https://www.americanexpress.com/us/credit-cards/card/blue-cash-everyday/)                                                                                                                                                      |
+
+## 2026.11.01.2
+
+Chipotle may post as fast food (MCC 5814) instead of a restaurant, so answers there say which card wins either way. No rates changed.
+
+| Merchant | Field     | Old → new             | Source |
+| -------- | --------- | --------------------- | ------ |
+| chipotle | ambiguity | may code as fast food | n/a    |
+
+## 2026.11.01.1
+
+Freedom Flex's Q4 dining note quotes Chase's "5% total" and says where the 7% figure comes from. No rates changed.
+
+| Card               | Field               | Old → new            | Source                                                                         |
+| ------------------ | ------------------- | -------------------- | ------------------------------------------------------------------------------ |
+| chase-freedom-flex | q4-2026-dining.note | quotes Chase's terms | [card page](https://creditcards.chase.com/cash-back-credit-cards/freedom/flex) |
+
+## 2026.11.01
+
+Cards can name a paid membership they need (`requires_membership`). Costco Anywhere needs a Costco membership, $65 a year for Gold Star; spending answers count it unless the person has one or shops at Costco. The AAdvantage Globe card page reworded its earning lines; no rates changed.
+
+| Card                                                          | Field               | Old → new                                     | Source                                                                                                                                                       |
+| ------------------------------------------------------------- | ------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| citi-costco-anywhere-visa, citi-costco-anywhere-visa-business | requires_membership | Costco membership, $65 a year                 | [Citi card page](https://www.citi.com/credit-cards/citi-costco-anywhere-visa-credit-card), [Costco membership page](https://www.costco.com/join-costco.html) |
+| citi-aadvantage-globe                                         | evidence            | quotes follow Citi's new wording (same rates) | [card page](https://www.citi.com/credit-cards/citi-aadvantage-globe-mastercard)                                                                              |
+
 ## 2026.10.30.3
 
 More everyday words find categories, for questions asked without a store name ("coffee shop", "dinner", "train"). Each maps to the category those purchases already fall under. No rates changed.

package/data/VERSION

@@ -1 +1 @@
-2026.10.30.3
+2026.11.01.3

package/data/cards/amex-blue-cash-everyday.yaml

@@ -15,7 +15,8 @@ welcome_offer:
   spend: 2000
   months: 6
   varies: true
-  note: 'Paid as Reward Dollars, redeemable for a statement credit or at Amazon.com checkout. The card page says "Earn $200"; the offer terms say "as high as $200", with the exact amount shown before you accept. Not available if you have or have had this Card, the Cash Magnet Card, the Blue Cash Preferred Card (including the Morgan Stanley version) or previous versions of these Cards.'
+  not_with: [amex-blue-cash-preferred]
+  note: 'Paid as Reward Dollars, redeemable for a statement credit or at Amazon.com checkout. The card page and offer terms say "as high as $200", with the exact amount shown before you accept; the card page has also shown "Earn $200". Not available if you have or have had this Card, the Cash Magnet Card, the Blue Cash Preferred Card (including the Morgan Stanley version) or previous versions of these Cards.'
 rules:
   - id: us-supermarkets
     match: { categories: [grocery.supermarket] }
@@ -76,14 +77,14 @@ evidence:
   - rule: annual_fee
     url: https://www.americanexpress.com/us/credit-cards/card/blue-cash-everyday/
     quote: 'No Annual Fee'
-  - rule: welcome_offer
-    url: https://www.americanexpress.com/us/credit-cards/card/blue-cash-everyday/
-    quote: 'Earn $200 Cash Back'
   - rule: welcome_offer
     url: https://www.americanexpress.com/us/credit-cards/card/blue-cash-everyday/
     quote: 'after you spend $2,000 in purchases on your new Card in the first 6 months of Card Membership'
   - rule: welcome_offer
     url: https://www.americanexpress.com/en-us/credit-cards/apply/terms/personal/blue-cash-everyday-credit-card/25330-10-0
     quote: 'As High as $200 Cash Back Welcome Offer'
+  - rule: not_with
+    url: https://www.americanexpress.com/en-us/credit-cards/apply/terms/personal/blue-cash-everyday-credit-card/25330-10-0
+    quote: 'if you have or have had this Card, the Cash Magnet® Card, the Blue Cash Preferred® Card'
 todo:
   - 'Amazon is filed as online retail, so it earns 3% here; superstore sites (walmart.com, target.com) and online drugstores may too, but the terms define the category by merchant code and type of goods, so they are not modeled.'

package/data/cards/chase-freedom-flex.yaml

@@ -66,7 +66,7 @@ rules:
     requires: { activation: true }
     valid_from: 2026-10-01
     valid_to: 2026-12-31
-    note: Chase says activated categories earn 5% total (4% on top of the 1% base) and doesn't say whether that stacks with the 3% dining rate, so earnrate shows 5%, not 7%, until the $1,500 quarterly cap.
+    note: Chase's terms say activated categories earn "5% Cash Back rewards total" (4% on top of the 1% base), so earnrate shows 5% until the $1,500 quarterly cap. Some blogs report 7% for dining (the 3% dining rate plus the 4% bonus); Chase's own terms don't say that.
   - id: q4-2026-american-red-cross
     match: { merchants: [american-red-cross] }
     rate: 5

package/data/cards/chase-southwest-plus.yaml

@@ -14,6 +14,7 @@ welcome_offer:
   points: 80000
   spend: 1000
   months: 3
+  not_with: [chase-southwest-priority, chase-southwest-premier]
   note: 'Chase labels it a limited-time offer and states no end date. Not available to current cardmembers of any Southwest Rapid Rewards Credit Card, or previous cardmembers of any Southwest Rapid Rewards Credit Card who received a new Cardmember bonus within the last 24 months (this does not apply to business cards).'
 caps:
   - id: gas-and-grocery
@@ -70,3 +71,6 @@ evidence:
   - rule: lyft
     url: https://creditcards.chase.com/travel-credit-cards/southwest/plus
     quote: 'earn 2X Rapid Rewards points on qualifying Lyft products and services purchased through the Lyft mobile application through 12/31/2027'
+  - rule: not_with
+    url: https://creditcards.chase.com/travel-credit-cards/southwest/plus
+    quote: 'not available to either (i) current Cardmembers of any Southwest Rapid Rewards® Credit Card'

package/data/cards/chase-southwest-premier.yaml

@@ -14,6 +14,7 @@ welcome_offer:
   points: 85000
   spend: 2000
   months: 3
+  not_with: [chase-southwest-plus, chase-southwest-priority]
   note: 'Chase labels it a limited-time offer and states no end date. Not available to current cardmembers of any Southwest Rapid Rewards Credit Card, or previous cardmembers of any Southwest Rapid Rewards Credit Card who received a new Cardmember bonus within the last 24 months (this does not apply to business cards).'
 caps:
   - id: grocery-and-dining
@@ -70,3 +71,6 @@ evidence:
   - rule: lyft
     url: https://creditcards.chase.com/travel-credit-cards/southwest/premier
     quote: 'earn 3X Rapid Rewards points on qualifying Lyft products and services purchased through the Lyft mobile application through 12/31/2027'
+  - rule: not_with
+    url: https://creditcards.chase.com/travel-credit-cards/southwest/premier
+    quote: 'not available to either (i) current Cardmembers of any Southwest Rapid Rewards® Credit Card'

package/data/cards/chase-southwest-priority.yaml

@@ -13,6 +13,7 @@ welcome_offer:
   points: 90000
   spend: 3000
   months: 3
+  not_with: [chase-southwest-plus, chase-southwest-premier]
   note: 'Chase labels it a limited-time offer and states no end date. Not available to current cardmembers of any Southwest Rapid Rewards Credit Card, or previous cardmembers of any Southwest Rapid Rewards Credit Card who received a new Cardmember bonus within the last 24 months (this does not apply to business cards).'
 rules:
   - id: southwest
@@ -56,3 +57,6 @@ evidence:
   - rule: lyft
     url: https://creditcards.chase.com/travel-credit-cards/southwest/priority
     quote: 'earn 5X Rapid Rewards points on qualifying Lyft products and services purchased through the Lyft mobile application through 12/31/2027'
+  - rule: not_with
+    url: https://creditcards.chase.com/travel-credit-cards/southwest/priority
+    quote: 'not available to either (i) current Cardmembers of any Southwest Rapid Rewards® Credit Card'

package/data/cards/citi-aadvantage-globe.yaml

@@ -3,8 +3,8 @@ name: Citi / AAdvantage Globe Mastercard
 issuer: citi
 network: mastercard
 currency: aadvantage-miles
-last_verified: 2026-10-26
-verified_by: collin
+last_verified: 2026-11-01
+verified_by: claude
 source_urls:
   - https://www.citi.com/credit-cards/citi-aadvantage-globe-mastercard
 base_rate: 1
@@ -35,22 +35,22 @@ rules:
 evidence:
   - rule: base_rate
     url: https://www.citi.com/credit-cards/citi-aadvantage-globe-mastercard
-    quote: 'Earn 1 AAdvantage® mile for every $1 spent on all other purchases.'
+    quote: 'Earn 1 AAdvantage® mile for every $1 spent on all other purchases'
   - rule: aadvantage-hotels
     url: https://www.citi.com/credit-cards/citi-aadvantage-globe-mastercard
-    quote: 'Earn 6 AAdvantage® miles per $1 spent on eligible AAdvantage Hotels™ bookings'
+    quote: 'Earn 6 AAdvantage® miles for every $1 spent on eligible AAdvantage Hotels™ bookings'
   - rule: american-airlines
     url: https://www.citi.com/credit-cards/citi-aadvantage-globe-mastercard
-    quote: '3 AAdvantage® miles per $1 spent on eligible American Airlines purchases'
+    quote: '3 AAdvantage® miles for every $1 spent on eligible American Airlines purchases'
   - rule: american-airlines
     url: https://www.citi.com/credit-cards/citi-aadvantage-globe-mastercard
     quote: 'Eligible American Airlines purchases are items billed by American Airlines as the merchant of record.'
   - rule: restaurants
     url: https://www.citi.com/credit-cards/citi-aadvantage-globe-mastercard
-    quote: 'Earn 2 AAdvantage® miles for every $1 spent at restaurants, including takeout and delivery.'
+    quote: 'Earn 2 AAdvantage® miles for every $1 spent at restaurants, including takeout and delivery'
   - rule: rides-and-rails
     url: https://www.citi.com/credit-cards/citi-aadvantage-globe-mastercard
-    quote: 'Earn 2 AAdvantage® miles for every $1 spent on eligible Rides and Rails™ purchases, including taxis, rideshares and public transit.'
+    quote: 'Earn 2 AAdvantage® miles for every $1 spent on eligible Rides and Rails™ purchases, including taxis, rideshares and public transit'
   - rule: rides-and-rails
     url: https://www.citi.com/credit-cards/citi-aadvantage-globe-mastercard
     quote: 'passenger railways, bridge and road tolls, parking lots'

package/data/cards/citi-costco-anywhere-visa-business.yaml

@@ -7,11 +7,19 @@ last_verified: 2026-10-31
 verified_by: claude
 source_urls:
   - https://www.citi.com/credit-cards/costco-anywhere-visa-business-card
+  - https://www.costco.com/join-costco.html
 # Paid once a year as a Costco reward certificate after the February statement,
 # redeemable for cash or merchandise at a U.S. Costco warehouse.
 base_rate: 1
 business: true
 annual_fee: 0
+# Gold Star, the basic tier. Executive ($130) pays some of its cost back as
+# Costco's own 2% reward, which earnrate doesn't model.
+requires_membership:
+  id: costco
+  name: a Costco membership
+  annual_fee: 65
+  members_shop_at: [costco, costco-gas, costco-travel]
 caps:
   # Costco gas, other gas and EV charging share one $7,000 cap. Rewards run on
   # January–December billing statements.
@@ -47,7 +55,7 @@ rules:
     rate: 2
     note: All other purchases at Costco warehouses and Costco.com.
 todo:
-  - 'The $0 annual fee requires an active, paid Costco membership. The card page shows no welcome offer.'
+  - 'The card page shows no welcome offer.'
 evidence:
   - rule: base_rate
     url: https://www.citi.com/credit-cards/costco-anywhere-visa-business-card
@@ -85,3 +93,9 @@ evidence:
   - rule: annual_fee
     url: https://www.citi.com/credit-cards/costco-anywhere-visa-business-card
     quote: '$0 annual fee with active Costco membership.'
+  - rule: requires_membership
+    url: https://www.citi.com/credit-cards/costco-anywhere-visa-business-card
+    quote: 'No annual fee with paid Costco membership.'
+  - rule: requires_membership
+    url: https://www.costco.com/join-costco.html
+    quote: 'Gold Star $65/yr'

package/data/cards/citi-costco-anywhere-visa.yaml

@@ -7,10 +7,18 @@ last_verified: 2026-10-26
 verified_by: collin
 source_urls:
   - https://www.citi.com/credit-cards/citi-costco-anywhere-visa-credit-card
+  - https://www.costco.com/join-costco.html
 # Paid once a year as a Costco reward certificate after the February statement,
 # redeemable for cash or merchandise at a U.S. Costco warehouse.
 base_rate: 1
 annual_fee: 0
+# Gold Star, the basic tier. Executive ($130) pays some of its cost back as
+# Costco's own 2% reward, which earnrate doesn't model.
+requires_membership:
+  id: costco
+  name: a Costco membership
+  annual_fee: 65
+  members_shop_at: [costco, costco-gas, costco-travel]
 caps:
   # Costco gas, other gas and EV charging share one $7,000 cap. Rewards run on
   # January–December billing statements.
@@ -46,7 +54,7 @@ rules:
     rate: 2
     note: All other purchases at Costco warehouses and Costco.com.
 todo:
-  - 'The $0 annual fee requires an active, paid Costco membership. The card page shows no welcome offer.'
+  - 'The card page shows no welcome offer.'
 evidence:
   - rule: base_rate
     url: https://www.citi.com/credit-cards/citi-costco-anywhere-visa-credit-card
@@ -84,3 +92,9 @@ evidence:
   - rule: annual_fee
     url: https://www.citi.com/credit-cards/citi-costco-anywhere-visa-credit-card
     quote: '$0 annual fee with active Costco membership.'
+  - rule: requires_membership
+    url: https://www.citi.com/credit-cards/citi-costco-anywhere-visa-credit-card
+    quote: 'No annual fee with paid Costco membership.'
+  - rule: requires_membership
+    url: https://www.costco.com/join-costco.html
+    quote: 'Gold Star $65/yr'

package/data/merchants/overrides.yaml

@@ -160,6 +160,14 @@
     may_code_as: [dining, entertainment]
     note: Restaurants inside a hotel may code as dining, or as lodging if charged to the room. Shows and casino charges code separately.
 
+- id: chipotle
+  name: Chipotle
+  aliases: [chipotle mexican grill]
+  category: dining
+  ambiguity:
+    may_code_as: [dining.fast_food]
+    note: Fast-casual chains can post as fast food (MCC 5814) instead of a restaurant (5812); a statement shows which.
+
 - id: comcast
   name: Comcast Xfinity
   aliases: [comcast, xfinity]

package/data/merchants/seed.yaml

@@ -45,12 +45,6 @@
   }
 
 # Restaurants and fast food
-- {
-    id: chipotle,
-    name: Chipotle,
-    aliases: [chipotle mexican grill],
-    category: dining,
-  }
 - { id: sweetgreen, name: Sweetgreen, category: dining }
 - {
     id: cheesecake-factory,

package/dist/cli/cheatsheet.js

@@ -15,7 +15,7 @@ name with --cards, or else from every card earnrate knows.
 
 Options:
   --cards <ids>          Use these cards instead of your wallet, comma separated.
-  --member <name>        A membership you have, like amazon-prime. Repeatable.
+  --member <name>        A membership you have, like amazon-prime or costco. Repeatable.
   --valuation <profile>  flat or points-heavy, instead of your wallet's values.
   --date <YYYY-MM-DD>    The day to check. Default: today.
   --json                 Print the cheat sheet as JSON.

package/dist/cli/explore.js

@@ -12,7 +12,7 @@ const FILTER_OPTIONS = `  --cash, --points        Cash back cards only, or point
   --issuer <id>           One issuer's cards, e.g. chase or amex.
   --business              Business cards instead of personal ones.
   --closed                Include cards the issuer no longer takes applications for.
-  --member <name>         A membership you have, e.g. amazon-prime. Repeatable.
+  --member <name>         A membership you have, e.g. amazon-prime or costco. Repeatable.
   --valuation <profile>   flat (points at 1¢, the default) or points-heavy
                           (MR and UR at 1.7¢).`;
 const BEST_HELP = `Usage: ${CLI_NAME} best <merchant or category> [amount] [options]

package/dist/cli/import.js

@@ -22,13 +22,14 @@ Reads card statements (Amex and Chase activity CSVs) and reports:
 
 Name several statements, each with its card, to see one report across them.
 
-Nothing is written unless you pass --apply, and then only cap totals plus a
-fingerprint of each recorded purchase, so importing twice never counts twice.
+Nothing is written unless you pass --apply, and then only cap totals,
+welcome-bonus spending and a fingerprint of each recorded purchase, so
+importing twice never counts twice.
 The statements themselves are never stored.
 
 Options:
   --card <id>            The card a statement is for, as in your wallet.
-  --apply                Record cap usage for the current period.
+  --apply                Record cap usage and welcome-bonus spending.
   --valuation <profile>  flat or points-heavy, instead of your wallet's values.
   -h, --help             Show this help.
 `;

package/dist/cli/run.js

@@ -42,7 +42,7 @@ Save your cards (optional):
   ${CLI_NAME} add <card-id> [--pick ...]           Add a card you hold.
   ${CLI_NAME} update <card-id> [--pick ...]        Change picks, label or activations.
   ${CLI_NAME} remove <card-id>                     Remove a card.
-  ${CLI_NAME} memberships [names...]               Show or set memberships (amazon-prime).
+  ${CLI_NAME} memberships [names...]               Show or set memberships (amazon-prime, costco).
 
 Other commands:
   ${CLI_NAME} cheatsheet                           The best card for each category this quarter.

package/dist/data/integrity.js

@@ -1,3 +1,4 @@
+import { WALLET_VERSION } from "../schema/wallet.js";
 function duplicates(ids) {
     const seen = new Set();
     const dupes = new Set();
@@ -56,6 +57,11 @@ function cardProblems(card, catalog, merchantIds) {
     if (!currencies.has(card.currency)) {
         problems.push(`${where}: unknown currency '${card.currency}'`);
     }
+    for (const id of card.welcome_offer?.not_with ?? [])
+        if (!cardIds.has(id))
+            problems.push(`${where} welcome_offer.not_with: unknown card '${id}'`);
+    for (const m of card.requires_membership?.members_shop_at ?? [])
+        checkMerchant(m, 'requires_membership');
     if (card.pools_into) {
         if (!currencies.has(card.pools_into.currency)) {
             problems.push(`${where} pools_into: unknown currency '${card.pools_into.currency}'`);
@@ -79,6 +85,8 @@ function cardProblems(card, catalog, merchantIds) {
         ...(card.annual_fee !== undefined ? ['annual_fee'] : []),
         ...(card.first_year_fee !== undefined ? ['first_year_fee'] : []),
         ...(card.welcome_offer ? ['welcome_offer'] : []),
+        ...(card.welcome_offer?.not_with ? ['not_with'] : []),
+        ...(card.requires_membership ? ['requires_membership'] : []),
         ...card.rules.map((r) => r.id),
     ]);
     const sourcePages = new Set(card.source_urls.map((u) => u.split('#')[0]));
@@ -188,6 +196,8 @@ export function walletProblems(wallet, catalog) {
     const problems = [];
     const cards = new Map(catalog.cards.map((c) => [c.id, c]));
     const currencies = new Map(catalog.currencies.map((c) => [c.id, c]));
+    if ((wallet.version ?? 1) > WALLET_VERSION)
+        problems.push(`wallet: saved by a newer earnrate (format ${String(wallet.version)}); update earnrate to read it`);
     for (const id of duplicates(wallet.cards.map((c) => c.id))) {
         problems.push(`wallet: card '${id}' is listed twice`);
     }

package/dist/data/wallet-edit.js

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import { isMap, isSeq, parseDocument, stringify } from 'yaml';
 import { applyBonusBooking, applyBooking, } from "../engine/record.js";
-import { WalletSchema } from "../schema/wallet.js";
+import { WALLET_VERSION, WalletSchema } from "../schema/wallet.js";
 const NEW_WALLET = `# Your earnrate wallet: the cards you hold, by id. Never card numbers.
 # Format: https://github.com/cwasley/earnrate#your-wallet
 
@@ -57,6 +57,12 @@ function fieldLines(field, f, indent) {
                 `${indent}  spent: ${String(b.spent)}\n`,
                 b.spend === undefined ? '' : `${indent}  spend: ${String(b.spend)}\n`,
                 b.by === undefined ? '' : `${indent}  by: ${scalar(b.by)}\n`,
+                b.points === undefined
+                    ? ''
+                    : `${indent}  points: ${String(b.points)}\n`,
+                b.dollars === undefined
+                    ? ''
+                    : `${indent}  dollars: ${String(b.dollars)}\n`,
             ].join('');
         }
         case 'chosen': {
@@ -100,7 +106,7 @@ const column = (text, at) => at - lineStart(text, at);
 // Appends a card after the last one, matching the list's indentation.
 export function addCardText(text, entry) {
     if (text === null || text.trim() === '') {
-        return `${NEW_WALLET}cards:\n${cardLines(entry, '  ')}`;
+        return `${NEW_WALLET}version: ${String(WALLET_VERSION)}\ncards:\n${cardLines(entry, '  ')}`;
     }
     const { cards } = cardsSeq(text);
     const first = cards.items[0];

package/dist/engine/cheat-sheet.js

@@ -1,8 +1,10 @@
 import { resolveMerchantById } from "../merchants/resolve.js";
 import { categoryResolution, exploreCards, } from "./explore.js";
+import { bonusStatus } from "./bonus.js";
 import { periodKey } from "./periods.js";
 import { recommend } from "./recommend.js";
 import { setupNotes } from "./setup.js";
+import { listed, money, shortDate } from "./text.js";
 const CHEAT_SHEET_ITEMS = [
     { label: 'Groceries', category: 'grocery.supermarket' },
     { label: 'Dining', category: 'dining' },
@@ -17,6 +19,7 @@ const CHEAT_SHEET_ITEMS = [
 // The best card in the wallet for each everyday kind of purchase on `date`,
 // with caps, picks and activations as the wallet has them.
 export function cheatSheet(catalog, wallet, date, items = CHEAT_SHEET_ITEMS) {
+    const ranked = [];
     const rows = items.map((item) => {
         const merchant = 'merchant' in item
             ? resolveMerchantById(catalog, item.merchant, null)
@@ -30,7 +33,10 @@ export function cheatSheet(catalog, wallet, date, items = CHEAT_SHEET_ITEMS) {
             date,
             country: 'US',
         }, merchant);
-        const top = rec.ranked.find((r) => r.cardId === rec.decision?.cardId);
+        // The card that earns the most, even when a welcome bonus would take the
+        // pick for one purchase: the sheet is for the whole quarter.
+        const top = rec.decision ? rec.ranked[0] : undefined;
+        ranked.push({ label: item.label, cards: rec.ranked });
         return {
             label: item.label,
             cardId: top?.cardId ?? null,
@@ -40,8 +46,44 @@ export function cheatSheet(catalog, wallet, date, items = CHEAT_SHEET_ITEMS) {
             note: top?.warnings[0] ?? null,
         };
     });
+    const bonuses = wallet.cards.flatMap((held) => {
+        const status = bonusStatus(catalog, wallet, held, date);
+        if (status?.state !== 'open')
+            return [];
+        const name = held.checkout_label ??
+            catalog.cards.find((c) => c.id === held.id)?.name ??
+            held.id;
+        // Rows where the bonus card matches the row's card, or comes within a
+        // point and three quarters of its rate (as single answers mention it).
+        const matches = [];
+        const near = [];
+        for (const { label, cards } of ranked) {
+            const best = cards[0]?.effectiveReturnPct;
+            const own = cards.find((c) => c.cardId === held.id)?.effectiveReturnPct;
+            if (best === undefined || own === undefined)
+                continue;
+            if (best - own < 1e-9)
+                matches.push(label.toLowerCase());
+            else if (best - own <= 1 && own >= best * 0.75)
+                near.push(label.toLowerCase());
+        }
+        const where = [
+            ...(matches.length > 0
+                ? [`matches the listed card on ${listed(matches)}`]
+                : []),
+            ...(near.length > 0 ? [`comes within a point on ${listed(near)}`] : []),
+        ];
+        return [
+            `Working on ${name}'s welcome bonus: ${money(status.remaining ?? 0)} more by ${shortDate(status.deadline ?? date)}. ${where.length > 0
+                ? `It ${where.join(' and ')}, so those are the places to use it.`
+                : 'It trails the listed cards everywhere, so use it on everyday spending only as needed to reach the bonus.'}`,
+        ];
+    });
     const notes = [
-        ...new Set(wallet.cards.flatMap((held) => setupNotes(catalog, wallet, held, date).map((n) => n.text))),
+        ...new Set([
+            ...bonuses,
+            ...wallet.cards.flatMap((held) => setupNotes(catalog, wallet, held, date).map((n) => n.text)),
+        ]),
     ];
     const [year, q] = (periodKey('quarter', date, null) ?? '').split('-');
     return {