Using it with AI agents

POST /api/mcp is a Model Context Protocol server: the same keys and the same permissions as the API, and a set of tools a model can call. It is what "put that on my to-do list" means when the thing being asked is an assistant rather than the app.

The examples below use https://app.ontoplano.com. Your own instance answers at https://your-host/api/mcp — the address you type into the browser, with /api/mcp after it.

Connecting without a key

Paste your instance's address into an assistant that speaks MCP — Claude, ChatGPT, or anything else with a connector screen — and it will do the rest:

https://app.ontoplano.com/api/mcp

The assistant discovers that the address is protected, registers itself, and sends you here. You see a screen on your own instance saying which assistant is asking and what it would be able to do, you press Connect it, and you are handed back. No key is typed, pasted or stored by anybody.

What it would be able to do is a list of tick boxes, gathered by what they are about — your week, money, the diary, the house — and everything the assistant asked for is ticked. Untick a line, or a whole heading, and the key it walks away with cannot reach that at all: a tool whose permission was not granted is not offered to the assistant, so one that may not read your diary does not know write_entry exists.

What it gets is an ordinary key, made for it and named after it, so it stands in the list under Settings → AI & Integrations → Integrations with a revoke button beside it like every other. Deleting is a box of its own on that screen and it starts unticked — the connection reads and writes, and takes nothing away unless you said it may.

Two details for anyone implementing against it: the flow is the authorization code grant with PKCE (S256 only — there is no plain, and no implicit grant), and the discovery documents are at /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server. The token that comes out does not expire, so there is no refresh token to hold; revoking is what ends it.

Make a key

Settings → AI & Integrations → AI → Create a key. It is shown once, so keep the tab open while you set the assistant up.

Every permission the tools use is ticked to begin with, reading and writing both. Untick what you would rather it did not see — a tool whose permission was not granted is not offered to the assistant at all, so a read-only key does not know that add_task exists.

Deleting is a box of its own below that table, and the one thing that starts unticked. Without it an assistant can add and change but never remove, and the tools that delete are not offered to it either; tick it if you want them.

The Integrations tab beside it has the wider form — every permission, the ones an assistant has no use for included, and an expiry date — for a key meant to run a script rather than an assistant. Keys are revoked there too, and a revoked key stops working on the next request.

Connect it

I use ontoplano — a life management app my assistant can connect to.
Please connect to it and use it whenever I ask you about my week, my to-do
list, my diary, my notebooks, my shopping list or my recipes.

  Address:    https://app.ontoplano.com/api/mcp
  Protocol:   MCP, over streamable HTTP (stateless — no session, no GET)
  Key:        send it as an "Authorization: Bearer" header

Once you are connected, tell me what is on my plan today. Do not change
anything in my account until I ask you to.

Key: onto_YOUR_KEY_HERE

/plugin marketplace add ontoplano/claude-plugin
/plugin install ontoplano@ontoplano

claude mcp add --scope user --transport http ontoplano https://app.ontoplano.com/api/mcp \
  --header "Authorization: Bearer onto_YOUR_KEY_HERE"

{
	"mcpServers": {
		"ontoplano": {
			"command": "npx",
			"args": [
				"-y",
				"mcp-remote",
				"https://app.ontoplano.com/api/mcp",
				"--header",
				"Authorization:Bearer onto_YOUR_KEY_HERE"
			]
		}
	}
}

[mcp_servers.ontoplano]
url = "https://app.ontoplano.com/api/mcp"
bearer_token_env_var = "ONTOPLANO_KEY"

echo 'export ONTOPLANO_KEY=onto_YOUR_KEY_HERE' >> ~/.bashrc   # zsh: ~/.zshrc

{
	"mcpServers": {
		"ontoplano": {
			"url": "https://app.ontoplano.com/api/mcp",
			"headers": { "Authorization": "Bearer onto_YOUR_KEY_HERE" }
		}
	}
}

Restart the client after editing its file. If it lists ontoplano's tools, it worked.

Blocks and to-dos are different things

A to-do is something to do with no hour attached; a block is an hour. "Ring the dentist" is a to-do, "deep work from 9 to 11" is a block. An assistant that only has add_task answers the second by writing the time into the title, and your day still looks empty.

With schedule:write it puts a real block on the day and can answer for the ones already there. finish_block takes both answers, and skipped is a real answer — a week that can only be told about the parts that went well starts lying by the second one.

change_block moves and renames; cancel_block takes something off a day. Cancelled is not skipped: skipped means you meant to do it and did not, and the weekly review asks about it; cancelled means the plan was wrong. An assistant with only one of them uses the wrong one when it moves something.

All of it is that day only. Moving this Thursday's gym never moves gym, which is what alt-dragging it in the app does too.

The pictures and recordings in what it reads

A note, a task and an idea can all hold a picture or a recording, and what a tool hands back is the markdown that refers to it: ![the wall](/media/31), [said](/media/audio/44). The media tool turns that link into the file itself — hand it the link exactly as the writing writes it, and the picture comes back as a picture:

{ "name": "media", "arguments": { "path": "/media/31" } }

/media/audio/44 for a recording. The same file is also an ordinary HTTP request, for a script that holds the key itself rather than speaking the protocol:

curl -H "Authorization: Bearer $ONTOPLANO_KEY" \
  https://your-instance/media/31 --output picture.png

Both doors ask the same question, and the answer is the permission that reads the thing the file is in.

A picture in a note wants notes:read, one on a task tasks:read, a face people:read, a recipe photograph kitchen:read. There is no separate media grant — a file answers to whatever refers to it, and one that nothing refers to answers to nobody. A key tied to one notebook reaches the files inside that notebook and no others.

Anything the key may not reach is a 404, the same as an id that never existed, so there is nothing to learn by walking the numbers.

How it behaves

• It offers only what the key holds. tools/list is filtered by permission, and the permission is checked again on every call.
• Nothing in it is new behaviour. Every tool calls the same function the web page calls, so the same limits, validation and ownership checks apply.
• It is stateless. No session and no event stream: every request carries its own key, and a GET answers 405.
• A refusal is an answer. "That is not a date" comes back as tool content the model can read and act on, not as a protocol error. Its structuredContent carries a code software can branch on — the same words the JSON API answers with: not_found, validation_error, conflict, plan_limit, forbidden, rate_limited — beside the sentence, and details where the refusal knows more.
• Deleting is its own permission. Tools that remove a row for good need the destructive grant, and without it they are not offered at all.
• Every write answers with what it replaced — before and after, and for a delete the whole removed row — so a bad call can be put back from the conversation itself. Two exceptions say so in their own description: tag_task answers with the labels and nothing else, because two copies of a task to report one label is most of what marking a list costs, and the person's own copy of the change is in the log under Settings → Integrations either way.
• A listing answers with a line. A task comes back as what it is, where it stands and its labels; a note as its name, its labels and an opening. verbose: true gives the whole row, and fields: "title,notes" gives exactly those. This is a budget, not a limit: a model reading a list to find one thing pays for forty rows it will not use, three times over — on the way in, on the way out, and again next turn.
• A line says what the row is about, and names the pictures it refers to. A task's line carries an opening of its notes and the links in them; a note's line the same. media fetches one when it turns out to matter — a list is rarely read for its pictures, and always read to find something.
• A list can be asked for narrowly. status, tags, withoutTags and taggedSince on the task list; tags and taggedSince on notes. tags takes as many labels as you like and answers with anything carrying any one of them, so a queue spread over u5, e2 and i5 is one call rather than three. The date read is the label's own — it does not move when the thing is edited — so "what went into review since this morning" is one call.
• up_next answers what to do next, by the ratings on the tasks themselves: most urgent first, then the easiest, then the one most wanted. All three run the same way — five is the most of what the word says. A rating nobody set is not a zero: it counts as 2.5, the middle of the scale, so a task marked 3 beats an unrated one and 0–2 are the tiers that mean "later".
• A change names only what changes. Every change_* and edit_* tool takes an id and the fields being changed; a field left out keeps what it had. Where a field can be emptied, its description says how — null for a rating, an empty string for notes, {} for attributes. An argument that holds a whole set, such as tags on change_task, replaces it; tag_task adds and removes one label at a time.
• A change can refuse to overwrite somebody else's. A change_* or edit_* tool on a thing that keeps an updatedAt takes ifUpdatedAt: pass the stamp you read, and if the thing has changed since, nothing is written and the refusal's code is conflict, with the current updatedAt in its details. Every change on those tools answers with its new updatedAt.
• A create can be sent again. Tools that make or count something — every add_*, write_entry, log_*, record_*, tick_habit, set_alarm — take a requestId you choose. Sent again with the same arguments within a day, the call answers with the first answer, marked replayed: true, and nothing is made twice; so an assistant that lost an answer can retry without asking whether the first one landed. The same id with different arguments is refused as a conflict.
• A list comes a page at a time. A tool marked "answers a page" takes limit and offset, and answers with count (what is in this answer) and total (what matched). While more is left the answer also carries remaining and nextOffset; pass nextOffset as offset to read on. No nextOffset means nothing is left.
• A wrong argument is refused before anything runs. An argument the tool does not take, a string where it wants a number, a value outside its enum or its bounds: the answer is a JSON-RPC error -32602 naming the argument, with code: "validation_error" in its data, and nothing is written.

