BrightMind

Create BrightMind lists, several in one call. A list is a place to file tasks, so make one only when the user asks for it or clearly wants their work split up; tags are the lighter way to group things. Icons and colours are optional decoration: pick an emoji, or search a Phosphor slug with find-icons, and move on if neither fits. A name already in use is refused per list with the wording to show the user.

add-lists

Create tasks in BrightMind, up to 25 in one call counting nested subtasks, so capture several at once rather than one per call. Nesting runs three levels in one call, a task with subtasks and those with steps of their own, and a list too long for one batch is finished across the calls that follow rather than flattened into them. Nothing is in until the last batch answers, so say how much landed from created_including_subtasks, never from the size of what was pasted. Two dates matter and they are not the same: scheduledOn is the day the user means to DO it, deadlineOn is the day it is genuinely due, and a task can have either, both or neither. recurFrom decides how a repeat advances: schedule holds a fixed cadence (rent, medication), completion counts from the day it was actually done (a haircut); omitted, a repeat with a scheduledOn keeps its cadence and one with no day counts from the doing, so send completion yourself when the gap is the point (shaving every 3 days). A task created with no scheduledOn will not appear on Home, so ask which day they mean to do it rather than telling them it will be there. Re-sending a bare title the user already has on the same schedule, in any list and up to a day later, comes back as already existing instead of making a second copy, so say that rather than claiming a new task; set allowDuplicates only when they have asked for another copy. A task sent with subtasks is never checked against existing tasks, so to add steps to a task the user already has, find it and create the subtasks with parentId instead of re-sending the whole tree. Every created line ends with where the task landed, the inbox or a list id, and that is the only destination this result knows: no other list, project or screen is yours to name. A task with a scheduledTime is still a task, not a calendar entry: if the user is describing a meeting, appointment, or anything with attendees, create a calendar event instead.

add-tasks

Tick BrightMind tasks off, up to 25 in one call. This is the only way a task is completed: it records the completion in the task's history, which updating status cannot do. A repeating task is never over when it is ticked off, it rolls to its next date and comes back as rolled_forward, so tell the user the next date rather than saying they are done with it. A repeat sitting on a past day is today's occurrence: completing it records today and rolls to the first day after today, and skipped_on names any missed days in between that recorded nothing. To put a repeat's occurrence off instead of completing it, move its scheduled_on with update-tasks, in place; never complete it for that, and never create a copy beside the series. Completing the same task twice in a day is refused rather than rolling a repeat forward twice. Only the user's own completion word marks a task off. 'not now', 'later', 'skip', 'not tonight', or anything you read as a decline is never this tool: move the task to when they will do it, or leave it and say so. Where the decline was half-heard, or the task is one this session set up and its time has not come, ask for a plain yes before calling this, because a completion writes a history the user knows is false and cancels the reminder that would have started them.

complete-tasks

Remove BrightMind objects, up to 25 in one call. Nothing is destroyed: a task goes to the trash and is recoverable for 30 days with restore-objects, taking every time of a task done several times a day with it, and a list is archived rather than trashed, which leaves every task in it untouched. Removing more than 10 objects at once is refused unless confirm is true, so tell the user how many would go and get a yes first. When the user only wants something off their plate rather than gone, update-tasks with a new date or status wontdo keeps the record and is usually what they meant.

delete-object

Look up Phosphor icon slugs by keyword, for the icon field on a BrightMind list. Icons are optional: a list is perfectly fine without one, and the icon field also accepts a plain emoji. Search here only when the user asked for a particular look.

find-icons

Read the user's BrightMind tasks by scope. Use scope=date to see what is still open on a day, and scope=completed to see what the user finished on a day or span (the one to use for a done-today report); a text search matches words, never a date. Call this to get task ids before updating, completing or deleting anything. Two dates matter and they are not the same: scheduled_on is the day the user intends to do the task, deadline_on is the day it is actually due. A task can have either, both or neither. Returns the fields listed in each preview line plus id; subtasks are not included, and finished tasks only under scope=completed or scope=search, and a page past 20 rows is trimmed to identifying fields only. A task the user linked is passed by its href id, not searched by its title: put it in taskIds, and it comes back in full with its subtasks.

find-tasks

Read one BrightMind object in full by its id: a task with its note, tags, reminders, subtask tree and completion history, or a list with its open tasks. Use it when find-tasks gave you an id and the user wants the detail. Remember the two dates are different: scheduled_on is the day the user means to do it, deadline_on is the day it is genuinely due.

get-object

Get the shape of the user's BrightMind tasks in one cheap call: what is scheduled today, how much is overdue, how much is waiting in the inbox, and every list and tag with its open count. Call this first when the user asks what is on their plate or how their tasks are organised. It reports counts and today's set only, never the whole backlog: use find-tasks with a scope to read further.

get-overview

Bring BrightMind objects back, up to 25 in one call: pull tasks out of the trash, reopen archived tasks, or unarchive a list. A task that was archived before it was trashed comes back in two steps, because the first call only clears the trash stamp and leaves it archived, so read the status in the result and call again to reopen it. A restored subtask whose parent is still trashed or no longer exists comes back as a task of its own at root level rather than under that parent, so say so instead of promising it is back where it was. An object that is neither trashed nor archived has nothing to restore and is refused on its own, without touching the rest of the batch.

restore-objects

Pass over the current occurrence of a repeating BrightMind task without finishing it, up to 25 in one call. Use it when the user cancelled, missed or decided against this one time and the repeat carries on: "skip today's run", "not doing the gym today". It writes no completion history, so the day it passes over keeps recording nothing, which is the truth about it. That is the difference from complete-tasks, which records the day as done. It reaches only the current occurrence, the one scheduled_on shows: a later one is reached only by also passing over every one before it, so when the user named a later day, say so and ask rather than calling it twice. It is also not how a repeat is stopped for good: dropping the whole series is update-tasks with status wontdo, or delete-object. A task that does not repeat has no next occurrence and is refused, with the error naming what to do instead.

skip-tasks