| name | compile |
| description | Generate a monthly categorized budget JSON by running fetch + recompile, then classifying leftovers and forecasting partial months. Use when the user asks to generate, create, or analyze a monthly budget, expenses, or income. |
Compile Budget
Full monthly pipeline. {household} (e.g. trevo) scopes all data under resources/{household}/.
Output is the canonical flat array in SCHEMA.md at
resources/{household}/{YYYY-MM}/expenses/result/budget_{mmm}_{YYYY}.json.
Pipeline
node plugins/open-personal-finance/scripts/fetch.mjs --household {h} --month {YYYY-MM}
node plugins/open-personal-finance/scripts/recompile.mjs --household {h} --month {YYYY-MM}
node plugins/open-personal-finance/scripts/audit.mjs --household {h} --month {YYYY-MM}
/fetch → raw + split files. Each row is tagged _status (posted/pending). When a
card bill closes, Pluggy re-issues its transactions as POSTED under new ids; fetch
identifies those closed bills and removes the stale PENDING duplicates they leave behind
(a PENDING credit row is dropped when a POSTED row with the same card/description/amount/date
already supersedes it). It prints PENDING credit transactions remaining: N — genuine
still-open charges are kept./recompile → builds the canonical budget: auto-classifies expenses/income from
expenses_memory.md / income_memory.md, preserves any prior classifications, parses
installment fields, enriches opaque descriptions, and carries the status (posted/pending)
onto every row. Prints rows left unclassified./classify (or /categorize + /recognize for a first full pass) the unclassified
rows so they consult memory, get classified, and persist new patterns. Re-run /recompile
to apply the new patterns./forecast — for a partial month only, add provisional income (salary) and recurring
fixed expenses as provisional: true rows. /recompile carries these forward and
reconciles them as the real transactions post./audit → node .../audit.mjs --household {h} --month {YYYY-MM} (auto-fixes, retries).
Audit always runs as the final step of every compile so the budget is validated on disk./advise → generates and sends the two Telegram messages (it calls /notify).
Reference
expenses_memory.md — merchant → category/subcategory rules (drives auto-classification).income_memory.md — salary definitions, amount ranges, date windows, known income.- Keep these current via
/classify and /learn; they are the single source of truth, so
the scripts never need per-month edits.
