Anvaya

Create a new blank DRAFT budget scenario with no categories or items. Use when the user wants to start a fresh "what-if" budget from scratch. To clone the active scenario instead (carrying over categories, items, vendor alternatives, and funding sources), use snapshot_budget.

Create a new guest group for organizing guests into families or social circles. Group names are unique per wedding (case-insensitive); attempting to reuse an existing name throws. Use when the user says "create a group for the Sharma family" or "group my college friends".

Delete one or more budget categories from the specified scenario (defaults to the active scenario). Pass a single name for a plain delete, or multiple names with reassignToCategoryName to MERGE duplicates (items are re-parented into the target; allocated amounts sum into the target; sources are deleted). Without reassignToCategoryName, items in the sources are cascade-deleted along with the category — refuses if any have completed payments unless allowItemsWithPayments=true. Source names are resolved case-insensitively and one name MAY match multiple categories (the duplicate-cleanup case). The reassign target must resolve to exactly one category. Requires FAMILY_ADMIN. Returns { deletedCount, deletedNames, unmatchedNames, itemsReassigned, itemsDeleted, allocatedMerged, scenarioId, target }.

Delete a budget line item from the active scenario. Refuses to delete items with completed payments — clear those first. Requires FAMILY_ADMIN. ALWAYS pass `title` (the exact line item name from a prior list_budget_items call) so the confirmation card can show "Delete budget item: Catering deposit" instead of an opaque slug ID.

Delete a budget scenario. Cannot delete the currently active scenario.

Delete a comment (soft-delete via deletedAt). Permitted for the original author or any FAMILY_ADMIN+ member. Returns 'Comment not found' for unknown IDs, comments belonging to a different wedding, already-deleted comments, or comments the caller is not allowed to delete (existence is masked to prevent cross-author leakage). The corresponding activity-feed entry is hidden.

Permanently delete a wedding event and all its guest assignments (the `GuestEvent` join rows are removed in the same transaction). Use when the user explicitly asks to remove or cancel an event. Requires FAMILY_ADMIN. ALWAYS pass `name` (the exact event name from a prior list_events / get_event call) so the confirmation card can show "Delete event: Sangeet" instead of an opaque slug ID.

Delete a single guest. Cascades to their event invites, RSVPs, gifts, broadcast deliveries, seat assignments, intake responses, and conversations. Comments authored about the guest are soft-deleted. Requires FAMILY_ADMIN. For bulk delete use delete_guests. ALWAYS pass `name` (the exact guest name from a prior list_guests / get_guest call) so the confirmation card can show "Delete guest: Priya Kapoor" instead of an opaque slug ID — required for the user to verify the right guest before applying.

Delete a guest group. Guests in the group are NOT deleted — their `groupId` is detached (set to null) before the group itself is removed (the schema declares `Guest.groupId` as a nullable foreign key with `onDelete: SetNull`). Returns `{ success, deletedId, removedName, detachedGuests }` so the caller can surface how many guests were ungrouped. Requires FAMILY_ADMIN.

Bulk-delete guests. Returns `{ deleted, notFoundIds }` so the caller can tell the user which IDs were ignored (e.g. wrong wedding or already deleted). Cascade rules and audit logging match `delete_guest`. Requires FAMILY_ADMIN. ALWAYS pass `names` (parallel array of guest display names, one per guestId in order) so the confirmation card can render human-readable targets instead of opaque slug IDs.

Delete a single task. Requires FAMILY_ADMIN. For multi-delete use delete_tasks. ALWAYS pass `title` (the exact task title from a prior list_tasks call) so the confirmation card can show "Delete task: Buy a unicorn" instead of an opaque slug ID — required for the user to verify the right task before applying.

Bulk-delete tasks. Returns `{ deleted, notFoundIds }` so the caller can tell the user which IDs were ignored (e.g. wrong wedding or already deleted). Requires FAMILY_ADMIN. ALWAYS pass `titles` (parallel array of task titles, one per taskId in order) so the confirmation card can render human-readable targets instead of opaque slug IDs.