Common requests

What somebody asks, the call an assistant makes for it, and the part of the answer worth reading. They run in this order against a fresh account in the test suite, which checks each answer holds what is printed here.

“Start a notebook for the kitchen, under Home.”

{
	"name": "add_notebook",
	"arguments": { "title": "Kitchen", "folder": "Home" }
}

The answer holds, among the rest:

{ "id": 1 }

“Add ‘descale the kettle’ to the kitchen notebook.”

{
	"name": "add_task",
	"arguments": { "title": "Descale the kettle", "notebookId": 1 }
}

The answer holds, among the rest:

{ "id": 1, "before": null, "after": { "id": 1, "title": "Descale the kettle" } }

“And ‘fix the cupboard hinge’.”

{
	"name": "add_task",
	"arguments": { "title": "Fix the cupboard hinge", "notebookId": 1 }
}

The answer holds, among the rest:

{ "id": 2 }

“The hinge is urgent.”

{ "name": "change_task", "arguments": { "id": 2, "urgency": 5 } }

The answer holds, among the rest:

{ "after": { "id": 2, "ratings": { "urgency": 5 } } }

Only id and the field being changed are sent; everything left out keeps what it had.

“What should I do next?”

{ "name": "up_next", "arguments": {} }

The answer holds, among the rest:

{
	"items": [{ "id": 2, "title": "Fix the cupboard hinge" }],
	"count": 1,
	"total": 2,
	"remaining": 1,
	"nextOffset": 1
}

One task by default. remaining and nextOffset are there because more is left: passing offset: 1 reads the next one.

“Actually, the hinge can wait — forget the urgency.”

{ "name": "change_task", "arguments": { "id": 2, "urgency": null } }

The answer holds, among the rest:

{
	"before": { "ratings": { "urgency": 5 } },
	"after": { "ratings": { "urgency": null } }
}

null clears a rating; leaving urgency out would have kept it.

“I descaled the kettle.”

{ "name": "finish_task", "arguments": { "id": 1 } }

The answer holds, among the rest:

{ "ok": true, "after": { "id": 1, "status": "done" } }

“Which kitchen tasks are still open?”

{
	"name": "tasks",
	"arguments": { "notebookId": 1, "status": "open", "fields": "title,status" }
}

The answer holds, among the rest:

{
	"items": [{ "id": 2, "title": "Fix the cupboard hinge", "status": "todo" }],
	"count": 1,
	"total": 1
}

No nextOffset in the answer means there is nothing more to read.

“Note down that the oven runs hot.”

{
	"name": "write_entry",
	"arguments": {
		"content": "The oven runs about 20° hot — set it lower than the recipe says."
	}
}

The answer holds, among the rest:

{ "id": 1 }

“File that note under the kitchen notebook.”

{ "name": "move_notes", "arguments": { "ids": [1], "notebookId": 1 } }

The answer holds, among the rest:

{ "ok": true, "moved": 1 }

“What is labelled kitchen?”

{ "name": "tasks", "arguments": { "tag": "kitchen" } }

The answer holds, among the rest:

{
	"count": 0,
	"total": 0,
	"warning": "`tag` is deprecated and will be removed in 0.185.0. …"
}

tag is the old spelling of tags. It still works until the release named, and the answer says so.

“Make the hinge a 3 for urgency.”

{ "name": "change_task", "arguments": { "id": 2, "urgncy": 3 } }

Refused before the tool runs, as a JSON-RPC error -32602 with the message “urgncy is not an argument this tool takes.”

A misspelt argument is named back, and nothing is written.

“Put ‘buy light bulbs’ on the list.”

{
	"name": "add_task",
	"arguments": { "title": "Buy light bulbs", "requestId": "5f1c-bulbs" }
}

The answer holds, among the rest:

{ "id": 3 }

requestId is any string the assistant picks for this one call.

“(No answer came back, so the assistant sends the same call again.)”

{
	"name": "add_task",
	"arguments": { "title": "Buy light bulbs", "requestId": "5f1c-bulbs" }
}

The answer holds, among the rest:

{ "id": 3, "replayed": true }

Same requestId and arguments within a day: the first answer comes back, marked replayed, and there is still one task.

What an assistant can do, room by room

The common verbs for each kind of thing, and the tools that do them over MCP beside what the app itself offers. A blank is a verb neither has; app only is a gap an assistant cannot fill yet; app only, on purpose is a decision, said below — mostly deletions kept for the person. Generated from src/lib/server/mcp/capabilities.json, which a test holds to the tools the server serves and the actions the app has.

Not there yet — what the app does and an assistant cannot:

Left out on purpose:

• Notes and diary entries, delete. Writing is precious: an assistant archives, and the person deletes in the app.
• Goals, delete. A goal stands for a commitment: closed or abandoned by a tool, deleted only in the app.
• Habits, delete. A habit carries its kept days: deleted only in the app.
• Recipes, delete. A recipe is archived by a tool; deleting one is done in the app.
• Workouts, delete. An exercise carries its sessions: archived by a tool, deleted in the app. Sessions and categories can be removed.
• Bills, delete. A bill carries its payment history: archived by a tool, deleted in the app where that history is in front of the person.
• Accounts and movements, delete. A ledger takes every line in it when deleted: archived by a tool, deleted in the app. A single line can be removed.
• Commitments, delete. A commitment carries financial history: assistants archive it; permanent deletion is only in the archived app view. Mistaken entries can be reversed and restored through the assistant log.
• People, delete. A person's page stands for somebody: deleted only in the app.
• Labels, create. A label comes into being by being used — tags on a task, a note or an idea — so there is nothing to make first.
• Recordings, create. A recording is made by a microphone in the app; there is nothing for a tool to say into.
• Recordings, delete. A recording is the one copy of something said: deleted only in the app.

Old spellings

