nodmix 2026.5.25

package/docs/channels/matrix-migration.md

@@ -0,0 +1,370 @@
+---
+summary: "How Nodmix upgrades the previous Matrix plugin in place, including encrypted-state recovery limits and manual recovery steps."
+read_when:
+  - Upgrading an existing Matrix installation
+  - Migrating encrypted Matrix history and device state
+title: "Matrix migration"
+---
+
+Upgrade from the previous public `matrix` plugin to the current implementation.
+
+For most users, the upgrade is in place:
+
+- the plugin stays `@nodmix/matrix`
+- the channel stays `matrix`
+- your config stays under `channels.matrix`
+- cached credentials stay under `~/.nodmix/credentials/matrix/`
+- runtime state stays under `~/.nodmix/matrix/`
+
+You do not need to rename config keys or reinstall the plugin under a new name.
+
+## What the migration does automatically
+
+When the gateway starts, and when you run [`nodmix doctor --fix`](/gateway/doctor), Nodmix tries to repair old Matrix state automatically.
+Before any actionable Matrix migration step mutates on-disk state, Nodmix creates or reuses a focused recovery snapshot.
+
+When you use `nodmix update`, the exact trigger depends on how Nodmix is installed:
+
+- source installs run `nodmix doctor --fix` during the update flow, then restart the gateway by default
+- package-manager installs update the package, run a non-interactive doctor pass, then rely on the default gateway restart so startup can finish Matrix migration
+- if you use `nodmix update --no-restart`, startup-backed Matrix migration is deferred until you later run `nodmix doctor --fix` and restart the gateway
+
+Automatic migration covers:
+
+- creating or reusing a pre-migration snapshot under `~/Backups/nodmix-migrations/`
+- reusing your cached Matrix credentials
+- keeping the same account selection and `channels.matrix` config
+- moving the oldest flat Matrix sync store into the current account-scoped location
+- moving the oldest flat Matrix crypto store into the current account-scoped location when the target account can be resolved safely
+- extracting a previously saved Matrix room-key backup decryption key from the old rust crypto store, when that key exists locally
+- reusing the most complete existing token-hash storage root for the same Matrix account, homeserver, and user when the access token changes later
+- scanning sibling token-hash storage roots for pending encrypted-state restore metadata when the Matrix access token changed but the account/device identity stayed the same
+- restoring backed-up room keys into the new crypto store on the next Matrix startup
+
+Snapshot details:
+
+- Nodmix writes a marker file at `~/.nodmix/matrix/migration-snapshot.json` after a successful snapshot so later startup and repair passes can reuse the same archive.
+- These automatic Matrix migration snapshots back up config + state only (`includeWorkspace: false`).
+- If Matrix only has warning-only migration state, for example because `userId` or `accessToken` is still missing, Nodmix does not create the snapshot yet because no Matrix mutation is actionable.
+- If the snapshot step fails, Nodmix skips Matrix migration for that run instead of mutating state without a recovery point.
+
+About multi-account upgrades:
+
+- the oldest flat Matrix store (`~/.nodmix/matrix/bot-storage.json` and `~/.nodmix/matrix/crypto/`) came from a single-store layout, so Nodmix can only migrate it into one resolved Matrix account target
+- already account-scoped legacy Matrix stores are detected and prepared per configured Matrix account
+
+## What the migration cannot do automatically
+
+The previous public Matrix plugin did **not** automatically create Matrix room-key backups. It persisted local crypto state and requested device verification, but it did not guarantee that your room keys were backed up to the homeserver.
+
+That means some encrypted installs can only be migrated partially.
+
+Nodmix cannot automatically recover:
+
+- local-only room keys that were never backed up
+- encrypted state when the target Matrix account cannot be resolved yet because `homeserver`, `userId`, or `accessToken` are still unavailable
+- automatic migration of one shared flat Matrix store when multiple Matrix accounts are configured but `channels.matrix.defaultAccount` is not set
+- custom plugin path installs that are pinned to a repo path instead of the standard Matrix package
+- a missing recovery key when the old store had backed-up keys but did not keep the decryption key locally
+
+Current warning scope:
+
+- custom Matrix plugin path installs are surfaced by both gateway startup and `nodmix doctor`
+
+If your old installation had local-only encrypted history that was never backed up, some older encrypted messages may remain unreadable after the upgrade.
+
+## Recommended upgrade flow
+
+1. Update Nodmix and the Matrix plugin normally.
+   Prefer plain `nodmix update` without `--no-restart` so startup can finish the Matrix migration immediately.
+2. Run:
+
+   ```bash
+   nodmix doctor --fix
+   ```
+
+   If Matrix has actionable migration work, doctor will create or reuse the pre-migration snapshot first and print the archive path.
+
+3. Start or restart the gateway.
+4. Check current verification and backup state:
+
+   ```bash
+   nodmix matrix verify status
+   nodmix matrix verify backup status
+   ```
+
+5. Put the recovery key for the Matrix account you are repairing in an account-specific environment variable. For a single default account, `MATRIX_RECOVERY_KEY` is fine. For multiple accounts, use one variable per account, for example `MATRIX_RECOVERY_KEY_ASSISTANT`, and add `--account assistant` to the command.
+
+6. If Nodmix tells you a recovery key is needed, run the command for the matching account:
+
+   ```bash
+   printf '%s\n' "$MATRIX_RECOVERY_KEY" | nodmix matrix verify backup restore --recovery-key-stdin
+   printf '%s\n' "$MATRIX_RECOVERY_KEY_ASSISTANT" | nodmix matrix verify backup restore --recovery-key-stdin --account assistant
+   ```
+
+7. If this device is still unverified, run the command for the matching account:
+
+   ```bash
+   printf '%s\n' "$MATRIX_RECOVERY_KEY" | nodmix matrix verify device --recovery-key-stdin
+   printf '%s\n' "$MATRIX_RECOVERY_KEY_ASSISTANT" | nodmix matrix verify device --recovery-key-stdin --account assistant
+   ```
+
+   If the recovery key is accepted and backup is usable, but `Cross-signing verified`
+   is still `no`, complete self-verification from another Matrix client:
+
+   ```bash
+   nodmix matrix verify self
+   ```
+
+   Accept the request in another Matrix client, compare the emoji or decimals,
+   and type `yes` only when they match. The command exits successfully only
+   after `Cross-signing verified` becomes `yes`.
+
+8. If you are intentionally abandoning unrecoverable old history and want a fresh backup baseline for future messages, run:
+
+   ```bash
+   nodmix matrix verify backup reset --yes
+   ```
+
+9. If no server-side key backup exists yet, create one for future recoveries:
+
+   ```bash
+   nodmix matrix verify bootstrap
+   ```
+
+## How encrypted migration works
+
+Encrypted migration is a two-stage process:
+
+1. Startup or `nodmix doctor --fix` creates or reuses the pre-migration snapshot if encrypted migration is actionable.
+2. Startup or `nodmix doctor --fix` inspects the old Matrix crypto store through the active Matrix plugin install.
+3. If a backup decryption key is found, Nodmix writes it into the new recovery-key flow and marks room-key restore as pending.
+4. On the next Matrix startup, Nodmix restores backed-up room keys into the new crypto store automatically.
+
+If the old store reports room keys that were never backed up, Nodmix warns instead of pretending recovery succeeded.
+
+## Common messages and what they mean
+
+### Upgrade and detection messages
+
+`Matrix plugin upgraded in place.`
+
+- Meaning: the old on-disk Matrix state was detected and migrated into the current layout.
+- What to do: nothing unless the same output also includes warnings.
+
+`Matrix migration snapshot created before applying Matrix upgrades.`
+
+- Meaning: Nodmix created a recovery archive before mutating Matrix state.
+- What to do: keep the printed archive path until you confirm migration succeeded.
+
+`Matrix migration snapshot reused before applying Matrix upgrades.`
+
+- Meaning: Nodmix found an existing Matrix migration snapshot marker and reused that archive instead of creating a duplicate backup.
+- What to do: keep the printed archive path until you confirm migration succeeded.
+
+`Legacy Matrix state detected at ... but channels.matrix is not configured yet.`
+
+- Meaning: old Matrix state exists, but Nodmix cannot map it to a current Matrix account because Matrix is not configured.
+- What to do: configure `channels.matrix`, then rerun `nodmix doctor --fix` or restart the gateway.
+
+`Legacy Matrix state detected at ... but the new account-scoped target could not be resolved yet (need homeserver, userId, and access token for channels.matrix...).`
+
+- Meaning: Nodmix found old state, but it still cannot determine the exact current account/device root.
+- What to do: start the gateway once with a working Matrix login, or rerun `nodmix doctor --fix` after cached credentials exist.
+
+`Legacy Matrix state detected at ... but multiple Matrix accounts are configured and channels.matrix.defaultAccount is not set.`
+
+- Meaning: Nodmix found one shared flat Matrix store, but it refuses to guess which named Matrix account should receive it.
+- What to do: set `channels.matrix.defaultAccount` to the intended account, then rerun `nodmix doctor --fix` or restart the gateway.
+
+`Matrix legacy sync store not migrated because the target already exists (...)`
+
+- Meaning: the new account-scoped location already has a sync or crypto store, so Nodmix did not overwrite it automatically.
+- What to do: verify that the current account is the correct one before manually removing or moving the conflicting target.
+
+`Failed migrating Matrix legacy sync store (...)` or `Failed migrating Matrix legacy crypto store (...)`
+
+- Meaning: Nodmix tried to move old Matrix state but the filesystem operation failed.
+- What to do: inspect filesystem permissions and disk state, then rerun `nodmix doctor --fix`.
+
+`Legacy Matrix encrypted state detected at ... but channels.matrix is not configured yet.`
+
+- Meaning: Nodmix found an old encrypted Matrix store, but there is no current Matrix config to attach it to.
+- What to do: configure `channels.matrix`, then rerun `nodmix doctor --fix` or restart the gateway.
+
+`Legacy Matrix encrypted state detected at ... but the account-scoped target could not be resolved yet (need homeserver, userId, and access token for channels.matrix...).`
+
+- Meaning: the encrypted store exists, but Nodmix cannot safely decide which current account/device it belongs to.
+- What to do: start the gateway once with a working Matrix login, or rerun `nodmix doctor --fix` after cached credentials are available.
+
+`Legacy Matrix encrypted state detected at ... but multiple Matrix accounts are configured and channels.matrix.defaultAccount is not set.`
+
+- Meaning: Nodmix found one shared flat legacy crypto store, but it refuses to guess which named Matrix account should receive it.
+- What to do: set `channels.matrix.defaultAccount` to the intended account, then rerun `nodmix doctor --fix` or restart the gateway.
+
+`Matrix migration warnings are present, but no on-disk Matrix mutation is actionable yet. No pre-migration snapshot was needed.`
+
+- Meaning: Nodmix detected old Matrix state, but the migration is still blocked on missing identity or credential data.
+- What to do: finish Matrix login or config setup, then rerun `nodmix doctor --fix` or restart the gateway.
+
+`Legacy Matrix encrypted state was detected, but the Matrix plugin helper is unavailable. Install or repair @nodmix/matrix so Nodmix can inspect the old rust crypto store before upgrading.`
+
+- Meaning: Nodmix found old encrypted Matrix state, but it could not load the helper entrypoint from the Matrix plugin that normally inspects that store.
+- What to do: reinstall or repair the Matrix plugin (`nodmix plugins install @nodmix/matrix`, or `nodmix plugins install ./path/to/local/matrix-plugin` for a repo checkout), then rerun `nodmix doctor --fix` or restart the gateway.
+
+`Matrix plugin helper path is unsafe: ... Reinstall @nodmix/matrix and try again.`
+
+- Meaning: Nodmix found a helper file path that escapes the plugin root or fails plugin boundary checks, so it refused to import it.
+- What to do: reinstall the Matrix plugin from a trusted path, then rerun `nodmix doctor --fix` or restart the gateway.
+
+`- Failed creating a Matrix migration snapshot before repair: ...`
+
+`- Skipping Matrix migration changes for now. Resolve the snapshot failure, then rerun "nodmix doctor --fix".`
+
+- Meaning: Nodmix refused to mutate Matrix state because it could not create the recovery snapshot first.
+- What to do: resolve the backup error, then rerun `nodmix doctor --fix` or restart the gateway.
+
+`Failed migrating legacy Matrix client storage: ...`
+
+- Meaning: the Matrix client-side fallback found old flat storage, but the move failed. Nodmix now aborts that fallback instead of silently starting with a fresh store.
+- What to do: inspect filesystem permissions or conflicts, keep the old state intact, and retry after fixing the error.
+
+`Matrix is installed from a custom path: ...`
+
+- Meaning: Matrix is pinned to a path install, so mainline updates do not automatically replace it with the repo's standard Matrix package.
+- What to do: reinstall with `nodmix plugins install @nodmix/matrix` when you want to return to the default Matrix plugin.
+
+### Encrypted-state recovery messages
+
+`matrix: restored X/Y room key(s) from legacy encrypted-state backup`
+
+- Meaning: backed-up room keys were restored successfully into the new crypto store.
+- What to do: usually nothing.
+
+`matrix: N legacy local-only room key(s) were never backed up and could not be restored automatically`
+
+- Meaning: some old room keys existed only in the old local store and had never been uploaded to Matrix backup.
+- What to do: expect some old encrypted history to remain unavailable unless you can recover those keys manually from another verified client.
+
+`Legacy Matrix encrypted state for account "..." has backed-up room keys, but no local backup decryption key was found. Ask the operator to run "nodmix matrix verify backup restore --recovery-key-stdin" after upgrade if they have the recovery key.`
+
+- Meaning: backup exists, but Nodmix could not recover the recovery key automatically.
+- What to do: run `printf '%s\n' "$MATRIX_RECOVERY_KEY" | nodmix matrix verify backup restore --recovery-key-stdin`.
+
+`Failed inspecting legacy Matrix encrypted state for account "..." (...): ...`
+
+- Meaning: Nodmix found the old encrypted store, but it could not inspect it safely enough to prepare recovery.
+- What to do: rerun `nodmix doctor --fix`. If it repeats, keep the old state directory intact and recover using another verified Matrix client plus `printf '%s\n' "$MATRIX_RECOVERY_KEY" | nodmix matrix verify backup restore --recovery-key-stdin`.
+
+`Legacy Matrix backup key was found for account "...", but .../recovery-key.json already contains a different recovery key. Leaving the existing file unchanged.`
+
+- Meaning: Nodmix detected a backup key conflict and refused to overwrite the current recovery-key file automatically.
+- What to do: verify which recovery key is correct before retrying any restore command.
+
+`Legacy Matrix encrypted state for account "..." cannot be fully converted automatically because the old rust crypto store does not expose all local room keys for export.`
+
+- Meaning: this is the hard limit of the old storage format.
+- What to do: backed-up keys can still be restored, but local-only encrypted history may remain unavailable.
+
+`matrix: failed restoring room keys from legacy encrypted-state backup: ...`
+
+- Meaning: the new plugin attempted restore but Matrix returned an error.
+- What to do: run `nodmix matrix verify backup status`, then retry with `printf '%s\n' "$MATRIX_RECOVERY_KEY" | nodmix matrix verify backup restore --recovery-key-stdin` if needed.
+
+### Manual recovery messages
+
+`Backup key is not loaded on this device. Run 'nodmix matrix verify backup restore' to load it and restore old room keys.`
+
+- Meaning: Nodmix knows you should have a backup key, but it is not active on this device.
+- What to do: run `nodmix matrix verify backup restore`, or set `MATRIX_RECOVERY_KEY` and run `printf '%s\n' "$MATRIX_RECOVERY_KEY" | nodmix matrix verify backup restore --recovery-key-stdin` if needed.
+
+`Store a recovery key with 'nodmix matrix verify device --recovery-key-stdin', then run 'nodmix matrix verify backup restore'.`
+
+- Meaning: this device does not currently have the recovery key stored.
+- What to do: set `MATRIX_RECOVERY_KEY`, run `printf '%s\n' "$MATRIX_RECOVERY_KEY" | nodmix matrix verify device --recovery-key-stdin`, then restore the backup.
+
+`Backup key mismatch on this device. Re-run 'nodmix matrix verify device --recovery-key-stdin' with the matching recovery key.`
+
+- Meaning: the stored key does not match the active Matrix backup.
+- What to do: set `MATRIX_RECOVERY_KEY` to the correct key and run `printf '%s\n' "$MATRIX_RECOVERY_KEY" | nodmix matrix verify device --recovery-key-stdin`.
+
+If you accept losing unrecoverable old encrypted history, you can instead reset the
+current backup baseline with `nodmix matrix verify backup reset --yes`. When the
+stored backup secret is broken, that reset may also recreate secret storage so the
+new backup key can load correctly after restart.
+
+`Backup trust chain is not verified on this device. Re-run 'nodmix matrix verify device --recovery-key-stdin'.`
+
+- Meaning: the backup exists, but this device does not trust the cross-signing chain strongly enough yet.
+- What to do: set `MATRIX_RECOVERY_KEY` and run `printf '%s\n' "$MATRIX_RECOVERY_KEY" | nodmix matrix verify device --recovery-key-stdin`.
+
+`Matrix recovery key is required`
+
+- Meaning: you tried a recovery step without supplying a recovery key when one was required.
+- What to do: rerun the command with `--recovery-key-stdin`, for example `printf '%s\n' "$MATRIX_RECOVERY_KEY" | nodmix matrix verify device --recovery-key-stdin`.
+
+`Invalid Matrix recovery key: ...`
+
+- Meaning: the provided key could not be parsed or did not match the expected format.
+- What to do: retry with the exact recovery key from your Matrix client or recovery-key file.
+
+`Matrix recovery key was applied, but this device still lacks full Matrix identity trust.`
+
+- Meaning: Nodmix could apply the recovery key, but Matrix still has not
+  established full cross-signing identity trust for this device. Check the
+  command output for `Recovery key accepted`, `Backup usable`,
+  `Cross-signing verified`, and `Device verified by owner`.
+- What to do: run `nodmix matrix verify self`, accept the request in another
+  Matrix client, compare the SAS, and type `yes` only when it matches. The
+  command waits for full Matrix identity trust before reporting success. Use
+  `printf '%s\n' "$MATRIX_RECOVERY_KEY" | nodmix matrix verify bootstrap --recovery-key-stdin --force-reset-cross-signing`
+  only when you intentionally want to replace the current cross-signing identity.
+
+`Matrix key backup is not active on this device after loading from secret storage.`
+
+- Meaning: secret storage did not produce an active backup session on this device.
+- What to do: verify the device first, then recheck with `nodmix matrix verify backup status`.
+
+`Matrix crypto backend cannot load backup keys from secret storage. Verify this device with 'nodmix matrix verify device --recovery-key-stdin' first.`
+
+- Meaning: this device cannot restore from secret storage until device verification is complete.
+- What to do: run `printf '%s\n' "$MATRIX_RECOVERY_KEY" | nodmix matrix verify device --recovery-key-stdin` first.
+
+### Custom plugin install messages
+
+`Matrix is installed from a custom path that no longer exists: ...`
+
+- Meaning: your plugin install record points at a local path that is gone.
+- What to do: reinstall with `nodmix plugins install @nodmix/matrix`, or if you are running from a repo checkout, `nodmix plugins install ./path/to/local/matrix-plugin`.
+
+## If encrypted history still does not come back
+
+Run these checks in order:
+
+```bash
+nodmix matrix verify status --verbose
+nodmix matrix verify backup status --verbose
+printf '%s\n' "$MATRIX_RECOVERY_KEY" | nodmix matrix verify backup restore --recovery-key-stdin --verbose
+```
+
+If the backup restores successfully but some old rooms are still missing history, those missing keys were probably never backed up by the previous plugin.
+
+## If you want to start fresh for future messages
+
+If you accept losing unrecoverable old encrypted history and only want a clean backup baseline going forward, run these commands in order:
+
+```bash
+nodmix matrix verify backup reset --yes
+nodmix matrix verify backup status --verbose
+nodmix matrix verify status
+```
+
+If the device is still unverified after that, finish verification from your Matrix client by comparing the SAS emoji or decimal codes and confirming that they match.
+
+## Related
+
+- [Matrix](/channels/matrix): channel setup and config.
+- [Matrix push rules](/channels/matrix-push-rules): notification routing.
+- [Doctor](/gateway/doctor): health check and automatic migration trigger.
+- [Migration guide](/install/migrating): all migration paths (machine moves, cross-system imports).
+- [Plugins](/tools/plugin): plugin install and registration.

