fengming 0.3.9 → 0.3.11

package/docs/cli/memory.md

@@ -1,183 +0,0 @@
----
-summary: "CLI reference for `fengming 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"
----
-
-# `fengming 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
-fengming memory status
-fengming memory status --deep
-fengming memory status --fix
-fengming memory index --force
-fengming memory search "meeting notes"
-fengming memory search --query "deployment" --max-results 20
-fengming memory promote --limit 10 --min-score 0.75
-fengming memory promote --apply
-fengming memory promote --json --min-recall-count 0 --min-unique-queries 0
-fengming memory promote-explain "router vlan"
-fengming memory promote-explain "router vlan" --json
-fengming memory rem-harness
-fengming memory rem-harness --json
-fengming memory status --json
-fengming memory status --deep --index
-fengming memory status --deep --index --verbose
-fengming memory status --agent main
-fengming 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
-fengming 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 `fengming 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
-fengming 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
-fengming 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 except for `dreaming.phases.deep.maxPromotedSnippetTokens`, which bounds promoted snippet length while keeping provenance visible. Use CLI flags on `memory promote` when you need one-off manual threshold 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

@@ -1,317 +0,0 @@
----
-summary: "CLI reference for `fengming message` (send + channel actions)"
-read_when:
-  - Adding or modifying message CLI actions
-  - Changing outbound channel behavior
-title: "Message"
----
-
-# `fengming message`
-
-Single outbound command for sending messages and channel actions
-(Discord/Google Chat/iMessage/Matrix/Mattermost (plugin)/Microsoft Teams/Signal/Slack/Telegram/WhatsApp).
-
-## Usage
-
-```
-fengming 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)
-- `fengming 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, FengMing 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
-
-- `fengming 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, FengMing 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:
-
-```
-fengming message send --channel discord \
-  --target channel:123 --message "hi" --reply-to 456
-```
-
-Send a message with semantic buttons:
-
-```
-fengming 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
-fengming 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:
-
-```
-fengming 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):
-
-```
-fengming 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:
-
-```
-fengming message send --channel msteams \
-  --target conversation:19:abc@thread.tacv2 --message "hi"
-```
-
-Create a Teams poll:
-
-```
-fengming message poll --channel msteams \
-  --target conversation:19:abc@thread.tacv2 \
-  --poll-question "Lunch?" \
-  --poll-option Pizza --poll-option Sushi
-```
-
-React in Slack:
-
-```
-fengming message react --channel slack \
-  --target C123 --message-id 456 --emoji "✅"
-```
-
-React in a Signal group:
-
-```
-fengming 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:
-
-```
-fengming 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:
-
-```
-fengming 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
-fengming 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
-fengming message send --channel telegram --target @mychat \
-  --media ./diagram.png --force-document
-```
-
-## Related
-
-- [CLI reference](/cli)
-- [Agent send](/tools/agent-send)