feat(piggy): piggy list/add/remove (v0.6.0)HEADv0.6.0master

New `piggy` group:
- `piggy list` lists piggy banks with saved/target amounts and linked
  accounts.
- `piggy add|remove <name|id> <amount> [--account NAME]` changes the
  saved amount on a linked account via PUT /piggy-banks/{id}.

Firefly syncs the whole account list on that PUT, so every linked account
is resent (others without current_amount, which keeps their value) or it
would be unlinked. Removing below zero is rejected before any write, and
the saved amount is read back so a refused add fails loudly instead of
returning 200 unchanged.

add/remove currently hit an upstream bug on Firefly III <= 6.7.9:
PiggyBankFactory::linkToAccountIds passes the pivot current_amount (an int
from the DB) to bcsub() uncast, so any PUT with "accounts" 500s
(firefly-iii/firefly-iii#13063). Documented in SKILL.md/README; the live
integration test skips on that error and runs once upstream is fixed.

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

1 files changed, 22 insertions, 0 deletions

diff --git a/SKILL.md b/SKILL.md
index 87dcc94..7611e7d 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -83,6 +83,9 @@ 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 piggy list
+firefly piggy add <name|id> <amount> [--account NAME]     # --account only if linked to several
+firefly piggy remove <name|id> <amount> [--account NAME]
 ```
 
 Global: `--human` (tables, do not use when parsing), `--url`/`--token`
@@ -166,6 +169,25 @@ firefly budget disable Groceries                        # stop budgeting it (tog
 fields you pass (rename via `--name`, or edit the auto-budget fields). Note the
 leaf names are hyphenated (`limit-list`, `limit-set`), not `limit list`.
 
+**Piggy banks.** A piggy bank earmarks money inside one or more linked asset
+accounts; moving money in or out does NOT create a transaction or change any
+account balance. `piggy list` shows each one with `current_amount`,
+`target_amount` and its linked `accounts`. `piggy add/remove <ref> <amount>`
+changes the saved amount on the linked account (`--account NAME` when the
+piggy bank has several). Removing more than is saved is a hard error before
+any write; an add Firefly refuses (not enough unallocated money, target
+exceeded) is a hard error too, never a silent no-op.
+```bash
+firefly piggy list
+firefly piggy add "BBVA risparmi" 7.09
+firefly piggy remove "BBVA risparmi" 2 --account BBVA
+```
+**Known upstream bug:** on Firefly III up to at least 6.7.9, `piggy add` and
+`piggy remove` fail with `API error 500: ... bcsub(): Argument #2 ($num2) must
+be of type string, int given` (firefly-iii/firefly-iii#13063). Nothing is
+written. Until it is fixed, tell the user to move the amount in the Firefly
+web UI; do not call the API directly.
+
 **Check a balance:**
 ```bash
 firefly account balance test01            # -> {"id","name","current_balance"}