# Utility Balance Adjustment Batch — keyboard-first path map

- Date/time: 2026-07-10
- Live DB: `chestervillagenydb`
- Module/menu path: `Billing/Collections > Utility/Property Tax Billing > Balance Adjustments > Utility Balance Adjustment Batch`
- Screen/window: Utility Balance Adjustment Batch / Batch Entry
- Record IDs: existing utility account `601-2`; draft batch `AJH59`
- Goal: reduce utility principal balance by `$59.00` without changing original billing
- Starting proof: `C:/MCSJAgent/proof/utility-adjustment-before.png`
- Ending proof: `C:/MCSJAgent/proof/utility-principal-credit.png`
- Status: **learning/incomplete** — draft entry reached; Save, Verification Listing, Update Batch, and refreshed balance were not completed.

## Keyboard path

1. Create/select batch ID and date; choose Batch Entry; Next.
2. Add row.
3. Tab order verified live:
   `Acct # -> Sub # -> Service Type -> Tran Type -> Adj. Code -> Bill Code -> Year -> Period -> Principal -> Int/Penalty -> Descript -> Date -> Seq`
4. `F3` from Adj. Code opens the code picklist.
5. A balance-reducing principal entry uses a negative amount.
6. Required completion boundary: Save -> Batch Verification Listing -> Update Batch -> reopen/refresh account balance.

## Field/focus map

- Reliable start focus: account field after Add.
- Account/sub used: `601` / `2`; owner/location populated after validation.
- Service/transaction defaults observed: Water / Balance Adjustment.
- F3 picklist: returned code `100`, but its description/type was not verified; do not post from this evidence alone.
- Masked Batch ID pitfall: Ctrl+A did not reliably replace the existing character(s); intended `JH59` became visible as `AJH59`.
- Principal draft: `-59.00`; interest/penalty left at zero.
- Save/update confirmations: not learned in this run.

## Behind-the-scenes visibility

- Swing Bridge: reliable for opening the menu path.
- AgentV4: reliable for tabs and toolbar buttons (`_Next`, `_Add`) and full JavaFX state.
- `FXSETTEXT` on bound custom text controls can fail with `A bound value cannot be set`; use focused keyboard entry.
- Use `python C:/MCSJAgent/mcsj-fx-summary.py --port 9801 --top --pretty` instead of repeated multi-megabyte FXTREE dumps.

## Reusable helper/script changes

- Added compact read-only JavaFX summary: `C:/MCSJAgent/mcsj-fx-summary.py`.
- Added shell-safe Base64 typing command: `mcsj-fast-operator.ps1 typeb64 <base64-utf8-text>`.
- No posting macro yet; build one only after the adjustment-code meaning and Save/Verify/Update sequence are verified end-to-end.

## Patch target

- Patched skill: `mcsj-fast-local-operator`.
- Rule: one failed account-level shortcut then deterministic batch route; verify adjustment-code meaning; reserve actions for final Save/Verify/Update/proof.