Begin the Deferno authentication flow.

Returns a URL for the user to open in their browser. The user authenticates via the OIDC provider, then sees a short code to paste back here.

NOTE: In HTTP transport with OAuth enabled, authentication is handled automatically by the transport layer. This tool is only needed for stdio/CLI transport.

Finish authentication by exchanging the browser code for a token.

session_id comes from the start_auth response. code is the short code the user copied from their browser after signing in via the OIDC provider.

NOTE: In HTTP transport with OAuth enabled, authentication is handled automatically. This tool is only needed for stdio/CLI.

Log out and remove saved credentials.

Return the currently authenticated Deferno user.

Call this first to confirm that the Authorization header is valid before issuing task operations.

Return the user's settings blob (theme, done-visibility, etc.).

Patch user settings. Omitted fields stay unchanged.

Create a new task.

complete_by must be an ISO-8601 UTC timestamp. parent_id attaches the new task as a child of an existing task. productive and desire are floats in [0, 1] representing how productive this task feels and how much the user wants to do it. recurrence sets a repeat schedule. Use {"type": "daily"}, {"type": "every_n_days", "n": 3}, or {"type": "weekly", "days": ["Mon", "Wed", "Fri"]}. recurring_type controls behavior when a recurring task is missed. Must be one of "chore" (lingers until done, default), "habit" (fresh start each day), or "event" (time-bound, can't be made up). Only meaningful when recurrence is set.

v0.2 optional field:

• occurrence_id: when this Task is a materialized subtask of a recurring entity's occurrence, the Occurrence id it belongs to. Normal tasks omit this field.

Patch mutable fields on a task.

task_id accepts any reference form — UUID, sequence shorthand (#123, personal-org only), canonical ref (acme-123), or app URL — and is resolved to a UUID before the update.

status must be one of open, in-progress, in-review, done, dropped, pruned. The backend rejects completing a task while any of its children are still active.

Pass None explicitly to clear a field (e.g. complete_by=None removes the deadline). Omitting a parameter leaves it unchanged.

recurrence sets or clears a repeat schedule (see create_task).

recurring_type can be "chore", "habit", or "event" (see create_task for details). Pass None to clear.

For recurring tasks, if you change title, description, labels, or complete_by, you MUST also provide recurring_scope: "this" (single instance), "following" (this and future), or "all" (entire series). "this" and "following" also require recurrence_id (the ISO start time of the instance). If the task is recurring and scope is missing, the call will fail with a message asking you to specify the scope — ask the user which option they prefer.

v0.2 optional field:

• occurrence_id: when this Task is a materialized subtask of a recurring entity's occurrence, the Occurrence id it belongs to. Normal tasks omit this field.

Convenience wrapper around update_task for status changes.

task_id accepts any reference form — UUID, sequence shorthand (#123, personal-org only), canonical ref (acme-123), or app URL.

Accepts open, in-progress, in-review, done, dropped, pruned.

Move a task to a different parent or reorder within its current parent.

task_id and new_parent_id each accept any reference form — UUID, sequence shorthand (#123, personal-org only), canonical ref (acme-123), or app URL — and are resolved to UUIDs before the move.

new_parent_id=None detaches the task to root level (kept as-is, not resolved). position is the insertion index in the target's children list (0 = first). Omit to append at end.

Decompose a task into two child tasks while preserving the parent.

task_id accepts any reference form — UUID, sequence shorthand (#123, personal-org only), canonical ref (acme-123), or app URL.

Returns the updated parent and both new children.

Insert a new next-step task directly after task_id in the sequence.

task_id accepts any reference form — UUID, sequence shorthand (#123, personal-org only), canonical ref (acme-123), or app URL.

Preserves any existing downstream chain. Returns the original task and the newly created next task.

Roll the active children of a task back into the parent.

task_id accepts any reference form — UUID, sequence shorthand (#123, personal-org only), canonical ref (acme-123), or app URL.

Child content is appended to the parent description; the children are marked as pruned but remain recoverable. Pass the id of any child whose parent should receive the merge.

Return the user's historical mood-per-task log for finished tasks.

Export all user data as JSON.

Returns a complete backup of all tasks (with full history, mood vectors, recurrence rules), root ordering, and daily plans. The export can be imported via the Deferno web UI settings page.

Hard-delete a task by id.

task_id accepts any reference form — UUID, sequence shorthand (#123, personal-org only), canonical ref (acme-123), or app URL. The returned task_id is the resolved UUID the deletion ran against.

Calendar view of tasks (recurring expansions + due dates).

start and end are YYYY-MM-DD strings; end is exclusive. tz is an optional IANA timezone for local-midnight alignment.

Import an ExportData blob produced by export_data.

data should be the full ExportData object (with keys tasks, events, habits, chores, root_order, daily_plans). Pass an empty dict to dry-run.

Promote a personal-org task into a target org.

Moves the task from the caller's personal org into target_org_id, re-encrypting it under the target org's data-encryption key. The caller must own the task in their personal org AND be a member of target_org_id. Returns JSON null on success (the backend returns no body).

Execute multiple task operations atomically in a single call.

operations is a list of operation objects. Each must have an op field ("update" or "move") and a task_id.

Update operations accept the same fields as update_task (title, description, status, labels, etc.) at the top level alongside op and task_id.

Move operations accept new_parent_id (UUID or null for root) and an optional position (insertion index).

All operations succeed or none do (all-or-nothing). On success returns {"tasks": [...]}, the list of all modified tasks.

Batch-presign S3 PUT URLs for files to attach to a task.

task_id accepts any reference form — UUID, sequence shorthand (#123, personal-org only), canonical ref (acme-123), or app URL — and is resolved to a UUID before presigning.

files is a list of {filename, content_type, size_bytes} records (the wire keys match the backend PresignRequest struct — no serde renames). The server enforces a 25 MB per-file cap and a blocked-MIME list; violations return 400. Returns a list of {attachment_id, put_url, expires_at} records — the caller PUTs each blob to its url before invoking commit_task_attachments.

Commit presigned intents and/or url-provider entries to a task.

task_id accepts any reference form — UUID, sequence shorthand (#123, personal-org only), canonical ref (acme-123), or app URL — and is resolved to a UUID before the commit.

intents is a list of attachment_ids returned by a prior presign call. urls is a list of {url, filename?} records for the url-provider (no upload). At least one must be non-empty. Returns the full attachments Vec post-commit.

List a task's attachments. Returns the AttachmentView wire shape: {id, provider, filename, mime, size, created_at, created_by, url}. For provider=s3 records, url is a freshly-signed GET URL.

task_id accepts any reference form — UUID, sequence shorthand (#123, personal-org only), canonical ref (acme-123), or app URL — and is resolved to a UUID before the lookup.

Delete a single attachment from a task.

task_id accepts any reference form — UUID, sequence shorthand (#123, personal-org only), canonical ref (acme-123), or app URL — and is resolved to a UUID before the delete. att_id is an attachment id (not an item reference) and is passed through unresolved.

Create a recurring chore that lingers until done.

Chores differ from habits in that an unfinished occurrence carries forward (Missed/InProgress) rather than resetting each period. complete_by should be the first scheduled date as ISO-8601. recurrence follows the same shape as Task: {"type": "daily"}, {"type": "every_n_days", "n": 3}, or {"type": "weekly", "days": ["Mon", "Wed"]}.

v0.2 optional fields:

• cadence_mode: "rolling" (default; the next occurrence is computed from the actual completion time) or "fixed" (the next occurrence is anchored to the original schedule, ignoring completion delay).

• deadline_time_of_day: "HH:MM" time-of-day deadline within scheduled_date (user's TZ). Defaults to end-of-day.

• subtask_template: a list of subtask shapes that materialize as child Tasks on each occurrence. Empty list (default) means no template.

Patch mutable fields on a chore. Omitted fields stay untouched.

chore_id accepts any reference form — UUID, sequence shorthand (#123, personal-org only), canonical ref (acme-123), or app URL — and is resolved to a UUID before the patch.

complete_by cannot be cleared on chores. Pass new value to shift the schedule. Updating recurrence rotates the chore's series ID so prior occurrences remain attached to the old definition.

v0.2 optional fields:

• cadence_mode: "rolling" (default; the next occurrence is computed from the actual completion time) or "fixed" (the next occurrence is anchored to the original schedule, ignoring completion delay).

• deadline_time_of_day: "HH:MM" time-of-day deadline within scheduled_date (user's TZ). Defaults to end-of-day.

• subtask_template: a list of subtask shapes that materialize as child Tasks on each occurrence. Empty list (default) means no template.

Archive (soft-delete) a chore.

chore_id accepts any reference form — UUID, sequence shorthand (#123, personal-org only), canonical ref (acme-123), or app URL — and is resolved to a UUID before the delete.

List derived occurrences for a chore in the given date window.

chore_id accepts any reference form — UUID, sequence shorthand (#123, personal-org only), canonical ref (acme-123), or app URL — and is resolved to a UUID before the lookup.

Each occurrence has a status: Scheduled, Missed, InProgress, Skipped, DoneOnTime, or DoneLate. Dates use YYYY-MM-DD; range is inclusive on both ends.

Set the status of a single chore occurrence.

chore_id accepts any reference form — UUID, sequence shorthand (#123, personal-org only), canonical ref (acme-123), or app URL — and is resolved to a UUID before the status change.

status is the action to apply: one of "in_progress", "done", or "dropped" (alias: "skipped" for legacy callers). date is YYYY-MM-DD.

Note: Done resolves on the server to either DoneOnTime or DoneLate based on the occurrence's complete_by.

Apply status to the earliest unresolved occurrence of a chore.

chore_id accepts any reference form — UUID, sequence shorthand (#123, personal-org only), canonical ref (acme-123), or app URL — and is resolved to a UUID before marking the occurrence.

Useful for the common "I just did the dishes" case where the user doesn't want to look up which date is overdue. 404 if no unresolved occurrence exists.

status is the action to apply: one of "in_progress", "done", or "dropped" (alias: "skipped" for legacy callers).

Note: Done resolves on the server to either DoneOnTime or DoneLate based on the occurrence's complete_by.

Move a single chore occurrence to new_date without touching the cadence.

chore_id accepts any reference form — UUID, sequence shorthand (#123, personal-org only), canonical ref (acme-123), or app URL — and is resolved to a UUID before the reschedule. date and new_date are YYYY-MM-DD occurrence dates, not item references.

NOTE (v0.2): the backend returns 501 today for chores (legacy storage); the tool is exposed for forward compatibility. Once the chore storage is migrated, this becomes the SCOPE-010 path.

Create a recurring habit that resets each period.

Habits differ from chores in that an unfinished occurrence does not carry forward — each period gets a fresh start. recurrence follows the same shape as Task: {"type": "daily"}, {"type": "every_n_days", "n": 3}, or {"type": "weekly", "days": ["Mon", "Wed"]}.

v0.2 optional fields:

• deadline_time_of_day: "HH:MM" time-of-day deadline (user's TZ).

• subtask_template: list of subtask shapes materialized per occurrence.

Patch mutable fields on a habit. Omitted fields stay untouched.

habit_id accepts any reference form — UUID, sequence shorthand (#123, personal-org only), canonical ref (acme-123), or app URL — and is resolved to a UUID before the patch.

v0.2 optional fields:

• deadline_time_of_day: "HH:MM" time-of-day deadline (user's TZ).

• subtask_template: list of subtask shapes materialized per occurrence.

Archive (soft-delete) a habit.

habit_id accepts any reference form — UUID, sequence shorthand (#123, personal-org only), canonical ref (acme-123), or app URL — and is resolved to a UUID before the delete.

List occurrences for a habit in a date window.

habit_id accepts any reference form — UUID, sequence shorthand (#123, personal-org only), canonical ref (acme-123), or app URL — and is resolved to a UUID before the lookup.

Dates use YYYY-MM-DD; range is inclusive on both ends.

Mark a habit occurrence as done or not-done.

habit_id accepts any reference form — UUID, sequence shorthand (#123, personal-org only), canonical ref (acme-123), or app URL — and is resolved to a UUID before marking the occurrence.

date is YYYY-MM-DD; defaults to today on the server side.

Clear an explicitly-marked habit occurrence at date (YYYY-MM-DD).

habit_id accepts any reference form — UUID, sequence shorthand (#123, personal-org only), canonical ref (acme-123), or app URL — and is resolved to a UUID before clearing the occurrence.

Move a single habit occurrence to new_date without touching the cadence.

habit_id accepts any reference form — UUID, sequence shorthand (#123, personal-org only), canonical ref (acme-123), or app URL — and is resolved to a UUID before the reschedule. date and new_date are YYYY-MM-DD occurrence dates, not item references.

NOTE (v0.2): the backend returns 501 today for habits (legacy storage); the tool is exposed for forward compatibility.

Create a time-bound event.

complete_by is the start time (ISO-8601). end_time (if provided) must be at or after complete_by.

v0.2 optional fields:

• subtask_template: list of subtask shapes materialized per occurrence.

Patch mutable fields on an event. Backend rejects end_time < complete_by.

event_id accepts any reference form — UUID, sequence shorthand (#123, personal-org only), canonical ref (acme-123), or app URL — and is resolved to a UUID before the patch.

v0.2 optional fields:

• subtask_template: list of subtask shapes materialized per occurrence.

Archive (soft-delete) an event.

event_id accepts any reference form — UUID, sequence shorthand (#123, personal-org only), canonical ref (acme-123), or app URL — and is resolved to a UUID before the delete.

List occurrences for an Event in a date range.

event_id accepts any reference form — UUID, sequence shorthand (#123, personal-org only), canonical ref (acme-123), or app URL — and is resolved to a UUID before the lookup.

from_date / to_date are YYYY-MM-DD; both optional. Returns the unified-Occurrence shape (id, parent_id, scheduled_date, status, comment, attachments). Events never produce DoneLate.

Mark a single event occurrence with an action.

event_id accepts any reference form — UUID, sequence shorthand (#123, personal-org only), canonical ref (acme-123), or app URL — and is resolved to a UUID before the mark.

action is one of "in_progress", "done", "dropped" (alias: "skipped"). date is YYYY-MM-DD.

When the occurrence has materialized subtasks, cascade_subtasks=false (the default) causes a 409 if any subtask is non-terminal (SUBTASK-003). Pass cascade_subtasks=true to sweep them to the matching terminal status.

Clear an event occurrence row entirely (undo a prior mark).

event_id accepts any reference form — UUID, sequence shorthand (#123, personal-org only), canonical ref (acme-123), or app URL — and is resolved to a UUID before the clear.

date is YYYY-MM-DD. Returns {"ok": true} on success.

Move a single event occurrence to new_date without touching the RRULE.

event_id accepts any reference form — UUID, sequence shorthand (#123, personal-org only), canonical ref (acme-123), or app URL — and is resolved to a UUID before the reschedule.

The origin date's row is marked Dropped (with rescheduled_to=new_date); a fresh Scheduled row lands on the target date (with rescheduled_from=origin_date). 400 if new_date equals the origin date.

Batch-presign attachments for a specific event occurrence (date).

event_id accepts any reference form — UUID, sequence shorthand (#123, personal-org only), canonical ref (acme-123), or app URL — and is resolved to a UUID before presigning.

Each entry in files is {filename, content_type, size_bytes}. Server enforces 25 MB per-file cap, blocked-MIME list, and a max-attachments cap. Returns presigned PUT URLs with intent ids that commit_event_occurrence_attachments later consumes.

Commit intents and/or url-provider entries to an event occurrence.

event_id accepts any reference form — UUID, sequence shorthand (#123, personal-org only), canonical ref (acme-123), or app URL — and is resolved to a UUID before the commit.

intents are attachment ids returned by a prior presign call whose files have been PUT to S3. urls are url-provider entries {url, filename?}. 400 if both lists are empty.

List attachments on a specific event occurrence (date).

event_id accepts any reference form — UUID, sequence shorthand (#123, personal-org only), canonical ref (acme-123), or app URL — and is resolved to a UUID before the lookup.

Returns the AttachmentView shape: {id, provider, filename, mime, size, created_at, created_by, url}. url is a freshly signed GET for s3-backed entries.

Delete a single attachment from an event occurrence.

event_id accepts any reference form — UUID, sequence shorthand (#123, personal-org only), canonical ref (acme-123), or app URL — and is resolved to a UUID before the delete. att_id is the attachment id returned in the AttachmentView (not an item reference) and is passed through unresolved.

Returns {"ok": true} on success.

Append a new comment to an event occurrence (date).

event_id accepts any reference form — UUID, sequence shorthand (#123, personal-org only), canonical ref (acme-123), or app URL — and is resolved to a UUID before the comment is posted.

Multiple comments per occurrence are supported (PR-F). Returns the persisted Comment with id + created_at.

Edit the latest comment on an event occurrence (date).

event_id accepts any reference form — UUID, sequence shorthand (#123, personal-org only), canonical ref (acme-123), or app URL — and is resolved to a UUID before the edit.

Soft-delete the latest comment on an event occurrence (date).

event_id accepts any reference form — UUID, sequence shorthand (#123, personal-org only), canonical ref (acme-123), or app URL — and is resolved to a UUID before the delete.

Patch a comment's body or visibility.

Empty payload (no fields supplied) → backend returns 422.

Delete a comment owned by the caller.

List the caller's saved searches in their explicit order.

Save a search. query_string is the same syntax as search_items.

Patch a saved search's name or query string.

Delete a saved search.

Replace the saved-search ordering with the given full list of IDs.

List submitted feedback (admin only).

Return aggregate feedback statistics (admin only).

Update a feedback item's status / admin notes (admin only).

Fetch a single item (Task / Habit / Chore / Event) by any reference.

item accepts any Ref input form and is resolved transparently:

• a UUID (GET /items/{id});

• a Sequence shorthand -- #123 or bare 123. This resolves against your personal org only, by design. For an item in a shared org, name it by its Canonical ref (acme-123) or its App URL instead -- both resolve across orgs;

• a Canonical ref (slug-123, e.g. u-1y0e2v-123);

• an App URL (https://app.defernowork.com/o/{org_slug}/items/{seq-or-id});

• the unambiguous GitHub Alias owner/repo#N (it carries a /, so it can't be confused with a Canonical ref) -- auto-routed to the by-alias endpoint.

Deferno-# vs GitHub-# ambiguity. A bare #N always means a Deferno Sequence shorthand here; it is NOT inferred as a GitHub issue. Likewise an ambiguous string like ABC-223 collides with a Canonical ref and is therefore NOT auto-routed to alias resolution. Inferring which a user means from conversation is the job of a future context-adaptive classifier (see CONTEXT.md "Flagged ambiguities"), not this tool. Until then, use as_alias=true to force the alias path.

Args: item: Any Ref input form (or, with as_alias=true, a raw alias). full: When true, return the complete record (action history, comments, children, mood, attachments, ...) instead of the default compact projection. as_alias: When true, BYPASS the Ref classifier and look item up directly via GET /items/by-alias/{item}. This is the explicit escape-hatch for ambiguous external aliases (e.g. ABC-223) that the classifier deliberately will not auto-route. The unambiguous GitHub form owner/repo#N already routes to by-alias WITHOUT this flag.

Returns a compact projection by default (a small whitelist of fields, including description). Pass full=true for the complete record (action history, comments, children, mood, attachments, ...).

List items of any kind (Task / Habit / Chore / Event), windowed.

The canonical, bounded list view. Returns a Compact projection by default -- a small fixed field set per row (ref, kind, title, status, complete_by, parent_id, labels) with the heavy body (description) and raw id dropped -- so a query returns a trimmed set, not the entire working set in full detail.

Filters (composed into an OData $filter with and):

• kind -- one of "task", "habit", "chore", "event".

• status -- the item status (e.g. "open", "done").

• from_date / to_date -- YYYY-MM-DD; filter on complete_by widened to RFC3339 day boundaries (start-of-day for from_date, end-of-day for to_date).

An unknown / unfilterable field returns a backend 400, surfaced clearly (not swallowed).

• limit -- maps to OData $top. The backend caps $top at 500 by REJECTING larger values with a 400 (it does NOT clamp); the number is passed through verbatim.

• full=true -- return every field on each row (drops the projection).

• window="all" -- opt out of the default done-visibility window for full history (the default window applies only to the unfiltered call).

Regardless of projection, the backend always injects ref, org_slug, type and sequence into every row.

Full-text search over items, returning a Compact projection.

The compact, kind-neutral full-text search over items. Returns a Compact projection by default -- the same small fixed field set per row as list_items (ref, kind, title, status, complete_by, parent_id, labels) -- so the heavy body (description) and the raw id are dropped. Pass full=true for the rows verbatim.

Scope: full-text search currently covers Tasks only. This tool is backed by the Tasks search path (GET /tasks/search) because the backend has no kind-neutral /items/search endpoint today; a kind-neutral full-text search is a known backend follow-on (to be filed in the Deferno backend repo, out of scope for the MCP). Non-Task kinds (Habits / Chores / Events) are therefore not reached by query yet -- use list_items to enumerate those.

Args: query: Search query (min 2 characters). Searches title and description. status: Filter by status (open, in-progress, in-review, done, dropped). label: Filter by label tag. from_date: Filter items due on or after this ISO 8601 date. to_date: Filter items due on or before this ISO 8601 date. parent_id: Scope search to children of this item (UUID). full: When true, return every field on each row (no projection).

Calendar view across all item kinds (Task, Habit, Chore, Event).

start and end are YYYY-MM-DD; end is exclusive. tz is an optional IANA timezone for local-midnight alignment.

Daily plan across all item kinds (Task, Habit, Chore, Event).

Returns a polymorphic array — each entry has a kind discriminator. date defaults to today; tz is an optional IANA timezone.

Add an item (any kind) to the daily plan.

Remove an item from the daily plan.

Replace the daily plan ordering with the given full list of IDs.

Convert an item to a different kind (Task / Chore / Habit / Event).

item_id accepts any reference form — UUID, sequence shorthand (#123, personal-org only), canonical ref (acme-123), or app URL — and is resolved to a UUID before the conversion.

to is one of "task", "chore", "habit", "event" -- this is the backend wire field name (ConvertItemPayload.to). complete_by (RFC3339) is required when to is Event/Chore/Habit; recurrence is required when to is Habit/Chore (and optional for Event); end_time is Event-only. Returns the updated item view -- the backend uses 201 on a real conversion, 200 when to equals the current kind (idempotent).

Return the change-history list for any item kind (Task/Habit/Chore/Event).

item_id accepts any reference form — UUID, sequence shorthand (#123, personal-org only), canonical ref (acme-123), or app URL — and is resolved to a UUID before the history lookup.

Pin or unpin a sidebar item (Task/Habit/Chore/Event).

item_id accepts any reference form — UUID, sequence shorthand (#123, personal-org only), canonical ref (acme-123), or app URL — and is resolved to a UUID before the pin toggle.

Backend body is {pinned: bool} -- the gap-closure plan's optional label argument is not part of this endpoint (custom pin labels live on PATCH /tasks/pinned/{id}). Returns {"ok": true} on success (backend response is 204 NO_CONTENT).

List the user's sidebar-pinned items in display order.

Returns a JSON array of {task: TaskSummary, label: str | null} objects. The backend reconciles inconsistencies on every call — list entries whose underlying task is unpinned or deleted are dropped — so the result is always self-consistent and safe to render directly in the sidebar.

Replace the pinned-list ordering with task_ids.

task_ids must be an exact permutation of the user's current pinned set: extra ids, missing ids, or duplicates all 400. To add or remove an item, use set_item_pinned first, then reorder. Returns {"reordered": True, "count": N} on success.

Set or clear the custom sidebar label for a pinned task.

pinned_id is the underlying task UUID (the pinned list keys on task id; there is no separate pin-record id, hence the route /tasks/pinned/{id}). Pass label=None (or omit) to clear the label — this is the only way to clear it, so the body is always sent as {"label": label} including the JSON null. 404 if the task is not in the pinned list.

Return today's curated daily plan.

The plan auto-seeds from recurring tasks, carries forward incomplete items from yesterday, and includes any task/chore/event with a due date falling on the target date in the user's timezone.

Parameters

date : optional YYYY-MM-DD. Defaults to today in the user's timezone. If no timezone is known, defaults to UTC. tz : optional IANA timezone (e.g. "America/Los_Angeles"). Supply if you know the user's local timezone — Claude Desktop / Claude Code typically have this in the system prompt as locale info. Once supplied for the first time, the backend persists it as the user's preference, so future calls don't need to repeat it.

Add a task to the daily plan.

task_id is the UUID of an existing task. date defaults to today.

Remove a task from the daily plan.

task_id is the UUID of the task to remove. date defaults to today.

Replace the daily plan ordering with the given task ID list.

task_ids is the full ordered list of task UUIDs for the plan. date defaults to today.

Query calendar events for a date range.

Returns recurring task instances (expanded from RRULE schedules) plus one-off tasks with due dates in the range. start and end are YYYY-MM-DD strings.

Parameters

start : YYYY-MM-DD start of the window (inclusive). end : YYYY-MM-DD end of the window (exclusive). tz : optional IANA timezone (e.g. "America/Los_Angeles"). Supply if you know the user's local timezone — the backend uses it to align the day window boundaries with local midnight rather than UTC midnight.