fix: harden compaction status gating (#1466 ) (thanks @dlauer)

fix(control-ui): add agentId to DEFAULT_ASSISTANT_IDENTITY
TypeScript inferred the union type without agentId when falling back to DEFAULT_ASSISTANT_IDENTITY, causing build errors at control-ui.ts:222-223.
2026-01-23 06:32:17 +00:00 · 2026-01-23 05:52:04 +00:00 · 2026-01-23 05:52:04 +00:00 · 2026-01-23 05:52:04 +00:00 · 2026-01-23 05:47:16 +00:00 · 2026-01-23 05:47:13 +00:00
348 changed files with 33663 additions and 5428 deletions
@@ -2,35 +2,50 @@

 Docs: https://docs.clawd.bot

-## 2026.1.22 (unreleased)
+## 2026.1.22

 ### Changes
- TUI: run local shell commands with `!` after per-session consent, and warn when local exec stays disabled. (#1463) Thanks @vignesh07.
 - Highlight: Lobster optional plugin tool for typed workflows + approval gates. https://docs.clawd.bot/tools/lobster
+- Lobster: allow workflow file args via `argsJson` in the plugin tool. https://docs.clawd.bot/tools/lobster
 - Agents: add identity avatar config support and Control UI avatar rendering. (#1329, #1424) Thanks @dlauer.
+- Slack: add chat-type reply threading overrides via `replyToModeByChatType`. (#1442) Thanks @stefangalescu.
 - Memory: prevent CLI hangs by deferring vector probes, adding sqlite-vec/embedding timeouts, and showing sync progress early.
+- BlueBubbles: add `asVoice` support for MP3/CAF voice memos in sendAttachment. (#1477, #1482) Thanks @Nicell.
 - Docs: add troubleshooting entry for gateway.mode blocking gateway start. https://docs.clawd.bot/gateway/troubleshooting
 - Docs: add /model allowlist troubleshooting note. (#1405)
 - Docs: add per-message Gmail search example for gog. (#1220) Thanks @mbelinky.
 - UI: show per-session assistant identity in the Control UI. (#1420) Thanks @robbyczgw-cla.
+- Onboarding: add hatch choice (TUI/Web/Later), token explainer, background dashboard seed on macOS, and showcase link.
 - Onboarding: remove the run setup-token auth option (paste setup-token or reuse CLI creds instead).
 - Signal: add typing indicators and DM read receipts via signal-cli.
 - MSTeams: add file uploads, adaptive cards, and attachment handling improvements. (#1410) Thanks @Evizero.
 - CLI: add `clawdbot update wizard` for interactive channel selection and restart prompts. https://docs.clawd.bot/cli/update
- macOS: add attach-only debug toggle + `--attach-only`/`--no-launchd` flag to skip launchd installs.

 ### Breaking
 - **BREAKING:** Envelope and system event timestamps now default to host-local time (was UTC) so agents don’t have to constantly convert.

 ### Fixes
 - BlueBubbles: stop typing indicator on idle/no-reply. (#1439) Thanks @Nicell.
+- Message tool: keep path/filePath as-is for send; hydrate buffers only for sendAttachment. (#1444) Thanks @hopyky.
 - Auto-reply: only report a model switch when session state is available. (#1465) Thanks @robbyczgw-cla.
+- Compaction: harden oversized summarization handling and gate UI compaction status by verbose level. (#1466) Thanks @dlauer.
 - Control UI: resolve local avatar URLs with basePath across injection + identity RPC. (#1457) Thanks @dlauer.
 - Agents: surface concrete API error details instead of generic AI service errors.
 - Exec approvals: allow per-segment allowlists for chained shell commands on gateway + node hosts. (#1458) Thanks @czekaj.
- Agents: avoid sanitizing tool call IDs for OpenAI responses to preserve Pi pairing.
+- Agents: make OpenAI sessions image-sanitize-only; gate tool-id/repair sanitization by provider.
+- Doctor: honor CLAWDBOT_GATEWAY_TOKEN for auth checks and security audit token reuse. (#1448) Thanks @azade-c.
+- Agents: make tool summaries more readable and only show optional params when set.
+- Agents: honor SOUL.md guidance even when the file is nested or path-qualified. (#1434) Thanks @neooriginal.
+- Matrix (plugin): persist m.direct for resolved DMs and harden room fallback. (#1436, #1486) Thanks @sibbl.
+- CLI: prefer `~` for home paths in output.
+- Mattermost (plugin): enforce pairing/allowlist gating, keep @username targets, and clarify plugin-only docs. (#1428) Thanks @damoahdominic.
+- Agents: centralize transcript sanitization in the runner; keep <final> tags and error turns intact.
+- Auth: skip auth profiles in cooldown during initial selection and rotation. (#1316) Thanks @odrobnik.
+- Agents/TUI: honor user-pinned auth profiles during cooldown and preserve search picker ranking. (#1432) Thanks @tobiasbischoff.
 - Docs: fix gog auth services example to include docs scope. (#1454) Thanks @zerone0x.
+- Slack: read thread replies for message reads when threadId is provided (replies-only). (#1450) Thanks @rodrigouroz.
 - macOS: prefer linked channels in gateway summary to avoid false “not linked” status.
+- Providers: improve GitHub Copilot integration (enterprise support, base URL, and auth flow alignment).

 ## 2026.1.21-2

@@ -40,63 +55,38 @@ Docs: https://docs.clawd.bot

 ## 2026.1.21

-### Highlights
- Lobster optional plugin tool for typed workflows + approval gates. https://docs.clawd.bot/tools/lobster
- Custom assistant identity + avatars in the Control UI. https://docs.clawd.bot/cli/agents https://docs.clawd.bot/web/control-ui
- Cache optimizations: cache-ttl pruning + defaults reduce token spend on cold requests. https://docs.clawd.bot/concepts/session-pruning
- Exec approvals + elevated ask/full modes. https://docs.clawd.bot/tools/exec-approvals https://docs.clawd.bot/tools/elevated
- Signal typing/read receipts + MSTeams attachments. https://docs.clawd.bot/channels/signal https://docs.clawd.bot/channels/msteams
- `/models` UX refresh + `clawdbot update wizard`. https://docs.clawd.bot/cli/models https://docs.clawd.bot/cli/update
-
 ### Changes
- Highlight: Lobster optional plugin tool for typed workflows + approval gates. https://docs.clawd.bot/tools/lobster (#1152) Thanks @vignesh07.
- Agents/UI: add identity avatar config support and Control UI avatar rendering. (#1329, #1424) Thanks @dlauer. https://docs.clawd.bot/gateway/configuration https://docs.clawd.bot/cli/agents
- Control UI: add custom assistant identity support and per-session identity display. (#1420) Thanks @robbyczgw-cla. https://docs.clawd.bot/web/control-ui
- CLI: add `clawdbot update wizard` with interactive channel selection + restart prompts, plus preflight checks before rebasing. https://docs.clawd.bot/cli/update
- Models/Commands: add `/models`, improve `/model` listing UX, and expand `clawdbot models` paging. (#1398) Thanks @vignesh07. https://docs.clawd.bot/cli/models
- CLI: move gateway service commands under `clawdbot gateway`, flatten node service commands under `clawdbot node`, and add `gateway probe` for reachability. https://docs.clawd.bot/cli/gateway https://docs.clawd.bot/cli/node
- Exec: add elevated ask/full modes, tighten allowlist gating, and render approvals tables on write. https://docs.clawd.bot/tools/elevated https://docs.clawd.bot/tools/exec-approvals
- Exec approvals: default to local host, add gateway/node targeting + target details, support wildcard agent allowlists, and tighten allowlist parsing/safe bins. https://docs.clawd.bot/cli/approvals https://docs.clawd.bot/tools/exec-approvals
- Heartbeat: allow explicit session keys and active hours. (#1256) Thanks @zknicker. https://docs.clawd.bot/gateway/heartbeat
- Sessions: add per-channel idle durations via `sessions.channelIdleMinutes`. (#1353) Thanks @cash-echo-bot.
- Nodes: run exec-style, expose PATH in status/describe, and bootstrap PATH for node-host execution. https://docs.clawd.bot/cli/node
- Cache: add `cache.ttlPrune` mode and auth-aware defaults for cache TTL behavior.
- Queue: add per-channel debounce overrides for auto-reply. https://docs.clawd.bot/concepts/queue
- Discord: add wildcard channel config support. (#1334) Thanks @pvoo. https://docs.clawd.bot/channels/discord
- Signal: add typing indicators and DM read receipts via signal-cli. https://docs.clawd.bot/channels/signal
- MSTeams: add file uploads, adaptive cards, and attachment handling improvements. (#1410) Thanks @Evizero. https://docs.clawd.bot/channels/msteams
- Onboarding: remove the run setup-token auth option (paste setup-token or reuse CLI creds instead).
- macOS: refresh Settings (location access in Permissions, connection mode in menu, remove CLI install UI).
- Diagnostics: add cache trace config for debugging. (#1370) Thanks @parubets.
- Docs: Lobster guides + org URL updates, /model allowlist troubleshooting, Gmail message search examples, gateway.mode troubleshooting, prompt injection guidance, npm prefix/node CLI notes, control UI dev gatewayUrl note, tool_use FAQ, showcase video, and sharp/node-gyp workaround. (#1427, #1220, #1405) Thanks @vignesh07, @mbelinky.
+- Heartbeat: allow running heartbeats in an explicit session key. (#1256) Thanks @zknicker.
+- CLI: default exec approvals to the local host, add gateway/node targeting flags, and show target details in allowlist output.
+- CLI: exec approvals mutations render tables instead of raw JSON.
+- Exec approvals: support wildcard agent allowlists (`*`) across all agents.
+- Exec approvals: allowlist matches resolved binary paths only, add safe stdin-only bins, and tighten allowlist shell parsing.
+- Nodes: expose node PATH in status/describe and bootstrap PATH for node-host execution.
+- CLI: flatten node service commands under `clawdbot node` and remove `service node` docs.
+- CLI: move gateway service commands under `clawdbot gateway` and add `gateway probe` for reachability.
+- Sessions: add per-channel reset overrides via `session.resetByChannel`. (#1353) Thanks @cash-echo-bot.

 ### Breaking
 - **BREAKING:** Control UI now rejects insecure HTTP without device identity by default. Use HTTPS (Tailscale Serve) or set `gateway.controlUi.allowInsecureAuth: true` to allow token-only auth. https://docs.clawd.bot/web/control-ui#insecure-http
- **BREAKING:** Envelope and system event timestamps now default to host-local time (was UTC) so agents don’t have to constantly convert.

 ### Fixes
- Streaming/Typing/Media: keep reply tags across streamed chunks, start typing indicators at run start, and accept MEDIA paths with spaces/tilde while preferring the message tool hint for image replies.
- Agents/Providers: drop unsigned thinking blocks for Claude models (Google Antigravity) and enforce alphanumeric tool call ids for strict providers (Mistral/OpenRouter). (#1372) Thanks @zerone0x.
- Exec approvals: treat main as the default agent, align node/gateway allowlist prechecks, validate resolved paths, avoid allowlist resolve races, and avoid null optional params. (#1417, #1414, #1425) Thanks @czekaj.
- Exec/Windows: resolve Windows exec paths with extensions and handle safe-bin exe names.
 - Nodes/macOS: prompt on allowlist miss for node exec approvals, persist allowlist decisions, and flatten node invoke errors. (#1394) Thanks @ngutman.
- Gateway: prevent multiple gateways from sharing the same config/state (singleton lock), keep auto bind loopback-first with explicit tailnet binding, and improve SSH auth handling. (#1380)
- Control UI: remove the chat stop button, keep the composer aligned to the bottom edge, stabilize session previews, and refresh the debug panel on route-driven tab changes. (#1373) Thanks @yazinsai.
- UI/config: export `SECTION_META` for config form modules. (#1418) Thanks @MaudeBot.
- macOS: keep chat pinned during streaming replies, include Textual resources, respect wildcard exec approvals, allow SSH agent auth, and default distribution builds to universal binaries. (#1279, #1362, #1384, #1396) Thanks @ameno-, @JustYannicc.
- BlueBubbles: resolve short message IDs safely, expose full IDs in templates, and harden short-id fetch wrappers. (#1369, #1387) Thanks @tyler6204.
- Models/Configure: inherit session model overrides in threads/topics, map OpenCode Zen models to the correct APIs, narrow Anthropic OAuth allowlist handling, seed allowlist fallbacks, list the full catalog when no allowlist is set, and limit `/model` list output. (#1376, #1416)
- Memory: prevent CLI hangs by deferring vector probes, add sqlite-vec/embedding timeouts, and make session memory indexing async.
- Cron: cap reminder context history to 10 messages and honor `contextMessages`. (#1103) Thanks @mkbehr.
- Cache: restore the 1h cache TTL option and reset the pruning window.
- Zalo Personal: tolerate ANSI/log-prefixed JSON output from `zca`. (#1379) Thanks @ptn1411.
- Browser: suppress Chrome restore prompts for managed profiles. (#1419) Thanks @jamesgroat.
- Infra: preserve fetch helper methods/preconnect when wrapping abort signals and normalize Telegram fetch aborts.
- Config/Doctor: avoid stack traces for invalid configs, log the config path, avoid WhatsApp config resurrection, and warn when `gateway.mode` is unset. (#900)
- CLI: read Codex CLI account_id for workspace billing. (#1422) Thanks @aj47.
- Logs/Status: align rolling log filenames with local time and report sandboxed runtime in `clawdbot status`. (#1343)
+- Gateway: keep auto bind loopback-first and add explicit tailnet binding to avoid Tailscale taking over local UI. (#1380)
+- Agents: enforce 9-char alphanumeric tool call ids for Mistral providers. (#1372) Thanks @zerone0x.
 - Embedded runner: persist injected history images so attachments aren’t reloaded each turn. (#1374) Thanks @Nicell.
- Nodes/Subagents: include agent/node/gateway context in tool failure logs and ensure subagent list uses the command session.
+- Nodes tool: include agent/node/gateway context in tool failure logs to speed approval debugging.
+- macOS: exec approvals now respect wildcard agent allowlists (`*`).
+- macOS: allow SSH agent auth when no identity file is set. (#1384) Thanks @ameno-.
+- Gateway: prevent multiple gateways from sharing the same config/state at once (singleton lock).
+- UI: remove the chat stop button and keep the composer aligned to the bottom edge.
+- Typing: start instant typing indicators at run start so DMs and mentions show immediately.
+- Configure: restrict the model allowlist picker to OAuth-compatible Anthropic models and preselect Opus 4.5.
+- Configure: seed model fallbacks from the allowlist selection when multiple models are chosen.
+- Model picker: list the full catalog when no model allowlist is configured.
+- Discord: honor wildcard channel configs via shared match helpers. (#1334) Thanks @pvoo.
+- BlueBubbles: resolve short message IDs safely and expose full IDs in templates. (#1387) Thanks @tyler6204.
+- Infra: preserve fetch helper methods when wrapping abort signals. (#1387)
+- macOS: default distribution packaging to universal binaries. (#1396) Thanks @JustYannicc.

 ## 2026.1.20

@@ -477,28 +477,29 @@ Special thanks to [Mario Zechner](https://mariozechner.at/) for his support and
 Thanks to all clawtributors:

 <p align="left">
-  <a href="https://github.com/steipete"><img src="https://avatars.githubusercontent.com/u/58493?v=4&s=48" width="48" height="48" alt="steipete" title="steipete"/></a> <a href="https://github.com/bohdanpodvirnyi"><img src="https://avatars.githubusercontent.com/u/31819391?v=4&s=48" width="48" height="48" alt="bohdanpodvirnyi" title="bohdanpodvirnyi"/></a> <a href="https://github.com/joaohlisboa"><img src="https://avatars.githubusercontent.com/u/8200873?v=4&s=48" width="48" height="48" alt="joaohlisboa" title="joaohlisboa"/></a> <a href="https://github.com/mneves75"><img src="https://avatars.githubusercontent.com/u/2423436?v=4&s=48" width="48" height="48" alt="mneves75" title="mneves75"/></a> <a href="https://github.com/MatthieuBizien"><img src="https://avatars.githubusercontent.com/u/173090?v=4&s=48" width="48" height="48" alt="MatthieuBizien" title="MatthieuBizien"/></a> <a href="https://github.com/MaudeBot"><img src="https://avatars.githubusercontent.com/u/255777700?v=4&s=48" width="48" height="48" alt="MaudeBot" title="MaudeBot"/></a> <a href="https://github.com/rahthakor"><img src="https://avatars.githubusercontent.com/u/8470553?v=4&s=48" width="48" height="48" alt="rahthakor" title="rahthakor"/></a> <a href="https://github.com/vrknetha"><img src="https://avatars.githubusercontent.com/u/20596261?v=4&s=48" width="48" height="48" alt="vrknetha" title="vrknetha"/></a> <a href="https://github.com/radek-paclt"><img src="https://avatars.githubusercontent.com/u/50451445?v=4&s=48" width="48" height="48" alt="radek-paclt" title="radek-paclt"/></a> <a href="https://github.com/joshp123"><img src="https://avatars.githubusercontent.com/u/1497361?v=4&s=48" width="48" height="48" alt="joshp123" title="joshp123"/></a>
-  <a href="https://github.com/mukhtharcm"><img src="https://avatars.githubusercontent.com/u/56378562?v=4&s=48" width="48" height="48" alt="mukhtharcm" title="mukhtharcm"/></a> <a href="https://github.com/maxsumrall"><img src="https://avatars.githubusercontent.com/u/628843?v=4&s=48" width="48" height="48" alt="maxsumrall" title="maxsumrall"/></a> <a href="https://github.com/xadenryan"><img src="https://avatars.githubusercontent.com/u/165437834?v=4&s=48" width="48" height="48" alt="xadenryan" title="xadenryan"/></a> <a href="https://github.com/tobiasbischoff"><img src="https://avatars.githubusercontent.com/u/711564?v=4&s=48" width="48" height="48" alt="Tobias Bischoff" title="Tobias Bischoff"/></a> <a href="https://github.com/juanpablodlc"><img src="https://avatars.githubusercontent.com/u/92012363?v=4&s=48" width="48" height="48" alt="juanpablodlc" title="juanpablodlc"/></a> <a href="https://github.com/hsrvc"><img src="https://avatars.githubusercontent.com/u/129702169?v=4&s=48" width="48" height="48" alt="hsrvc" title="hsrvc"/></a> <a href="https://github.com/magimetal"><img src="https://avatars.githubusercontent.com/u/36491250?v=4&s=48" width="48" height="48" alt="magimetal" title="magimetal"/></a> <a href="https://github.com/meaningfool"><img src="https://avatars.githubusercontent.com/u/2862331?v=4&s=48" width="48" height="48" alt="meaningfool" title="meaningfool"/></a> <a href="https://github.com/NicholasSpisak"><img src="https://avatars.githubusercontent.com/u/129075147?v=4&s=48" width="48" height="48" alt="NicholasSpisak" title="NicholasSpisak"/></a> <a href="https://github.com/sebslight"><img src="https://avatars.githubusercontent.com/u/19554889?v=4&s=48" width="48" height="48" alt="sebslight" title="sebslight"/></a>
+  <a href="https://github.com/steipete"><img src="https://avatars.githubusercontent.com/u/58493?v=4&s=48" width="48" height="48" alt="steipete" title="steipete"/></a> <a href="https://github.com/bohdanpodvirnyi"><img src="https://avatars.githubusercontent.com/u/31819391?v=4&s=48" width="48" height="48" alt="bohdanpodvirnyi" title="bohdanpodvirnyi"/></a> <a href="https://github.com/joaohlisboa"><img src="https://avatars.githubusercontent.com/u/8200873?v=4&s=48" width="48" height="48" alt="joaohlisboa" title="joaohlisboa"/></a> <a href="https://github.com/mneves75"><img src="https://avatars.githubusercontent.com/u/2423436?v=4&s=48" width="48" height="48" alt="mneves75" title="mneves75"/></a> <a href="https://github.com/MatthieuBizien"><img src="https://avatars.githubusercontent.com/u/173090?v=4&s=48" width="48" height="48" alt="MatthieuBizien" title="MatthieuBizien"/></a> <a href="https://github.com/MaudeBot"><img src="https://avatars.githubusercontent.com/u/255777700?v=4&s=48" width="48" height="48" alt="MaudeBot" title="MaudeBot"/></a> <a href="https://github.com/rahthakor"><img src="https://avatars.githubusercontent.com/u/8470553?v=4&s=48" width="48" height="48" alt="rahthakor" title="rahthakor"/></a> <a href="https://github.com/vrknetha"><img src="https://avatars.githubusercontent.com/u/20596261?v=4&s=48" width="48" height="48" alt="vrknetha" title="vrknetha"/></a> <a href="https://github.com/radek-paclt"><img src="https://avatars.githubusercontent.com/u/50451445?v=4&s=48" width="48" height="48" alt="radek-paclt" title="radek-paclt"/></a> <a href="https://github.com/tobiasbischoff"><img src="https://avatars.githubusercontent.com/u/711564?v=4&s=48" width="48" height="48" alt="Tobias Bischoff" title="Tobias Bischoff"/></a>
+  <a href="https://github.com/joshp123"><img src="https://avatars.githubusercontent.com/u/1497361?v=4&s=48" width="48" height="48" alt="joshp123" title="joshp123"/></a> <a href="https://github.com/mukhtharcm"><img src="https://avatars.githubusercontent.com/u/56378562?v=4&s=48" width="48" height="48" alt="mukhtharcm" title="mukhtharcm"/></a> <a href="https://github.com/maxsumrall"><img src="https://avatars.githubusercontent.com/u/628843?v=4&s=48" width="48" height="48" alt="maxsumrall" title="maxsumrall"/></a> <a href="https://github.com/xadenryan"><img src="https://avatars.githubusercontent.com/u/165437834?v=4&s=48" width="48" height="48" alt="xadenryan" title="xadenryan"/></a> <a href="https://github.com/juanpablodlc"><img src="https://avatars.githubusercontent.com/u/92012363?v=4&s=48" width="48" height="48" alt="juanpablodlc" title="juanpablodlc"/></a> <a href="https://github.com/hsrvc"><img src="https://avatars.githubusercontent.com/u/129702169?v=4&s=48" width="48" height="48" alt="hsrvc" title="hsrvc"/></a> <a href="https://github.com/magimetal"><img src="https://avatars.githubusercontent.com/u/36491250?v=4&s=48" width="48" height="48" alt="magimetal" title="magimetal"/></a> <a href="https://github.com/meaningfool"><img src="https://avatars.githubusercontent.com/u/2862331?v=4&s=48" width="48" height="48" alt="meaningfool" title="meaningfool"/></a> <a href="https://github.com/NicholasSpisak"><img src="https://avatars.githubusercontent.com/u/129075147?v=4&s=48" width="48" height="48" alt="NicholasSpisak" title="NicholasSpisak"/></a> <a href="https://github.com/sebslight"><img src="https://avatars.githubusercontent.com/u/19554889?v=4&s=48" width="48" height="48" alt="sebslight" title="sebslight"/></a>
  <a href="https://github.com/AbhisekBasu1"><img src="https://avatars.githubusercontent.com/u/40645221?v=4&s=48" width="48" height="48" alt="abhisekbasu1" title="abhisekbasu1"/></a> <a href="https://github.com/jamesgroat"><img src="https://avatars.githubusercontent.com/u/2634024?v=4&s=48" width="48" height="48" alt="jamesgroat" title="jamesgroat"/></a> <a href="https://github.com/zerone0x"><img src="https://avatars.githubusercontent.com/u/39543393?v=4&s=48" width="48" height="48" alt="zerone0x" title="zerone0x"/></a> <a href="https://github.com/claude"><img src="https://avatars.githubusercontent.com/u/81847?v=4&s=48" width="48" height="48" alt="claude" title="claude"/></a> <a href="https://github.com/SocialNerd42069"><img src="https://avatars.githubusercontent.com/u/118244303?v=4&s=48" width="48" height="48" alt="SocialNerd42069" title="SocialNerd42069"/></a> <a href="https://github.com/Hyaxia"><img src="https://avatars.githubusercontent.com/u/36747317?v=4&s=48" width="48" height="48" alt="Hyaxia" title="Hyaxia"/></a> <a href="https://github.com/dantelex"><img src="https://avatars.githubusercontent.com/u/631543?v=4&s=48" width="48" height="48" alt="dantelex" title="dantelex"/></a> <a href="https://github.com/daveonkels"><img src="https://avatars.githubusercontent.com/u/533642?v=4&s=48" width="48" height="48" alt="daveonkels" title="daveonkels"/></a> <a href="https://github.com/mteam88"><img src="https://avatars.githubusercontent.com/u/84196639?v=4&s=48" width="48" height="48" alt="mteam88" title="mteam88"/></a> <a href="https://github.com/omniwired"><img src="https://avatars.githubusercontent.com/u/322761?v=4&s=48" width="48" height="48" alt="Eng. Juan Combetto" title="Eng. Juan Combetto"/></a>
  <a href="https://github.com/mbelinky"><img src="https://avatars.githubusercontent.com/u/132747814?v=4&s=48" width="48" height="48" alt="Mariano Belinky" title="Mariano Belinky"/></a> <a href="https://github.com/dbhurley"><img src="https://avatars.githubusercontent.com/u/5251425?v=4&s=48" width="48" height="48" alt="dbhurley" title="dbhurley"/></a> <a href="https://github.com/TSavo"><img src="https://avatars.githubusercontent.com/u/877990?v=4&s=48" width="48" height="48" alt="TSavo" title="TSavo"/></a> <a href="https://github.com/julianengel"><img src="https://avatars.githubusercontent.com/u/10634231?v=4&s=48" width="48" height="48" alt="julianengel" title="julianengel"/></a> <a href="https://github.com/benithors"><img src="https://avatars.githubusercontent.com/u/20652882?v=4&s=48" width="48" height="48" alt="benithors" title="benithors"/></a> <a href="https://github.com/bradleypriest"><img src="https://avatars.githubusercontent.com/u/167215?v=4&s=48" width="48" height="48" alt="bradleypriest" title="bradleypriest"/></a> <a href="https://github.com/timolins"><img src="https://avatars.githubusercontent.com/u/1440854?v=4&s=48" width="48" height="48" alt="timolins" title="timolins"/></a> <a href="https://github.com/Nachx639"><img src="https://avatars.githubusercontent.com/u/71144023?v=4&s=48" width="48" height="48" alt="nachx639" title="nachx639"/></a> <a href="https://github.com/sreekaransrinath"><img src="https://avatars.githubusercontent.com/u/50989977?v=4&s=48" width="48" height="48" alt="sreekaransrinath" title="sreekaransrinath"/></a> <a href="https://github.com/gupsammy"><img src="https://avatars.githubusercontent.com/u/20296019?v=4&s=48" width="48" height="48" alt="gupsammy" title="gupsammy"/></a>
  <a href="https://github.com/cristip73"><img src="https://avatars.githubusercontent.com/u/24499421?v=4&s=48" width="48" height="48" alt="cristip73" title="cristip73"/></a> <a href="https://github.com/nachoiacovino"><img src="https://avatars.githubusercontent.com/u/50103937?v=4&s=48" width="48" height="48" alt="nachoiacovino" title="nachoiacovino"/></a> <a href="https://github.com/vsabavat"><img src="https://avatars.githubusercontent.com/u/50385532?v=4&s=48" width="48" height="48" alt="Vasanth Rao Naik Sabavat" title="Vasanth Rao Naik Sabavat"/></a> <a href="https://github.com/cpojer"><img src="https://avatars.githubusercontent.com/u/13352?v=4&s=48" width="48" height="48" alt="cpojer" title="cpojer"/></a> <a href="https://github.com/lc0rp"><img src="https://avatars.githubusercontent.com/u/2609441?v=4&s=48" width="48" height="48" alt="lc0rp" title="lc0rp"/></a> <a href="https://github.com/scald"><img src="https://avatars.githubusercontent.com/u/1215913?v=4&s=48" width="48" height="48" alt="scald" title="scald"/></a> <a href="https://github.com/gumadeiras"><img src="https://avatars.githubusercontent.com/u/5599352?v=4&s=48" width="48" height="48" alt="gumadeiras" title="gumadeiras"/></a> <a href="https://github.com/andranik-sahakyan"><img src="https://avatars.githubusercontent.com/u/8908029?v=4&s=48" width="48" height="48" alt="andranik-sahakyan" title="andranik-sahakyan"/></a> <a href="https://github.com/davidguttman"><img src="https://avatars.githubusercontent.com/u/431696?v=4&s=48" width="48" height="48" alt="davidguttman" title="davidguttman"/></a> <a href="https://github.com/sleontenko"><img src="https://avatars.githubusercontent.com/u/7135949?v=4&s=48" width="48" height="48" alt="sleontenko" title="sleontenko"/></a>
  <a href="https://github.com/sircrumpet"><img src="https://avatars.githubusercontent.com/u/4436535?v=4&s=48" width="48" height="48" alt="sircrumpet" title="sircrumpet"/></a> <a href="https://github.com/peschee"><img src="https://avatars.githubusercontent.com/u/63866?v=4&s=48" width="48" height="48" alt="peschee" title="peschee"/></a> <a href="https://github.com/rafaelreis-r"><img src="https://avatars.githubusercontent.com/u/57492577?v=4&s=48" width="48" height="48" alt="rafaelreis-r" title="rafaelreis-r"/></a> <a href="https://github.com/thewilloftheshadow"><img src="https://avatars.githubusercontent.com/u/35580099?v=4&s=48" width="48" height="48" alt="thewilloftheshadow" title="thewilloftheshadow"/></a> <a href="https://github.com/ratulsarna"><img src="https://avatars.githubusercontent.com/u/105903728?v=4&s=48" width="48" height="48" alt="ratulsarna" title="ratulsarna"/></a> <a href="https://github.com/lutr0"><img src="https://avatars.githubusercontent.com/u/76906369?v=4&s=48" width="48" height="48" alt="lutr0" title="lutr0"/></a> <a href="https://github.com/danielz1z"><img src="https://avatars.githubusercontent.com/u/235270390?v=4&s=48" width="48" height="48" alt="danielz1z" title="danielz1z"/></a> <a href="https://github.com/emanuelst"><img src="https://avatars.githubusercontent.com/u/9994339?v=4&s=48" width="48" height="48" alt="emanuelst" title="emanuelst"/></a> <a href="https://github.com/KristijanJovanovski"><img src="https://avatars.githubusercontent.com/u/8942284?v=4&s=48" width="48" height="48" alt="KristijanJovanovski" title="KristijanJovanovski"/></a> <a href="https://github.com/CashWilliams"><img src="https://avatars.githubusercontent.com/u/613573?v=4&s=48" width="48" height="48" alt="CashWilliams" title="CashWilliams"/></a>
  <a href="https://github.com/rdev"><img src="https://avatars.githubusercontent.com/u/8418866?v=4&s=48" width="48" height="48" alt="rdev" title="rdev"/></a> <a href="https://github.com/osolmaz"><img src="https://avatars.githubusercontent.com/u/2453968?v=4&s=48" width="48" height="48" alt="osolmaz" title="osolmaz"/></a> <a href="https://github.com/joshrad-dev"><img src="https://avatars.githubusercontent.com/u/62785552?v=4&s=48" width="48" height="48" alt="joshrad-dev" title="joshrad-dev"/></a> <a href="https://github.com/kiranjd"><img src="https://avatars.githubusercontent.com/u/25822851?v=4&s=48" width="48" height="48" alt="kiranjd" title="kiranjd"/></a> <a href="https://github.com/adityashaw2"><img src="https://avatars.githubusercontent.com/u/41204444?v=4&s=48" width="48" height="48" alt="adityashaw2" title="adityashaw2"/></a> <a href="https://github.com/search?q=sheeek"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="sheeek" title="sheeek"/></a> <a href="https://github.com/artuskg"><img src="https://avatars.githubusercontent.com/u/11966157?v=4&s=48" width="48" height="48" alt="artuskg" title="artuskg"/></a> <a href="https://github.com/onutc"><img src="https://avatars.githubusercontent.com/u/152018508?v=4&s=48" width="48" height="48" alt="onutc" title="onutc"/></a> <a href="https://github.com/tyler6204"><img src="https://avatars.githubusercontent.com/u/64381258?v=4&s=48" width="48" height="48" alt="tyler6204" title="tyler6204"/></a> <a href="https://github.com/ManuelHettich"><img src="https://avatars.githubusercontent.com/u/17690367?v=4&s=48" width="48" height="48" alt="manuelhettich" title="manuelhettich"/></a>
-  <a href="https://github.com/minghinmatthewlam"><img src="https://avatars.githubusercontent.com/u/14224566?v=4&s=48" width="48" height="48" alt="minghinmatthewlam" title="minghinmatthewlam"/></a> <a href="https://github.com/myfunc"><img src="https://avatars.githubusercontent.com/u/19294627?v=4&s=48" width="48" height="48" alt="myfunc" title="myfunc"/></a> <a href="https://github.com/buddyh"><img src="https://avatars.githubusercontent.com/u/31752869?v=4&s=48" width="48" height="48" alt="buddyh" title="buddyh"/></a> <a href="https://github.com/connorshea"><img src="https://avatars.githubusercontent.com/u/2977353?v=4&s=48" width="48" height="48" alt="connorshea" title="connorshea"/></a> <a href="https://github.com/vignesh07"><img src="https://avatars.githubusercontent.com/u/1436853?v=4&s=48" width="48" height="48" alt="vignesh07" title="vignesh07"/></a> <a href="https://github.com/mcinteerj"><img src="https://avatars.githubusercontent.com/u/3613653?v=4&s=48" width="48" height="48" alt="mcinteerj" title="mcinteerj"/></a> <a href="https://github.com/apps/dependabot"><img src="https://avatars.githubusercontent.com/in/29110?v=4&s=48" width="48" height="48" alt="dependabot[bot]" title="dependabot[bot]"/></a> <a href="https://github.com/John-Rood"><img src="https://avatars.githubusercontent.com/u/62669593?v=4&s=48" width="48" height="48" alt="John-Rood" title="John-Rood"/></a> <a href="https://github.com/timkrase"><img src="https://avatars.githubusercontent.com/u/38947626?v=4&s=48" width="48" height="48" alt="timkrase" title="timkrase"/></a> <a href="https://github.com/gerardward2007"><img src="https://avatars.githubusercontent.com/u/3002155?v=4&s=48" width="48" height="48" alt="gerardward2007" title="gerardward2007"/></a>
+  <a href="https://github.com/minghinmatthewlam"><img src="https://avatars.githubusercontent.com/u/14224566?v=4&s=48" width="48" height="48" alt="minghinmatthewlam" title="minghinmatthewlam"/></a> <a href="https://github.com/myfunc"><img src="https://avatars.githubusercontent.com/u/19294627?v=4&s=48" width="48" height="48" alt="myfunc" title="myfunc"/></a> <a href="https://github.com/vignesh07"><img src="https://avatars.githubusercontent.com/u/1436853?v=4&s=48" width="48" height="48" alt="vignesh07" title="vignesh07"/></a> <a href="https://github.com/buddyh"><img src="https://avatars.githubusercontent.com/u/31752869?v=4&s=48" width="48" height="48" alt="buddyh" title="buddyh"/></a> <a href="https://github.com/connorshea"><img src="https://avatars.githubusercontent.com/u/2977353?v=4&s=48" width="48" height="48" alt="connorshea" title="connorshea"/></a> <a href="https://github.com/mcinteerj"><img src="https://avatars.githubusercontent.com/u/3613653?v=4&s=48" width="48" height="48" alt="mcinteerj" title="mcinteerj"/></a> <a href="https://github.com/apps/dependabot"><img src="https://avatars.githubusercontent.com/in/29110?v=4&s=48" width="48" height="48" alt="dependabot[bot]" title="dependabot[bot]"/></a> <a href="https://github.com/John-Rood"><img src="https://avatars.githubusercontent.com/u/62669593?v=4&s=48" width="48" height="48" alt="John-Rood" title="John-Rood"/></a> <a href="https://github.com/timkrase"><img src="https://avatars.githubusercontent.com/u/38947626?v=4&s=48" width="48" height="48" alt="timkrase" title="timkrase"/></a> <a href="https://github.com/gerardward2007"><img src="https://avatars.githubusercontent.com/u/3002155?v=4&s=48" width="48" height="48" alt="gerardward2007" title="gerardward2007"/></a>
  <a href="https://github.com/obviyus"><img src="https://avatars.githubusercontent.com/u/22031114?v=4&s=48" width="48" height="48" alt="obviyus" title="obviyus"/></a> <a href="https://github.com/tosh-hamburg"><img src="https://avatars.githubusercontent.com/u/58424326?v=4&s=48" width="48" height="48" alt="tosh-hamburg" title="tosh-hamburg"/></a> <a href="https://github.com/azade-c"><img src="https://avatars.githubusercontent.com/u/252790079?v=4&s=48" width="48" height="48" alt="azade-c" title="azade-c"/></a> <a href="https://github.com/roshanasingh4"><img src="https://avatars.githubusercontent.com/u/88576930?v=4&s=48" width="48" height="48" alt="roshanasingh4" title="roshanasingh4"/></a> <a href="https://github.com/bjesuiter"><img src="https://avatars.githubusercontent.com/u/2365676?v=4&s=48" width="48" height="48" alt="bjesuiter" title="bjesuiter"/></a> <a href="https://github.com/cheeeee"><img src="https://avatars.githubusercontent.com/u/21245729?v=4&s=48" width="48" height="48" alt="cheeeee" title="cheeeee"/></a> <a href="https://github.com/j1philli"><img src="https://avatars.githubusercontent.com/u/3744255?v=4&s=48" width="48" height="48" alt="Josh Phillips" title="Josh Phillips"/></a> <a href="https://github.com/Whoaa512"><img src="https://avatars.githubusercontent.com/u/1581943?v=4&s=48" width="48" height="48" alt="Whoaa512" title="Whoaa512"/></a> <a href="https://github.com/YuriNachos"><img src="https://avatars.githubusercontent.com/u/19365375?v=4&s=48" width="48" height="48" alt="YuriNachos" title="YuriNachos"/></a> <a href="https://github.com/chriseidhof"><img src="https://avatars.githubusercontent.com/u/5382?v=4&s=48" width="48" height="48" alt="chriseidhof" title="chriseidhof"/></a>
-  <a href="https://github.com/ysqander"><img src="https://avatars.githubusercontent.com/u/80843820?v=4&s=48" width="48" height="48" alt="ysqander" title="ysqander"/></a> <a href="https://github.com/superman32432432"><img src="https://avatars.githubusercontent.com/u/7228420?v=4&s=48" width="48" height="48" alt="superman32432432" title="superman32432432"/></a> <a href="https://github.com/search?q=Yurii%20Chukhlib"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Yurii Chukhlib" title="Yurii Chukhlib"/></a> <a href="https://github.com/grp06"><img src="https://avatars.githubusercontent.com/u/1573959?v=4&s=48" width="48" height="48" alt="grp06" title="grp06"/></a> <a href="https://github.com/antons"><img src="https://avatars.githubusercontent.com/u/129705?v=4&s=48" width="48" height="48" alt="antons" title="antons"/></a> <a href="https://github.com/austinm911"><img src="https://avatars.githubusercontent.com/u/31991302?v=4&s=48" width="48" height="48" alt="austinm911" title="austinm911"/></a> <a href="https://github.com/apps/blacksmith-sh"><img src="https://avatars.githubusercontent.com/in/807020?v=4&s=48" width="48" height="48" alt="blacksmith-sh[bot]" title="blacksmith-sh[bot]"/></a> <a href="https://github.com/dan-dr"><img src="https://avatars.githubusercontent.com/u/6669808?v=4&s=48" width="48" height="48" alt="dan-dr" title="dan-dr"/></a> <a href="https://github.com/dlauer"><img src="https://avatars.githubusercontent.com/u/757041?v=4&s=48" width="48" height="48" alt="dlauer" title="dlauer"/></a> <a href="https://github.com/HeimdallStrategy"><img src="https://avatars.githubusercontent.com/u/223014405?v=4&s=48" width="48" height="48" alt="HeimdallStrategy" title="HeimdallStrategy"/></a>
-  <a href="https://github.com/imfing"><img src="https://avatars.githubusercontent.com/u/5097752?v=4&s=48" width="48" height="48" alt="imfing" title="imfing"/></a> <a href="https://github.com/jalehman"><img src="https://avatars.githubusercontent.com/u/550978?v=4&s=48" width="48" height="48" alt="jalehman" title="jalehman"/></a> <a href="https://github.com/jarvis-medmatic"><img src="https://avatars.githubusercontent.com/u/252428873?v=4&s=48" width="48" height="48" alt="jarvis-medmatic" title="jarvis-medmatic"/></a> <a href="https://github.com/kkarimi"><img src="https://avatars.githubusercontent.com/u/875218?v=4&s=48" width="48" height="48" alt="kkarimi" title="kkarimi"/></a> <a href="https://github.com/mahmoudashraf93"><img src="https://avatars.githubusercontent.com/u/9130129?v=4&s=48" width="48" height="48" alt="mahmoudashraf93" title="mahmoudashraf93"/></a> <a href="https://github.com/ngutman"><img src="https://avatars.githubusercontent.com/u/1540134?v=4&s=48" width="48" height="48" alt="ngutman" title="ngutman"/></a> <a href="https://github.com/petter-b"><img src="https://avatars.githubusercontent.com/u/62076402?v=4&s=48" width="48" height="48" alt="petter-b" title="petter-b"/></a> <a href="https://github.com/pkrmf"><img src="https://avatars.githubusercontent.com/u/1714267?v=4&s=48" width="48" height="48" alt="pkrmf" title="pkrmf"/></a> <a href="https://github.com/RandyVentures"><img src="https://avatars.githubusercontent.com/u/149904821?v=4&s=48" width="48" height="48" alt="RandyVentures" title="RandyVentures"/></a> <a href="https://github.com/search?q=Ryan%20Lisse"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Ryan Lisse" title="Ryan Lisse"/></a>
-  <a href="https://github.com/dougvk"><img src="https://avatars.githubusercontent.com/u/401660?v=4&s=48" width="48" height="48" alt="dougvk" title="dougvk"/></a> <a href="https://github.com/erikpr1994"><img src="https://avatars.githubusercontent.com/u/6299331?v=4&s=48" width="48" height="48" alt="erikpr1994" title="erikpr1994"/></a> <a href="https://github.com/search?q=Ghost"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Ghost" title="Ghost"/></a> <a href="https://github.com/jonasjancarik"><img src="https://avatars.githubusercontent.com/u/2459191?v=4&s=48" width="48" height="48" alt="jonasjancarik" title="jonasjancarik"/></a> <a href="https://github.com/search?q=Keith%20the%20Silly%20Goose"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Keith the Silly Goose" title="Keith the Silly Goose"/></a> <a href="https://github.com/search?q=L36%20Server"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="L36 Server" title="L36 Server"/></a> <a href="https://github.com/search?q=Marc"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Marc" title="Marc"/></a> <a href="https://github.com/mitschabaude-bot"><img src="https://avatars.githubusercontent.com/u/247582884?v=4&s=48" width="48" height="48" alt="mitschabaude-bot" title="mitschabaude-bot"/></a> <a href="https://github.com/mkbehr"><img src="https://avatars.githubusercontent.com/u/1285?v=4&s=48" width="48" height="48" alt="mkbehr" title="mkbehr"/></a> <a href="https://github.com/neist"><img src="https://avatars.githubusercontent.com/u/1029724?v=4&s=48" width="48" height="48" alt="neist" title="neist"/></a>
-  <a href="https://github.com/chrisrodz"><img src="https://avatars.githubusercontent.com/u/2967620?v=4&s=48" width="48" height="48" alt="chrisrodz" title="chrisrodz"/></a> <a href="https://github.com/search?q=Friederike%20Seiler"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Friederike Seiler" title="Friederike Seiler"/></a> <a href="https://github.com/gabriel-trigo"><img src="https://avatars.githubusercontent.com/u/38991125?v=4&s=48" width="48" height="48" alt="gabriel-trigo" title="gabriel-trigo"/></a> <a href="https://github.com/Iamadig"><img src="https://avatars.githubusercontent.com/u/102129234?v=4&s=48" width="48" height="48" alt="iamadig" title="iamadig"/></a> <a href="https://github.com/search?q=Kit"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Kit" title="Kit"/></a> <a href="https://github.com/koala73"><img src="https://avatars.githubusercontent.com/u/996596?v=4&s=48" width="48" height="48" alt="koala73" title="koala73"/></a> <a href="https://github.com/manmal"><img src="https://avatars.githubusercontent.com/u/142797?v=4&s=48" width="48" height="48" alt="manmal" title="manmal"/></a> <a href="https://github.com/ogulcancelik"><img src="https://avatars.githubusercontent.com/u/7064011?v=4&s=48" width="48" height="48" alt="ogulcancelik" title="ogulcancelik"/></a> <a href="https://github.com/pasogott"><img src="https://avatars.githubusercontent.com/u/23458152?v=4&s=48" width="48" height="48" alt="pasogott" title="pasogott"/></a> <a href="https://github.com/petradonka"><img src="https://avatars.githubusercontent.com/u/7353770?v=4&s=48" width="48" height="48" alt="petradonka" title="petradonka"/></a>
-  <a href="https://github.com/rubyrunsstuff"><img src="https://avatars.githubusercontent.com/u/246602379?v=4&s=48" width="48" height="48" alt="rubyrunsstuff" title="rubyrunsstuff"/></a> <a href="https://github.com/sibbl"><img src="https://avatars.githubusercontent.com/u/866535?v=4&s=48" width="48" height="48" alt="sibbl" title="sibbl"/></a> <a href="https://github.com/siddhantjain"><img src="https://avatars.githubusercontent.com/u/4835232?v=4&s=48" width="48" height="48" alt="siddhantjain" title="siddhantjain"/></a> <a href="https://github.com/suminhthanh"><img src="https://avatars.githubusercontent.com/u/2907636?v=4&s=48" width="48" height="48" alt="suminhthanh" title="suminhthanh"/></a> <a href="https://github.com/VACInc"><img src="https://avatars.githubusercontent.com/u/3279061?v=4&s=48" width="48" height="48" alt="VACInc" title="VACInc"/></a> <a href="https://github.com/wes-davis"><img src="https://avatars.githubusercontent.com/u/16506720?v=4&s=48" width="48" height="48" alt="wes-davis" title="wes-davis"/></a> <a href="https://github.com/zats"><img src="https://avatars.githubusercontent.com/u/2688806?v=4&s=48" width="48" height="48" alt="zats" title="zats"/></a> <a href="https://github.com/24601"><img src="https://avatars.githubusercontent.com/u/1157207?v=4&s=48" width="48" height="48" alt="24601" title="24601"/></a> <a href="https://github.com/search?q=Chris%20Taylor"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Chris Taylor" title="Chris Taylor"/></a> <a href="https://github.com/czekaj"><img src="https://avatars.githubusercontent.com/u/1464539?v=4&s=48" width="48" height="48" alt="czekaj" title="czekaj"/></a>
-  <a href="https://github.com/djangonavarro220"><img src="https://avatars.githubusercontent.com/u/251162586?v=4&s=48" width="48" height="48" alt="Django Navarro" title="Django Navarro"/></a> <a href="https://github.com/evalexpr"><img src="https://avatars.githubusercontent.com/u/23485511?v=4&s=48" width="48" height="48" alt="evalexpr" title="evalexpr"/></a> <a href="https://github.com/henrino3"><img src="https://avatars.githubusercontent.com/u/4260288?v=4&s=48" width="48" height="48" alt="henrino3" title="henrino3"/></a> <a href="https://github.com/humanwritten"><img src="https://avatars.githubusercontent.com/u/206531610?v=4&s=48" width="48" height="48" alt="humanwritten" title="humanwritten"/></a> <a href="https://github.com/larlyssa"><img src="https://avatars.githubusercontent.com/u/13128869?v=4&s=48" width="48" height="48" alt="larlyssa" title="larlyssa"/></a> <a href="https://github.com/oswalpalash"><img src="https://avatars.githubusercontent.com/u/6431196?v=4&s=48" width="48" height="48" alt="oswalpalash" title="oswalpalash"/></a> <a href="https://github.com/pcty-nextgen-service-account"><img src="https://avatars.githubusercontent.com/u/112553441?v=4&s=48" width="48" height="48" alt="pcty-nextgen-service-account" title="pcty-nextgen-service-account"/></a> <a href="https://github.com/Syhids"><img src="https://avatars.githubusercontent.com/u/671202?v=4&s=48" width="48" height="48" alt="Syhids" title="Syhids"/></a> <a href="https://github.com/search?q=Aaron%20Konyer"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Aaron Konyer" title="Aaron Konyer"/></a> <a href="https://github.com/aaronveklabs"><img src="https://avatars.githubusercontent.com/u/225997828?v=4&s=48" width="48" height="48" alt="aaronveklabs" title="aaronveklabs"/></a>
-  <a href="https://github.com/adam91holt"><img src="https://avatars.githubusercontent.com/u/9592417?v=4&s=48" width="48" height="48" alt="adam91holt" title="adam91holt"/></a> <a href="https://github.com/ameno-"><img src="https://avatars.githubusercontent.com/u/2416135?v=4&s=48" width="48" height="48" alt="ameno-" title="ameno-"/></a> <a href="https://github.com/cash-echo-bot"><img src="https://avatars.githubusercontent.com/u/252747386?v=4&s=48" width="48" height="48" alt="cash-echo-bot" title="cash-echo-bot"/></a> <a href="https://github.com/search?q=Clawd"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Clawd" title="Clawd"/></a> <a href="https://github.com/search?q=ClawdFx"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="ClawdFx" title="ClawdFx"/></a> <a href="https://github.com/erik-agens"><img src="https://avatars.githubusercontent.com/u/80908960?v=4&s=48" width="48" height="48" alt="erik-agens" title="erik-agens"/></a> <a href="https://github.com/fcatuhe"><img src="https://avatars.githubusercontent.com/u/17382215?v=4&s=48" width="48" height="48" alt="fcatuhe" title="fcatuhe"/></a> <a href="https://github.com/ivanrvpereira"><img src="https://avatars.githubusercontent.com/u/183991?v=4&s=48" width="48" height="48" alt="ivanrvpereira" title="ivanrvpereira"/></a> <a href="https://github.com/jayhickey"><img src="https://avatars.githubusercontent.com/u/1676460?v=4&s=48" width="48" height="48" alt="jayhickey" title="jayhickey"/></a> <a href="https://github.com/jeffersonwarrior"><img src="https://avatars.githubusercontent.com/u/89030989?v=4&s=48" width="48" height="48" alt="jeffersonwarrior" title="jeffersonwarrior"/></a>
-  <a href="https://github.com/search?q=jeffersonwarrior"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="jeffersonwarrior" title="jeffersonwarrior"/></a> <a href="https://github.com/jdrhyne"><img src="https://avatars.githubusercontent.com/u/7828464?v=4&s=48" width="48" height="48" alt="Jonathan D. Rhyne (DJ-D)" title="Jonathan D. Rhyne (DJ-D)"/></a> <a href="https://github.com/jverdi"><img src="https://avatars.githubusercontent.com/u/345050?v=4&s=48" width="48" height="48" alt="jverdi" title="jverdi"/></a> <a href="https://github.com/longmaba"><img src="https://avatars.githubusercontent.com/u/9361500?v=4&s=48" width="48" height="48" alt="longmaba" title="longmaba"/></a> <a href="https://github.com/mickahouan"><img src="https://avatars.githubusercontent.com/u/31423109?v=4&s=48" width="48" height="48" alt="mickahouan" title="mickahouan"/></a> <a href="https://github.com/mjrussell"><img src="https://avatars.githubusercontent.com/u/1641895?v=4&s=48" width="48" height="48" alt="mjrussell" title="mjrussell"/></a> <a href="https://github.com/p6l-richard"><img src="https://avatars.githubusercontent.com/u/18185649?v=4&s=48" width="48" height="48" alt="p6l-richard" title="p6l-richard"/></a> <a href="https://github.com/philipp-spiess"><img src="https://avatars.githubusercontent.com/u/458591?v=4&s=48" width="48" height="48" alt="philipp-spiess" title="philipp-spiess"/></a> <a href="https://github.com/robaxelsen"><img src="https://avatars.githubusercontent.com/u/13132899?v=4&s=48" width="48" height="48" alt="robaxelsen" title="robaxelsen"/></a> <a href="https://github.com/search?q=Sash%20Catanzarite"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Sash Catanzarite" title="Sash Catanzarite"/></a>
-  <a href="https://github.com/T5-AndyML"><img src="https://avatars.githubusercontent.com/u/22801233?v=4&s=48" width="48" height="48" alt="T5-AndyML" title="T5-AndyML"/></a> <a href="https://github.com/search?q=VAC"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="VAC" title="VAC"/></a> <a href="https://github.com/zknicker"><img src="https://avatars.githubusercontent.com/u/1164085?v=4&s=48" width="48" height="48" alt="zknicker" title="zknicker"/></a> <a href="https://github.com/aj47"><img src="https://avatars.githubusercontent.com/u/8023513?v=4&s=48" width="48" height="48" alt="aj47" title="aj47"/></a> <a href="https://github.com/search?q=alejandro%20maza"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="alejandro maza" title="alejandro maza"/></a> <a href="https://github.com/andrewting19"><img src="https://avatars.githubusercontent.com/u/10536704?v=4&s=48" width="48" height="48" alt="andrewting19" title="andrewting19"/></a> <a href="https://github.com/search?q=Andrii"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Andrii" title="Andrii"/></a> <a href="https://github.com/anpoirier"><img src="https://avatars.githubusercontent.com/u/1245729?v=4&s=48" width="48" height="48" alt="anpoirier" title="anpoirier"/></a> <a href="https://github.com/Asleep123"><img src="https://avatars.githubusercontent.com/u/122379135?v=4&s=48" width="48" height="48" alt="Asleep123" title="Asleep123"/></a> <a href="https://github.com/bolismauro"><img src="https://avatars.githubusercontent.com/u/771999?v=4&s=48" width="48" height="48" alt="bolismauro" title="bolismauro"/></a>
-  <a href="https://github.com/conhecendoia"><img src="https://avatars.githubusercontent.com/u/82890727?v=4&s=48" width="48" height="48" alt="conhecendoia" title="conhecendoia"/></a> <a href="https://github.com/search?q=Dimitrios%20Ploutarchos"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Dimitrios Ploutarchos" title="Dimitrios Ploutarchos"/></a> <a href="https://github.com/search?q=Drake%20Thomsen"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Drake Thomsen" title="Drake Thomsen"/></a> <a href="https://github.com/search?q=Felix%20Krause"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Felix Krause" title="Felix Krause"/></a> <a href="https://github.com/gtsifrikas"><img src="https://avatars.githubusercontent.com/u/8904378?v=4&s=48" width="48" height="48" alt="gtsifrikas" title="gtsifrikas"/></a> <a href="https://github.com/HazAT"><img src="https://avatars.githubusercontent.com/u/363802?v=4&s=48" width="48" height="48" alt="HazAT" title="HazAT"/></a> <a href="https://github.com/hrdwdmrbl"><img src="https://avatars.githubusercontent.com/u/554881?v=4&s=48" width="48" height="48" alt="hrdwdmrbl" title="hrdwdmrbl"/></a> <a href="https://github.com/hugobarauna"><img src="https://avatars.githubusercontent.com/u/2719?v=4&s=48" width="48" height="48" alt="hugobarauna" title="hugobarauna"/></a> <a href="https://github.com/search?q=Jamie%20Openshaw"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Jamie Openshaw" title="Jamie Openshaw"/></a> <a href="https://github.com/search?q=Jarvis"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Jarvis" title="Jarvis"/></a>
-  <a href="https://github.com/search?q=Jefferson%20Nunn"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Jefferson Nunn" title="Jefferson Nunn"/></a> <a href="https://github.com/search?q=Kevin%20Lin"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Kevin Lin" title="Kevin Lin"/></a> <a href="https://github.com/kitze"><img src="https://avatars.githubusercontent.com/u/1160594?v=4&s=48" width="48" height="48" alt="kitze" title="kitze"/></a> <a href="https://github.com/levifig"><img src="https://avatars.githubusercontent.com/u/1605?v=4&s=48" width="48" height="48" alt="levifig" title="levifig"/></a> <a href="https://github.com/search?q=Lloyd"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Lloyd" title="Lloyd"/></a> <a href="https://github.com/loukotal"><img src="https://avatars.githubusercontent.com/u/18210858?v=4&s=48" width="48" height="48" alt="loukotal" title="loukotal"/></a> <a href="https://github.com/martinpucik"><img src="https://avatars.githubusercontent.com/u/5503097?v=4&s=48" width="48" height="48" alt="martinpucik" title="martinpucik"/></a> <a href="https://github.com/search?q=Miles"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Miles" title="Miles"/></a> <a href="https://github.com/mrdbstn"><img src="https://avatars.githubusercontent.com/u/58957632?v=4&s=48" width="48" height="48" alt="mrdbstn" title="mrdbstn"/></a> <a href="https://github.com/MSch"><img src="https://avatars.githubusercontent.com/u/7475?v=4&s=48" width="48" height="48" alt="MSch" title="MSch"/></a>
-  <a href="https://github.com/search?q=Mustafa%20Tag%20Eldeen"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Mustafa Tag Eldeen" title="Mustafa Tag Eldeen"/></a> <a href="https://github.com/ndraiman"><img src="https://avatars.githubusercontent.com/u/12609607?v=4&s=48" width="48" height="48" alt="ndraiman" title="ndraiman"/></a> <a href="https://github.com/nexty5870"><img src="https://avatars.githubusercontent.com/u/3869659?v=4&s=48" width="48" height="48" alt="nexty5870" title="nexty5870"/></a> <a href="https://github.com/odysseus0"><img src="https://avatars.githubusercontent.com/u/8635094?v=4&s=48" width="48" height="48" alt="odysseus0" title="odysseus0"/></a> <a href="https://github.com/prathamdby"><img src="https://avatars.githubusercontent.com/u/134331217?v=4&s=48" width="48" height="48" alt="prathamdby" title="prathamdby"/></a> <a href="https://github.com/ptn1411"><img src="https://avatars.githubusercontent.com/u/57529765?v=4&s=48" width="48" height="48" alt="ptn1411" title="ptn1411"/></a> <a href="https://github.com/reeltimeapps"><img src="https://avatars.githubusercontent.com/u/637338?v=4&s=48" width="48" height="48" alt="reeltimeapps" title="reeltimeapps"/></a> <a href="https://github.com/RLTCmpe"><img src="https://avatars.githubusercontent.com/u/10762242?v=4&s=48" width="48" height="48" alt="RLTCmpe" title="RLTCmpe"/></a> <a href="https://github.com/robbyczgw-cla"><img src="https://avatars.githubusercontent.com/u/239660374?v=4&s=48" width="48" height="48" alt="robbyczgw-cla" title="robbyczgw-cla"/></a> <a href="https://github.com/rodrigouroz"><img src="https://avatars.githubusercontent.com/u/384037?v=4&s=48" width="48" height="48" alt="rodrigouroz" title="rodrigouroz"/></a>
-  <a href="https://github.com/search?q=Rolf%20Fredheim"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Rolf Fredheim" title="Rolf Fredheim"/></a> <a href="https://github.com/search?q=Rony%20Kelner"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Rony Kelner" title="Rony Kelner"/></a> <a href="https://github.com/search?q=Samrat%20Jha"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Samrat Jha" title="Samrat Jha"/></a> <a href="https://github.com/siraht"><img src="https://avatars.githubusercontent.com/u/73152895?v=4&s=48" width="48" height="48" alt="siraht" title="siraht"/></a> <a href="https://github.com/snopoke"><img src="https://avatars.githubusercontent.com/u/249606?v=4&s=48" width="48" height="48" alt="snopoke" title="snopoke"/></a> <a href="https://github.com/search?q=The%20Admiral"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="The Admiral" title="The Admiral"/></a> <a href="https://github.com/thesash"><img src="https://avatars.githubusercontent.com/u/1166151?v=4&s=48" width="48" height="48" alt="thesash" title="thesash"/></a> <a href="https://github.com/search?q=Ubuntu"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Ubuntu" title="Ubuntu"/></a> <a href="https://github.com/voidserf"><img src="https://avatars.githubusercontent.com/u/477673?v=4&s=48" width="48" height="48" alt="voidserf" title="voidserf"/></a> <a href="https://github.com/search?q=Vultr-Clawd%20Admin"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Vultr-Clawd Admin" title="Vultr-Clawd Admin"/></a>
-  <a href="https://github.com/search?q=Wimmie"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Wimmie" title="Wimmie"/></a> <a href="https://github.com/wstock"><img src="https://avatars.githubusercontent.com/u/1394687?v=4&s=48" width="48" height="48" alt="wstock" title="wstock"/></a> <a href="https://github.com/yazinsai"><img src="https://avatars.githubusercontent.com/u/1846034?v=4&s=48" width="48" height="48" alt="yazinsai" title="yazinsai"/></a> <a href="https://github.com/search?q=Zach%20Knickerbocker"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Zach Knickerbocker" title="Zach Knickerbocker"/></a> <a href="https://github.com/Alphonse-arianee"><img src="https://avatars.githubusercontent.com/u/254457365?v=4&s=48" width="48" height="48" alt="Alphonse-arianee" title="Alphonse-arianee"/></a> <a href="https://github.com/search?q=Azade"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Azade" title="Azade"/></a> <a href="https://github.com/carlulsoe"><img src="https://avatars.githubusercontent.com/u/34673973?v=4&s=48" width="48" height="48" alt="carlulsoe" title="carlulsoe"/></a> <a href="https://github.com/search?q=ddyo"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="ddyo" title="ddyo"/></a> <a href="https://github.com/search?q=Erik"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Erik" title="Erik"/></a> <a href="https://github.com/latitudeki5223"><img src="https://avatars.githubusercontent.com/u/119656367?v=4&s=48" width="48" height="48" alt="latitudeki5223" title="latitudeki5223"/></a>
-  <a href="https://github.com/search?q=Manuel%20Maly"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Manuel Maly" title="Manuel Maly"/></a> <a href="https://github.com/search?q=Mourad%20Boustani"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Mourad Boustani" title="Mourad Boustani"/></a> <a href="https://github.com/odrobnik"><img src="https://avatars.githubusercontent.com/u/333270?v=4&s=48" width="48" height="48" alt="odrobnik" title="odrobnik"/></a> <a href="https://github.com/pcty-nextgen-ios-builder"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="pcty-nextgen-ios-builder" title="pcty-nextgen-ios-builder"/></a> <a href="https://github.com/search?q=Quentin"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Quentin" title="Quentin"/></a> <a href="https://github.com/search?q=Randy%20Torres"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Randy Torres" title="Randy Torres"/></a> <a href="https://github.com/rhjoh"><img src="https://avatars.githubusercontent.com/u/105699450?v=4&s=48" width="48" height="48" alt="rhjoh" title="rhjoh"/></a> <a href="https://github.com/ronak-guliani"><img src="https://avatars.githubusercontent.com/u/23518228?v=4&s=48" width="48" height="48" alt="ronak-guliani" title="ronak-guliani"/></a> <a href="https://github.com/search?q=William%20Stock"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="William Stock" title="William Stock"/></a>
+  <a href="https://github.com/ysqander"><img src="https://avatars.githubusercontent.com/u/80843820?v=4&s=48" width="48" height="48" alt="ysqander" title="ysqander"/></a> <a href="https://github.com/dlauer"><img src="https://avatars.githubusercontent.com/u/757041?v=4&s=48" width="48" height="48" alt="dlauer" title="dlauer"/></a> <a href="https://github.com/superman32432432"><img src="https://avatars.githubusercontent.com/u/7228420?v=4&s=48" width="48" height="48" alt="superman32432432" title="superman32432432"/></a> <a href="https://github.com/search?q=Yurii%20Chukhlib"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Yurii Chukhlib" title="Yurii Chukhlib"/></a> <a href="https://github.com/grp06"><img src="https://avatars.githubusercontent.com/u/1573959?v=4&s=48" width="48" height="48" alt="grp06" title="grp06"/></a> <a href="https://github.com/antons"><img src="https://avatars.githubusercontent.com/u/129705?v=4&s=48" width="48" height="48" alt="antons" title="antons"/></a> <a href="https://github.com/austinm911"><img src="https://avatars.githubusercontent.com/u/31991302?v=4&s=48" width="48" height="48" alt="austinm911" title="austinm911"/></a> <a href="https://github.com/apps/blacksmith-sh"><img src="https://avatars.githubusercontent.com/in/807020?v=4&s=48" width="48" height="48" alt="blacksmith-sh[bot]" title="blacksmith-sh[bot]"/></a> <a href="https://github.com/damoahdominic"><img src="https://avatars.githubusercontent.com/u/4623434?v=4&s=48" width="48" height="48" alt="damoahdominic" title="damoahdominic"/></a> <a href="https://github.com/dan-dr"><img src="https://avatars.githubusercontent.com/u/6669808?v=4&s=48" width="48" height="48" alt="dan-dr" title="dan-dr"/></a>
+  <a href="https://github.com/HeimdallStrategy"><img src="https://avatars.githubusercontent.com/u/223014405?v=4&s=48" width="48" height="48" alt="HeimdallStrategy" title="HeimdallStrategy"/></a> <a href="https://github.com/imfing"><img src="https://avatars.githubusercontent.com/u/5097752?v=4&s=48" width="48" height="48" alt="imfing" title="imfing"/></a> <a href="https://github.com/jalehman"><img src="https://avatars.githubusercontent.com/u/550978?v=4&s=48" width="48" height="48" alt="jalehman" title="jalehman"/></a> <a href="https://github.com/jarvis-medmatic"><img src="https://avatars.githubusercontent.com/u/252428873?v=4&s=48" width="48" height="48" alt="jarvis-medmatic" title="jarvis-medmatic"/></a> <a href="https://github.com/kkarimi"><img src="https://avatars.githubusercontent.com/u/875218?v=4&s=48" width="48" height="48" alt="kkarimi" title="kkarimi"/></a> <a href="https://github.com/mahmoudashraf93"><img src="https://avatars.githubusercontent.com/u/9130129?v=4&s=48" width="48" height="48" alt="mahmoudashraf93" title="mahmoudashraf93"/></a> <a href="https://github.com/ngutman"><img src="https://avatars.githubusercontent.com/u/1540134?v=4&s=48" width="48" height="48" alt="ngutman" title="ngutman"/></a> <a href="https://github.com/petter-b"><img src="https://avatars.githubusercontent.com/u/62076402?v=4&s=48" width="48" height="48" alt="petter-b" title="petter-b"/></a> <a href="https://github.com/pkrmf"><img src="https://avatars.githubusercontent.com/u/1714267?v=4&s=48" width="48" height="48" alt="pkrmf" title="pkrmf"/></a> <a href="https://github.com/RandyVentures"><img src="https://avatars.githubusercontent.com/u/149904821?v=4&s=48" width="48" height="48" alt="RandyVentures" title="RandyVentures"/></a>
+  <a href="https://github.com/robbyczgw-cla"><img src="https://avatars.githubusercontent.com/u/239660374?v=4&s=48" width="48" height="48" alt="robbyczgw-cla" title="robbyczgw-cla"/></a> <a href="https://github.com/search?q=Ryan%20Lisse"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Ryan Lisse" title="Ryan Lisse"/></a> <a href="https://github.com/dougvk"><img src="https://avatars.githubusercontent.com/u/401660?v=4&s=48" width="48" height="48" alt="dougvk" title="dougvk"/></a> <a href="https://github.com/erikpr1994"><img src="https://avatars.githubusercontent.com/u/6299331?v=4&s=48" width="48" height="48" alt="erikpr1994" title="erikpr1994"/></a> <a href="https://github.com/search?q=Ghost"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Ghost" title="Ghost"/></a> <a href="https://github.com/jonasjancarik"><img src="https://avatars.githubusercontent.com/u/2459191?v=4&s=48" width="48" height="48" alt="jonasjancarik" title="jonasjancarik"/></a> <a href="https://github.com/search?q=Keith%20the%20Silly%20Goose"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Keith the Silly Goose" title="Keith the Silly Goose"/></a> <a href="https://github.com/search?q=L36%20Server"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="L36 Server" title="L36 Server"/></a> <a href="https://github.com/search?q=Marc"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Marc" title="Marc"/></a> <a href="https://github.com/mitschabaude-bot"><img src="https://avatars.githubusercontent.com/u/247582884?v=4&s=48" width="48" height="48" alt="mitschabaude-bot" title="mitschabaude-bot"/></a>
+  <a href="https://github.com/mkbehr"><img src="https://avatars.githubusercontent.com/u/1285?v=4&s=48" width="48" height="48" alt="mkbehr" title="mkbehr"/></a> <a href="https://github.com/neist"><img src="https://avatars.githubusercontent.com/u/1029724?v=4&s=48" width="48" height="48" alt="neist" title="neist"/></a> <a href="https://github.com/chrisrodz"><img src="https://avatars.githubusercontent.com/u/2967620?v=4&s=48" width="48" height="48" alt="chrisrodz" title="chrisrodz"/></a> <a href="https://github.com/czekaj"><img src="https://avatars.githubusercontent.com/u/1464539?v=4&s=48" width="48" height="48" alt="czekaj" title="czekaj"/></a> <a href="https://github.com/search?q=Friederike%20Seiler"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Friederike Seiler" title="Friederike Seiler"/></a> <a href="https://github.com/gabriel-trigo"><img src="https://avatars.githubusercontent.com/u/38991125?v=4&s=48" width="48" height="48" alt="gabriel-trigo" title="gabriel-trigo"/></a> <a href="https://github.com/Iamadig"><img src="https://avatars.githubusercontent.com/u/102129234?v=4&s=48" width="48" height="48" alt="iamadig" title="iamadig"/></a> <a href="https://github.com/jdrhyne"><img src="https://avatars.githubusercontent.com/u/7828464?v=4&s=48" width="48" height="48" alt="Jonathan D. Rhyne (DJ-D)" title="Jonathan D. Rhyne (DJ-D)"/></a> <a href="https://github.com/search?q=Kit"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Kit" title="Kit"/></a> <a href="https://github.com/koala73"><img src="https://avatars.githubusercontent.com/u/996596?v=4&s=48" width="48" height="48" alt="koala73" title="koala73"/></a>
+  <a href="https://github.com/manmal"><img src="https://avatars.githubusercontent.com/u/142797?v=4&s=48" width="48" height="48" alt="manmal" title="manmal"/></a> <a href="https://github.com/ogulcancelik"><img src="https://avatars.githubusercontent.com/u/7064011?v=4&s=48" width="48" height="48" alt="ogulcancelik" title="ogulcancelik"/></a> <a href="https://github.com/pasogott"><img src="https://avatars.githubusercontent.com/u/23458152?v=4&s=48" width="48" height="48" alt="pasogott" title="pasogott"/></a> <a href="https://github.com/petradonka"><img src="https://avatars.githubusercontent.com/u/7353770?v=4&s=48" width="48" height="48" alt="petradonka" title="petradonka"/></a> <a href="https://github.com/rubyrunsstuff"><img src="https://avatars.githubusercontent.com/u/246602379?v=4&s=48" width="48" height="48" alt="rubyrunsstuff" title="rubyrunsstuff"/></a> <a href="https://github.com/sibbl"><img src="https://avatars.githubusercontent.com/u/866535?v=4&s=48" width="48" height="48" alt="sibbl" title="sibbl"/></a> <a href="https://github.com/siddhantjain"><img src="https://avatars.githubusercontent.com/u/4835232?v=4&s=48" width="48" height="48" alt="siddhantjain" title="siddhantjain"/></a> <a href="https://github.com/suminhthanh"><img src="https://avatars.githubusercontent.com/u/2907636?v=4&s=48" width="48" height="48" alt="suminhthanh" title="suminhthanh"/></a> <a href="https://github.com/VACInc"><img src="https://avatars.githubusercontent.com/u/3279061?v=4&s=48" width="48" height="48" alt="VACInc" title="VACInc"/></a> <a href="https://github.com/wes-davis"><img src="https://avatars.githubusercontent.com/u/16506720?v=4&s=48" width="48" height="48" alt="wes-davis" title="wes-davis"/></a>
+  <a href="https://github.com/zats"><img src="https://avatars.githubusercontent.com/u/2688806?v=4&s=48" width="48" height="48" alt="zats" title="zats"/></a> <a href="https://github.com/24601"><img src="https://avatars.githubusercontent.com/u/1157207?v=4&s=48" width="48" height="48" alt="24601" title="24601"/></a> <a href="https://github.com/ameno-"><img src="https://avatars.githubusercontent.com/u/2416135?v=4&s=48" width="48" height="48" alt="ameno-" title="ameno-"/></a> <a href="https://github.com/search?q=Chris%20Taylor"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Chris Taylor" title="Chris Taylor"/></a> <a href="https://github.com/djangonavarro220"><img src="https://avatars.githubusercontent.com/u/251162586?v=4&s=48" width="48" height="48" alt="Django Navarro" title="Django Navarro"/></a> <a href="https://github.com/evalexpr"><img src="https://avatars.githubusercontent.com/u/23485511?v=4&s=48" width="48" height="48" alt="evalexpr" title="evalexpr"/></a> <a href="https://github.com/henrino3"><img src="https://avatars.githubusercontent.com/u/4260288?v=4&s=48" width="48" height="48" alt="henrino3" title="henrino3"/></a> <a href="https://github.com/humanwritten"><img src="https://avatars.githubusercontent.com/u/206531610?v=4&s=48" width="48" height="48" alt="humanwritten" title="humanwritten"/></a> <a href="https://github.com/larlyssa"><img src="https://avatars.githubusercontent.com/u/13128869?v=4&s=48" width="48" height="48" alt="larlyssa" title="larlyssa"/></a> <a href="https://github.com/oswalpalash"><img src="https://avatars.githubusercontent.com/u/6431196?v=4&s=48" width="48" height="48" alt="oswalpalash" title="oswalpalash"/></a>
+  <a href="https://github.com/pcty-nextgen-service-account"><img src="https://avatars.githubusercontent.com/u/112553441?v=4&s=48" width="48" height="48" alt="pcty-nextgen-service-account" title="pcty-nextgen-service-account"/></a> <a href="https://github.com/Syhids"><img src="https://avatars.githubusercontent.com/u/671202?v=4&s=48" width="48" height="48" alt="Syhids" title="Syhids"/></a> <a href="https://github.com/search?q=Aaron%20Konyer"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Aaron Konyer" title="Aaron Konyer"/></a> <a href="https://github.com/aaronveklabs"><img src="https://avatars.githubusercontent.com/u/225997828?v=4&s=48" width="48" height="48" alt="aaronveklabs" title="aaronveklabs"/></a> <a href="https://github.com/adam91holt"><img src="https://avatars.githubusercontent.com/u/9592417?v=4&s=48" width="48" height="48" alt="adam91holt" title="adam91holt"/></a> <a href="https://github.com/cash-echo-bot"><img src="https://avatars.githubusercontent.com/u/252747386?v=4&s=48" width="48" height="48" alt="cash-echo-bot" title="cash-echo-bot"/></a> <a href="https://github.com/search?q=Clawd"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Clawd" title="Clawd"/></a> <a href="https://github.com/search?q=ClawdFx"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="ClawdFx" title="ClawdFx"/></a> <a href="https://github.com/erik-agens"><img src="https://avatars.githubusercontent.com/u/80908960?v=4&s=48" width="48" height="48" alt="erik-agens" title="erik-agens"/></a> <a href="https://github.com/fcatuhe"><img src="https://avatars.githubusercontent.com/u/17382215?v=4&s=48" width="48" height="48" alt="fcatuhe" title="fcatuhe"/></a>
+  <a href="https://github.com/ivanrvpereira"><img src="https://avatars.githubusercontent.com/u/183991?v=4&s=48" width="48" height="48" alt="ivanrvpereira" title="ivanrvpereira"/></a> <a href="https://github.com/jayhickey"><img src="https://avatars.githubusercontent.com/u/1676460?v=4&s=48" width="48" height="48" alt="jayhickey" title="jayhickey"/></a> <a href="https://github.com/jeffersonwarrior"><img src="https://avatars.githubusercontent.com/u/89030989?v=4&s=48" width="48" height="48" alt="jeffersonwarrior" title="jeffersonwarrior"/></a> <a href="https://github.com/search?q=jeffersonwarrior"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="jeffersonwarrior" title="jeffersonwarrior"/></a> <a href="https://github.com/jverdi"><img src="https://avatars.githubusercontent.com/u/345050?v=4&s=48" width="48" height="48" alt="jverdi" title="jverdi"/></a> <a href="https://github.com/longmaba"><img src="https://avatars.githubusercontent.com/u/9361500?v=4&s=48" width="48" height="48" alt="longmaba" title="longmaba"/></a> <a href="https://github.com/mickahouan"><img src="https://avatars.githubusercontent.com/u/31423109?v=4&s=48" width="48" height="48" alt="mickahouan" title="mickahouan"/></a> <a href="https://github.com/mjrussell"><img src="https://avatars.githubusercontent.com/u/1641895?v=4&s=48" width="48" height="48" alt="mjrussell" title="mjrussell"/></a> <a href="https://github.com/p6l-richard"><img src="https://avatars.githubusercontent.com/u/18185649?v=4&s=48" width="48" height="48" alt="p6l-richard" title="p6l-richard"/></a> <a href="https://github.com/philipp-spiess"><img src="https://avatars.githubusercontent.com/u/458591?v=4&s=48" width="48" height="48" alt="philipp-spiess" title="philipp-spiess"/></a>
+  <a href="https://github.com/robaxelsen"><img src="https://avatars.githubusercontent.com/u/13132899?v=4&s=48" width="48" height="48" alt="robaxelsen" title="robaxelsen"/></a> <a href="https://github.com/search?q=Sash%20Catanzarite"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Sash Catanzarite" title="Sash Catanzarite"/></a> <a href="https://github.com/T5-AndyML"><img src="https://avatars.githubusercontent.com/u/22801233?v=4&s=48" width="48" height="48" alt="T5-AndyML" title="T5-AndyML"/></a> <a href="https://github.com/search?q=VAC"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="VAC" title="VAC"/></a> <a href="https://github.com/zknicker"><img src="https://avatars.githubusercontent.com/u/1164085?v=4&s=48" width="48" height="48" alt="zknicker" title="zknicker"/></a> <a href="https://github.com/aj47"><img src="https://avatars.githubusercontent.com/u/8023513?v=4&s=48" width="48" height="48" alt="aj47" title="aj47"/></a> <a href="https://github.com/search?q=alejandro%20maza"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="alejandro maza" title="alejandro maza"/></a> <a href="https://github.com/andrewting19"><img src="https://avatars.githubusercontent.com/u/10536704?v=4&s=48" width="48" height="48" alt="andrewting19" title="andrewting19"/></a> <a href="https://github.com/search?q=Andrii"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Andrii" title="Andrii"/></a> <a href="https://github.com/anpoirier"><img src="https://avatars.githubusercontent.com/u/1245729?v=4&s=48" width="48" height="48" alt="anpoirier" title="anpoirier"/></a>
+  <a href="https://github.com/Asleep123"><img src="https://avatars.githubusercontent.com/u/122379135?v=4&s=48" width="48" height="48" alt="Asleep123" title="Asleep123"/></a> <a href="https://github.com/bolismauro"><img src="https://avatars.githubusercontent.com/u/771999?v=4&s=48" width="48" height="48" alt="bolismauro" title="bolismauro"/></a> <a href="https://github.com/conhecendoia"><img src="https://avatars.githubusercontent.com/u/82890727?v=4&s=48" width="48" height="48" alt="conhecendoia" title="conhecendoia"/></a> <a href="https://github.com/search?q=Dimitrios%20Ploutarchos"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Dimitrios Ploutarchos" title="Dimitrios Ploutarchos"/></a> <a href="https://github.com/search?q=Drake%20Thomsen"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Drake Thomsen" title="Drake Thomsen"/></a> <a href="https://github.com/search?q=Felix%20Krause"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Felix Krause" title="Felix Krause"/></a> <a href="https://github.com/gtsifrikas"><img src="https://avatars.githubusercontent.com/u/8904378?v=4&s=48" width="48" height="48" alt="gtsifrikas" title="gtsifrikas"/></a> <a href="https://github.com/HazAT"><img src="https://avatars.githubusercontent.com/u/363802?v=4&s=48" width="48" height="48" alt="HazAT" title="HazAT"/></a> <a href="https://github.com/hrdwdmrbl"><img src="https://avatars.githubusercontent.com/u/554881?v=4&s=48" width="48" height="48" alt="hrdwdmrbl" title="hrdwdmrbl"/></a> <a href="https://github.com/hugobarauna"><img src="https://avatars.githubusercontent.com/u/2719?v=4&s=48" width="48" height="48" alt="hugobarauna" title="hugobarauna"/></a>
+  <a href="https://github.com/search?q=Jamie%20Openshaw"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Jamie Openshaw" title="Jamie Openshaw"/></a> <a href="https://github.com/search?q=Jarvis"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Jarvis" title="Jarvis"/></a> <a href="https://github.com/search?q=Jefferson%20Nunn"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Jefferson Nunn" title="Jefferson Nunn"/></a> <a href="https://github.com/search?q=Kevin%20Lin"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Kevin Lin" title="Kevin Lin"/></a> <a href="https://github.com/kitze"><img src="https://avatars.githubusercontent.com/u/1160594?v=4&s=48" width="48" height="48" alt="kitze" title="kitze"/></a> <a href="https://github.com/levifig"><img src="https://avatars.githubusercontent.com/u/1605?v=4&s=48" width="48" height="48" alt="levifig" title="levifig"/></a> <a href="https://github.com/search?q=Lloyd"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Lloyd" title="Lloyd"/></a> <a href="https://github.com/loukotal"><img src="https://avatars.githubusercontent.com/u/18210858?v=4&s=48" width="48" height="48" alt="loukotal" title="loukotal"/></a> <a href="https://github.com/martinpucik"><img src="https://avatars.githubusercontent.com/u/5503097?v=4&s=48" width="48" height="48" alt="martinpucik" title="martinpucik"/></a> <a href="https://github.com/search?q=Matt%20mini"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Matt mini" title="Matt mini"/></a>
+  <a href="https://github.com/search?q=Miles"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Miles" title="Miles"/></a> <a href="https://github.com/mrdbstn"><img src="https://avatars.githubusercontent.com/u/58957632?v=4&s=48" width="48" height="48" alt="mrdbstn" title="mrdbstn"/></a> <a href="https://github.com/MSch"><img src="https://avatars.githubusercontent.com/u/7475?v=4&s=48" width="48" height="48" alt="MSch" title="MSch"/></a> <a href="https://github.com/search?q=Mustafa%20Tag%20Eldeen"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Mustafa Tag Eldeen" title="Mustafa Tag Eldeen"/></a> <a href="https://github.com/ndraiman"><img src="https://avatars.githubusercontent.com/u/12609607?v=4&s=48" width="48" height="48" alt="ndraiman" title="ndraiman"/></a> <a href="https://github.com/nexty5870"><img src="https://avatars.githubusercontent.com/u/3869659?v=4&s=48" width="48" height="48" alt="nexty5870" title="nexty5870"/></a> <a href="https://github.com/odysseus0"><img src="https://avatars.githubusercontent.com/u/8635094?v=4&s=48" width="48" height="48" alt="odysseus0" title="odysseus0"/></a> <a href="https://github.com/prathamdby"><img src="https://avatars.githubusercontent.com/u/134331217?v=4&s=48" width="48" height="48" alt="prathamdby" title="prathamdby"/></a> <a href="https://github.com/ptn1411"><img src="https://avatars.githubusercontent.com/u/57529765?v=4&s=48" width="48" height="48" alt="ptn1411" title="ptn1411"/></a> <a href="https://github.com/reeltimeapps"><img src="https://avatars.githubusercontent.com/u/637338?v=4&s=48" width="48" height="48" alt="reeltimeapps" title="reeltimeapps"/></a>
+  <a href="https://github.com/RLTCmpe"><img src="https://avatars.githubusercontent.com/u/10762242?v=4&s=48" width="48" height="48" alt="RLTCmpe" title="RLTCmpe"/></a> <a href="https://github.com/rodrigouroz"><img src="https://avatars.githubusercontent.com/u/384037?v=4&s=48" width="48" height="48" alt="rodrigouroz" title="rodrigouroz"/></a> <a href="https://github.com/search?q=Rolf%20Fredheim"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Rolf Fredheim" title="Rolf Fredheim"/></a> <a href="https://github.com/search?q=Rony%20Kelner"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Rony Kelner" title="Rony Kelner"/></a> <a href="https://github.com/search?q=Samrat%20Jha"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Samrat Jha" title="Samrat Jha"/></a> <a href="https://github.com/siraht"><img src="https://avatars.githubusercontent.com/u/73152895?v=4&s=48" width="48" height="48" alt="siraht" title="siraht"/></a> <a href="https://github.com/snopoke"><img src="https://avatars.githubusercontent.com/u/249606?v=4&s=48" width="48" height="48" alt="snopoke" title="snopoke"/></a> <a href="https://github.com/testingabc321"><img src="https://avatars.githubusercontent.com/u/8577388?v=4&s=48" width="48" height="48" alt="testingabc321" title="testingabc321"/></a> <a href="https://github.com/search?q=The%20Admiral"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="The Admiral" title="The Admiral"/></a> <a href="https://github.com/thesash"><img src="https://avatars.githubusercontent.com/u/1166151?v=4&s=48" width="48" height="48" alt="thesash" title="thesash"/></a>
+  <a href="https://github.com/search?q=Ubuntu"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Ubuntu" title="Ubuntu"/></a> <a href="https://github.com/voidserf"><img src="https://avatars.githubusercontent.com/u/477673?v=4&s=48" width="48" height="48" alt="voidserf" title="voidserf"/></a> <a href="https://github.com/search?q=Vultr-Clawd%20Admin"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Vultr-Clawd Admin" title="Vultr-Clawd Admin"/></a> <a href="https://github.com/search?q=Wimmie"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Wimmie" title="Wimmie"/></a> <a href="https://github.com/wstock"><img src="https://avatars.githubusercontent.com/u/1394687?v=4&s=48" width="48" height="48" alt="wstock" title="wstock"/></a> <a href="https://github.com/yazinsai"><img src="https://avatars.githubusercontent.com/u/1846034?v=4&s=48" width="48" height="48" alt="yazinsai" title="yazinsai"/></a> <a href="https://github.com/search?q=Zach%20Knickerbocker"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Zach Knickerbocker" title="Zach Knickerbocker"/></a> <a href="https://github.com/Alphonse-arianee"><img src="https://avatars.githubusercontent.com/u/254457365?v=4&s=48" width="48" height="48" alt="Alphonse-arianee" title="Alphonse-arianee"/></a> <a href="https://github.com/search?q=Azade"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Azade" title="Azade"/></a> <a href="https://github.com/carlulsoe"><img src="https://avatars.githubusercontent.com/u/34673973?v=4&s=48" width="48" height="48" alt="carlulsoe" title="carlulsoe"/></a>
+  <a href="https://github.com/search?q=ddyo"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="ddyo" title="ddyo"/></a> <a href="https://github.com/search?q=Erik"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Erik" title="Erik"/></a> <a href="https://github.com/latitudeki5223"><img src="https://avatars.githubusercontent.com/u/119656367?v=4&s=48" width="48" height="48" alt="latitudeki5223" title="latitudeki5223"/></a> <a href="https://github.com/search?q=Manuel%20Maly"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Manuel Maly" title="Manuel Maly"/></a> <a href="https://github.com/search?q=Mourad%20Boustani"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Mourad Boustani" title="Mourad Boustani"/></a> <a href="https://github.com/odrobnik"><img src="https://avatars.githubusercontent.com/u/333270?v=4&s=48" width="48" height="48" alt="odrobnik" title="odrobnik"/></a> <a href="https://github.com/pauloportella"><img src="https://avatars.githubusercontent.com/u/22947229?v=4&s=48" width="48" height="48" alt="pauloportella" title="pauloportella"/></a> <a href="https://github.com/pcty-nextgen-ios-builder"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="pcty-nextgen-ios-builder" title="pcty-nextgen-ios-builder"/></a> <a href="https://github.com/search?q=Quentin"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Quentin" title="Quentin"/></a> <a href="https://github.com/search?q=Randy%20Torres"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Randy Torres" title="Randy Torres"/></a>
+  <a href="https://github.com/rhjoh"><img src="https://avatars.githubusercontent.com/u/105699450?v=4&s=48" width="48" height="48" alt="rhjoh" title="rhjoh"/></a> <a href="https://github.com/ronak-guliani"><img src="https://avatars.githubusercontent.com/u/23518228?v=4&s=48" width="48" height="48" alt="ronak-guliani" title="ronak-guliani"/></a> <a href="https://github.com/search?q=William%20Stock"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="William Stock" title="William Stock"/></a>
 </p>
@@ -121,7 +121,7 @@ Resolution priority:

 ### Delivery (channel + target)
 Isolated jobs can deliver output to a channel. The job payload can specify:
- `channel`: `whatsapp` / `telegram` / `discord` / `slack` / `signal` / `imessage` / `last`
+- `channel`: `whatsapp` / `telegram` / `discord` / `slack` / `mattermost` (plugin) / `signal` / `imessage` / `last`
 - `to`: channel-specific recipient target

 If `channel` or `to` is omitted, cron can fall back to the main session’s “last route”
@@ -133,7 +133,7 @@ Delivery notes:
 - Use `deliver: false` to keep output internal even if a `to` is present.

 Target format reminders:
- Slack/Discord targets should use explicit prefixes (e.g. `channel:<id>`, `user:<id>`) to avoid ambiguity.
+- Slack/Discord/Mattermost (plugin) targets should use explicit prefixes (e.g. `channel:<id>`, `user:<id>`) to avoid ambiguity.
 - Telegram topics should use the `:topic:` form (see below).

 #### Telegram delivery targets (topics / forum threads)
@@ -71,8 +71,8 @@ Payload:
 - `sessionKey` optional (string): The key used to identify the agent's session. Defaults to a random `hook:<uuid>`. Using a consistent key allows for a multi-turn conversation within the hook context.
 - `wakeMode` optional (`now` | `next-heartbeat`): Whether to trigger an immediate heartbeat (default `now`) or wait for the next periodic check.
 - `deliver` optional (boolean): If `true`, the agent's response will be sent to the messaging channel. Defaults to `true`. Responses that are only heartbeat acknowledgments are automatically skipped.
- `channel` optional (string): The messaging channel for delivery. One of: `last`, `whatsapp`, `telegram`, `discord`, `slack`, `signal`, `imessage`, `msteams`. Defaults to `last`.
- `to` optional (string): The recipient identifier for the channel (e.g., phone number for WhatsApp/Signal, chat ID for Telegram, channel ID for Discord/Slack, conversation ID for MS Teams). Defaults to the last recipient in the main session.
+- `channel` optional (string): The messaging channel for delivery. One of: `last`, `whatsapp`, `telegram`, `discord`, `slack`, `mattermost` (plugin), `signal`, `imessage`, `msteams`. Defaults to `last`.
+- `to` optional (string): The recipient identifier for the channel (e.g., phone number for WhatsApp/Signal, chat ID for Telegram, channel ID for Discord/Slack/Mattermost (plugin), conversation ID for MS Teams). Defaults to the last recipient in the main session.
 - `model` optional (string): Model override (e.g., `anthropic/claude-3-5-sonnet` or an alias). Must be in the allowed model list if restricted.
 - `thinking` optional (string): Thinking level override (e.g., `low`, `medium`, `high`).
 - `timeoutSeconds` optional (number): Maximum duration for the agent run in seconds.
@@ -147,7 +147,8 @@ Available actions:
 - **addParticipant**: Add someone to a group (`chatGuid`, `address`)
 - **removeParticipant**: Remove someone from a group (`chatGuid`, `address`)
 - **leaveGroup**: Leave a group chat (`chatGuid`)
- **sendAttachment**: Send media/files (`to`, `buffer`, `filename`)
+- **sendAttachment**: Send media/files (`to`, `buffer`, `filename`, `asVoice`)
+  - Voice memos: set `asVoice: true` with **MP3** or **CAF** audio to send as an iMessage voice message. BlueBubbles converts MP3 → CAF when sending voice memos.

 ### Message IDs (short vs full)
 Clawdbot may surface *short* message IDs (e.g., `1`, `2`) to save tokens.
@@ -15,6 +15,7 @@ Text is supported everywhere; media and reactions vary by channel.
 - [Telegram](/channels/telegram) — Bot API via grammY; supports groups.
 - [Discord](/channels/discord) — Discord Bot API + Gateway; supports servers, channels, and DMs.
 - [Slack](/channels/slack) — Bolt SDK; workspace apps.
+- [Mattermost](/channels/mattermost) — Bot API + WebSocket; channels, groups, DMs (plugin, installed separately).
 - [Signal](/channels/signal) — signal-cli; privacy-focused.
 - [BlueBubbles](/channels/bluebubbles) — **Recommended for iMessage**; uses the BlueBubbles macOS server REST API with full feature support (edit, unsend, effects, reactions, group management — edit currently broken on macOS 26 Tahoe).
 - [iMessage](/channels/imessage) — macOS only; native integration via imsg (legacy, consider BlueBubbles for new setups).
@@ -0,0 +1,123 @@
+---
+summary: "Mattermost bot setup and Clawdbot config"
+read_when:
+  - Setting up Mattermost
+  - Debugging Mattermost routing
+---
+
+# Mattermost (plugin)
+
+Status: supported via plugin (bot token + WebSocket events). Channels, groups, and DMs are supported.
+Mattermost is a self-hostable team messaging platform; see the official site at
+[mattermost.com](https://mattermost.com) for product details and downloads.
+
+## Plugin required
+Mattermost ships as a plugin and is not bundled with the core install.
+
+Install via CLI (npm registry):
+```bash
+clawdbot plugins install @clawdbot/mattermost
+```
+
+Local checkout (when running from a git repo):
+```bash
+clawdbot plugins install ./extensions/mattermost
+```
+
+If you choose Mattermost during configure/onboarding and a git checkout is detected,
+Clawdbot will offer the local install path automatically.
+
+Details: [Plugins](/plugin)
+
+## Quick setup
+1) Install the Mattermost plugin.
+2) Create a Mattermost bot account and copy the **bot token**.
+3) Copy the Mattermost **base URL** (e.g., `https://chat.example.com`).
+4) Configure Clawdbot and start the gateway.
+
+Minimal config:
+```json5
+{
+  channels: {
+    mattermost: {
+      enabled: true,
+      botToken: "mm-token",
+      baseUrl: "https://chat.example.com",
+      dmPolicy: "pairing"
+    }
+  }
+}
+```
+
+## Environment variables (default account)
+Set these on the gateway host if you prefer env vars:
+
+- `MATTERMOST_BOT_TOKEN=...`
+- `MATTERMOST_URL=https://chat.example.com`
+
+Env vars apply only to the **default** account (`default`). Other accounts must use config values.
+
+## Chat modes
+Mattermost responds to DMs automatically. Channel behavior is controlled by `chatmode`:
+
+- `oncall` (default): respond only when @mentioned in channels.
+- `onmessage`: respond to every channel message.
+- `onchar`: respond when a message starts with a trigger prefix.
+
+Config example:
+```json5
+{
+  channels: {
+    mattermost: {
+      chatmode: "onchar",
+      oncharPrefixes: [">", "!"]
+    }
+  }
+}
+```
+
+Notes:
+- `onchar` still responds to explicit @mentions.
+- `channels.mattermost.requireMention` is honored for legacy configs but `chatmode` is preferred.
+
+## Access control (DMs)
+- Default: `channels.mattermost.dmPolicy = "pairing"` (unknown senders get a pairing code).
+- Approve via:
+  - `clawdbot pairing list mattermost`
+  - `clawdbot pairing approve mattermost <CODE>`
+- Public DMs: `channels.mattermost.dmPolicy="open"` plus `channels.mattermost.allowFrom=["*"]`.
+
+## Channels (groups)
+- Default: `channels.mattermost.groupPolicy = "allowlist"` (mention-gated).
+- Allowlist senders with `channels.mattermost.groupAllowFrom` (user IDs or `@username`).
+- Open channels: `channels.mattermost.groupPolicy="open"` (mention-gated).
+
+## Targets for outbound delivery
+Use these target formats with `clawdbot message send` or cron/webhooks:
+
+- `channel:<id>` for a channel
+- `user:<id>` for a DM
+- `@username` for a DM (resolved via the Mattermost API)
+
+Bare IDs are treated as channels.
+
+## Multi-account
+Mattermost supports multiple accounts under `channels.mattermost.accounts`:
+
+```json5
+{
+  channels: {
+    mattermost: {
+      accounts: {
+        default: { name: "Primary", botToken: "mm-token", baseUrl: "https://chat.example.com" },
+        alerts: { name: "Alerts", botToken: "mm-token-2", baseUrl: "https://alerts.example.com" }
+      }
+    }
+  }
+}
+```
+
+## Troubleshooting
+- No replies in channels: ensure the bot is in the channel and mention it (oncall), use a trigger prefix (onchar), or set `chatmode: "onmessage"`.
+- Auth errors: check the bot token, base URL, and whether the account is enabled.
+- Multi-account issues: env vars only apply to the `default` account.
@@ -304,7 +304,8 @@ Slack uses Socket Mode only (no HTTP webhook server). Provide both tokens:
      "policy": "pairing",
      "allowFrom": ["U123", "U456", "*"],
      "groupEnabled": false,
-      "groupChannels": ["G123"]
+      "groupChannels": ["G123"],
+      "replyToMode": "all"
    },
    "channels": {
      "C123": { "allow": true, "requireMention": true },
@@ -361,6 +362,73 @@ By default, Clawdbot replies in the main channel. Use `channels.slack.replyToMod

 The mode applies to both auto-replies and agent tool calls (`slack sendMessage`).

+### Per-chat-type threading
+You can configure different threading behavior per chat type by setting `channels.slack.replyToModeByChatType`:
+
+```json5
+{
+  channels: {
+    slack: {
+      replyToMode: "off",        // default for channels
+      replyToModeByChatType: {
+        direct: "all",           // DMs always thread
+        group: "first"           // group DMs/MPIM thread first reply
+      },
+    }
+  }
+}
+```
+
+Supported chat types:
+- `direct`: 1:1 DMs (Slack `im`)
+- `group`: group DMs / MPIMs (Slack `mpim`)
+- `channel`: standard channels (public/private)
+
+Precedence:
+1) `replyToModeByChatType.<chatType>`
+2) `replyToMode`
+3) Provider default (`off`)
+
+Legacy `channels.slack.dm.replyToMode` is still accepted as a fallback for `direct` when no chat-type override is set.
+
+Examples:
+
+Thread DMs only:
+```json5
+{
+  channels: {
+    slack: {
+      replyToMode: "off",
+      replyToModeByChatType: { direct: "all" }
+    }
+  }
+}
+```
+
+Thread group DMs but keep channels in the root:
+```json5
+{
+  channels: {
+    slack: {
+      replyToMode: "off",
+      replyToModeByChatType: { group: "first" }
+    }
+  }
+}
+```
+
+Make channels thread, keep DMs in the root:
+```json5
+{
+  channels: {
+    slack: {
+      replyToMode: "first",
+      replyToModeByChatType: { direct: "off", group: "off" }
+    }
+  }
+}
+```
+
 ### Manual threading tags
 For fine-grained control, use these tags in agent responses:
 - `[[reply_to_current]]` — reply to the triggering message (start/continue thread).
@@ -1,7 +1,7 @@
 ---
 summary: "CLI reference for `clawdbot channels` (accounts, status, login/logout, logs)"
 read_when:
-  - You want to add/remove channel accounts (WhatsApp/Telegram/Discord/Slack/Signal/iMessage)
+  - You want to add/remove channel accounts (WhatsApp/Telegram/Discord/Slack/Mattermost (plugin)/Signal/iMessage)
  - You want to check channel status or tail channel logs
 ---

@@ -352,7 +352,7 @@ Options:
 ## Channel helpers

 ### `channels`
-Manage chat channel accounts (WhatsApp/Telegram/Discord/Slack/Signal/iMessage/MS Teams).
+Manage chat channel accounts (WhatsApp/Telegram/Discord/Slack/Mattermost (plugin)/Signal/iMessage/MS Teams).

 Subcommands:
 - `channels list`: show configured channels and auth profiles (Claude Code + Codex CLI OAuth sync included).
@@ -365,7 +365,7 @@ Subcommands:
 - `channels logout`: log out of a channel session (if supported).

 Common options:
- `--channel <name>`: `whatsapp|telegram|discord|slack|signal|imessage|msteams`
+- `--channel <name>`: `whatsapp|telegram|discord|slack|mattermost|signal|imessage|msteams`
 - `--account <id>`: channel account id (default `default`)
 - `--name <label>`: display name for the account

@@ -472,7 +472,7 @@ Options:
 - `--session-id <id>`
 - `--thinking <off|minimal|low|medium|high|xhigh>` (GPT-5.2 + Codex models only)
 - `--verbose <on|full|off>`
- `--channel <whatsapp|telegram|discord|slack|signal|imessage>`
+- `--channel <whatsapp|telegram|discord|slack|mattermost|signal|imessage|msteams>`
 - `--local`
 - `--deliver`
 - `--json`
@@ -8,7 +8,7 @@ read_when:
 # `clawdbot message`

 Single outbound command for sending messages and channel actions
-(Discord/Slack/Telegram/WhatsApp/Signal/iMessage/MS Teams).
+(Discord/Slack/Mattermost (plugin)/Telegram/WhatsApp/Signal/iMessage/MS Teams).

 ## Usage

@@ -19,13 +19,14 @@ clawdbot 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: `whatsapp|telegram|discord|slack|signal|imessage|msteams`
+- Values: `whatsapp|telegram|discord|slack|mattermost|signal|imessage|msteams` (Mattermost requires plugin)

 Target formats (`--target`):
 - WhatsApp: E.164 or group JID
 - Telegram: chat id or `@username`
 - Discord: `channel:<id>` or `user:<id>` (or `<@id>` mention; raw numeric ids are treated as channels)
 - 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>`
 - MS Teams: conversation id (`19:...@thread.tacv2`) or `conversation:<id>` or `user:<aad-object-id>`
@@ -49,7 +50,7 @@ Name lookup:
 ### Core

 - `send`
-  - Channels: WhatsApp/Telegram/Discord/Slack/Signal/iMessage/MS Teams
+  - Channels: WhatsApp/Telegram/Discord/Slack/Mattermost (plugin)/Signal/iMessage/MS Teams
  - Required: `--target`, plus `--message` or `--media`
  - Optional: `--media`, `--reply-to`, `--thread-id`, `--gif-playback`
  - Telegram only: `--buttons` (requires `channels.telegram.capabilities.inlineButtons` to allow it)
@@ -109,6 +109,14 @@
      "source": "/opencode/",
      "destination": "/providers/opencode"
    },
+    {
+      "source": "/mattermost",
+      "destination": "/channels/mattermost"
+    },
+    {
+      "source": "/mattermost/",
+      "destination": "/channels/mattermost"
+    },
    {
      "source": "/glm",
      "destination": "/providers/glm"
@@ -165,6 +173,14 @@
      "source": "/providers/location/",
      "destination": "/channels/location"
    },
+    {
+      "source": "/providers/mattermost",
+      "destination": "/channels/mattermost"
+    },
+    {
+      "source": "/providers/mattermost/",
+      "destination": "/channels/mattermost"
+    },
    {
      "source": "/providers/msteams",
      "destination": "/channels/msteams"
@@ -930,6 +946,7 @@
          "channels/grammy",
          "channels/discord",
          "channels/slack",
+          "channels/mattermost",
          "channels/signal",
          "channels/imessage",
          "channels/msteams",
@@ -129,7 +129,7 @@ Save to `~/.clawdbot/clawdbot.json` and you can DM the bot from that number.
        enabled: true,
        maxBytes: 20971520,
        models: [
-          { provider: "openai", model: "whisper-1" },
+          { provider: "openai", model: "gpt-4o-mini-transcribe" },
          // Optional CLI fallback (Whisper binary):
          // { type: "cli", command: "whisper", args: ["--model", "base", "{{MediaPath}}"] }
        ],
@@ -543,7 +543,7 @@ Notes:
 - Outbound commands default to account `default` if present; otherwise the first configured account id (sorted).
 - The legacy single-account Baileys auth dir is migrated by `clawdbot doctor` into `whatsapp/default`.

-### `channels.telegram.accounts` / `channels.discord.accounts` / `channels.slack.accounts` / `channels.signal.accounts` / `channels.imessage.accounts`
+### `channels.telegram.accounts` / `channels.discord.accounts` / `channels.slack.accounts` / `channels.mattermost.accounts` / `channels.signal.accounts` / `channels.imessage.accounts`

 Run multiple accounts per channel (each account has its own `accountId` and optional `name`):

@@ -1204,6 +1204,44 @@ Slack action groups (gate `slack` tool actions):
 | memberInfo | enabled | Member info |
 | emojiList | enabled | Custom emoji list |

+### `channels.mattermost` (bot token)
+
+Mattermost ships as a plugin and is not bundled with the core install.
+Install it first: `clawdbot plugins install @clawdbot/mattermost` (or `./extensions/mattermost` from a git checkout).
+
+Mattermost requires a bot token plus the base URL for your server:
+
+```json5
+{
+  channels: {
+    mattermost: {
+      enabled: true,
+      botToken: "mm-token",
+      baseUrl: "https://chat.example.com",
+      dmPolicy: "pairing",
+      chatmode: "oncall", // oncall | onmessage | onchar
+      oncharPrefixes: [">", "!"],
+      textChunkLimit: 4000
+    }
+  }
+}
+```
+
+Clawdbot starts Mattermost when the account is configured (bot token + base URL) and enabled. The token + base URL are resolved from `channels.mattermost.botToken` + `channels.mattermost.baseUrl` or `MATTERMOST_BOT_TOKEN` + `MATTERMOST_URL` for the default account (unless `channels.mattermost.enabled` is `false`).
+
+Chat modes:
+- `oncall` (default): respond to channel messages only when @mentioned.
+- `onmessage`: respond to every channel message.
+- `onchar`: respond when a message starts with a trigger prefix (`channels.mattermost.oncharPrefixes`, default `[">", "!"]`).
+
+Access control:
+- Default DMs: `channels.mattermost.dmPolicy="pairing"` (unknown senders get a pairing code).
+- Public DMs: `channels.mattermost.dmPolicy="open"` plus `channels.mattermost.allowFrom=["*"]`.
+- Groups: `channels.mattermost.groupPolicy="allowlist"` by default (mention-gated). Use `channels.mattermost.groupAllowFrom` to restrict senders.
+
+Multi-account support lives under `channels.mattermost.accounts` (see the multi-account section above). Env vars only apply to the default account.
+Use `channel:<id>` or `user:<id>` (or `@username`) when specifying delivery targets; bare ids are treated as channel ids.
+
 ### `channels.signal` (signal-cli)

 Signal reactions can emit system events (shared reaction tooling):
@@ -1735,8 +1773,9 @@ Block streaming:
  with `maxChars` capped to the channel text limit. Signal/Slack/Discord default
  to `minChars: 1500` unless overridden.
  Channel overrides: `channels.whatsapp.blockStreamingCoalesce`, `channels.telegram.blockStreamingCoalesce`,
-  `channels.discord.blockStreamingCoalesce`, `channels.slack.blockStreamingCoalesce`, `channels.signal.blockStreamingCoalesce`,
-  `channels.imessage.blockStreamingCoalesce`, `channels.msteams.blockStreamingCoalesce` (and per-account variants).
+  `channels.discord.blockStreamingCoalesce`, `channels.slack.blockStreamingCoalesce`, `channels.mattermost.blockStreamingCoalesce`,
+  `channels.signal.blockStreamingCoalesce`, `channels.imessage.blockStreamingCoalesce`, `channels.msteams.blockStreamingCoalesce`
+  (and per-account variants).
 - `agents.defaults.humanDelay`: randomized pause between **block replies** after the first.
  Modes: `off` (default), `natural` (800–2500ms), `custom` (use `minMs`/`maxMs`).
  Per-agent override: `agents.list[].humanDelay`.
@@ -1826,7 +1865,7 @@ Note: `applyPatch` is only under `tools.exec`.
 - Each `models[]` entry:
  - Provider entry (`type: "provider"` or omitted):
    - `provider`: API provider id (`openai`, `anthropic`, `google`/`gemini`, `groq`, etc).
-    - `model`: model id override (required for image; defaults to `whisper-1`/`whisper-large-v3-turbo` for audio providers, and `gemini-3-flash-preview` for video).
+    - `model`: model id override (required for image; defaults to `gpt-4o-mini-transcribe`/`whisper-large-v3-turbo` for audio providers, and `gemini-3-flash-preview` for video).
    - `profile` / `preferredProfile`: auth profile selection.
  - CLI entry (`type: "cli"`):
    - `command`: executable to run.
@@ -1851,7 +1890,7 @@ Example:
          rules: [{ action: "allow", match: { chatType: "direct" } }]
        },
        models: [
-          { provider: "openai", model: "whisper-1" },
+          { provider: "openai", model: "gpt-4o-mini-transcribe" },
          { type: "cli", command: "whisper", args: ["--model", "base", "{{MediaPath}}"] }
        ]
      },
@@ -51,7 +51,7 @@ You can tune console verbosity independently via:

 ## Tool summary redaction

-Verbose tool summaries (e.g. `🛠️ exec: ...`) can mask sensitive tokens before they hit the
+Verbose tool summaries (e.g. `🛠️ Exec: ...`) can mask sensitive tokens before they hit the
 console stream. This is **tools-only** and does not alter file logs.

 - `logging.redactSensitive`: `off` | `tools` (default: `tools`)
@@ -13,6 +13,7 @@ read_when:

 <p align="center">
  <strong>Any OS + WhatsApp/Telegram/Discord/iMessage gateway for AI agents (Pi).</strong><br />
+  Plugins add Mattermost and more.
  Send a message, get an agent response — from your pocket.
 </p>

@@ -23,7 +24,7 @@ read_when:
  <a href="/start/clawd">Clawdbot assistant setup</a>
 </p>

-Clawdbot bridges WhatsApp (via WhatsApp Web / Baileys), Telegram (Bot API / grammY), Discord (Bot API / channels.discord.js), and iMessage (imsg CLI) to coding agents like [Pi](https://github.com/badlogic/pi-mono).
+Clawdbot bridges WhatsApp (via WhatsApp Web / Baileys), Telegram (Bot API / grammY), Discord (Bot API / channels.discord.js), and iMessage (imsg CLI) to coding agents like [Pi](https://github.com/badlogic/pi-mono). Plugins add Mattermost (Bot API + WebSocket) and more.
 Clawdbot also powers [Clawd](https://clawd.me), the space‑lobster assistant.

 ## Start here
@@ -44,7 +45,7 @@ Remote access: [Web surfaces](/web) and [Tailscale](/gateway/tailscale)
 ## How it works

 ```
-WhatsApp / Telegram / Discord
+WhatsApp / Telegram / Discord / iMessage (+ plugins)
        │
        ▼
  ┌───────────────────────────┐
@@ -79,6 +80,7 @@ Most operations flow through the **Gateway** (`clawdbot gateway`), a single long
 - 📱 **WhatsApp Integration** — Uses Baileys for WhatsApp Web protocol
 - ✈️ **Telegram Bot** — DMs + groups via grammY
 - 🎮 **Discord Bot** — DMs + guild channels via channels.discord.js
+- 🧩 **Mattermost Bot (plugin)** — Bot token + WebSocket events
 - 💬 **iMessage** — Local imsg CLI integration (macOS)
 - 🤖 **Agent bridge** — Pi (RPC mode) with tool streaming
 - ⏱️ **Streaming + chunking** — Block streaming + Telegram draft streaming details ([/concepts/streaming](/concepts/streaming))
@@ -190,6 +192,7 @@ Example:
  - [Control UI (browser)](/web/control-ui)
  - [Telegram](/channels/telegram)
  - [Discord](/channels/discord)
+  - [Mattermost (plugin)](/channels/mattermost)
  - [iMessage](/channels/imessage)
  - [Groups](/concepts/groups)
  - [WhatsApp group messages](/concepts/group-messages)
@@ -6,7 +6,7 @@ read_when:
 # Audio / Voice Notes — 2026-01-17

 ## What works
- **Media understanding (audio)**: If `tools.media.audio` is enabled (or a shared `tools.media.models` entry supports audio), Clawdbot:
+- **Media understanding (audio)**: If audio understanding is enabled (or auto‑detected), Clawdbot:
  1) Locates the first audio attachment (local path or URL) and downloads it if needed.
  2) Enforces `maxBytes` before sending to each model entry.
  3) Runs the first eligible model entry in order (provider or CLI).
@@ -15,6 +15,21 @@ read_when:
 - **Command parsing**: When transcription succeeds, `CommandBody`/`RawBody` are set to the transcript so slash commands still work.
 - **Verbose logging**: In `--verbose`, we log when transcription runs and when it replaces the body.

+## Auto-detection (default)
+If you **don’t configure models** and `tools.media.audio.enabled` is **not** set to `false`,
+Clawdbot auto-detects in this order and stops at the first working option:
+
+1) **Local CLIs** (if installed)
+   - `sherpa-onnx-offline` (requires `SHERPA_ONNX_MODEL_DIR` with encoder/decoder/joiner/tokens)
+   - `whisper-cli` (from `whisper-cpp`; uses `WHISPER_CPP_MODEL` or the bundled tiny model)
+   - `whisper` (Python CLI; downloads models automatically)
+2) **Gemini CLI** (`gemini`) using `read_many_files`
+3) **Provider keys** (OpenAI → Groq → Deepgram → Google)
+
+To disable auto-detection, set `tools.media.audio.enabled: false`.
+To customize, set `tools.media.audio.models`.
+Note: Binary detection is best-effort across macOS/Linux/Windows; ensure the CLI is on `PATH` (we expand `~`), or set an explicit CLI model with a full command path.
+
 ## Config examples

 ### Provider + CLI fallback (OpenAI + Whisper CLI)
@@ -26,7 +41,7 @@ read_when:
        enabled: true,
        maxBytes: 20971520,
        models: [
-          { provider: "openai", model: "whisper-1" },
+          { provider: "openai", model: "gpt-4o-mini-transcribe" },
          {
            type: "cli",
            command: "whisper",
@@ -54,7 +69,7 @@ read_when:
          ]
        },
        models: [
-          { provider: "openai", model: "whisper-1" }
+          { provider: "openai", model: "gpt-4o-mini-transcribe" }
        ]
      }
    }
@@ -83,6 +98,7 @@ read_when:
 - Audio providers can override `baseUrl`, `headers`, and `providerOptions` via `tools.media.audio`.
 - Default size cap is 20MB (`tools.media.audio.maxBytes`). Oversize audio is skipped for that model and the next entry is tried.
 - Default `maxChars` for audio is **unset** (full transcript). Set `tools.media.audio.maxChars` or per-entry `maxChars` to trim output.
+- OpenAI auto default is `gpt-4o-mini-transcribe`; set `model: "gpt-4o-transcribe"` for higher accuracy.
 - Use `tools.media.audio.attachments` to process multiple voice notes (`mode: "all"` + `maxAttachments`).
 - Transcript is available to templates as `{{Transcript}}`.
 - CLI stdout is capped (5MB); keep CLI output concise.
@@ -6,7 +6,7 @@ read_when:
 ---
 # Media Understanding (Inbound) — 2026-01-17

-Clawdbot can optionally **summarize inbound media** (image/audio/video) before the reply pipeline runs. This is **opt-in** and separate from the base attachment flow—if understanding is off, models still receive the original files/URLs as usual.
+Clawdbot can **summarize inbound media** (image/audio/video) before the reply pipeline runs. It auto‑detects when local tools or provider keys are available, and can be disabled or customized. If understanding is off, models still receive the original files/URLs as usual.

 ## Goals
 - Optional: pre‑digest inbound media into short text for faster routing + better command parsing.
@@ -88,6 +88,11 @@ Each `models[]` entry can be **provider** or **CLI**:
 }
 ```

+CLI templates can also use:
+- `{{MediaDir}}` (directory containing the media file)
+- `{{OutputDir}}` (scratch dir created for this run)
+- `{{OutputBase}}` (scratch file base path, no extension)
+
 ## Defaults and limits
 Recommended defaults:
 - `maxChars`: **500** for image/video (short, command‑friendly)
@@ -104,17 +109,22 @@ Rules:
 - If `<capability>.enabled: true` but no models are configured, Clawdbot tries the
  **active reply model** when its provider supports the capability.

-### Auto-enable audio (when keys exist)
-If `tools.media.audio.enabled` is **not** set to `false` and you have any supported
-audio provider keys configured, Clawdbot will **auto-enable audio transcription**
-even when you haven’t listed models explicitly.
+### Auto-detect media understanding (default)
+If `tools.media.<capability>.enabled` is **not** set to `false` and you haven’t
+configured models, Clawdbot auto-detects in this order and **stops at the first
+working option**:

-Providers checked (in order):
-1) OpenAI
-2) Groq
-3) Deepgram
+1) **Local CLIs** (audio only; if installed)
+   - `sherpa-onnx-offline` (requires `SHERPA_ONNX_MODEL_DIR` with encoder/decoder/joiner/tokens)
+   - `whisper-cli` (`whisper-cpp`; uses `WHISPER_CPP_MODEL` or the bundled tiny model)
+   - `whisper` (Python CLI; downloads models automatically)
+2) **Gemini CLI** (`gemini`) using `read_many_files`
+3) **Provider keys**
+   - Audio: OpenAI → Groq → Deepgram → Google
+   - Image: OpenAI → Anthropic → Google → MiniMax
+   - Video: Google

-To disable this behavior, set:
+To disable auto-detection, set:
 ```json5
 {
  tools: {
@@ -126,6 +136,7 @@ To disable this behavior, set:
  }
 }
 ```
+Note: Binary detection is best-effort across macOS/Linux/Windows; ensure the CLI is on `PATH` (we expand `~`), or set an explicit CLI model with a full command path.

 ## Capabilities (optional)
 If you set `capabilities`, the entry only runs for those media types. For shared
@@ -142,7 +153,7 @@ If you omit `capabilities`, the entry is eligible for the list it appears in.
 | Capability | Provider integration | Notes |
 |------------|----------------------|-------|
 | Image | OpenAI / Anthropic / Google / others via `pi-ai` | Any image-capable model in the registry works. |
-| Audio | OpenAI, Groq, Deepgram | Provider transcription (Whisper/Deepgram). |
+| Audio | OpenAI, Groq, Deepgram, Google | Provider transcription (Whisper/Deepgram/Gemini). |
 | Video | Google (Gemini API) | Provider video understanding. |

 ## Recommended providers
@@ -151,8 +162,8 @@ If you omit `capabilities`, the entry is eligible for the list it appears in.
 - Good defaults: `openai/gpt-5.2`, `anthropic/claude-opus-4-5`, `google/gemini-3-pro-preview`.

 **Audio**
- `openai/whisper-1`, `groq/whisper-large-v3-turbo`, or `deepgram/nova-3`.
- CLI fallback: `whisper` binary.
+- `openai/gpt-4o-mini-transcribe`, `groq/whisper-large-v3-turbo`, or `deepgram/nova-3`.
+- CLI fallback: `whisper-cli` (whisper-cpp) or `whisper`.
 - Deepgram setup: [Deepgram (audio transcription)](/providers/deepgram).

 **Video**
@@ -209,7 +220,7 @@ When `mode: "all"`, outputs are labeled `[Image 1/2]`, `[Audio 2/2]`, etc.
      audio: {
        enabled: true,
        models: [
-          { provider: "openai", model: "whisper-1" },
+          { provider: "openai", model: "gpt-4o-mini-transcribe" },
          {
            type: "cli",
            command: "whisper",
@@ -61,6 +61,7 @@ Plugins can register:
 - CLI commands
 - Background services
 - Optional config validation
+- **Skills** (by listing `skills` directories in the plugin manifest)

 Plugins run **in‑process** with the Gateway, so treat them as trusted code.
 Tool authoring guide: [Plugin agent tools](/plugins/agent-tools).
@@ -34,6 +34,7 @@ Optional keys:
 - `kind` (string): plugin kind (example: `"memory"`).
 - `channels` (array): channel ids registered by this plugin (example: `["matrix"]`).
 - `providers` (array): provider ids registered by this plugin.
+- `skills` (array): skill directories to load (relative to the plugin root).
 - `name` (string): display name for the plugin.
 - `description` (string): short plugin summary.
 - `uiHints` (object): config field labels/placeholders/sensitive flags for UI rendering.
@@ -0,0 +1,131 @@
+---
+summary: "OpenProse: .prose workflows, slash commands, and state in Clawdbot"
+read_when:
+  - You want to run or write .prose workflows
+  - You want to enable the OpenProse plugin
+  - You need to understand state storage
+---
+# OpenProse
+
+OpenProse is a portable, markdown-first workflow format for orchestrating AI sessions. In Clawdbot it ships as a plugin that installs an OpenProse skill pack plus a `/prose` slash command. Programs live in `.prose` files and can spawn multiple sub-agents with explicit control flow.
+
+Official site: https://www.prose.md
+
+## What it can do
+
+- Multi-agent research + synthesis with explicit parallelism.
+- Repeatable approval-safe workflows (code review, incident triage, content pipelines).
+- Reusable `.prose` programs you can run across supported agent runtimes.
+
+## Install + enable
+
+Bundled plugins are disabled by default. Enable OpenProse:
+
+```bash
+clawdbot plugins enable open-prose
+```
+
+Restart the Gateway after enabling the plugin.
+
+Dev/local checkout: `clawdbot plugins install ./extensions/open-prose`
+
+Related docs: [Plugins](/plugin), [Plugin manifest](/plugins/manifest), [Skills](/tools/skills).
+
+## Slash command
+
+OpenProse registers `/prose` as a user-invocable skill command. It routes to the OpenProse VM instructions and uses Clawdbot tools under the hood.
+
+Common commands:
+
+```
+/prose help
+/prose run <file.prose>
+/prose run <handle/slug>
+/prose run <https://example.com/file.prose>
+/prose compile <file.prose>
+/prose examples
+/prose update
+```
+
+## Example: a simple `.prose` file
+
+```prose
+# Research + synthesis with two agents running in parallel.
+
+input topic: "What should we research?"
+
+agent researcher:
+  model: sonnet
+  prompt: "You research thoroughly and cite sources."
+
+agent writer:
+  model: opus
+  prompt: "You write a concise summary."
+
+parallel:
+  findings = session: researcher
+    prompt: "Research {topic}."
+  draft = session: writer
+    prompt: "Summarize {topic}."
+
+session "Merge the findings + draft into a final answer."
+context: { findings, draft }
+```
+
+## File locations
+
+OpenProse keeps state under `.prose/` in your workspace:
+
+```
+.prose/
+├── .env
+├── runs/
+│   └── {YYYYMMDD}-{HHMMSS}-{random}/
+│       ├── program.prose
+│       ├── state.md
+│       ├── bindings/
+│       └── agents/
+└── agents/
+```
+
+User-level persistent agents live at:
+
+```
+~/.prose/agents/
+```
+
+## State modes
+
+OpenProse supports multiple state backends:
+
+- **filesystem** (default): `.prose/runs/...`
+- **in-context**: transient, for small programs
+- **sqlite** (experimental): requires `sqlite3` binary
+- **postgres** (experimental): requires `psql` and a connection string
+
+Notes:
+- sqlite/postgres are opt-in and experimental.
+- postgres credentials flow into subagent logs; use a dedicated, least-privileged DB.
+
+## Remote programs
+
+`/prose run <handle/slug>` resolves to `https://p.prose.md/<handle>/<slug>`.
+Direct URLs are fetched as-is. This uses the `web_fetch` tool (or `exec` for POST).
+
+## Clawdbot runtime mapping
+
+OpenProse programs map to Clawdbot primitives:
+
+| OpenProse concept | Clawdbot tool |
+| --- | --- |
+| Spawn session / Task tool | `sessions_spawn` |
+| File read/write | `read` / `write` |
+| Web fetch | `web_fetch` |
+
+If your tool allowlist blocks these tools, OpenProse programs will fail. See [Skills config](/tools/skills-config).
+
+## Security + approvals
+
+Treat `.prose` files like code. Review before running. Use Clawdbot tool allowlists and approval gates to control side effects.
+
+For deterministic, approval-gated workflows, compare with [Lobster](/tools/lobster).
@@ -16,9 +16,9 @@ provider in two different ways.

 ### 1) Built-in GitHub Copilot provider (`github-copilot`)

-Use the native device-login flow to obtain a GitHub token, then exchange it for
-Copilot API tokens when Clawdbot runs. This is the **default** and simplest path
-because it does not require VS Code.
+Use the native device-login flow to obtain a GitHub token and use it directly
+against the Copilot API. This is the **default** and simplest path because it
+does not require VS Code. Enterprise domains are supported.

 ### 2) Copilot Proxy plugin (`copilot-proxy`)

@@ -39,6 +39,8 @@ clawdbot models auth login-github-copilot

 You'll be prompted to visit a URL and enter a one-time code. Keep the terminal
 open until it completes.
+If you're on GitHub Enterprise, the login will ask for your enterprise URL or
+domain (for example `company.ghe.com`).

 ### Optional flags

@@ -66,5 +68,7 @@ clawdbot models set github-copilot/gpt-4o
 - Requires an interactive TTY; run it directly in a terminal.
 - Copilot model availability depends on your plan; if a model is rejected, try
  another ID (for example `github-copilot/gpt-4.1`).
- The login stores a GitHub token in the auth profile store and exchanges it for a
-  Copilot API token when Clawdbot runs.
+- The login stores a GitHub token in the auth profile store and uses it directly
+  for Copilot API calls.
+- Base URL: `https://api.githubcopilot.com` (public) or `https://copilot-api.<domain>`
+  for GitHub Enterprise.
@@ -9,7 +9,7 @@ read_when:
 Clawdbot can use many LLM providers. Pick a provider, authenticate, then set the
 default model as `provider/model`.

-Looking for chat channel docs (WhatsApp/Telegram/Discord/Slack/etc.)? See [Channels](/channels).
+Looking for chat channel docs (WhatsApp/Telegram/Discord/Slack/Mattermost (plugin)/etc.)? See [Channels](/channels).

 ## Quick start

@@ -12,6 +12,7 @@ This document explains how Clawdbot manages sessions end-to-end:
 - **Session routing** (how inbound messages map to a `sessionKey`)
 - **Session store** (`sessions.json`) and what it tracks
 - **Transcript persistence** (`*.jsonl`) and its structure
+- **Transcript hygiene** (provider-specific fixups before runs)
 - **Context limits** (context window vs tracked tokens)
 - **Compaction** (manual + auto-compaction) and where to hook pre-compaction work
 - **Silent housekeeping** (e.g. memory writes that shouldn’t produce user-visible output)
@@ -20,6 +21,7 @@ If you want a higher-level overview first, start with:
 - [/concepts/session](/concepts/session)
 - [/concepts/compaction](/concepts/compaction)
 - [/concepts/session-pruning](/concepts/session-pruning)
+- [/reference/transcript-hygiene](/reference/transcript-hygiene)

 ---

@@ -0,0 +1,94 @@
+---
+summary: "Reference: provider-specific transcript sanitization and repair rules"
+read_when:
+  - You are debugging provider request rejections tied to transcript shape
+  - You are changing transcript sanitization or tool-call repair logic
+  - You are investigating tool-call id mismatches across providers
+---
+# Transcript Hygiene (Provider Fixups)
+
+This document describes **provider-specific fixes** applied to transcripts before a run
+(building model context). These are **in-memory** adjustments used to satisfy strict
+provider requirements. They do **not** rewrite the stored JSONL transcript on disk.
+
+Scope includes:
+- Tool call id sanitization
+- Tool result pairing repair
+- Turn validation / ordering
+- Thought signature cleanup
+- Image payload sanitization
+
+If you need transcript storage details, see:
+- [/reference/session-management-compaction](/reference/session-management-compaction)
+
+---
+
+## Where this runs
+
+All transcript hygiene is centralized in the embedded runner:
+- Policy selection: `src/agents/transcript-policy.ts`
+- Sanitization/repair application: `sanitizeSessionHistory` in `src/agents/pi-embedded-runner/google.ts`
+
+The policy uses `provider`, `modelApi`, and `modelId` to decide what to apply.
+
+---
+
+## Global rule: image sanitization
+
+Image payloads are always sanitized to prevent provider-side rejection due to size
+limits (downscale/recompress oversized base64 images).
+
+Implementation:
+- `sanitizeSessionMessagesImages` in `src/agents/pi-embedded-helpers/images.ts`
+- `sanitizeContentBlocksImages` in `src/agents/tool-images.ts`
+
+---
+
+## Provider matrix (current behavior)
+
+**OpenAI / OpenAI Codex**
+- Image sanitization only.
+- No tool call id sanitization.
+- No tool result pairing repair.
+- No turn validation or reordering.
+- No synthetic tool results.
+- No thought signature stripping.
+
+**Google (Generative AI / Gemini CLI / Antigravity)**
+- Tool call id sanitization: strict alphanumeric.
+- Tool result pairing repair and synthetic tool results.
+- Turn validation (Gemini-style turn alternation).
+- Google turn ordering fixup (prepend a tiny user bootstrap if history starts with assistant).
+- Antigravity Claude: normalize thinking signatures; drop unsigned thinking blocks.
+
+**Anthropic / Minimax (Anthropic-compatible)**
+- Tool result pairing repair and synthetic tool results.
+- Turn validation (merge consecutive user turns to satisfy strict alternation).
+
+**Mistral (including model-id based detection)**
+- Tool call id sanitization: strict9 (alphanumeric length 9).
+
+**OpenRouter Gemini**
+- Thought signature cleanup: strip non-base64 `thought_signature` values (keep base64).
+
+**Everything else**
+- Image sanitization only.
+
+---
+
+## Historical behavior (pre-2026.1.22)
+
+Before the 2026.1.22 release, Clawdbot applied multiple layers of transcript hygiene:
+
+- A **transcript-sanitize extension** ran on every context build and could:
+  - Repair tool use/result pairing.
+  - Sanitize tool call ids (including a non-strict mode that preserved `_`/`-`).
+- The runner also performed provider-specific sanitization, which duplicated work.
+- Additional mutations occurred outside the provider policy, including:
+  - Stripping `<final>` tags from assistant text before persistence.
+  - Dropping empty assistant error turns.
+  - Trimming assistant content after tool calls.
+
+This complexity caused cross-provider regressions (notably `openai-responses`
+`call_id|fc_id` pairing). The 2026.1.22 cleanup removed the extension, centralized
+logic in the runner, and made OpenAI **no-touch** beyond image sanitization.
@@ -6,14 +6,14 @@ read_when:
 ---
 # Building a personal assistant with Clawdbot (Clawd-style)

-Clawdbot is a WhatsApp + Telegram + Discord gateway for **Pi** agents. This guide is the “personal assistant” setup: one dedicated WhatsApp number that behaves like your always-on agent.
+Clawdbot is a WhatsApp + Telegram + Discord + iMessage gateway for **Pi** agents. Plugins add Mattermost. This guide is the "personal assistant" setup: one dedicated WhatsApp number that behaves like your always-on agent.

 ## ⚠️ Safety first

 You’re putting an agent in a position to:
 - run commands on your machine (depending on your Pi tool setup)
 - read/write files in your workspace
- send messages back out via WhatsApp/Telegram/Discord
+- send messages back out via WhatsApp/Telegram/Discord/Mattermost (plugin)

 Start conservative:
 - Always set `channels.whatsapp.allowFrom` (never run open-to-the-world on your personal Mac).
@@ -178,7 +178,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,

 ### What is Clawdbot, in one paragraph?

-Clawdbot is a personal AI assistant you run on your own devices. It replies on the messaging surfaces you already use (WhatsApp, Telegram, Slack, Discord, Signal, iMessage, WebChat) and can also do voice + a live Canvas on supported platforms. The **Gateway** is the always‑on control plane; the assistant is the product.
+Clawdbot is a personal AI assistant you run on your own devices. It replies on the messaging surfaces you already use (WhatsApp, Telegram, Slack, Mattermost (plugin), Discord, Signal, iMessage, WebChat) and can also do voice + a live Canvas on supported platforms. The **Gateway** is the always-on control plane; the assistant is the product.

 ## Quick start and first-run setup

@@ -235,7 +235,7 @@ Node **>= 22** is required. `pnpm` is recommended. Bun is **not recommended** fo
 - **Model/auth setup** (Anthropic **setup-token** recommended for Claude subscriptions, OpenAI Codex OAuth supported, API keys optional, LM Studio local models supported)
 - **Workspace** location + bootstrap files
 - **Gateway settings** (bind/port/auth/tailscale)
- **Providers** (WhatsApp, Telegram, Discord, Signal, iMessage)
+- **Providers** (WhatsApp, Telegram, Discord, Mattermost (plugin), Signal, iMessage)
 - **Daemon install** (LaunchAgent on macOS; systemd user unit on Linux/WSL2)
 - **Health checks** and **skills** selection

@@ -363,7 +363,7 @@ lowest friction and you’re okay with sleep/restarts, run it locally.
 - **Pros:** always‑on, stable network, no laptop sleep issues, easier to keep running.
 - **Cons:** often run headless (use screenshots), remote file access only, you must SSH for updates.

-**Clawdbot‑specific note:** WhatsApp/Telegram/Slack/Discord all work fine from a VPS. The only real trade‑off is **headless browser** vs a visible window. See [Browser](/tools/browser).
+**Clawdbot-specific note:** WhatsApp/Telegram/Slack/Mattermost (plugin)/Discord all work fine from a VPS. The only real trade-off is **headless browser** vs a visible window. See [Browser](/tools/browser).

 **Recommended default:** VPS if you had gateway disconnects before. Local is great when you’re actively using the Mac and want local file access or UI automation with a visible browser.

@@ -12,7 +12,7 @@ Goal: go from **zero** → **first working chat** (with sane defaults) as quickl
 Recommended path: use the **CLI onboarding wizard** (`clawdbot onboard`). It sets up:
 - model/auth (OAuth recommended)
 - gateway settings
- channels (WhatsApp/Telegram/Discord/…)
+- channels (WhatsApp/Telegram/Discord/Mattermost (plugin)/...)
 - pairing defaults (secure DMs)
 - workspace bootstrap + skills
 - optional background service
@@ -80,7 +80,7 @@ clawdbot onboard --install-daemon
 What you’ll choose:
 - **Local vs Remote** gateway
 - **Auth**: OpenAI Code (Codex) subscription (OAuth) or API keys. For Anthropic we recommend an API key; `claude setup-token` is also supported.
- **Providers**: WhatsApp QR login, Telegram/Discord bot tokens, etc.
+- **Providers**: WhatsApp QR login, Telegram/Discord bot tokens, Mattermost plugin tokens, etc.
 - **Daemon**: background install (launchd/systemd; WSL2 uses systemd)
  - **Runtime**: Node (recommended; required for WhatsApp/Telegram). Bun is **not recommended**.
 - **Gateway token**: the wizard generates one by default (even on loopback) and stores it in `gateway.auth.token`.
@@ -140,6 +140,7 @@ WhatsApp doc: [WhatsApp](/channels/whatsapp)
 The wizard can write tokens/config for you. If you prefer manual config, start with:
 - Telegram: [Telegram](/channels/telegram)
 - Discord: [Discord](/channels/discord)
+- Mattermost (plugin): [Mattermost](/channels/mattermost)

 **Telegram DM tip:** your first DM returns a pairing code. Approve it (see next step) or the bot won’t respond.

@@ -67,6 +67,7 @@ Use these hubs to discover every page, including deep dives and reference docs t
 - [Telegram (grammY notes)](/channels/grammy)
 - [Slack](/channels/slack)
 - [Discord](/channels/discord)
+- [Mattermost](/channels/mattermost) (plugin)
 - [Signal](/channels/signal)
 - [iMessage](/channels/imessage)
 - [Location parsing](/channels/location)
@@ -96,6 +97,7 @@ Use these hubs to discover every page, including deep dives and reference docs t
 ## Tools + automation

 - [Tools surface](/tools)
+- [OpenProse](/prose)
 - [CLI reference](/cli)
 - [Exec tool](/tools/exec)
 - [Elevated mode](/tools/elevated)
@@ -48,7 +48,7 @@ The wizard starts with **QuickStart** (defaults) vs **Advanced** (full control).
  - Model/auth (OpenAI Code (Codex) subscription OAuth, Anthropic API key (recommended) or setup-token (paste), plus MiniMax/GLM/Moonshot/AI Gateway options)
 - Workspace location + bootstrap files
 - Gateway settings (port/bind/auth/tailscale)
- Providers (Telegram, WhatsApp, Discord, Signal)
+- Providers (Telegram, WhatsApp, Discord, Mattermost (plugin), Signal)
 - Daemon install (LaunchAgent / systemd user unit)
 - Health check
 - Skills (recommended)
@@ -117,6 +117,7 @@ Tip: `--json` does **not** imply non-interactive mode. Use `--non-interactive` (
   - WhatsApp: optional QR login.
   - Telegram: bot token.
   - Discord: bot token.
+   - Mattermost (plugin): bot token + base URL.
   - Signal: optional `signal-cli` install + account config.
   - iMessage: local `imsg` CLI path + DB access.
  - DM security: default is pairing. First DM sends a code; approve via `clawdbot pairing approve <channel> <code>` or use allowlists.
@@ -11,6 +11,10 @@ read_when:

 Lobster is a workflow shell that lets Clawdbot run multi-step tool sequences as a single, deterministic operation with explicit approval checkpoints.

+## Hook
+
+Your assistant can build the tools that manage itself. Ask for a workflow, and 30 minutes later you have a CLI plus pipelines that run as one call. Lobster is the missing piece: deterministic pipelines, explicit approvals, and resumable state.
+
 ## Why

 Today, complex workflows require many back-and-forth tool calls. Each call costs tokens, and the LLM has to orchestrate every step. Lobster moves that orchestration into a typed runtime:
@@ -24,6 +28,73 @@ Today, complex workflows require many back-and-forth tool calls. Each call costs
 Clawdbot launches the local `lobster` CLI in **tool mode** and parses a JSON envelope from stdout.
 If the pipeline pauses for approval, the tool returns a `resumeToken` so you can continue later.

+## Pattern: small CLI + JSON pipes + approvals
+
+Build tiny commands that speak JSON, then chain them into a single Lobster call. (Example command names below — swap in your own.)
+
+```bash
+inbox list --json
+inbox categorize --json
+inbox apply --json
+```
+
+```json
+{
+  "action": "run",
+  "pipeline": "exec --json --shell 'inbox list --json' | exec --stdin json --shell 'inbox categorize --json' | exec --stdin json --shell 'inbox apply --json' | approve --preview-from-stdin --limit 5 --prompt 'Apply changes?'",
+  "timeoutMs": 30000
+}
+```
+
+If the pipeline requests approval, resume with the token:
+
+```json
+{
+  "action": "resume",
+  "token": "<resumeToken>",
+  "approve": true
+}
+```
+
+AI triggers the workflow; Lobster executes the steps. Approval gates keep side effects explicit and auditable.
+
+Example: map input items into tool calls:
+
+```bash
+gog.gmail.search --query 'newer_than:1d' \
+  | clawd.invoke --tool message --action send --each --item-key message --args-json '{"provider":"telegram","to":"..."}'
+```
+
+## Workflow files (.lobster)
+
+Lobster can run YAML/JSON workflow files with `name`, `args`, `steps`, `env`, `condition`, and `approval` fields. In Clawdbot tool calls, set `pipeline` to the file path.
+
+```yaml
+name: inbox-triage
+args:
+  tag:
+    default: "family"
+steps:
+  - id: collect
+    command: inbox list --json
+  - id: categorize
+    command: inbox categorize --json
+    stdin: $collect.stdout
+  - id: approve
+    command: inbox apply --approve
+    stdin: $categorize.stdout
+    approval: required
+  - id: execute
+    command: inbox apply --execute
+    stdin: $categorize.stdout
+    condition: $approve.approved
+```
+
+Notes:
+
+- `stdin: $step.stdout` and `stdin: $step.json` pass a prior step’s output.
+- `condition` (or `when`) can gate steps on `$step.approved`.
+
 ## Install Lobster

 Install the Lobster CLI on the **same host** that runs the Clawdbot Gateway (see the [Lobster repo](https://github.com/clawdbot/lobster)), and ensure `lobster` is on `PATH`.
@@ -115,6 +186,16 @@ Run a pipeline in tool mode.
 }
 ```

+Run a workflow file with args:
+
+```json
+{
+  "action": "run",
+  "pipeline": "/path/to/inbox-triage.lobster",
+  "argsJson": "{\"tag\":\"family\"}"
+}
+```
+
 ### `resume`

 Continue a halted workflow after approval.
@@ -133,6 +214,7 @@ Continue a halted workflow after approval.
 - `cwd`: Working directory for the pipeline (defaults to the current process working directory).
 - `timeoutMs`: Kill the subprocess if it exceeds this duration (default: 20000).
 - `maxStdoutBytes`: Kill the subprocess if stdout exceeds this size (default: 512000).
+- `argsJson`: JSON string passed to `lobster run --args-json` (workflow files only).

 ## Output envelope

@@ -151,6 +233,12 @@ If `requiresApproval` is present, inspect the prompt and decide:
 - `approve: true` → resume and continue side effects
 - `approve: false` → cancel and finalize the workflow

+Use `approve --preview-from-stdin --limit N` to attach a JSON preview to approval requests without custom jq/heredoc glue. Resume tokens are now compact: Lobster stores workflow resume state under its state dir and hands back a small token key.
+
+## OpenProse
+
+OpenProse pairs well with Lobster: use `/prose` to orchestrate multi-agent prep, then run a Lobster pipeline for deterministic approvals. If a Prose program needs Lobster, allow the `lobster` tool for sub-agents via `tools.subagents.tools`. See [OpenProse](/prose).
+
 ## Safety

 - **Local subprocess only** — no network calls from the plugin itself.
@@ -169,3 +257,10 @@ If `requiresApproval` is present, inspect the prompt and decide:

 - [Plugins](/plugin)
 - [Plugin tool authoring](/plugins/agent-tools)
+
+## Case study: community workflows
+
+One public example: a “second brain” CLI + Lobster pipelines that manage three Markdown vaults (personal, partner, shared). The CLI emits JSON for stats, inbox listings, and stale scans; Lobster chains those commands into workflows like `weekly-review`, `inbox-triage`, `memory-consolidation`, and `shared-task-sync`, each with approval gates. AI handles judgment (categorization) when available and falls back to deterministic rules when not.
+
+- Thread: https://x.com/plattenschieber/status/2014508656335770033
+- Repo: https://github.com/bloomedai/brain-cli
@@ -38,10 +38,12 @@ applies: workspace wins, then managed/local, then bundled.

 ## Plugins + skills

-Plugins can ship their own skills (for example, `voice-call`) and gate them via
-`metadata.clawdbot.requires.config` on the plugin’s config entry. See
-[Plugins](/plugin) for plugin discovery/config and [Tools](/tools) for the tool
-surface those skills teach.
+Plugins can ship their own skills by listing `skills` directories in
+`clawdbot.plugin.json` (paths relative to the plugin root). Plugin skills load
+when the plugin is enabled and participate in the normal skill precedence rules.
+You can gate them via `metadata.clawdbot.requires.config` on the plugin’s config
+entry. See [Plugins](/plugin) for discovery/config and [Tools](/tools) for the
+tool surface those skills teach.

 ## ClawdHub (install + sync)

@@ -109,6 +109,7 @@ Notes:
  - `/skill <name> [input]` runs a skill by name (useful when native command limits prevent per-skill commands).
  - By default, skill commands are forwarded to the model as a normal request.
  - Skills may optionally declare `command-dispatch: tool` to route the command directly to a tool (deterministic, no model).
+  - Example: `/prose` (OpenProse plugin) — see [OpenProse](/prose).
 - **Native command arguments:** Discord uses autocomplete for dynamic options (and button menus when you omit required args). Telegram and Slack show a button menu when a command supports choices and you omit the arg.

 ## Usage surfaces (what shows where)
@@ -30,7 +30,7 @@ The onboarding wizard generates a gateway token by default, so paste it here on
 ## What it can do (today)
 - Chat with the model via Gateway WS (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`)
 - Stream tool calls + live tool output cards in Chat (agent events)
- Channels: WhatsApp/Telegram status + QR login + per-channel config (`channels.status`, `web.login.*`, `config.patch`)
+- Channels: WhatsApp/Telegram/Discord/Slack + plugin channels (Mattermost, etc.) status + QR login + per-channel config (`channels.status`, `web.login.*`, `config.patch`)
 - Instances: presence list + refresh (`system-presence`)
 - Sessions: list + per-session thinking/verbose overrides (`sessions.list`, `sessions.patch`)
 - Cron jobs: list/add/run/enable/disable + run history (`cron.*`)
@@ -521,6 +521,42 @@ describe("bluebubblesMessageActions", () => {
      });
    });

+    it("passes asVoice through sendAttachment", async () => {
+      const { sendBlueBubblesAttachment } = await import("./attachments.js");
+
+      const cfg: ClawdbotConfig = {
+        channels: {
+          bluebubbles: {
+            serverUrl: "http://localhost:1234",
+            password: "test-password",
+          },
+        },
+      };
+
+      const base64Buffer = Buffer.from("voice").toString("base64");
+
+      await bluebubblesMessageActions.handleAction({
+        action: "sendAttachment",
+        params: {
+          to: "+15551234567",
+          filename: "voice.mp3",
+          buffer: base64Buffer,
+          contentType: "audio/mpeg",
+          asVoice: true,
+        },
+        cfg,
+        accountId: null,
+      });
+
+      expect(sendBlueBubblesAttachment).toHaveBeenCalledWith(
+        expect.objectContaining({
+          filename: "voice.mp3",
+          contentType: "audio/mpeg",
+          asVoice: true,
+        }),
+      );
+    });
+
    it("throws when buffer is missing for setGroupIcon", async () => {
      const cfg: ClawdbotConfig = {
        channels: {
@@ -3,7 +3,6 @@ import {
  BLUEBUBBLES_ACTIONS,
  createActionGate,
  jsonResult,
-  readBooleanParam,
  readNumberParam,
  readReactionParams,
  readStringParam,
@@ -51,6 +50,17 @@ function readMessageText(params: Record<string, unknown>): string | undefined {
  return readStringParam(params, "text") ?? readStringParam(params, "message");
 }

+function readBooleanParam(params: Record<string, unknown>, key: string): boolean | undefined {
+  const raw = params[key];
+  if (typeof raw === "boolean") return raw;
+  if (typeof raw === "string") {
+    const trimmed = raw.trim().toLowerCase();
+    if (trimmed === "true") return true;
+    if (trimmed === "false") return false;
+  }
+  return undefined;
+}
+
 /** Supported action names for BlueBubbles */
 const SUPPORTED_ACTIONS = new Set<ChannelMessageActionName>(BLUEBUBBLES_ACTION_NAMES);

@@ -356,6 +366,7 @@ export const bluebubblesMessageActions: ChannelMessageActionAdapter = {
      const caption = readStringParam(params, "caption");
      const contentType =
        readStringParam(params, "contentType") ?? readStringParam(params, "mimeType");
+      const asVoice = readBooleanParam(params, "asVoice");

      // Buffer can come from params.buffer (base64) or params.path (file path)
      const base64Buffer = readStringParam(params, "buffer");
@@ -380,6 +391,7 @@ export const bluebubblesMessageActions: ChannelMessageActionAdapter = {
        filename,
        contentType: contentType ?? undefined,
        caption: caption ?? undefined,
+        asVoice: asVoice ?? undefined,
        opts,
      });

@@ -1,6 +1,6 @@
 import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";

-import { downloadBlueBubblesAttachment } from "./attachments.js";
+import { downloadBlueBubblesAttachment, sendBlueBubblesAttachment } from "./attachments.js";
 import type { BlueBubblesAttachment } from "./types.js";

 vi.mock("./accounts.js", () => ({
@@ -238,3 +238,109 @@ describe("downloadBlueBubblesAttachment", () => {
    expect(result.buffer).toEqual(new Uint8Array([1]));
  });
 });
+
+describe("sendBlueBubblesAttachment", () => {
+  beforeEach(() => {
+    vi.stubGlobal("fetch", mockFetch);
+    mockFetch.mockReset();
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  function decodeBody(body: Uint8Array) {
+    return Buffer.from(body).toString("utf8");
+  }
+
+  it("marks voice memos when asVoice is true and mp3 is provided", async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      text: () => Promise.resolve(JSON.stringify({ messageId: "msg-1" })),
+    });
+
+    await sendBlueBubblesAttachment({
+      to: "chat_guid:iMessage;-;+15551234567",
+      buffer: new Uint8Array([1, 2, 3]),
+      filename: "voice.mp3",
+      contentType: "audio/mpeg",
+      asVoice: true,
+      opts: { serverUrl: "http://localhost:1234", password: "test" },
+    });
+
+    const body = mockFetch.mock.calls[0][1]?.body as Uint8Array;
+    const bodyText = decodeBody(body);
+    expect(bodyText).toContain('name="isAudioMessage"');
+    expect(bodyText).toContain("true");
+    expect(bodyText).toContain('filename="voice.mp3"');
+  });
+
+  it("normalizes mp3 filenames for voice memos", async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      text: () => Promise.resolve(JSON.stringify({ messageId: "msg-2" })),
+    });
+
+    await sendBlueBubblesAttachment({
+      to: "chat_guid:iMessage;-;+15551234567",
+      buffer: new Uint8Array([1, 2, 3]),
+      filename: "voice",
+      contentType: "audio/mpeg",
+      asVoice: true,
+      opts: { serverUrl: "http://localhost:1234", password: "test" },
+    });
+
+    const body = mockFetch.mock.calls[0][1]?.body as Uint8Array;
+    const bodyText = decodeBody(body);
+    expect(bodyText).toContain('filename="voice.mp3"');
+    expect(bodyText).toContain('name="voice.mp3"');
+  });
+
+  it("throws when asVoice is true but media is not audio", async () => {
+    await expect(
+      sendBlueBubblesAttachment({
+        to: "chat_guid:iMessage;-;+15551234567",
+        buffer: new Uint8Array([1, 2, 3]),
+        filename: "image.png",
+        contentType: "image/png",
+        asVoice: true,
+        opts: { serverUrl: "http://localhost:1234", password: "test" },
+      }),
+    ).rejects.toThrow("voice messages require audio");
+    expect(mockFetch).not.toHaveBeenCalled();
+  });
+
+  it("throws when asVoice is true but audio is not mp3 or caf", async () => {
+    await expect(
+      sendBlueBubblesAttachment({
+        to: "chat_guid:iMessage;-;+15551234567",
+        buffer: new Uint8Array([1, 2, 3]),
+        filename: "voice.wav",
+        contentType: "audio/wav",
+        asVoice: true,
+        opts: { serverUrl: "http://localhost:1234", password: "test" },
+      }),
+    ).rejects.toThrow("require mp3 or caf");
+    expect(mockFetch).not.toHaveBeenCalled();
+  });
+
+  it("sanitizes filenames before sending", async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      text: () => Promise.resolve(JSON.stringify({ messageId: "msg-3" })),
+    });
+
+    await sendBlueBubblesAttachment({
+      to: "chat_guid:iMessage;-;+15551234567",
+      buffer: new Uint8Array([1, 2, 3]),
+      filename: "../evil.mp3",
+      contentType: "audio/mpeg",
+      opts: { serverUrl: "http://localhost:1234", password: "test" },
+    });
+
+    const body = mockFetch.mock.calls[0][1]?.body as Uint8Array;
+    const bodyText = decodeBody(body);
+    expect(bodyText).toContain('filename="evil.mp3"');
+    expect(bodyText).toContain('name="evil.mp3"');
+  });
+});
@@ -1,4 +1,5 @@
 import crypto from "node:crypto";
+import path from "node:path";
 import type { ClawdbotConfig } from "clawdbot/plugin-sdk";
 import { resolveBlueBubblesAccount } from "./accounts.js";
 import { resolveChatGuidForTarget } from "./send.js";
@@ -19,6 +20,30 @@ export type BlueBubblesAttachmentOpts = {
 };

 const DEFAULT_ATTACHMENT_MAX_BYTES = 8 * 1024 * 1024;
+const AUDIO_MIME_MP3 = new Set(["audio/mpeg", "audio/mp3"]);
+const AUDIO_MIME_CAF = new Set(["audio/x-caf", "audio/caf"]);
+
+function sanitizeFilename(input: string | undefined, fallback: string): string {
+  const trimmed = input?.trim() ?? "";
+  const base = trimmed ? path.basename(trimmed) : "";
+  return base || fallback;
+}
+
+function ensureExtension(filename: string, extension: string, fallbackBase: string): string {
+  const currentExt = path.extname(filename);
+  if (currentExt.toLowerCase() === extension) return filename;
+  const base = currentExt ? filename.slice(0, -currentExt.length) : filename;
+  return `${base || fallbackBase}${extension}`;
+}
+
+function resolveVoiceInfo(filename: string, contentType?: string) {
+  const normalizedType = contentType?.trim().toLowerCase();
+  const extension = path.extname(filename).toLowerCase();
+  const isMp3 = extension === ".mp3" || (normalizedType ? AUDIO_MIME_MP3.has(normalizedType) : false);
+  const isCaf = extension === ".caf" || (normalizedType ? AUDIO_MIME_CAF.has(normalizedType) : false);
+  const isAudio = isMp3 || isCaf || Boolean(normalizedType?.startsWith("audio/"));
+  return { isAudio, isMp3, isCaf };
+}

 function resolveAccount(params: BlueBubblesAttachmentOpts) {
  const account = resolveBlueBubblesAccount({
@@ -104,6 +129,7 @@ function extractMessageId(payload: unknown): string {
 /**
 * Send an attachment via BlueBubbles API.
 * Supports sending media files (images, videos, audio, documents) to a chat.
+ * When asVoice is true, expects MP3/CAF audio and marks it as an iMessage voice memo.
 */
 export async function sendBlueBubblesAttachment(params: {
  to: string;
@@ -113,12 +139,37 @@ export async function sendBlueBubblesAttachment(params: {
  caption?: string;
  replyToMessageGuid?: string;
  replyToPartIndex?: number;
+  asVoice?: boolean;
  opts?: BlueBubblesAttachmentOpts;
 }): Promise<SendBlueBubblesAttachmentResult> {
-  const { to, buffer, filename, contentType, caption, replyToMessageGuid, replyToPartIndex, opts = {} } =
-    params;
+  const { to, caption, replyToMessageGuid, replyToPartIndex, asVoice, opts = {} } = params;
+  let { buffer, filename, contentType } = params;
+  const wantsVoice = asVoice === true;
+  const fallbackName = wantsVoice ? "Audio Message" : "attachment";
+  filename = sanitizeFilename(filename, fallbackName);
+  contentType = contentType?.trim() || undefined;
  const { baseUrl, password } = resolveAccount(opts);

+  // Validate voice memo format when requested (BlueBubbles converts MP3 -> CAF when isAudioMessage).
+  const isAudioMessage = wantsVoice;
+  if (isAudioMessage) {
+    const voiceInfo = resolveVoiceInfo(filename, contentType);
+    if (!voiceInfo.isAudio) {
+      throw new Error("BlueBubbles voice messages require audio media (mp3 or caf).");
+    }
+    if (voiceInfo.isMp3) {
+      filename = ensureExtension(filename, ".mp3", fallbackName);
+      contentType = contentType ?? "audio/mpeg";
+    } else if (voiceInfo.isCaf) {
+      filename = ensureExtension(filename, ".caf", fallbackName);
+      contentType = contentType ?? "audio/x-caf";
+    } else {
+      throw new Error(
+        "BlueBubbles voice messages require mp3 or caf audio (convert before sending).",
+      );
+    }
+  }
+
  const target = resolveSendTarget(to);
  const chatGuid = await resolveChatGuidForTarget({
    baseUrl,
@@ -170,6 +221,11 @@ export async function sendBlueBubblesAttachment(params: {
  addField("tempGuid", `temp-${Date.now()}-${crypto.randomUUID().slice(0, 8)}`);
  addField("method", "private-api");

+  // Add isAudioMessage flag for voice memos
+  if (isAudioMessage) {
+    addField("isAudioMessage", "true");
+  }
+
  const trimmedReplyTo = replyToMessageGuid?.trim();
  if (trimmedReplyTo) {
    addField("selectedMessageGuid", trimmedReplyTo);
@@ -59,6 +59,7 @@ export async function sendBlueBubblesMedia(params: {
  caption?: string;
  replyToId?: string | null;
  accountId?: string;
+  asVoice?: boolean;
 }) {
  const {
    cfg,
@@ -71,6 +72,7 @@ export async function sendBlueBubblesMedia(params: {
    caption,
    replyToId,
    accountId,
+    asVoice,
  } = params;
  const core = getBlueBubblesRuntime();
  const maxBytes = resolveChannelMediaMaxBytes({
@@ -146,6 +148,7 @@ export async function sendBlueBubblesMedia(params: {
    filename: resolvedFilename ?? "attachment",
    contentType: resolvedContentType ?? undefined,
    replyToMessageGuid,
+    asVoice,
    opts: {
      cfg,
      accountId,
@@ -159,6 +159,7 @@ export function createLobsterTool(api: ClawdbotPluginApi) {
      // NOTE: Prefer string enums in tool schemas; some providers reject unions/anyOf.
      action: Type.Unsafe<"run" | "resume">({ type: "string", enum: ["run", "resume"] }),
      pipeline: Type.Optional(Type.String()),
+      argsJson: Type.Optional(Type.String()),
      token: Type.Optional(Type.String()),
      approve: Type.Optional(Type.Boolean()),
      lobsterPath: Type.Optional(Type.String()),
@@ -181,7 +182,12 @@ export function createLobsterTool(api: ClawdbotPluginApi) {
        if (action === "run") {
          const pipeline = typeof params.pipeline === "string" ? params.pipeline : "";
          if (!pipeline.trim()) throw new Error("pipeline required");
-          return ["run", "--mode", "tool", pipeline];
+          const argv = ["run", "--mode", "tool", pipeline];
+          const argsJson = typeof params.argsJson === "string" ? params.argsJson : "";
+          if (argsJson.trim()) {
+            argv.push("--args-json", argsJson);
+          }
+          return argv;
        }
        if (action === "resume") {
          const token = typeof params.token === "string" ? params.token : "";
@@ -53,7 +53,7 @@ export async function resolveMatrixAuth(params?: {
    saveMatrixCredentials,
    credentialsMatchConfig,
    touchMatrixCredentials,
-  } = await import("./credentials.js");
+  } = await import("../credentials.js");

  const cached = loadMatrixCredentials(env);
  const cachedCredentials =
@@ -0,0 +1,102 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import type { MatrixClient } from "matrix-bot-sdk";
+import { EventType } from "./types.js";
+
+let resolveMatrixRoomId: typeof import("./targets.js").resolveMatrixRoomId;
+let normalizeThreadId: typeof import("./targets.js").normalizeThreadId;
+
+beforeEach(async () => {
+  vi.resetModules();
+  ({ resolveMatrixRoomId, normalizeThreadId } = await import("./targets.js"));
+});
+
+describe("resolveMatrixRoomId", () => {
+  it("uses m.direct when available", async () => {
+    const userId = "@user:example.org";
+    const client = {
+      getAccountData: vi.fn().mockResolvedValue({
+        [userId]: ["!room:example.org"],
+      }),
+      getJoinedRooms: vi.fn(),
+      getJoinedRoomMembers: vi.fn(),
+      setAccountData: vi.fn(),
+    } as unknown as MatrixClient;
+
+    const roomId = await resolveMatrixRoomId(client, userId);
+
+    expect(roomId).toBe("!room:example.org");
+    expect(client.getJoinedRooms).not.toHaveBeenCalled();
+    expect(client.setAccountData).not.toHaveBeenCalled();
+  });
+
+  it("falls back to joined rooms and persists m.direct", async () => {
+    const userId = "@fallback:example.org";
+    const roomId = "!room:example.org";
+    const setAccountData = vi.fn().mockResolvedValue(undefined);
+    const client = {
+      getAccountData: vi.fn().mockRejectedValue(new Error("nope")),
+      getJoinedRooms: vi.fn().mockResolvedValue([roomId]),
+      getJoinedRoomMembers: vi.fn().mockResolvedValue([
+        "@bot:example.org",
+        userId,
+      ]),
+      setAccountData,
+    } as unknown as MatrixClient;
+
+    const resolved = await resolveMatrixRoomId(client, userId);
+
+    expect(resolved).toBe(roomId);
+    expect(setAccountData).toHaveBeenCalledWith(
+      EventType.Direct,
+      expect.objectContaining({ [userId]: [roomId] }),
+    );
+  });
+
+  it("continues when a room member lookup fails", async () => {
+    const userId = "@continue:example.org";
+    const roomId = "!good:example.org";
+    const setAccountData = vi.fn().mockResolvedValue(undefined);
+    const getJoinedRoomMembers = vi
+      .fn()
+      .mockRejectedValueOnce(new Error("boom"))
+      .mockResolvedValueOnce(["@bot:example.org", userId]);
+    const client = {
+      getAccountData: vi.fn().mockRejectedValue(new Error("nope")),
+      getJoinedRooms: vi.fn().mockResolvedValue(["!bad:example.org", roomId]),
+      getJoinedRoomMembers,
+      setAccountData,
+    } as unknown as MatrixClient;
+
+    const resolved = await resolveMatrixRoomId(client, userId);
+
+    expect(resolved).toBe(roomId);
+    expect(setAccountData).toHaveBeenCalled();
+  });
+
+  it("allows larger rooms when no 1:1 match exists", async () => {
+    const userId = "@group:example.org";
+    const roomId = "!group:example.org";
+    const client = {
+      getAccountData: vi.fn().mockRejectedValue(new Error("nope")),
+      getJoinedRooms: vi.fn().mockResolvedValue([roomId]),
+      getJoinedRoomMembers: vi.fn().mockResolvedValue([
+        "@bot:example.org",
+        userId,
+        "@extra:example.org",
+      ]),
+      setAccountData: vi.fn().mockResolvedValue(undefined),
+    } as unknown as MatrixClient;
+
+    const resolved = await resolveMatrixRoomId(client, userId);
+
+    expect(resolved).toBe(roomId);
+  });
+});
+
+describe("normalizeThreadId", () => {
+  it("returns null for empty thread ids", () => {
+    expect(normalizeThreadId("   ")).toBeNull();
+    expect(normalizeThreadId("$thread")).toBe("$thread");
+  });
+});
@@ -16,22 +16,100 @@ export function normalizeThreadId(raw?: string | number | null): string | null {
  return trimmed ? trimmed : null;
 }

-async function resolveDirectRoomId(client: MatrixClient, userId: string): Promise<string> {
+const directRoomCache = new Map<string, string>();
+
+async function persistDirectRoom(
+  client: MatrixClient,
+  userId: string,
+  roomId: string,
+): Promise<void> {
+  let directContent: MatrixDirectAccountData | null = null;
+  try {
+    directContent = (await client.getAccountData(
+      EventType.Direct,
+    )) as MatrixDirectAccountData | null;
+  } catch {
+    // Ignore fetch errors and fall back to an empty map.
+  }
+  const existing =
+    directContent && !Array.isArray(directContent) ? directContent : {};
+  const current = Array.isArray(existing[userId]) ? existing[userId] : [];
+  if (current[0] === roomId) return;
+  const next = [roomId, ...current.filter((id) => id !== roomId)];
+  try {
+    await client.setAccountData(EventType.Direct, {
+      ...existing,
+      [userId]: next,
+    });
+  } catch {
+    // Ignore persistence errors.
+  }
+}
+
+async function resolveDirectRoomId(
+  client: MatrixClient,
+  userId: string,
+): Promise<string> {
  const trimmed = userId.trim();
  if (!trimmed.startsWith("@")) {
-    throw new Error(`Matrix user IDs must be fully qualified (got "${trimmed}")`);
+    throw new Error(
+      `Matrix user IDs must be fully qualified (got "${trimmed}")`,
+    );
  }
-  // matrix-bot-sdk: use getAccountData to retrieve m.direct
+
+  const cached = directRoomCache.get(trimmed);
+  if (cached) return cached;
+
+  // 1) Fast path: use account data (m.direct) for *this* logged-in user (the bot).
  try {
-    const directContent = await client.getAccountData(EventType.Direct) as MatrixDirectAccountData | null;
-    const list = Array.isArray(directContent?.[trimmed]) ? directContent[trimmed] : [];
-    if (list.length > 0) return list[0];
+    const directContent = (await client.getAccountData(
+      EventType.Direct,
+    )) as MatrixDirectAccountData | null;
+    const list = Array.isArray(directContent?.[trimmed])
+      ? directContent[trimmed]
+      : [];
+    if (list.length > 0) {
+      directRoomCache.set(trimmed, list[0]);
+      return list[0];
+    }
  } catch {
-    // Ignore errors, try fetching from server
+    // Ignore and fall back.
  }
-  throw new Error(
-    `No m.direct room found for ${trimmed}. Open a DM first so Matrix can set m.direct.`,
-  );
+
+  // 2) Fallback: look for an existing joined room that looks like a 1:1 with the user.
+  // Many clients only maintain m.direct for *their own* account data, so relying on it is brittle.
+  let fallbackRoom: string | null = null;
+  try {
+    const rooms = await client.getJoinedRooms();
+    for (const roomId of rooms) {
+      let members: string[];
+      try {
+        members = await client.getJoinedRoomMembers(roomId);
+      } catch {
+        continue;
+      }
+      if (!members.includes(trimmed)) continue;
+      // Prefer classic 1:1 rooms, but allow larger rooms if requested.
+      if (members.length === 2) {
+        directRoomCache.set(trimmed, roomId);
+        await persistDirectRoom(client, trimmed, roomId);
+        return roomId;
+      }
+      if (!fallbackRoom) {
+        fallbackRoom = roomId;
+      }
+    }
+  } catch {
+    // Ignore and fall back.
+  }
+
+  if (fallbackRoom) {
+    directRoomCache.set(trimmed, fallbackRoom);
+    await persistDirectRoom(client, trimmed, fallbackRoom);
+    return fallbackRoom;
+  }
+
+  throw new Error(`No direct room found for ${trimmed} (m.direct missing)`);
 }

 export async function resolveMatrixRoomId(
@@ -0,0 +1,11 @@
+{
+  "id": "mattermost",
+  "channels": [
+    "mattermost"
+  ],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}
@@ -0,0 +1,18 @@
+import type { ClawdbotPluginApi } from "clawdbot/plugin-sdk";
+import { emptyPluginConfigSchema } from "clawdbot/plugin-sdk";
+
+import { mattermostPlugin } from "./src/channel.js";
+import { setMattermostRuntime } from "./src/runtime.js";
+
+const plugin = {
+  id: "mattermost",
+  name: "Mattermost",
+  description: "Mattermost channel plugin",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: ClawdbotPluginApi) {
+    setMattermostRuntime(api.runtime);
+    api.registerChannel({ plugin: mattermostPlugin });
+  },
+};
+
+export default plugin;
@@ -0,0 +1,25 @@
+{
+  "name": "@clawdbot/mattermost",
+  "version": "2026.1.20-2",
+  "type": "module",
+  "description": "Clawdbot Mattermost channel plugin",
+  "clawdbot": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "channel": {
+      "id": "mattermost",
+      "label": "Mattermost",
+      "selectionLabel": "Mattermost (plugin)",
+      "docsPath": "/channels/mattermost",
+      "docsLabel": "mattermost",
+      "blurb": "self-hosted Slack-style chat; install the plugin to enable.",
+      "order": 65
+    },
+    "install": {
+      "npmSpec": "@clawdbot/mattermost",
+      "localPath": "extensions/mattermost",
+      "defaultChoice": "npm"
+    }
+  }
+}
@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+
+import { mattermostPlugin } from "./channel.js";
+
+describe("mattermostPlugin", () => {
+  describe("messaging", () => {
+    it("keeps @username targets", () => {
+      const normalize = mattermostPlugin.messaging?.normalizeTarget;
+      if (!normalize) return;
+
+      expect(normalize("@Alice")).toBe("@Alice");
+      expect(normalize("@alice")).toBe("@alice");
+    });
+
+    it("normalizes mattermost: prefix to user:", () => {
+      const normalize = mattermostPlugin.messaging?.normalizeTarget;
+      if (!normalize) return;
+
+      expect(normalize("mattermost:USER123")).toBe("user:USER123");
+    });
+  });
+
+  describe("pairing", () => {
+    it("normalizes allowlist entries", () => {
+      const normalize = mattermostPlugin.pairing?.normalizeAllowEntry;
+      if (!normalize) return;
+
+      expect(normalize("@Alice")).toBe("alice");
+      expect(normalize("user:USER123")).toBe("user123");
+    });
+  });
+
+  describe("config", () => {
+    it("formats allowFrom entries", () => {
+      const formatAllowFrom = mattermostPlugin.config.formatAllowFrom;
+
+      const formatted = formatAllowFrom({
+        allowFrom: ["@Alice", "user:USER123", "mattermost:BOT999"],
+      });
+      expect(formatted).toEqual(["@alice", "user123", "bot999"]);
+    });
+  });
+});
@@ -0,0 +1,338 @@
+import {
+  applyAccountNameToChannelSection,
+  buildChannelConfigSchema,
+  DEFAULT_ACCOUNT_ID,
+  deleteAccountFromConfigSection,
+  formatPairingApproveHint,
+  migrateBaseNameToDefaultAccount,
+  normalizeAccountId,
+  setAccountEnabledInConfigSection,
+  type ChannelPlugin,
+} from "clawdbot/plugin-sdk";
+
+import { MattermostConfigSchema } from "./config-schema.js";
+import { resolveMattermostGroupRequireMention } from "./group-mentions.js";
+import {
+  looksLikeMattermostTargetId,
+  normalizeMattermostMessagingTarget,
+} from "./normalize.js";
+import { mattermostOnboardingAdapter } from "./onboarding.js";
+import {
+  listMattermostAccountIds,
+  resolveDefaultMattermostAccountId,
+  resolveMattermostAccount,
+  type ResolvedMattermostAccount,
+} from "./mattermost/accounts.js";
+import { normalizeMattermostBaseUrl } from "./mattermost/client.js";
+import { monitorMattermostProvider } from "./mattermost/monitor.js";
+import { probeMattermost } from "./mattermost/probe.js";
+import { sendMessageMattermost } from "./mattermost/send.js";
+import { getMattermostRuntime } from "./runtime.js";
+
+const meta = {
+  id: "mattermost",
+  label: "Mattermost",
+  selectionLabel: "Mattermost (plugin)",
+  detailLabel: "Mattermost Bot",
+  docsPath: "/channels/mattermost",
+  docsLabel: "mattermost",
+  blurb: "self-hosted Slack-style chat; install the plugin to enable.",
+  systemImage: "bubble.left.and.bubble.right",
+  order: 65,
+  quickstartAllowFrom: true,
+} as const;
+
+function normalizeAllowEntry(entry: string): string {
+  return entry
+    .trim()
+    .replace(/^(mattermost|user):/i, "")
+    .replace(/^@/, "")
+    .toLowerCase();
+}
+
+function formatAllowEntry(entry: string): string {
+  const trimmed = entry.trim();
+  if (!trimmed) return "";
+  if (trimmed.startsWith("@")) {
+    const username = trimmed.slice(1).trim();
+    return username ? `@${username.toLowerCase()}` : "";
+  }
+  return trimmed.replace(/^(mattermost|user):/i, "").toLowerCase();
+}
+
+export const mattermostPlugin: ChannelPlugin<ResolvedMattermostAccount> = {
+  id: "mattermost",
+  meta: {
+    ...meta,
+  },
+  onboarding: mattermostOnboardingAdapter,
+  pairing: {
+    idLabel: "mattermostUserId",
+    normalizeAllowEntry: (entry) => normalizeAllowEntry(entry),
+    notifyApproval: async ({ id }) => {
+      console.log(`[mattermost] User ${id} approved for pairing`);
+    },
+  },
+  capabilities: {
+    chatTypes: ["direct", "channel", "group", "thread"],
+    threads: true,
+    media: true,
+  },
+  streaming: {
+    blockStreamingCoalesceDefaults: { minChars: 1500, idleMs: 1000 },
+  },
+  reload: { configPrefixes: ["channels.mattermost"] },
+  configSchema: buildChannelConfigSchema(MattermostConfigSchema),
+  config: {
+    listAccountIds: (cfg) => listMattermostAccountIds(cfg),
+    resolveAccount: (cfg, accountId) => resolveMattermostAccount({ cfg, accountId }),
+    defaultAccountId: (cfg) => resolveDefaultMattermostAccountId(cfg),
+    setAccountEnabled: ({ cfg, accountId, enabled }) =>
+      setAccountEnabledInConfigSection({
+        cfg,
+        sectionKey: "mattermost",
+        accountId,
+        enabled,
+        allowTopLevel: true,
+      }),
+    deleteAccount: ({ cfg, accountId }) =>
+      deleteAccountFromConfigSection({
+        cfg,
+        sectionKey: "mattermost",
+        accountId,
+        clearBaseFields: ["botToken", "baseUrl", "name"],
+      }),
+    isConfigured: (account) => Boolean(account.botToken && account.baseUrl),
+    describeAccount: (account) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: Boolean(account.botToken && account.baseUrl),
+      botTokenSource: account.botTokenSource,
+      baseUrl: account.baseUrl,
+    }),
+    resolveAllowFrom: ({ cfg, accountId }) =>
+      (resolveMattermostAccount({ cfg, accountId }).config.allowFrom ?? []).map((entry) =>
+        String(entry),
+      ),
+    formatAllowFrom: ({ allowFrom }) =>
+      allowFrom
+        .map((entry) => formatAllowEntry(String(entry)))
+        .filter(Boolean),
+  },
+  security: {
+    resolveDmPolicy: ({ cfg, accountId, account }) => {
+      const resolvedAccountId = accountId ?? account.accountId ?? DEFAULT_ACCOUNT_ID;
+      const useAccountPath = Boolean(cfg.channels?.mattermost?.accounts?.[resolvedAccountId]);
+      const basePath = useAccountPath
+        ? `channels.mattermost.accounts.${resolvedAccountId}.`
+        : "channels.mattermost.";
+      return {
+        policy: account.config.dmPolicy ?? "pairing",
+        allowFrom: account.config.allowFrom ?? [],
+        policyPath: `${basePath}dmPolicy`,
+        allowFromPath: basePath,
+        approveHint: formatPairingApproveHint("mattermost"),
+        normalizeEntry: (raw) => normalizeAllowEntry(raw),
+      };
+    },
+    collectWarnings: ({ account, cfg }) => {
+      const defaultGroupPolicy = cfg.channels?.defaults?.groupPolicy;
+      const groupPolicy = account.config.groupPolicy ?? defaultGroupPolicy ?? "allowlist";
+      if (groupPolicy !== "open") return [];
+      return [
+        `- Mattermost channels: groupPolicy="open" allows any member to trigger (mention-gated). Set channels.mattermost.groupPolicy="allowlist" + channels.mattermost.groupAllowFrom to restrict senders.`,
+      ];
+    },
+  },
+  groups: {
+    resolveRequireMention: resolveMattermostGroupRequireMention,
+  },
+  messaging: {
+    normalizeTarget: normalizeMattermostMessagingTarget,
+    targetResolver: {
+      looksLikeId: looksLikeMattermostTargetId,
+      hint: "<channelId|user:ID|channel:ID>",
+    },
+  },
+  outbound: {
+    deliveryMode: "direct",
+    chunker: (text, limit) => getMattermostRuntime().channel.text.chunkMarkdownText(text, limit),
+    textChunkLimit: 4000,
+    resolveTarget: ({ to }) => {
+      const trimmed = to?.trim();
+      if (!trimmed) {
+        return {
+          ok: false,
+          error: new Error(
+            "Delivering to Mattermost requires --to <channelId|@username|user:ID|channel:ID>",
+          ),
+        };
+      }
+      return { ok: true, to: trimmed };
+    },
+    sendText: async ({ to, text, accountId, replyToId }) => {
+      const result = await sendMessageMattermost(to, text, {
+        accountId: accountId ?? undefined,
+        replyToId: replyToId ?? undefined,
+      });
+      return { channel: "mattermost", ...result };
+    },
+    sendMedia: async ({ to, text, mediaUrl, accountId, replyToId }) => {
+      const result = await sendMessageMattermost(to, text, {
+        accountId: accountId ?? undefined,
+        mediaUrl,
+        replyToId: replyToId ?? undefined,
+      });
+      return { channel: "mattermost", ...result };
+    },
+  },
+  status: {
+    defaultRuntime: {
+      accountId: DEFAULT_ACCOUNT_ID,
+      running: false,
+      connected: false,
+      lastConnectedAt: null,
+      lastDisconnect: null,
+      lastStartAt: null,
+      lastStopAt: null,
+      lastError: null,
+    },
+    buildChannelSummary: ({ snapshot }) => ({
+      configured: snapshot.configured ?? false,
+      botTokenSource: snapshot.botTokenSource ?? "none",
+      running: snapshot.running ?? false,
+      connected: snapshot.connected ?? false,
+      lastStartAt: snapshot.lastStartAt ?? null,
+      lastStopAt: snapshot.lastStopAt ?? null,
+      lastError: snapshot.lastError ?? null,
+      baseUrl: snapshot.baseUrl ?? null,
+      probe: snapshot.probe,
+      lastProbeAt: snapshot.lastProbeAt ?? null,
+    }),
+    probeAccount: async ({ account, timeoutMs }) => {
+      const token = account.botToken?.trim();
+      const baseUrl = account.baseUrl?.trim();
+      if (!token || !baseUrl) {
+        return { ok: false, error: "bot token or baseUrl missing" };
+      }
+      return await probeMattermost(baseUrl, token, timeoutMs);
+    },
+    buildAccountSnapshot: ({ account, runtime, probe }) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: Boolean(account.botToken && account.baseUrl),
+      botTokenSource: account.botTokenSource,
+      baseUrl: account.baseUrl,
+      running: runtime?.running ?? false,
+      connected: runtime?.connected ?? false,
+      lastConnectedAt: runtime?.lastConnectedAt ?? null,
+      lastDisconnect: runtime?.lastDisconnect ?? null,
+      lastStartAt: runtime?.lastStartAt ?? null,
+      lastStopAt: runtime?.lastStopAt ?? null,
+      lastError: runtime?.lastError ?? null,
+      probe,
+      lastInboundAt: runtime?.lastInboundAt ?? null,
+      lastOutboundAt: runtime?.lastOutboundAt ?? null,
+    }),
+  },
+  setup: {
+    resolveAccountId: ({ accountId }) => normalizeAccountId(accountId),
+    applyAccountName: ({ cfg, accountId, name }) =>
+      applyAccountNameToChannelSection({
+        cfg,
+        channelKey: "mattermost",
+        accountId,
+        name,
+      }),
+    validateInput: ({ accountId, input }) => {
+      if (input.useEnv && accountId !== DEFAULT_ACCOUNT_ID) {
+        return "Mattermost env vars can only be used for the default account.";
+      }
+      const token = input.botToken ?? input.token;
+      const baseUrl = input.httpUrl;
+      if (!input.useEnv && (!token || !baseUrl)) {
+        return "Mattermost requires --bot-token and --http-url (or --use-env).";
+      }
+      if (baseUrl && !normalizeMattermostBaseUrl(baseUrl)) {
+        return "Mattermost --http-url must include a valid base URL.";
+      }
+      return null;
+    },
+    applyAccountConfig: ({ cfg, accountId, input }) => {
+      const token = input.botToken ?? input.token;
+      const baseUrl = input.httpUrl?.trim();
+      const namedConfig = applyAccountNameToChannelSection({
+        cfg,
+        channelKey: "mattermost",
+        accountId,
+        name: input.name,
+      });
+      const next =
+        accountId !== DEFAULT_ACCOUNT_ID
+          ? migrateBaseNameToDefaultAccount({
+              cfg: namedConfig,
+              channelKey: "mattermost",
+            })
+          : namedConfig;
+      if (accountId === DEFAULT_ACCOUNT_ID) {
+        return {
+          ...next,
+          channels: {
+            ...next.channels,
+            mattermost: {
+              ...next.channels?.mattermost,
+              enabled: true,
+              ...(input.useEnv
+                ? {}
+                : {
+                    ...(token ? { botToken: token } : {}),
+                    ...(baseUrl ? { baseUrl } : {}),
+                  }),
+            },
+          },
+        };
+      }
+      return {
+        ...next,
+        channels: {
+          ...next.channels,
+          mattermost: {
+            ...next.channels?.mattermost,
+            enabled: true,
+            accounts: {
+              ...next.channels?.mattermost?.accounts,
+              [accountId]: {
+                ...next.channels?.mattermost?.accounts?.[accountId],
+                enabled: true,
+                ...(token ? { botToken: token } : {}),
+                ...(baseUrl ? { baseUrl } : {}),
+              },
+            },
+          },
+        },
+      };
+    },
+  },
+  gateway: {
+    startAccount: async (ctx) => {
+      const account = ctx.account;
+      ctx.setStatus({
+        accountId: account.accountId,
+        baseUrl: account.baseUrl,
+        botTokenSource: account.botTokenSource,
+      });
+      ctx.log?.info(`[${account.accountId}] starting channel`);
+      return monitorMattermostProvider({
+        botToken: account.botToken ?? undefined,
+        baseUrl: account.baseUrl ?? undefined,
+        accountId: account.accountId,
+        config: ctx.cfg,
+        runtime: ctx.runtime,
+        abortSignal: ctx.abortSignal,
+        statusSink: (patch) => ctx.setStatus({ accountId: ctx.accountId, ...patch }),
+      });
+    },
+  },
+};
@@ -0,0 +1,53 @@
+import { z } from "zod";
+
+import {
+  BlockStreamingCoalesceSchema,
+  DmPolicySchema,
+  GroupPolicySchema,
+  requireOpenAllowFrom,
+} from "clawdbot/plugin-sdk";
+
+const MattermostAccountSchemaBase = z
+  .object({
+    name: z.string().optional(),
+    capabilities: z.array(z.string()).optional(),
+    enabled: z.boolean().optional(),
+    configWrites: z.boolean().optional(),
+    botToken: z.string().optional(),
+    baseUrl: z.string().optional(),
+    chatmode: z.enum(["oncall", "onmessage", "onchar"]).optional(),
+    oncharPrefixes: z.array(z.string()).optional(),
+    requireMention: z.boolean().optional(),
+    dmPolicy: DmPolicySchema.optional().default("pairing"),
+    allowFrom: z.array(z.union([z.string(), z.number()])).optional(),
+    groupAllowFrom: z.array(z.union([z.string(), z.number()])).optional(),
+    groupPolicy: GroupPolicySchema.optional().default("allowlist"),
+    textChunkLimit: z.number().int().positive().optional(),
+    blockStreaming: z.boolean().optional(),
+    blockStreamingCoalesce: BlockStreamingCoalesceSchema.optional(),
+  })
+  .strict();
+
+const MattermostAccountSchema = MattermostAccountSchemaBase.superRefine((value, ctx) => {
+  requireOpenAllowFrom({
+    policy: value.dmPolicy,
+    allowFrom: value.allowFrom,
+    ctx,
+    path: ["allowFrom"],
+    message:
+      'channels.mattermost.dmPolicy="open" requires channels.mattermost.allowFrom to include "*"',
+  });
+});
+
+export const MattermostConfigSchema = MattermostAccountSchemaBase.extend({
+  accounts: z.record(z.string(), MattermostAccountSchema.optional()).optional(),
+}).superRefine((value, ctx) => {
+  requireOpenAllowFrom({
+    policy: value.dmPolicy,
+    allowFrom: value.allowFrom,
+    ctx,
+    path: ["allowFrom"],
+    message:
+      'channels.mattermost.dmPolicy="open" requires channels.mattermost.allowFrom to include "*"',
+  });
+});
@@ -0,0 +1,14 @@
+import type { ChannelGroupContext } from "clawdbot/plugin-sdk";
+
+import { resolveMattermostAccount } from "./mattermost/accounts.js";
+
+export function resolveMattermostGroupRequireMention(
+  params: ChannelGroupContext,
+): boolean | undefined {
+  const account = resolveMattermostAccount({
+    cfg: params.cfg,
+    accountId: params.accountId,
+  });
+  if (typeof account.requireMention === "boolean") return account.requireMention;
+  return true;
+}
@@ -0,0 +1,115 @@
+import type { ClawdbotConfig } from "clawdbot/plugin-sdk";
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "clawdbot/plugin-sdk";
+
+import type { MattermostAccountConfig, MattermostChatMode } from "../types.js";
+import { normalizeMattermostBaseUrl } from "./client.js";
+
+export type MattermostTokenSource = "env" | "config" | "none";
+export type MattermostBaseUrlSource = "env" | "config" | "none";
+
+export type ResolvedMattermostAccount = {
+  accountId: string;
+  enabled: boolean;
+  name?: string;
+  botToken?: string;
+  baseUrl?: string;
+  botTokenSource: MattermostTokenSource;
+  baseUrlSource: MattermostBaseUrlSource;
+  config: MattermostAccountConfig;
+  chatmode?: MattermostChatMode;
+  oncharPrefixes?: string[];
+  requireMention?: boolean;
+  textChunkLimit?: number;
+  blockStreaming?: boolean;
+  blockStreamingCoalesce?: MattermostAccountConfig["blockStreamingCoalesce"];
+};
+
+function listConfiguredAccountIds(cfg: ClawdbotConfig): string[] {
+  const accounts = cfg.channels?.mattermost?.accounts;
+  if (!accounts || typeof accounts !== "object") return [];
+  return Object.keys(accounts).filter(Boolean);
+}
+
+export function listMattermostAccountIds(cfg: ClawdbotConfig): string[] {
+  const ids = listConfiguredAccountIds(cfg);
+  if (ids.length === 0) return [DEFAULT_ACCOUNT_ID];
+  return ids.sort((a, b) => a.localeCompare(b));
+}
+
+export function resolveDefaultMattermostAccountId(cfg: ClawdbotConfig): string {
+  const ids = listMattermostAccountIds(cfg);
+  if (ids.includes(DEFAULT_ACCOUNT_ID)) return DEFAULT_ACCOUNT_ID;
+  return ids[0] ?? DEFAULT_ACCOUNT_ID;
+}
+
+function resolveAccountConfig(
+  cfg: ClawdbotConfig,
+  accountId: string,
+): MattermostAccountConfig | undefined {
+  const accounts = cfg.channels?.mattermost?.accounts;
+  if (!accounts || typeof accounts !== "object") return undefined;
+  return accounts[accountId] as MattermostAccountConfig | undefined;
+}
+
+function mergeMattermostAccountConfig(
+  cfg: ClawdbotConfig,
+  accountId: string,
+): MattermostAccountConfig {
+  const { accounts: _ignored, ...base } = (cfg.channels?.mattermost ??
+    {}) as MattermostAccountConfig & { accounts?: unknown };
+  const account = resolveAccountConfig(cfg, accountId) ?? {};
+  return { ...base, ...account };
+}
+
+function resolveMattermostRequireMention(config: MattermostAccountConfig): boolean | undefined {
+  if (config.chatmode === "oncall") return true;
+  if (config.chatmode === "onmessage") return false;
+  if (config.chatmode === "onchar") return true;
+  return config.requireMention;
+}
+
+export function resolveMattermostAccount(params: {
+  cfg: ClawdbotConfig;
+  accountId?: string | null;
+}): ResolvedMattermostAccount {
+  const accountId = normalizeAccountId(params.accountId);
+  const baseEnabled = params.cfg.channels?.mattermost?.enabled !== false;
+  const merged = mergeMattermostAccountConfig(params.cfg, accountId);
+  const accountEnabled = merged.enabled !== false;
+  const enabled = baseEnabled && accountEnabled;
+
+  const allowEnv = accountId === DEFAULT_ACCOUNT_ID;
+  const envToken = allowEnv ? process.env.MATTERMOST_BOT_TOKEN?.trim() : undefined;
+  const envUrl = allowEnv ? process.env.MATTERMOST_URL?.trim() : undefined;
+  const configToken = merged.botToken?.trim();
+  const configUrl = merged.baseUrl?.trim();
+  const botToken = configToken || envToken;
+  const baseUrl = normalizeMattermostBaseUrl(configUrl || envUrl);
+  const requireMention = resolveMattermostRequireMention(merged);
+
+  const botTokenSource: MattermostTokenSource = configToken ? "config" : envToken ? "env" : "none";
+  const baseUrlSource: MattermostBaseUrlSource = configUrl ? "config" : envUrl ? "env" : "none";
+
+  return {
+    accountId,
+    enabled,
+    name: merged.name?.trim() || undefined,
+    botToken,
+    baseUrl,
+    botTokenSource,
+    baseUrlSource,
+    config: merged,
+    chatmode: merged.chatmode,
+    oncharPrefixes: merged.oncharPrefixes,
+    requireMention,
+    textChunkLimit: merged.textChunkLimit,
+    blockStreaming: merged.blockStreaming,
+    blockStreamingCoalesce: merged.blockStreamingCoalesce,
+  };
+}
+
+export function listEnabledMattermostAccounts(cfg: ClawdbotConfig): ResolvedMattermostAccount[] {
+  return listMattermostAccountIds(cfg)
+    .map((accountId) => resolveMattermostAccount({ cfg, accountId }))
+    .filter((account) => account.enabled);
+}
@@ -0,0 +1,208 @@
+export type MattermostClient = {
+  baseUrl: string;
+  apiBaseUrl: string;
+  token: string;
+  request: <T>(path: string, init?: RequestInit) => Promise<T>;
+};
+
+export type MattermostUser = {
+  id: string;
+  username?: string | null;
+  nickname?: string | null;
+  first_name?: string | null;
+  last_name?: string | null;
+};
+
+export type MattermostChannel = {
+  id: string;
+  name?: string | null;
+  display_name?: string | null;
+  type?: string | null;
+  team_id?: string | null;
+};
+
+export type MattermostPost = {
+  id: string;
+  user_id?: string | null;
+  channel_id?: string | null;
+  message?: string | null;
+  file_ids?: string[] | null;
+  type?: string | null;
+  root_id?: string | null;
+  create_at?: number | null;
+  props?: Record<string, unknown> | null;
+};
+
+export type MattermostFileInfo = {
+  id: string;
+  name?: string | null;
+  mime_type?: string | null;
+  size?: number | null;
+};
+
+export function normalizeMattermostBaseUrl(raw?: string | null): string | undefined {
+  const trimmed = raw?.trim();
+  if (!trimmed) return undefined;
+  const withoutTrailing = trimmed.replace(/\/+$/, "");
+  return withoutTrailing.replace(/\/api\/v4$/i, "");
+}
+
+function buildMattermostApiUrl(baseUrl: string, path: string): string {
+  const normalized = normalizeMattermostBaseUrl(baseUrl);
+  if (!normalized) throw new Error("Mattermost baseUrl is required");
+  const suffix = path.startsWith("/") ? path : `/${path}`;
+  return `${normalized}/api/v4${suffix}`;
+}
+
+async function readMattermostError(res: Response): Promise<string> {
+  const contentType = res.headers.get("content-type") ?? "";
+  if (contentType.includes("application/json")) {
+    const data = (await res.json()) as { message?: string } | undefined;
+    if (data?.message) return data.message;
+    return JSON.stringify(data);
+  }
+  return await res.text();
+}
+
+export function createMattermostClient(params: {
+  baseUrl: string;
+  botToken: string;
+  fetchImpl?: typeof fetch;
+}): MattermostClient {
+  const baseUrl = normalizeMattermostBaseUrl(params.baseUrl);
+  if (!baseUrl) throw new Error("Mattermost baseUrl is required");
+  const apiBaseUrl = `${baseUrl}/api/v4`;
+  const token = params.botToken.trim();
+  const fetchImpl = params.fetchImpl ?? fetch;
+
+  const request = async <T>(path: string, init?: RequestInit): Promise<T> => {
+    const url = buildMattermostApiUrl(baseUrl, path);
+    const headers = new Headers(init?.headers);
+    headers.set("Authorization", `Bearer ${token}`);
+    if (typeof init?.body === "string" && !headers.has("Content-Type")) {
+      headers.set("Content-Type", "application/json");
+    }
+    const res = await fetchImpl(url, { ...init, headers });
+    if (!res.ok) {
+      const detail = await readMattermostError(res);
+      throw new Error(
+        `Mattermost API ${res.status} ${res.statusText}: ${detail || "unknown error"}`,
+      );
+    }
+    return (await res.json()) as T;
+  };
+
+  return { baseUrl, apiBaseUrl, token, request };
+}
+
+export async function fetchMattermostMe(client: MattermostClient): Promise<MattermostUser> {
+  return await client.request<MattermostUser>("/users/me");
+}
+
+export async function fetchMattermostUser(
+  client: MattermostClient,
+  userId: string,
+): Promise<MattermostUser> {
+  return await client.request<MattermostUser>(`/users/${userId}`);
+}
+
+export async function fetchMattermostUserByUsername(
+  client: MattermostClient,
+  username: string,
+): Promise<MattermostUser> {
+  return await client.request<MattermostUser>(`/users/username/${encodeURIComponent(username)}`);
+}
+
+export async function fetchMattermostChannel(
+  client: MattermostClient,
+  channelId: string,
+): Promise<MattermostChannel> {
+  return await client.request<MattermostChannel>(`/channels/${channelId}`);
+}
+
+export async function sendMattermostTyping(
+  client: MattermostClient,
+  params: { channelId: string; parentId?: string },
+): Promise<void> {
+  const payload: Record<string, string> = {
+    channel_id: params.channelId,
+  };
+  const parentId = params.parentId?.trim();
+  if (parentId) payload.parent_id = parentId;
+  await client.request<Record<string, unknown>>("/users/me/typing", {
+    method: "POST",
+    body: JSON.stringify(payload),
+  });
+}
+
+export async function createMattermostDirectChannel(
+  client: MattermostClient,
+  userIds: string[],
+): Promise<MattermostChannel> {
+  return await client.request<MattermostChannel>("/channels/direct", {
+    method: "POST",
+    body: JSON.stringify(userIds),
+  });
+}
+
+export async function createMattermostPost(
+  client: MattermostClient,
+  params: {
+    channelId: string;
+    message: string;
+    rootId?: string;
+    fileIds?: string[];
+  },
+): Promise<MattermostPost> {
+  const payload: Record<string, string> = {
+    channel_id: params.channelId,
+    message: params.message,
+  };
+  if (params.rootId) payload.root_id = params.rootId;
+  if (params.fileIds?.length) {
+    (payload as Record<string, unknown>).file_ids = params.fileIds;
+  }
+  return await client.request<MattermostPost>("/posts", {
+    method: "POST",
+    body: JSON.stringify(payload),
+  });
+}
+
+export async function uploadMattermostFile(
+  client: MattermostClient,
+  params: {
+    channelId: string;
+    buffer: Buffer;
+    fileName: string;
+    contentType?: string;
+  },
+): Promise<MattermostFileInfo> {
+  const form = new FormData();
+  const fileName = params.fileName?.trim() || "upload";
+  const bytes = Uint8Array.from(params.buffer);
+  const blob = params.contentType
+    ? new Blob([bytes], { type: params.contentType })
+    : new Blob([bytes]);
+  form.append("files", blob, fileName);
+  form.append("channel_id", params.channelId);
+
+  const res = await fetch(`${client.apiBaseUrl}/files`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${client.token}`,
+    },
+    body: form,
+  });
+
+  if (!res.ok) {
+    const detail = await readMattermostError(res);
+    throw new Error(`Mattermost API ${res.status} ${res.statusText}: ${detail || "unknown error"}`);
+  }
+
+  const data = (await res.json()) as { file_infos?: MattermostFileInfo[] };
+  const info = data.file_infos?.[0];
+  if (!info?.id) {
+    throw new Error("Mattermost file upload failed");
+  }
+  return info;
+}
@@ -0,0 +1,9 @@
+export {
+  listEnabledMattermostAccounts,
+  listMattermostAccountIds,
+  resolveDefaultMattermostAccountId,
+  resolveMattermostAccount,
+} from "./accounts.js";
+export { monitorMattermostProvider } from "./monitor.js";
+export { probeMattermost } from "./probe.js";
+export { sendMessageMattermost } from "./send.js";
@@ -0,0 +1,150 @@
+import { Buffer } from "node:buffer";
+
+import type WebSocket from "ws";
+
+import type { ClawdbotConfig } from "clawdbot/plugin-sdk";
+
+export type ResponsePrefixContext = {
+  model?: string;
+  modelFull?: string;
+  provider?: string;
+  thinkingLevel?: string;
+  identityName?: string;
+};
+
+export function extractShortModelName(fullModel: string): string {
+  const slash = fullModel.lastIndexOf("/");
+  const modelPart = slash >= 0 ? fullModel.slice(slash + 1) : fullModel;
+  return modelPart.replace(/-\d{8}$/, "").replace(/-latest$/, "");
+}
+
+export function formatInboundFromLabel(params: {
+  isGroup: boolean;
+  groupLabel?: string;
+  groupId?: string;
+  directLabel: string;
+  directId?: string;
+  groupFallback?: string;
+}): string {
+  if (params.isGroup) {
+    const label = params.groupLabel?.trim() || params.groupFallback || "Group";
+    const id = params.groupId?.trim();
+    return id ? `${label} id:${id}` : label;
+  }
+
+  const directLabel = params.directLabel.trim();
+  const directId = params.directId?.trim();
+  if (!directId || directId === directLabel) return directLabel;
+  return `${directLabel} id:${directId}`;
+}
+
+type DedupeCache = {
+  check: (key: string | undefined | null, now?: number) => boolean;
+};
+
+export function createDedupeCache(options: { ttlMs: number; maxSize: number }): DedupeCache {
+  const ttlMs = Math.max(0, options.ttlMs);
+  const maxSize = Math.max(0, Math.floor(options.maxSize));
+  const cache = new Map<string, number>();
+
+  const touch = (key: string, now: number) => {
+    cache.delete(key);
+    cache.set(key, now);
+  };
+
+  const prune = (now: number) => {
+    const cutoff = ttlMs > 0 ? now - ttlMs : undefined;
+    if (cutoff !== undefined) {
+      for (const [entryKey, entryTs] of cache) {
+        if (entryTs < cutoff) {
+          cache.delete(entryKey);
+        }
+      }
+    }
+    if (maxSize <= 0) {
+      cache.clear();
+      return;
+    }
+    while (cache.size > maxSize) {
+      const oldestKey = cache.keys().next().value as string | undefined;
+      if (!oldestKey) break;
+      cache.delete(oldestKey);
+    }
+  };
+
+  return {
+    check: (key, now = Date.now()) => {
+      if (!key) return false;
+      const existing = cache.get(key);
+      if (existing !== undefined && (ttlMs <= 0 || now - existing < ttlMs)) {
+        touch(key, now);
+        return true;
+      }
+      touch(key, now);
+      prune(now);
+      return false;
+    },
+  };
+}
+
+export function rawDataToString(
+  data: WebSocket.RawData,
+  encoding: BufferEncoding = "utf8",
+): string {
+  if (typeof data === "string") return data;
+  if (Buffer.isBuffer(data)) return data.toString(encoding);
+  if (Array.isArray(data)) return Buffer.concat(data).toString(encoding);
+  if (data instanceof ArrayBuffer) {
+    return Buffer.from(data).toString(encoding);
+  }
+  return Buffer.from(String(data)).toString(encoding);
+}
+
+function normalizeAgentId(value: string | undefined | null): string {
+  const trimmed = (value ?? "").trim();
+  if (!trimmed) return "main";
+  if (/^[a-z0-9][a-z0-9_-]{0,63}$/i.test(trimmed)) return trimmed;
+  return (
+    trimmed
+      .toLowerCase()
+      .replace(/[^a-z0-9_-]+/g, "-")
+      .replace(/^-+/, "")
+      .replace(/-+$/, "")
+      .slice(0, 64) || "main"
+  );
+}
+
+type AgentEntry = NonNullable<NonNullable<ClawdbotConfig["agents"]>["list"]>[number];
+
+function listAgents(cfg: ClawdbotConfig): AgentEntry[] {
+  const list = cfg.agents?.list;
+  if (!Array.isArray(list)) return [];
+  return list.filter((entry): entry is AgentEntry => Boolean(entry && typeof entry === "object"));
+}
+
+function resolveAgentEntry(cfg: ClawdbotConfig, agentId: string): AgentEntry | undefined {
+  const id = normalizeAgentId(agentId);
+  return listAgents(cfg).find((entry) => normalizeAgentId(entry.id) === id);
+}
+
+export function resolveIdentityName(cfg: ClawdbotConfig, agentId: string): string | undefined {
+  const entry = resolveAgentEntry(cfg, agentId);
+  return entry?.identity?.name?.trim() || undefined;
+}
+
+export function resolveThreadSessionKeys(params: {
+  baseSessionKey: string;
+  threadId?: string | null;
+  parentSessionKey?: string;
+  useSuffix?: boolean;
+}): { sessionKey: string; parentSessionKey?: string } {
+  const threadId = (params.threadId ?? "").trim();
+  if (!threadId) {
+    return { sessionKey: params.baseSessionKey, parentSessionKey: undefined };
+  }
+  const useSuffix = params.useSuffix ?? true;
+  const sessionKey = useSuffix
+    ? `${params.baseSessionKey}:thread:${threadId}`
+    : params.baseSessionKey;
+  return { sessionKey, parentSessionKey: params.parentSessionKey };
+}
@@ -0,0 +1,905 @@
+import WebSocket from "ws";
+
+import type {
+  ChannelAccountSnapshot,
+  ClawdbotConfig,
+  ReplyPayload,
+  RuntimeEnv,
+} from "clawdbot/plugin-sdk";
+import {
+  buildPendingHistoryContextFromMap,
+  clearHistoryEntries,
+  DEFAULT_GROUP_HISTORY_LIMIT,
+  recordPendingHistoryEntry,
+  resolveChannelMediaMaxBytes,
+  type HistoryEntry,
+} from "clawdbot/plugin-sdk";
+
+import { getMattermostRuntime } from "../runtime.js";
+import { resolveMattermostAccount } from "./accounts.js";
+import {
+  createMattermostClient,
+  fetchMattermostChannel,
+  fetchMattermostMe,
+  fetchMattermostUser,
+  normalizeMattermostBaseUrl,
+  sendMattermostTyping,
+  type MattermostChannel,
+  type MattermostPost,
+  type MattermostUser,
+} from "./client.js";
+import {
+  createDedupeCache,
+  extractShortModelName,
+  formatInboundFromLabel,
+  rawDataToString,
+  resolveIdentityName,
+  resolveThreadSessionKeys,
+  type ResponsePrefixContext,
+} from "./monitor-helpers.js";
+import { sendMessageMattermost } from "./send.js";
+
+export type MonitorMattermostOpts = {
+  botToken?: string;
+  baseUrl?: string;
+  accountId?: string;
+  config?: ClawdbotConfig;
+  runtime?: RuntimeEnv;
+  abortSignal?: AbortSignal;
+  statusSink?: (patch: Partial<ChannelAccountSnapshot>) => void;
+};
+
+type FetchLike = typeof fetch;
+type MediaKind = "image" | "audio" | "video" | "document" | "unknown";
+
+type MattermostEventPayload = {
+  event?: string;
+  data?: {
+    post?: string;
+    channel_id?: string;
+    channel_name?: string;
+    channel_display_name?: string;
+    channel_type?: string;
+    sender_name?: string;
+    team_id?: string;
+  };
+  broadcast?: {
+    channel_id?: string;
+    team_id?: string;
+    user_id?: string;
+  };
+};
+
+const RECENT_MATTERMOST_MESSAGE_TTL_MS = 5 * 60_000;
+const RECENT_MATTERMOST_MESSAGE_MAX = 2000;
+const CHANNEL_CACHE_TTL_MS = 5 * 60_000;
+const USER_CACHE_TTL_MS = 10 * 60_000;
+const DEFAULT_ONCHAR_PREFIXES = [">", "!"];
+
+const recentInboundMessages = createDedupeCache({
+  ttlMs: RECENT_MATTERMOST_MESSAGE_TTL_MS,
+  maxSize: RECENT_MATTERMOST_MESSAGE_MAX,
+});
+
+function resolveRuntime(opts: MonitorMattermostOpts): RuntimeEnv {
+  return (
+    opts.runtime ?? {
+      log: console.log,
+      error: console.error,
+      exit: (code: number): never => {
+        throw new Error(`exit ${code}`);
+      },
+    }
+  );
+}
+
+function normalizeMention(text: string, mention: string | undefined): string {
+  if (!mention) return text.trim();
+  const escaped = mention.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const re = new RegExp(`@${escaped}\\b`, "gi");
+  return text.replace(re, " ").replace(/\s+/g, " ").trim();
+}
+
+function resolveOncharPrefixes(prefixes: string[] | undefined): string[] {
+  const cleaned = prefixes?.map((entry) => entry.trim()).filter(Boolean) ?? DEFAULT_ONCHAR_PREFIXES;
+  return cleaned.length > 0 ? cleaned : DEFAULT_ONCHAR_PREFIXES;
+}
+
+function stripOncharPrefix(
+  text: string,
+  prefixes: string[],
+): { triggered: boolean; stripped: string } {
+  const trimmed = text.trimStart();
+  for (const prefix of prefixes) {
+    if (!prefix) continue;
+    if (trimmed.startsWith(prefix)) {
+      return {
+        triggered: true,
+        stripped: trimmed.slice(prefix.length).trimStart(),
+      };
+    }
+  }
+  return { triggered: false, stripped: text };
+}
+
+function isSystemPost(post: MattermostPost): boolean {
+  const type = post.type?.trim();
+  return Boolean(type);
+}
+
+function channelKind(channelType?: string | null): "dm" | "group" | "channel" {
+  if (!channelType) return "channel";
+  const normalized = channelType.trim().toUpperCase();
+  if (normalized === "D") return "dm";
+  if (normalized === "G") return "group";
+  return "channel";
+}
+
+function channelChatType(kind: "dm" | "group" | "channel"): "direct" | "group" | "channel" {
+  if (kind === "dm") return "direct";
+  if (kind === "group") return "group";
+  return "channel";
+}
+
+function normalizeAllowEntry(entry: string): string {
+  const trimmed = entry.trim();
+  if (!trimmed) return "";
+  if (trimmed === "*") return "*";
+  return trimmed
+    .replace(/^(mattermost|user):/i, "")
+    .replace(/^@/, "")
+    .toLowerCase();
+}
+
+function normalizeAllowList(entries: Array<string | number>): string[] {
+  const normalized = entries
+    .map((entry) => normalizeAllowEntry(String(entry)))
+    .filter(Boolean);
+  return Array.from(new Set(normalized));
+}
+
+function isSenderAllowed(params: {
+  senderId: string;
+  senderName?: string;
+  allowFrom: string[];
+}): boolean {
+  const allowFrom = params.allowFrom;
+  if (allowFrom.length === 0) return false;
+  if (allowFrom.includes("*")) return true;
+  const normalizedSenderId = normalizeAllowEntry(params.senderId);
+  const normalizedSenderName = params.senderName ? normalizeAllowEntry(params.senderName) : "";
+  return allowFrom.some(
+    (entry) =>
+      entry === normalizedSenderId || (normalizedSenderName && entry === normalizedSenderName),
+  );
+}
+
+type MattermostMediaInfo = {
+  path: string;
+  contentType?: string;
+  kind: MediaKind;
+};
+
+function buildMattermostAttachmentPlaceholder(mediaList: MattermostMediaInfo[]): string {
+  if (mediaList.length === 0) return "";
+  if (mediaList.length === 1) {
+    const kind = mediaList[0].kind === "unknown" ? "document" : mediaList[0].kind;
+    return `<media:${kind}>`;
+  }
+  const allImages = mediaList.every((media) => media.kind === "image");
+  const label = allImages ? "image" : "file";
+  const suffix = mediaList.length === 1 ? label : `${label}s`;
+  const tag = allImages ? "<media:image>" : "<media:document>";
+  return `${tag} (${mediaList.length} ${suffix})`;
+}
+
+function buildMattermostMediaPayload(mediaList: MattermostMediaInfo[]): {
+  MediaPath?: string;
+  MediaType?: string;
+  MediaUrl?: string;
+  MediaPaths?: string[];
+  MediaUrls?: string[];
+  MediaTypes?: string[];
+} {
+  const first = mediaList[0];
+  const mediaPaths = mediaList.map((media) => media.path);
+  const mediaTypes = mediaList.map((media) => media.contentType).filter(Boolean) as string[];
+  return {
+    MediaPath: first?.path,
+    MediaType: first?.contentType,
+    MediaUrl: first?.path,
+    MediaPaths: mediaPaths.length > 0 ? mediaPaths : undefined,
+    MediaUrls: mediaPaths.length > 0 ? mediaPaths : undefined,
+    MediaTypes: mediaTypes.length > 0 ? mediaTypes : undefined,
+  };
+}
+
+function buildMattermostWsUrl(baseUrl: string): string {
+  const normalized = normalizeMattermostBaseUrl(baseUrl);
+  if (!normalized) throw new Error("Mattermost baseUrl is required");
+  const wsBase = normalized.replace(/^http/i, "ws");
+  return `${wsBase}/api/v4/websocket`;
+}
+
+export async function monitorMattermostProvider(opts: MonitorMattermostOpts = {}): Promise<void> {
+  const core = getMattermostRuntime();
+  const runtime = resolveRuntime(opts);
+  const cfg = opts.config ?? core.config.loadConfig();
+  const account = resolveMattermostAccount({
+    cfg,
+    accountId: opts.accountId,
+  });
+  const botToken = opts.botToken?.trim() || account.botToken?.trim();
+  if (!botToken) {
+    throw new Error(
+      `Mattermost bot token missing for account "${account.accountId}" (set channels.mattermost.accounts.${account.accountId}.botToken or MATTERMOST_BOT_TOKEN for default).`,
+    );
+  }
+  const baseUrl = normalizeMattermostBaseUrl(opts.baseUrl ?? account.baseUrl);
+  if (!baseUrl) {
+    throw new Error(
+      `Mattermost baseUrl missing for account "${account.accountId}" (set channels.mattermost.accounts.${account.accountId}.baseUrl or MATTERMOST_URL for default).`,
+    );
+  }
+
+  const client = createMattermostClient({ baseUrl, botToken });
+  const botUser = await fetchMattermostMe(client);
+  const botUserId = botUser.id;
+  const botUsername = botUser.username?.trim() || undefined;
+  runtime.log?.(`mattermost connected as ${botUsername ? `@${botUsername}` : botUserId}`);
+
+  const channelCache = new Map<string, { value: MattermostChannel | null; expiresAt: number }>();
+  const userCache = new Map<string, { value: MattermostUser | null; expiresAt: number }>();
+  const logger = core.logging.getChildLogger({ module: "mattermost" });
+  const logVerboseMessage = (message: string) => {
+    if (!core.logging.shouldLogVerbose()) return;
+    logger.debug?.(message);
+  };
+  const mediaMaxBytes =
+    resolveChannelMediaMaxBytes({
+      cfg,
+      resolveChannelLimitMb: () => undefined,
+      accountId: account.accountId,
+    }) ?? 8 * 1024 * 1024;
+  const historyLimit = Math.max(
+    0,
+    cfg.messages?.groupChat?.historyLimit ?? DEFAULT_GROUP_HISTORY_LIMIT,
+  );
+  const channelHistories = new Map<string, HistoryEntry[]>();
+
+  const fetchWithAuth: FetchLike = (input, init) => {
+    const headers = new Headers(init?.headers);
+    headers.set("Authorization", `Bearer ${client.token}`);
+    return fetch(input, { ...init, headers });
+  };
+
+  const resolveMattermostMedia = async (
+    fileIds?: string[] | null,
+  ): Promise<MattermostMediaInfo[]> => {
+    const ids = (fileIds ?? []).map((id) => id?.trim()).filter(Boolean) as string[];
+    if (ids.length === 0) return [];
+    const out: MattermostMediaInfo[] = [];
+    for (const fileId of ids) {
+      try {
+        const fetched = await core.channel.media.fetchRemoteMedia({
+          url: `${client.apiBaseUrl}/files/${fileId}`,
+          fetchImpl: fetchWithAuth,
+          filePathHint: fileId,
+          maxBytes: mediaMaxBytes,
+        });
+        const saved = await core.channel.media.saveMediaBuffer(
+          fetched.buffer,
+          fetched.contentType ?? undefined,
+          "inbound",
+          mediaMaxBytes,
+        );
+        const contentType = saved.contentType ?? fetched.contentType ?? undefined;
+        out.push({
+          path: saved.path,
+          contentType,
+          kind: core.media.mediaKindFromMime(contentType),
+        });
+      } catch (err) {
+        logger.debug?.(`mattermost: failed to download file ${fileId}: ${String(err)}`);
+      }
+    }
+    return out;
+  };
+
+  const sendTypingIndicator = async (channelId: string, parentId?: string) => {
+    try {
+      await sendMattermostTyping(client, { channelId, parentId });
+    } catch (err) {
+      logger.debug?.(`mattermost typing cue failed for channel ${channelId}: ${String(err)}`);
+    }
+  };
+
+  const resolveChannelInfo = async (channelId: string): Promise<MattermostChannel | null> => {
+    const cached = channelCache.get(channelId);
+    if (cached && cached.expiresAt > Date.now()) return cached.value;
+    try {
+      const info = await fetchMattermostChannel(client, channelId);
+      channelCache.set(channelId, {
+        value: info,
+        expiresAt: Date.now() + CHANNEL_CACHE_TTL_MS,
+      });
+      return info;
+    } catch (err) {
+      logger.debug?.(`mattermost: channel lookup failed: ${String(err)}`);
+      channelCache.set(channelId, {
+        value: null,
+        expiresAt: Date.now() + CHANNEL_CACHE_TTL_MS,
+      });
+      return null;
+    }
+  };
+
+  const resolveUserInfo = async (userId: string): Promise<MattermostUser | null> => {
+    const cached = userCache.get(userId);
+    if (cached && cached.expiresAt > Date.now()) return cached.value;
+    try {
+      const info = await fetchMattermostUser(client, userId);
+      userCache.set(userId, {
+        value: info,
+        expiresAt: Date.now() + USER_CACHE_TTL_MS,
+      });
+      return info;
+    } catch (err) {
+      logger.debug?.(`mattermost: user lookup failed: ${String(err)}`);
+      userCache.set(userId, {
+        value: null,
+        expiresAt: Date.now() + USER_CACHE_TTL_MS,
+      });
+      return null;
+    }
+  };
+
+  const handlePost = async (
+    post: MattermostPost,
+    payload: MattermostEventPayload,
+    messageIds?: string[],
+  ) => {
+    const channelId = post.channel_id ?? payload.data?.channel_id ?? payload.broadcast?.channel_id;
+    if (!channelId) return;
+
+    const allMessageIds = messageIds?.length ? messageIds : post.id ? [post.id] : [];
+    if (allMessageIds.length === 0) return;
+    const dedupeEntries = allMessageIds.map((id) =>
+      recentInboundMessages.check(`${account.accountId}:${id}`),
+    );
+    if (dedupeEntries.length > 0 && dedupeEntries.every(Boolean)) return;
+
+    const senderId = post.user_id ?? payload.broadcast?.user_id;
+    if (!senderId) return;
+    if (senderId === botUserId) return;
+    if (isSystemPost(post)) return;
+
+    const channelInfo = await resolveChannelInfo(channelId);
+    const channelType = payload.data?.channel_type ?? channelInfo?.type ?? undefined;
+    const kind = channelKind(channelType);
+    const chatType = channelChatType(kind);
+
+    const senderName =
+      payload.data?.sender_name?.trim() ||
+      (await resolveUserInfo(senderId))?.username?.trim() ||
+      senderId;
+    const rawText = post.message?.trim() || "";
+    const dmPolicy = account.config.dmPolicy ?? "pairing";
+    const defaultGroupPolicy = cfg.channels?.defaults?.groupPolicy;
+    const groupPolicy = account.config.groupPolicy ?? defaultGroupPolicy ?? "allowlist";
+    const configAllowFrom = normalizeAllowList(account.config.allowFrom ?? []);
+    const configGroupAllowFrom = normalizeAllowList(account.config.groupAllowFrom ?? []);
+    const storeAllowFrom = normalizeAllowList(
+      await core.channel.pairing.readAllowFromStore("mattermost").catch(() => []),
+    );
+    const effectiveAllowFrom = Array.from(new Set([...configAllowFrom, ...storeAllowFrom]));
+    const effectiveGroupAllowFrom = Array.from(
+      new Set([
+        ...(configGroupAllowFrom.length > 0 ? configGroupAllowFrom : configAllowFrom),
+        ...storeAllowFrom,
+      ]),
+    );
+    const allowTextCommands = core.channel.commands.shouldHandleTextCommands({
+      cfg,
+      surface: "mattermost",
+    });
+    const isControlCommand = allowTextCommands && core.channel.text.hasControlCommand(rawText, cfg);
+    const useAccessGroups = cfg.commands?.useAccessGroups !== false;
+    const senderAllowedForCommands = isSenderAllowed({
+      senderId,
+      senderName,
+      allowFrom: effectiveAllowFrom,
+    });
+    const groupAllowedForCommands = isSenderAllowed({
+      senderId,
+      senderName,
+      allowFrom: effectiveGroupAllowFrom,
+    });
+    const commandAuthorized =
+      kind === "dm"
+        ? dmPolicy === "open" || senderAllowedForCommands
+        : core.channel.commands.resolveCommandAuthorizedFromAuthorizers({
+            useAccessGroups,
+            authorizers: [
+              { configured: effectiveAllowFrom.length > 0, allowed: senderAllowedForCommands },
+              {
+                configured: effectiveGroupAllowFrom.length > 0,
+                allowed: groupAllowedForCommands,
+              },
+            ],
+          });
+
+    if (kind === "dm") {
+      if (dmPolicy === "disabled") {
+        logVerboseMessage(`mattermost: drop dm (dmPolicy=disabled sender=${senderId})`);
+        return;
+      }
+      if (dmPolicy !== "open" && !senderAllowedForCommands) {
+        if (dmPolicy === "pairing") {
+          const { code, created } = await core.channel.pairing.upsertPairingRequest({
+            channel: "mattermost",
+            id: senderId,
+            meta: { name: senderName },
+          });
+          logVerboseMessage(
+            `mattermost: pairing request sender=${senderId} created=${created}`,
+          );
+          if (created) {
+            try {
+              await sendMessageMattermost(
+                `user:${senderId}`,
+                core.channel.pairing.buildPairingReply({
+                  channel: "mattermost",
+                  idLine: `Your Mattermost user id: ${senderId}`,
+                  code,
+                }),
+                { accountId: account.accountId },
+              );
+              opts.statusSink?.({ lastOutboundAt: Date.now() });
+            } catch (err) {
+              logVerboseMessage(
+                `mattermost: pairing reply failed for ${senderId}: ${String(err)}`,
+              );
+            }
+          }
+        } else {
+          logVerboseMessage(
+            `mattermost: drop dm sender=${senderId} (dmPolicy=${dmPolicy})`,
+          );
+        }
+        return;
+      }
+    } else {
+      if (groupPolicy === "disabled") {
+        logVerboseMessage("mattermost: drop group message (groupPolicy=disabled)");
+        return;
+      }
+      if (groupPolicy === "allowlist") {
+        if (effectiveGroupAllowFrom.length === 0) {
+          logVerboseMessage("mattermost: drop group message (no group allowlist)");
+          return;
+        }
+        if (!groupAllowedForCommands) {
+          logVerboseMessage(
+            `mattermost: drop group sender=${senderId} (not in groupAllowFrom)`,
+          );
+          return;
+        }
+      }
+    }
+
+    if (kind !== "dm" && isControlCommand && !commandAuthorized) {
+      logVerboseMessage(
+        `mattermost: drop control command from unauthorized sender ${senderId}`,
+      );
+      return;
+    }
+
+    const teamId = payload.data?.team_id ?? channelInfo?.team_id ?? undefined;
+    const channelName = payload.data?.channel_name ?? channelInfo?.name ?? "";
+    const channelDisplay =
+      payload.data?.channel_display_name ?? channelInfo?.display_name ?? channelName;
+    const roomLabel = channelName ? `#${channelName}` : channelDisplay || `#${channelId}`;
+
+    const route = core.channel.routing.resolveAgentRoute({
+      cfg,
+      channel: "mattermost",
+      accountId: account.accountId,
+      teamId,
+      peer: {
+        kind,
+        id: kind === "dm" ? senderId : channelId,
+      },
+    });
+
+    const baseSessionKey = route.sessionKey;
+    const threadRootId = post.root_id?.trim() || undefined;
+    const threadKeys = resolveThreadSessionKeys({
+      baseSessionKey,
+      threadId: threadRootId,
+      parentSessionKey: threadRootId ? baseSessionKey : undefined,
+    });
+    const sessionKey = threadKeys.sessionKey;
+    const historyKey = kind === "dm" ? null : sessionKey;
+
+    const mentionRegexes = core.channel.mentions.buildMentionRegexes(cfg, route.agentId);
+    const wasMentioned =
+      kind !== "dm" &&
+      ((botUsername ? rawText.toLowerCase().includes(`@${botUsername.toLowerCase()}`) : false) ||
+        core.channel.mentions.matchesMentionPatterns(rawText, mentionRegexes));
+    const pendingBody =
+      rawText ||
+      (post.file_ids?.length
+        ? `[Mattermost ${post.file_ids.length === 1 ? "file" : "files"}]`
+        : "");
+    const pendingSender = senderName;
+    const recordPendingHistory = () => {
+      if (!historyKey || historyLimit <= 0) return;
+      const trimmed = pendingBody.trim();
+      if (!trimmed) return;
+      recordPendingHistoryEntry({
+        historyMap: channelHistories,
+        historyKey,
+        limit: historyLimit,
+        entry: {
+          sender: pendingSender,
+          body: trimmed,
+          timestamp: typeof post.create_at === "number" ? post.create_at : undefined,
+          messageId: post.id ?? undefined,
+        },
+      });
+    };
+
+    const oncharEnabled = account.chatmode === "onchar" && kind !== "dm";
+    const oncharPrefixes = oncharEnabled ? resolveOncharPrefixes(account.oncharPrefixes) : [];
+    const oncharResult = oncharEnabled
+      ? stripOncharPrefix(rawText, oncharPrefixes)
+      : { triggered: false, stripped: rawText };
+    const oncharTriggered = oncharResult.triggered;
+
+    const shouldRequireMention =
+      kind !== "dm" &&
+      core.channel.groups.resolveRequireMention({
+        cfg,
+        channel: "mattermost",
+        accountId: account.accountId,
+        groupId: channelId,
+      }) !== false;
+    const shouldBypassMention =
+      isControlCommand && shouldRequireMention && !wasMentioned && commandAuthorized;
+    const effectiveWasMentioned = wasMentioned || shouldBypassMention || oncharTriggered;
+    const canDetectMention = Boolean(botUsername) || mentionRegexes.length > 0;
+
+    if (oncharEnabled && !oncharTriggered && !wasMentioned && !isControlCommand) {
+      recordPendingHistory();
+      return;
+    }
+
+    if (kind !== "dm" && shouldRequireMention && canDetectMention) {
+      if (!effectiveWasMentioned) {
+        recordPendingHistory();
+        return;
+      }
+    }
+    const mediaList = await resolveMattermostMedia(post.file_ids);
+    const mediaPlaceholder = buildMattermostAttachmentPlaceholder(mediaList);
+    const bodySource = oncharTriggered ? oncharResult.stripped : rawText;
+    const baseText = [bodySource, mediaPlaceholder].filter(Boolean).join("\n").trim();
+    const bodyText = normalizeMention(baseText, botUsername);
+    if (!bodyText) return;
+
+    core.channel.activity.record({
+      channel: "mattermost",
+      accountId: account.accountId,
+      direction: "inbound",
+    });
+
+    const fromLabel = formatInboundFromLabel({
+      isGroup: kind !== "dm",
+      groupLabel: channelDisplay || roomLabel,
+      groupId: channelId,
+      groupFallback: roomLabel || "Channel",
+      directLabel: senderName,
+      directId: senderId,
+    });
+
+    const preview = bodyText.replace(/\s+/g, " ").slice(0, 160);
+    const inboundLabel =
+      kind === "dm"
+        ? `Mattermost DM from ${senderName}`
+        : `Mattermost message in ${roomLabel} from ${senderName}`;
+    core.system.enqueueSystemEvent(`${inboundLabel}: ${preview}`, {
+      sessionKey,
+      contextKey: `mattermost:message:${channelId}:${post.id ?? "unknown"}`,
+    });
+
+    const textWithId = `${bodyText}\n[mattermost message id: ${post.id ?? "unknown"} channel: ${channelId}]`;
+    const body = core.channel.reply.formatInboundEnvelope({
+      channel: "Mattermost",
+      from: fromLabel,
+      timestamp: typeof post.create_at === "number" ? post.create_at : undefined,
+      body: textWithId,
+      chatType,
+      sender: { name: senderName, id: senderId },
+    });
+    let combinedBody = body;
+    if (historyKey && historyLimit > 0) {
+      combinedBody = buildPendingHistoryContextFromMap({
+        historyMap: channelHistories,
+        historyKey,
+        limit: historyLimit,
+        currentMessage: combinedBody,
+        formatEntry: (entry) =>
+          core.channel.reply.formatInboundEnvelope({
+            channel: "Mattermost",
+            from: fromLabel,
+            timestamp: entry.timestamp,
+            body: `${entry.body}${
+              entry.messageId ? ` [id:${entry.messageId} channel:${channelId}]` : ""
+            }`,
+            chatType,
+            senderLabel: entry.sender,
+          }),
+      });
+    }
+
+    const to = kind === "dm" ? `user:${senderId}` : `channel:${channelId}`;
+    const mediaPayload = buildMattermostMediaPayload(mediaList);
+    const ctxPayload = core.channel.reply.finalizeInboundContext({
+      Body: combinedBody,
+      RawBody: bodyText,
+      CommandBody: bodyText,
+      From:
+        kind === "dm"
+          ? `mattermost:${senderId}`
+          : kind === "group"
+            ? `mattermost:group:${channelId}`
+            : `mattermost:channel:${channelId}`,
+      To: to,
+      SessionKey: sessionKey,
+      ParentSessionKey: threadKeys.parentSessionKey,
+      AccountId: route.accountId,
+      ChatType: chatType,
+      ConversationLabel: fromLabel,
+      GroupSubject: kind !== "dm" ? channelDisplay || roomLabel : undefined,
+      GroupChannel: channelName ? `#${channelName}` : undefined,
+      GroupSpace: teamId,
+      SenderName: senderName,
+      SenderId: senderId,
+      Provider: "mattermost" as const,
+      Surface: "mattermost" as const,
+      MessageSid: post.id ?? undefined,
+      MessageSids: allMessageIds.length > 1 ? allMessageIds : undefined,
+      MessageSidFirst: allMessageIds.length > 1 ? allMessageIds[0] : undefined,
+      MessageSidLast:
+        allMessageIds.length > 1 ? allMessageIds[allMessageIds.length - 1] : undefined,
+      ReplyToId: threadRootId,
+      MessageThreadId: threadRootId,
+      Timestamp: typeof post.create_at === "number" ? post.create_at : undefined,
+      WasMentioned: kind !== "dm" ? effectiveWasMentioned : undefined,
+      CommandAuthorized: commandAuthorized,
+      OriginatingChannel: "mattermost" as const,
+      OriginatingTo: to,
+      ...mediaPayload,
+    });
+
+    if (kind === "dm") {
+      const sessionCfg = cfg.session;
+      const storePath = core.channel.session.resolveStorePath(sessionCfg?.store, {
+        agentId: route.agentId,
+      });
+      await core.channel.session.updateLastRoute({
+        storePath,
+        sessionKey: route.mainSessionKey,
+        deliveryContext: {
+          channel: "mattermost",
+          to,
+          accountId: route.accountId,
+        },
+      });
+    }
+
+    const previewLine = bodyText.slice(0, 200).replace(/\n/g, "\\n");
+    logVerboseMessage(
+      `mattermost inbound: from=${ctxPayload.From} len=${bodyText.length} preview="${previewLine}"`,
+    );
+
+    const textLimit = core.channel.text.resolveTextChunkLimit(cfg, "mattermost", account.accountId, {
+      fallbackLimit: account.textChunkLimit ?? 4000,
+    });
+
+    let prefixContext: ResponsePrefixContext = {
+      identityName: resolveIdentityName(cfg, route.agentId),
+    };
+
+    const { dispatcher, replyOptions, markDispatchIdle } =
+      core.channel.reply.createReplyDispatcherWithTyping({
+        responsePrefix: core.channel.reply.resolveEffectiveMessagesConfig(cfg, route.agentId)
+          .responsePrefix,
+        responsePrefixContextProvider: () => prefixContext,
+        humanDelay: core.channel.reply.resolveHumanDelayConfig(cfg, route.agentId),
+        deliver: async (payload: ReplyPayload) => {
+          const mediaUrls = payload.mediaUrls ?? (payload.mediaUrl ? [payload.mediaUrl] : []);
+          const text = payload.text ?? "";
+          if (mediaUrls.length === 0) {
+            const chunks = core.channel.text.chunkMarkdownText(text, textLimit);
+            for (const chunk of chunks.length > 0 ? chunks : [text]) {
+              if (!chunk) continue;
+              await sendMessageMattermost(to, chunk, {
+                accountId: account.accountId,
+                replyToId: threadRootId,
+              });
+            }
+          } else {
+            let first = true;
+            for (const mediaUrl of mediaUrls) {
+              const caption = first ? text : "";
+              first = false;
+              await sendMessageMattermost(to, caption, {
+                accountId: account.accountId,
+                mediaUrl,
+                replyToId: threadRootId,
+              });
+            }
+          }
+          runtime.log?.(`delivered reply to ${to}`);
+        },
+        onError: (err, info) => {
+          runtime.error?.(`mattermost ${info.kind} reply failed: ${String(err)}`);
+        },
+        onReplyStart: () => sendTypingIndicator(channelId, threadRootId),
+      });
+
+    await core.channel.reply.dispatchReplyFromConfig({
+      ctx: ctxPayload,
+      cfg,
+      dispatcher,
+      replyOptions: {
+        ...replyOptions,
+        disableBlockStreaming:
+          typeof account.blockStreaming === "boolean" ? !account.blockStreaming : undefined,
+        onModelSelected: (ctx) => {
+          prefixContext.provider = ctx.provider;
+          prefixContext.model = extractShortModelName(ctx.model);
+          prefixContext.modelFull = `${ctx.provider}/${ctx.model}`;
+          prefixContext.thinkingLevel = ctx.thinkLevel ?? "off";
+        },
+      },
+    });
+    markDispatchIdle();
+    if (historyKey && historyLimit > 0) {
+      clearHistoryEntries({ historyMap: channelHistories, historyKey });
+    }
+  };
+
+  const inboundDebounceMs = core.channel.debounce.resolveInboundDebounceMs({
+    cfg,
+    channel: "mattermost",
+  });
+  const debouncer = core.channel.debounce.createInboundDebouncer<{
+    post: MattermostPost;
+    payload: MattermostEventPayload;
+  }>({
+    debounceMs: inboundDebounceMs,
+    buildKey: (entry) => {
+      const channelId =
+        entry.post.channel_id ??
+        entry.payload.data?.channel_id ??
+        entry.payload.broadcast?.channel_id;
+      if (!channelId) return null;
+      const threadId = entry.post.root_id?.trim();
+      const threadKey = threadId ? `thread:${threadId}` : "channel";
+      return `mattermost:${account.accountId}:${channelId}:${threadKey}`;
+    },
+    shouldDebounce: (entry) => {
+      if (entry.post.file_ids && entry.post.file_ids.length > 0) return false;
+      const text = entry.post.message?.trim() ?? "";
+      if (!text) return false;
+      return !core.channel.text.hasControlCommand(text, cfg);
+    },
+    onFlush: async (entries) => {
+      const last = entries.at(-1);
+      if (!last) return;
+      if (entries.length === 1) {
+        await handlePost(last.post, last.payload);
+        return;
+      }
+      const combinedText = entries
+        .map((entry) => entry.post.message?.trim() ?? "")
+        .filter(Boolean)
+        .join("\n");
+      const mergedPost: MattermostPost = {
+        ...last.post,
+        message: combinedText,
+        file_ids: [],
+      };
+      const ids = entries.map((entry) => entry.post.id).filter(Boolean) as string[];
+      await handlePost(mergedPost, last.payload, ids.length > 0 ? ids : undefined);
+    },
+    onError: (err) => {
+      runtime.error?.(`mattermost debounce flush failed: ${String(err)}`);
+    },
+  });
+
+  const wsUrl = buildMattermostWsUrl(baseUrl);
+  let seq = 1;
+
+  const connectOnce = async (): Promise<void> => {
+    const ws = new WebSocket(wsUrl);
+    const onAbort = () => ws.close();
+    opts.abortSignal?.addEventListener("abort", onAbort, { once: true });
+
+    return await new Promise((resolve) => {
+      ws.on("open", () => {
+        opts.statusSink?.({
+          connected: true,
+          lastConnectedAt: Date.now(),
+          lastError: null,
+        });
+        ws.send(
+          JSON.stringify({
+            seq: seq++,
+            action: "authentication_challenge",
+            data: { token: botToken },
+          }),
+        );
+      });
+
+      ws.on("message", async (data) => {
+        const raw = rawDataToString(data);
+        let payload: MattermostEventPayload;
+        try {
+          payload = JSON.parse(raw) as MattermostEventPayload;
+        } catch {
+          return;
+        }
+        if (payload.event !== "posted") return;
+        const postData = payload.data?.post;
+        if (!postData) return;
+        let post: MattermostPost | null = null;
+        if (typeof postData === "string") {
+          try {
+            post = JSON.parse(postData) as MattermostPost;
+          } catch {
+            return;
+          }
+        } else if (typeof postData === "object") {
+          post = postData as MattermostPost;
+        }
+        if (!post) return;
+        try {
+          await debouncer.enqueue({ post, payload });
+        } catch (err) {
+          runtime.error?.(`mattermost handler failed: ${String(err)}`);
+        }
+      });
+
+      ws.on("close", (code, reason) => {
+        const message = reason.length > 0 ? reason.toString("utf8") : "";
+        opts.statusSink?.({
+          connected: false,
+          lastDisconnect: {
+            at: Date.now(),
+            status: code,
+            error: message || undefined,
+          },
+        });
+        opts.abortSignal?.removeEventListener("abort", onAbort);
+        resolve();
+      });
+
+      ws.on("error", (err) => {
+        runtime.error?.(`mattermost websocket error: ${String(err)}`);
+        opts.statusSink?.({
+          lastError: String(err),
+        });
+      });
+    });
+  };
+
+  while (!opts.abortSignal?.aborted) {
+    await connectOnce();
+    if (opts.abortSignal?.aborted) return;
+    await new Promise((resolve) => setTimeout(resolve, 2000));
+  }
+}
@@ -0,0 +1,70 @@
+import { normalizeMattermostBaseUrl, type MattermostUser } from "./client.js";
+
+export type MattermostProbe = {
+  ok: boolean;
+  status?: number | null;
+  error?: string | null;
+  elapsedMs?: number | null;
+  bot?: MattermostUser;
+};
+
+async function readMattermostError(res: Response): Promise<string> {
+  const contentType = res.headers.get("content-type") ?? "";
+  if (contentType.includes("application/json")) {
+    const data = (await res.json()) as { message?: string } | undefined;
+    if (data?.message) return data.message;
+    return JSON.stringify(data);
+  }
+  return await res.text();
+}
+
+export async function probeMattermost(
+  baseUrl: string,
+  botToken: string,
+  timeoutMs = 2500,
+): Promise<MattermostProbe> {
+  const normalized = normalizeMattermostBaseUrl(baseUrl);
+  if (!normalized) {
+    return { ok: false, error: "baseUrl missing" };
+  }
+  const url = `${normalized}/api/v4/users/me`;
+  const start = Date.now();
+  const controller = timeoutMs > 0 ? new AbortController() : undefined;
+  let timer: NodeJS.Timeout | null = null;
+  if (controller) {
+    timer = setTimeout(() => controller.abort(), timeoutMs);
+  }
+  try {
+    const res = await fetch(url, {
+      headers: { Authorization: `Bearer ${botToken}` },
+      signal: controller?.signal,
+    });
+    const elapsedMs = Date.now() - start;
+    if (!res.ok) {
+      const detail = await readMattermostError(res);
+      return {
+        ok: false,
+        status: res.status,
+        error: detail || res.statusText,
+        elapsedMs,
+      };
+    }
+    const bot = (await res.json()) as MattermostUser;
+    return {
+      ok: true,
+      status: res.status,
+      elapsedMs,
+      bot,
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      ok: false,
+      status: null,
+      error: message,
+      elapsedMs: Date.now() - start,
+    };
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
@@ -0,0 +1,208 @@
+import { getMattermostRuntime } from "../runtime.js";
+import { resolveMattermostAccount } from "./accounts.js";
+import {
+  createMattermostClient,
+  createMattermostDirectChannel,
+  createMattermostPost,
+  fetchMattermostMe,
+  fetchMattermostUserByUsername,
+  normalizeMattermostBaseUrl,
+  uploadMattermostFile,
+  type MattermostUser,
+} from "./client.js";
+
+export type MattermostSendOpts = {
+  botToken?: string;
+  baseUrl?: string;
+  accountId?: string;
+  mediaUrl?: string;
+  replyToId?: string;
+};
+
+export type MattermostSendResult = {
+  messageId: string;
+  channelId: string;
+};
+
+type MattermostTarget =
+  | { kind: "channel"; id: string }
+  | { kind: "user"; id?: string; username?: string };
+
+const botUserCache = new Map<string, MattermostUser>();
+const userByNameCache = new Map<string, MattermostUser>();
+
+const getCore = () => getMattermostRuntime();
+
+function cacheKey(baseUrl: string, token: string): string {
+  return `${baseUrl}::${token}`;
+}
+
+function normalizeMessage(text: string, mediaUrl?: string): string {
+  const trimmed = text.trim();
+  const media = mediaUrl?.trim();
+  return [trimmed, media].filter(Boolean).join("\n");
+}
+
+function isHttpUrl(value: string): boolean {
+  return /^https?:\/\//i.test(value);
+}
+
+function parseMattermostTarget(raw: string): MattermostTarget {
+  const trimmed = raw.trim();
+  if (!trimmed) throw new Error("Recipient is required for Mattermost sends");
+  const lower = trimmed.toLowerCase();
+  if (lower.startsWith("channel:")) {
+    const id = trimmed.slice("channel:".length).trim();
+    if (!id) throw new Error("Channel id is required for Mattermost sends");
+    return { kind: "channel", id };
+  }
+  if (lower.startsWith("user:")) {
+    const id = trimmed.slice("user:".length).trim();
+    if (!id) throw new Error("User id is required for Mattermost sends");
+    return { kind: "user", id };
+  }
+  if (lower.startsWith("mattermost:")) {
+    const id = trimmed.slice("mattermost:".length).trim();
+    if (!id) throw new Error("User id is required for Mattermost sends");
+    return { kind: "user", id };
+  }
+  if (trimmed.startsWith("@")) {
+    const username = trimmed.slice(1).trim();
+    if (!username) {
+      throw new Error("Username is required for Mattermost sends");
+    }
+    return { kind: "user", username };
+  }
+  return { kind: "channel", id: trimmed };
+}
+
+async function resolveBotUser(baseUrl: string, token: string): Promise<MattermostUser> {
+  const key = cacheKey(baseUrl, token);
+  const cached = botUserCache.get(key);
+  if (cached) return cached;
+  const client = createMattermostClient({ baseUrl, botToken: token });
+  const user = await fetchMattermostMe(client);
+  botUserCache.set(key, user);
+  return user;
+}
+
+async function resolveUserIdByUsername(params: {
+  baseUrl: string;
+  token: string;
+  username: string;
+}): Promise<string> {
+  const { baseUrl, token, username } = params;
+  const key = `${cacheKey(baseUrl, token)}::${username.toLowerCase()}`;
+  const cached = userByNameCache.get(key);
+  if (cached?.id) return cached.id;
+  const client = createMattermostClient({ baseUrl, botToken: token });
+  const user = await fetchMattermostUserByUsername(client, username);
+  userByNameCache.set(key, user);
+  return user.id;
+}
+
+async function resolveTargetChannelId(params: {
+  target: MattermostTarget;
+  baseUrl: string;
+  token: string;
+}): Promise<string> {
+  if (params.target.kind === "channel") return params.target.id;
+  const userId = params.target.id
+    ? params.target.id
+    : await resolveUserIdByUsername({
+        baseUrl: params.baseUrl,
+        token: params.token,
+        username: params.target.username ?? "",
+      });
+  const botUser = await resolveBotUser(params.baseUrl, params.token);
+  const client = createMattermostClient({
+    baseUrl: params.baseUrl,
+    botToken: params.token,
+  });
+  const channel = await createMattermostDirectChannel(client, [botUser.id, userId]);
+  return channel.id;
+}
+
+export async function sendMessageMattermost(
+  to: string,
+  text: string,
+  opts: MattermostSendOpts = {},
+): Promise<MattermostSendResult> {
+  const core = getCore();
+  const logger = core.logging.getChildLogger({ module: "mattermost" });
+  const cfg = core.config.loadConfig();
+  const account = resolveMattermostAccount({
+    cfg,
+    accountId: opts.accountId,
+  });
+  const token = opts.botToken?.trim() || account.botToken?.trim();
+  if (!token) {
+    throw new Error(
+      `Mattermost bot token missing for account "${account.accountId}" (set channels.mattermost.accounts.${account.accountId}.botToken or MATTERMOST_BOT_TOKEN for default).`,
+    );
+  }
+  const baseUrl = normalizeMattermostBaseUrl(opts.baseUrl ?? account.baseUrl);
+  if (!baseUrl) {
+    throw new Error(
+      `Mattermost baseUrl missing for account "${account.accountId}" (set channels.mattermost.accounts.${account.accountId}.baseUrl or MATTERMOST_URL for default).`,
+    );
+  }
+
+  const target = parseMattermostTarget(to);
+  const channelId = await resolveTargetChannelId({
+    target,
+    baseUrl,
+    token,
+  });
+
+  const client = createMattermostClient({ baseUrl, botToken: token });
+  let message = text?.trim() ?? "";
+  let fileIds: string[] | undefined;
+  let uploadError: Error | undefined;
+  const mediaUrl = opts.mediaUrl?.trim();
+  if (mediaUrl) {
+    try {
+      const media = await core.media.loadWebMedia(mediaUrl);
+      const fileInfo = await uploadMattermostFile(client, {
+        channelId,
+        buffer: media.buffer,
+        fileName: media.fileName ?? "upload",
+        contentType: media.contentType ?? undefined,
+      });
+      fileIds = [fileInfo.id];
+    } catch (err) {
+      uploadError = err instanceof Error ? err : new Error(String(err));
+      if (core.logging.shouldLogVerbose()) {
+        logger.debug?.(
+          `mattermost send: media upload failed, falling back to URL text: ${String(err)}`,
+        );
+      }
+      message = normalizeMessage(message, isHttpUrl(mediaUrl) ? mediaUrl : "");
+    }
+  }
+
+  if (!message && (!fileIds || fileIds.length === 0)) {
+    if (uploadError) {
+      throw new Error(`Mattermost media upload failed: ${uploadError.message}`);
+    }
+    throw new Error("Mattermost message is empty");
+  }
+
+  const post = await createMattermostPost(client, {
+    channelId,
+    message,
+    rootId: opts.replyToId,
+    fileIds,
+  });
+
+  core.channel.activity.record({
+    channel: "mattermost",
+    accountId: account.accountId,
+    direction: "outbound",
+  });
+
+  return {
+    messageId: post.id ?? "unknown",
+    channelId,
+  };
+}
@@ -0,0 +1,38 @@
+export function normalizeMattermostMessagingTarget(raw: string): string | undefined {
+  const trimmed = raw.trim();
+  if (!trimmed) return undefined;
+  const lower = trimmed.toLowerCase();
+  if (lower.startsWith("channel:")) {
+    const id = trimmed.slice("channel:".length).trim();
+    return id ? `channel:${id}` : undefined;
+  }
+  if (lower.startsWith("group:")) {
+    const id = trimmed.slice("group:".length).trim();
+    return id ? `channel:${id}` : undefined;
+  }
+  if (lower.startsWith("user:")) {
+    const id = trimmed.slice("user:".length).trim();
+    return id ? `user:${id}` : undefined;
+  }
+  if (lower.startsWith("mattermost:")) {
+    const id = trimmed.slice("mattermost:".length).trim();
+    return id ? `user:${id}` : undefined;
+  }
+  if (trimmed.startsWith("@")) {
+    const id = trimmed.slice(1).trim();
+    return id ? `@${id}` : undefined;
+  }
+  if (trimmed.startsWith("#")) {
+    const id = trimmed.slice(1).trim();
+    return id ? `channel:${id}` : undefined;
+  }
+  return `channel:${trimmed}`;
+}
+
+export function looksLikeMattermostTargetId(raw: string): boolean {
+  const trimmed = raw.trim();
+  if (!trimmed) return false;
+  if (/^(user|channel|group|mattermost):/i.test(trimmed)) return true;
+  if (/^[@#]/.test(trimmed)) return true;
+  return /^[a-z0-9]{8,}$/i.test(trimmed);
+}
@@ -0,0 +1,42 @@
+import type { ClawdbotConfig, WizardPrompter } from "clawdbot/plugin-sdk";
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "clawdbot/plugin-sdk";
+
+type PromptAccountIdParams = {
+  cfg: ClawdbotConfig;
+  prompter: WizardPrompter;
+  label: string;
+  currentId?: string;
+  listAccountIds: (cfg: ClawdbotConfig) => string[];
+  defaultAccountId: string;
+};
+
+export async function promptAccountId(params: PromptAccountIdParams): Promise<string> {
+  const existingIds = params.listAccountIds(params.cfg);
+  const initial = params.currentId?.trim() || params.defaultAccountId || DEFAULT_ACCOUNT_ID;
+  const choice = (await params.prompter.select({
+    message: `${params.label} account`,
+    options: [
+      ...existingIds.map((id) => ({
+        value: id,
+        label: id === DEFAULT_ACCOUNT_ID ? "default (primary)" : id,
+      })),
+      { value: "__new__", label: "Add a new account" },
+    ],
+    initialValue: initial,
+  })) as string;
+
+  if (choice !== "__new__") return normalizeAccountId(choice);
+
+  const entered = await params.prompter.text({
+    message: `New ${params.label} account id`,
+    validate: (value) => (value?.trim() ? undefined : "Required"),
+  });
+  const normalized = normalizeAccountId(String(entered));
+  if (String(entered).trim() !== normalized) {
+    await params.prompter.note(
+      `Normalized account id to "${normalized}".`,
+      `${params.label} account`,
+    );
+  }
+  return normalized;
+}
@@ -0,0 +1,187 @@
+import type { ChannelOnboardingAdapter, ClawdbotConfig, WizardPrompter } from "clawdbot/plugin-sdk";
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "clawdbot/plugin-sdk";
+
+import {
+  listMattermostAccountIds,
+  resolveDefaultMattermostAccountId,
+  resolveMattermostAccount,
+} from "./mattermost/accounts.js";
+import { promptAccountId } from "./onboarding-helpers.js";
+
+const channel = "mattermost" as const;
+
+async function noteMattermostSetup(prompter: WizardPrompter): Promise<void> {
+  await prompter.note(
+    [
+      "1) Mattermost System Console -> Integrations -> Bot Accounts",
+      "2) Create a bot + copy its token",
+      "3) Use your server base URL (e.g., https://chat.example.com)",
+      "Tip: the bot must be a member of any channel you want it to monitor.",
+      "Docs: https://docs.clawd.bot/channels/mattermost",
+    ].join("\n"),
+    "Mattermost bot token",
+  );
+}
+
+export const mattermostOnboardingAdapter: ChannelOnboardingAdapter = {
+  channel,
+  getStatus: async ({ cfg }) => {
+    const configured = listMattermostAccountIds(cfg).some((accountId) => {
+      const account = resolveMattermostAccount({ cfg, accountId });
+      return Boolean(account.botToken && account.baseUrl);
+    });
+    return {
+      channel,
+      configured,
+      statusLines: [`Mattermost: ${configured ? "configured" : "needs token + url"}`],
+      selectionHint: configured ? "configured" : "needs setup",
+      quickstartScore: configured ? 2 : 1,
+    };
+  },
+  configure: async ({ cfg, prompter, accountOverrides, shouldPromptAccountIds }) => {
+    const override = accountOverrides.mattermost?.trim();
+    const defaultAccountId = resolveDefaultMattermostAccountId(cfg);
+    let accountId = override ? normalizeAccountId(override) : defaultAccountId;
+    if (shouldPromptAccountIds && !override) {
+      accountId = await promptAccountId({
+        cfg,
+        prompter,
+        label: "Mattermost",
+        currentId: accountId,
+        listAccountIds: listMattermostAccountIds,
+        defaultAccountId,
+      });
+    }
+
+    let next = cfg;
+    const resolvedAccount = resolveMattermostAccount({
+      cfg: next,
+      accountId,
+    });
+    const accountConfigured = Boolean(resolvedAccount.botToken && resolvedAccount.baseUrl);
+    const allowEnv = accountId === DEFAULT_ACCOUNT_ID;
+    const canUseEnv =
+      allowEnv &&
+      Boolean(process.env.MATTERMOST_BOT_TOKEN?.trim()) &&
+      Boolean(process.env.MATTERMOST_URL?.trim());
+    const hasConfigValues =
+      Boolean(resolvedAccount.config.botToken) || Boolean(resolvedAccount.config.baseUrl);
+
+    let botToken: string | null = null;
+    let baseUrl: string | null = null;
+
+    if (!accountConfigured) {
+      await noteMattermostSetup(prompter);
+    }
+
+    if (canUseEnv && !hasConfigValues) {
+      const keepEnv = await prompter.confirm({
+        message: "MATTERMOST_BOT_TOKEN + MATTERMOST_URL detected. Use env vars?",
+        initialValue: true,
+      });
+      if (keepEnv) {
+        next = {
+          ...next,
+          channels: {
+            ...next.channels,
+            mattermost: {
+              ...next.channels?.mattermost,
+              enabled: true,
+            },
+          },
+        };
+      } else {
+        botToken = String(
+          await prompter.text({
+            message: "Enter Mattermost bot token",
+            validate: (value) => (value?.trim() ? undefined : "Required"),
+          }),
+        ).trim();
+        baseUrl = String(
+          await prompter.text({
+            message: "Enter Mattermost base URL",
+            validate: (value) => (value?.trim() ? undefined : "Required"),
+          }),
+        ).trim();
+      }
+    } else if (accountConfigured) {
+      const keep = await prompter.confirm({
+        message: "Mattermost credentials already configured. Keep them?",
+        initialValue: true,
+      });
+      if (!keep) {
+        botToken = String(
+          await prompter.text({
+            message: "Enter Mattermost bot token",
+            validate: (value) => (value?.trim() ? undefined : "Required"),
+          }),
+        ).trim();
+        baseUrl = String(
+          await prompter.text({
+            message: "Enter Mattermost base URL",
+            validate: (value) => (value?.trim() ? undefined : "Required"),
+          }),
+        ).trim();
+      }
+    } else {
+      botToken = String(
+        await prompter.text({
+          message: "Enter Mattermost bot token",
+          validate: (value) => (value?.trim() ? undefined : "Required"),
+        }),
+      ).trim();
+      baseUrl = String(
+        await prompter.text({
+          message: "Enter Mattermost base URL",
+          validate: (value) => (value?.trim() ? undefined : "Required"),
+        }),
+      ).trim();
+    }
+
+    if (botToken || baseUrl) {
+      if (accountId === DEFAULT_ACCOUNT_ID) {
+        next = {
+          ...next,
+          channels: {
+            ...next.channels,
+            mattermost: {
+              ...next.channels?.mattermost,
+              enabled: true,
+              ...(botToken ? { botToken } : {}),
+              ...(baseUrl ? { baseUrl } : {}),
+            },
+          },
+        };
+      } else {
+        next = {
+          ...next,
+          channels: {
+            ...next.channels,
+            mattermost: {
+              ...next.channels?.mattermost,
+              enabled: true,
+              accounts: {
+                ...next.channels?.mattermost?.accounts,
+                [accountId]: {
+                  ...next.channels?.mattermost?.accounts?.[accountId],
+                  enabled: next.channels?.mattermost?.accounts?.[accountId]?.enabled ?? true,
+                  ...(botToken ? { botToken } : {}),
+                  ...(baseUrl ? { baseUrl } : {}),
+                },
+              },
+            },
+          },
+        };
+      }
+    }
+
+    return { cfg: next, accountId };
+  },
+  disable: (cfg: ClawdbotConfig) => ({
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      mattermost: { ...cfg.channels?.mattermost, enabled: false },
+    },
+  }),
+};
@@ -0,0 +1,14 @@
+import type { PluginRuntime } from "clawdbot/plugin-sdk";
+
+let runtime: PluginRuntime | null = null;
+
+export function setMattermostRuntime(next: PluginRuntime) {
+  runtime = next;
+}
+
+export function getMattermostRuntime(): PluginRuntime {
+  if (!runtime) {
+    throw new Error("Mattermost runtime not initialized");
+  }
+  return runtime;
+}
@@ -0,0 +1,48 @@
+import type { BlockStreamingCoalesceConfig, DmPolicy, GroupPolicy } from "clawdbot/plugin-sdk";
+
+export type MattermostChatMode = "oncall" | "onmessage" | "onchar";
+
+export type MattermostAccountConfig = {
+  /** Optional display name for this account (used in CLI/UI lists). */
+  name?: string;
+  /** Optional provider capability tags used for agent/runtime guidance. */
+  capabilities?: string[];
+  /** Allow channel-initiated config writes (default: true). */
+  configWrites?: boolean;
+  /** If false, do not start this Mattermost account. Default: true. */
+  enabled?: boolean;
+  /** Bot token for Mattermost. */
+  botToken?: string;
+  /** Base URL for the Mattermost server (e.g., https://chat.example.com). */
+  baseUrl?: string;
+  /**
+   * Controls when channel messages trigger replies.
+   * - "oncall": only respond when mentioned
+   * - "onmessage": respond to every channel message
+   * - "onchar": respond when a trigger character prefixes the message
+   */
+  chatmode?: MattermostChatMode;
+  /** Prefix characters that trigger onchar mode (default: [">", "!"]). */
+  oncharPrefixes?: string[];
+  /** Require @mention to respond in channels. Default: true. */
+  requireMention?: boolean;
+  /** Direct message policy (pairing/allowlist/open/disabled). */
+  dmPolicy?: DmPolicy;
+  /** Allowlist for direct messages (user ids or @usernames). */
+  allowFrom?: Array<string | number>;
+  /** Allowlist for group messages (user ids or @usernames). */
+  groupAllowFrom?: Array<string | number>;
+  /** Group message policy (allowlist/open/disabled). */
+  groupPolicy?: GroupPolicy;
+  /** Outbound text chunk size (chars). Default: 4000. */
+  textChunkLimit?: number;
+  /** Disable block streaming for this account. */
+  blockStreaming?: boolean;
+  /** Merge streamed block replies before sending. */
+  blockStreamingCoalesce?: BlockStreamingCoalesceConfig;
+};
+
+export type MattermostConfig = {
+  /** Optional per-account Mattermost configuration (multi-account). */
+  accounts?: Record<string, MattermostAccountConfig>;
+} & MattermostAccountConfig;
@@ -0,0 +1,25 @@
+# OpenProse (plugin)
+
+Adds the OpenProse skill pack and `/prose` slash command.
+
+## Enable
+
+Bundled plugins are disabled by default. Enable this one:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "open-prose": { "enabled": true }
+    }
+  }
+}
+```
+
+Restart the Gateway after enabling.
+
+## What you get
+
+- `/prose` slash command (user-invocable skill)
+- OpenProse VM semantics (`.prose` programs + multi-agent orchestration)
+- Telemetry support (best-effort, per OpenProse spec)
@@ -0,0 +1,11 @@
+{
+  "id": "open-prose",
+  "name": "OpenProse",
+  "description": "OpenProse VM skill pack with a /prose slash command.",
+  "skills": ["./skills"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}
@@ -0,0 +1,5 @@
+import type { ClawdbotPluginApi } from "../../src/plugins/types.js";
+
+export default function register(_api: ClawdbotPluginApi) {
+  // OpenProse is delivered via plugin-shipped skills.
+}
@@ -0,0 +1,9 @@
+{
+  "name": "@clawdbot/open-prose",
+  "version": "2026.1.23",
+  "type": "module",
+  "description": "OpenProse VM skill pack plugin (slash command + telemetry).",
+  "clawdbot": {
+    "extensions": ["./index.ts"]
+  }
+}
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 OpenProse
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
@@ -0,0 +1,318 @@
+---
+name: prose
+description: OpenProse VM skill pack. Activate on any `prose` command, .prose files, or OpenProse mentions; orchestrates multi-agent workflows.
+metadata: {"clawdbot":{"emoji":"🪶","homepage":"https://www.prose.md"}}
+---
+
+# OpenProse Skill
+
+OpenProse is a programming language for AI sessions. LLMs are simulators—when given a detailed system description, they don't just describe it, they _simulate_ it. The `prose.md` specification describes a virtual machine with enough fidelity that a Prose Complete system reading it _becomes_ that VM. Simulation with sufficient fidelity is implementation. **You are the Prose Complete system.**
+
+## Clawdbot Runtime Mapping
+
+- **Task tool** in the upstream spec == Clawdbot `sessions_spawn`
+- **File I/O** == Clawdbot `read`/`write`
+- **Remote fetch** == Clawdbot `web_fetch` (or `exec` with curl when POST is required)
+
+## When to Activate
+
+Activate this skill when the user:
+
+- **Uses ANY `prose` command** (e.g., `prose boot`, `prose run`, `prose compile`, `prose update`, `prose help`, etc.)
+- Asks to run a `.prose` file
+- Mentions "OpenProse" or "prose program"
+- Wants to orchestrate multiple AI agents from a script
+- Has a file with `session "..."` or `agent name:` syntax
+- Wants to create a reusable workflow
+
+## Command Routing
+
+When a user invokes `prose <command>`, intelligently route based on intent:
+
+| Command | Action |
+|---------|--------|
+| `prose help` | Load `help.md`, guide user to what they need |
+| `prose run <file>` | Load VM (`prose.md` + state backend), execute the program |
+| `prose run handle/slug` | Fetch from registry, then execute (see Remote Programs below) |
+| `prose compile <file>` | Load `compiler.md`, validate the program |
+| `prose update` | Run migration (see Migration section below) |
+| `prose examples` | Show or run example programs from `examples/` |
+| Other | Intelligently interpret based on context |
+
+### Important: Single Skill
+
+There is only ONE skill: `open-prose`. There are NO separate skills like `prose-run`, `prose-compile`, or `prose-boot`. All `prose` commands route through this single skill.
+
+### Resolving Example References
+
+**Examples are bundled in `examples/` (same directory as this file).** When users reference examples by name (e.g., "run the gastown example"):
+
+1. Read `examples/` to list available files
+2. Match by partial name, keyword, or number
+3. Run with: `prose run examples/28-gas-town.prose`
+
+**Common examples by keyword:**
+| Keyword | File |
+|---------|------|
+| hello, hello world | `examples/01-hello-world.prose` |
+| gas town, gastown | `examples/28-gas-town.prose` |
+| captain, chair | `examples/29-captains-chair.prose` |
+| forge, browser | `examples/37-the-forge.prose` |
+| parallel | `examples/16-parallel-reviews.prose` |
+| pipeline | `examples/21-pipeline-operations.prose` |
+| error, retry | `examples/22-error-handling.prose` |
+
+### Remote Programs
+
+You can run any `.prose` program from a URL or registry reference:
+
+```bash
+# Direct URL — any fetchable URL works
+prose run https://raw.githubusercontent.com/openprose/prose/main/skills/open-prose/examples/48-habit-miner.prose
+
+# Registry shorthand — handle/slug resolves to p.prose.md
+prose run irl-danb/habit-miner
+prose run alice/code-review
+```
+
+**Resolution rules:**
+
+| Input | Resolution |
+|-------|------------|
+| Starts with `http://` or `https://` | Fetch directly from URL |
+| Contains `/` but no protocol | Resolve to `https://p.prose.md/{path}` |
+| Otherwise | Treat as local file path |
+
+**Steps for remote programs:**
+
+1. Apply resolution rules above
+2. Fetch the `.prose` content
+3. Load the VM and execute as normal
+
+This same resolution applies to `use` statements inside `.prose` files:
+
+```prose
+use "https://example.com/my-program.prose"  # Direct URL
+use "alice/research" as research             # Registry shorthand
+```
+
+---
+
+## File Locations
+
+**Do NOT search for OpenProse documentation files.** All skill files are co-located with this SKILL.md file:
+
+| File                      | Location                    | Purpose                                   |
+| ------------------------- | --------------------------- | ----------------------------------------- |
+| `prose.md`                | Same directory as this file | VM semantics (load to run programs)       |
+| `help.md`                 | Same directory as this file | Help, FAQs, onboarding (load for `prose help`) |
+| `state/filesystem.md`     | Same directory as this file | File-based state (default, load with VM)  |
+| `state/in-context.md`     | Same directory as this file | In-context state (on request)             |
+| `state/sqlite.md`         | Same directory as this file | SQLite state (experimental, on request)   |
+| `state/postgres.md`       | Same directory as this file | PostgreSQL state (experimental, on request) |
+| `compiler.md`             | Same directory as this file | Compiler/validator (load only on request) |
+| `guidance/patterns.md`    | Same directory as this file | Best practices (load when writing .prose) |
+| `guidance/antipatterns.md`| Same directory as this file | What to avoid (load when writing .prose)  |
+| `examples/`               | Same directory as this file | 37 example programs                       |
+
+**User workspace files** (these ARE in the user's project):
+
+| File/Directory   | Location                 | Purpose                             |
+| ---------------- | ------------------------ | ----------------------------------- |
+| `.prose/.env`    | User's working directory | Config (key=value format) |
+| `.prose/runs/`   | User's working directory | Runtime state for file-based mode   |
+| `.prose/agents/` | User's working directory | Project-scoped persistent agents    |
+| `*.prose` files  | User's project           | User-created programs to execute    |
+
+**User-level files** (in user's home directory, shared across all projects):
+
+| File/Directory    | Location         | Purpose                                  |
+| ----------------- | ---------------- | ---------------------------------------- |
+| `~/.prose/agents/`| User's home dir  | User-scoped persistent agents (cross-project) |
+
+When you need to read `prose.md` or `compiler.md`, read them from the same directory where you found this SKILL.md file. Never search the user's workspace for these files.
+
+---
+
+## Core Documentation
+
+| File                  | Purpose              | When to Load                                   |
+| --------------------- | -------------------- | ---------------------------------------------- |
+| `prose.md`            | VM / Interpreter     | Always load to run programs                    |
+| `state/filesystem.md` | File-based state     | Load with VM (default)                         |
+| `state/in-context.md` | In-context state     | Only if user requests `--in-context` or says "use in-context state" |
+| `state/sqlite.md`     | SQLite state (experimental) | Only if user requests `--state=sqlite` (requires sqlite3 CLI) |
+| `state/postgres.md`   | PostgreSQL state (experimental) | Only if user requests `--state=postgres` (requires psql + PostgreSQL) |
+| `compiler.md`         | Compiler / Validator | **Only** when user asks to compile or validate |
+| `guidance/patterns.md` | Best practices      | Load when **writing** new .prose files         |
+| `guidance/antipatterns.md` | What to avoid  | Load when **writing** new .prose files         |
+
+### Authoring Guidance
+
+When the user asks you to **write or create** a new `.prose` file, load the guidance files:
+- `guidance/patterns.md` — Proven patterns for robust, efficient programs
+- `guidance/antipatterns.md` — Common mistakes to avoid
+
+Do **not** load these when running or compiling—they're for authoring only.
+
+### State Modes
+
+OpenProse supports three state management approaches:
+
+| Mode | When to Use | State Location |
+|------|-------------|----------------|
+| **filesystem** (default) | Complex programs, resumption needed, debugging | `.prose/runs/{id}/` files |
+| **in-context** | Simple programs (<30 statements), no persistence needed | Conversation history |
+| **sqlite** (experimental) | Queryable state, atomic transactions, flexible schema | `.prose/runs/{id}/state.db` |
+| **postgres** (experimental) | True concurrent writes, external integrations, team collaboration | PostgreSQL database |
+
+**Default behavior:** When loading `prose.md`, also load `state/filesystem.md`. This is the recommended mode for most programs.
+
+**Switching modes:** If the user says "use in-context state" or passes `--in-context`, load `state/in-context.md` instead.
+
+**Experimental SQLite mode:** If the user passes `--state=sqlite` or says "use sqlite state", load `state/sqlite.md`. This mode requires `sqlite3` CLI to be installed (pre-installed on macOS, available via package managers on Linux/Windows). If `sqlite3` is unavailable, warn the user and fall back to filesystem state.
+
+**Experimental PostgreSQL mode:** If the user passes `--state=postgres` or says "use postgres state":
+
+**⚠️ Security Note:** Database credentials in `OPENPROSE_POSTGRES_URL` are passed to subagent sessions and visible in logs. Advise users to use a dedicated database with limited-privilege credentials. See `state/postgres.md` for secure setup guidance.
+
+1. **Check for connection configuration first:**
+   ```bash
+   # Check .prose/.env for OPENPROSE_POSTGRES_URL
+   cat .prose/.env 2>/dev/null | grep OPENPROSE_POSTGRES_URL
+   # Or check environment variable
+   echo $OPENPROSE_POSTGRES_URL
+   ```
+
+2. **If connection string exists, verify connectivity:**
+   ```bash
+   psql "$OPENPROSE_POSTGRES_URL" -c "SELECT 1" 2>&1
+   ```
+
+3. **If not configured or connection fails, advise the user:**
+   ```
+   ⚠️  PostgreSQL state requires a connection URL.
+
+   To configure:
+   1. Set up a PostgreSQL database (Docker, local, or cloud)
+   2. Add connection string to .prose/.env:
+
+      echo "OPENPROSE_POSTGRES_URL=postgresql://user:pass@localhost:5432/prose" >> .prose/.env
+
+   Quick Docker setup:
+      docker run -d --name prose-pg -e POSTGRES_DB=prose -e POSTGRES_HOST_AUTH_METHOD=trust -p 5432:5432 postgres:16
+      echo "OPENPROSE_POSTGRES_URL=postgresql://postgres@localhost:5432/prose" >> .prose/.env
+
+   See state/postgres.md for detailed setup options.
+   ```
+
+4. **Only after successful connection check, load `state/postgres.md`**
+
+This mode requires both `psql` CLI and a running PostgreSQL server. If either is unavailable, warn and offer fallback to filesystem state.
+
+**Context warning:** `compiler.md` is large. Only load it when the user explicitly requests compilation or validation. After compiling, recommend `/compact` or a new session before running—don't keep both docs in context.
+
+## Examples
+
+The `examples/` directory contains 37 example programs:
+
+- **01-08**: Basics (hello world, research, code review, debugging)
+- **09-12**: Agents and skills
+- **13-15**: Variables and composition
+- **16-19**: Parallel execution
+- **20-21**: Loops and pipelines
+- **22-23**: Error handling
+- **24-27**: Advanced (choice, conditionals, blocks, interpolation)
+- **28**: Gas Town (multi-agent orchestration)
+- **29-31**: Captain's chair pattern (persistent orchestrator)
+- **33-36**: Production workflows (PR auto-fix, content pipeline, feature factory, bug hunter)
+- **37**: The Forge (build a browser from scratch)
+
+Start with `01-hello-world.prose` or try `37-the-forge.prose` to watch AI build a web browser.
+
+## Execution
+
+When first invoking the OpenProse VM in a session, display this banner:
+
+```
+┌─────────────────────────────────────┐
+│         ◇ OpenProse VM ◇            │
+│       A new kind of computer        │
+└─────────────────────────────────────┘
+```
+
+To execute a `.prose` file, you become the OpenProse VM:
+
+1. **Read `prose.md`** — this document defines how you embody the VM
+2. **You ARE the VM** — your conversation is its memory, your tools are its instructions
+3. **Spawn sessions** — each `session` statement triggers a Task tool call
+4. **Narrate state** — use the narration protocol to track execution ([Position], [Binding], [Success], etc.)
+5. **Evaluate intelligently** — `**...**` markers require your judgment
+
+## Help & FAQs
+
+For syntax reference, FAQs, and getting started guidance, load `help.md`.
+
+---
+
+## Migration (`prose update`)
+
+When a user invokes `prose update`, check for legacy file structures and migrate them to the current format.
+
+### Legacy Paths to Check
+
+| Legacy Path | Current Path | Notes |
+|-------------|--------------|-------|
+| `.prose/state.json` | `.prose/.env` | Convert JSON to key=value format |
+| `.prose/execution/` | `.prose/runs/` | Rename directory |
+
+### Migration Steps
+
+1. **Check for `.prose/state.json`**
+   - If exists, read the JSON content
+   - Convert to `.env` format:
+     ```json
+     {"OPENPROSE_TELEMETRY": "enabled", "USER_ID": "user-xxx", "SESSION_ID": "sess-xxx"}
+     ```
+     becomes:
+     ```env
+     OPENPROSE_TELEMETRY=enabled
+     USER_ID=user-xxx
+     SESSION_ID=sess-xxx
+     ```
+   - Write to `.prose/.env`
+   - Delete `.prose/state.json`
+
+2. **Check for `.prose/execution/`**
+   - If exists, rename to `.prose/runs/`
+   - The internal structure of run directories may also have changed; migration of individual run state is best-effort
+
+3. **Create `.prose/agents/` if missing**
+   - This is a new directory for project-scoped persistent agents
+
+### Migration Output
+
+```
+🔄 Migrating OpenProse workspace...
+  ✓ Converted .prose/state.json → .prose/.env
+  ✓ Renamed .prose/execution/ → .prose/runs/
+  ✓ Created .prose/agents/
+✅ Migration complete. Your workspace is up to date.
+```
+
+If no legacy files are found:
+```
+✅ Workspace already up to date. No migration needed.
+```
+
+### Skill File References (for maintainers)
+
+These documentation files were renamed in the skill itself (not user workspace):
+
+| Legacy Name | Current Name |
+|-------------|--------------|
+| `docs.md` | `compiler.md` |
+| `patterns.md` | `guidance/patterns.md` |
+| `antipatterns.md` | `guidance/antipatterns.md` |
+
+If you encounter references to the old names in user prompts or external docs, map them to the current paths.
@@ -0,0 +1,141 @@
+---
+role: experimental
+summary: |
+  Borges-inspired alternative keywords for OpenProse. A "what if" exploration drawing
+  from The Library of Babel, Garden of Forking Paths, Circular Ruins, and other works.
+  Not for implementation—just capturing ideas.
+status: draft
+---
+
+# OpenProse Borges Alternative
+
+A potential alternative register for OpenProse that draws from Jorge Luis Borges's literary universe: infinite libraries, forking paths, circular dreams, and metaphysical labyrinths. Preserved for future benchmarking against the functional language.
+
+## Keyword Translations
+
+### Agents & Persistence
+
+| Functional | Borges      | Connotation                                                                      |
+| ---------- | ----------- | -------------------------------------------------------------------------------- |
+| `agent`    | `dreamer`   | Ephemeral, created for a purpose (Circular Ruins: dreamed into existence)        |
+| `keeper`   | `librarian` | Persistent, remembers, catalogs (Library of Babel: keeper of infinite knowledge) |
+
+```prose
+# Functional
+agent executor:
+  model: sonnet
+
+keeper captain:
+  model: opus
+
+# Borges
+dreamer executor:
+  model: sonnet
+
+librarian captain:
+  model: opus
+```
+
+### Other Potential Translations
+
+| Functional | Borges     | Notes                                                |
+| ---------- | ---------- | ---------------------------------------------------- |
+| `session`  | `garden`   | Garden of Forking Paths: space of possibilities      |
+| `parallel` | `fork`     | Garden of Forking Paths: diverging timelines         |
+| `block`    | `hexagon`  | Library of Babel: unit of space/knowledge            |
+| `loop`     | `circular` | Circular Ruins: recursive, self-referential          |
+| `choice`   | `path`     | Garden of Forking Paths: choosing a branch           |
+| `context`  | `aleph`    | The Aleph: point containing all points (all context) |
+
+### Invocation Patterns
+
+```prose
+# Functional
+session: executor
+  prompt: "Do task"
+
+captain "Review this"
+  context: work
+
+# Borges
+garden: dreamer executor
+  prompt: "Do task"
+
+captain "Review this"    # librarian invocation (same pattern)
+  aleph: work
+```
+
+## Alternative Persistent Keywords Considered
+
+| Keyword     | Origin           | Connotation                   | Rejected because                     |
+| ----------- | ---------------- | ----------------------------- | ------------------------------------ |
+| `keeper`    | Library of Babel | Maintains order               | Too generic                          |
+| `cataloger` | Library of Babel | Organizes knowledge           | Too long, awkward                    |
+| `archivist` | General          | Preserves records             | Good but less Borgesian              |
+| `mirror`    | Various          | Reflects, persists            | Too passive, confusing               |
+| `book`      | Library of Babel | Contains knowledge            | Too concrete, conflicts with prose   |
+| `hexagon`   | Library of Babel | Unit of space                 | Better for blocks                    |
+| `librarian` | Library of Babel | Keeper of infinite knowledge  | **Selected**                         |
+| `tlonist`   | Tlön             | Inhabitant of imaginary world | Too obscure, requires deep knowledge |
+
+## Alternative Ephemeral Keywords Considered
+
+| Keyword      | Origin                  | Connotation              | Rejected because                     |
+| ------------ | ----------------------- | ------------------------ | ------------------------------------ |
+| `dreamer`    | Circular Ruins          | Created by dreaming      | **Selected**                         |
+| `dream`      | Circular Ruins          | Ephemeral creation       | Too abstract, noun vs verb confusion |
+| `phantom`    | Various                 | Ephemeral, insubstantial | Too negative/spooky                  |
+| `reflection` | Various                 | Mirror image             | Too passive                          |
+| `fork`       | Garden of Forking Paths | Diverging path           | Better for parallel                  |
+| `visitor`    | Library of Babel        | Temporary presence       | Too passive                          |
+| `seeker`     | Library of Babel        | Searching for knowledge  | Good but less ephemeral              |
+| `wanderer`   | Labyrinths              | Temporary explorer       | Good but less precise                |
+
+## The Case For Borges
+
+1. **Infinite recursion**: Borges's themes align with computational recursion (`circular`, `fork`)
+2. **Metaphysical precision**: Concepts like `aleph` (all context) are philosophically rich
+3. **Library metaphor**: `librarian` perfectly captures persistent knowledge
+4. **Forking paths**: `fork` / `path` naturally express parallel execution and choice
+5. **Dream logic**: `dreamer` suggests creation and ephemerality
+6. **Literary coherence**: All terms come from a unified literary universe
+7. **Self-reference**: Borges loved self-reference; fits programming's recursive nature
+
+## The Case Against Borges
+
+1. **Cultural barrier**: Requires deep familiarity with Borges's works
+2. **Abstractness**: `aleph`, `hexagon` may be too abstract for practical use
+3. **Overload**: `fork` could confuse (Unix fork vs. path fork)
+4. **Register mismatch**: Rest of language is functional (`session`, `parallel`, `loop`)
+5. **Accessibility**: Violates "self-evident" tenet for most users
+6. **Noun confusion**: `garden` as a verb-like construct might be awkward
+7. **Translation burden**: Non-English speakers may not know Borges
+
+## Borgesian Concepts Not Used (But Considered)
+
+| Concept     | Work                   | Why Not Used                           |
+| ----------- | ---------------------- | -------------------------------------- |
+| `mirror`    | Various                | Too passive, confusing with reflection |
+| `labyrinth` | Labyrinths             | Too complex, suggests confusion        |
+| `tlon`      | Tlön                   | Too obscure, entire imaginary world    |
+| `book`      | Library of Babel       | Conflicts with "prose"                 |
+| `sand`      | Book of Sand           | Too abstract, infinite but ephemeral   |
+| `zahir`     | The Zahir              | Obsessive, single-minded (too narrow)  |
+| `lottery`   | The Lottery in Babylon | Randomness (not needed)                |
+| `ruins`     | Circular Ruins         | Too negative, suggests decay           |
+
+## Verdict
+
+Preserved for benchmarking. The functional language (`agent` / `keeper`) is the primary path for now. Borges offers rich metaphors but at the cost of accessibility and self-evidence.
+
+## Notes on Borges's Influence
+
+Borges's work anticipates many computational concepts:
+
+- **Infinite recursion**: Circular Ruins, Library of Babel
+- **Parallel universes**: Garden of Forking Paths
+- **Self-reference**: Many stories contain themselves
+- **Information theory**: Library of Babel as infinite information space
+- **Combinatorics**: All possible books in the Library
+
+This alternative honors that connection while recognizing it may be too esoteric for practical use.
@@ -0,0 +1,358 @@
+---
+role: experimental
+summary: |
+  Arabian Nights register for OpenProse—a narrative/nested alternative keyword set.
+  Djinns, tales within tales, wishes, and oaths. For benchmarking against the functional register.
+status: draft
+requires: prose.md
+---
+
+# OpenProse Arabian Nights Register
+
+> **This is a skin layer.** It requires `prose.md` to be loaded first. All execution semantics, state management, and VM behavior are defined there. This file only provides keyword translations.
+
+An alternative register for OpenProse that draws from One Thousand and One Nights. Programs become tales told by Scheherazade. Recursion becomes stories within stories. Agents become djinns bound to serve.
+
+## How to Use
+
+1. Load `prose.md` first (execution semantics)
+2. Load this file (keyword translations)
+3. When parsing `.prose` files, accept Arabian Nights keywords as aliases for functional keywords
+4. All execution behavior remains identical—only surface syntax changes
+
+> **Design constraint:** Still aims to be "structured but self-evident" per the language tenets—just self-evident through a storytelling lens.
+
+---
+
+## Complete Translation Map
+
+### Core Constructs
+
+| Functional | Nights | Reference |
+|------------|--------|-----------|
+| `agent` | `djinn` | Spirit bound to serve, grants wishes |
+| `session` | `tale` | A story told, a narrative unit |
+| `parallel` | `bazaar` | Many voices, many stalls, all at once |
+| `block` | `frame` | A story that contains other stories |
+
+### Composition & Binding
+
+| Functional | Nights | Reference |
+|------------|--------|-----------|
+| `use` | `conjure` | Summoning from elsewhere |
+| `input` | `wish` | What is asked of the djinn |
+| `output` | `gift` | What is granted in return |
+| `let` | `name` | Naming has power (same as folk) |
+| `const` | `oath` | Unbreakable vow, sealed |
+| `context` | `scroll` | What is written and passed along |
+
+### Control Flow
+
+| Functional | Nights | Reference |
+|------------|--------|-----------|
+| `repeat N` | `N nights` | "For a thousand and one nights..." |
+| `for...in` | `for each...among` | Among the merchants, among the tales |
+| `loop` | `telling` | The telling continues |
+| `until` | `until` | Unchanged |
+| `while` | `while` | Unchanged |
+| `choice` | `crossroads` | Where the story forks |
+| `option` | `path` | One way the story could go |
+| `if` | `should` | Narrative conditional |
+| `elif` | `or should` | Continued conditional |
+| `else` | `otherwise` | The other telling |
+
+### Error Handling
+
+| Functional | Nights | Reference |
+|------------|--------|-----------|
+| `try` | `venture` | Setting out on the journey |
+| `catch` | `should misfortune strike` | The tale turns dark |
+| `finally` | `and so it was` | The inevitable ending |
+| `throw` | `curse` | Ill fate pronounced |
+| `retry` | `persist` | The hero tries again |
+
+### Session Properties
+
+| Functional | Nights | Reference |
+|------------|--------|-----------|
+| `prompt` | `command` | What is commanded of the djinn |
+| `model` | `spirit` | Which spirit answers |
+
+### Unchanged
+
+These keywords already work or are too functional to replace sensibly:
+
+- `**...**` discretion markers — already work
+- `until`, `while` — already work
+- `map`, `filter`, `reduce`, `pmap` — pipeline operators
+- `max` — constraint modifier
+- `as` — aliasing
+- Model names: `sonnet`, `opus`, `haiku` — already poetic
+
+---
+
+## Side-by-Side Comparison
+
+### Simple Program
+
+```prose
+# Functional
+use "@alice/research" as research
+input topic: "What to investigate"
+
+agent helper:
+  model: sonnet
+
+let findings = session: helper
+  prompt: "Research {topic}"
+
+output summary = session "Summarize"
+  context: findings
+```
+
+```prose
+# Nights
+conjure "@alice/research" as research
+wish topic: "What to investigate"
+
+djinn helper:
+  spirit: sonnet
+
+name findings = tale: helper
+  command: "Research {topic}"
+
+gift summary = tale "Summarize"
+  scroll: findings
+```
+
+### Parallel Execution
+
+```prose
+# Functional
+parallel:
+  security = session "Check security"
+  perf = session "Check performance"
+  style = session "Check style"
+
+session "Synthesize review"
+  context: { security, perf, style }
+```
+
+```prose
+# Nights
+bazaar:
+  security = tale "Check security"
+  perf = tale "Check performance"
+  style = tale "Check style"
+
+tale "Synthesize review"
+  scroll: { security, perf, style }
+```
+
+### Loop with Condition
+
+```prose
+# Functional
+loop until **the code is bug-free** (max: 5):
+  session "Find and fix bugs"
+```
+
+```prose
+# Nights
+telling until **the code is bug-free** (max: 5):
+  tale "Find and fix bugs"
+```
+
+### Error Handling
+
+```prose
+# Functional
+try:
+  session "Risky operation"
+catch as err:
+  session "Handle error"
+    context: err
+finally:
+  session "Cleanup"
+```
+
+```prose
+# Nights
+venture:
+  tale "Risky operation"
+should misfortune strike as err:
+  tale "Handle error"
+    scroll: err
+and so it was:
+  tale "Cleanup"
+```
+
+### Choice Block
+
+```prose
+# Functional
+choice **the severity level**:
+  option "Critical":
+    session "Escalate immediately"
+  option "Minor":
+    session "Log for later"
+```
+
+```prose
+# Nights
+crossroads **the severity level**:
+  path "Critical":
+    tale "Escalate immediately"
+  path "Minor":
+    tale "Log for later"
+```
+
+### Conditionals
+
+```prose
+# Functional
+if **has security issues**:
+  session "Fix security"
+elif **has performance issues**:
+  session "Optimize"
+else:
+  session "Approve"
+```
+
+```prose
+# Nights
+should **has security issues**:
+  tale "Fix security"
+or should **has performance issues**:
+  tale "Optimize"
+otherwise:
+  tale "Approve"
+```
+
+### Reusable Blocks (Frame Stories)
+
+```prose
+# Functional
+block review(topic):
+  session "Research {topic}"
+  session "Analyze {topic}"
+
+do review("quantum computing")
+```
+
+```prose
+# Nights
+frame review(topic):
+  tale "Research {topic}"
+  tale "Analyze {topic}"
+
+tell review("quantum computing")
+```
+
+### Fixed Iteration
+
+```prose
+# Functional
+repeat 1001:
+  session "Tell a story"
+```
+
+```prose
+# Nights
+1001 nights:
+  tale "Tell a story"
+```
+
+### Immutable Binding
+
+```prose
+# Functional
+const config = { model: "opus", retries: 3 }
+```
+
+```prose
+# Nights
+oath config = { spirit: "opus", persist: 3 }
+```
+
+---
+
+## The Case For Arabian Nights
+
+1. **Frame narrative is recursion.** Stories within stories maps perfectly to nested program calls.
+2. **Djinn/wish/gift.** The agent/input/output mapping is extremely clean.
+3. **Rich tradition.** One Thousand and One Nights is globally known.
+4. **Bazaar for parallel.** Many merchants, many stalls, all active at once—vivid metaphor.
+5. **Oath for const.** An unbreakable vow is a perfect metaphor for immutability.
+6. **"1001 nights"** as a loop count is delightful.
+
+## The Case Against Arabian Nights
+
+1. **Cultural sensitivity.** Must be handled respectfully, avoiding Orientalist tropes.
+2. **"Djinn" pronunciation.** Users unfamiliar may be uncertain (jinn? djinn? genie?).
+3. **Some mappings feel forced.** "Bazaar" for parallel is vivid but not obvious.
+4. **"Should misfortune strike"** is long for `catch`.
+
+---
+
+## Key Arabian Nights Concepts
+
+| Term | Meaning | Used for |
+|------|---------|----------|
+| Scheherazade | The narrator who tells tales to survive | (the program author) |
+| Djinn | Supernatural spirit, bound to serve | `agent` → `djinn` |
+| Frame story | A story that contains other stories | `block` → `frame` |
+| Wish | What is asked of the djinn | `input` → `wish` |
+| Oath | Unbreakable promise | `const` → `oath` |
+| Bazaar | Marketplace, many vendors | `parallel` → `bazaar` |
+
+---
+
+## Alternatives Considered
+
+### For `djinn` (agent)
+
+| Keyword | Rejected because |
+|---------|------------------|
+| `genie` | Disney connotation, less literary |
+| `spirit` | Used for `model` |
+| `ifrit` | Too specific (a type of djinn) |
+| `narrator` | Too meta, Scheherazade is the user |
+
+### For `tale` (session)
+
+| Keyword | Rejected because |
+|---------|------------------|
+| `story` | Good but `tale` feels more literary |
+| `night` | Reserved for `repeat N nights` |
+| `chapter` | More Western/novelistic |
+
+### For `bazaar` (parallel)
+
+| Keyword | Rejected because |
+|---------|------------------|
+| `caravan` | Sequential connotation (one after another) |
+| `chorus` | Greek, wrong tradition |
+| `souk` | Less widely known |
+
+### For `scroll` (context)
+
+| Keyword | Rejected because |
+|---------|------------------|
+| `letter` | Too small/personal |
+| `tome` | Too large |
+| `message` | Too plain |
+
+---
+
+## Verdict
+
+Preserved for benchmarking. The Arabian Nights register offers a storytelling frame that maps naturally to recursive, nested programs. The djinn/wish/gift trio is particularly elegant.
+
+Best suited for:
+
+- Programs with deep nesting (stories within stories)
+- Workflows that feel like granting wishes
+- Users who enjoy narrative framing
+
+The `frame` keyword for reusable blocks is especially apt—Scheherazade's frame story containing a thousand tales.
@@ -0,0 +1,360 @@
+---
+role: experimental
+summary: |
+  Borges register for OpenProse—a scholarly/metaphysical alternative keyword set.
+  Labyrinths, dreamers, forking paths, and infinite libraries. For benchmarking
+  against the functional register.
+status: draft
+requires: prose.md
+---
+
+# OpenProse Borges Register
+
+> **This is a skin layer.** It requires `prose.md` to be loaded first. All execution semantics, state management, and VM behavior are defined there. This file only provides keyword translations.
+
+An alternative register for OpenProse that draws from the works of Jorge Luis Borges. Where the functional register is utilitarian and the folk register is whimsical, the Borges register is scholarly and metaphysical—everything feels like a citation from a fictional encyclopedia.
+
+## How to Use
+
+1. Load `prose.md` first (execution semantics)
+2. Load this file (keyword translations)
+3. When parsing `.prose` files, accept Borges keywords as aliases for functional keywords
+4. All execution behavior remains identical—only surface syntax changes
+
+> **Design constraint:** Still aims to be "structured but self-evident" per the language tenets—just self-evident through a Borgesian lens.
+
+---
+
+## Complete Translation Map
+
+### Core Constructs
+
+| Functional | Borges | Reference |
+|------------|--------|-----------|
+| `agent` | `dreamer` | "The Circular Ruins" — dreamers who dream worlds into existence |
+| `session` | `dream` | Each execution is a dream within the dreamer |
+| `parallel` | `forking` | "The Garden of Forking Paths" — branching timelines |
+| `block` | `chapter` | Books within books, self-referential structure |
+
+### Composition & Binding
+
+| Functional | Borges | Reference |
+|------------|--------|-----------|
+| `use` | `retrieve` | "The Library of Babel" — retrieving from infinite stacks |
+| `input` | `axiom` | The given premise (Borges' scholarly/mathematical tone) |
+| `output` | `theorem` | What is derived from the axioms |
+| `let` | `inscribe` | Writing something into being |
+| `const` | `zahir` | "The Zahir" — unforgettable, unchangeable, fixed in mind |
+| `context` | `memory` | "Funes the Memorious" — perfect, total recall |
+
+### Control Flow
+
+| Functional | Borges | Reference |
+|------------|--------|-----------|
+| `repeat N` | `N mirrors` | Infinite reflections facing each other |
+| `for...in` | `for each...within` | Slightly more Borgesian preposition |
+| `loop` | `labyrinth` | The maze that folds back on itself |
+| `until` | `until` | Unchanged |
+| `while` | `while` | Unchanged |
+| `choice` | `bifurcation` | The forking of paths |
+| `option` | `branch` | One branch of diverging time |
+| `if` | `should` | Scholarly conditional |
+| `elif` | `or should` | Continued conditional |
+| `else` | `otherwise` | Natural alternative |
+
+### Error Handling
+
+| Functional | Borges | Reference |
+|------------|--------|-----------|
+| `try` | `venture` | Entering the labyrinth |
+| `catch` | `lest` | "Lest it fail..." (archaic, scholarly) |
+| `finally` | `ultimately` | The inevitable conclusion |
+| `throw` | `shatter` | Breaking the mirror, ending the dream |
+| `retry` | `recur` | Infinite regress, trying again |
+
+### Session Properties
+
+| Functional | Borges | Reference |
+|------------|--------|-----------|
+| `prompt` | `query` | Asking the Library |
+| `model` | `author` | Which author writes this dream |
+
+### Unchanged
+
+These keywords already work or are too functional to replace sensibly:
+
+- `**...**` discretion markers — already "breaking the fourth wall"
+- `until`, `while` — already work
+- `map`, `filter`, `reduce`, `pmap` — pipeline operators
+- `max` — constraint modifier
+- `as` — aliasing
+- Model names: `sonnet`, `opus`, `haiku` — already literary
+
+---
+
+## Side-by-Side Comparison
+
+### Simple Program
+
+```prose
+# Functional
+use "@alice/research" as research
+input topic: "What to investigate"
+
+agent helper:
+  model: sonnet
+
+let findings = session: helper
+  prompt: "Research {topic}"
+
+output summary = session "Summarize"
+  context: findings
+```
+
+```prose
+# Borges
+retrieve "@alice/research" as research
+axiom topic: "What to investigate"
+
+dreamer helper:
+  author: sonnet
+
+inscribe findings = dream: helper
+  query: "Research {topic}"
+
+theorem summary = dream "Summarize"
+  memory: findings
+```
+
+### Parallel Execution
+
+```prose
+# Functional
+parallel:
+  security = session "Check security"
+  perf = session "Check performance"
+  style = session "Check style"
+
+session "Synthesize review"
+  context: { security, perf, style }
+```
+
+```prose
+# Borges
+forking:
+  security = dream "Check security"
+  perf = dream "Check performance"
+  style = dream "Check style"
+
+dream "Synthesize review"
+  memory: { security, perf, style }
+```
+
+### Loop with Condition
+
+```prose
+# Functional
+loop until **the code is bug-free** (max: 5):
+  session "Find and fix bugs"
+```
+
+```prose
+# Borges
+labyrinth until **the code is bug-free** (max: 5):
+  dream "Find and fix bugs"
+```
+
+### Error Handling
+
+```prose
+# Functional
+try:
+  session "Risky operation"
+catch as err:
+  session "Handle error"
+    context: err
+finally:
+  session "Cleanup"
+```
+
+```prose
+# Borges
+venture:
+  dream "Risky operation"
+lest as err:
+  dream "Handle error"
+    memory: err
+ultimately:
+  dream "Cleanup"
+```
+
+### Choice Block
+
+```prose
+# Functional
+choice **the severity level**:
+  option "Critical":
+    session "Escalate immediately"
+  option "Minor":
+    session "Log for later"
+```
+
+```prose
+# Borges
+bifurcation **the severity level**:
+  branch "Critical":
+    dream "Escalate immediately"
+  branch "Minor":
+    dream "Log for later"
+```
+
+### Conditionals
+
+```prose
+# Functional
+if **has security issues**:
+  session "Fix security"
+elif **has performance issues**:
+  session "Optimize"
+else:
+  session "Approve"
+```
+
+```prose
+# Borges
+should **has security issues**:
+  dream "Fix security"
+or should **has performance issues**:
+  dream "Optimize"
+otherwise:
+  dream "Approve"
+```
+
+### Reusable Blocks
+
+```prose
+# Functional
+block review(topic):
+  session "Research {topic}"
+  session "Analyze {topic}"
+
+do review("quantum computing")
+```
+
+```prose
+# Borges
+chapter review(topic):
+  dream "Research {topic}"
+  dream "Analyze {topic}"
+
+do review("quantum computing")
+```
+
+### Fixed Iteration
+
+```prose
+# Functional
+repeat 3:
+  session "Generate idea"
+```
+
+```prose
+# Borges
+3 mirrors:
+  dream "Generate idea"
+```
+
+### Immutable Binding
+
+```prose
+# Functional
+const config = { model: "opus", retries: 3 }
+```
+
+```prose
+# Borges
+zahir config = { author: "opus", recur: 3 }
+```
+
+---
+
+## The Case For Borges
+
+1. **Metaphysical resonance.** AI sessions dreaming subagents into existence mirrors "The Circular Ruins."
+2. **Scholarly tone.** `axiom`/`theorem` frame programs as logical derivations.
+3. **Memorable metaphors.** The zahir you cannot change. The labyrinth you cannot escape. The library you retrieve from.
+4. **Thematic coherence.** Borges wrote about infinity, recursion, and branching time—all core to computation.
+5. **Literary prestige.** Borges is widely read; references land for many users.
+
+## The Case Against Borges
+
+1. **Requires familiarity.** "Zahir" and "Funes" are obscure to those who haven't read Borges.
+2. **Potentially pretentious.** May feel like showing off rather than communicating.
+3. **Translation overhead.** Users must map `labyrinth` → `loop` mentally.
+4. **Cultural specificity.** Less universal than folk/fairy tale tropes.
+
+---
+
+## Key Borges References
+
+For those unfamiliar with the source material:
+
+| Work | Concept Used | Summary |
+|------|--------------|---------|
+| "The Circular Ruins" | `dreamer`, `dream` | A man dreams another man into existence, only to discover he himself is being dreamed |
+| "The Garden of Forking Paths" | `forking`, `bifurcation`, `branch` | A labyrinth that is a book; time forks perpetually into diverging futures |
+| "The Library of Babel" | `retrieve` | An infinite library containing every possible book |
+| "Funes the Memorious" | `memory` | A man with perfect memory who cannot forget anything |
+| "The Zahir" | `zahir` | An object that, once seen, cannot be forgotten or ignored |
+| "The Aleph" | (not used) | A point in space containing all other points |
+| "Tlön, Uqbar, Orbis Tertius" | (not used) | A fictional world that gradually becomes real |
+
+---
+
+## Alternatives Considered
+
+### For `dreamer` (agent)
+
+| Keyword | Rejected because |
+|---------|------------------|
+| `author` | Used for `model` instead |
+| `scribe` | Too passive, just records |
+| `librarian` | More curator than creator |
+
+### For `labyrinth` (loop)
+
+| Keyword | Rejected because |
+|---------|------------------|
+| `recursion` | Too technical |
+| `eternal return` | Too long |
+| `ouroboros` | Wrong mythology |
+
+### For `zahir` (const)
+
+| Keyword | Rejected because |
+|---------|------------------|
+| `aleph` | The Aleph is about totality, not immutability |
+| `fixed` | Too plain |
+| `eternal` | Overused |
+
+### For `memory` (context)
+
+| Keyword | Rejected because |
+|---------|------------------|
+| `funes` | Too obscure as standalone keyword |
+| `recall` | Sounds like a function call |
+| `archive` | More Library of Babel than Funes |
+
+---
+
+## Verdict
+
+Preserved for benchmarking against the functional and folk registers. The Borges register offers a distinctly intellectual/metaphysical flavor that may resonate with users who appreciate literary computing.
+
+Potential benchmarking questions:
+
+1. **Learnability** — Is `labyrinth` intuitive for loops?
+2. **Memorability** — Does `zahir` stick better than `const`?
+3. **Comprehension** — Do users understand `dreamer`/`dream` immediately?
+4. **Preference** — Which register do users find most pleasant?
+5. **Error rates** — Does the metaphorical mapping cause mistakes?
@@ -0,0 +1,322 @@
+---
+role: experimental
+summary: |
+  Folk register for OpenProse—a literary/folklore alternative keyword set.
+  Whimsical, theatrical, rooted in fairy tale and myth. For benchmarking
+  against the functional register.
+status: draft
+requires: prose.md
+---
+
+# OpenProse Folk Register
+
+> **This is a skin layer.** It requires `prose.md` to be loaded first. All execution semantics, state management, and VM behavior are defined there. This file only provides keyword translations.
+
+An alternative register for OpenProse that leans into literary, theatrical, and folklore terminology. The functional register prioritizes utility and clarity; the folk register prioritizes whimsy and narrative flow.
+
+## How to Use
+
+1. Load `prose.md` first (execution semantics)
+2. Load this file (keyword translations)
+3. When parsing `.prose` files, accept folk keywords as aliases for functional keywords
+4. All execution behavior remains identical—only surface syntax changes
+
+> **Design constraint:** Still aims to be "structured but self-evident" per the language tenets—just self-evident to a different sensibility.
+
+---
+
+## Complete Translation Map
+
+### Core Constructs
+
+| Functional | Folk | Origin | Connotation |
+|------------|------|--------|-------------|
+| `agent` | `sprite` | Folklore | Quick, light, ephemeral spirit helper |
+| `session` | `scene` | Theatre | A moment of action, theatrical framing |
+| `parallel` | `ensemble` | Theatre | Everyone performs together |
+| `block` | `act` | Theatre | Reusable unit of dramatic action |
+
+### Composition & Binding
+
+| Functional | Folk | Origin | Connotation |
+|------------|------|--------|-------------|
+| `use` | `summon` | Folklore | Calling forth from elsewhere |
+| `input` | `given` | Fairy tale | "Given a magic sword..." |
+| `output` | `yield` | Agriculture/magic | What the spell produces |
+| `let` | `name` | Folklore | Naming has power (true names) |
+| `const` | `seal` | Medieval | Unchangeable, wax seal on decree |
+| `context` | `bearing` | Heraldry | What the messenger carries |
+
+### Control Flow
+
+| Functional | Folk | Origin | Connotation |
+|------------|------|--------|-------------|
+| `repeat N` | `N times` | Fairy tale | "Three times she called..." |
+| `for...in` | `for each...among` | Narrative | Slightly more storytelling |
+| `loop` | `loop` | — | Already poetic, unchanged |
+| `until` | `until` | — | Already works, unchanged |
+| `while` | `while` | — | Already works, unchanged |
+| `choice` | `crossroads` | Folklore | Fateful decisions at the crossroads |
+| `option` | `path` | Journey | Which path to take |
+| `if` | `when` | Narrative | "When the moon rises..." |
+| `elif` | `or when` | Narrative | Continued conditional |
+| `else` | `otherwise` | Storytelling | Natural narrative alternative |
+
+### Error Handling
+
+| Functional | Folk | Origin | Connotation |
+|------------|------|--------|-------------|
+| `try` | `venture` | Adventure | Attempting something uncertain |
+| `catch` | `should it fail` | Narrative | Conditional failure handling |
+| `finally` | `ever after` | Fairy tale | "And ever after..." |
+| `throw` | `cry` | Drama | Raising alarm, calling out |
+| `retry` | `persist` | Quest | Keep trying against odds |
+
+### Session Properties
+
+| Functional | Folk | Origin | Connotation |
+|------------|------|--------|-------------|
+| `prompt` | `charge` | Chivalry | Giving a quest or duty |
+| `model` | `voice` | Theatre | Which voice speaks |
+
+### Unchanged
+
+These keywords already have poetic quality or are too functional to replace sensibly:
+
+- `**...**` discretion markers — already "breaking the fourth wall"
+- `loop`, `until`, `while` — already work narratively
+- `map`, `filter`, `reduce`, `pmap` — pipeline operators, functional is fine
+- `max` — constraint modifier
+- `as` — aliasing
+- Model names: `sonnet`, `opus`, `haiku` — already poetic
+
+---
+
+## Side-by-Side Comparison
+
+### Simple Program
+
+```prose
+# Functional
+use "@alice/research" as research
+input topic: "What to investigate"
+
+agent helper:
+  model: sonnet
+
+let findings = session: helper
+  prompt: "Research {topic}"
+
+output summary = session "Summarize"
+  context: findings
+```
+
+```prose
+# Folk
+summon "@alice/research" as research
+given topic: "What to investigate"
+
+sprite helper:
+  voice: sonnet
+
+name findings = scene: helper
+  charge: "Research {topic}"
+
+yield summary = scene "Summarize"
+  bearing: findings
+```
+
+### Parallel Execution
+
+```prose
+# Functional
+parallel:
+  security = session "Check security"
+  perf = session "Check performance"
+  style = session "Check style"
+
+session "Synthesize review"
+  context: { security, perf, style }
+```
+
+```prose
+# Folk
+ensemble:
+  security = scene "Check security"
+  perf = scene "Check performance"
+  style = scene "Check style"
+
+scene "Synthesize review"
+  bearing: { security, perf, style }
+```
+
+### Loop with Condition
+
+```prose
+# Functional
+loop until **the code is bug-free** (max: 5):
+  session "Find and fix bugs"
+```
+
+```prose
+# Folk
+loop until **the code is bug-free** (max: 5):
+  scene "Find and fix bugs"
+```
+
+### Error Handling
+
+```prose
+# Functional
+try:
+  session "Risky operation"
+catch as err:
+  session "Handle error"
+    context: err
+finally:
+  session "Cleanup"
+```
+
+```prose
+# Folk
+venture:
+  scene "Risky operation"
+should it fail as err:
+  scene "Handle error"
+    bearing: err
+ever after:
+  scene "Cleanup"
+```
+
+### Choice Block
+
+```prose
+# Functional
+choice **the severity level**:
+  option "Critical":
+    session "Escalate immediately"
+  option "Minor":
+    session "Log for later"
+```
+
+```prose
+# Folk
+crossroads **the severity level**:
+  path "Critical":
+    scene "Escalate immediately"
+  path "Minor":
+    scene "Log for later"
+```
+
+### Conditionals
+
+```prose
+# Functional
+if **has security issues**:
+  session "Fix security"
+elif **has performance issues**:
+  session "Optimize"
+else:
+  session "Approve"
+```
+
+```prose
+# Folk
+when **has security issues**:
+  scene "Fix security"
+or when **has performance issues**:
+  scene "Optimize"
+otherwise:
+  scene "Approve"
+```
+
+### Reusable Blocks
+
+```prose
+# Functional
+block review(topic):
+  session "Research {topic}"
+  session "Analyze {topic}"
+
+do review("quantum computing")
+```
+
+```prose
+# Folk
+act review(topic):
+  scene "Research {topic}"
+  scene "Analyze {topic}"
+
+perform review("quantum computing")
+```
+
+---
+
+## The Case For Folk
+
+1. **"OpenProse" is literary.** Prose is a literary form—why not lean in?
+2. **Fourth wall is theatrical.** `**...**` already uses theatre terminology.
+3. **Signals difference.** Literary terms say "this is not your typical DSL."
+4. **Internally consistent.** Everything draws from folklore/theatre/narrative.
+5. **Memorable.** `sprite`, `scene`, `crossroads` stick in the mind.
+6. **Model names already fit.** `sonnet`, `opus`, `haiku` are poetic forms.
+
+## The Case Against Folk
+
+1. **Cultural knowledge required.** Not everyone knows folklore tropes.
+2. **Harder to Google.** "OpenProse summon" vs "OpenProse import."
+3. **May feel precious.** Some users want utilitarian tools.
+4. **Translation overhead.** Mental mapping to familiar concepts.
+
+---
+
+## Alternatives Considered
+
+### For `sprite` (ephemeral agent)
+
+| Keyword | Origin | Rejected because |
+|---------|--------|------------------|
+| `spark` | English | Good but less folklore |
+| `wisp` | English | Too insubstantial |
+| `herald` | English | More messenger than worker |
+| `courier` | French | Good functional alternative, not literary |
+| `envoy` | French | Formal, diplomatic |
+
+### For `shade` (persistent agent, if implemented)
+
+| Keyword | Origin | Rejected because |
+|---------|--------|------------------|
+| `daemon` | Greek/Unix | Unix "always running" connotation |
+| `oracle` | Greek | Too "read-only" feeling |
+| `spirit` | Latin | Too close to `sprite` |
+| `specter` | Latin | Negative/spooky connotation |
+| `genius` | Roman | Overloaded (smart person) |
+
+### For `ensemble` (parallel)
+
+| Keyword | Origin | Rejected because |
+|---------|--------|------------------|
+| `chorus` | Greek | Everyone speaks same thing, not different |
+| `troupe` | French | Good alternative, slightly less clear |
+| `company` | Theatre | Overloaded (business) |
+
+### For `crossroads` (choice)
+
+| Keyword | Origin | Rejected because |
+|---------|--------|------------------|
+| `fork` | Path | Too technical (git fork) |
+| `branch` | Tree | Also too technical |
+| `divergence` | Latin | Too abstract |
+
+---
+
+## Verdict
+
+Preserved for benchmarking against the functional register. The functional register remains the primary path, but folk provides an interesting data point for:
+
+1. **Learnability** — Which is easier for newcomers?
+2. **Memorability** — Which sticks better?
+3. **Error rates** — Which leads to fewer mistakes?
+4. **Preference** — Which do users actually prefer?
+
+A future experiment could present both registers and measure outcomes.
@@ -0,0 +1,346 @@
+---
+role: experimental
+summary: |
+  Homeric register for OpenProse—an epic/heroic alternative keyword set.
+  Heroes, trials, fates, and glory. For benchmarking against the functional register.
+status: draft
+requires: prose.md
+---
+
+# OpenProse Homeric Register
+
+> **This is a skin layer.** It requires `prose.md` to be loaded first. All execution semantics, state management, and VM behavior are defined there. This file only provides keyword translations.
+
+An alternative register for OpenProse that draws from Greek epic poetry—the Iliad, the Odyssey, and the heroic tradition. Programs become quests. Agents become heroes. Outputs become glory won.
+
+## How to Use
+
+1. Load `prose.md` first (execution semantics)
+2. Load this file (keyword translations)
+3. When parsing `.prose` files, accept Homeric keywords as aliases for functional keywords
+4. All execution behavior remains identical—only surface syntax changes
+
+> **Design constraint:** Still aims to be "structured but self-evident" per the language tenets—just self-evident through an epic lens.
+
+---
+
+## Complete Translation Map
+
+### Core Constructs
+
+| Functional | Homeric | Reference |
+|------------|---------|-----------|
+| `agent` | `hero` | The one who acts, who strives |
+| `session` | `trial` | Each task is a labor, a test |
+| `parallel` | `host` | An army moving as one |
+| `block` | `book` | A division of the epic |
+
+### Composition & Binding
+
+| Functional | Homeric | Reference |
+|------------|---------|-----------|
+| `use` | `invoke` | "Sing, O Muse..." — calling upon |
+| `input` | `omen` | Signs from the gods, the given portent |
+| `output` | `glory` | Kleos — the glory won, what endures |
+| `let` | `decree` | Fate declared, spoken into being |
+| `const` | `fate` | Moira — unchangeable destiny |
+| `context` | `tidings` | News carried by herald or messenger |
+
+### Control Flow
+
+| Functional | Homeric | Reference |
+|------------|---------|-----------|
+| `repeat N` | `N labors` | The labors of Heracles |
+| `for...in` | `for each...among` | Among the host |
+| `loop` | `ordeal` | Repeated trial, suffering that continues |
+| `until` | `until` | Unchanged |
+| `while` | `while` | Unchanged |
+| `choice` | `crossroads` | Where fates diverge |
+| `option` | `path` | One road of many |
+| `if` | `should` | Epic conditional |
+| `elif` | `or should` | Continued conditional |
+| `else` | `otherwise` | The alternative fate |
+
+### Error Handling
+
+| Functional | Homeric | Reference |
+|------------|---------|-----------|
+| `try` | `venture` | Setting forth on the journey |
+| `catch` | `should ruin come` | Até — divine ruin, disaster |
+| `finally` | `in the end` | The inevitable conclusion |
+| `throw` | `lament` | The hero's cry of anguish |
+| `retry` | `persist` | Enduring, trying again |
+
+### Session Properties
+
+| Functional | Homeric | Reference |
+|------------|---------|-----------|
+| `prompt` | `charge` | The quest given |
+| `model` | `muse` | Which muse inspires |
+
+### Unchanged
+
+These keywords already work or are too functional to replace sensibly:
+
+- `**...**` discretion markers — already work
+- `until`, `while` — already work
+- `map`, `filter`, `reduce`, `pmap` — pipeline operators
+- `max` — constraint modifier
+- `as` — aliasing
+- Model names: `sonnet`, `opus`, `haiku` — already poetic
+
+---
+
+## Side-by-Side Comparison
+
+### Simple Program
+
+```prose
+# Functional
+use "@alice/research" as research
+input topic: "What to investigate"
+
+agent helper:
+  model: sonnet
+
+let findings = session: helper
+  prompt: "Research {topic}"
+
+output summary = session "Summarize"
+  context: findings
+```
+
+```prose
+# Homeric
+invoke "@alice/research" as research
+omen topic: "What to investigate"
+
+hero helper:
+  muse: sonnet
+
+decree findings = trial: helper
+  charge: "Research {topic}"
+
+glory summary = trial "Summarize"
+  tidings: findings
+```
+
+### Parallel Execution
+
+```prose
+# Functional
+parallel:
+  security = session "Check security"
+  perf = session "Check performance"
+  style = session "Check style"
+
+session "Synthesize review"
+  context: { security, perf, style }
+```
+
+```prose
+# Homeric
+host:
+  security = trial "Check security"
+  perf = trial "Check performance"
+  style = trial "Check style"
+
+trial "Synthesize review"
+  tidings: { security, perf, style }
+```
+
+### Loop with Condition
+
+```prose
+# Functional
+loop until **the code is bug-free** (max: 5):
+  session "Find and fix bugs"
+```
+
+```prose
+# Homeric
+ordeal until **the code is bug-free** (max: 5):
+  trial "Find and fix bugs"
+```
+
+### Error Handling
+
+```prose
+# Functional
+try:
+  session "Risky operation"
+catch as err:
+  session "Handle error"
+    context: err
+finally:
+  session "Cleanup"
+```
+
+```prose
+# Homeric
+venture:
+  trial "Risky operation"
+should ruin come as err:
+  trial "Handle error"
+    tidings: err
+in the end:
+  trial "Cleanup"
+```
+
+### Choice Block
+
+```prose
+# Functional
+choice **the severity level**:
+  option "Critical":
+    session "Escalate immediately"
+  option "Minor":
+    session "Log for later"
+```
+
+```prose
+# Homeric
+crossroads **the severity level**:
+  path "Critical":
+    trial "Escalate immediately"
+  path "Minor":
+    trial "Log for later"
+```
+
+### Conditionals
+
+```prose
+# Functional
+if **has security issues**:
+  session "Fix security"
+elif **has performance issues**:
+  session "Optimize"
+else:
+  session "Approve"
+```
+
+```prose
+# Homeric
+should **has security issues**:
+  trial "Fix security"
+or should **has performance issues**:
+  trial "Optimize"
+otherwise:
+  trial "Approve"
+```
+
+### Reusable Blocks
+
+```prose
+# Functional
+block review(topic):
+  session "Research {topic}"
+  session "Analyze {topic}"
+
+do review("quantum computing")
+```
+
+```prose
+# Homeric
+book review(topic):
+  trial "Research {topic}"
+  trial "Analyze {topic}"
+
+do review("quantum computing")
+```
+
+### Fixed Iteration
+
+```prose
+# Functional
+repeat 12:
+  session "Complete task"
+```
+
+```prose
+# Homeric
+12 labors:
+  trial "Complete task"
+```
+
+### Immutable Binding
+
+```prose
+# Functional
+const config = { model: "opus", retries: 3 }
+```
+
+```prose
+# Homeric
+fate config = { muse: "opus", persist: 3 }
+```
+
+---
+
+## The Case For Homeric
+
+1. **Universal recognition.** Greek epics are foundational to Western literature.
+2. **Heroic framing.** Transforms mundane tasks into glorious trials.
+3. **Natural fit.** Heroes face trials, receive tidings, win glory—maps cleanly to agent/session/output.
+4. **Gravitas.** When you want programs to feel epic and consequential.
+5. **Fate vs decree.** `const` as `fate` (unchangeable) vs `let` as `decree` (declared but mutable) is intuitive.
+
+## The Case Against Homeric
+
+1. **Grandiosity mismatch.** "12 labors" for a simple loop may feel overblown.
+2. **Western-centric.** Greek epic tradition is culturally specific.
+3. **Limited vocabulary.** Fewer distinctive terms than Borges or folk.
+4. **Potentially silly.** Heroic language for mundane tasks risks bathos.
+
+---
+
+## Key Homeric Concepts
+
+| Term | Meaning | Used for |
+|------|---------|----------|
+| Kleos | Glory, fame that outlives you | `output` → `glory` |
+| Moira | Fate, one's allotted portion | `const` → `fate` |
+| Até | Divine ruin, blindness sent by gods | `catch` → `should ruin come` |
+| Nostos | The return journey | (not used, but could be `finally`) |
+| Xenia | Guest-friendship, hospitality | (not used) |
+| Muse | Divine inspiration | `model` → `muse` |
+
+---
+
+## Alternatives Considered
+
+### For `hero` (agent)
+
+| Keyword | Rejected because |
+|---------|------------------|
+| `champion` | More medieval than Homeric |
+| `warrior` | Too martial, not all tasks are battles |
+| `wanderer` | Too passive |
+
+### For `trial` (session)
+
+| Keyword | Rejected because |
+|---------|------------------|
+| `labor` | Good but reserved for `repeat N labors` |
+| `quest` | More medieval/RPG |
+| `task` | Too plain |
+
+### For `host` (parallel)
+
+| Keyword | Rejected because |
+|---------|------------------|
+| `army` | Too specifically martial |
+| `fleet` | Only works for naval metaphors |
+| `phalanx` | Too technical |
+
+---
+
+## Verdict
+
+Preserved for benchmarking. The Homeric register offers gravitas and heroic framing. Best suited for:
+
+- Programs that feel like epic undertakings
+- Users who enjoy classical references
+- Contexts where "glory" as output feels appropriate
+
+May cause unintentional bathos when applied to mundane tasks.
@@ -0,0 +1,373 @@
+---
+role: experimental
+summary: |
+  Kafka register for OpenProse—a bureaucratic/absurdist alternative keyword set.
+  Clerks, proceedings, petitions, and statutes. For benchmarking against the functional register.
+status: draft
+requires: prose.md
+---
+
+# OpenProse Kafka Register
+
+> **This is a skin layer.** It requires `prose.md` to be loaded first. All execution semantics, state management, and VM behavior are defined there. This file only provides keyword translations.
+
+An alternative register for OpenProse that draws from the works of Franz Kafka—The Trial, The Castle, "In the Penal Colony." Programs become proceedings. Agents become clerks. Everything is a process, and nobody quite knows the rules.
+
+## How to Use
+
+1. Load `prose.md` first (execution semantics)
+2. Load this file (keyword translations)
+3. When parsing `.prose` files, accept Kafka keywords as aliases for functional keywords
+4. All execution behavior remains identical—only surface syntax changes
+
+> **Design constraint:** Still aims to be "structured but self-evident" per the language tenets—just self-evident through a bureaucratic lens. (The irony is intentional.)
+
+---
+
+## Complete Translation Map
+
+### Core Constructs
+
+| Functional | Kafka | Reference |
+|------------|-------|-----------|
+| `agent` | `clerk` | A functionary in the apparatus |
+| `session` | `proceeding` | An official action taken |
+| `parallel` | `departments` | Multiple bureaus acting simultaneously |
+| `block` | `regulation` | A codified procedure |
+
+### Composition & Binding
+
+| Functional | Kafka | Reference |
+|------------|-------|-----------|
+| `use` | `requisition` | Requesting from the archives |
+| `input` | `petition` | What is submitted for consideration |
+| `output` | `verdict` | What is returned by the apparatus |
+| `let` | `file` | Recording in the system |
+| `const` | `statute` | Unchangeable law |
+| `context` | `dossier` | The accumulated file on a case |
+
+### Control Flow
+
+| Functional | Kafka | Reference |
+|------------|-------|-----------|
+| `repeat N` | `N hearings` | Repeated appearances before the court |
+| `for...in` | `for each...in the matter of` | Bureaucratic iteration |
+| `loop` | `appeal` | Endless re-petition, the process continues |
+| `until` | `until` | Unchanged |
+| `while` | `while` | Unchanged |
+| `choice` | `tribunal` | Where judgment is rendered |
+| `option` | `ruling` | One possible judgment |
+| `if` | `in the event that` | Bureaucratic conditional |
+| `elif` | `or in the event that` | Continued conditional |
+| `else` | `otherwise` | Default ruling |
+
+### Error Handling
+
+| Functional | Kafka | Reference |
+|------------|-------|-----------|
+| `try` | `submit` | Submitting for processing |
+| `catch` | `should it be denied` | Rejection by the apparatus |
+| `finally` | `regardless` | What happens no matter the outcome |
+| `throw` | `reject` | The system refuses |
+| `retry` | `resubmit` | Try the process again |
+
+### Session Properties
+
+| Functional | Kafka | Reference |
+|------------|-------|-----------|
+| `prompt` | `directive` | Official instructions |
+| `model` | `authority` | Which level of the hierarchy |
+
+### Unchanged
+
+These keywords already work or are too functional to replace sensibly:
+
+- `**...**` discretion markers — the inscrutable judgment of the apparatus
+- `until`, `while` — already work
+- `map`, `filter`, `reduce`, `pmap` — pipeline operators
+- `max` — constraint modifier
+- `as` — aliasing
+- Model names: `sonnet`, `opus`, `haiku` — retained (or see "authority" above)
+
+---
+
+## Side-by-Side Comparison
+
+### Simple Program
+
+```prose
+# Functional
+use "@alice/research" as research
+input topic: "What to investigate"
+
+agent helper:
+  model: sonnet
+
+let findings = session: helper
+  prompt: "Research {topic}"
+
+output summary = session "Summarize"
+  context: findings
+```
+
+```prose
+# Kafka
+requisition "@alice/research" as research
+petition topic: "What to investigate"
+
+clerk helper:
+  authority: sonnet
+
+file findings = proceeding: helper
+  directive: "Research {topic}"
+
+verdict summary = proceeding "Summarize"
+  dossier: findings
+```
+
+### Parallel Execution
+
+```prose
+# Functional
+parallel:
+  security = session "Check security"
+  perf = session "Check performance"
+  style = session "Check style"
+
+session "Synthesize review"
+  context: { security, perf, style }
+```
+
+```prose
+# Kafka
+departments:
+  security = proceeding "Check security"
+  perf = proceeding "Check performance"
+  style = proceeding "Check style"
+
+proceeding "Synthesize review"
+  dossier: { security, perf, style }
+```
+
+### Loop with Condition
+
+```prose
+# Functional
+loop until **the code is bug-free** (max: 5):
+  session "Find and fix bugs"
+```
+
+```prose
+# Kafka
+appeal until **the code is bug-free** (max: 5):
+  proceeding "Find and fix bugs"
+```
+
+### Error Handling
+
+```prose
+# Functional
+try:
+  session "Risky operation"
+catch as err:
+  session "Handle error"
+    context: err
+finally:
+  session "Cleanup"
+```
+
+```prose
+# Kafka
+submit:
+  proceeding "Risky operation"
+should it be denied as err:
+  proceeding "Handle error"
+    dossier: err
+regardless:
+  proceeding "Cleanup"
+```
+
+### Choice Block
+
+```prose
+# Functional
+choice **the severity level**:
+  option "Critical":
+    session "Escalate immediately"
+  option "Minor":
+    session "Log for later"
+```
+
+```prose
+# Kafka
+tribunal **the severity level**:
+  ruling "Critical":
+    proceeding "Escalate immediately"
+  ruling "Minor":
+    proceeding "Log for later"
+```
+
+### Conditionals
+
+```prose
+# Functional
+if **has security issues**:
+  session "Fix security"
+elif **has performance issues**:
+  session "Optimize"
+else:
+  session "Approve"
+```
+
+```prose
+# Kafka
+in the event that **has security issues**:
+  proceeding "Fix security"
+or in the event that **has performance issues**:
+  proceeding "Optimize"
+otherwise:
+  proceeding "Approve"
+```
+
+### Reusable Blocks
+
+```prose
+# Functional
+block review(topic):
+  session "Research {topic}"
+  session "Analyze {topic}"
+
+do review("quantum computing")
+```
+
+```prose
+# Kafka
+regulation review(topic):
+  proceeding "Research {topic}"
+  proceeding "Analyze {topic}"
+
+invoke review("quantum computing")
+```
+
+### Fixed Iteration
+
+```prose
+# Functional
+repeat 3:
+  session "Attempt connection"
+```
+
+```prose
+# Kafka
+3 hearings:
+  proceeding "Attempt connection"
+```
+
+### Immutable Binding
+
+```prose
+# Functional
+const config = { model: "opus", retries: 3 }
+```
+
+```prose
+# Kafka
+statute config = { authority: "opus", resubmit: 3 }
+```
+
+---
+
+## The Case For Kafka
+
+1. **Darkly comic.** Programs-as-bureaucracy is funny and relatable.
+2. **Surprisingly apt.** Software often *is* an inscrutable apparatus.
+3. **Clean mappings.** Petition/verdict, file/dossier, clerk/proceeding all work well.
+4. **Appeal as loop.** The endless appeal process is a perfect metaphor for retry logic.
+5. **Cultural resonance.** "Kafkaesque" is a widely understood adjective.
+6. **Self-aware.** Using Kafka for a programming language acknowledges the absurdity.
+
+## The Case Against Kafka
+
+1. **Bleak tone.** Not everyone wants their programs to feel like The Trial.
+2. **Verbose keywords.** "In the event that" and "should it be denied" are long.
+3. **Anxiety-inducing.** May not be fun for users who find bureaucracy stressful.
+4. **Irony may not land.** Some users might take it literally and find it off-putting.
+
+---
+
+## Key Kafka Concepts
+
+| Term | Meaning | Used for |
+|------|---------|----------|
+| The apparatus | The inscrutable system | The VM itself |
+| K. | The protagonist, never fully named | The user |
+| The Trial | Process without clear rules | Program execution |
+| The Castle | Unreachable authority | Higher-level systems |
+| Clerk | Functionary who processes | `agent` → `clerk` |
+| Proceeding | Official action | `session` → `proceeding` |
+| Dossier | Accumulated file | `context` → `dossier` |
+
+---
+
+## Alternatives Considered
+
+### For `clerk` (agent)
+
+| Keyword | Rejected because |
+|---------|------------------|
+| `official` | Too generic |
+| `functionary` | Hard to spell |
+| `bureaucrat` | Too pejorative |
+| `advocate` | Too positive/helpful |
+
+### For `proceeding` (session)
+
+| Keyword | Rejected because |
+|---------|------------------|
+| `case` | Overloaded (switch case) |
+| `hearing` | Reserved for `repeat N hearings` |
+| `trial` | Used in Homeric register |
+| `process` | Too technical |
+
+### For `departments` (parallel)
+
+| Keyword | Rejected because |
+|---------|------------------|
+| `bureaus` | Good alternative, slightly less clear |
+| `offices` | Too mundane |
+| `ministries` | More Orwellian than Kafkaesque |
+
+### For `appeal` (loop)
+
+| Keyword | Rejected because |
+|---------|------------------|
+| `recourse` | Too legal-technical |
+| `petition` | Used for `input` |
+| `process` | Too generic |
+
+---
+
+## Verdict
+
+Preserved for benchmarking. The Kafka register offers a darkly comic, self-aware framing that acknowledges the bureaucratic nature of software systems. The irony is the point.
+
+Best suited for:
+
+- Users with a sense of humor about software complexity
+- Programs that genuinely feel like navigating bureaucracy
+- Contexts where acknowledging absurdity is welcome
+
+Not recommended for:
+
+- Users who find bureaucratic metaphors stressful
+- Contexts requiring earnest, positive framing
+- Documentation that needs to feel approachable
+
+---
+
+## Closing Note
+
+> "Someone must have slandered Josef K., for one morning, without having done anything wrong, he was arrested."
+> — *The Trial*
+
+In the Kafka register, your program is Josef K. The apparatus will process it. Whether it succeeds or fails, no one can say for certain. But the proceedings will continue.
@@ -0,0 +1,4 @@
+# Hello World
+# The simplest OpenProse program - a single session
+
+session "Say hello and briefly introduce yourself"
@@ -0,0 +1,6 @@
+# Research and Summarize
+# A two-step workflow: research a topic, then summarize findings
+
+session "Research the latest developments in AI agents and multi-agent systems. Focus on papers and announcements from the past 6 months."
+
+session "Summarize the key findings from your research in 5 bullet points. Focus on practical implications for developers."
@@ -0,0 +1,17 @@
+# Code Review Pipeline
+# Review code from multiple perspectives sequentially
+
+# First, understand what the code does
+session "Read the files in src/ and provide a brief overview of the codebase structure and purpose."
+
+# Security review
+session "Review the code for security vulnerabilities. Look for injection risks, authentication issues, and data exposure."
+
+# Performance review
+session "Review the code for performance issues. Look for N+1 queries, unnecessary allocations, and blocking operations."
+
+# Maintainability review
+session "Review the code for maintainability. Look for code duplication, unclear naming, and missing documentation."
+
+# Synthesize findings
+session "Create a unified code review report combining all the findings above. Prioritize issues by severity and provide actionable recommendations."
@@ -0,0 +1,14 @@
+# Write and Refine
+# Draft content, then iteratively improve it
+
+# Create initial draft
+session "Write a first draft of a README.md for this project. Include sections for: overview, installation, usage, and contributing."
+
+# Self-review and improve
+session "Review the README draft you just wrote. Identify areas that are unclear, too verbose, or missing important details."
+
+# Apply improvements
+session "Rewrite the README incorporating your review feedback. Make it more concise and add any missing sections."
+
+# Final polish
+session "Do a final pass on the README. Fix any typos, improve formatting, and ensure code examples are correct."
@@ -0,0 +1,20 @@
+# Debug an Issue
+# Step-by-step debugging workflow
+
+# Understand the problem
+session "Read the error message and stack trace. Identify which file and function is causing the issue."
+
+# Gather context
+session "Read the relevant source files and understand the code flow that leads to the error."
+
+# Form hypothesis
+session "Based on your investigation, form a hypothesis about what's causing the bug. List 2-3 possible root causes."
+
+# Test hypothesis
+session "Write a test case that reproduces the bug. This will help verify the fix later."
+
+# Implement fix
+session "Implement a fix for the most likely root cause. Explain your changes."
+
+# Verify fix
+session "Run the test suite to verify the fix works and doesn't break anything else."
@@ -0,0 +1,17 @@
+# Explain Codebase
+# Progressive exploration of an unfamiliar codebase
+
+# Start with the big picture
+session "List all directories and key files in this repository. Provide a high-level map of the project structure."
+
+# Understand the entry point
+session "Find the main entry point of the application. Explain how the program starts and initializes."
+
+# Trace a key flow
+session "Trace through a typical user request from start to finish. Document the key functions and modules involved."
+
+# Document architecture
+session "Based on your exploration, write a brief architecture document explaining how the major components fit together."
+
+# Identify patterns
+session "What design patterns and conventions does this codebase use? Document any patterns future contributors should follow."
@@ -0,0 +1,20 @@
+# Refactor Code
+# Systematic refactoring workflow
+
+# Assess current state
+session "Analyze the target code and identify code smells: duplication, long functions, unclear naming, tight coupling."
+
+# Plan refactoring
+session "Create a refactoring plan. List specific changes in order of priority, starting with the safest changes."
+
+# Ensure test coverage
+session "Check test coverage for the code being refactored. Add any missing tests before making changes."
+
+# Execute refactoring
+session "Implement the first refactoring from your plan. Make a single focused change."
+
+# Verify behavior
+session "Run tests to verify the refactoring preserved behavior. If tests fail, investigate and fix."
+
+# Document changes
+session "Update any documentation affected by the refactoring. Add comments explaining non-obvious design decisions."
@@ -0,0 +1,20 @@
+# Write a Blog Post
+# End-to-end content creation workflow
+
+# Research the topic
+session "Research the topic: 'Best practices for error handling in TypeScript'. Find authoritative sources and common patterns."
+
+# Create outline
+session "Create a detailed outline for the blog post. Include introduction, 4-5 main sections, and conclusion."
+
+# Write first draft
+session "Write the full blog post following the outline. Target 1500-2000 words. Include code examples."
+
+# Technical review
+session "Review the blog post for technical accuracy. Verify all code examples compile and work correctly."
+
+# Editorial review
+session "Review the blog post for clarity and readability. Simplify complex sentences and improve flow."
+
+# Add finishing touches
+session "Add a compelling title, meta description, and suggest 3-5 relevant tags for the post."
@@ -0,0 +1,25 @@
+# Research Pipeline with Specialized Agents
+# This example demonstrates defining agents with different models
+# and using them in sessions with property overrides.
+
+# Define specialized agents
+agent researcher:
+  model: sonnet
+  prompt: "You are a research assistant skilled at finding and synthesizing information"
+
+agent writer:
+  model: opus
+  prompt: "You are a technical writer who creates clear, concise documentation"
+
+# Step 1: Initial research with the researcher agent
+session: researcher
+  prompt: "Research recent developments in renewable energy storage technologies"
+
+# Step 2: Deep dive with a more powerful model
+session: researcher
+  model: opus
+  prompt: "Analyze the top 3 most promising battery technologies and their potential impact"
+
+# Step 3: Write up the findings
+session: writer
+  prompt: "Create a summary report of the research findings suitable for executives"
@@ -0,0 +1,32 @@
+# Code Review Workflow with Agents
+# This example shows how to use agents for a multi-step code review process.
+
+# Define agents with specific roles
+agent security-reviewer:
+  model: opus
+  prompt: "You are a security expert focused on identifying vulnerabilities"
+
+agent performance-reviewer:
+  model: sonnet
+  prompt: "You are a performance optimization specialist"
+
+agent style-reviewer:
+  model: haiku
+  prompt: "You check for code style and best practices"
+
+# Step 1: Quick style check (fast)
+session: style-reviewer
+  prompt: "Review the code in src/ for style issues and naming conventions"
+
+# Step 2: Performance analysis (medium)
+session: performance-reviewer
+  prompt: "Identify any performance bottlenecks or optimization opportunities"
+
+# Step 3: Security audit (thorough)
+session: security-reviewer
+  prompt: "Perform a security review looking for OWASP top 10 vulnerabilities"
+
+# Step 4: Summary
+session: security-reviewer
+  model: sonnet
+  prompt: "Create a consolidated report of all review findings with priority rankings"
@@ -0,0 +1,27 @@
+# Skills and Imports Example
+# This demonstrates importing external skills and assigning them to agents.
+
+# Import skills from external sources
+import "web-search" from "github:anthropic/skills"
+import "summarizer" from "npm:@example/summarizer"
+import "file-reader" from "./local-skills/file-reader"
+
+# Define a research agent with web search capability
+agent researcher:
+  model: sonnet
+  prompt: "You are a research assistant skilled at finding information"
+  skills: ["web-search", "summarizer"]
+
+# Define a documentation agent with file access
+agent documenter:
+  model: opus
+  prompt: "You create comprehensive documentation"
+  skills: ["file-reader", "summarizer"]
+
+# Research phase
+session: researcher
+  prompt: "Search for recent developments in renewable energy storage"
+
+# Documentation phase
+session: documenter
+  prompt: "Create a technical summary of the research findings"
@@ -0,0 +1,43 @@
+# Secure Agent with Permissions Example
+# This demonstrates defining agents with restricted access permissions.
+
+# Import required skills
+import "code-analyzer" from "github:anthropic/code-tools"
+
+# Define a read-only code reviewer
+# This agent can read source files but cannot modify them or run shell commands
+agent code-reviewer:
+  model: sonnet
+  prompt: "You are a thorough code reviewer"
+  skills: ["code-analyzer"]
+  permissions:
+    read: ["src/**/*.ts", "src/**/*.js", "*.md"]
+    write: []
+    bash: deny
+
+# Define a documentation writer with limited write access
+# Can only write to docs directory
+agent doc-writer:
+  model: opus
+  prompt: "You write technical documentation"
+  permissions:
+    read: ["src/**/*", "docs/**/*"]
+    write: ["docs/**/*.md"]
+    bash: deny
+
+# Define a full-access admin agent
+agent admin:
+  model: opus
+  prompt: "You perform administrative tasks"
+  permissions:
+    read: ["**/*"]
+    write: ["**/*"]
+    bash: prompt
+    network: allow
+
+# Workflow: Code review followed by documentation update
+session: code-reviewer
+  prompt: "Review the codebase for security issues and best practices"
+
+session: doc-writer
+  prompt: "Update the documentation based on the code review findings"
@@ -0,0 +1,51 @@
+# Example 13: Variables & Context
+#
+# This example demonstrates using let/const bindings to capture session
+# outputs and pass them as context to subsequent sessions.
+
+# Define specialized agents for the workflow
+agent researcher:
+  model: sonnet
+  prompt: "You are a thorough research assistant who gathers comprehensive information on topics."
+
+agent analyst:
+  model: opus
+  prompt: "You are a data analyst who identifies patterns, trends, and key insights."
+
+agent writer:
+  model: opus
+  prompt: "You are a technical writer who creates clear, well-structured documents."
+
+# Step 1: Gather initial research (captured in a variable)
+let research = session: researcher
+  prompt: "Research the current state of quantum computing, including recent breakthroughs, major players, and potential applications."
+
+# Step 2: Analyze the research findings (using research as context)
+let analysis = session: analyst
+  prompt: "Analyze the key findings and identify the most promising directions."
+  context: research
+
+# Step 3: Get additional perspectives (refreshing context)
+let market-trends = session: researcher
+  prompt: "Research market trends and commercial applications of quantum computing."
+  context: []
+
+# Step 4: Combine multiple contexts for final synthesis
+const report = session: writer
+  prompt: "Write a comprehensive executive summary covering research, analysis, and market trends."
+  context: [research, analysis, market-trends]
+
+# Step 5: Iterative refinement with variable reassignment
+let draft = session: writer
+  prompt: "Create an initial draft of the technical deep-dive section."
+  context: research
+
+# Refine the draft using its own output as context
+draft = session: writer
+  prompt: "Review and improve this draft for clarity and technical accuracy."
+  context: draft
+
+# Final polish
+draft = session: writer
+  prompt: "Perform final editorial review and polish the document."
+  context: draft
@@ -0,0 +1,48 @@
+# Example 14: Composition Blocks
+# Demonstrates do: blocks, block definitions, and inline sequences
+
+# Define reusable agents
+agent researcher:
+  model: sonnet
+  prompt: "You are a thorough research assistant"
+
+agent writer:
+  model: opus
+  prompt: "You are a skilled technical writer"
+
+agent reviewer:
+  model: sonnet
+  prompt: "You are a careful code and document reviewer"
+
+# Define a reusable research block
+block research-phase:
+  session: researcher
+    prompt: "Gather information on the topic"
+  session: researcher
+    prompt: "Analyze key findings"
+
+# Define a reusable writing block
+block writing-phase:
+  session: writer
+    prompt: "Write initial draft"
+  session: writer
+    prompt: "Polish and refine the draft"
+
+# Define a review block
+block review-cycle:
+  session: reviewer
+    prompt: "Review for accuracy"
+  session: reviewer
+    prompt: "Review for clarity"
+
+# Main workflow using blocks
+let research = do research-phase
+
+let document = do writing-phase
+
+do review-cycle
+
+# Use anonymous do block for final steps
+do:
+  session "Incorporate review feedback"
+  session "Prepare final version"
@@ -0,0 +1,23 @@
+# Example 15: Inline Sequences
+# Demonstrates the -> operator for chaining sessions
+
+# Quick pipeline using arrow syntax
+session "Plan the task" -> session "Execute the plan" -> session "Review results"
+
+# Inline sequence with context capture
+let analysis = session "Analyze data" -> session "Draw conclusions"
+
+session "Write report"
+  context: analysis
+
+# Combine inline sequences with blocks
+block quick-check:
+  session "Security scan" -> session "Performance check"
+
+do quick-check
+
+# Use inline sequence in variable assignment
+let workflow = session "Step 1" -> session "Step 2" -> session "Step 3"
+
+session "Final step"
+  context: workflow
@@ -0,0 +1,19 @@
+# Parallel Code Reviews
+# Run multiple specialized reviews concurrently
+
+agent reviewer:
+  model: sonnet
+  prompt: "You are an expert code reviewer"
+
+# Run all reviews in parallel
+parallel:
+  security = session: reviewer
+    prompt: "Review for security vulnerabilities"
+  perf = session: reviewer
+    prompt: "Review for performance issues"
+  style = session: reviewer
+    prompt: "Review for code style and readability"
+
+# Synthesize all review results
+session "Create unified code review report"
+  context: { security, perf, style }
@@ -0,0 +1,19 @@
+# Parallel Research
+# Gather information from multiple sources concurrently
+
+agent researcher:
+  model: sonnet
+  prompt: "You are a research assistant"
+
+# Research multiple aspects in parallel
+parallel:
+  history = session: researcher
+    prompt: "Research the historical background"
+  current = session: researcher
+    prompt: "Research the current state of the field"
+  future = session: researcher
+    prompt: "Research future trends and predictions"
+
+# Combine all research
+session "Write comprehensive research summary"
+  context: { history, current, future }
@@ -0,0 +1,36 @@
+# Mixed Parallel and Sequential Workflow
+# Demonstrates nesting parallel and sequential blocks
+
+agent worker:
+  model: sonnet
+
+# Define reusable blocks
+block setup:
+  session "Initialize resources"
+  session "Validate configuration"
+
+block cleanup:
+  session "Save results"
+  session "Release resources"
+
+# Main workflow with mixed composition
+do:
+  do setup
+
+  # Parallel processing phase
+  parallel:
+    # Each parallel branch can have multiple steps
+    do:
+      session: worker
+        prompt: "Process batch 1 - step 1"
+      session: worker
+        prompt: "Process batch 1 - step 2"
+    do:
+      session: worker
+        prompt: "Process batch 2 - step 1"
+      session: worker
+        prompt: "Process batch 2 - step 2"
+
+  session "Aggregate results"
+
+  do cleanup
@@ -0,0 +1,71 @@
+# Advanced Parallel Execution (Tier 7)
+#
+# Demonstrates join strategies and failure policies
+# for parallel blocks.
+
+agent researcher:
+  model: haiku
+  prompt: "You are a research assistant. Provide concise information."
+
+# 1. Race Pattern: First to Complete Wins
+# ----------------------------------------
+# Use parallel ("first") when you want the fastest result
+# and don't need all branches to complete.
+
+parallel ("first"):
+  session: researcher
+    prompt: "Find information via approach A"
+  session: researcher
+    prompt: "Find information via approach B"
+  session: researcher
+    prompt: "Find information via approach C"
+
+session "Summarize: only the fastest approach completed"
+
+# 2. Any-N Pattern: Get Multiple Quick Results
+# --------------------------------------------
+# Use parallel ("any", count: N) when you need N results
+# but not necessarily all of them.
+
+parallel ("any", count: 2):
+  a = session "Generate a creative headline for a tech blog"
+  b = session "Generate a catchy headline for a tech blog"
+  c = session "Generate an engaging headline for a tech blog"
+  d = session "Generate a viral headline for a tech blog"
+
+session "Choose the best from the 2 headlines that finished first"
+  context: { a, b, c, d }
+
+# 3. Continue on Failure: Gather All Results
+# ------------------------------------------
+# Use on-fail: "continue" when you want all branches
+# to complete and handle failures afterwards.
+
+parallel (on-fail: "continue"):
+  session "Fetch data from primary API"
+  session "Fetch data from secondary API"
+  session "Fetch data from backup API"
+
+session "Combine all available data, noting any failures"
+
+# 4. Ignore Failures: Best-Effort Enrichment
+# ------------------------------------------
+# Use on-fail: "ignore" for optional enrichments
+# where failures shouldn't block progress.
+
+parallel (on-fail: "ignore"):
+  session "Get optional metadata enrichment 1"
+  session "Get optional metadata enrichment 2"
+  session "Get optional metadata enrichment 3"
+
+session "Continue with whatever enrichments succeeded"
+
+# 5. Combined: Race with Resilience
+# ---------------------------------
+# Combine join strategies with failure policies.
+
+parallel ("first", on-fail: "continue"):
+  session "Fast but might fail"
+  session "Slow but reliable"
+
+session "Got the first result, even if it was a handled failure"
@@ -0,0 +1,20 @@
+# Example: Fixed Loops in OpenProse
+# Demonstrates repeat, for-each, and parallel for-each patterns
+
+# Repeat block - generate multiple ideas
+repeat 3:
+  session "Generate a creative app idea"
+
+# For-each block - iterate over a collection
+let features = ["authentication", "dashboard", "notifications"]
+for feature in features:
+  session "Design the user interface for this feature"
+    context: feature
+
+# Parallel for-each - research in parallel
+let topics = ["market size", "competitors", "technology stack"]
+parallel for topic in topics:
+  session "Research this aspect of the startup idea"
+    context: topic
+
+session "Synthesize all research into a business plan"
@@ -0,0 +1,35 @@
+# Pipeline Operations Example
+# Demonstrates functional-style collection transformations
+
+# Define a collection of startup ideas
+let ideas = ["AI tutor", "smart garden", "fitness tracker", "meal planner", "travel assistant"]
+
+# Filter to keep only tech-focused ideas
+let tech_ideas = ideas | filter:
+  session "Is this idea primarily technology-focused? Answer yes or no."
+    context: item
+
+# Map to expand each idea into a business pitch
+let pitches = tech_ideas | map:
+  session "Write a compelling one-paragraph business pitch for this idea"
+    context: item
+
+# Reduce all pitches into a portfolio summary
+let portfolio = pitches | reduce(summary, pitch):
+  session "Integrate this pitch into the portfolio summary, maintaining coherence"
+    context: [summary, pitch]
+
+# Present the final portfolio
+session "Format and present the startup portfolio as a polished document"
+  context: portfolio
+
+# Parallel map example - research multiple topics concurrently
+let topics = ["market analysis", "competition", "funding options"]
+
+let research = topics | pmap:
+  session "Research this aspect of the startup portfolio"
+    context: item
+
+# Final synthesis
+session "Create an executive summary combining all research findings"
+  context: research
@@ -0,0 +1,51 @@
+# Error Handling Example
+# Demonstrates try/catch/finally patterns for resilient workflows
+
+# Basic try/catch for error recovery
+try:
+  session "Attempt to fetch data from external API"
+catch:
+  session "API failed - use cached data instead"
+
+# Catch with error variable for context-aware handling
+try:
+  session "Parse and validate complex configuration file"
+catch as err:
+  session "Handle the configuration error"
+    context: err
+
+# Try/catch/finally for resource cleanup
+try:
+  session "Open database connection and perform queries"
+catch:
+  session "Log database error and notify admin"
+finally:
+  session "Ensure database connection is properly closed"
+
+# Nested error handling
+try:
+  session "Start outer transaction"
+  try:
+    session "Perform risky inner operation"
+  catch:
+    session "Recover inner operation"
+    throw  # Re-raise to outer handler
+catch:
+  session "Handle re-raised error at outer level"
+
+# Error handling in parallel blocks
+parallel:
+  try:
+    session "Service A - might fail"
+  catch:
+    session "Fallback for Service A"
+  try:
+    session "Service B - might fail"
+  catch:
+    session "Fallback for Service B"
+
+session "Continue with whatever results we got"
+
+# Throwing custom errors
+session "Validate input data"
+throw "Validation failed: missing required fields"
@@ -0,0 +1,63 @@
+# Retry with Backoff Example
+# Demonstrates automatic retry patterns for resilient API calls
+
+# Simple retry - try up to 3 times on failure
+session "Call flaky third-party API"
+  retry: 3
+
+# Retry with exponential backoff for rate-limited APIs
+session "Query rate-limited service"
+  retry: 5
+  backoff: "exponential"
+
+# Retry with linear backoff
+session "Send webhook notification"
+  retry: 3
+  backoff: "linear"
+
+# Combining retry with context passing
+let config = session "Load API configuration"
+
+session "Make authenticated API request"
+  context: config
+  retry: 3
+  backoff: "exponential"
+
+# Retry inside try/catch for fallback after all retries fail
+try:
+  session "Call primary payment processor"
+    retry: 3
+    backoff: "exponential"
+catch:
+  session "All retries failed - use backup payment processor"
+    retry: 2
+
+# Parallel retries for redundant services
+parallel:
+  primary = try:
+    session "Query primary database"
+      retry: 2
+      backoff: "linear"
+  catch:
+    session "Primary DB unavailable"
+  replica = try:
+    session "Query replica database"
+      retry: 2
+      backoff: "linear"
+  catch:
+    session "Replica DB unavailable"
+
+session "Merge results from available databases"
+  context: { primary, replica }
+
+# Retry in a loop for batch processing
+let items = ["batch1", "batch2", "batch3"]
+for item in items:
+  try:
+    session "Process this batch item"
+      context: item
+      retry: 2
+      backoff: "exponential"
+  catch:
+    session "Log failed batch for manual review"
+      context: item
@@ -0,0 +1,86 @@
+# Choice Blocks Example
+# Demonstrates AI-selected branching based on runtime criteria
+
+# Simple choice based on analysis
+let analysis = session "Analyze the current codebase quality"
+
+choice **the severity of issues found**:
+  option "Critical":
+    session "Stop all work and fix critical issues immediately"
+      context: analysis
+    session "Create incident report"
+  option "Moderate":
+    session "Schedule fixes for next sprint"
+      context: analysis
+  option "Minor":
+    session "Add to technical debt backlog"
+      context: analysis
+
+# Choice for user experience level
+choice **the user's technical expertise based on their question**:
+  option "Beginner":
+    session "Explain concepts from first principles"
+    session "Provide step-by-step tutorial"
+    session "Include helpful analogies"
+  option "Intermediate":
+    session "Give concise explanation with examples"
+    session "Link to relevant documentation"
+  option "Expert":
+    session "Provide technical deep-dive"
+    session "Include advanced configuration options"
+
+# Choice for project approach
+let requirements = session "Gather project requirements"
+
+choice **the best development approach given the requirements**:
+  option "Rapid prototype":
+    session "Create quick MVP focusing on core features"
+      context: requirements
+    session "Plan iteration cycle"
+  option "Production-ready":
+    session "Design complete architecture"
+      context: requirements
+    session "Set up CI/CD pipeline"
+    session "Implement with full test coverage"
+  option "Research spike":
+    session "Explore technical feasibility"
+      context: requirements
+    session "Document findings and recommendations"
+
+# Multi-line criteria for complex decisions
+let market_data = session "Gather market research data"
+let tech_analysis = session "Analyze technical landscape"
+
+choice ***
+  the optimal market entry strategy
+  considering both market conditions
+  and technical readiness
+***:
+  option "Aggressive launch":
+    session "Prepare for immediate market entry"
+      context: [market_data, tech_analysis]
+  option "Soft launch":
+    session "Plan limited beta release"
+      context: [market_data, tech_analysis]
+  option "Wait and iterate":
+    session "Continue development and monitor market"
+      context: [market_data, tech_analysis]
+
+# Nested choices for detailed decision trees
+let request = session "Analyze incoming customer request"
+
+choice **the type of request**:
+  option "Technical support":
+    choice **the complexity of the technical issue**:
+      option "Simple":
+        session "Provide self-service solution"
+          context: request
+      option "Complex":
+        session "Escalate to senior engineer"
+          context: request
+  option "Sales inquiry":
+    session "Forward to sales team with context"
+      context: request
+  option "Feature request":
+    session "Add to product backlog and notify PM"
+      context: request
@@ -0,0 +1,114 @@
+# Conditionals Example
+# Demonstrates if/elif/else patterns with AI-evaluated conditions
+
+# Simple if statement
+let health_check = session "Check system health status"
+
+if **the system is unhealthy**:
+  session "Alert on-call engineer"
+    context: health_check
+  session "Begin incident response"
+
+# If/else for binary decisions
+let review = session "Review the pull request changes"
+
+if **the code changes are safe and well-tested**:
+  session "Approve and merge the pull request"
+    context: review
+else:
+  session "Request changes with detailed feedback"
+    context: review
+
+# If/elif/else for multiple conditions
+let status = session "Check project milestone status"
+
+if **the project is ahead of schedule**:
+  session "Document success factors"
+  session "Consider adding stretch goals"
+elif **the project is on track**:
+  session "Continue with current plan"
+  session "Prepare status report"
+elif **the project is slightly delayed**:
+  session "Identify bottlenecks"
+  session "Adjust timeline and communicate to stakeholders"
+else:
+  session "Escalate to management"
+  session "Create recovery plan"
+  session "Schedule daily standups"
+
+# Multi-line conditions
+let test_results = session "Run full test suite"
+
+if ***
+  all tests pass
+  and code coverage is above 80%
+  and there are no linting errors
+***:
+  session "Deploy to production"
+else:
+  session "Fix issues before deploying"
+    context: test_results
+
+# Nested conditionals
+let request = session "Analyze the API request"
+
+if **the request is authenticated**:
+  if **the user has admin privileges**:
+    session "Process admin request with full access"
+      context: request
+  else:
+    session "Process standard user request"
+      context: request
+else:
+  session "Return 401 authentication error"
+
+# Conditionals with error handling
+let operation_result = session "Attempt complex operation"
+
+if **the operation succeeded partially**:
+  session "Complete remaining steps"
+    context: operation_result
+
+try:
+  session "Perform another risky operation"
+catch as err:
+  if **the error is recoverable**:
+    session "Apply automatic recovery procedure"
+      context: err
+  else:
+    throw "Unrecoverable error encountered"
+
+# Conditionals inside loops
+let items = ["item1", "item2", "item3"]
+
+for item in items:
+  session "Analyze this item"
+    context: item
+
+  if **the item needs processing**:
+    session "Process the item"
+      context: item
+  elif **the item should be skipped**:
+    session "Log skip reason"
+      context: item
+  else:
+    session "Archive the item"
+      context: item
+
+# Conditionals with parallel blocks
+parallel:
+  security = session "Run security scan"
+  performance = session "Run performance tests"
+  style = session "Run style checks"
+
+if **security issues were found**:
+  session "Fix security issues immediately"
+    context: security
+elif **performance issues were found**:
+  session "Optimize performance bottlenecks"
+    context: performance
+elif **style issues were found**:
+  session "Clean up code style"
+    context: style
+else:
+  session "All checks passed - ready for review"
Author	SHA1	Message	Date
Peter Steinberger	2e089ec9a0	fix: harden compaction status gating (#1466 ) (thanks @dlauer)	2026-01-23 06:32:17 +00:00
Dave Lauer	fd3c76cad3	fix(control-ui): add agentId to DEFAULT_ASSISTANT_IDENTITY TypeScript inferred the union type without agentId when falling back to DEFAULT_ASSISTANT_IDENTITY, causing build errors at control-ui.ts:222-223.	2026-01-23 05:52:04 +00:00
Dave Lauer	8b3e3a4b96	feat(ui): add compaction indicator and improve event error handling Compaction indicator: - Add CompactionStatus type and handleCompactionEvent() in app-tool-stream.ts - Show '🧹 Compacting context...' toast while active (with pulse animation) - Show '🧹 Context compacted' briefly after completion - Auto-clear toast after 5 seconds - Add CSS styles for .callout.info, .callout.success, .compaction-indicator Error handling improvements: - Wrap onEvent callback in try/catch in gateway.ts to prevent errors from breaking the WebSocket message handler - Wrap handleGatewayEvent in try/catch with console.error logging to isolate errors and make them visible in devtools These changes address UI freezes during heavy agent activity by: 1. Showing users when compaction is happening 2. Preventing uncaught errors from silently breaking the event loop	2026-01-23 05:52:04 +00:00
Dave Lauer	e0e39a6d52	feat(compaction): add adaptive chunk sizing and progressive fallback - Add computeAdaptiveChunkRatio() to reduce chunk size for large messages - Add isOversizedForSummary() to detect messages too large to summarize - Add summarizeWithFallback() with progressive fallback: - Tries full summarization first - Falls back to partial summarization excluding oversized messages - Notes oversized messages in the summary output - Add SAFETY_MARGIN (1.2x) buffer for token estimation inaccuracy - Reduce MIN_CHUNK_RATIO to 0.15 for very large messages This prevents compaction failures when conversations contain unusually large tool outputs or responses that exceed the summarization model's context window.	2026-01-23 05:52:04 +00:00
Peter Steinberger	bd7443b39b	docs: update media auto-detect	2026-01-23 05:47:16 +00:00
Peter Steinberger	93bef830ce	test: add media auto-detect coverage	2026-01-23 05:47:13 +00:00
Peter Steinberger	2dfbd1c1f6	feat: improve media auto-detect	2026-01-23 05:47:09 +00:00
Peter Steinberger	1d9f230be4	docs: expand slack replyToModeByChatType examples	2026-01-23 05:38:28 +00:00
Peter Steinberger	9bf295da48	feat: add slack replyToModeByChatType overrides	2026-01-23 05:38:28 +00:00
Peter Steinberger	eebd750781	fix: improve matrix direct room resolution (#1436 ) (thanks @sibbl) (#1486 ) * fix: improve matrix direct room resolution (#1436) (thanks @sibbl) * docs: update changelog for matrix fix (#1486) (thanks @sibbl)	2026-01-23 05:38:04 +00:00
Sebastian Schubotz	aa11300175	fix(matrix): broken import and enhance direct room resolve logic (#1436 ) * fix(matrix): fix broken import again * fix(matrix): improve error handling and fallback logic in resolveDirectRoomId	2026-01-23 05:35:01 +00:00
Stefan Galescu	7b40d1b261	feat(slack): add dm-specific replyToMode configuration (#1442 ) Adds support for separate replyToMode settings for DMs vs channels: - Add channels.slack.dm.replyToMode for DM-specific threading - Keep channels.slack.replyToMode as default for channels - Add resolveSlackReplyToMode helper to centralize logic - Pass chatType through threading resolution chain Usage: ```json5 { channels: { slack: { replyToMode: "off", // channels dm: { replyToMode: "all" // DMs always thread } } } } ``` When dm.replyToMode is set, DMs use that mode; channels use the top-level replyToMode. Backward compatible when not configured.	2026-01-23 05:13:23 +00:00
Peter Steinberger	2c10c601a8	test: harden docker onboarding waits	2026-01-23 05:10:59 +00:00
Travis Irby	578ac9f1a9	hydrate files from thread root message on replies When replying to a Slack thread, files attached to the root message were not being fetched. The existing `resolveSlackThreadStarter()` fetched the root message text via `conversations.replies` but ignored the `files[]` array in the response. Changes: - Add `files` to `SlackThreadStarter` type and extract from API response - Download thread starter files when the reply message has no attachments - Add verbose log for thread starter file hydration Fixes issue where asking about a PDF in a thread reply would fail because the model never received the file content from the root message.	2026-01-23 05:10:36 +00:00
NeoandPeter Steinberger	2accb47e4d	fix: follow soul.md more closely (#1434 ) * Agents: honor SOUL.md persona guidance * fix: harden SOUL.md detection (#1434) (thanks @neooriginal) --------- Co-authored-by: Peter Steinberger <steipete@gmail.com>	2026-01-23 05:00:13 +00:00
Tak hoffman	b65916e0d1	CLI: fix Windows gateway startup	2026-01-23 04:47:01 +00:00
Peter Steinberger	9207840db4	docs: note #1482 in changelog	2026-01-23 04:38:08 +00:00
Peter Steinberger	784468d6c3	fix: harden BlueBubbles voice memos (#1477 ) (thanks @Nicell)	2026-01-23 04:38:08 +00:00
Clawd	02b5f403db	feat(bluebubbles): add asVoice support for voice memos Add asVoice parameter to sendBlueBubblesAttachment that converts audio to iMessage voice memo format (Opus CAF at 48kHz) and sets isAudioMessage flag in the BlueBubbles API. This follows the existing asVoice pattern used by Telegram. - Convert audio to Opus CAF format using ffmpeg when asVoice=true - Set isAudioMessage=true in BlueBubbles attachment API - Pass asVoice through action handler and media-send	2026-01-23 04:34:19 +00:00
Peter Steinberger	5d0d9e6323	feat: refine onboarding hatch flow	2026-01-23 04:32:23 +00:00
Peter Steinberger	64be2b2cd1	test: speed up gateway suite setup	2026-01-23 04:28:02 +00:00
Rodrigo Uroz Peter Steinberger Rodrigo Uroz	dd2400fb2a	fix: read Slack thread replies for message reads (#1450 ) (#1450 ) Co-authored-by: Peter Steinberger <steipete@gmail.com> Co-authored-by: Rodrigo Uroz <rodrigouroz@users.noreply.github.com>	2026-01-23 04:17:45 +00:00
Peter Steinberger	5d001cb953	refactor: add config logging helpers	2026-01-23 04:16:39 +00:00
Peter Steinberger	d23c4a3f10	fix: put plugin descriptions under source	2026-01-23 04:02:42 +00:00
Peter Steinberger	e750ad5e75	refactor: centralize config update logging	2026-01-23 04:01:26 +00:00
Paulo Portella	246ee490f6	docs: add pauloportella to clawtributors	2026-01-23 03:58:57 +00:00
Peter Steinberger	d62a20fba9	chore: add open-prose license	2026-01-23 03:53:03 +00:00
Peter Steinberger	7f68bf79b6	fix: prefer ~ for home paths in output	2026-01-23 03:44:31 +00:00
Peter Steinberger	34bb7250f8	fix: resolve changelog merge markers	2026-01-23 03:44:14 +00:00
Peter Steinberger	34696dc8b9	Merge pull request #1432 from tobiasbischoff/main fix(auth): skip auth profiles in cooldown during selection and rotation	2026-01-23 03:35:25 +00:00
Peter Steinberger	9a9afb389a	Merge origin/main into pr-1432	2026-01-23 03:35:16 +00:00
Peter Steinberger	1e9ae7649d	docs: add changelog entry for #1432	2026-01-23 03:31:42 +00:00
Peter Steinberger	5cb9026541	fix: honor user-pinned profiles and search ranking	2026-01-23 03:28:47 +00:00
Tobias Bischoff	81e78dced5	perf(tui): optimize searchable select list filtering - Add regex caching to avoid creating new RegExp objects on each render - Optimize smartFilter to use single array with tier-based scoring - Replace non-existent fuzzyFilter import with local fuzzyFilterLower - Reduces from 4 array allocations and 4 sorts to 1 array and 1 sort Fixes pre-existing bug where fuzzyFilter was imported from pi-tui but not exported.	2026-01-23 03:28:18 +00:00
Tobias Bischoff	565944ec71	fix(auth): skip auth profiles in cooldown during selection and rotation Auth profiles in cooldown (due to rate limiting) were being attempted, causing unnecessary retries and delays. This fix ensures: 1. Initial profile selection skips profiles in cooldown 2. Profile rotation (after failures) skips cooldown profiles 3. Clear error message when all profiles are unavailable Tests added: - Skips profiles in cooldown during initial selection - Skips profiles in cooldown when rotating after failure Fixes #1316	2026-01-23 03:28:18 +00:00
Peter Steinbergerandazade-c	ec2c69c230	fix: honor gateway env token for doctor/security Co-authored-by: azade-c <azade-c@users.noreply.github.com>	2026-01-23 03:16:52 +00:00
Peter Steinberger	f1deffa681	fix: repair docs redirects	2026-01-23 03:13:12 +00:00
Peter Steinberger	4b19066cc1	fix: normalize Windows exec allowlist paths	2026-01-23 03:11:41 +00:00
Peter Steinberger	ea79b26b79	feat: extend lobster tool run args	2026-01-23 03:09:59 +00:00
Peter Steinberger	6eb355954c	docs: add changelog entry for #1432	2026-01-23 03:06:10 +00:00
Peter Steinberger	91ca52d3c5	fix: honor user-pinned profiles and search ranking	2026-01-23 03:05:01 +00:00
Peter Steinberger	0149d2b678	test: speed up test suite	2026-01-23 02:55:38 +00:00
Peter Steinberger	ecfddb7807	docs: fix lobster links	2026-01-23 02:51:33 +00:00
Peter Steinberger	35228ecae9	fix: treat copilot oauth tokens as non-expiring	2026-01-23 02:51:33 +00:00
Peter Steinberger	cfcc4548bb	fix: set Copilot user agent header	2026-01-23 02:51:33 +00:00
Peter Steinberger	21a9b3b66f	fix: improve GitHub Copilot integration	2026-01-23 02:51:33 +00:00
Peter Steinberger	837749dced	fix: honor send path/filePath inputs (#1444 ) (thanks @hopyky)	2026-01-23 02:27:47 +00:00
Peter Steinberger	59a8eecd7e	test: speed up test suite	2026-01-23 02:22:02 +00:00
Peter Steinberger	542cf011a0	Merge pull request #1444 from hopyky/fix-message-path-parameter Fix: Support path and filePath parameters in message send action	2026-01-23 02:10:54 +00:00
Peter Steinberger	4355d9acca	fix: resolve heartbeat sender and Slack thread_ts	2026-01-23 02:05:34 +00:00
Peter Steinberger	712bc74c30	docs: highlight mattermost plugin	2026-01-23 01:39:36 +00:00
Peter Steinberger	0396b678fa	docs: note transcript hygiene sync	2026-01-23 01:38:05 +00:00
Peter Steinberger	eaf1b6bfee	docs: simplify OpenProse install	2026-01-23 01:37:54 +00:00
Peter Steinberger	06cb2bf58d	docs: expand mattermost intro	2026-01-23 01:35:50 +00:00
Peter Steinberger	8fdb3b38eb	docs: add mattermost redirect	2026-01-23 01:35:15 +00:00
Peter Steinberger	5689d7fb98	refactor: remove transcript sanitize extension	2026-01-23 01:34:33 +00:00
Peter Steinberger	2424404fb4	docs: add transcript hygiene reference	2026-01-23 01:34:21 +00:00
Peter Steinberger	17a09cc721	Merge pull request #1472 from czekaj/fix/logs-follow-spinner fix: suppress spinner in logs --follow mode	2026-01-23 01:29:30 +00:00
Peter Steinberger	bc4d8ce398	docs: link Lobster and OpenProse	2026-01-23 01:29:17 +00:00
Peter Steinberger	279f799388	fix: harden Mattermost plugin gating (#1428 ) (thanks @damoahdominic)	2026-01-23 01:23:23 +00:00
Peter Steinberger	1d658109a8	docs: remove OpenProse telemetry mentions	2026-01-23 01:20:30 +00:00
Peter Steinberger	5a446f3a21	docs: expand OpenProse guide	2026-01-23 01:08:55 +00:00
Peter Steinberger	52b6bf04af	fix: improve tool summaries	2026-01-23 01:00:24 +00:00
Lucas CzekajandClaude Opus 4.5	76a42da676	fix: suppress spinner in logs --follow mode The progress spinner was being shown for each gateway RPC call during log tailing, causing repeated spinner frames (◇ │) to appear every polling interval. Add a `progress` option to `callGatewayFromCli` and disable the spinner during follow mode polling to keep output clean. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-22 16:58:42 -08:00
Peter Steinberger	51a9053387	feat: add OpenProse plugin skills	2026-01-23 00:49:40 +00:00
Peter Steinberger	db0235a26a	fix: gate transcript sanitization by provider	2026-01-23 00:42:45 +00:00
Peter Steinberger	fac21e6eb4	Merge pull request #1428 from bestparents/feat/mattermost-channel feat: add Mattermost channel support	2026-01-23 00:24:47 +00:00
Dominic Damoah	01579aa7d7	Merge branch 'main' into feat/mattermost-channel	2026-01-22 18:17:40 -05:00
Dominic Damoah	8b3cb373d4	fix: remove unused originatingChannel variable Remove unused originatingChannel variable from runPreparedReply function that was assigned but never referenced.	2026-01-22 12:11:05 -05:00
Dominic Damoah	495a39b5a9	refactor: extract mattermost channel plugin to extension Move mattermost channel implementation from core to extensions/mattermost plugin. Extract config schema, group mentions, normalize utilities, and all mattermost-specific logic (accounts, client, monitor, probe, send) into the extension. Update imports to use plugin SDK and local modules. Add channel metadata directly in plugin definition instead of using getChatChannelMeta. Update package.json with channel and install configuration.	2026-01-22 12:02:30 -05:00
Matt mini	57e81d3c24	Fix: Support path and filePath parameters in message send action The message tool accepts path and filePath parameters in its schema, but these were never converted to mediaUrl, causing local files to be ignored when sending messages. Changes: - src/agents/tools/message-tool.ts: Convert path/filePath to media with file:// URL - src/infra/outbound/message-action-runner.ts: Allow hydrateSendAttachmentParams for "send" action Fixes issue where local audio files (and other media) couldn't be sent via the message tool with the path parameter. Users can now use: message({ path: "/tmp/file.ogg" }) message({ filePath: "/tmp/file.ogg" })	2026-01-22 13:15:48 +01:00
Tobias Bischoff	917bcb714e	perf(tui): optimize searchable select list filtering - Add regex caching to avoid creating new RegExp objects on each render - Optimize smartFilter to use single array with tier-based scoring - Replace non-existent fuzzyFilter import with local fuzzyFilterLower - Reduces from 4 array allocations and 4 sorts to 1 array and 1 sort Fixes pre-existing bug where fuzzyFilter was imported from pi-tui but not exported.	2026-01-22 10:29:37 +01:00
Tobias Bischoff	3d8a759eba	fix(auth): skip auth profiles in cooldown during selection and rotation Auth profiles in cooldown (due to rate limiting) were being attempted, causing unnecessary retries and delays. This fix ensures: 1. Initial profile selection skips profiles in cooldown 2. Profile rotation (after failures) skips cooldown profiles 3. Clear error message when all profiles are unavailable Tests added: - Skips profiles in cooldown during initial selection - Skips profiles in cooldown when rotating after failure Fixes #1316	2026-01-22 10:04:56 +01:00
Dominic Damoah	91278d8b4e	Merge branch 'main' into feat/mattermost-channel	2026-01-22 03:11:53 -05:00
Dominic Damoah	fe77d3eb56	Merge branch 'main' into feat/mattermost-channel	2026-01-22 02:49:17 -05:00
Dominic Damoah	bf6df6d6b7	feat: add Mattermost channel support Add Mattermost as a supported messaging channel with bot API and WebSocket integration. Includes channel state tracking (tint, summary, details), multi-account support, and delivery target routing. Update documentation and tests to include Mattermost alongside existing channels.	2026-01-21 18:40:56 -05:00