The surface is additive within a major version: a tool or a parameter is not removed, a parameter does not become required, an enum does not lose a value, a bound does not tighten, a default does not move and a tool does not start needing another grant — at any depth, fields inside a list included — without a release in between that marks the old shape deprecated. That is enforced by src/lib/server/mcp/manifest.json and a test that refuses any change breaking an existing caller.

A deprecated argument keeps working until the release named below. A call that uses one is translated, and its answer carries a warning naming the replacement and the release.

The tools

Every tool the server offers, with the exact description a model is handed — published from the same array that serves them, so the two cannot drift. A key is only offered the tools its permissions reach. The permissions themselves are on the permissions page.

Under each description: the permissions the key must hold, whether the tool writes, and what its answer carries. Parameters inside a list of objects are named with [] — measures[].unit is the unit of each line in measures.

today — Today's plan

What is on today: the blocks planned for it and the tasks pulled onto it. This is the answer to 'what am I meant to be doing', and the first thing to reach for before adding anything. Habits are not here — they are their own permission, and their own tool.

Needs today:read; read-only.

Takes no parameters.

habits — Habits due today

The habits scheduled for today, each with its streak and whether it has been kept yet. Separate from the day's plan on purpose: whether somebody kept their habits is a more personal thing than what is on their calendar, so it is granted separately.

Needs habits:read; read-only.

Takes no parameters.

tick_habit — Tick a habit

Tick a habit for a day: for something being built, the tick means it was done; for something being avoided, it means it happened. Name it or give the id habits gave; a name that matches two habits is refused rather than guessed. Ticking twice is not an error; the second call takes it back, which is how the app’s own tick behaves.

Needs habits:write; writes; answers with before and after.

set_habit_count — Set a habit’s count for a day

Set how many times a habit was logged on a day — the number itself, not a step, so sending it twice changes nothing. 0 clears the day. For a habit kept more than once a day ("three glasses of water"); for once-a-day ones tick_habit is the ordinary call. Name it or give the id habits gave; a name that matches two habits is refused rather than guessed. The answer’s before is the count it replaced, which is how to put it back.

Needs habits:write; writes; answers with before and after.

finish_block — Mark a block done or skipped

Answer for one block on the day: it happened, or it did not. Takes the id today gives for that block. Skipping is a real answer — say skipped when the person says they did not do it. It is NOT a way to clear something off the day: a skip goes into the week’s record and the review asks about it. To move a block use change_block; to take one off because it was never happening use cancel_block. todo takes an answer back, for one ticked by mistake.

Needs schedule:write; writes; answers with before and after.

add_block — Put a task block on a day

Add a one-off block to one day: a title, a start time and how long it runs. This is for "deep work from 9 to 11 today" — a thing with an hour. Use add_task instead when there is no time attached, and change_block to move or rename something already on the day rather than adding a second copy of it. It does not touch the repeating week; this is that day only.

Needs schedule:write; writes; answers with before and after.

change_block — Move or rename a task block

Change one task block on one day: its time, its day, how long it runs, or what it is called — and, for a one-off, the notebook it is filed under and its attributes. This is "push the study block to four", "make it two hours", "that was actually client work". Takes the id today or upcoming gives. Only the fields you pass change, and nothing is written unless all of them are valid; notebookId of 0 unfiles it and attributes of {} empties them. It affects that day only — moving this Thursday’s gym does not move gym — and it never edits the repeating week. Renaming keeps which part of life it belongs to and stops it being the named activity it was, because that is what saying it was something else means.

Needs schedule:write; writes; answers with before and after.

cancel_block — Take a block off the day

Remove a block from a day because it is not happening — the meeting moved, the class was called off, it was put on the wrong day. This is NOT the same as marking it skipped: skipped means it was meant to happen and did not, which is a fact the weekly review asks about, and cancelled means it was never going to. Use finish_block with "skipped" for the first and this for the second. A repeating block is only removed from that one day.

Needs schedule:write and destructive; deletes; answers with before and after.

upcoming — The days ahead

Everything planned from today onwards — the blocks of the week, in order. Use it to answer questions about a day that is not today.

Needs schedule:read; read-only.

past — The days behind

What was on the days that have already happened, with what each one was answered — done, skipped, or nothing yet. Use it before correcting a week: it gives the ids finish_block needs. Ask for a week back with days: 7, or name the day it starts on.

Needs schedule:read; read-only.

search — Search everything written

One search over diary entries, notebooks, notes, ideas, goals, people, recipes and todos. Prefer this to guessing which room a thing is in.

Needs search:read; read-only.

media — A picture or a recording

The bytes of a file this key may see, given the link as it appears in the writing — /media/12 for a picture, /media/audio/12 for a recording. A file answers to whatever refers to it, so the grant that lets you read the note lets you see the picture in it; one nothing refers to is reachable by nobody.

Needs any of ideas:read, kitchen:read, notes:read, people:read, tasks:read; read-only.

recordings — Recordings

The audio recordings, newest first: name, notes, length in seconds and when it was made. link is what media takes to fetch the sound itself.

Needs audio:read; read-only; answers a page.

change_recording — Rename a recording, or write its notes

Change a recording’s name, its notes, or both — a transcript, a summary, what it was about. A field left out is untouched; notes replace what was there, and an empty string clears them.

Needs audio:write; writes; answers with before and after.

tasks — The todo list

The to-do list: every task, including the ones already put on a day unless scheduled: "undated" asks for only the dateless ones. Answers with a line per task; verbose or fields for more. Narrow it rather than reading it whole — notebookId for one subject, status: "open", query for words, tags, withoutTags, taggedSince, dates and ratings — and sort to read it in another order. up_next is this list in priority order.

Needs tasks:read; read-only; answers a page.

up_next — What to do next

The task to do next, by the ratings on it: most urgent first, then the easiest, then the one most wanted. All three run the same way — five is the most of what the word says. An unrated one is not a zero: it counts as the middle of the scale, 2.5, so anything marked 4 or 5 beats it and 1 or 2 falls below it as the postpone tiers. Open, unarchived tasks only; tasks already put on a day are included unless scheduled: "undated". Answers with one line by default; limit for a short list to choose between, offset for the next page, and the same filters tasks takes — tags to ask it of one queue or of several at once.

Needs tasks:read; read-only; answers a page.

add_task — Add a todo

Put a task on the todo list. Leave the date off unless the person said when — a todo with no date is the normal case here, not an unfinished one.

Needs tasks:write; writes; answers with before and after, after being the new todo.

finish_task — Finish a todo

Mark a todo done, which is what "I did that" means here — it is not deleted, it moves to done and stays in the record. Ask tasks first for the id.

Needs tasks:write; writes; answers with before and after.

drop_task — Delete a todo

Remove a todo entirely, because it is not going to happen and is not worth a record — "bin that one", "forget it". Different from finish_task, which keeps it as something that was done. Gone for good; prefer finishing it when it actually happened.

Needs tasks:write and destructive; deletes; answers with before and after.

reopen_task — Put a todo back on the list

Undo a finish or a drop: the todo goes back to not-done. Use it when something was ticked by mistake, or when a dropped thing turns out to matter after all. It keeps its notes, its day and everything linked to it.

Needs tasks:write; writes; answers with before and after.

archive_task — Put a todo away for now

Put a todo out of the way without finishing it or dropping it — for something that matters but not this month. It keeps its notes, its notebook and its state, and comes back with unarchive_task. Prefer this to dropping when somebody says "not now" rather than "not going to".

Needs tasks:write; writes; answers with before and after.

unarchive_task — Bring a todo back

Bring back a todo that was put away, so it shows on the list again. It returns in whatever state it left in. tasks says which ones are archived.