Permanently delete a vendor and its directly-owned data (attachments, email threads/drafts, vendor alternatives, packages, vendor comments, and any payment rows that hang off the vendor alone). Scenario items remain — only the vendor alternative + any active selection are removed. Budget money is preserved: payments linked to a budget item are re-anchored to that item, so no line's `actual` and no "Spent" total changes. Requires FAMILY_ADMIN. Use when the user says "remove this vendor" or "delete [vendor]". ALWAYS pass `name` (the exact vendor name from a prior list_vendors / get_vendor call) so the confirmation card can show "Delete vendor: Saffron Lens Photography" instead of an opaque slug ID.

Edit an existing comment's body. Permitted for the original author or any FAMILY_ADMIN+ member. Returns 'Comment not found' for unknown IDs, comments belonging to a different wedding, soft-deleted comments, or comments the caller is not allowed to edit (existence is masked to prevent cross-author leakage).

Get the active scenario budget overview. Returns: `totalBudget` (the cap the user set); `totalAllocated` (sum of `ScenarioCategory.allocated` — the per-category bucket caps the user has divvied out; this is the number shown in the dashboard Allocated card AND the BudgetArtifact header). `totalEstimated` (sum of line-item estimates inside those categories — equals totalAllocated when every category is fully itemised but can diverge when items don't cover the bucket). `totalActual` (sum of `ScenarioItem.actual` — money actually PAID, i.e. the sum of completed payment records; this is the dashboard's "Spent" widget AND the BudgetArtifact's "Paid to date" column). `totalPaid` ALIASES `totalActual`: both equal `sum(ScenarioItem.actual)` so this surface agrees with the dashboard bento, SummaryStrip, and BudgetArtifact. Quote either, but prefer `totalActual` because the field name is unambiguous. `totalPaymentsCleared` (sum of `VendorPayment.amount` where `paidDate IS NOT NULL`, over the same scenario's items). Since the 2026-07-27 payments cutover the payment ledger IS `ScenarioItem.actual`, so `totalPaymentsCleared`, `totalActual` and `totalPaid` are the SAME number by construction — they can never disagree. NEVER narrate a gap between "committed" and "cleared": there is none. The field is kept only for wire compatibility; prefer `totalActual` in every answer. `totalCommitted` (booked-but-unpaid: items with a vendor selection, no actual spend yet, and no recorded payment). **Header alignment (S2-8):** the artifact card header reads "$totalAllocated allocated of $totalBudget". When you reference the overall budget position in prose, use `totalAllocated` (NOT `totalEstimated`) so your wording matches the card. Use `totalEstimated` only when the user explicitly asks about line-item totals separately. **Paid-to-date alignment (S2-6):** when the user asks "how much have I paid?" or "how much have I spent?", quote `totalActual` (matches the dashboard "Spent" card AND the artifact "Paid to date" strap). `totalPaid` and `totalPaymentsCleared` return the identical number — quote one figure, not three. `unbudgeted` (= totalBudget - totalEstimated — how much of the cap is still un-allocated to line items; "how much can I still plan for?"). `unspent` (= totalBudget - totalActual — room left against money already paid). `currency` (ISO code, defaults to "USD"); plus a per-category breakdown with allocated vs estimated vs actual vs paid vs paymentsCleared (these last three are the same number per category) vs committed. Each money field is also emitted as a `*Display` 2-decimal string ("750.50") to avoid float trimming on the client. Pass `scenarioId` to scope to a non-active scenario; omit for the active one. Use when the user asks "how is my budget?" or "what have I spent?".

Get a wedding overview including guest count, RSVP statistics, budget summary, vendor count, upcoming events, and near-due tasks. The returned `rsvp` object is per-GUEST (not per-invite) and always reconciles: `rsvp.PENDING + rsvp.CONFIRMED + rsvp.MAYBE + rsvp.DECLINED === guests.total`. Guests with no event invites at all are bucketed as PENDING (they have not responded yet). `overdueTasks` / `upcomingTasks` are the TOP 5 by due date; cite the real count from `overdueTotal` / `upcomingTotal` when talking to the user — never report the array length as the authoritative number. Use this when the user asks "how is my wedding going?" or wants a general status update.

Fetch a single wedding event with full detail: description, address, ceremony type, dress code, and the full list of assigned guests with their RSVP status. Use after list_events when the user drills into one event ("who's coming to the sangeet?", "what's the dress code for mehndi?"). Time fields: `date` is UTC midnight on the event's calendar day (do NOT naively format — US/CA clients render the previous day); `time` is a free-text label like "4:00 PM"; `dateISO` is an ISO-8601 string composed in the wedding's IANA timezone (default America/New_York) and is the field clients should display or parse.

