earnrate 0.2.5 → 0.2.7

package/dist/cli/run.js

@@ -5,7 +5,7 @@ import { fileURLToPath } from 'node:url';
 import { CLI_NAME, CONFIG_DIR, LLM_ENV_VAR, LLM_MAX_CALLS_ENV_VAR, LLM_MODEL_ENV_VAR, MERCHANT_CACHE_ENV_VAR, WALLET_ENV_VAR, } from "../brand.js";
 import { walletProblems } from "../data/integrity.js";
 import { loadCatalog, loadWallet, walletPath } from "../data/load.js";
-import { ALL_PERSONAL_CARDS, categoryResolution, exploreCards, findCategory, } from "../engine/explore.js";
+import { ALL_PERSONAL_CARDS, exploreCards } from "../engine/explore.js";
 import { profileText, VALUATION_PROFILES, withValuationProfile, } from "../engine/profiles.js";
 import { recommend } from "../engine/recommend.js";
 import { walletFromCards } from "../engine/transient.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 { resolveMerchant, withCallerCategory } from "../merchants/resolve.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.
@@ -63,7 +68,7 @@ Options:
   --country <code>       Where you're paying. Default: US.
   --cards <ids>          Answer for these cards instead of your wallet, comma
                          separated: --cards amex-gold,chase-prime-visa.
-  --member <name>        A membership you have, with --cards or no wallet.
+  --member <name>        A membership you have, in place of the saved ones.
   --category <id>        For a merchant earnrate doesn't know: its category,
                          e.g. grocery.supermarket. Ignored for known merchants.
   --llm, --no-llm        Ask Claude to classify merchants earnrate doesn't know.
@@ -87,7 +92,9 @@ export function displayPath(file) {
     return file.startsWith(`${home}/`) ? `~${file.slice(home.length)}` : file;
 }
 // The cards to answer for: those named with --cards, else the wallet file.