Needs tasks:write; writes; answers with before and after.

tag_task — Label a todo

Put labels on a todo or take them off, leaving its other labels alone — this is the one to use for marking a task, and change_task is for replacing every label at once. Several assistants sharing a list mark their own work this way; tasks takes a tag to read back only the ones you marked. Answers with the labels it has afterwards.

Needs tasks:write; writes; answers without before and after.

change_task — Change a todo

Rewrite a todo’s title, notes or state. Only id is needed: a field left out is untouched. Everything is checked before anything is written, and the change lands whole or not at all. Moving it on or off a day is schedule_task; finish_task and reopen_task are the shorthands for the two ends of status.

Needs tasks:write; writes; answers with before and after.

reorder_tasks — Put tasks in order on the board

Set the order tasks sit in on the board, the way dragging them does: the ids given, first to last. Tasks not named keep their places. tasks answers in this order unless asked for another. It is not a priority — up_next orders by the ratings.

Needs tasks:write; writes; answers with before and after.

schedule_task — Put a todo on a day

Give a todo a date, which moves it onto that day’s board. This is what "do it on Thursday" means here.

Needs tasks:write; writes; answers with before and after.

unschedule_task — Take a todo off its day

Take the date off a todo, which moves it back to the list of things with no time yet. This is "not today after all" — the todo is kept, it just stops being on a day.

Needs tasks:write; writes; answers with before and after.

goals — Goals

What the person is working towards, by horizon, with the work counted against each. add_goal transcribes one they just said; close_goal says how one ended.

Needs tasks:read; read-only.

close_goal — Say how a goal ended

Close a goal: achieved, missed, or abandoned. Missed and abandoned are different — missed is a deadline that passed, abandoned is a decision to stop — and both are worth recording honestly rather than being rounded to one. Takes the id goals gives. There is no tool that opens a goal; that is the person’s to make.

Needs tasks:write; writes; answers with before and after.

link_to_goal — Count work towards a goal

Attach todos or repeating blocks to a goal, so finishing them moves its progress. Adds to what is already linked; nothing is replaced. goals gives the goal id and what it already has on it.

Needs tasks:write; writes; answers with before and after.

unlink_from_goal — Take work off a goal

Detach todos or blocks from a goal. Only the ones named; everything else it counts stays.

Needs tasks:write; writes; answers with before and after.

reopen_goal — Reopen a goal

Put a closed goal back to open. Its outcome note is cleared and the date it was closed on goes with it, so a reopened goal does not read as having been finished at some point in the past.

Needs tasks:write; writes; answers with before and after.

change_goal — Change a goal

Rename a goal, or change its notes, horizon, start date, or what it is measured by. Only id is needed: a field left out is untouched, and nothing is written unless all of it is valid. targets replaces every measure at once, so read goals first. Adding one without disturbing the rest is add_goal_target. Saying how it ended is close_goal, not this.

Needs tasks:write; writes; answers with before and after.

diary — Recent diary entries

What has been written lately, newest first. An entry can belong to a notebook or to no notebook at all. Answers with a line and an opening per entry; verbose for the writing itself.

Needs notes:read; read-only; answers a page.

write_entry — Write a diary entry

Add an entry. Markdown. Writing one when asked is the point of this tool — keep their words and their voice where you have them, and do not invent an entry nobody asked for. Put it in a notebook when it is about one subject; leave the notebook off for an ordinary day.

Needs notes:write; writes; answers with before and after, after being the new note.

notebook_notes — The notes in a notebook

What has been written against one subject, newest first, with the id of each note. diary deliberately shows only entries outside a notebook, so this is the way to read one — and the way to find the id archive_note wants. Answers with a line and an opening per note; verbose for the writing itself, tags and taggedSince to narrow.

Needs notes:read; read-only; answers a page.

pin_note — Keep a note at the top

Hold a note at the top of its notebook — the measurements, the account number, the thing the notebook is actually for. As many as the person likes; the most recently pinned leads. unpin_note lets one go.

Needs notes:write; writes; answers with before and after.

unpin_note — Stop keeping a note at the top

Let a pinned note fall back into its notebook’s own order, where it is read with the rest.

Needs notes:write; writes; answers with before and after.

edit_entry — Change what a note says

Rewrite a note or a diary entry — its words, its title, its tags, its colour. Only the fields given change; the rest of it, and the notebook it lives in, are left alone. notebook_notes gives the id. To put one out of the way instead, archive_note.

Needs notes:write; writes; answers with before and after.

note_to_tasks — Make todos out of a checklist note

Turn a note that is really a checklist into the tasks it describes. Every - [ ] line becomes a task, with whatever is written under it as that task’s notes; a - [x] line comes across already done. Each is filed under the note’s own notebook, and each box is replaced by a reference to the task it became — TASK:#4 — so the note keeps its words and stops being a second copy of the list.

Needs tasks:write and notes:read; writes; answers with before and after.

archive_note — Put a note away

Hide a note without deleting it — for one that has stopped being current and is not something to throw out: the trip is over, the flat is rented. It stays in its notebook and comes back with unarchive_note. Notes are never deleted through a tool.

Needs notes:write; writes; answers with before and after.

unarchive_note — Bring a note back

Bring back a note that was put away, so it shows in its notebook again. notebook_notes with includeArchived says which ones are away.

Needs notes:write; writes; answers with before and after.

move_notes — Move notes to another notebook

File one or more notes or diary entries under a notebook, or with notebookId 0 into the diary. All of them move or none do, and each takes the next number free where it lands. notebook_notes and diary give the ids.

Needs notes:write; writes; answers with before and after.

notebooks — Notebooks

The subjects being written against — a trip, a renovation, a book — with the id every other tool means by notebookId. Ask for these before writing an entry into one. A key tied to one notebook is answered with that one. modules is what each one holds: the tabs it shows, which is also what it will accept being filed under it. favourite is whether the person has starred it; favourites come first.

Needs notes:read; read-only.

add_notebook — Make a notebook

Make a notebook — a subject written against with no deadline: a book, a trip, a renovation. write_entry files notes into it by name.

Needs notes:write; writes; answers with before and after, after being the new notebook.

change_notebook — Change a notebook

Rename a notebook, move it to another folder, rewrite the line under its title, set the labels a new note in it starts with or the category a new task in it starts with, change what it holds, or close and reopen it. Only id is needed: a field left out is untouched, and nothing is written unless all of it is valid.

Needs notes:write; writes; answers with before and after.

rename_notebook_folder — Rename a notebook folder

Rename or move a folder of notebooks: every notebook in it, and in the folders inside it, has that part of its path rewritten. notebooks gives each notebook its folder. Moving a folder into its own parent removes it; nothing is deleted.

Needs notes:write; writes; answers with before and after.

remove_notebook — Remove an empty notebook

Delete a notebook that holds nothing — no notes, no tasks, nothing filed under it at all. One with anything in it is refused with what it holds: somebody’s writing is deleted by them in the app, never through a tool. For a notebook made by mistake.

Needs notes:write and destructive; deletes; answers with before and after.

favourite_notebook — Star a notebook

Keep a notebook at the front of the shelf and at the top of every notebook picker, or take the star off with favourite: false. The star is the person’s own, so a notebook shared with them can carry one too. notebooks says which have one.

Needs notes:write; writes; answers with before and after.

share_notebook — Share a notebook with the family

Share one of the person’s notebooks with everybody on their family plan — they read it and write their own entries into it — or stop sharing with shared: false. Only its owner’s to flip, and only when they asked.

Needs notes:write; writes; answers with before and after.

