@rvanbaalen/ofxreader 1.2.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,185 @@
+# ofxreader
+
+[![release-please](https://github.com/rvanbaalen/ofxreader/actions/workflows/release-please.yml/badge.svg)](https://github.com/rvanbaalen/ofxreader/actions/workflows/release-please.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+
+A command-line tool **and MCP server** for reading and querying **OFX 2.x (XML)**
+financial files (bank and credit-card statement exports). Built for LLM/agent
+use: deterministic JSON output, composable filters, structured errors, and a
+self-documenting `--llm` mode.
+
+> Package name: **`@rvanbaalen/ofxreader`** — published to GitHub Packages.
+
+## Requirements
+
+- **Node.js ≥ 24** (uses native TypeScript type-stripping — no build step).
+  Works on Node ≥ 22.18 too. An `.nvmrc` pins the project to Node 24: `nvm use`.
+
+## Install
+
+### From GitHub Packages
+
+The package is published to GitHub Packages as `@rvanbaalen/ofxreader`. Point the
+`@rvanbaalen` scope at the GitHub registry and authenticate with a token that has
+the `read:packages` scope (GitHub Packages requires auth even for public
+packages):
+
+```sh
+# ~/.npmrc
+@rvanbaalen:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
+```
+
+```sh
+npm install -g @rvanbaalen/ofxreader   # installs the `ofxreader` and `ofx-mcp` bins
+ofxreader --llm
+```
+
+### From source
+
+```sh
+git clone https://github.com/rvanbaalen/ofxreader.git
+cd ofxreader
+nvm use                     # Node 24 (see .nvmrc)
+npm install                 # deps: fast-xml-parser, MCP SDK, zod
+
+# Symlink `ofxreader` into /usr/local/bin so you can run it anywhere.
+# /usr/local/bin usually needs sudo on macOS:
+sudo npm run install-cli
+
+# ...or install into a writable directory of your choice:
+OFXREADER_BIN_DIR="$HOME/.local/bin" npm run install-cli
+
+npm run uninstall-cli       # remove the symlink
+```
+
+Without installing, run it directly: `node bin/ofxreader.ts <command> <file>`.
+
+## Usage
+
+```sh
+ofxreader <command> <file.ofx> [options]
+ofxreader --llm            # full machine-readable usage guide (for LLMs/agents)
+ofxreader --help           # short usage
+ofxreader --version
+```
+
+### Commands
+
+| Command                | Output |
+|------------------------|--------|
+| `summary <file>`       | JSON array — one object per statement: account, currency, statement period, ledger & available balance, transaction counts, and totals (credits / debits / net). |
+| `accounts <file>`      | JSON array of accounts (`id`, `type`, `bankId`, `branchId`). |
+| `transactions <file>`  | `{ total, count, transactions: [...] }` — `total` is matches found, `count` is rows returned (differs when `--limit` is set). |
+| `vendors`              | List learned vendor aliases (no file argument). |
+| `vendor-learn "<vendor>" "<descriptor>" […]` | Teach raw descriptors for a vendor (no file argument). |
+
+### Transaction filters
+
+| Flag | Meaning |
+|------|---------|
+| `--from YYYY-MM-DD` / `--to YYYY-MM-DD` | Posted-date range (inclusive). |
+| `--min N` / `--max N` | Signed-amount range. Use the `=` form for negatives: `--min=-100`. |
+| `--type debit\|credit` | `debit` = amount < 0 (money out); `credit` = amount > 0 (money in). |
+| `--search TEXT` | Case-insensitive match over name + memo + payee. |
+| `--regex` | Treat `--search` as a JavaScript regular expression. |
+| `--account ACCTID` | Restrict to one account. |
+| `--vendor "Name"` | Resolve a learned vendor alias. Result holds only confirmed matches, plus a `vendorCandidates` list (fuzzy, unconfirmed) to learn from. See [Vendor learning](#vendor-learning). |
+| `--limit N` | Return at most N rows. |
+| `--pretty` | Indent JSON (default is compact). |
+
+### Examples
+
+```sh
+ofxreader summary statement.ofx --pretty
+ofxreader transactions statement.ofx --from 2024-01-01 --to 2024-03-31
+ofxreader transactions statement.ofx --type debit --search amazon
+ofxreader transactions statement.ofx --search "^ACME" --regex --limit 50
+```
+
+### Output contract
+
+- **Success** → JSON on **stdout**, exit `0`.
+- **Failure** → `{"error":{"code","message"}}` on **stderr**, non-zero exit.
+  Codes: `USAGE` (2), `FILE_NOT_FOUND` (1), `READ_ERROR` (1),
+  `NOT_OFX2` (1 — OFX 1.x SGML is rejected), `PARSE_ERROR` (1).
+
+Amounts are signed numbers; dates are ISO 8601 strings.
+
+## Vendor learning
+
+OFX descriptors are noisy and rarely equal the brand name (`SQ *JASONS CARO 0123`,
+`TST* JASONSCAROUSEL`). ofxreader keeps a local **vendor alias store** mapping a
+canonical vendor name to the descriptors that belong to it, so a question like
+*"what did I spend at Jason's Carousel in April"* resolves to exactly the right records.
+
+- A `--vendor` query returns **only confirmed** matches, plus a `vendorCandidates` list
+  (fuzzy, unconfirmed descriptors) ranked by similarity.
+- Confirm a candidate with the user, persist it, and future queries are deterministic.
+
+```sh
+# 1. Ask — confirmed matches + candidates to confirm
+ofxreader transactions statement.ofx --vendor "Jason's Carousel" --from 2024-04-01 --to 2024-04-30
+
+# 2. Teach the confirmed descriptors
+ofxreader vendor-learn "Jason's Carousel" "SQ *JASONS CARO 0123" "TST* JASONSCAROUSEL"
+
+# 3. Re-run step 1 — now deterministic
+```
+
+The store lives at `$OFXREADER_VENDORS`, else `$XDG_CONFIG_HOME/ofxreader/vendors.json`
+(fallback `~/.config/ofxreader/vendors.json`). It is the source of truth; nothing is
+sent anywhere.
+
+## Use as an MCP server
+
+The same parser is exposed as a local [Model Context Protocol](https://modelcontextprotocol.io)
+server (stdio transport) so Claude can work with OFX files directly. It registers
+these tools covering every CLI capability:
+
+| Tool | Input | Returns |
+|------|-------|---------|
+| `ofx_summary` | `path` | per-statement summaries |
+| `ofx_accounts` | `path` | account list |
+| `ofx_transactions` | `path` + filters (`from`, `to`, `min`, `max`, `type`, `search`, `regex`, `account`, `limit`, `vendor`) | `{ total, count, transactions[] }` (plus `vendorCandidates` when `vendor` is set) |
+| `ofx_vendor_learn` | `vendor`, `descriptors[]` | the updated vendor entry |
+| `ofx_vendors` | — | learned vendor aliases |
+
+It also exposes one **resource** template:
+
+| Resource | URI | Returns |
+|----------|-----|---------|
+| `ofx-balances` | `ofx:/absolute/path/to/file.ofx` | Ledger & available balance per account, each stated with its as-of date — e.g. `Balance at 2024-03-31 is 4327.87 USD` |
+
+Run it directly with `npm run mcp` (or `node bin/ofx-mcp.ts`).
+
+### Claude Desktop
+
+Add it to `~/Library/Application Support/Claude/claude_desktop_config.json`, then
+restart Claude Desktop. Use an **absolute** path to a Node ≥ 24 binary — the
+desktop app launches with a minimal PATH that won't include an nvm-managed `node`:
+
+```json
+{
+  "mcpServers": {
+    "ofxreader": {
+      "command": "/Users/robin/.nvm/versions/node/v24.13.1/bin/node",
+      "args": ["/Users/robin/Sites/projects/ofxreader/bin/ofx-mcp.ts"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+```sh
+claude mcp add ofxreader -- /Users/robin/.nvm/versions/node/v24.13.1/bin/node \
+  /Users/robin/Sites/projects/ofxreader/bin/ofx-mcp.ts
+```
+
+## Development
+
+```sh
+npm test          # node:test suite (runs .ts directly)
+npm run typecheck # tsc --noEmit (type-check only; never emits)
+```

package/bin/ofx-mcp.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "../src/mcp.ts";
+
+const server = createServer();
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/bin/ofxreader.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { run } from "../src/cli.ts";
+
+process.exitCode = run(process.argv.slice(2));

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@rvanbaalen/ofxreader",
+  "version": "1.2.0",
+  "description": "CLI for reading and querying OFX 2.x (XML) financial files. Built for LLM/agent use: deterministic JSON output and a self-documenting --llm mode.",
+  "type": "module",
+  "bin": {
+    "ofxreader": "bin/ofxreader.ts",
+    "ofx-mcp": "bin/ofx-mcp.ts"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "ofxreader": "node bin/ofxreader.ts",
+    "mcp": "node bin/ofx-mcp.ts",
+    "install-cli": "node scripts/install.ts",
+    "uninstall-cli": "node scripts/install.ts uninstall",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test test/*.test.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rvanbaalen/ofxreader.git"
+  },
+  "homepage": "https://github.com/rvanbaalen/ofxreader#readme",
+  "bugs": {
+    "url": "https://github.com/rvanbaalen/ofxreader/issues"
+  },
+  "author": "Robin van Baalen",
+  "keywords": [
+    "ofx",
+    "qfx",
+    "cli",
+    "mcp",
+    "finance",
+    "bank",
+    "transactions",
+    "llm",
+    "agent"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "fast-xml-parser": "^5.8.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "typescript": "^6.0.3"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,181 @@
+import { parseArgs } from "node:util";
+
+import { readOfxFile, parseOfx, OfxError } from "./parser.ts";
+import { buildDocument } from "./model.ts";
+import { filterTransactions } from "./query.ts";
+import type { TransactionFilters } from "./query.ts";
+import { summaries, uniqueAccounts } from "./report.ts";
+import { resolveVendorQuery } from "./vendors/resolve.ts";
+import { load as loadVendors, save as saveVendors, learn as learnVendor, today } from "./vendors/store.ts";
+import { emit, emitError } from "./output.ts";
+import { HELP_TEXT, LLM_INSTRUCTIONS } from "./help.ts";
+import { getVersion } from "./version.ts";
+
+const FILE_COMMANDS = ["summary", "accounts", "transactions"] as const;
+const ALL_COMMANDS = "summary | accounts | transactions | vendors | vendor-learn";
+
+const OPTIONS = {
+  from: { type: "string" },
+  to: { type: "string" },
+  min: { type: "string" },
+  max: { type: "string" },
+  type: { type: "string" },
+  search: { type: "string" },
+  regex: { type: "boolean" },
+  account: { type: "string" },
+  limit: { type: "string" },
+  vendor: { type: "string" },
+  pretty: { type: "boolean" },
+  llm: { type: "boolean" },
+  help: { type: "boolean", short: "h" },
+  version: { type: "boolean", short: "v" },
+} as const;
+
+/** Run the CLI. Returns the process exit code. */
+export function run(argv: string[]): number {
+  let values: Record<string, string | boolean | undefined>;
+  let positionals: string[];
+  try {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: OPTIONS });
+    values = parsed.values;
+    positionals = parsed.positionals;
+  } catch (err) {
+    emitError("USAGE", (err as Error).message);
+    return 2;
+  }
+
+  const pretty = values.pretty === true;
+
+  if (values.version === true) {
+    process.stdout.write(getVersion() + "\n");
+    return 0;
+  }
+  if (values.llm === true) {
+    process.stdout.write(LLM_INSTRUCTIONS + "\n");
+    return 0;
+  }
+  if (values.help === true) {
+    process.stdout.write(HELP_TEXT + "\n");
+    return 0;
+  }
+
+  const command = positionals[0];
+  if (command == null) {
+    process.stderr.write(HELP_TEXT + "\n");
+    return 2;
+  }
+
+  // Store-based commands (no OFX file argument).
+  if (command === "vendors") {
+    try {
+      emit(loadVendors().vendors, pretty);
+      return 0;
+    } catch (err) {
+      return reportError(err);
+    }
+  }
+  if (command === "vendor-learn") {
+    const name = positionals[1];
+    const descriptors = positionals.slice(2);
+    if (name == null || descriptors.length === 0) {
+      emitError("USAGE", 'Usage: ofxreader vendor-learn "<vendor>" "<descriptor>" [more...]');
+      return 2;
+    }
+    try {
+      const store = loadVendors();
+      const entry = learnVendor(store, name, descriptors, today());
+      saveVendors(store);
+      emit({ vendor: name, ...entry }, pretty);
+      return 0;
+    } catch (err) {
+      return reportError(err);
+    }
+  }
+
+  if (!(FILE_COMMANDS as readonly string[]).includes(command)) {
+    emitError("USAGE", `Unknown command "${command}". Expected: ${ALL_COMMANDS}. Run --llm for help.`);
+    return 2;
+  }
+
+  const file = positionals[1];
+  if (file == null) {
+    emitError("USAGE", `Missing file argument. Usage: ofxreader ${command} <file.ofx>`);
+    return 2;
+  }
+
+  try {
+    const doc = buildDocument(parseOfx(readOfxFile(file)));
+
+    if (command === "summary") {
+      emit(summaries(doc.statements), pretty);
+    } else if (command === "accounts") {
+      emit(uniqueAccounts(doc.statements), pretty);
+    } else {
+      const filters = buildFilters(values);
+      if (typeof values.vendor === "string") {
+        emit(resolveVendorQuery(loadVendors(), doc.statements, values.vendor, filters), pretty);
+      } else {
+        const all = doc.statements.flatMap((s) => s.transactions);
+        emit(filterTransactions(all, filters), pretty);
+      }
+    }
+    return 0;
+  } catch (err) {
+    return reportError(err);
+  }
+}
+
+function reportError(err: unknown): number {
+  if (err instanceof OfxError) {
+    emitError(err.code, err.message);
+    return err.code === "USAGE" ? 2 : 1;
+  }
+  emitError("INTERNAL", (err as Error).message);
+  return 1;
+}
+
+function buildFilters(values: Record<string, string | boolean | undefined>): TransactionFilters {
+  const f: TransactionFilters = {};
+
+  if (typeof values.from === "string") f.from = checkDate(values.from, "--from");
+  if (typeof values.to === "string") f.to = checkDate(values.to, "--to");
+  if (typeof values.min === "string") f.min = parseNum(values.min, "--min");
+  if (typeof values.max === "string") f.max = parseNum(values.max, "--max");
+
+  if (typeof values.type === "string") {
+    if (values.type !== "debit" && values.type !== "credit") {
+      throw new OfxError("USAGE", `--type must be "debit" or "credit", got "${values.type}".`);
+    }
+    f.type = values.type;
+  }
+
+  if (typeof values.search === "string") f.search = values.search;
+  if (values.regex === true) f.regex = true;
+  if (typeof values.account === "string") f.account = values.account;
+
+  if (typeof values.limit === "string") {
+    const n = parseNum(values.limit, "--limit");
+    if (!Number.isInteger(n) || n < 0) {
+      throw new OfxError("USAGE", `--limit must be a non-negative integer, got "${values.limit}".`);
+    }
+    f.limit = n;
+  }
+
+  if (f.regex && f.search == null) {
+    throw new OfxError("USAGE", "--regex requires --search.");
+  }
+  return f;
+}
+
+function parseNum(value: string, flag: string): number {
+  const n = Number(value);
+  if (Number.isNaN(n)) throw new OfxError("USAGE", `${flag} must be a number, got "${value}".`);
+  return n;
+}
+
+function checkDate(value: string, flag: string): string {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+    throw new OfxError("USAGE", `${flag} must be YYYY-MM-DD, got "${value}".`);
+  }
+  return value;
+}

package/src/dates.ts

@@ -0,0 +1,51 @@
+/**
+ * OFX datetime helpers.
+ *
+ * OFX dates look like:  YYYYMMDD[HHMMSS[.SSS]][[+/-OFFSET[:TZNAME]]]
+ * Examples:
+ *   "20240115"
+ *   "20240115120000"
+ *   "20240115120000.000"
+ *   "20240115120000.000[-5:EST]"
+ *   "20240115120000[+5.5:IST]"
+ */
+
+const OFX_DATE_RE =
+  /^(\d{4})(\d{2})(\d{2})(?:(\d{2})(\d{2})(\d{2})(?:\.(\d{1,3}))?)?(?:\[\s*([+-]?\d+(?:\.\d+)?)\s*(?::([^\]]*))?\])?$/;
+
+/**
+ * Convert an OFX datetime to ISO 8601.
+ * Returns a full timestamp when a time component is present, otherwise a
+ * date-only string (YYYY-MM-DD). Returns null when the value can't be parsed.
+ */
+export function ofxToIso(value: string | null | undefined): string | null {
+  if (value == null) return null;
+  const raw = String(value).trim();
+  const m = OFX_DATE_RE.exec(raw);
+  if (m == null) return null;
+
+  const [, y, mo, d, hh, mm, ss, ms, tz] = m;
+  if (hh == null) return `${y}-${mo}-${d}`;
+
+  const millis = ms != null ? `.${ms.padEnd(3, "0")}` : "";
+  const offset = tz != null ? formatOffset(tz) : "";
+  return `${y}-${mo}-${d}T${hh}:${mm}:${ss}${millis}${offset}`;
+}
+
+/** Date-only portion (YYYY-MM-DD) used for inclusive range comparisons. */
+export function ofxToDateOnly(value: string | null | undefined): string | null {
+  const iso = ofxToIso(value);
+  return iso == null ? null : iso.slice(0, 10);
+}
+
+function formatOffset(tz: string): string {
+  const hours = Number(tz);
+  if (Number.isNaN(hours)) return "";
+  const sign = hours < 0 ? "-" : "+";
+  const abs = Math.abs(hours);
+  const wholeHours = Math.floor(abs);
+  const minutes = Math.round((abs - wholeHours) * 60);
+  const hh = String(wholeHours).padStart(2, "0");
+  const mm = String(minutes).padStart(2, "0");
+  return `${sign}${hh}:${mm}`;
+}

package/src/help.ts

@@ -0,0 +1,130 @@
+export const HELP_TEXT = `ofxreader — read & query OFX 2.x (XML) files. JSON in, JSON out.
+
+USAGE
+  ofxreader <command> <file.ofx> [options]
+  ofxreader --llm        # full machine-readable usage guide (for LLMs/agents)
+  ofxreader --version
+  ofxreader --help
+
+COMMANDS
+  summary <file>        Per-statement overview (account, period, balances, totals)
+  accounts <file>       Accounts found in the file
+  transactions <file>   Transactions, with optional filters
+  vendors               List learned vendor aliases
+  vendor-learn "<vendor>" "<descriptor>" [more...]   Teach descriptors for a vendor
+
+TRANSACTION FILTERS
+  --from YYYY-MM-DD  --to YYYY-MM-DD   posted-date range (inclusive)
+  --min N            --max N           signed-amount range (e.g. --min=-100)
+  --type debit|credit                  debit = money out, credit = money in
+  --search TEXT      --regex           match name + memo + payee
+  --account ACCTID                     restrict to one account
+  --vendor "Name"                      resolve a learned vendor alias (+ candidates)
+  --limit N                            cap rows returned
+
+GLOBAL
+  --pretty                             indent JSON (default: compact)
+
+Run "ofxreader --llm" for output shapes, exit codes, and examples.`;
+
+export const LLM_INSTRUCTIONS = `ofxreader — instructions for LLM/agent use
+==========================================
+
+PURPOSE
+  Parse a bank or credit-card OFX 2.x (XML) export and return structured JSON for
+  accounts, balances, statement periods, and transactions — optionally filtered.
+  Output is deterministic JSON on stdout, so you can parse it directly.
+
+INVOCATION
+  ofxreader <command> <file.ofx> [options]
+
+COMMANDS
+  summary <file>
+      Per-statement overview. Returns a JSON array, one object per statement:
+        {
+          "account":   { "id", "type", "bankId", "branchId" },
+          "currency":  "USD" | null,
+          "period":    { "start": ISO8601|null, "end": ISO8601|null },
+          "balance":   { "amount": number, "asOf": ISO8601|null } | null,
+          "available": { "amount": number, "asOf": ISO8601|null } | null,
+          "counts":    { "transactions": int, "credits": int, "debits": int },
+          "totals":    { "credits": number, "debits": number, "net": number }
+        }
+
+  accounts <file>
+      JSON array of the accounts in the file:
+        { "id", "type", "bankId", "branchId" }
+
+  transactions <file> [filters]
+      JSON object:
+        { "total": int, "count": int, "transactions": [ Transaction, ... ] }
+      "total" = matches found; "count" = rows returned (differs when --limit is set).
+      Transaction:
+        {
+          "account": acctid, "id": fitid, "date": ISO8601|null,
+          "amount": number,           // signed; negative = money out
+          "trnType": "DEBIT"|"CREDIT"|"CHECK"|"POS"|"FEE"|...,  // raw OFX type
+          "name": string, "memo": string|null,
+          "payee": string|null, "checkNumber": string|null
+        }
+
+  vendors
+      JSON object mapping canonical vendor name -> { signatures[], raw[], updatedAt }.
+
+  vendor-learn "<vendor>" "<descriptor>" [more...]
+      Persist that these raw descriptors belong to the vendor (normalized into
+      signatures for deterministic matching). Returns the updated vendor entry.
+
+TRANSACTION FILTERS (transactions command only; all optional, all combinable)
+  --from YYYY-MM-DD    posted on/after this date (inclusive)
+  --to   YYYY-MM-DD    posted on/before this date (inclusive)
+  --min  N             signed amount >= N   (use = for negatives, e.g. --min=-100)
+  --max  N             signed amount <= N   (e.g. --max=-0.01 for outflows only)
+  --type debit|credit  debit = amount < 0 (money out); credit = amount > 0 (money in)
+  --search TEXT        case-insensitive substring over name + memo + payee
+  --regex              treat --search as a JavaScript regular expression
+  --account ACCTID     restrict to a single account (id from "accounts"/"summary")
+  --limit N            return at most N rows ("total" still reports all matches)
+  --vendor "Name"      resolve a learned vendor alias; results hold only CONFIRMED
+                       matches and add "vendorCandidates" (fuzzy) to learn from
+
+GLOBAL OPTIONS
+  --pretty             indent JSON for humans (default is compact, token-efficient)
+  --llm                print this guide
+  --version            print version
+  --help               print short usage
+
+VENDOR LEARNING (match messy descriptors to a real vendor)
+  OFX descriptors are noisy ("SQ *JASONS CARO 0123") and rarely equal the brand name.
+  To answer "what did I spend at Jason's Carousel in April":
+    1) transactions stmt.ofx --vendor "Jason's Carousel" --from 2024-04-01 --to 2024-04-30
+       -> "transactions" = confirmed matches; "vendorCandidates" = fuzzy guesses, each
+          { "normalized", "examples": [raw...], "count", "similarity" }.
+    2) If a candidate is right, confirm with the user, then persist it:
+          vendor-learn "Jason's Carousel" "SQ *JASONS CARO 0123" "TST* JASONSCAROUSEL"
+    3) Re-run step 1 — matches are now deterministic.
+  Store: $OFXREADER_VENDORS, else ~/.config/ofxreader/vendors.json.
+
+OUTPUT CONTRACT
+  Success: JSON on stdout, exit code 0.
+  Failure: JSON on stderr as {"error":{"code","message"}}, non-zero exit code.
+    USAGE          (exit 2)  bad/unknown arguments or missing file
+    FILE_NOT_FOUND (exit 1)  path does not exist
+    READ_ERROR     (exit 1)  path unreadable / is a directory
+    NOT_OFX2       (exit 1)  not an OFX 2.x XML file (OFX 1.x SGML is rejected)
+    PARSE_ERROR    (exit 1)  malformed XML / no <OFX> root
+    VENDOR_STORE_ERROR (exit 1)  vendor alias store is unreadable / invalid JSON
+  Notes: amounts are signed numbers; dates are ISO 8601 strings; flags accept
+  both "--flag value" and "--flag=value" (use the "=" form for negative numbers).
+
+EXAMPLES
+  ofxreader summary statement.ofx
+  ofxreader accounts statement.ofx --pretty
+  ofxreader transactions statement.ofx --from 2024-01-01 --to 2024-03-31
+  ofxreader transactions statement.ofx --type debit --search amazon
+  ofxreader transactions statement.ofx --min=-50 --max=-0.01        # small outflows
+  ofxreader transactions statement.ofx --search "^ACME" --regex --limit 50
+  ofxreader transactions statement.ofx --account 1234567890
+  ofxreader transactions statement.ofx --vendor "Jason's Carousel" --from 2024-04-01 --to 2024-04-30
+  ofxreader vendor-learn "Jason's Carousel" "SQ *JASONS CARO 0123"
+  ofxreader vendors`;