Module read 

The tools that read: what came, mail, tasks, the agenda, contacts, budgets, notes, projects and links. Each reads the files as the command line does (main, tasks, dav), and Sioul’s own sentences come in the configuration’s language. The labels and hints meant for the agent alone (“From”, “not found”) are English, as the tools’ descriptions are.

What others wrote (mail, invitations, contacts, file names, and notes) comes as data: on one line each where a line is one thing, and a message’s or a note’s own text between two lines that carry a mark made for that answer, which the text’s author cannot know, so cannot close.

Each keeps to what the person opened to agents (access): a closed project’s things, and things in no project while those are closed, are left out of every list, counted, never named; asked for by name, refused.

Structs

Desk 🔒

Tasks, the plan and the day, read once, as the command line’s tasks reads them.

Shield 🔒

Hostile mail to a shielded address, as the Porch judges it (the AI’s reading first, when it read it): its sender’s name, its subject and its words are kept from agents, as the Porch keeps them (docs/mcp.md).

Constants

LONGEST 🔒

Characters of a message or a note given at most: a long newsletter is not read whole.

MARGIN 🔒

Characters read and masked past what is given: a number or a code that the cut goes through is still known whole, and hidden whole.

Functions

agenda

budgets

card_lines 🔒

A task in lines, as sioul tasks prints it, with its UID.

find

find_message 🔒

A message’s file, by its key (its file, as the Porch and search give it) or its Message-ID; only inside the configured accounts’ mail, wherever its flags have moved it since.

find_task 🔒

A task by UID, else by the start of its title, else by a word of it; one only.

finding_label 🔒

The label a finding of the money watch names.

finding_text 🔒

What the money watch noticed, in a sentence, as the Budgets page says it.

folded 🔒

framed 🔒

Someone else’s words, between two lines that carry a mark made for this answer: whatever they say, they cannot end the frame and speak as Sioul.

given 🔒

A text read up to LONGEST characters and a margin, masked, as it is given: cut where the agent’s part ends, saying how much is left; total is how long the whole text was.

head 🔒

The first characters of a text, and how long it is.

holds 🔒

Whether text holds every word.

instant 🔒

Unix seconds as a moment in the person’s time zone, for data: “2026-10-05T09:00:00+02:00”.

judged 🔒

A message as the Porch judges it, with its account’s trusted checks, and the AI’s reading of a shielded address’s mail; none from a blocked sender.

lane_title 🔒

A lane’s title, as the Porch shows it.

lexical 🔒

A path with its “.” and “..” taken away as they are written, without asking the system (which may follow a link, or reach another computer).

links

list_projects

list_tasks

mail_consent 🔒

What the person opened to agents, for mail: the projects, their routes and Sioul’s ties.

mail_index 🔒

Every message’s headers, by Message-ID, from the same Maildirs and cache as links read.

mail_shown 🔒

A message’s title and detail (its sender) as an agent sees them, wherever it is listed: its subject masked with what its text says (a code in the subject, its phrase below); nothing of either when it is hostile mail to a shielded address.

mark 🔒

A mark nobody can guess, made for one answer: twelve letters (no digit, so that no mask can take it for a number).

masked_item 🔒

A Porch item’s subject and preview, masked; nothing of hostile mail, no preview of rude mail.

message_answer 🔒

open_ledger 🔒

The budgets’ file as an agent may see it: the budgets, their lines and their recurring payments kept from agents taken out, a line tied to a closed project too; reserves only while things outside projects are open. Returns it, how many budgets and lines were left out, and the labels of those lines (what the money watch would name).

open_related 🔒

Things tied to another, those kept from agents taken out; and how many.

open_tasks 🔒

“No task open”, “One task open”, “3 tasks open”.

place_of 🔒

The account whose mail a file is, and the folder it is in (“” for the inbox), however the paths are written (~, relative, through a link).

porch

The Porch, as sioul porch shows it, its codes left out.

read_message

read_note

related_rows 🔒

Related things as data, a message’s subject as an agent sees it.

rows 🔒

Lines of an answer, each one line whatever the words in it: what others wrote (a subject, a name, a title) cannot break one, nor add one.

search_contacts

search_mail

search_notes

tasks_list 🔒

tasks_now 🔒

tasks_today 🔒

Today laid out, as the Today page shows it: events at their times, the plan’s steps in the gaps.

words 🔒

The words of a query, folded: case and accents aside.