ideas — Ideas

Things caught before they evaporated, newest first. An idea is not a task: nobody has committed to doing it, which is what makes it cheap to write down.

Needs ideas:read; read-only; answers a page.

add_idea — Catch an idea

Write an idea down without deciding where it belongs. The lowest-friction thing here; prefer it to a todo when the person has not said they will do it.

Needs ideas:write; writes; answers with before and after, after being the new idea.

remove_idea — Delete an idea

Delete an idea — for one added by mistake, or one that has been dealt with. It is gone, not archived, so prefer leaving it alone unless the person asked.

Needs ideas:write and destructive; deletes; answers with before and after.

change_idea — Change an idea

Rewrite an idea, or retag it — for a misheard word or a better tag, not for turning it into something else. Only id is needed: a field left out is untouched.

Needs ideas:write; writes; answers with before and after.

tags — The labels

Every label the account uses, alphabetically, with the colour it wears and how many things carry it. One vocabulary for the whole app — the same word on a task, a note, an idea, a block and a picture.

Needs tags:read; read-only.

Takes no parameters.

notebook_tags — The labels in one notebook

The labels on what is filed under one subject, with how much of it carries each — and what kind: notes, tasks, ideas. Narrower than tags, which counts a word across the whole account, and the one to ask before labelling something the way this notebook labels things. A label the notebook suggests by default is listed at nought.

Needs tags:read and notes:read; read-only.

describe_tag — Say what a label means

Write down what a word means in this account — #short on the shopping is low on something, #short on a book is the book. One line; an empty one takes the meaning off again. The label itself is not changed: rename_tag is for that.

Needs tags:write; writes; answers with before and after.

rename_tag — Rename a label

Rename a label everywhere at once — for a typo, or for two words that turned out to mean one thing. Renaming onto a name the account already uses merges the two: everything that carried the old label carries the surviving one, and the old label stops existing. Answers with the label that survived.

Needs tags:write; writes; answers with before and after.

recolor_tag — Colour a label

Give a label a colour, so it is drawn in it wherever a chip for it appears. An empty string takes the colour off again, which is the plain chip every label starts as.

Needs tags:write; writes; answers with before and after.

remove_tag — Delete a label

Take a label out of the vocabulary and off everything that carried it — the tasks, notes, ideas, blocks and pictures keep everything else about them. Nothing is archived; the label is gone. To fold it into another label instead, rename_tag onto that one.

Needs tags:write and destructive; deletes; answers with before and after.

untag_notebook — Take a label off one notebook

Take a label off everything filed in one notebook — its notes, tasks and ideas — and off nothing outside it. The label stays in the vocabulary while anything else carries it. Answers with how many things lost it. To remove a label everywhere, remove_tag.

Needs tags:write; writes; answers with before and after.

shopping_list — The shopping list

What is to buy and what is already in the cupboard. An item is a thing, not a line: ticking it bought puts it back in the cupboard rather than deleting it. Each carries how many there are and how many are kept, so "what am I short of" is qty below idealQty — short: true asks for exactly those.

Needs inventory:read; read-only.

add_inventory_item — Add to the shopping list

Put something on the list. If the cupboard already has it, this says so rather than adding a second one.

Needs inventory:write; writes; answers with before and after, after being the new item.

tick_bought — Tick something bought

Mark an item bought, which moves it out of "to buy" and into the cupboard. The row stays: the same thing is bought again the next time it runs out.

Needs inventory:write; writes; answers with before and after.

untick_bought — Put something back on the list

Undo a tick: the item comes out of the cupboard and back onto "to buy". Use it when something was marked bought by mistake, or when it has run out again. Nothing is lost either way — the row, its category and its price history are the same row.

Needs inventory:write; writes; answers with before and after.

archive_item — Put something aside for now

Put an item away without deleting it — for something not wanted this week. It keeps everything about itself and comes back with unarchive_item. Prefer this to removing when somebody says "not now" rather than "never".

Needs inventory:write; writes; answers with before and after.

unarchive_item — Bring something back to the list

Bring back an item that was put away, so it shows on the list again. shopping_list says which items are archived.

Needs inventory:write; writes; answers with before and after.

remove_inventory_item — Take something off the shopping list

Remove an item because it is not wanted — "take milk off", "we already have that". Not the same as tick_bought, which records that it was bought and keeps it in the history and the price record. Takes the id shopping_list gives.

Needs inventory:write and destructive; deletes; answers with before and after.

recipes — Recipes

Every recipe, with its ingredients. An ingredient here is a shopping item with an amount, which is what lets a meal on a day fill the shopping list.

Needs kitchen:read; read-only.

add_recipe — Add a recipe

Write a recipe down. Ingredients are one per line — "200 g flour", "2 eggs" — and each becomes a shopping item, so the list knows about them the day the meal is planned.

Needs kitchen:write; writes; answers with before and after, after being the new recipe.

change_recipe — Change a recipe

Change a recipe’s title, method, servings, time, source or notebook, and its ingredients: addIngredients adds lines (one per line, quantity first), removeIngredients takes lines out by the ingredient ids recipes gives. Only id is needed: a field left out is untouched, and ingredients not named stay. An empty string clears a text field, 0 or null clears servings or time. The recipe and its ingredients land together or not at all.

Needs kitchen:write; writes; answers with before and after.

cooked_recipe — Say a recipe was cooked

Record that a meal was made — recipes shows when each was last cooked, and this is what sets it. Name the ingredient ids that ran out and they land back on the shopping list, which is the loop the kitchen exists to close.

Needs kitchen:write; writes; answers with before and after.

archive_recipe — Put a recipe away

Archive a recipe — out of the everyday list, not deleted — or bring one back with archived: false. For the dish nobody makes any more that somebody may yet ask for.

Needs kitchen:write; writes; answers with before and after.

file_inventory_item — File an item into a section

Move a shopping item into a section — "put the milk under Dairy". Takes the item’s id from shopping_list and the section by name from inventory_categories; an empty section name unfiles it. A name matching no section is refused with the ones that exist.

Needs inventory:write; writes; answers with before and after.

change_inventory_item — Rename a shopping item, or change its notes

Rename an item, change whether it is something to replenish or a someday wish, or rewrite its notes. Takes the id shopping_list gives. Only id is needed: a field left out is untouched. Its section is file_inventory_item, its place put_item, its price record_price.

Needs inventory:write; writes; answers with before and after.

inventory_categories — The shopping list’s sections

How the shopping list is sectioned — produce, cleaning, whatever the person keeps. Read it before filing an item somewhere.

Needs inventory:read; read-only.

Takes no parameters.

add_inventory_category — Add a shopping section

Make a new section for the shopping list — and say whether it holds food, because only food sections can feed recipes as ingredients.

Needs inventory:write; writes; answers with before and after, after being the new inventoryCategory.

change_inventory_category — Rename a shopping section

Rename a section, recolour it, or change whether it holds food. Only id is needed: a field left out is untouched, and the change lands whole or not at all — a refused share leaves the name as it was. The items filed under it stay exactly where they are.

Needs inventory:write; writes; answers with before and after.

move_inventory_category — Move a shopping section up or down

Move one of the person’s own sections one place earlier (-1) or later (1) in the order the inventory draws them. Its way back is the opposite move.

Needs inventory:write; writes; answers with before and after.

remove_inventory_category — Delete a shopping section

Delete a section. Its items are not touched — they stay on the list, just unfiled. A section is a shelf label, and removing the label must not empty the shelf.

Needs inventory:write and destructive; deletes; answers with before and after.

record_price — Record what an item cost

