Recalo

Create a rich page (a sequence of markdown and noun_ref blocks). Do NOT inline to-do checkboxes in markdown — create a checklist noun and reference it with a noun_ref block instead. Returns a link to the new page. To EDIT a page that already exists, do not create again — fetch it and use recalo-update-page. Pass the links it came from in `sources`.

recalo-create-page

Apply a JSON Patch (RFC 6902) to an entry's data — surgical, so you change only what you mean to without resending the rest. Fetch the entry first (recalo-fetch); pass its `id`, the `version` you fetched (optimistic concurrency — stale → you'll be told to fetch again), and a `patch` array (or only `sources`). Ops: add, remove, replace, move, copy. Paths are JSON Pointer against `data`: "/title", "/ingredients/2/quantity", "/ingredients/-" (append). Checklists: address an existing item or section by its `id`, not its position: "/items/<id>/checked", "/items/<id>", the same form for an item inside a section. Append with "/items/-", or "/items/<sectionId>/items/-" for a section. A position works only as an insert point ("/items/2", the `path` of add/move/copy); any other positional path is rejected. Replacing a whole entry must keep its `id` (copy it from data) or its reminder is lost. Several ops in one patch are fine: each id is looked up after the ops before it. Reorder with `move` ("from": "/items/<id>"); if you must remove+add, copy the existing item's `id` into the added value verbatim (omitting it mints a new id and cascade-deletes that item's reminder); brand-new items should omit `id` so the server assigns one. Movies, books and other entries saved from a lookup can't be edited; recipes, notes, checklists and entries saved with `data` can. Record personal data on a looked-up entry as events instead. To add a link, pass it in `sources` (a patch is optional then).

recalo-update-noun

Apply structured edits to a checklist and return its updated view. This is the channel the Recalo checklist card uses for its own controls — to edit a checklist on the user's behalf, use recalo-update-noun instead. New items and sections need a client-generated uuid.

recalo-checklist-edit

Fetch a single entity by its recalo:// URI. Supports recalo://noun/<id>, recalo://page/<id>, recalo://event/<id>, recalo://noun-type/<id>, recalo://docs/page-spec (the page block grammar — read it before authoring a page), and recalo://docs/help (how to use the Recalo app, where to download it, sharing, export — read it when the user asks about Recalo itself). A noun or page fetch lists `files` (when any): refs of the images the app read to write it, whether or not they appear in its content — pass any `/api/files/<uuid>` ref to recalo-get-file-urls to open it. It also lists `sources` (when any): the links it came from, each {url, role}, plus the post's author, summary and post_type when known. A noun fetch also returns its `events` (when any) — past and future, each with its id — plus a `hint` on how to change them (and, for a checklist, how to show it): for most entries pass an event id to recalo-update-event; for a checklist, edit the item via recalo-update-noun instead (that keeps its reminders in sync). Each noun fetch reports `permission`: `owner` or `edit` means you may change it; `view` means it is read-only and any write will be refused.

recalo-fetch

Turn `/api/files/<uuid>` refs from any fetched entry — an image in a page, a photo on an event, an entry's `files` — into temporary URLs you can open or show. Pass the refs verbatim. Each URL is valid for 24 hours; refs that are not the user's own ready images come back as `unavailable`.

recalo-get-file-urls

Look up authoritative metadata candidates for a movie, book, TV show, place or restaurant from external providers. Pass the `nounTypeSlug` and a `query` (a title or name). Returns candidates each with a `canonical_noun_id` — pick the right one(s) and pass them to `recalo-create-noun`. Subject to a daily limit.

recalo-lookup-metadata

Record something the user did or plans to do against an entry in their library. Pass the `nounId` the event is about, a `verbSlug` (e.g. "do", "watch", "read"), and `tense` ('past' or 'future'). Optionally attach a date via `eventLocal` + `datePrecision`, free-text `notes`, a `subject` (who did it) and `companions`. Dates use the user's timezone unless you pass `timezone`. To CHANGE an event that already exists (e.g. reschedule a reminder), do not record a new one — fetch the noun to get the event id and use recalo-update-event.

recalo-create-event

Remove access to one of the user's pages or checklists. `target` is one of: a share_id (a person who has access, or one sub-page grant of theirs from recipients[].scope), an invite_id (an invite not yet accepted), or `{ link: true }` to turn off the general-access link. Ids come from recalo-get-access. With `cascade` (default true) removing a person also removes their access to the sub-pages that were shared with it; a sub-page share_id removes just that one. Turning off a link does not remove people who already joined through it.

recalo-revoke-share

Create an entry in the user's library. `nounTypeSlug` is one of the types in the Recalo type catalog. The type's schema, fetched with `recalo-fetch recalo://noun-type/<slug>`, defines the required fields (e.g. `cover_emoji`), field shapes, and date formats that `data` must match, so fetch it before a direct `data` create. Provide either `data` (a plain entry matching that schema) or `canonicalNounIds` (movies, shows, books and places: the ids chosen from a lookup; the first is the primary, the rest are merged into it). A movie, show or book the lookup can't find is saved with `data`, as is a new recipe. Returns a link to the new entry. A new variation of a recipe the user holds: `remixed_from` (its id) + `remix_prompt` + either `patch` (JSON Patch ops against its data) or full `data`. To change an existing entry, fetch it and use recalo-update-noun instead. Pass the links it came from in `sources`.

recalo-create-noun

Search the user's Recalo library. Accepts one or more queries (fanned out, bounded) and returns matching nouns grouped per query, with user-facing links.

recalo-search