Get detailed information about a specific guest including their events, RSVP status, dietary preferences, and gifts. Use when the user asks about a specific person. `plusOneOf` is non-null when this guest is somebody else's plus-one (and `nameUnknown: true` means their name hasn't been captured — say "Guest of {plusOneOf.name}"). This returns ONE person; for a guest's whole party, use `list_guests` and keep the rows whose `plusOneOf.guestId` is this guest.

Get RSVP breakdown for each wedding event AND a wedding-wide per-guest summary, plus dietary aggregates. PRIMARY HEADLINE = `canonical` block. For "how many attending / replied / not responded yet" questions, ALWAYS quote `canonical.attending` / `canonical.responded` / `canonical.noResponse`. The CARD the user sees renders from `canonical`, so your prose MUST match. Canonical semantics (multi-event aware): `canonical.attending` = guests with ≥1 CONFIRMED invite (the "going to your wedding" headcount). `canonical.tentative` = ≥1 MAYBE and zero CONFIRMED. `canonical.notAttending` = every invite DECLINED. `canonical.noResponse` = all PENDING or no invites. `canonical.responded = attending + tentative + notAttending`. `summary` (legacy) is a STRICTER per-guest bucketing — `summary.confirmed` only counts guests where EVERY invite is CONFIRMED, so it is often dramatically smaller than `canonical.attending` in multi-event weddings. Do NOT lead with `summary.confirmed` when the user asks "how many attending" — that contradicts the card. Reach for `summary.*` only when the user explicitly asks "how many guests are confirmed to ALL events" or for parity with the dashboard `get_dashboard.rsvp` tile. `events[]` is per-INVITE (each guest × each event = one row). Use `events[i].pending` only when reporting on a single named event; never sum across events (double-counts). Use when the user asks about RSVPs, headcount, or who has responded.

Get detailed vendor information including attachments, quote, and linked budget item. Use when the user asks about a specific vendor.

Get an activity stream (comments + status changes). Pass entityType+entityId to scope to one entity (vendor, guest, task, etc.). Omit them to get wedding-wide recent activity. entityType alone (without entityId) acts as a wedding-wide filter. The output may also include COMMENT, BUDGET_SCENARIO, and WEDDING entries — all valid filter values.

List budget line items from a scenario (defaults to the active one), optionally filtered by category name. Each row exposes money fields with distinct meanings: `estimated` = budget allocation (what you PLAN to spend on this line); `actual` = money actually paid on this line — the sum of its completed payment records (`vendorPayments[].amount` where `paidDate IS NOT NULL`). The payment ledger IS this number: recording a payment raises it, unmarking one lowers it, and editing "Actual (paid)" in the app writes a payment entry to match. `paid` = the same number as `actual`, by construction — they can never disagree. Use the derived `paymentStatus` field and its friendly sibling `paymentStatusLabel` to describe payment state rather than computing it from raw amounts. Because `paid` and `actual` are the same number, the status compares money PAID against the line's PLANNED cost: "unbudgeted" = nothing planned and nothing paid; "unpaid" = a plan exists but nothing is paid; "partial" = paid is short of `estimated`; "paid" = paid has reached or passed `estimated`. To say how a line is tracking against plan, compare `actual` with `estimated` (over/under budget) — never `actual` with `paid`. Each money field also has a `*Display` 2dp string. Vendor alternatives + payments are nested. Output enums carry sibling labels: prefer `paymentStatusLabel`, `payments[].typeLabel` in user-facing prose. For "who is paying", use `fundingSource.name` (e.g. "Sharma Family") — null means unassigned. Pass `scenarioId` to inspect a specific scenario without activating it.

List all budget scenarios with their status (ACTIVE, DRAFT, ARCHIVED), total budget, and category count. Shows which one is currently active. Use when the user asks about budget what-if scenarios.

List wedding events (ceremonies, receptions, etc.) with dates, locations, and guest counts. Use for "what's on the schedule?", "show me the mehndi events", or to find an event ID before another action. Time fields: `date` is UTC midnight on the event's calendar day (do NOT naively format — US/CA clients render the previous day); `time` is a free-text label like "4:00 PM"; `dateISO` is an ISO-8601 string composed in the wedding's IANA timezone (default America/New_York) and is the field clients should display or parse.

