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). The event's FAQ questions and seating charts are deleted with it. 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, any older gift records, 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). A negative `totalActual` (or category `actual`) means recorded refunds exceed payments: say so plainly, never call it spending. `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. `rsvpCanonical.notInvited` counts those guests (on no event's list yet: nobody has invited them) and `rsvpCanonical.invitedPending` the invited guests still owing a reply; `notInvited + invitedPending === rsvpCanonical.noResponse`. For guests who haven't replied, lead with `rsvpCanonical.invitedPending`. `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. A negative budget total (`budget.spent`, `budget.paid` or `budget.paymentsCleared`) means refunds exceed payments; say so plainly, never call it spending. Use this when the user asks "how is my wedding going?" or wants a general status update.

Fetch one wedding event: description, address, ceremony type, dress code, exact RSVP counts for this event, a dietary tally, and a SHORT guest list (default 20 rows). Use after list_events when the user drills into one event ("how many are coming to the sangeet?", "what's the dress code for mehndi?", "who declined the haldi?"). COUNTS: quote `rsvp.*` — exact over every invite, never the length of `guests`. `rsvp.headcount` = CONFIRMED invites; plus-ones are their own guest rows, already inside every count (`rsvp.plusOnes` says how many), so never add them on top. GUESTS: `guests` holds at most `guestLimit` rows; `guestsTruncated: true` means more match (`guestsMatching`) and `fullGuestList` says how to get them. Pass `rsvpStatus` to list only guests with that RSVP for THIS event (the counts stay whole-event), and `guestLimit: 0` when you only need details and counts. For a whole roster, use list_guests with this `eventId` (plus `rsvpStatus` for this event's RSVP) and `limit`, paging with `nextCursor`. A row with `nameUnknown: true` is an unnamed plus-one: call them "Guest of {plusOneOf.name}". 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 and dietary preferences. 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. `address` is the guest's own postal address ({street, apt, city, stateProvince, postalCode, country}) or null; a household address shared by family members is not included here. `gifts` is read-only history from before gift tracking was retired: Anvaya cannot record, log or track gifts, so never offer to.

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 / haven't replied yet" questions, ALWAYS quote `canonical.attending` / `canonical.responded` / `canonical.invitedPending` (invited guests still owing a reply; `canonical.noResponse` on a result without it). `canonical.notInvited` guests are on no event's list yet: never call them silent or suggest reminding them; mention them separately. The card's headline shows `canonical.attending`, `canonical.tentative`, `canonical.notAttending` and `canonical.invitedPending` (as "No response") exactly as returned, with `canonical.notInvited` under it as not invited to an event yet, and its per-event rows show `events[]`, 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, and splits into `canonical.notInvited` (on no event's list yet: nobody has invited them) and `canonical.invitedPending` (invited to at least one event and still owing a reply). `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. A negative `quote` is legacy data from before quotes were validated: say it needs re-entering, and never treat it as a discount or the lowest price. 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. A negative `estimated` is legacy data from before estimates were validated: say it needs re-entering. `payments[].amount` is negative only for an ADJUSTMENT that lowered the paid total. 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, invitation, saveTheDate (Save the Date reply funnel), eventId, eventName, groupId, search (first, last or full name in either order, or email). RSVP filter, two meanings: WITH an event filter (`eventId` or `eventName`), `rsvpStatus` matches the guest's RSVP for THAT event ("who declined the Sangeet?" → `{ eventId, rsvpStatus: "DECLINED" }`). WITHOUT one it is the per-guest status across all events, matching the dashboard buckets (CONFIRMED = confirmed for every invite; PENDING includes guests with no invites yet). Invitation filter (across all events): `invitation: "awaiting-reply"` lists the guests invited to at least one event who still owe a reply, the people an RSVP reminder is for (count = get_rsvp_summary `canonical.invitedPending`); `invitation: "not-invited"` lists the guests on no event's list yet (count = `canonical.notInvited`). `rsvpStatus: "PENDING"` without an event also returns guests nobody has invited. 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` + `cursor` (pass back each `nextCursor` until it is null); only page on when the user needs the names, not to count. Counting: pass `countOnly: true` for an exact `{ count }` — never count rows client-side. ALWAYS PAGED: every call returns `{ items, nextCursor, total, _eventMatch? }` with at most `limit` rows (default 50, max 200), even with no filters. `total` is the exact match count across all pages, so quote it rather than `items.length`; `countOnly: true` returns just `{ 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 `total` (or a `countOnly` 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. A negative `quote` is legacy data from before quotes were validated: say it needs re-entering, and never treat it as a discount or the lowest price. 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.