-// 'none' means no wallet and no --cards, which answers from every card.
+// 'none' means no cards saved or named, which answers from every card.
+// Named cards use the saved memberships (unless --member names some) and the
+// saved point values, as the MCP tools do.
 export async function cardsToUse(catalog, file, io, named) {
     const problem = membershipProblem(catalog, named.members);
     if (problem !== null) {
@@ -95,15 +102,16 @@ export async function cardsToUse(catalog, file, io, named) {
         return null;
     }
     if (named.cards !== null) {
+        const saved = await savedSettings(io);
         const wallet = walletFromCards(catalog, {
             cards: named.cards.map((id) => ({ id })),
-            memberships: named.members,
+            memberships: named.members.length > 0 ? named.members : saved.memberships,
         }, io.today);
         if (typeof wallet === 'string') {
             io.stderr(`${wallet}\n`);
             return null;
         }
-        return wallet;
+        return { ...wallet, valuations: saved.valuations };
     }
     try {
         await access(file);
@@ -119,7 +127,7 @@ export async function cardsToUse(catalog, file, io, named) {
         io.stderr(`Your wallet at ${displayPath(file)} has problems:\n${problems.map((p) => `  - ${p}\n`).join('')}`);
         return null;
     }
-    return loaded;
+    return loaded.cards.length === 0 ? 'none' : loaded;
 }
 export const NO_WALLET_HINT = `These are every card earnrate knows. For the best of your own cards, name them with --cards amex-gold,chase-prime-visa, or save them: ${CLI_NAME} add <card-id> (${CLI_NAME} cards finds ids).`;
 // The point values and memberships saved in the wallet, which every answer
@@ -157,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];
@@ -194,14 +206,7 @@ export async function run(argv, io) {
         io.stderr(`Unknown category "${options.category}". Use one of: ${catalog.categories.map((c) => c.id).join(', ')}.\n`);
         return USAGE_ERROR;
     }
-    // Plain category words ("restaurants", "groceries") work like stores.
-    const resolvedName = resolveMerchant(catalog, purchase.merchant, purchase.channel);
-    const named = resolvedName.source === 'none' && options.category === null
-        ? findCategory(catalog, purchase.merchant)
-        : null;
-    let merchant = named === null
-        ? withCallerCategory(resolvedName, options.category)
-        : categoryResolution(catalog, named, purchase.channel);
+    let merchant = withCallerCategory(resolvePlace(catalog, purchase.merchant, purchase.channel), options.category);
     const notices = [];
     if (llmOn && merchant.source === 'none') {
         const opened = await openLlmSession({
@@ -218,7 +223,14 @@ 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, {
             merchant: purchase.merchant,
             category: null,
@@ -227,10 +239,10 @@ export async function run(argv, io) {
             date: purchase.date,
         }, {
             filters: ALL_PERSONAL_CARDS,
-            memberships: options.members,
+            memberships: options.members.length > 0 ? options.members : saved.memberships,
             valuations: options.valuation
                 ? VALUATION_PROFILES[options.valuation]
-                : {},
+                : saved.valuations,
         }, merchant);
         if (options.json) {
             io.stdout(`${JSON.stringify(explored, null, 2)}\n`);

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

@@ -3,6 +3,7 @@ import { CLI_NAME } from "../brand.js";
 import { FileWalletStore } from "../data/file-store.js";
 import { loadCatalog, loadWallet, walletPath } from "../data/load.js";
 import { isValuationProfile, profileText, VALUATION_PROFILES, } from "../engine/profiles.js";
+import { membershipName } from "../engine/memberships.js";
 import { knownMemberships, searchCards } from "../engine/setup.js";
 import { formatCardInfo, formatNotes } from "../format/cards.js";
 import { displayPath, RUNTIME_ERROR, USAGE_ERROR } from "./run.js";
@@ -41,19 +42,21 @@ ${CARD_OPTIONS}
 `,
     update: `Usage: ${CLI_NAME} update <card-id> [options]
 
-Changes a card in your wallet: picks for this period, label, anniversary or
-activations. Picks for the current period are merged with ones already set.
+Changes a card in your wallet: picks for this period, label, anniversary,
+activations or welcome bonus. Picks for the current period are merged with
+ones already set.
 
 ${CARD_OPTIONS}
 `,
     remove: `Usage: ${CLI_NAME} remove <card-id>
 
-Removes a card from your wallet, with its tracked cap usage.
+Removes a card from your wallet, with its tracked cap usage and bonus
+progress. Your memberships and point values stay.
 `,
     memberships: `Usage: ${CLI_NAME} memberships [<membership>...] [--none]
 
 With no arguments, shows your memberships and the ones earnrate knows. With
-names, replaces the list. --none clears it.
+names, replaces the list. --none clears it. No cards need to be saved first.
 `,
     values: `Usage: ${CLI_NAME} values [<currency>=<cents>...] [--profile <name>]
 
@@ -205,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) {
@@ -213,7 +216,7 @@ export async function runWalletCommand(command, argv, io) {
         }
         const list = values.none ? [] : positionals;
         return report(await store.setMemberships(list), list.length > 0
-            ? `Memberships set to ${list.join(', ')} in ${where}.`
+            ? `Memberships set to ${list.map((m) => `${membershipName(catalog, m)} (${m})`).join(', ')} in ${where}.`
             : `Memberships cleared in ${where}.`, null, io);
     }
     if (positionals.length !== 1) {

package/dist/data/file-store.js

@@ -1,7 +1,8 @@
 import { bookPurchase } from "../engine/record.js";
 import { addToWallet, removeFromWallet, updateInWallet, withMemberships, withValuations, } from "../engine/wallet-change.js";
 import { loadWallet } from "./load.js";
-import { addCardText, commitWalletText, readWalletText, removeCardText, setMembershipsText, setValuationsText, updateCardText, writeProgress, } from "./wallet-edit.js";
+import { emptyWallet, } from "./store.js";
+import { addCardText, commitWalletText, EMPTY_WALLET_TEXT, readWalletText, removeCardText, setMembershipsText, setValuationsText, updateCardText, writeProgress, } from "./wallet-edit.js";
 const failed = (error) => ({ ok: false, error });
 const errorText = (e) => (e instanceof Error ? e.message : String(e));
 const queues = new Map();
@@ -56,7 +57,7 @@ export class FileWalletStore {
             }
         });
     }
-    // Changes other than adding a card need a wallet file to change.
+    // Changing or removing a card needs a wallet file to change.
     existing(apply) {
         return (wallet) => wallet === null
             ? `No wallet at ${this.where} yet. Add a card first to create it.`
@@ -69,15 +70,13 @@ export class FileWalletStore {
         return this.change(this.existing((w) => updateInWallet(this.catalog, w, input, today)), (text, change) => updateCardText(text ?? '', input.id, change.fields));
     }
     removeCard(cardId) {
-        return this.change(this.existing((w) => w.cards.length === 1 && w.cards[0]?.id === cardId
-            ? failed(`${cardId} is the last card in ${this.where}. To start over, delete that file; to swap cards, add the new one first.`)
-            : removeFromWallet(w, cardId)), (text) => removeCardText(text ?? '', cardId));
+        return this.change(this.existing((w) => removeFromWallet(w, cardId)), (text) => removeCardText(text ?? '', cardId));
     }
     setMemberships(memberships) {
-        return this.change(this.existing((w) => withMemberships(this.catalog, w, memberships)), (text, change) => setMembershipsText(text ?? '', change.wallet.memberships));
+        return this.change((w) => withMemberships(this.catalog, w ?? emptyWallet(), memberships), (text, change) => setMembershipsText(text ?? EMPTY_WALLET_TEXT, change.wallet.memberships));
     }
     setValuations(changes) {
-        return this.change(this.existing((w) => withValuations(this.catalog, w, changes)), (text) => setValuationsText(text ?? '', changes));
+        return this.change((w) => withValuations(this.catalog, w ?? emptyWallet(), changes), (text) => setValuationsText(text ?? EMPTY_WALLET_TEXT, changes));
     }
     record(purchase, merchant) {
         return withWalletLock(this.where, async () => {

package/dist/data/integrity.js

@@ -179,6 +179,7 @@ export function catalogProblems(catalog) {
         ['currency', catalog.currencies.map((c) => c.id)],
         ['card', catalog.cards.map((c) => c.id)],
         ['membership', catalog.memberships.map((m) => m.id)],
+        ['issuer', catalog.issuers.map((i) => i.id)],
     ]) {
         for (const id of duplicates(ids))
             problems.push(`duplicate ${kind} id '${id}'`);
@@ -203,8 +204,11 @@ export function catalogProblems(catalog) {
         for (const id of m.members_shop_at)
             if (!merchantIds.has(id))
                 problems.push(`membership ${m.id}: members_shop_at '${id}' is not a merchant`);
+    const issuers = new Set(catalog.issuers.map((i) => i.id));
     for (const card of catalog.cards) {
         problems.push(...cardProblems(card, catalog, merchantIds));
+        if (!issuers.has(card.issuer))
+            problems.push(`${card.id}: unknown issuer '${card.issuer}' (data/issuers.yaml)`);
     }
     return problems;
 }

package/dist/data/load.js

@@ -8,6 +8,7 @@ import { CONFIG_DIR, WALLET_ENV_VAR } from "../brand.js";
 import { CardSchema } from "../schema/card.js";
 import { CategoriesFileSchema } from "../schema/category.js";
 import { CurrenciesFileSchema } from "../schema/currency.js";
+import { IssuersFileSchema } from "../schema/issuer.js";
 import { MembershipsFileSchema } from "../schema/membership.js";
 import { MerchantsFileSchema } from "../schema/merchant.js";
 import { WalletSchema } from "../schema/wallet.js";
@@ -31,9 +32,10 @@ async function loadCards(dir) {
     }));
 }
 export async function loadCatalog(dir = DATA_DIR) {
-    const [categories, currencies, memberships, cards, seed, overrides] = await Promise.all([
+    const [categories, currencies, issuers, memberships, cards, seed, overrides] = await Promise.all([
         readYaml(path.join(dir, 'categories.yaml'), CategoriesFileSchema),
         readYaml(path.join(dir, 'currencies.yaml'), CurrenciesFileSchema),
+        readYaml(path.join(dir, 'issuers.yaml'), IssuersFileSchema),
         readYaml(path.join(dir, 'memberships.yaml'), MembershipsFileSchema),
         loadCards(path.join(dir, 'cards')),
         readYaml(path.join(dir, 'merchants', 'seed.yaml'), MerchantsFileSchema),
@@ -42,6 +44,7 @@ export async function loadCatalog(dir = DATA_DIR) {
     return {
         categories,
         currencies,
+        issuers,
         memberships,
         cards,
         merchants: { seed, overrides },

package/dist/data/store.js

@@ -1,7 +1,9 @@
 import { bookPurchase } from "../engine/record.js";
 import { addToWallet, removeFromWallet, updateInWallet, withMemberships, withValuations, } from "../engine/wallet-change.js";
-import { WalletSchema } from "../schema/wallet.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.
+export const emptyWallet = () => WalletSchema.parse({ version: WALLET_VERSION });
 // A wallet stored as JSON text. Writes are serialized within this instance;
 // a backend shared across processes must serialize them itself (one Durable
 // Object per wallet does).
@@ -30,11 +32,7 @@ export class JsonWalletStore {
             const change = apply(before);
             if (!change.ok)
                 return failed(change.error);
-            // An empty wallet is stored as none: the schema needs a card.
-            if (change.wallet.cards.length === 0)
-                await this.backend.remove();
-            else
-                await this.backend.write(JSON.stringify(change.wallet));
+            await this.backend.write(JSON.stringify(change.wallet));
             return {
                 ok: true,
                 wallet: change.wallet,
@@ -58,10 +56,10 @@ export class JsonWalletStore {
         return this.change(this.needsWallet((w) => removeFromWallet(w, cardId)));
     }
     setMemberships(memberships) {
-        return this.change(this.needsWallet((w) => withMemberships(this.catalog, w, memberships)));
+        return this.change((w) => withMemberships(this.catalog, w ?? emptyWallet(), memberships));
     }
     setValuations(changes) {
-        return this.change(this.needsWallet((w) => withValuations(this.catalog, w, changes)));
+        return this.change((w) => withValuations(this.catalog, w ?? emptyWallet(), changes));
     }
     replace(wallet) {
         return this.change(() => ({ ok: true, wallet, fields: {}, notes: [] }));
@@ -91,17 +89,3 @@ export class JsonWalletStore {
         });
     }
 }
-export function memoryBackend(initial = null) {
-    let text = initial;
-    return {
-        read: () => Promise.resolve(text),
-        write: (next) => {
-            text = next;
-            return Promise.resolve();
-        },
-        remove: () => {
-            text = null;
-            return Promise.resolve();
-        },
-    };
-}

package/dist/data/wallet-edit.js

@@ -93,6 +93,17 @@ function cardsSeq(text) {
     }
     return { doc, cards };
 }
+function rootMap(text) {
+    const doc = parseDocument(text);
+    if (doc.errors.length > 0)
+        throw new Error(doc.errors[0]?.message);
+    const root = doc.contents;
+    if (!isMap(root))
+        throw new Error(`the wallet isn't a map; ${BY_HAND}`);
+    return root;
+}
+// A wallet with no cards yet, for memberships or point values saved first.
+export const EMPTY_WALLET_TEXT = `${NEW_WALLET}version: ${String(WALLET_VERSION)}\ncards: []\n`;
 function findCard(text, cardId) {
     const { cards } = cardsSeq(text);
     const card = cards.items.find((item) => isMap(item) && item.get('id') === cardId);
@@ -108,6 +119,17 @@ export function addCardText(text, entry) {
     if (text === null || text.trim() === '') {
         return `${NEW_WALLET}version: ${String(WALLET_VERSION)}\ncards:\n${cardLines(entry, '  ')}`;
     }
+    const pair = rootMap(text).items.find((p) => keyOf(p) === 'cards');
+    const value = pair?.value;
+    const none = value === null || (isSeq(value) && value.items.length === 0);
+    if (!pair || none) {
+        const block = `cards:\n${cardLines(entry, '  ')}`;
+        if (!pair)
+            return insertLines(text, text.length, block);
+        const start = lineStart(text, range(pair.key)[0]);
+        const end = afterLine(text, range(value ?? pair.key)[1] - 1);
+        return text.slice(0, start) + block + text.slice(end);
+    }
     const { cards } = cardsSeq(text);
     const first = cards.items[0];
     if (!isMap(first))
@@ -125,8 +147,13 @@ function cardLines(entry, dashIndent) {
 }
 export function removeCardText(text, cardId) {
     const card = findCard(text, cardId);
-    const start = lineStart(text, range(card)[0]);
     const end = afterLine(text, range(card)[1] - 1);
+    if (cardsSeq(text).cards.items.length === 1) {
+        const pair = rootMap(text).items.find((p) => keyOf(p) === 'cards');
+        const start = lineStart(text, range(pair?.key)[0]);
+        return `${text.slice(0, start)}cards: []\n${text.slice(end)}`;
+    }
+    const start = lineStart(text, range(card)[0]);
     return text.slice(0, start) + text.slice(end);
 }
 // Replaces each given field in place, or adds it after the card's last line.
@@ -156,10 +183,7 @@ export function updateCardText(text, cardId, fields) {
     return out;
 }
 export function setMembershipsText(text, memberships) {
-    const { doc } = cardsSeq(text);
-    const root = doc.contents;
-    if (!isMap(root))
-        throw new Error(`the wallet isn't a map; ${BY_HAND}`);
+    const root = rootMap(text);
     const line = `memberships: ${flowList(memberships)}\n`;
     const pair = root.items.find((p) => keyOf(p) === 'memberships');
     if (pair) {
@@ -168,7 +192,9 @@ export function setMembershipsText(text, memberships) {
         return text.slice(0, start) + line + text.slice(end);
     }
     const cards = root.items.find((p) => keyOf(p) === 'cards');
-    return insertLines(text, lineStart(text, range(cards?.key)[0]), line);
+    return cards
+        ? insertLines(text, lineStart(text, range(cards.key)[0]), line)
+        : insertLines(text, text.length, line);
 }
 // Point values, one currency at a time so the rest of the file, comments
 // included, stays as it was: a value is replaced in place, a new one goes
@@ -192,10 +218,7 @@ function aboveComments(text, at) {
     return start;
 }
 function setValuationText(text, id, cents) {
-    const { doc } = cardsSeq(text);
-    const root = doc.contents;
-    if (!isMap(root))
-        throw new Error(`the wallet isn't a map; ${BY_HAND}`);
+    const root = rootMap(text);
     const pair = root.items.find((p) => keyOf(p) === 'valuations');
     const map = pair?.value;
     const line = cents === null ? '' : `${id}: ${String(cents)}`;
@@ -209,7 +232,9 @@ function setValuationText(text, id, cents) {
             return text.slice(0, start) + block + text.slice(end);
         }
         const before = root.items.find((p) => keyOf(p) === 'memberships' || keyOf(p) === 'cards');
-        return insertLines(text, aboveComments(text, range(before?.key)[0]), block);
+        return before
+            ? insertLines(text, aboveComments(text, range(before.key)[0]), block)
+            : insertLines(text, text.length, block);
     }
     if (!isMap(map))
         throw new Error(`"valuations" isn't a map; ${BY_HAND}`);
@@ -251,7 +276,7 @@ function flowUsage(booking) {
         : booking.period;
     return `{ period: ${period}, spent: ${String(booking.after)} }`;
 }
-export function capUsageText(text, booking) {
+function capUsageText(text, booking) {
     const card = findCard(text, booking.cardId);
     const value = flowUsage(booking);
     const usage = card.get('cap_usage', true);
@@ -271,7 +296,7 @@ export function capUsageText(text, booking) {
     const at = afterLine(text, range(card)[1] - 1);
     return insertLines(text, at, `${indent}cap_usage:\n${indent}  ${booking.capKey}: ${value}\n`);
 }
-export function bonusSpentText(text, cardId, spent) {
+function bonusSpentText(text, cardId, spent) {
     const bonus = findCard(text, cardId).get('bonus', true);
     if (!isMap(bonus))
         throw new Error(`card '${cardId}' has no bonus`);

package/dist/engine/cheat-sheet.js

@@ -1,11 +1,12 @@
-import { resolveMerchantById } from "../merchants/resolve.js";
-import { categoryResolution, exploreCards, } from "./explore.js";
+import { categoryResolution, resolveMerchantById, } from "../merchants/resolve.js";
+import { exploreCards } from "./explore.js";
 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 { feeText, listed, money, shortDate } from "./text.js";
+import { capitalize, feeText, listed, money, shortDate } from "./text.js";
 // The everyday kinds of purchase: the cheat sheet's rows and the site's
 // quick picks.
 export const EVERYDAY_PURCHASES = [
@@ -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('-');
@@ -100,7 +109,6 @@ export function cheatSheet(catalog, wallet, date, items = EVERYDAY_PURCHASES) {
 // The best card earnrate knows for each everyday kind of purchase, for
 // someone who hasn't named any cards. Each row's note says what the card
 // costs or needs.
-const capitalized = (t) => t.charAt(0).toUpperCase() + t.slice(1);
 export function catalogCheatSheet(catalog, date, options, items = EVERYDAY_PURCHASES) {
     const rows = items.map((item) => {
         const top = exploreCards(catalog, 'merchant' in item
@@ -119,7 +127,7 @@ export function catalogCheatSheet(catalog, date, options, items = EVERYDAY_PURCH
                 channel: null,
                 date,
             }, options).ranked[0];
-        const fee = top ? `${capitalized(feeText(top))}.` : null;
+        const fee = top ? `${capitalize(feeText(top))}.` : null;
         return {
             label: item.label,
             cardId: top?.cardId ?? null,