feat: budget management group + tx add --budget (v0.4.0)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>

3 files changed, 32 insertions, 3 deletions

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"}
diff --git a/firefly_cli/__init__.py b/firefly_cli/__init__.py
index 66300ca..f2c1864 100644
--- a/firefly_cli/__init__.py
+++ b/firefly_cli/__init__.py
@@ -2,4 +2,4 @@
 # Copyright (C) 2026 Danilo M. <danix@danix.xyz>
 # Licensed under the GNU General Public License v2.0 only.
 
-__version__ = "0.3.8"
+__version__ = "0.4.0"
diff --git a/pyproject.toml b/pyproject.toml
index ae35bd7..0d1f7e6 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "firefly-iii-agent"
-version = "0.3.8"
+version = "0.4.0"
 description = "CLI tool for agent interaction with Firefly III"
 readme = "README.md"
 requires-python = ">=3.11"