personal-finance

Finalize a target month — always refetch it fresh to confirm the movements are complete (all transactions present, no pending left), then recompile with --final to strip provisionals, and run heartbeat for the current month. Defaults to settling the previous month.

Assess a household's monthly investment snapshot for real anomalies. A script produces an objective month-over-month diff (value + quantity per holding, tagged qty/price/new/gone, plus integrity checks); then you reason over it and write a plain-language verdict — a summary message, an assess_{month}.md, and an assess_{month}.json (per-item, consumed by the viewer). Called at the end of /investments; also use whenever the user asks to review, sanity-check, validate, or "assess" a month's investments/portfolio/patrimônio, or whether anything looks unusual, missing, or wrong.

Build a household's monthly investment-portfolio snapshot by reading the broker statements (screenshots + PDFs) in investments/input and writing the canonical personal_finances_{YYYY-MM}.json. Use when the user asks to compile, snapshot, update, or generate investments / portfolio / patrimônio / posições for a month, or mentions BTG/Nubank/Wise/FGTS/Morgan Stanley statements under investments/input.

Validate the schema of a monthly budget, auto-fixing where possible. Checks required fields, types, buckets, FX, enrichment and installment rules. Use when /fetch, /recompile, or /heartbeat call it, or when the user asks to audit, validate, or check a month's data integrity.

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.

Generate the two Telegram budget messages (leftover preamble + full advisory) from a compiled budget. Use when /compile, /heartbeat, or /settle need insights, or when the user asks for advice/analysis on their budget.

Fetch bank and credit card transactions from Pluggy API for a target month and write the raw month files used by the pipeline.

Fetch new Pluggy rows for the current month and recompile while preserving prior classifications. Use for the recurring mid-month update of the open month.

Send the prepared budget messages to Telegram. Reads TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID from .env.local and skips silently if not configured. Use when any skill needs to send notifications after /advise, or when the user asks to send notifications.

Rebuild a month's canonical budget JSON from raw transactions, auto-classifying from memory and preserving prior work. Use when /compile, /heartbeat, or /settle need to (re)generate budget_*.json.

Classify expense transactions into categories using merchant patterns from expenses_memory.md. Handles refunds, special transactions, and flags uncategorized items. Use when /compile calls it or when the user asks to categorize or classify expenses.

Provision recurring expenses for partial/open months based on historical patterns. Estimates fixed costs that haven't appeared yet so budget buckets show meaningful percentages mid-month. Use when /compile calls it for partial months or when the user asks to provision expenses.

Identify and classify income transactions from savings account data. Matches salary by amount+date rules, handles prior-month clearing, and provisions expected salary for partial months. Use when /compile calls it or when the user asks to recognize/classify income.

Discover and map Pluggy accounts to holders and banks. Authenticates, calls Identity/Item/Accounts APIs, and saves pluggy_items.json. Use when /fetch calls it, or when the user asks to list/map/refresh accounts.

Classify specific transactions (expenses or income) using the household's expenses_memory.md and income_memory.md. Receives 1 or more transactions via reply or inline. Updates memory files with new patterns. Use when the user asks to classify specific transactions — NOT for whole-month batch (that's /categorize).

Detect new transaction patterns not yet in memory and persist them. Compares classified budget rows against expenses_memory.md and income_memory.md, adds new patterns, and logs what was learned. Use when /categorize or /recognize call it after classification, or when the user asks to learn, sync, or update memory from a month's data.

Interactive setup wizard for new users. Creates the household folder structure, initializes memory files and .env.local, and runs /accounts if credentials are set. Use when a new user wants to get started or says "setup", "onboard", "get started", or "first time".

Forecast a partial month's full budget by provisioning both income (/recognize) and recurring expenses (/provision). Appends provisional rows into the same top-level flat month array. Use when the user asks to forecast, project, or estimate a partial month's budget.

List classified expense rows from the flat monthly budget result.

List rows still marked as unclassified.

List all rows from the flat monthly budget result.