docs(budget): say what settled_at does when it is left out

server/src/nest/budget/budget.mcp.ts

@@ -433,7 +433,7 @@ export class BudgetMcp {
       to_user_id: z.number().int().positive().describe('User ID of the member who received the payment'),
       amount: z.number().positive().describe('Amount paid, in `currency`'),
       currency: z.string().max(10).nullable().optional().describe("ISO currency code the payment was made in (e.g. \"USD\"); defaults to the trip currency. Its FX rate is frozen now, so the transfer keeps cancelling its expense when live rates drift."),
-      settled_at: z.string().max(40).nullable().optional().describe('Date the payment actually happened, YYYY-MM-DD; defaults to today when omitted.'),
+      settled_at: z.string().max(40).nullable().optional().describe('Day the payment actually happened, YYYY-MM-DD. Omitted means no day is stored and the ledger files the payment under the day it was recorded.'),
     },
     annotations: TOOL_ANNOTATIONS_NON_IDEMPOTENT,
     when: budgetAddonOn,

shared/src/budget/budget.schema.ts

@@ -240,7 +240,8 @@ export const budgetCreateSettlementRequestSchema = z.object({
   amount: z.number(),
   // The display currency the amount was entered in; the server freezes its FX rate.
   currency: z.string().nullable().optional(),
-  // The day the transfer happened; defaults to today (server-side) when omitted.
+  // The day the transfer happened. Null when the caller sets none; the ledger then
+  // uses the day it was recorded, which is where every older payment already sits.
   settled_at: z.string().nullable().optional(),
 });
 export type BudgetCreateSettlementRequest = z.infer<typeof budgetCreateSettlementRequestSchema>;

wiki/Budget-Tracking.md

@@ -92,7 +92,7 @@ Costs works out the minimum number of transfers needed to settle all debts (usin
 
 Balances are always netted in the **trip currency** and converted to your display currency once, at the end — so they stay stable even when the trip mixes currencies.
 
-A recorded payment carries **its own currency** too: settling a rouble debt with a euro transfer is normal, so the payment modal has a currency picker, and its rate is frozen when you record it. A payment made in another currency shows both amounts in the ledger (`$30.00 → 27,00 €`).
+A recorded payment carries **its own currency** too: settling a rouble debt with a euro transfer is normal, so the payment modal has a currency picker, and its rate is frozen when you record it. A payment made in another currency shows both amounts in the ledger (`$30.00 → 27,00 €`). A payment also carries the day it happened, editable like an expense's date, so a transfer you only get round to recording three days later still lands on the right day; payments recorded before this field existed stay on the day they were recorded.
 
 ![Add payment dialog with From and To member pickers, an amount field and a currency selector](assets/CostsSettleUp.png)
 

wiki/MCP-Tools-and-Resources.md

@@ -148,8 +148,8 @@ Requires `budget:read` or `budget:write` scope. Budget addon must be enabled.
 | `toggle_budget_member_paid` | Mark or unmark a member as having paid their share. |
 | `get_settlement_summary` | Each member's net balance and the suggested payments to settle shared expenses, in the trip's base currency. Call this before recording a settlement. |
 | `list_settlements` | List the recorded settle-up payments for a trip — who paid whom, how much, and when. |
-| `create_settlement` | Record a settle-up payment: one member paid another the given amount in the trip's base currency. |
-| `update_settlement` | Update a recorded settle-up payment (payer, recipient, and amount). |
+| `create_settlement` | Record a settle-up payment: one member paid another the given amount, with the payment's currency and the day it happened. |
+| `update_settlement` | Update a recorded settle-up payment (payer, recipient, amount, currency and the day it happened). |
 | `delete_settlement` | Delete a recorded settle-up payment. This is the undo for `create_settlement` and restores the affected balances. |
 
 ### Tags