List all guest groups (families, friend groups, etc.) with member counts. Use when the user asks about guest groups or families.

List wedding guests. Filters: side, tag, rsvpStatus (per-guest — PENDING includes guests with no invites yet), saveTheDate (soft-RSVP funnel), eventId, eventName, groupId, search (name + email). Event filter: use `eventId` when you already have the cuid; use `eventName` for human-readable lookups like "Reception" or "Mehndi" — it does a case-insensitive substring match against `WeddingEvent.name` and returns guests across ALL matching events (envelope includes `_eventMatch.resolvedTo` so you can confirm what was matched). Either filter accepted; pass both to OR them together. Pagination: `limit` (default 50, max 200) + `cursor` (the `nextCursor` from a previous call). Counting: pass `countOnly: true` for an exact `{ count }` — never count rows client-side. Returns a raw `Guest[]` for unfiltered calls; with any of `cursor`/`limit`/`search`/`groupId`/`eventName` it returns `{ items, nextCursor, _eventMatch? }`; with `countOnly` it returns `{ count, _eventMatch? }`. Output enums carry sibling labels: prefer `sideLabel` over `side`, `events[].rsvpStatusLabel` over `events[].rsvpStatus` in user-facing prose. SAVE THE DATE: every row carries `saveTheDateState` — `not_sent` | `awaiting` (sent, no reply) | `viewed` | `responded` | `covered_by_host`. `covered_by_host` is a contactless plus-one reached through their host's card: they are NOT missing a send and must never be counted as one or nudged. PLUS-ONES: they are ordinary rows in this list — a row with `plusOneOf: { guestId, name }` is that person's plus-one, and a null `plusOneOf` means they are not. So the row count IS the headcount; never add plus-ones on top of it, and describe them as a composition ("310 guests · 11 plus-ones"). A row with `nameUnknown: true` has no name captured yet — call them "Guest of {plusOneOf.name}", never by the placeholder in `firstName`. To see one guest's party, filter this list for rows whose `plusOneOf.guestId` is that guest. Use when the user asks about their guest list, who is invited, or who matches a filter.

List all wedding team members with their roles (COUPLE_PRIMARY, FAMILY_ADMIN, FAMILY_CONTRIBUTOR, GUEST). Each row includes an `isSelf` flag so callers can identify the authenticated user. Prefer `roleLabel` ("Couple (primary)", "Family admin", "Family contributor", "Guest") over the raw `role` token in user-facing prose. Audit r4 P14 caught the model rendering "COUPLE_PRIMARY" directly to users. Use when the user asks "who has access?" or "list collaborators".

List active planning intelligence signals for the wedding. Signals are AI-generated insights about budget risks, timeline conflicts, vendor gaps, guest patterns, and milestone celebrations. Filter by category or severity (one of: critical, warning, info, suggestion, celebration). Set format="summary" to get a per-severity breakdown plus the full list (use this when the user asks "how is my wedding planning going?" or "any issues I should know about?"); the default format="list" returns just the filterable raw list.

List wedding planning tasks. Filters: status (TODO/IN_PROGRESS/DONE), priority (NORMAL/HIGH), category, eventId, assignee (id/name/email), dueBefore/dueAfter (ISO-8601), overdue, search (title + description). Returns `{ total, byStatus: { TODO, IN_PROGRESS, DONE }, tasks: [...] }`. When the user asks for counts ("how many tasks?", "X total"), QUOTE `total` and `byStatus.*` VERBATIM — do not re-count or sum the `tasks` array yourself. Output enums carry sibling labels: prefer `statusLabel` ("To do" / "In progress" / "Done") over `status` and `priorityLabel` ("Normal" / "High") over `priority` in user-facing prose. Use for "what do I need to do?", "what's overdue?", or "tasks for the sangeet?".

List all wedding vendors. Can filter by status (RESEARCHING/CONTACTED/QUOTED/BOOKED/PAID/CANCELLED) or category (photography, catering, etc.). Output enums carry sibling labels: prefer `categoryLabel` (e.g. "Beauty Services") over `category` (`beauty_services`) and `statusLabel` (e.g. "Researching") over `status` (`RESEARCHING`) in user-facing prose. Audit r4 P14 caught the model echoing snake_case / SCREAMING_SNAKE tokens directly to users. Use when the user asks about their vendors.

