docs: spec for budget management group (list/create/delete/enable/disable/limit + tx add --budget)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

1 files changed, 156 insertions, 0 deletions

diff --git a/docs/superpowers/specs/2026-07-03-budget-management-design.md b/docs/superpowers/specs/2026-07-03-budget-management-design.md
new file mode 100644
index 0000000..854425f
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-03-budget-management-design.md
@@ -0,0 +1,156 @@
+# Budget management design
+
+Date: 2026-07-03
+Status: approved (design), pending spec review
+Firefly reference: v6.6.6 (matches running instance)
+
+## Goal
+
+Let the agent (and user) manage Firefly III budgets from the `firefly` CLI:
+see spending vs budget, set/change monthly limits, create/delete budgets,
+enable/disable them, and assign a budget to a transaction when adding it.
+
+Ships as ONE MINOR release (new `budget` group + one new optional flag on
+`tx add`, no breaking change to the existing contract).
+
+## Firefly API facts (verified against v6.6.6)
+
+- `GET /api/v1/budgets?start=&end=` — list budgets. With a start/end range the
+  budget objects carry `spent` (array per currency) for that range. Without it,
+  `spent` is null. Budget transformer fields include: `id`, `name`, `active`,
+  `auto_budget_type`, `auto_budget_period`, `auto_budget_amount`,
+  `currency_code`, `spent`.
+- `POST /api/v1/budgets` — create. Accepts `name` (required, unique per user),
+  `active` (bool), `auto_budget_type` (in: reset,rollover,adjusted,none),
+  `auto_budget_amount`, `auto_budget_period`, `currency_code`.
+- `PUT /api/v1/budgets/{id}` — update. Accepts `name`, `active`, and the same
+  auto-budget fields. There is NO dedicated enable/disable endpoint; toggling
+  `active` is done via this update.
+- `DELETE /api/v1/budgets/{id}` — delete.
+- `GET /api/v1/budgets/{id}/limits` — list budget limits (the period caps).
+- `POST /api/v1/budgets/{id}/limits` — create a limit. Accepts `start`
+  (required, date, before end), `end` (required, after start), `amount`
+  (required, positive), `currency_id`/`currency_code`, `notes`. BudgetLimit
+  transformer fields include: `id`, `budget_id`, `start`, `end`, `amount`,
+  `period`, `spent`, `currency_code`.
+- Transaction split accepts `budget_id` (and `budget_name`) — see
+  `StoreRequest.php` lines 262-263. Firefly does NOT auto-create budgets from a
+  transaction: the budget must already exist. So we resolve name -> id and pass
+  `budget_id`.
+
+Budget names are unique per user (`uniqueObjectForUser:budgets,name`), so
+name->id resolution is unambiguous in practice; the resolver still errors hard
+on a miss, matching account handling.
+
+## Commands
+
+New module `firefly_cli/commands/budget.py`. All handlers register via
+`@registry.command(...)` with the decorator immediately above the handler def
+(the v0.3.7 misbinding bug — keep decorator adjacent to `cmd_*`).
+
+| Command | HTTP | Args |
+|---|---|---|
+| `budget list` | `GET /budgets?start&end` | `--start`, `--end` (default: current month) |
+| `budget create <name>` | `POST /budgets` | `--active`/`--inactive` (default active), `--auto-budget-amount`, `--auto-budget-period`, `--auto-budget-type`, `--currency` |
+| `budget delete <ref>` | `DELETE /budgets/{id}` | `--yes` (required, matches `tx delete`) |
+| `budget enable <ref>` | `PUT /budgets/{id}` `{active:true}` | — |
+| `budget disable <ref>` | `PUT /budgets/{id}` `{active:false}` | — |
+| `budget limit list <ref>` | `GET /budgets/{id}/limits` | — |
+| `budget limit set <ref>` | `POST /budgets/{id}/limits` | `--amount` (required), `--start`, `--end` (default current month), `--currency` |
+
+`<ref>` is a budget name OR id, resolved by the new `resolver.budget()`.
+
+`budget limit` is a two-level group (`budget limit list`, `budget limit set`),
+consistent with how the registry keys multi-word command names.
+
+### tx add --budget
+
+Add one optional flag to `tx add`:
+`--budget <ref>` — resolve name/id via `resolver.budget()`, set `budget_id` on
+the transaction split. Omitted = no budget (unchanged behavior).
+
+Not added to `tx edit` this release (YAGNI; add when a re-budgeting task needs
+it).
+
+## Resolver
+
+Add `Resolver.budget(name_or_id)` mirroring `Resolver.account`:
+- numeric-looking arg -> fetch `GET /budgets/{id}` (via a `budget_by_id` path
+  or inline), return the object; miss -> `ResolutionError`.
+- otherwise list budgets and match by name; ambiguous or missing ->
+  `ResolutionError` listing candidates.
+
+Reuse the existing `_match` helper and `_list` pattern. `GET /budgets/{id}`
+returns a single budget; if Firefly returns a non-404 (e.g. the 401 quirk seen
+for unknown account ids) the resolver still fails closed. Add a `ponytail:`
+note only if the id path shows the same 401-for-unknown-id quirk in smoke.
+
+## Period helper
+
+`_current_month()` -> `(first_iso, last_iso)` using `datetime.date`:
+first = `date.today().replace(day=1)`, last = first day of next month minus one
+day (via `calendar.monthrange`). Shared by `budget list` and `budget limit set`
+default range. Stdlib only.
+
+## Output views (--human)
+
+JSON stays the default. Add to `output.py` `_VIEWS`:
+- budget view: columns `id`, `name`, `active`, `spent` (summed/trimmed like tx
+  amounts), plus limit info if a limit is present in the range.
+- budget-limit view: `id`, `budget_id`, `start`, `end`, `amount`, `spent`,
+  `period`.
+
+Match the existing `_VIEWS` signature-matching mechanism (a set of keys ->
+column list). If a resource shape doesn't match cleanly, fall back to raw JSON
+(existing behavior), no crash.
+
+## Completion
+
+Regenerate `completions/firefly.bash` via
+`python scripts/gen_completion.py > completions/firefly.bash`. Add fixed-enum
+values to `FLAG_VALUES` in `gen_completion.py` for `--auto-budget-type`
+(reset|rollover|adjusted|none), `--auto-budget-period`, and the
+`--active/--inactive` pair.
+
+## Errors
+
+All failures are `FireflyError` subclasses (existing contract): unresolved
+budget ref -> `ResolutionError` with candidates; a missing required `--amount`
+on `limit set` -> argparse error; Firefly 4xx/5xx -> surfaced by `client.py`.
+`budget delete` without `--yes` -> hard error, no call made.
+
+## Testing
+
+- Unit tests under `tests/unit/` per command, mocking `ctx.client` /
+  `ctx.resolver` (the established pattern). Cover: list with/without period,
+  create (active + inactive + auto-budget), delete (with and without --yes),
+  enable/disable body shape, limit list, limit set (default + explicit period),
+  tx add --budget sets `budget_id`, resolver.budget name + id + miss +
+  ambiguous.
+- One handler-registration regression test asserting each registered
+  `budget*` command binds to its `cmd_*` (registry misbinding is invisible to
+  direct-call unit tests — the v0.3.7 lesson).
+- Live smoke against the test instance (source
+  `~/.config/firefly-cli/test-creds.env`) after implementation: create a
+  budget, set a limit, list, assign via tx add (create-then-delete own data),
+  because the mocked suite bypasses the registry.
+
+## SKILL.md
+
+Document the new `budget` group, name->id resolution for budgets (must
+pre-exist, not auto-created), the current-month default period, and the
+`tx add --budget` flag.
+
+## Versioning
+
+New command group + new optional flag, contract-additive -> MINOR bump. Bump
+`pyproject.toml` and `firefly_cli/__init__.py` together, tag `vX.Y.Z` signed,
+push `--follow-tags`.
+
+## Out of scope (YAGNI)
+
+- `budget update` for rename / auto-budget edits (delete+recreate, or web UI).
+- `budget limit update` / `budget limit delete`.
+- `tx edit --budget`.
+- available-budgets endpoints, object-groups.
+Add any of these when a concrete task needs it.