From 73fffe2e6f359b302b72b1f3740a08e471a31acc Mon Sep 17 00:00:00 2001
From: "Danilo M." <danix@danix.xyz>
Date: Fri, 3 Jul 2026 18:02:48 +0200
Subject: feat: budget management group + tx add --budget (v0.4.0)

New budget group: list, create, delete, enable, disable, limit-list,
limit-set. Budgets resolve by name or id (must pre-exist, not auto-created).
tx add --budget assigns a budget to the transaction. budget list and
limit-set default to the current calendar month.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 SKILL.md | 31 ++++++++++++++++++++++++++++++-
 1 file changed, 30 insertions(+), 1 deletion(-)

(limited to 'SKILL.md')

diff --git a/SKILL.md b/SKILL.md
index 33e5ffc..e8a5a92 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -62,7 +62,7 @@ firefly account create <name> --type asset|expense|revenue
         [--opening-balance N] [--currency CODE]
 firefly tx add <amount> (--from <acct> | --from-id <id>) (--to <acct> | --to-id <id>)
         [--desc TEXT] [--date YYYY-MM-DD] [--category NAME] [--tags a,b] [--type T]
-        [--dry-run] [--skip-dupes]
+        [--budget <name|id>] [--dry-run] [--skip-dupes]
 firefly tx edit <id>
         [--amount N] [--date YYYY-MM-DD] [--desc TEXT] [--from <acct>] [--to <acct>]
         [--category NAME] [--tags a,b] [--type T]   # only fields passed are changed
@@ -72,6 +72,16 @@ firefly tx get <id>
 firefly tx search <query>
 firefly category list
 firefly tag list
+firefly budget list [--start YYYY-MM-DD] [--end YYYY-MM-DD]   # default: current month
+firefly budget create <name> [--active|--inactive]
+        [--auto-budget-amount N --auto-budget-period P --auto-budget-type T] [--currency CODE]
+firefly budget enable <name|id>
+firefly budget disable <name|id>
+firefly budget delete <name|id> --yes                # --yes required, no prompt
+firefly budget limit-list <name|id>
+firefly budget limit-set <name|id> --amount N
+        [--start YYYY-MM-DD] [--end YYYY-MM-DD] [--currency CODE]   # default period: current month
+firefly tx add ... --budget <name|id>                # assign a budget (must already exist)
 ```
 
 Global: `--human` (tables, do not use when parsing), `--url`/`--token`
@@ -133,6 +143,25 @@ it matches amount+date+accounts, not description, so two genuinely distinct
 purchases of the same value, same day, between the same accounts look like a
 duplicate; omit `--skip-dupes` where that is expected.
 
+**Work with budgets.** A budget is a named spending envelope with an optional
+per-period limit. Unlike categories and tags, budgets are **not** auto-created
+by `tx add`, they must exist first (create with `budget create`). Target a
+budget by name or numeric id; a name that does not resolve is a hard error
+listing candidates (never silently unbudgeted).
+```bash
+firefly budget create Groceries                        # make the envelope
+firefly budget limit-set Groceries --amount 400        # cap for the current month
+firefly budget list                                    # each budget + spent this month
+firefly budget list --start 2026-05-01 --end 2026-05-31  # spent in a chosen period
+firefly tx add 42.50 --from test01 --to Supermarket --budget Groceries
+firefly budget limit-list Groceries                    # existing caps for a budget
+firefly budget disable Groceries                        # stop budgeting it (toggle active)
+```
+`budget list` and `budget limit-set` default to the current calendar month when
+`--start`/`--end` are omitted. `budget delete <ref> --yes` removes a budget
+(the `--yes` guard mirrors `tx delete`). Note the leaf names are hyphenated
+(`limit-list`, `limit-set`), not `limit list`.
+
 **Check a balance:**
 ```bash
 firefly account balance test01            # -> {"id","name","current_balance"}
-- 
cgit v1.2.3