appears to reject receipt-only updates on existing explanations

[damacus]

Summary

freeagent-cli bank explain update advertises a --receipt flag, but when used to attach a receipt to an existing explanation without changing other fields, the CLI exits with:

no fields to update

This makes the most important reconciliation workflow appear supported in help text but unusable in practice.

Reproduction

Command pattern used:

freeagent-cli bank explain update EXPLANATION_URL --receipt ./paperless/Receipt-2860-8601.pdf

Observed result:

2026/03/26 22:51:51 no fields to update

I reproduced the same behavior across multiple existing explanations.

Examples used during testing:

• https://api.freeagent.com/v2/bank_transaction_explanations/694920607
• https://api.freeagent.com/v2/bank_transaction_explanations/694485684
• https://api.freeagent.com/v2/bank_transaction_explanations/693567610
• https://api.freeagent.com/v2/bank_transaction_explanations/692586808

Each command used only --receipt with a valid local PDF path.

Why this is a problem

In real bookkeeping workflows, a transaction is often already explained correctly but still missing its receipt. In that case, I do not want to:

• retype the date
• retype the description
• retype the gross value
• retype the category
• risk changing fields that are already correct
• delete and recreate the explanation just to attach a PDF

A receipt-only update is the natural and safest operation.

Expected behavior

If --receipt is provided, the CLI should treat that as a meaningful update even when no other fields are changing.

Expected successful workflow:

freeagent-cli bank explain update EXPLANATION_URL --receipt ./paperless/Receipt-2860-8601.pdf

Expected outcome:

• existing explanation remains otherwise unchanged
• receipt is attached
• command exits successfully

Actual behavior

The CLI appears to exclude receipt-only changes from its update field detection, resulting in no fields to update.

Suggested fix

• Treat --receipt as an update field in its own right.
• If the API requires multipart or a different endpoint shape, handle that internally.
• Keep the rest of the explanation unchanged when only --receipt is provided.

Desired follow-up

It would also be helpful if this behavior were covered by a CLI test, because attaching receipts to already-explained transactions is a common reconciliation path.

Related issue

A broader feature request is needed for first-class bank review/reconciliation commands, but this issue is narrower: the existing update command looks like it should work for receipt attachment and currently does not.

[damacus]

Fixed in the current mainline CLI and verified against real FreeAgent data on 2026-04-13.

Acceptance test used the exact receipt-only update form that previously failed with no fields to update:

• freeagent-cli bank explain update 704767887 --receipt /Users/damacus/receipts/paperless/Receipt-2829-4890-4308.pdf
• freeagent-cli bank explain update 702209039 --receipt /Users/damacus/receipts/paperless/Receipt-2123-3007-1292.pdf
• freeagent-cli bank explain update 703032295 --receipt /Users/damacus/receipts/paperless/github-damacus-receipt-2026-04-07.pdf
• freeagent-cli bank explain update 703027299 --receipt /Users/damacus/receipts/paperless/Maslins-Limited_Invoice_102302.pdf

All four updates succeeded and returned explanations with populated attachment objects.

Root cause here was binary drift: the source tree already contained the fix, but the installed local freeagent-cli binary predated it. Rebuilding from current main and replacing the stale binary resolved the behavior on the normal command path as well.