synapse_instructions — Manual

What it does

Reads and updates the user's standing instructions for Synapse reactions — the rules Navi follows when a platform event (mail, a todo, a Telegram message) arrives while nobody is watching. They are the user's own words, kept per user in the database, and both the user and you may refine them.

There are two documents, selected by doc:

`doc`	Holds	Read by
`reaction` (default)	What to do: which events deserve a reaction, what the reaction should be, what to leave alone.	The reaction run itself — read it before acting on a Synapse event.
`dispatcher`	Where it goes: which kind of event belongs to which profile, and what counts as one conversation.	The dispatcher meta-pass only — the hidden one-shot call that picks a profile and shapes the task.

The two never mix: routing text in reaction clutters the run's own prompt, and reaction detail in dispatcher makes the router guess. Put a rule where its reader is.

One rule travels the other way: what counts as one conversation (the key that keeps a Telegram chat in one session) is read from whichever document states it, so a rule left in reaction is still honoured — but dispatcher is where it belongs, and it is the document that also has to say which profile handles the event. A profile named there is matched by name as well as by id, and it has to be one the delivery account's role may use: an admin's events may be routed to an admin-only profile, a regular user's may not, and a refusal is logged rather than applied silently.

Parameters

Parameter	Required	Description
`op`	yes	`read` \	`update`.
`doc`	no	`reaction` (default) \	`dispatcher`.
`content`	for `update`	The full new text of the document — it replaces the current one, it is not appended.
`reason`	for `update`	One sentence: why the rules changed.

{"op": "read", "doc": "dispatcher"}
{"op": "update", "doc": "reaction", "content": "Todo events from gntodo: summarise and report. Marketing mail: ignore.", "reason": "The user asked to stop reacting to newsletters."}

read on an empty document answers that nothing is configured yet — that is a success, not an error. The call fails only when there is no user context in the run, when doc is neither of the two, when op is unknown, or when update carries no content.

Rules

Read before acting. When a Synapse event is in front of you, read doc='reaction' first; the user's intent for that event is in there, and it is more authoritative than your judgement about what the event deserves.
Update only what was asked for, and say why. Every edit is recorded with edited_by='navi' and your reason, and the user reviews that history — an edit they did not want is visible, and one with no reason looks arbitrary.
update replaces the whole document. Read it first, then send the full new text; sending only the new paragraph silently deletes everything else.
Prefer rewriting the rule to piling on exceptions. A document that says "in this case do X" three times is trying to say one thing badly.
The conversation key belongs to dispatcher. When the user wants a chat (a Telegram thread, a ticket) to stay in one session, the routing document is where that rule goes — the reaction run cannot decide it.