earnrate 0.2.6 → 0.2.8

package/README.md

@@ -9,7 +9,7 @@ I wanted a ghost card: one card that always charges the best of my cards. The ca
 
 **earnrate is the best-card decision layer for people and AI agents.** Give it a merchant, and it tells you which card earns the most there, from your own cards or from every card it knows, and why. Save your cards and it tracks your caps and chosen categories. It's valuation-aware and transparent about its assumptions. It never sees a card number.
 
-- Runs on your machine, in your browser at [earnrate.dev](https://earnrate.dev), or in Claude as a connector at `https://mcp.earnrate.dev`, with nothing to install. No account and no affiliate links; the hosted server counts requests by tool name, nothing about what you ask. See the [privacy page](https://earnrate.dev/privacy).
+- Runs on your machine, in your browser at [earnrate.dev](https://earnrate.dev) (which you can add to your phone's Home Screen and use offline), or in Claude as a connector at `https://mcp.earnrate.dev`, with nothing to install. No account and no affiliate links; the hosted server counts requests by tool name, nothing about what you ask. See the [privacy page](https://earnrate.dev/privacy).
 - U.S. cards and U.S. merchants, for now.
 
 > **Status:** early, and it works: the engine, CLI, optional Claude merchant lookup, MCP server and the hosted Claude connector. See [the benchmark](docs/benchmark.md) (run 2026-10-24) for how it compares to an existing card-picking MCP server.
@@ -43,11 +43,11 @@ 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. ...
+     6% cash back on supermarkets. ...
   2. Prime Visa           5%  $4.00
-     5% cash back from its "whole-foods" rule. Online or in-store.
+     5% cash back on Whole Foods Market, with Amazon Prime. ...
   3. Amex Gold            4%  $3.20
-     4x Amex Membership Rewards from its "us-supermarkets" rule. ...
+     4x Amex Membership Rewards on supermarkets. ...
      Valued at 1¢ per point: 4% back.
   + 6 more cards (--all lists them)
 
@@ -61,6 +61,10 @@ Options: `--online` or `--in-store`, `--valuation flat|points-heavy`, `--all`, `
 
 `earnrate cheatsheet` prints the card to use for each everyday kind of purchase this quarter (groceries, dining, gas, Amazon, Costco, travel, streaming, drugstores, everything else), with your caps, picks and activations as they are now. `--cards` uses cards you name instead, and `--every-card` picks from every card to show what's worth getting. It's also in the My wallet tab on [earnrate.dev](https://earnrate.dev).
 
+`earnrate todo` lists what your saved cards need this quarter, soonest first: bonuses to activate (with Chase's deadline), categories to pick, caps running low and welcome bonuses to finish. `--ics earnrate.ics` also writes the dates as a calendar file with reminders. My wallet on earnrate.dev shows the same list as "To do now", with an "Add the dates to your calendar" button.
+
+`earnrate missed` lists the stores earnrate didn't recognize when you asked here, most asked about first. They're kept only on your computer; [open an issue](https://github.com/cwasley/earnrate/issues) to suggest one for the data.
+
 ### Your wallet
 
 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`, `memberships` and `values` write it for you and keep your comments, or you can edit it by hand. Only the cards are required:
@@ -184,7 +188,7 @@ Use the connector (or plugin) or the local extension, not both: each keeps its o
 - `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
 - `resolve_merchant`: how a merchant was identified
-- `list_wallet`: your cards, caps left this period, chosen categories, welcome-bonus progress and the point values you've set
+- `list_wallet`: a to-do list for your cards right now, then your cards, caps left this period, chosen categories, welcome-bonus progress and the point values you've set
 - `cheat_sheet`: the card to use for each everyday kind of purchase this quarter
 - `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
@@ -228,7 +232,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. 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.
+- **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. An hourly check confirms earnrate.dev and the hosted server are up, and a daily one checks them end to end (a browser load of the site, sign in, ask, save a card, delete the wallet, and the server's error counts), opening 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.
@@ -249,7 +253,7 @@ Rotating categories (Freedom Flex) are added each quarter once the issuer posts
 earnrate needs no account. The local version has no telemetry; the hosted server counts requests and errors by method, tool name or page only, never what was asked. 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 and errors by method, tool name or page only. Connecting it starts an anonymous wallet (a recovery code, no email). It holds only what you save: card IDs and the details you gave, memberships and point values, 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 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. When you ask about a store earnrate doesn't recognize, its name goes in `~/.earnrate/missed-merchants.json` (`earnrate missed` lists them; `EARNRATE_MISSED_MERCHANTS=off` keeps no list).
 - **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.

package/data/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 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.02.5
+
+Prime Visa's 3% without-Prime rate no longer applies at Whole Foods stores outside the U.S. Chase's terms exclude "purchases made at international Whole Foods Markets" from both the 5% and the 3% rate; only the 5% rule was U.S.-only.
+
+| Card             | Field                     | Old → new                                                              | Source                                                                                             |
+| ---------------- | ------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| chase-prime-visa | amazon-without-prime      | Whole Foods moved to its own rule                                      | [Chase Prime Visa page](https://creditcards.chase.com/cash-back-credit-cards/amazon-prime-rewards) |
+| chase-prime-visa | whole-foods-without-prime | new rule: 3% at Whole Foods without Prime, U.S. only (abroad: 3% → 1%) | [Chase Prime Visa page](https://creditcards.chase.com/cash-back-credit-cards/amazon-prime-rewards) |
+
+## 2026.11.02.4
+
+Customized Cash's todo about purchases that cross the $2,500 quarterly cap is resolved: past the cap, a BofA Rewards tier's boosted base rate now applies. No rates changed.
+
+| Card                                    | Field | Old → new                     | Source |
+| --------------------------------------- | ----- | ----------------------------- | ------ |
+| bank-of-america-customized-cash-rewards | todo  | removed the cap-crossing note | n/a    |
+
+## 2026.11.02.3
+
+The engine now prices spending past a cap at the card's best uncapped rate for that purchase when it beats the cap's own rate, so Freedom Flex's todo about crossing its $1,500 quarterly cap is resolved. No rates changed.
+
+| Card               | Field | Old → new                     | Source                                                                                 |
+| ------------------ | ----- | ----------------------------- | -------------------------------------------------------------------------------------- |
+| chase-freedom-flex | todo  | removed the cap-crossing note | [Freedom Flex FAQ](https://www.chase.com/personal/credit-cards/freedom/flex-learnmore) |
+
 ## 2026.11.02.2
 
 Rules can carry `activate_by`, the issuer's activation deadline, so answers mention it only while a bonus isn't activated. No rates changed.

package/data/VERSION

@@ -1 +1 @@
-2026.11.02.2
+2026.11.02.5

package/data/cards/bank-of-america-customized-cash-rewards.yaml

@@ -212,5 +212,4 @@ evidence:
 todo:
   - New accounts earn 6% in the choice category for the first year (an extra 3%, inside the same $2,500 quarterly cap, with no BofA Rewards bonus on the extra 3%). earnrate can't see when an account was opened, so this isn't modeled.
   - 'The BofA Rewards rules use proposed membership ids: bofa-rewards-member, bofa-rewards-preferred-plus, bofa-rewards-preferred-honors and bofa-rewards-premier. Cardholders who joined Preferred Rewards before May 26, 2026 may have an "extended card benefit" that Bank of America doesn''t define.'
-  - With a BofA Rewards tier, a purchase that crosses the $2,500 cap counts the part past the cap at 1% instead of the tier's boosted base rate, so it's slightly understated.
   - "Online shopping counts any online purchase earnrate can't place in an excluded category, including unknown merchants. Bank of America also excludes doctors, government, insurance, schools and other non-retail services, which earnrate can't tell apart."

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

@@ -187,5 +187,4 @@ evidence:
     url: https://creditcards.chase.com/cash-back-credit-cards/freedom/flex
     quote: 'Earn a $250 bonus after you spend $500 on purchases in the first 3 months from account opening'
 todo:
-  - 'q4-2026-dining: a single dining purchase that crosses the $1,500 cap counts the part over the cap at 1%, not the everyday 3%; whole purchases after the cap correctly fall back to the 3% dining rule.'
   - 'Q2 2027 (Apr-Jun) shows "Coming Soon"; add it after Chase posts it (activation opens March 15, 2027).'

package/data/cards/chase-prime-visa.yaml

@@ -38,9 +38,14 @@ rules:
     rate: 5
     requires: { membership: amazon-prime }
   - id: amazon-without-prime
-    match: { merchants: [amazon, amazon-fresh, whole-foods, audible] }
+    match: { merchants: [amazon, amazon-fresh, audible] }
     rate: 3
     note: Without an eligible Prime membership these earn 3% instead of 5%.
+  - id: whole-foods-without-prime
+    match: { merchants: [whole-foods] }
+    rate: 3
+    geography: us_only
+    note: Without an eligible Prime membership, Whole Foods earns 3% instead of 5%, in the U.S. only.
   - id: chase-travel
     match: { merchants: [chase-travel] }
     rate: 5
@@ -93,6 +98,12 @@ evidence:
   - rule: amazon-without-prime
     url: https://creditcards.chase.com/cash-back-credit-cards/amazon-prime-rewards
     quote: '3% back without an eligible Prime membership for each $1 of eligible purchases'
+  - rule: whole-foods-without-prime
+    url: https://creditcards.chase.com/cash-back-credit-cards/amazon-prime-rewards
+    quote: '3% back without an eligible Prime membership for each $1 of eligible purchases'
+  - rule: whole-foods-without-prime
+    url: https://creditcards.chase.com/cash-back-credit-cards/amazon-prime-rewards
+    quote: 'purchases made at international Whole Foods Markets'
   - rule: chase-travel
     url: https://creditcards.chase.com/cash-back-credit-cards/amazon-prime-rewards
     quote: '5% back or 3% back through Chase Travel'

package/dist/brand.js

@@ -5,6 +5,7 @@ export const MCP_SERVER_NAME = 'earnrate';
 export const CONFIG_DIR = '.earnrate'; // under the home directory
 export const WALLET_ENV_VAR = 'EARNRATE_WALLET';
 export const MERCHANT_CACHE_ENV_VAR = 'EARNRATE_MERCHANT_CACHE';
+export const MISSED_ENV_VAR = 'EARNRATE_MISSED_MERCHANTS';
 export const LLM_ENV_VAR = 'EARNRATE_LLM';
 export const LLM_MODEL_ENV_VAR = 'EARNRATE_LLM_MODEL';
 export const LLM_MAX_CALLS_ENV_VAR = 'EARNRATE_LLM_MAX_CALLS';

package/dist/cli/import.js

@@ -1,5 +1,6 @@
 import { createHash } from 'node:crypto';
-import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { readFile } from 'node:fs/promises';
+import { writeFileAtomic } from "../data/atomic-write.js";
 import path from 'node:path';
 import { parseArgs } from 'node:util';
 import { z } from 'zod';
@@ -247,10 +248,7 @@ export async function runImport(argv, io) {
         recorded.add(fingerprint(entry));
     for (const entry of bonusEntries)
         recorded.add(fingerprint(entry, 'bonus'));
-    await mkdir(path.dirname(ledgerFile), { recursive: true });
-    const tmp = `${ledgerFile}.${String(process.pid)}.tmp`;
-    await writeFile(tmp, `${JSON.stringify({ version: 1, recorded: [...recorded] }, null, 2)}\n`);
-    await rename(tmp, ledgerFile);
+    await writeFileAtomic(ledgerFile, `${JSON.stringify({ version: 1, recorded: [...recorded] }, null, 2)}\n`);
     io.stdout(`Recorded ${toRecord.join(' and ')} in ${displayPath(walletFile)}.\n`);
     return 0;
 }

package/dist/cli/missed.js

@@ -0,0 +1,65 @@
+import { rm } from 'node:fs/promises';
+import { parseArgs } from 'node:util';
+import { CLI_NAME, MISSED_ENV_VAR } from "../brand.js";
+import { loadCatalog } from "../data/load.js";
+import { categoryPhrase, shortDate } from "../engine/text.js";
+import { missedPath, readMissed } from "../merchants/missed.js";
+import { displayPath, USAGE_ERROR } from "./run.js";
+const MISSED_HELP = `Usage: ${CLI_NAME} missed [--clear]
+
+Stores earnrate didn't recognize when you asked about them here (the command
+line or the local MCP server), most asked about first. They're kept only on
+this computer. To suggest one for earnrate's data, open an issue at
+https://github.com/cwasley/earnrate/issues.
+
+Set ${MISSED_ENV_VAR}=off to stop keeping the list, or to a path to keep it
+somewhere else.
+
+Options:
+  --clear      Delete the list.
+  -h, --help   Show this help.
+`;
+export async function runMissed(argv, io) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            options: {
+                clear: { type: 'boolean' },
+                help: { type: 'boolean', short: 'h' },
+            },
+        });
+    }
+    catch (e) {
+        io.stderr(`${e instanceof Error ? e.message : String(e)}\n${MISSED_HELP}`);
+        return USAGE_ERROR;
+    }
+    if (parsed.values.help) {
+        io.stdout(MISSED_HELP);
+        return 0;
+    }
+    const file = missedPath(io.env);
+    if (file === null) {
+        io.stdout(`The list is off (${MISSED_ENV_VAR}=off).\n`);
+        return 0;
+    }
+    if (parsed.values.clear) {
+        await rm(file, { force: true });
+        io.stdout(`Deleted ${displayPath(file)}.\n`);
+        return 0;
+    }
+    const missed = await readMissed(file);
+    if (missed.length === 0) {
+        io.stdout('No unrecognized stores yet.\n');
+        return 0;
+    }
+    const catalog = await loadCatalog();
+    const lines = missed
+        .sort((a, b) => b.count - a.count || b.last_seen.localeCompare(a.last_seen))
+        .map((m) => {
+        const kinds = m.categories.map((c) => categoryPhrase(catalog, c));
+        return `- ${m.name}: ${String(m.count)} ${m.count === 1 ? 'time' : 'times'}, last ${shortDate(m.last_seen)}${kinds.length === 0 ? '' : ` (taken as ${kinds.join(', ')})`}`;
+    });
+    io.stdout(`${lines.join('\n')}\n\nKept in ${displayPath(file)}. Suggest additions at https://github.com/cwasley/earnrate/issues.\n`);
+    return 0;
+}

package/dist/cli/run.js

@@ -14,10 +14,13 @@ import { formatRecommendation, plain, } from "../format/recommendation.js";
 import { DEFAULT_LLM_MODEL } from "../merchants/anthropic.js";
 import { DEFAULT_MAX_CALLS } from "../merchants/fallback.js";
 import { llmEnabled, openLlmSession } from "../merchants/from-env.js";
+import { missedPath, missLogAt } from "../merchants/missed.js";
 import { resolvePlace, withCallerCategory } from "../merchants/resolve.js";
 import { packageVersion } from "../version.js";
 import { membershipProblem, parseCliArgs } from "./args.js";
 import { runCheatSheet } from "./cheatsheet.js";
+import { runMissed } from "./missed.js";
+import { runTodo } from "./todo.js";
 import { runBest, runSimulate } from "./explore.js";
 import { runImport } from "./import.js";
 import { runOffers } from "./offers.js";
@@ -47,6 +50,8 @@ Save your cards (optional):
 
 Other commands:
   ${CLI_NAME} cheatsheet                           The best card for each category this quarter.
+  ${CLI_NAME} todo [--ics file]                    What your cards need this quarter, with dates.
+  ${CLI_NAME} missed                               Stores earnrate didn't recognize, kept on this computer.
   ${CLI_NAME} import <statement.csv> --card <id>   Replay a statement against your wallet.
   ${CLI_NAME} offers [--cash | --points]           Rank welcome offers on cards you don't have.
   ${CLI_NAME} mcp                                  Run the MCP server over stdio, for AI assistants.
@@ -160,6 +165,10 @@ export async function run(argv, io) {
         return runBest(argv.slice(1), io);
     if (argv[0] === 'cheatsheet')
         return runCheatSheet(argv.slice(1), io);
+    if (argv[0] === 'todo')
+        return runTodo(argv.slice(1), io);
+    if (argv[0] === 'missed')
+        return runMissed(argv.slice(1), io);
     if (argv[0] === 'simulate')
         return runSimulate(argv.slice(1), io);
     const command = argv[0];
@@ -214,6 +223,12 @@ export async function run(argv, io) {
         merchant = resolved.merchant;
         notices.push(...resolved.notices);
     }
+    const missedFile = missedPath(io.env);
+    if (missedFile !== null &&
+        (merchant.source === 'none' ||
+            merchant.source === 'caller' ||
+            merchant.source === 'llm'))
+        await missLogAt(missedFile).note(purchase.merchant, merchant.source === 'none' ? null : merchant.category, io.today);
     if (loaded === 'none') {
         const saved = await savedSettings(io);
         const explored = exploreCards(catalog, {

package/dist/cli/todo.js

@@ -0,0 +1,62 @@
+import { writeFile } from 'node:fs/promises';
+import { parseArgs } from 'node:util';
+import { CLI_NAME } from "../brand.js";
+import { loadCatalog, walletPath } from "../data/load.js";
+import { checklist, checklistCalendar } from "../engine/checklist.js";
+import { cardText } from "../format/card-text.js";
+import { dateProblem } from "./args.js";
+import { displayPath, readWallet, RUNTIME_ERROR, USAGE_ERROR, } from "./run.js";
+const TODO_HELP = `Usage: ${CLI_NAME} todo [--ics <file>] [--date <YYYY-MM-DD>]
+
+What your saved cards need this period, soonest first: bonuses to activate,
+categories to pick, spending caps running low, welcome bonuses to finish, and
+rotating categories the issuer hasn't posted yet.
+
+Options:
+  --ics <file>          Also write the dated items as a calendar file to import
+                        into your calendar app, with reminders two days before.
+  --date <YYYY-MM-DD>   The day to check. Default: today.
+  -h, --help            Show this help.
+`;
+export async function runTodo(argv, io) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            options: {
+                ics: { type: 'string' },
+                date: { type: 'string' },
+                help: { type: 'boolean', short: 'h' },
+            },
+        });
+    }
+    catch (e) {
+        io.stderr(`${e instanceof Error ? e.message : String(e)}\n${TODO_HELP}`);
+        return USAGE_ERROR;
+    }
+    const { values } = parsed;
+    if (values.help) {
+        io.stdout(TODO_HELP);
+        return 0;
+    }
+    const problem = dateProblem(values.date);
+    if (problem !== null) {
+        io.stderr(`${problem}\n`);
+        return USAGE_ERROR;
+    }
+    const catalog = await loadCatalog();
+    const wallet = await readWallet(walletPath(io.env), io);
+    if (wallet === null)
+        return RUNTIME_ERROR;
+    const today = values.date ?? io.today;
+    const items = checklist(catalog, wallet, today, undefined, cardText(catalog).shortName);
+    io.stdout(items.length === 0
+        ? 'Nothing to do: every bonus is activated, every pick is made, and no cap or welcome bonus needs attention.\n'
+        : `${items.map((i) => `- ${i.text}`).join('\n')}\n`);
+    if (values.ics !== undefined) {
+        const stamp = `${new Date().toISOString().replace(/[-:]/g, '').slice(0, 15)}Z`;
+        await writeFile(values.ics, checklistCalendar(items, stamp));
+        io.stdout(`Wrote ${displayPath(values.ics)}; open it to add the dates to your calendar.\n`);
+    }
+    return 0;
+}

package/dist/cli/wallet.js

@@ -208,7 +208,7 @@ export async function runWalletCommand(command, argv, io) {
     if (command === 'memberships') {
         if (positionals.length === 0 && !values.none) {
             const held = await heldWallet(io);
-            io.stdout(`Yours: ${held && held.memberships.length > 0 ? held.memberships.join(', ') : 'none'}\nKnown: ${knownMemberships(catalog).join(', ')}\n`);
+            io.stdout(`Yours: ${held && held.memberships.length > 0 ? held.memberships.map((m) => `${membershipName(catalog, m)} (${m})`).join(', ') : 'none'}\nKnown: ${knownMemberships(catalog).join(', ')}\n`);
             return 0;
         }
         if (positionals.length > 0 && values.none) {

package/dist/data/atomic-write.js

@@ -0,0 +1,13 @@
+import { chmod, mkdir, realpath, rename, stat, writeFile, } from 'node:fs/promises';
+import path from 'node:path';
+// Writes through a symlink rather than replacing it, and keeps the file's
+// mode: a user's chmod 600 must survive every edit.
+export async function writeFileAtomic(file, text) {
+    const target = await realpath(file).catch(() => file);
+    const mode = await stat(target).then((s) => s.mode & 0o777, () => 0o600);
+    await mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
+    const tmp = `${target}.${String(process.pid)}.tmp`;
+    await writeFile(tmp, text, { mode });
+    await chmod(tmp, mode); // writeFile's mode is narrowed by the umask
+    await rename(tmp, target);
+}

package/dist/data/store.js

@@ -1,5 +1,6 @@
 import { bookPurchase } from "../engine/record.js";
 import { addToWallet, removeFromWallet, updateInWallet, withMemberships, withValuations, } from "../engine/wallet-change.js";
+import { withoutCardNumbers } from "../schema/card-number.js";
 import { WALLET_VERSION, WalletSchema } from "../schema/wallet.js";
 const failed = (error) => ({ ok: false, error });
 // Memberships and point values can be saved before any card.
@@ -19,7 +20,9 @@ export class JsonWalletStore {
     }
     async load() {
         const text = await this.backend.read();
-        return text === null ? null : WalletSchema.parse(JSON.parse(text));
+        return text === null
+            ? null
+            : WalletSchema.parse(withoutCardNumbers(JSON.parse(text)));
     }
     serialized(task) {
         const run = this.queue.then(task, task);

package/dist/data/wallet-edit.js

@@ -1,5 +1,5 @@
-import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
-import path from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { writeFileAtomic } from "./atomic-write.js";
 import { isDeepStrictEqual } from 'node:util';
 import { isMap, isSeq, parseDocument, stringify } from 'yaml';
 import { applyBonusBooking, applyBooking, } from "../engine/record.js";
@@ -359,8 +359,5 @@ export async function commitWalletText(file, after, expected, fallback = BY_HAND
     if (!parsed.success || !isDeepStrictEqual(parsed.data, expected)) {
         throw new Error(`couldn't update ${file} safely; ${fallback}`);
     }
-    await mkdir(path.dirname(file), { recursive: true });
-    const tmp = `${file}.${String(process.pid)}.tmp`;
-    await writeFile(tmp, after);
-    await rename(tmp, file);
+    await writeFileAtomic(file, after);
 }

package/dist/engine/cheat-sheet.js

@@ -4,6 +4,7 @@ import { bonusStatus } from "./bonus.js";
 import { EPSILON, isClose } from "./compare.js";
 import { periodKey } from "./periods.js";
 import { recommend } from "./recommend.js";
+import { checklist } from "./checklist.js";
 import { setupNotes } from "./setup.js";
 import { capitalize, feeText, listed, money, shortDate } from "./text.js";
 // The everyday kinds of purchase: the cheat sheet's rows and the site's
@@ -82,10 +83,18 @@ export function cheatSheet(catalog, wallet, date, items = EVERYDAY_PURCHASES) {
                 : 'It trails the listed cards everywhere, so use it on everyday spending only as needed to reach the bonus.'}`,
         ];
     });
+    // Picks and activations in plain words, as the to-do list says them; the
+    // setup notes name ids for an agent to set.
+    const todo = checklist(catalog, wallet, date).filter((i) => i.kind === 'pick' || i.kind === 'activate');
     const notes = [
         ...new Set([
             ...bonuses,
-            ...wallet.cards.flatMap((held) => setupNotes(catalog, wallet, held, date).map((n) => n.text)),
+            ...todo.map((i) => i.text),
+            ...wallet.cards.flatMap((held) => setupNotes(catalog, wallet, held, date)
+                .filter((n) => n.kind !== 'pick' && n.kind !== 'activation')
+                .map((n) => n.kind === 'membership'
+                ? n.text.replace(/ \([a-z0-9-]+\)/g, '')
+                : n.text)),
         ]),
     ];
     const [year, q] = (periodKey('quarter', date, null) ?? '').split('-');

package/dist/engine/checklist.js

@@ -0,0 +1,152 @@
+import { daysBetween, periodEnd, periodKey } from "./periods.js";
+import { CAP_PERIODS, choiceName, listed, money, shortDate, wholeDollars, } from "./text.js";
+import { optionName } from "./rule-text.js";
+import { activationsDue, walletSummary, } from "./wallet-summary.js";
+// What the wallet's cards need this period, soonest first: bonuses to
+// activate, categories to pick, caps running low, welcome bonuses to finish,
+// and rotating categories the issuer hasn't posted yet.
+export function checklist(catalog, wallet, today, summary = walletSummary(catalog, wallet, today), 
+// A shorter card name than the issuer's full one, where the caller has it.
+shortName) {
+    const items = [];
+    for (const held of wallet.cards) {
+        const card = catalog.cards.find((c) => c.id === held.id);
+        const s = summary.cards.find((c) => c.cardId === held.id);
+        if (!card || !s)
+            continue;
+        const name = s.checkoutLabel ?? shortName?.(card.id) ?? s.cardName;
+        for (const a of activationsDue(catalog, card, held, today)) {
+            const starts = a.from !== null && a.from > today
+                ? `, starting ${shortDate(a.from)}`
+                : '';
+            items.push({
+                kind: 'activate',
+                cardId: card.id,
+                text: `Activate ${name}'s bonus on ${a.what}${starts}${a.activateBy === null ? '' : `, by ${shortDate(a.activateBy)}`}.`,
+                due: a.activateBy ?? (a.from !== null && a.from > today ? a.from : a.to),
+            });
+        }
+        const picked = (id) => s.chosen?.picks[id] !== undefined;
+        const current = s.chosen?.current === true;
+        const unpicked = card.choices.filter((c) => !c.default &&
+            !(current && picked(c.id)) &&
+            c.period !== 'until_changed');
+        const [first] = unpicked;
+        if (first) {
+            const period = first.period === 'until_changed'
+                ? null
+                : periodKey(first.period, today, null);
+            items.push({
+                kind: 'pick',
+                cardId: card.id,
+                text: `Pick ${name}'s ${listed(unpicked.map((c) => choiceName(c.id)))} categories for this ${first.period.replace('_', ' ')}; until then they earn the base rate.`,
+                due: period === null ? null : periodEnd(period),
+            });
+        }
+        else {
+            // Picks made for this period: near its end, a reminder to make the
+            // next period's (Cash+ asks each quarter).
+            const ending = card.choices.find((c) => c.period !== 'until_changed' && !c.default && current);
+            const period = ending === undefined || ending.period === 'until_changed'
+                ? null
+                : periodKey(ending.period, today, null);
+            const end = period === null ? null : periodEnd(period);
+            if (ending && end !== null && daysBetween(today, end) <= 14)
+                items.push({
+                    kind: 'pick',
+                    cardId: card.id,
+                    text: `Pick ${name}'s categories for next ${ending.period.replace('_', ' ')}; this one ends ${shortDate(end)}.`,
+                    due: end,
+                });
+        }
+        // A pick earnrate assumes because none was saved: worth confirming.
+        const assumed = card.choices.filter((c) => c.default && !picked(c.id));
+        if (assumed.length > 0)
+            items.push({
+                kind: 'pick',
+                cardId: card.id,
+                text: `${name}'s ${listed(assumed.map((c) => choiceName(c.id)))} pick is assumed to be ${listed(assumed.flatMap((c) => (c.default ?? []).map((o) => optionName(catalog, card, c.id, o))))}; set it if you picked something else.`,
+                due: null,
+            });
+        for (const cap of s.caps) {
+            // Only caps nearly used up: the rest aren't something to do.
+            if (cap.remaining === null || cap.remaining > cap.amount * 0.25)
+                continue;
+            const resets = cap.currentPeriod === null ? null : periodEnd(cap.currentPeriod);
+            items.push({
+                kind: 'cap',
+                cardId: card.id,
+                text: cap.remaining === 0
+                    ? `${name}'s ${cap.label} cap is used up${resets === null ? '' : ` until ${shortDate(resets)}`}; another card may earn more there.`
+                    : `${name}: ${money(cap.remaining)} left of ${money(cap.amount)} ${CAP_PERIODS[cap.period]} at the bonus rate on ${cap.label}.`,
+                due: resets,
+            });
+        }
+        const b = s.bonus;
+        if (b?.state === 'open' && b.remaining !== null && b.deadline !== null) {
+            const weeks = Math.max(1, (b.daysLeft ?? 7) / 7);
+            items.push({
+                kind: 'bonus',
+                cardId: card.id,
+                text: `${name}'s welcome bonus: ${money(b.remaining)} to go by ${shortDate(b.deadline)}, about ${wholeDollars(b.remaining / weeks)} a week.`,
+                due: b.deadline,
+            });
+        }
+        if (s.rotationGap !== null) {
+            items.push({
+                kind: 'rotation',
+                cardId: card.id,
+                text: `${name}'s ${s.rotationGap} categories aren't out yet; earnrate adds them once the issuer posts them.`,
+                due: null,
+            });
+        }
+    }
+    return items.sort((a, b) => (a.due ?? '9999').localeCompare(b.due ?? '9999') ||
+        a.cardId.localeCompare(b.cardId));
+}
+// An all-day calendar event for each dated action (activations, picks,
+// welcome-bonus deadlines), with a reminder two days before. Built on the
+// device: nothing is sent anywhere.
+export function checklistCalendar(items, stamp) {
+    const escape = (t) => t.replace(/\\/g, '\\\\').replace(/[,;]/g, (c) => `\\${c}`);
+    const fold = (line) => {
+        const parts = [];
+        for (let i = 0; i < line.length; i += 73)
+            parts.push(line.slice(i, i + 73));
+        return parts.join('\r\n ');
+    };
+    const day = (d) => d.replace(/-/g, '');
+    const next = (d) => {
+        const t = new Date(`${d}T00:00:00Z`);
+        t.setUTCDate(t.getUTCDate() + 1);
+        return t.toISOString().slice(0, 10);
+    };
+    const events = items
+        .filter((i) => i.due !== null && i.kind !== 'cap' && i.kind !== 'rotation')
+        .flatMap((i) => {
+        const due = i.due ?? '';
+        return [
+            'BEGIN:VEVENT',
+            `UID:${i.kind}-${i.cardId}-${due}@earnrate.dev`,
+            `DTSTAMP:${stamp}`,
+            `DTSTART;VALUE=DATE:${day(due)}`,
+            `DTEND;VALUE=DATE:${day(next(due))}`,
+            fold(`SUMMARY:${escape(i.text)}`),
+            'BEGIN:VALARM',
+            'TRIGGER:-P2D',
+            'ACTION:DISPLAY',
+            fold(`DESCRIPTION:${escape(i.text)}`),
+            'END:VALARM',
+            'END:VEVENT',
+        ];
+    });
+    return [
+        'BEGIN:VCALENDAR',
+        'VERSION:2.0',
+        'PRODID:-//earnrate//checklist//EN',
+        'CALSCALE:GREGORIAN',
+        ...events,
+        'END:VCALENDAR',
+        '',
+    ].join('\r\n');
+}