Write down what was paid for a shopping item — "milk was 6,50 today". The list keeps a small price history per item, which is how it can notice drift. Takes the id shopping_list gives, and the price as the person said it.

Needs inventory:write; writes; answers with before and after.

add_goal — Write down a goal they made

Transcribe a goal the person just committed to, in their own words — "apply to twenty companies this quarter". Never invent one, and never add a goal they did not say: a goal is a commitment, and the commitment is theirs. goal_areas lists the areas one can be filed under.

Needs tasks:write; writes; answers with before and after, after being the new goal.

log_goal_progress — Move a goal’s number

Record progress on a goal that counts something: pass value to set where it stands, or delta to add what just happened — "I sent three more CVs" is delta: 3. Exactly one of the two. A goal measured by several things also needs unit, to say which of them moved; goals shows them and where each stands.

Needs tasks:write; writes; answers with before and after.

add_goal_target — Add something a goal is measured by

Give a goal another measure — "and fifty kilometres run". Leaves the measures already on it alone, and starts at zero. goals shows what it is measured by.

Needs tasks:write; writes; answers with before and after.

remove_goal_target — Take a measure off a goal

Drop one of the things a goal is measured by, by its unit. The goal and its other measures stay. For a measure that was a mistake — one that simply did not happen is what close_goal is for.

Needs tasks:write and destructive; deletes; answers with before and after.

goal_areas — The areas goals are filed under

The areas of life a goal can belong to — career, health, whatever the person keeps. Read it before filing a goal; add_goal_area makes a missing one.

Needs tasks:read; read-only.

Takes no parameters.

add_goal_area — Add a goal area

Make a new area to file goals under. Only when the person named one that does not exist — goal_areas says what already does.

Needs tasks:write; writes; answers with before and after.

change_goal_area — Rename or recolour a goal area

Rename an area, or change its colour. Only id is needed: a field left out is untouched. A name another area already has is refused rather than merged. The goals filed under it stay where they are.

Needs tasks:write; writes; answers with before and after.

move_goal_area — Move a goal area up or down

Move an area one place earlier (delta: -1) or later (delta: 1) in the order goal_areas lists them, which is the order the app shows them in. Moving the first one earlier, or the last one later, changes nothing.

Needs tasks:write; writes; answers with before and after.

all_habits — Every habit

The full list of habits, due today or not — id, name, type and which days each is scheduled. habits is today’s view with streaks; this is the one to read before adding or changing one. Archived habits are left out unless includeArchived is set; those carry an archivedAt.

Needs habits:read; read-only.

add_habit — Add a habit

Start tracking a habit: something to keep doing (good), to avoid (bad), or just to watch (neutral). Scheduled days come in the same shape all_habits shows for existing ones; leave them out for every day.

Needs habits:write; writes; answers with before and after, after being the new habit.

change_habit — Change a habit

Rename a habit or change its type, description or days. Only id is needed: a field left out is untouched. An empty description clears it; an empty scheduledDays clears the days. Its history of kept days stays exactly as it was.

Needs habits:write; writes; answers with before and after.

archive_habit — Put a habit away

Stop tracking a habit without losing it: it leaves today’s list and the room, and every logged day is kept. unarchive_habit brings it back.

Needs habits:write; writes; answers with before and after.

unarchive_habit — Bring a habit back

Start tracking an archived habit again, with its history as it was. all_habits with includeArchived lists the archived ones.

Needs habits:write; writes; answers with before and after.

reminders — What will reach out, and when

Everything set to go off, soonest first: reminders on blocks, alarms about nothing in particular, birthdays, bills that want paying, and a weekly review left open. subjectKind says which. Include the past to see what already fired.

Needs schedule:read; read-only.

set_alarm — Set a reminder about nothing else

A time and a sentence, reaching the phone even with the app closed — "take the bread out at ten past", "ring mum at six". Use this when there is nothing to schedule; when the reminder is about something already on the day, remind_before_block hangs it on that block instead, which keeps the two together. cancel_alarm takes it back.

Needs schedule:write; writes; answers with before and after.

change_reminder — Change a reminder that is already set

Move a reminder, reword it, or change whether it makes a noise — the one set_alarm made, or a nudge before a block. Send only what changes; anything left out stays as it is, and nothing is written unless all of it is valid. sound: null hands the choice back to the default. Takes the id reminders gives.

Needs schedule:write; writes; answers with before and after.

cancel_alarm — Take a reminder back

Remove a reminder outright — the one set_alarm made, or any other. dismiss_reminder waves one off and leaves the row; this deletes it. Takes the id reminders gives.

Needs schedule:write and destructive; deletes; answers with before and after.

remind_task — Ring about a todo at a time

A reminder about one todo, at a time, reaching the phone even with the app closed — "remind me at six to send this". Says the todo’s title unless message says otherwise, and pressing it opens the todo list. The todo stays undated; schedule_task is for putting it on a day. change_reminder and cancel_alarm take the answer’s id.

Needs tasks:write; writes; answers with before and after.

remind_before_block — Set a reminder on a block

Be told some minutes before a block starts — it reaches the phone even with the app closed. A reminder belongs to a block: for "remind me at three to call the dentist", first add_block the call at three, then set the reminder on it. Takes the id the day gives, like slot:42.

Needs schedule:write; writes; answers with before and after.

dismiss_reminder — Dismiss a reminder

Wave one reminder off so it does not fire — for "no need to remind me about that any more". Takes the id reminders gives; the block it sat on is untouched.

Needs schedule:write; writes; answers with before and after.

repeating_week — The week as it repeats

The blocks that make up every week — each with its weekday, time, length and category. Weekdays are numbered from Monday: 0 is Monday, 6 is Sunday. Not all of them are weekly: repeats says in words how often each one comes back, which can be every N weeks, every N days, or a day of the month. This is the template the days are generated from; today and upcoming show what it produced. Read it before changing Tuesdays rather than a Tuesday.

Needs schedule:read; read-only.

add_repeating_block — Put a task block on every week

Add a block that comes back — "gym on Tuesdays at seven", "the bins every other Tuesday", "rent on the first". Weekly unless repeats says otherwise. This changes every week from now on; add_block is the one for a single day. Weekdays count from Monday: 0 is Monday, 6 is Sunday. A block can be a bare category rather than a named thing — leave the title out and it shows as the category itself, which is what "put work in those hours" means.

Needs schedule:write; writes; answers with before and after, after being the new repeatingBlock.

change_repeating_block — Change a repeating task block

Change every future occurrence of a repeating block: its weekday, time, length, how often it comes back, the text on it, its category, its reminder, its notebook or its attributes — or pause and resume it. This is "move gym to Wednesdays" or "make it every other week"; change_block is "move this Wednesday’s gym". Only id is needed: a field left out is untouched, and nothing is written unless all of it is valid. An empty title takes the text off. Takes the id repeating_week gives.

Needs schedule:write; writes; answers with before and after.

remove_repeating_block — Take a block out of the week

Remove a repeating block from every week to come. Its past occurrences and their record stay. For one day only, use cancel_block instead — this is the whole pattern.

Needs schedule:write and destructive; deletes; answers with before and after.

categories — The parts of a life

The categories blocks are filed under — the areas of this person’s life, each with its colour. Read it before writing a block, so the name is real rather than guessed.

Needs schedule:read; read-only.

Takes no parameters.

activities — The named recurring things

Activities are the named things inside categories — "piano", not just "music". A block can name one instead of a bare category. add_activity and change_activity write them.

Needs schedule:read; read-only.

Takes no parameters.

add_activity — Name a new recurring thing