package/docs/channels/matrix-presentation.md

@@ -0,0 +1,77 @@
+---
+summary: "Matrix MessagePresentation metadata for Nodmix-aware clients"
+read_when:
+  - Building Matrix clients that render Nodmix rich responses
+  - Debugging com.nodmix.presentation event content
+title: "Matrix presentation metadata"
+---
+
+Nodmix can attach normalized `MessagePresentation` metadata to outbound Matrix `m.room.message` events under `com.nodmix.presentation`.
+
+Stock Matrix clients continue to render the plain text `body`. Nodmix-aware clients can read the structured metadata and render native UI such as buttons, selects, context rows, and dividers.
+
+## Event content
+
+The metadata is stored in Matrix event content:
+
+```json
+{
+  "msgtype": "m.text",
+  "body": "Select model\n\n- DeepSeek: /model deepseek/deepseek-chat",
+  "com.nodmix.presentation": {
+    "version": 1,
+    "type": "message.presentation",
+    "title": "Select model",
+    "tone": "info",
+    "blocks": [
+      {
+        "type": "select",
+        "placeholder": "Choose model",
+        "options": [
+          {
+            "label": "DeepSeek",
+            "value": "/model deepseek/deepseek-chat"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+`version` is the Matrix presentation metadata schema version. `type` is a stable discriminator for Nodmix-aware clients. Clients should ignore unknown `type` values, unknown versions they cannot safely interpret, and unknown block types.
+
+## Fallback behavior
+
+Nodmix always renders a readable plain text fallback into `body`. The structured metadata is additive and must not be required for basic Matrix interoperability.
+
+Unsupported clients should continue to show the fallback text. Nodmix-aware clients may prefer the structured metadata for display while preserving the fallback text for copy, search, notifications, and accessibility.
+
+## Supported blocks
+
+The Matrix outbound adapter advertises support for:
+
+- `buttons`
+- `select`
+- `context`
+- `divider`
+
+Clients should treat these blocks as best-effort presentation hints. Unknown fields and unknown block types should be ignored rather than causing the full message to fail rendering.
+
+## Interactions
+
+This metadata does not add Matrix callback semantics. Button and select option values are fallback interaction payloads, usually slash commands or text commands. A Matrix client that wants to support interaction can send the selected value back to the room as a normal message.
+
+For example, a button with value `/model deepseek/deepseek-chat` can be handled by sending that value as an encrypted Matrix text message in the same room.
+
+## Relationship to approval metadata
+
+`com.nodmix.presentation` is for general rich message presentation.
+
+Approval prompts use the dedicated `com.nodmix.approval` metadata because approvals carry safety-sensitive state, decisions, and exec/plugin details. If both metadata keys are present on the same event, clients should prefer the dedicated approval renderer.
+
+## Media messages
+
+When a reply contains multiple media URLs, Nodmix sends one Matrix event per media URL. Presentation metadata is attached only to the first media event so clients have one stable structured payload and duplicate renderers are avoided.
+
+Keep presentation metadata compact. Large user-visible text should stay in `body` and use the normal Matrix text chunking path.

package/docs/channels/matrix-push-rules.md

@@ -0,0 +1,150 @@
+---
+summary: "Per-recipient Matrix push rules for quiet finalized preview edits"
+read_when:
+  - Setting up Matrix quiet streaming for self-hosted Synapse or Tuwunel
+  - Users want notifications only on finished blocks, not on every preview edit
+title: "Matrix push rules for quiet previews"
+---
+
+When `channels.matrix.streaming` is `"quiet"`, Nodmix edits a single preview event in place and marks the finalized edit with a custom content flag. Matrix clients notify on the final edit only if a per-user push rule matches that flag. This page is for operators who self-host Matrix and want to install that rule for each recipient account.
+
+If you only want stock Matrix notification behavior, use `streaming: "partial"` or leave streaming off. See [Matrix channel setup](/channels/matrix#streaming-previews).
+
+## Prerequisites
+
+- recipient user = the person who should receive the notification
+- bot user = the Nodmix Matrix account that sends the reply
+- use the recipient user's access token for the API calls below
+- match `sender` in the push rule against the bot user's full MXID
+- the recipient account must already have working pushers — quiet preview rules only work when normal Matrix push delivery is healthy
+
+## Steps
+
+<Steps>
+  <Step title="Configure quiet previews">
+
+```json5
+{
+  channels: {
+    matrix: {
+      streaming: "quiet",
+    },
+  },
+}
+```
+
+  </Step>
+
+  <Step title="Get the recipient's access token">
+    Reuse an existing client session token where possible. To mint a fresh one:
+
+```bash
+curl -sS -X POST \
+  "https://matrix.example.org/_matrix/client/v3/login" \
+  -H "Content-Type: application/json" \
+  --data '{
+    "type": "m.login.password",
+    "identifier": { "type": "m.id.user", "user": "@alice:example.org" },
+    "password": "REDACTED"
+  }'
+```
+
+  </Step>
+
+  <Step title="Verify pushers exist">
+
+```bash
+curl -sS \
+  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
+  "https://matrix.example.org/_matrix/client/v3/pushers"
+```
+
+If no pushers come back, fix normal Matrix push delivery for this account before continuing.
+
+  </Step>
+
+  <Step title="Install the override push rule">
+    Nodmix marks finalized text-only preview edits with `content["com.nodmix.finalized_preview"] = true`. Install a rule that matches that marker plus the bot MXID as sender:
+
+```bash
+curl -sS -X PUT \
+  "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/nodmix-finalized-preview-botname" \
+  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
+  -H "Content-Type: application/json" \
+  --data '{
+    "conditions": [
+      { "kind": "event_match", "key": "type", "pattern": "m.room.message" },
+      {
+        "kind": "event_property_is",
+        "key": "content.m\\.relates_to.rel_type",
+        "value": "m.replace"
+      },
+      {
+        "kind": "event_property_is",
+        "key": "content.com\\.nodmix\\.finalized_preview",
+        "value": true
+      },
+      { "kind": "event_match", "key": "sender", "pattern": "@bot:example.org" }
+    ],
+    "actions": [
+      "notify",
+      { "set_tweak": "sound", "value": "default" },
+      { "set_tweak": "highlight", "value": false }
+    ]
+  }'
+```
+
+    Replace before running:
+
+    - `https://matrix.example.org`: your homeserver base URL
+    - `$USER_ACCESS_TOKEN`: the recipient user's access token
+    - `nodmix-finalized-preview-botname`: a rule ID unique per bot per recipient (pattern: `nodmix-finalized-preview-<botname>`)
+    - `@bot:example.org`: your Nodmix bot MXID, not the recipient's
+
+  </Step>
+
+  <Step title="Verify">
+
+```bash
+curl -sS \
+  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
+  "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/nodmix-finalized-preview-botname"
+```
+
+Then test a streamed reply. In quiet mode the room shows a quiet draft preview and notifies once the block or turn finishes.
+
+  </Step>
+</Steps>
+
+To remove the rule later, `DELETE` the same rule URL with the recipient's token.
+
+## Multi-bot notes
+
+Push rules are keyed by `ruleId`: re-running `PUT` against the same ID updates a single rule. For multiple Nodmix bots notifying the same recipient, create one rule per bot with a distinct sender match.
+
+New user-defined `override` rules are inserted ahead of default suppress rules, so no extra ordering parameter is needed. The rule only affects text-only preview edits that can be finalized in place; media fallbacks and stale-preview fallbacks use normal Matrix delivery.
+
+## Homeserver notes
+
+<AccordionGroup>
+  <Accordion title="Synapse">
+    No special `homeserver.yaml` change is required. If normal Matrix notifications already reach this user, the recipient token + `pushrules` call above is the main setup step.
+
+    If you run Synapse behind a reverse proxy or workers, make sure `/_matrix/client/.../pushrules/` reaches Synapse correctly. Push delivery is handled by the main process or `synapse.app.pusher` / configured pusher workers — ensure those are healthy.
+
+    The rule uses the `event_property_is` push-rule condition (MSC3758, push rule v1.10), which was added to Synapse in 2023. Older Synapse releases accept the `PUT pushrules/...` call but silently never match the condition — upgrade Synapse if no notification arrives on a finalized preview edit.
+
+  </Accordion>
+
+  <Accordion title="Tuwunel">
+    Same flow as Synapse; no Tuwunel-specific config is needed for the finalized preview marker.
+
+    If notifications disappear while the user is active on another device, check whether `suppress_push_when_active` is enabled. Tuwunel added this option in 1.4.2 (September 2025) and it can intentionally suppress pushes to other devices while one device is active.
+
+  </Accordion>
+</AccordionGroup>
+
+## Related
+
+- [Matrix channel setup](/channels/matrix)
+- [Streaming concepts](/concepts/streaming)