nodmix 2026.5.25

package/docs/cli/memory.md

@@ -0,0 +1,183 @@
+---
+summary: "CLI reference for `nodmix memory` (status/index/search/promote/promote-explain/rem-harness)"
+read_when:
+  - You want to index or search semantic memory
+  - You're debugging memory availability or indexing
+  - You want to promote recalled short-term memory into `MEMORY.md`
+title: "Memory"
+---
+
+# `nodmix memory`
+
+Manage semantic memory indexing and search.
+Provided by the bundled `memory-core` plugin. The command is available when
+`plugins.slots.memory` selects `memory-core` (the default); other memory plugins
+expose their own CLI namespaces.
+
+Related:
+
+- Memory concept: [Memory](/concepts/memory)
+- Memory wiki: [Memory Wiki](/plugins/memory-wiki)
+- Wiki CLI: [wiki](/cli/wiki)
+- Plugins: [Plugins](/tools/plugin)
+
+## Examples
+
+```bash
+nodmix memory status
+nodmix memory status --deep
+nodmix memory status --fix
+nodmix memory index --force
+nodmix memory search "meeting notes"
+nodmix memory search --query "deployment" --max-results 20
+nodmix memory promote --limit 10 --min-score 0.75
+nodmix memory promote --apply
+nodmix memory promote --json --min-recall-count 0 --min-unique-queries 0
+nodmix memory promote-explain "router vlan"
+nodmix memory promote-explain "router vlan" --json
+nodmix memory rem-harness
+nodmix memory rem-harness --json
+nodmix memory status --json
+nodmix memory status --deep --index
+nodmix memory status --deep --index --verbose
+nodmix memory status --agent main
+nodmix memory index --agent main --verbose
+```
+
+## Options
+
+`memory status` and `memory index`:
+
+- `--agent <id>`: scope to a single agent. Without it, these commands run for each configured agent; if no agent list is configured, they fall back to the default agent.
+- `--verbose`: emit detailed logs during probes and indexing.
+
+`memory status`:
+
+- `--deep`: probe local vector-store readiness, embedding-provider readiness, and semantic vector-search readiness. Plain `memory status` stays fast and does not run live embedding or provider discovery work; unknown vector-store or semantic-vector state means it was not probed in that command. QMD lexical `searchMode: "search"` skips semantic vector probes and embedding maintenance even with `--deep`.
+- `--index`: run a reindex if the store is dirty (implies `--deep`).
+- `--fix`: repair stale recall locks and normalize promotion metadata.
+- `--json`: print JSON output.
+
+If `memory status` shows `Dreaming status: blocked`, the managed dreaming cron is enabled but the heartbeat that drives it is not firing for the default agent. See [Dreaming never runs](/concepts/dreaming#dreaming-never-runs-status-shows-blocked) for the two common causes.
+
+`memory index`:
+
+- `--force`: force a full reindex.
+
+`memory search`:
+
+- Query input: pass either positional `[query]` or `--query <text>`.
+- If both are provided, `--query` wins.
+- If neither is provided, the command exits with an error.
+- `--agent <id>`: scope to a single agent (default: the default agent).
+- `--max-results <n>`: limit the number of results returned.
+- `--min-score <n>`: filter out low-score matches.
+- `--json`: print JSON results.
+
+`memory promote`:
+
+Preview and apply short-term memory promotions.
+
+```bash
+nodmix memory promote [--apply] [--limit <n>] [--include-promoted]
+```
+
+- `--apply` -- write promotions to `MEMORY.md` (default: preview only).
+- `--limit <n>` -- cap the number of candidates shown.
+- `--include-promoted` -- include entries already promoted in previous cycles.
+
+Full options:
+
+- Ranks short-term candidates from `memory/YYYY-MM-DD.md` using weighted promotion signals (`frequency`, `relevance`, `query diversity`, `recency`, `consolidation`, `conceptual richness`).
+- Uses short-term signals from both memory recalls and daily-ingestion passes, plus light/REM phase reinforcement signals.
+- When dreaming is enabled, `memory-core` auto-manages one cron job that runs a full sweep (`light -> REM -> deep`) in the background (no manual `nodmix cron add` required).
+- `--agent <id>`: scope to a single agent (default: the default agent).
+- `--limit <n>`: max candidates to return/apply.
+- `--min-score <n>`: minimum weighted promotion score.
+- `--min-recall-count <n>`: minimum recall count required for a candidate.
+- `--min-unique-queries <n>`: minimum distinct query count required for a candidate.
+- `--apply`: append selected candidates into `MEMORY.md` and mark them promoted.
+- `--include-promoted`: include already promoted candidates in output.
+- `--json`: print JSON output.
+
+`memory promote-explain`:
+
+Explain a specific promotion candidate and its score breakdown.
+
+```bash
+nodmix memory promote-explain <selector> [--agent <id>] [--include-promoted] [--json]
+```
+
+- `<selector>`: candidate key, path fragment, or snippet fragment to look up.
+- `--agent <id>`: scope to a single agent (default: the default agent).
+- `--include-promoted`: include already promoted candidates.
+- `--json`: print JSON output.
+
+`memory rem-harness`:
+
+Preview REM reflections, candidate truths, and deep promotion output without writing anything.
+
+```bash
+nodmix memory rem-harness [--agent <id>] [--include-promoted] [--json]
+```
+
+- `--agent <id>`: scope to a single agent (default: the default agent).
+- `--include-promoted`: include already promoted deep candidates.
+- `--json`: print JSON output.
+
+## Dreaming
+
+Dreaming is the background memory consolidation system with three cooperative
+phases: **light** (sort/stage short-term material), **deep** (promote durable
+facts into `MEMORY.md`), and **REM** (reflect and surface themes).
+
+- Enable with `plugins.entries.memory-core.config.dreaming.enabled: true`.
+- Toggle from chat with `/dreaming on|off` (or inspect with `/dreaming status`).
+- Dreaming runs on one managed sweep schedule (`dreaming.frequency`) and executes phases in order: light, REM, deep.
+- Only the deep phase writes durable memory to `MEMORY.md`.
+- Human-readable phase output and diary entries are written to `DREAMS.md` (or existing `dreams.md`), with optional per-phase reports in `memory/dreaming/<phase>/YYYY-MM-DD.md`.
+- Ranking uses weighted signals: recall frequency, retrieval relevance, query diversity, temporal recency, cross-day consolidation, and derived concept richness.
+- Promotion re-reads the live daily note before writing to `MEMORY.md`, so edited or deleted short-term snippets do not get promoted from stale recall-store snapshots.
+- Scheduled and manual `memory promote` runs share the same deep phase defaults unless you pass CLI threshold overrides.
+- Automatic runs fan out across configured memory workspaces.
+
+Default scheduling:
+
+- **Sweep cadence**: `dreaming.frequency = 0 3 * * *`
+- **Deep thresholds**: `minScore=0.8`, `minRecallCount=3`, `minUniqueQueries=3`, `recencyHalfLifeDays=14`, `maxAgeDays=30`
+
+Example:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "memory-core": {
+        "config": {
+          "dreaming": {
+            "enabled": true
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Notes:
+
+- `memory index --verbose` prints per-phase details (provider, model, sources, batch activity).
+- `memory status` includes any extra paths configured via `memorySearch.extraPaths`.
+- If effectively active memory remote API key fields are configured as SecretRefs, the command resolves those values from the active gateway snapshot. If gateway is unavailable, the command fails fast.
+- Gateway version skew note: this command path requires a gateway that supports `secrets.resolve`; older gateways return an unknown-method error.
+- Tune scheduled sweep cadence with `dreaming.frequency`. Deep promotion policy is otherwise internal; use CLI flags on `memory promote` when you need one-off manual overrides.
+- `memory rem-harness --path <file-or-dir> --grounded` previews grounded `What Happened`, `Reflections`, and `Possible Lasting Updates` from historical daily notes without writing anything.
+- `memory rem-backfill --path <file-or-dir>` writes reversible grounded diary entries into `DREAMS.md` for UI review.
+- `memory rem-backfill --path <file-or-dir> --stage-short-term` also seeds grounded durable candidates into the live short-term promotion store so the normal deep phase can rank them.
+- `memory rem-backfill --rollback` removes previously written grounded diary entries, and `memory rem-backfill --rollback-short-term` removes previously staged grounded short-term candidates.
+- See [Dreaming](/concepts/dreaming) for full phase descriptions and configuration reference.
+
+## Related
+
+- [CLI reference](/cli)
+- [Memory overview](/concepts/memory)

package/docs/cli/message.md

@@ -0,0 +1,317 @@
+---
+summary: "CLI reference for `nodmix message` (send + channel actions)"
+read_when:
+  - Adding or modifying message CLI actions
+  - Changing outbound channel behavior
+title: "Message"
+---
+
+# `nodmix message`
+
+Single outbound command for sending messages and channel actions
+(Discord/Google Chat/iMessage/Matrix/Mattermost (plugin)/Microsoft Teams/Signal/Slack/Telegram/WhatsApp).
+
+## Usage
+
+```
+nodmix message <subcommand> [flags]
+```
+
+Channel selection:
+
+- `--channel` required if more than one channel is configured.
+- If exactly one channel is configured, it becomes the default.
+- Values: `discord|googlechat|imessage|matrix|mattermost|msteams|signal|slack|telegram|whatsapp` (Mattermost requires plugin)
+- `nodmix message` resolves the selected channel to its owning plugin when `--channel` or a channel-prefixed target is present; otherwise it loads configured channel plugins for default-channel inference.
+
+Target formats (`--target`):
+
+- WhatsApp: E.164, group JID, or WhatsApp Channel/Newsletter JID (`...@newsletter`)
+- Telegram: chat id, `@username`, or forum topic target (`-1001234567890:topic:42`, or `--thread-id 42`)
+- Discord: `channel:<id>` or `user:<id>` (or `<@id>` mention; raw numeric ids are treated as channels)
+- Google Chat: `spaces/<spaceId>` or `users/<userId>`
+- Slack: `channel:<id>` or `user:<id>` (raw channel id is accepted)
+- Mattermost (plugin): `channel:<id>`, `user:<id>`, or `@username` (bare ids are treated as channels)
+- Signal: `+E.164`, `group:<id>`, `signal:+E.164`, `signal:group:<id>`, or `username:<name>`/`u:<name>`
+- iMessage: handle, `chat_id:<id>`, `chat_guid:<guid>`, or `chat_identifier:<id>`
+- Matrix: `@user:server`, `!room:server`, or `#alias:server`
+- Microsoft Teams: conversation id (`19:...@thread.tacv2`) or `conversation:<id>` or `user:<aad-object-id>`
+
+Name lookup:
+
+- For supported providers (Discord/Slack/etc), channel names like `Help` or `#help` are resolved via the directory cache.
+- On cache miss, Nodmix will attempt a live directory lookup when the provider supports it.
+
+## Common flags
+
+- `--channel <name>`
+- `--account <id>`
+- `--target <dest>` (target channel or user for send/poll/read/etc)
+- `--targets <name>` (repeat; broadcast only)
+- `--json`
+- `--dry-run`
+- `--verbose`
+
+## SecretRef behavior
+
+- `nodmix message` resolves supported channel SecretRefs before running the selected action.
+- Resolution is scoped to the active action target when possible:
+  - channel-scoped when `--channel` is set (or inferred from prefixed targets like `discord:...`)
+  - account-scoped when `--account` is set (channel globals + selected account surfaces)
+  - when `--account` is omitted, Nodmix does not force a `default` account SecretRef scope
+- Unresolved SecretRefs on unrelated channels do not block a targeted message action.
+- If the selected channel/account SecretRef is unresolved, the command fails closed for that action.
+
+## Actions
+
+### Core
+
+- `send`
+  - Channels: WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost (plugin)/Signal/iMessage/Matrix/Microsoft Teams
+  - Required: `--target`, plus `--message`, `--media`, or `--presentation`
+  - Optional: `--media`, `--presentation`, `--delivery`, `--pin`, `--reply-to`, `--thread-id`, `--gif-playback`, `--force-document`, `--silent`
+  - Shared presentation payloads: `--presentation` sends semantic blocks (`text`, `context`, `divider`, `buttons`, `select`) that core renders through the selected channel's declared capabilities. See [Message Presentation](/plugins/message-presentation).
+  - Generic delivery preferences: `--delivery` accepts delivery hints such as `{ "pin": true }`; `--pin` is shorthand for pinned delivery when the channel supports it.
+  - Telegram + WhatsApp: `--force-document` (send images, GIFs, and videos as documents to avoid channel compression)
+  - Telegram only: `--thread-id` (forum topic id)
+  - Slack only: `--thread-id` (thread timestamp; `--reply-to` uses the same field)
+  - Telegram + Discord: `--silent`
+  - WhatsApp only: `--gif-playback`; WhatsApp Channels/Newsletters are addressed with their native `@newsletter` JID.
+
+- `poll`
+  - Channels: WhatsApp/Telegram/Discord/Matrix/Microsoft Teams
+  - Required: `--target`, `--poll-question`, `--poll-option` (repeat)
+  - Optional: `--poll-multi`
+  - Discord only: `--poll-duration-hours`, `--silent`, `--message`
+  - Telegram only: `--poll-duration-seconds` (5-600), `--silent`, `--poll-anonymous` / `--poll-public`, `--thread-id`
+
+- `react`
+  - Channels: Discord/Google Chat/Matrix/Nextcloud Talk/Signal/Slack/Telegram/WhatsApp
+  - Required: `--message-id`, `--target`
+  - Optional: `--emoji`, `--remove`, `--participant`, `--from-me`, `--target-author`, `--target-author-uuid`
+  - Note: `--remove` requires `--emoji` (omit `--emoji` to clear own reactions where supported; see /tools/reactions)
+  - WhatsApp only: `--participant`, `--from-me`
+  - Signal group reactions: `--target-author` or `--target-author-uuid` required
+  - Nextcloud Talk: adding reactions only; `--remove` is rejected with a clear error (see /tools/reactions)
+
+- `reactions`
+  - Channels: Discord/Google Chat/Slack/Matrix
+  - Required: `--message-id`, `--target`
+  - Optional: `--limit`
+
+- `read`
+  - Channels: Discord/Slack/Matrix
+  - Required: `--target`
+  - Optional: `--limit`, `--message-id`, `--before`, `--after`
+  - Slack only: `--message-id` reads a specific Slack message timestamp; combine with `--thread-id` to read an exact thread reply.
+  - Discord only: `--around`
+
+- `edit`
+  - Channels: Discord/Slack/Matrix
+  - Required: `--message-id`, `--message`, `--target`
+
+- `delete`
+  - Channels: Discord/Slack/Telegram/Matrix
+  - Required: `--message-id`, `--target`
+
+- `pin` / `unpin`
+  - Channels: Discord/Slack/Matrix
+  - Required: `--message-id`, `--target`
+
+- `pins` (list)
+  - Channels: Discord/Slack/Matrix
+  - Required: `--target`
+
+- `permissions`
+  - Channels: Discord/Matrix
+  - Required: `--target`
+  - Matrix only: available when Matrix encryption is enabled and verification actions are allowed
+
+- `search`
+  - Channels: Discord
+  - Required: `--guild-id`, `--query`
+  - Optional: `--channel-id`, `--channel-ids` (repeat), `--author-id`, `--author-ids` (repeat), `--limit`
+
+### Threads
+
+- `thread create`
+  - Channels: Discord
+  - Required: `--thread-name`, `--target` (channel id)
+  - Optional: `--message-id`, `--message`, `--auto-archive-min`
+
+- `thread list`
+  - Channels: Discord
+  - Required: `--guild-id`
+  - Optional: `--channel-id`, `--include-archived`, `--before`, `--limit`
+
+- `thread reply`
+  - Channels: Discord
+  - Required: `--target` (thread id), `--message`
+  - Optional: `--media`, `--reply-to`
+
+### Emojis
+
+- `emoji list`
+  - Discord: `--guild-id`
+  - Slack: no extra flags
+
+- `emoji upload`
+  - Channels: Discord
+  - Required: `--guild-id`, `--emoji-name`, `--media`
+  - Optional: `--role-ids` (repeat)
+
+### Stickers
+
+- `sticker send`
+  - Channels: Discord
+  - Required: `--target`, `--sticker-id` (repeat)
+  - Optional: `--message`
+
+- `sticker upload`
+  - Channels: Discord
+  - Required: `--guild-id`, `--sticker-name`, `--sticker-desc`, `--sticker-tags`, `--media`
+
+### Roles / Channels / Members / Voice
+
+- `role info` (Discord): `--guild-id`
+- `role add` / `role remove` (Discord): `--guild-id`, `--user-id`, `--role-id`
+- `channel info` (Discord): `--target`
+- `channel list` (Discord): `--guild-id`
+- `member info` (Discord/Slack): `--user-id` (+ `--guild-id` for Discord)
+- `voice status` (Discord): `--guild-id`, `--user-id`
+
+### Events
+
+- `event list` (Discord): `--guild-id`
+- `event create` (Discord): `--guild-id`, `--event-name`, `--start-time`
+  - Optional: `--end-time`, `--desc`, `--channel-id`, `--location`, `--event-type`
+
+### Moderation (Discord)
+
+- `timeout`: `--guild-id`, `--user-id` (optional `--duration-min` or `--until`; omit both to clear timeout)
+- `kick`: `--guild-id`, `--user-id` (+ `--reason`)
+- `ban`: `--guild-id`, `--user-id` (+ `--delete-days`, `--reason`)
+  - `timeout` also supports `--reason`
+
+### Broadcast
+
+- `broadcast`
+  - Channels: any configured channel; use `--channel all` to target all providers
+  - Required: `--targets <target...>`
+  - Optional: `--message`, `--media`, `--dry-run`
+
+## Examples
+
+Send a Discord reply:
+
+```
+nodmix message send --channel discord \
+  --target channel:123 --message "hi" --reply-to 456
+```
+
+Send a message with semantic buttons:
+
+```
+nodmix message send --channel discord \
+  --target channel:123 --message "Choose:" \
+  --presentation '{"blocks":[{"type":"buttons","buttons":[{"label":"Approve","value":"approve","style":"success"},{"label":"Decline","value":"decline","style":"danger"}]}]}'
+```
+
+Core renders the same `presentation` payload into Discord components, Slack blocks, Telegram inline buttons, Mattermost props, or Teams/Feishu cards depending on channel capability. See [Message Presentation](/plugins/message-presentation) for the full contract and fallback rules.
+
+Send a richer presentation payload:
+
+```bash
+nodmix message send --channel googlechat --target spaces/AAA... \
+  --message "Choose:" \
+  --presentation '{"title":"Deploy approval","tone":"warning","blocks":[{"type":"text","text":"Choose a path"},{"type":"buttons","buttons":[{"label":"Approve","value":"approve"},{"label":"Decline","value":"decline"}]}]}'
+```
+
+Create a Discord poll:
+
+```
+nodmix message poll --channel discord \
+  --target channel:123 \
+  --poll-question "Snack?" \
+  --poll-option Pizza --poll-option Sushi \
+  --poll-multi --poll-duration-hours 48
+```
+
+Create a Telegram poll (auto-close in 2 minutes):
+
+```
+nodmix message poll --channel telegram \
+  --target @mychat \
+  --poll-question "Lunch?" \
+  --poll-option Pizza --poll-option Sushi \
+  --poll-duration-seconds 120 --silent
+```
+
+Send a Teams proactive message:
+
+```
+nodmix message send --channel msteams \
+  --target conversation:19:abc@thread.tacv2 --message "hi"
+```
+
+Create a Teams poll:
+
+```
+nodmix message poll --channel msteams \
+  --target conversation:19:abc@thread.tacv2 \
+  --poll-question "Lunch?" \
+  --poll-option Pizza --poll-option Sushi
+```
+
+React in Slack:
+
+```
+nodmix message react --channel slack \
+  --target C123 --message-id 456 --emoji "✅"
+```
+
+React in a Signal group:
+
+```
+nodmix message react --channel signal \
+  --target signal:group:abc123 --message-id 1737630212345 \
+  --emoji "✅" --target-author-uuid 123e4567-e89b-12d3-a456-426614174000
+```
+
+Send Telegram inline buttons through generic presentation:
+
+```
+nodmix message send --channel telegram --target @mychat --message "Choose:" \
+  --presentation '{"blocks":[{"type":"buttons","buttons":[{"label":"Yes","value":"cmd:yes"},{"label":"No","value":"cmd:no"}]}]}'
+```
+
+Send a Telegram Mini App button through generic presentation:
+
+```
+nodmix message send --channel telegram --target 123456789 --message "Open app:" \
+  --presentation '{"blocks":[{"type":"buttons","buttons":[{"label":"Launch","webApp":{"url":"https://example.com/app"}}]}]}'
+```
+
+Telegram web app buttons are supported only in private chats between a user and
+the bot. Older JSON payloads using `web_app` still parse, but `webApp` is the
+canonical presentation field.
+
+Send a Teams card through generic presentation:
+
+```bash
+nodmix message send --channel msteams \
+  --target conversation:19:abc@thread.tacv2 \
+  --presentation '{"title":"Status update","blocks":[{"type":"text","text":"Build completed"}]}'
+```
+
+Send a Telegram or WhatsApp image as a document to avoid compression:
+
+```bash
+nodmix message send --channel telegram --target @mychat \
+  --media ./diagram.png --force-document
+```
+
+## Related
+
+- [CLI reference](/cli)
+- [Agent send](/tools/agent-send)