Add an activity — a named thing inside a category, like "piano" inside "music" — so blocks can name it instead of the bare category.

Needs schedule:write; writes; answers with before and after, after being the new activity.

change_activity — Rename an activity, or say what it is

Change an activity: its name, the line describing it, which category it belongs to, or whether it is switched on. Takes the id activities gives. Only id is needed: a field left out is untouched. Blocks that name it follow the change; nothing on any day is moved.

Needs schedule:write; writes; answers with before and after.

remove_activity — Delete an activity

Delete an activity, used or not. Without moveTo, every block that named it becomes a block of its category labelled with its name, past occurrences keep the name, and goals stop counting it. With moveTo, all of it — blocks, occurrences, goal links — names that activity instead. To keep it as it is, switch it off with change_activity and active: false.

Needs schedule:write and destructive; deletes; answers with before and after.

people — The people in their life

Everybody the person keeps a page for — name, relationship, birthday, contact details. These are other people’s facts held in this account, which is why they sit behind their own permission.

Needs people:read; read-only.

Takes no parameters.

upcoming_birthdays — Whose birthday is coming

Birthdays in the days ahead, soonest first — the answer to "whose birthday is coming up". Only people with a birthday written down appear.

Needs people:read; read-only.

add_person — Add a person

Keep a page for somebody — name at minimum; birthday as YYYY-MM-DD, or --MM-DD when the year is unknown. A birthday written down announces itself on the morning, unless told not to.

Needs people:write; writes; answers with before and after, after being the new person.

change_person — Change a person’s page

Correct or extend what is recorded about somebody — a birthday learnt, a number changed. Only id is needed: a field left out is untouched, and an empty string clears a birthday, phone, email or notes. Takes the id people gives.

Needs people:write; writes; answers with before and after.

daily_wins — Three things that went well

The day’s three wins, as written. A practice, not a log: three lines a day, and blank ones are simply not written yet.

Needs notes:read; read-only.

record_win — Record a win

Write one of the day’s three good things, in the person’s own words, into the first empty line. Refused when all three are written — a day holds three, and the fourth is tomorrow’s first.

Needs notes:write; writes; answers with before and after.

weekly_review — How a week actually went

A week read whole: planned against done, by category, with the three lines written about it. The heart of the app — this is what the Monday mail says, and what closing a week means. Defaults to the week now running.

Needs tasks:read; read-only.

write_review_note — Write the week’s note

Replace the note on a week’s review — in the person’s own words, and only when they said them. This is what they will reread in a year; never compose it unasked. It used to be three separate lines and is one piece of writing now, so a note somebody dictates in three sentences is stored as they said it.

Needs tasks:write; writes; answers with before and after.

data_streams — The numbers being tracked

The account’s data streams — weight, mood, sleep, anything a plugin or a person logs over time — each with its slug, kind and unit. log_data_point writes into one by its slug.

Needs streams:read; read-only.

Takes no parameters.

log_data_point — Log a reading

Write one point into a data stream — "I weigh 82 today", "slept 6 hours". Takes the stream’s slug as data_streams gives it; a slug that names nothing is refused with the list, never created on the quiet.

Needs streams:write; writes; answers with before and after.

apply_idea — Mark an idea applied

Say an idea was acted on, with a note about what came of it — or take that back by calling it again. Applied is not deleted: the idea stays, wearing what happened.

Needs ideas:write; writes; answers with before and after.

favorite_idea — Star an idea

Star an idea, or unstar it by calling this again. A star is the person’s to ask for — never decorate their inbox on your own judgement.

Needs ideas:write; writes; answers with before and after.

where_is — Where a thing lives

Find a thing by name and say where it lives — "Living room › White chest › First drawer" — with its fields (a tape’s length, a cable’s plug). The inventory half of the shopping list.

Needs locations:read; read-only.

locations — The locations tree

Every location, nested the way the house is — rooms holding furniture holding drawers — each with how many things sit directly in it.

Needs locations:read; read-only.

Takes no parameters.

add_location — Add a location

Add a location things can live in — a room, a chest, a drawer — optionally inside another location.

Needs locations:write; writes; answers with before and after, after being the new location.

change_location — Rename or move a location

Rename a location, or move it under a different parent. Only id is needed: a field left out is untouched, its notes included. parent_id of 0 or null moves it to the top level. It refuses to be put inside itself.

Needs locations:write; writes; answers with before and after.

remove_location — Remove a location

Remove a location. Locations inside it rise to where it was; things in it stay, just without an address.

Needs locations:write and destructive; deletes; answers with before and after.

put_item — Say where a thing lives

Put a shopping/inventory item in a location, or take its address away by leaving location_id out. The item itself is untouched.

Needs locations:write; writes; answers with before and after.

set_item_attributes — Set a thing’s attributes

Replace an item’s attributes wholesale — { "length": "5m", "plug": "USB-C" }. Not every thing shares a shape; these are this thing’s. A name with an empty value is a whole attribute: "cable" says as much as "kind": "cable". Send the full set: removing one is writing the rest.

Needs inventory:write; writes; answers with before and after.

inventory_attributes — What the things say about themselves

Every attribute the account’s things carry — "length", "brand" — with how many things carry it, the values it takes, and any colour given to either. Read it before renaming or removing one.

Needs inventory:read; read-only.

Takes no parameters.

change_inventory_attribute — Rename or recolour an attribute

Rename an attribute on every thing that carries it — or merge it into another by renaming onto that name — or, with value, rename or recolour just that value of it. color is #rrggbb; an empty string takes the colour off. Its way back is the opposite rename.

Needs inventory:write; writes; answers with before and after.

remove_inventory_attribute — Take an attribute off everything

Take an attribute off every thing that carries it, or with value, only off the things that say that value. The things themselves stay. set_item_attributes puts one back on a thing.

Needs inventory:write and destructive; deletes; answers with before and after.

workouts — Your workouts

The workouts you have written down, under Health. Each has a category and a plan; put one on the week with add_block and its workoutId to have it planned like a meal.

Needs workouts:read; read-only.

set_workout_measures — Say what a workout measures

Declare what a workout is measured by — a run by kilometres and a pace, a push day by what was benched and for how many reps. Names and units only; no amounts. Replaces the list it has, so send all of them. A session may still measure anything: this decides what its form opens on.

Needs workouts:write; writes; answers with before and after.

workout_sessions — What was actually done

Sessions, newest first: the day, anything noted, and lines of activity, amount and unit in the person’s own words — ran 5 km, deadlifted 120 kg. Narrow it with workout_id or since rather than reading everything.

Needs workouts:read; read-only; answers a page.

log_workout — Write down a session

Record that a workout happened, and how much of what was done. Everything but the workout is optional: a session with no lines is one that happened. Use the person’s own words and units — "ran" and "km", not a normalised distance — because that is what a chart of it will be grouped by. workout_sessions shows what they have called things before.

Needs workouts:write; writes; answers with before and after, after being the new workoutSession.

change_workout_session — Correct a session

Rewrite a session that was written down wrong. Only id is needed: a field left out is untouched. The lines are replaced by the ones given, so send them all; leaving measures off keeps the ones it has, and [] removes them. An empty notes clears the notes. The session and its lines land together or not at all.

Needs workouts:write; writes; answers with before and after.

remove_workout_session — Remove a session

Delete a session that was logged by accident. Its lines go with it; the workout itself stays. For correcting one rather than removing it, use change_workout_session.

Needs workouts:write and destructive; deletes; answers with before and after.

workout_history — One activity over time

Every time one activity was measured, oldest first — the shape to draw or to compare against. workout_activities lists what this account has measured and how often, which is where the name comes from.