Remove one or more guests from their current group (ungroup them). Returns `{ removed, notFoundIds, notInGroup }` where `notFoundIds` lists guest IDs not in this wedding and `notInGroup` lists ids that had no group to begin with (no-op).

Activate a budget scenario — demotes the current active scenario to DRAFT and promotes the target to ACTIVE.

Set the total budget on the active scenario. Use when the user says "our total budget is $X".

Clone the active budget scenario as a new DRAFT. Copies all categories, items, vendor alternatives, and funding sources. Use when the user says "save the current budget" or "create a what-if copy".

Remove one or more guests from a single event (inverse of assign_guests_to_events for one event). Returns `{ unassigned, notFoundIds }` where `notFoundIds` are guests that were never assigned (or do not belong to this wedding). Idempotent. ALWAYS pass `guestLabels` (parallel to guestIds) and `eventLabel` (the single event's name) so the confirmation card shows real names ("Remove Priya Kapoor from Reception") instead of opaque IDs — copy them verbatim from the prior list_guests / list_events results.

Clear `paidDate` on a scheduled vendor payment so it returns to the "unpaid / due" state. Inverse of marking a payment as paid via the web UI. **This moves money.** Since the 2026-07-27 payments cutover the paid ledger IS `ScenarioItem.actual`, so unmarking a payment LOWERS the linked budget item's `actual` (and the wedding's "Spent" / "Paid to date" totals) by that amount, in the same transaction. Say so before you call it, and confirm with the user when the amount is material. Only scheduled rows can be unmarked: an ADJUSTMENT ("Recorded payment") row is rejected with "Recorded payments can't be marked unpaid — delete the entry instead." Idempotent: clearing an already-unpaid payment returns `{ success: true, alreadyUnpaid: true }` and writes no audit entry. Use when the user says "undo the mark-paid on the catering deposit" or "I clicked that by mistake".

Update a budget line item in the active scenario — change the name, amounts, funding source, notes, or move it to another category. At least one updatable field must be provided; an empty patch is rejected.

Update an existing event's details (name, date, location, dress code, etc.). Time fields: `date` is UTC midnight on the event's calendar day (do NOT naively format — US/CA clients render the previous day); `time` is a free-text label like "4:00 PM"; `dateISO` is an ISO-8601 string composed in the wedding's IANA timezone (default America/New_York) and is the field clients should display or parse.

Update one or more guests' information — including their plus-ones. Two modes: (1) per-row patches via `updates: [{guestId, ...patch}, ...]` when guests need different changes ("update Priya's email and Arjun's phone", "let Priya bring her husband Raj"); (2) bulk shorthand via `guestIds + patch` when applying the same patch to many ("tag all college friends as 'family'", "move these 12 to bride's side"). Provide exactly one mode. Best-effort partial-failure: per-row failures don't abort the rest. Note: `tags` REPLACES the existing tag set; for additive tagging, fetch via list_guests first and merge client-side. The `name` back-compat field splits on the LAST whitespace (matches add_guests). PLUS-ONES (per-row `updates` mode only): `plusOnes` is the FULL desired party for that guest and REPLACES it. Plus-ones are ordinary guest rows — read the current party from `list_guests` and keep every row whose `plusOneOf.guestId` is this guest, passing each back by its `guestId`. ⚠️ DESTRUCTIVE: leaving an existing plus-one out of the list DELETES that guest along with their RSVPs and their seat. Confirm with the user before shrinking a party. ALWAYS pass `guestLabel` on each `updates` row (or `guestLabels` parallel to the bulk `guestIds`) so the confirmation card shows real names ("Update Priya Kapoor") instead of opaque IDs — copy them verbatim from the prior list_guests result.

Update one or more guests' RSVP for specific events. Pass an array of {guestId, eventId, status, ...} rows. Valid `status` values: PENDING, CONFIRMED, DECLINED, MAYBE. Bad statuses, missing guests, or missing events are surfaced as per-row failures (not a whole-call rejection) so a 5-row batch with one bad row still applies the other four — matches the per-row semantics of `update_guests` (audit Bug 25). Use when the user says "mark these 5 as confirmed for the reception" or a single guest declines. ALWAYS pass `guestLabel` and `eventLabel` on every row so the confirmation card shows real names ("Mark Priya Kapoor as Confirmed for Reception") instead of opaque IDs — copy them verbatim from the prior list_guests / list_events results.