# 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.

## 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. |

```json
{"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.