Needs workouts:read; read-only.

workout_activities — What this account measures

Every activity and unit that has ever been written down, with how many times — the names workout_history takes, and the ones to reuse when logging so a chart groups them together.

Needs workouts:read; read-only.

Takes no parameters.

workout_categories — The categories of workout this account keeps

The categories a workout can be filed under — this account’s own list, not a fixed one. add_workout and change_workout take a category_id from here.

Needs workouts:read; read-only.

Takes no parameters.

add_workout_category — Add a category of workout

Add a category to this account’s list — "Swimming", "Physio". Answering with one that already exists returns it rather than making a second.

Needs workouts:write; writes; answers with before and after, after being the new workoutCategory.

change_workout_category — Rename a category of workout

Rename one of the account’s workout categories. The workouts filed under it stay filed under it.

Needs workouts:write; writes; answers with before and after.

remove_workout_category — Remove a category of workout

Take a category off the list. Workouts filed under it keep existing, without one.

Needs workouts:write and destructive; deletes; answers with before and after.

add_workout — Add a workout

Write a workout down: a title, a category (one of the account’s own, from workout_categories), a plan as Markdown, and roughly how long it takes. Scheduling it onto a day is a block with its workoutId, the way a meal is a block with a recipe.

Needs workouts:write; writes; answers with before and after, after being the new workout.

change_workout — Change a workout

Rewrite a workout — for a misheard word or a better plan, not to turn it into a different session. Only id is needed: a field left out is untouched. An empty string clears the plan or the notes; 0 or null clears minutes or category_id.

Needs workouts:write; writes; answers with before and after.

archive_workout — Put a workout away, or bring it back

Take a workout out of the working list, or restore it. Nothing is lost either way — its history stays.

Needs workouts:write; writes; answers with before and after.

workout_done — Mark a workout done

Record that a workout happened just now — the gym’s version of marking a recipe cooked. It stamps the last-done time.

Needs workouts:write; writes; answers with before and after.

budgets — Monthly category budgets

Allocated, spent, remaining and separate refund credits for one month in original currencies. Budgets do not move money. Orphaned categories remain visible. Defaults to the account’s current month.

Needs statements:read; read-only; answers a page.

add_budget — Set a monthly category ceiling

Create a ceiling for one category, month and original currency with an owned ledger. Exact nonnegative minor units. No bank movement, stock entry or reserve is created.

Needs statements:write; writes; answers with before and after, after being the new budget.

change_budget — Change a budget ceiling

Change only named budget fields. Omitted values stay unchanged. ifUpdatedAt refuses stale edits; no bank or stock record changes.

Needs statements:write; writes; answers with before and after.

delete_budget — Remove a budget ceiling

Remove only a monthly ceiling. The before state is retained for recovery; bank history and spending remain unchanged.

Needs statements:write and destructive; deletes; answers with before and after.

copy_budgets — Copy missing monthly budgets

Copy ceilings between civil months in one transaction. Existing category/currency buckets are never overwritten. Returns added and skipped counts; no money moves.

Needs statements:write; writes; answers with before and after.

personal_spending — Personal spending and exclusions

Original-currency groups of gross expenses, refunds, signed net spending, personal income, transfer and cash exclusions, custody shares and unclassified counts. Refunds follow their actual date and parent category, never income. No balance or available-funds claim. Without a window reports the last 12 calendar months.

Needs statements:read; read-only.

summary — The money picture

One answer to the four money questions — what is mine, what is committed, what I spent this month and what is left against my plans — for every original currency separately, never a combined total. Funds, stocks (custody, reserves, payables, receivables), personal spending with its exclusions, and the month’s budgets. Available is funds minus custody minus reserves, never payables or receivables. Gaps such as an account without a declared opening or unclassified lines are named, not hidden in a confident number.

Needs statements:read; read-only.

commitments — What you owe, hold and set aside

Custody, payables, receivables and reserves are stocks, not bank movements or budgets. Each balance is its opening plus entries, in its own currency. Totals stay separate by kind and currency; never subtract payables or add receivables to available bank funds.

Needs statements:read; read-only; answers a page.

commitment_entries — A commitment’s history

Entries and running balances for one commitment. Positive increases the obligation or earmark; negative reduces it. Linked movements remain in their original ledgers.

Needs statements:read; read-only; answers a page.

add_commitment — Record money owed, held or set aside

Create a stock without moving money: custody is held for someone, payable is owed, receivable is owed to you, reserve is your earmark. Currency is explicit ISO 4217; opening_minor is nonnegative original-currency minor units. No bank line or expense is created.

Needs statements:write; writes; answers with before and after, after being the new commitment.

change_commitment — Correct a commitment

Edit the fields originally recorded. Omitted fields stay untouched; person_id 0 clears the person. Currency, kind and opening changes cannot invalidate retained history. Settlements and adjustments belong in entries, not in an invented bank movement.

Needs statements:write; writes; answers with before and after.

archive_commitment — Put a commitment away or reopen it

Archive without losing history. archived false reopens it. No balance or bank line changes.

Needs statements:write; writes; answers with before and after.

close_commitment — Close a settled commitment

Close a zero balance. A nonzero balance is refused unless write_off_note explicitly authorizes and explains an entry removing the residual. No ledger adjustment is made. archive_commitment with archived false reopens the record; undo any write-off separately through its entry.

Needs statements:write; writes; answers with before and after.

record_commitment_entry — Record a stock adjustment

One dated adjustment in signed minor units: positive increases, negative reduces. An optional transaction_id links real evidence and must obey its currency, sign and allocation guards; use settle_commitment or consume_reserve for a payment. Nothing moves in the ledger. delete_commitment_entry reverses a mistake.

Needs statements:write; writes; answers with before and after, after being the new commitmentEntry.

delete_commitment_entry — Reverse a mistaken commitment entry

Remove one mistaken stock entry, restoring its effect on the commitment. Refuses an invalid resulting balance. Movement and allocations stay intact; explicitly unsplit afterward if needed. The owner can Put it back from the assistant log through the same validated entry service.

Needs statements:write and destructive; deletes; answers with before and after.

settle_commitment — Offset or settle with an existing payment

Apply one owned, same-currency bank movement to custody, payable or receivable once. Refuses overpayment and duplicate evidence. An owner’s expense becomes custody allocation, not personal spending. This never creates or changes a bank amount. Reverse its entry explicitly, then unsplit the movement.

Needs statements:write; writes; answers with before and after.

consume_reserve — Use a reserve for an existing expense

Reduce a reserve once using a same-currency expense or fee already recorded. The payment stays personal spending exactly once. Refuses overconsumption, duplicate evidence or a custody split. Reverse the entry to undo; ledger truth stays unchanged.

Needs statements:write; writes; answers with before and after.

split_movement — Split personal and third-party money

Partition a movement without altering its amount. Signed allocation amounts must have its sign and add exactly to it. Personal parts may override category. Each custody part requires an owned same-currency custody/payable commitment and atomically records one matching entry. Refuses replacement while linked entries remain.

Needs statements:write; writes; answers with before and after.

unsplit_movement — Make a movement whole again

Remove allocations only after every linked entry is explicitly reversed. The original movement and ledger amount never change.

Needs statements:write; writes; answers with before and after.

ledgers — Your ledgers

Accounts with original currency, declared opening, as-of supported amount, outside-coverage count and recorded/supported/verified evidence status. No opening means supportedMinor is null. balanceCents is retained only as a legacy recorded subtotal, never a bank balance; use recordedMinor. Unknown currency stays unspecified and is never converted.

Needs statements:read; read-only.