loudmouth-ai 0.1.0

package/docs/concepts/context.md

@@ -0,0 +1,151 @@
+---
+summary: "Context: what the model sees, how it is built, and how to inspect it"
+read_when:
+  - You want to understand what “context” means in Clawdbot
+  - You are debugging why the model “knows” something (or forgot it)
+  - You want to reduce context overhead (/context, /status, /compact)
+---
+# Context
+
+“Context” is **everything Clawdbot sends to the model for a run**. It is bounded by the model’s **context window** (token limit).
+
+Beginner mental model:
+- **System prompt** (Clawdbot-built): rules, tools, skills list, time/runtime, and injected workspace files.
+- **Conversation history**: your messages + the assistant’s messages for this session.
+- **Tool calls/results + attachments**: command output, file reads, images/audio, etc.
+
+Context is *not the same thing* as “memory”: memory can be stored on disk and reloaded later; context is what’s inside the model’s current window.
+
+## Quick start (inspect context)
+
+- `/status` → quick “how full is my window?” view + session settings.
+- `/context list` → what’s injected + rough sizes (per file + totals).
+- `/context detail` → deeper breakdown: per-file, per-tool schema sizes, per-skill entry sizes, and system prompt size.
+- `/usage tokens` → append per-reply usage footer to normal replies.
+- `/compact` → summarize older history into a compact entry to free window space.
+
+See also: [Slash commands](/tools/slash-commands), [Token use & costs](/token-use), [Compaction](/concepts/compaction).
+
+## Example output
+
+Values vary by model, provider, tool policy, and what’s in your workspace.
+
+### `/context list`
+
+```
+🧠 Context breakdown
+Workspace: <workspaceDir>
+Bootstrap max/file: 20,000 chars
+Sandbox: mode=non-main sandboxed=false
+System prompt (run): 38,412 chars (~9,603 tok) (Project Context 23,901 chars (~5,976 tok))
+
+Injected workspace files:
+- AGENTS.md: OK | raw 1,742 chars (~436 tok) | injected 1,742 chars (~436 tok)
+- SOUL.md: OK | raw 912 chars (~228 tok) | injected 912 chars (~228 tok)
+- TOOLS.md: TRUNCATED | raw 54,210 chars (~13,553 tok) | injected 20,962 chars (~5,241 tok)
+- IDENTITY.md: OK | raw 211 chars (~53 tok) | injected 211 chars (~53 tok)
+- USER.md: OK | raw 388 chars (~97 tok) | injected 388 chars (~97 tok)
+- HEARTBEAT.md: MISSING | raw 0 | injected 0
+- BOOTSTRAP.md: OK | raw 0 chars (~0 tok) | injected 0 chars (~0 tok)
+
+Skills list (system prompt text): 2,184 chars (~546 tok) (12 skills)
+Tools: read, edit, write, exec, process, browser, message, sessions_send, …
+Tool list (system prompt text): 1,032 chars (~258 tok)
+Tool schemas (JSON): 31,988 chars (~7,997 tok) (counts toward context; not shown as text)
+Tools: (same as above)
+
+Session tokens (cached): 14,250 total / ctx=32,000
+```
+
+### `/context detail`
+
+```
+🧠 Context breakdown (detailed)
+…
+Top skills (prompt entry size):
+- frontend-design: 412 chars (~103 tok)
+- oracle: 401 chars (~101 tok)
+… (+10 more skills)
+
+Top tools (schema size):
+- browser: 9,812 chars (~2,453 tok)
+- exec: 6,240 chars (~1,560 tok)
+… (+N more tools)
+```
+
+## What counts toward the context window
+
+Everything the model receives counts, including:
+- System prompt (all sections).
+- Conversation history.
+- Tool calls + tool results.
+- Attachments/transcripts (images/audio/files).
+- Compaction summaries and pruning artifacts.
+- Provider “wrappers” or hidden headers (not visible, still counted).
+
+## How Clawdbot builds the system prompt
+
+The system prompt is **Clawdbot-owned** and rebuilt each run. It includes:
+- Tool list + short descriptions.
+- Skills list (metadata only; see below).
+- Workspace location.
+- Time (UTC + converted user time if configured).
+- Runtime metadata (host/OS/model/thinking).
+- Injected workspace bootstrap files under **Project Context**.
+
+Full breakdown: [System Prompt](/concepts/system-prompt).
+
+## Injected workspace files (Project Context)
+
+By default, Clawdbot injects a fixed set of workspace files (if present):
+- `AGENTS.md`
+- `SOUL.md`
+- `TOOLS.md`
+- `IDENTITY.md`
+- `USER.md`
+- `HEARTBEAT.md`
+- `BOOTSTRAP.md` (first-run only)
+
+Large files are truncated per-file using `agents.defaults.bootstrapMaxChars` (default `20000` chars). `/context` shows **raw vs injected** sizes and whether truncation happened.
+
+## Skills: what’s injected vs loaded on-demand
+
+The system prompt includes a compact **skills list** (name + description + location). This list has real overhead.
+
+Skill instructions are *not* included by default. The model is expected to `read` the skill’s `SKILL.md` **only when needed**.
+
+## Tools: there are two costs
+
+Tools affect context in two ways:
+1) **Tool list text** in the system prompt (what you see as “Tooling”).
+2) **Tool schemas** (JSON). These are sent to the model so it can call tools. They count toward context even though you don’t see them as plain text.
+
+`/context detail` breaks down the biggest tool schemas so you can see what dominates.
+
+## Commands, directives, and “inline shortcuts”
+
+Slash commands are handled by the Gateway. There are a few different behaviors:
+- **Standalone commands**: a message that is only `/...` runs as a command.
+- **Directives**: `/think`, `/verbose`, `/reasoning`, `/elevated`, `/model`, `/queue` are stripped before the model sees the message.
+  - Directive-only messages persist session settings.
+  - Inline directives in a normal message act as per-message hints.
+- **Inline shortcuts** (allowlisted senders only): certain `/...` tokens inside a normal message can run immediately (example: “hey /status”), and are stripped before the model sees the remaining text.
+
+Details: [Slash commands](/tools/slash-commands).
+
+## Sessions, compaction, and pruning (what persists)
+
+What persists across messages depends on the mechanism:
+- **Normal history** persists in the session transcript until compacted/pruned by policy.
+- **Compaction** persists a summary into the transcript and keeps recent messages intact.
+- **Pruning** removes old tool results from the *in-memory* prompt for a run, but does not rewrite the transcript.
+
+Docs: [Session](/concepts/session), [Compaction](/concepts/compaction), [Session pruning](/concepts/session-pruning).
+
+## What `/context` actually reports
+
+`/context` prefers the latest **run-built** system prompt report when available:
+- `System prompt (run)` = captured from the last embedded (tool-capable) run and persisted in the session store.
+- `System prompt (estimate)` = computed on the fly when no run report exists (or when running via a CLI backend that doesn’t generate the report).
+
+Either way, it reports sizes and top contributors; it does **not** dump the full system prompt or tool schemas.

package/docs/concepts/group-messages.md

@@ -0,0 +1,78 @@
+---
+summary: "Behavior and config for WhatsApp group message handling (mentionPatterns are shared across surfaces)"
+read_when:
+  - Changing group message rules or mentions
+---
+# Group messages (WhatsApp web channel)
+
+Goal: let Clawd sit in WhatsApp groups, wake up only when pinged, and keep that thread separate from the personal DM session.
+
+Note: `agents.list[].groupChat.mentionPatterns` is now used by Telegram/Discord/Slack/iMessage as well; this doc focuses on WhatsApp-specific behavior. For multi-agent setups, set `agents.list[].groupChat.mentionPatterns` per agent (or use `messages.groupChat.mentionPatterns` as a global fallback).
+
+## What’s implemented (2025-12-03)
+- Activation modes: `mention` (default) or `always`. `mention` requires a ping (real WhatsApp @-mentions via `mentionedJids`, regex patterns, or the bot’s E.164 anywhere in the text). `always` wakes the agent on every message but it should reply only when it can add meaningful value; otherwise it returns the silent token `NO_REPLY`. Defaults can be set in config (`channels.whatsapp.groups`) and overridden per group via `/activation`. When `channels.whatsapp.groups` is set, it also acts as a group allowlist (include `"*"` to allow all).
+- Group policy: `channels.whatsapp.groupPolicy` controls whether group messages are accepted (`open|disabled|allowlist`). `allowlist` uses `channels.whatsapp.groupAllowFrom` (fallback: explicit `channels.whatsapp.allowFrom`). Default is `allowlist` (blocked until you add senders).
+- Per-group sessions: session keys look like `agent:<agentId>:whatsapp:group:<jid>` so commands such as `/verbose on` or `/think high` (sent as standalone messages) are scoped to that group; personal DM state is untouched. Heartbeats are skipped for group threads.
+- Context injection: **pending-only** group messages (default 50) that *did not* trigger a run are prefixed under `[Chat messages since your last reply - for context]`, with the triggering line under `[Current message - respond to this]`. Messages already in the session are not re-injected.
+- Sender surfacing: every group batch now ends with `[from: Sender Name (+E164)]` so Pi knows who is speaking.
+- Ephemeral/view-once: we unwrap those before extracting text/mentions, so pings inside them still trigger.
+- Group system prompt: on the first turn of a group session (and whenever `/activation` changes the mode) we inject a short blurb into the system prompt like `You are replying inside the WhatsApp group "<subject>". Group members: Alice (+44...), Bob (+43...), … Activation: trigger-only … Address the specific sender noted in the message context.` If metadata isn’t available we still tell the agent it’s a group chat.
+
+## Config example (WhatsApp)
+Add a `groupChat` block to `~/.clawdbot/clawdbot.json` so display-name pings work even when WhatsApp strips the visual `@` in the text body:
+
+```json5
+{
+  channels: {
+    whatsapp: {
+      groups: {
+        "*": { requireMention: true }
+      }
+    }
+  },
+  agents: {
+    list: [
+      {
+        id: "main",
+        groupChat: {
+          historyLimit: 50,
+          mentionPatterns: [
+            "@?clawdbot",
+            "\\+?15555550123"
+          ]
+        }
+      }
+    ]
+  }
+}
+```
+
+Notes:
+- The regexes are case-insensitive; they cover a display-name ping like `@clawdbot` and the raw number with or without `+`/spaces.
+- WhatsApp still sends canonical mentions via `mentionedJids` when someone taps the contact, so the number fallback is rarely needed but is a useful safety net.
+
+### Activation command (owner-only)
+
+Use the group chat command:
+- `/activation mention`
+- `/activation always`
+
+Only the owner number (from `channels.whatsapp.allowFrom`, or the bot’s own E.164 when unset) can change this. Send `/status` as a standalone message in the group to see the current activation mode.
+
+## How to use
+1) Add your WhatsApp account (the one running Clawdbot) to the group.
+2) Say `@clawdbot …` (or include the number). Only allowlisted senders can trigger it unless you set `groupPolicy: "open"`.
+3) The agent prompt will include recent group context plus the trailing `[from: …]` marker so it can address the right person.
+4) Session-level directives (`/verbose on`, `/think high`, `/new` or `/reset`, `/compact`) apply only to that group’s session; send them as standalone messages so they register. Your personal DM session remains independent.
+
+## Testing / verification
+- Manual smoke:
+  - Send an `@clawd` ping in the group and confirm a reply that references the sender name.
+  - Send a second ping and verify the history block is included then cleared on the next turn.
+- Check gateway logs (run with `--verbose`) to see `inbound web message` entries showing `from: <groupJid>` and the `[from: …]` suffix.
+
+## Known considerations
+- Heartbeats are intentionally skipped for groups to avoid noisy broadcasts.
+- Echo suppression uses the combined batch string; if you send identical text twice without mentions, only the first will get a response.
+- Session store entries will appear as `agent:<agentId>:whatsapp:group:<jid>` in the session store (`~/.clawdbot/agents/<agentId>/sessions/sessions.json` by default); a missing entry just means the group hasn’t triggered a run yet.
+- Typing indicators in groups follow `agents.defaults.typingMode` (default: `message` when unmentioned).

package/docs/concepts/groups.md

@@ -0,0 +1,308 @@
+---
+summary: "Group chat behavior across surfaces (WhatsApp/Telegram/Discord/Slack/Signal/iMessage/Microsoft Teams)"
+read_when:
+  - Changing group chat behavior or mention gating
+---
+# Groups
+
+Clawdbot treats group chats consistently across surfaces: WhatsApp, Telegram, Discord, Slack, Signal, iMessage, Microsoft Teams.
+
+## Beginner intro (2 minutes)
+Clawdbot “lives” on your own messaging accounts. There is no separate WhatsApp bot user.
+If **you** are in a group, Clawdbot can see that group and respond there.
+
+Default behavior:
+- Groups are restricted (`groupPolicy: "allowlist"`).
+- Replies require a mention unless you explicitly disable mention gating.
+
+Translation: allowlisted senders can trigger Clawdbot by mentioning it.
+
+> TL;DR
+> - **DM access** is controlled by `*.allowFrom`.
+> - **Group access** is controlled by `*.groupPolicy` + allowlists (`*.groups`, `*.groupAllowFrom`).
+> - **Reply triggering** is controlled by mention gating (`requireMention`, `/activation`).
+
+Quick flow (what happens to a group message):
+```
+groupPolicy? disabled -> drop
+groupPolicy? allowlist -> group allowed? no -> drop
+requireMention? yes -> mentioned? no -> store for context only
+otherwise -> reply
+```
+
+![Group message flow](/images/groups-flow.svg)
+
+If you want...
+| Goal | What to set |
+|------|-------------|
+| Allow all groups but only reply on @mentions | `groups: { "*": { requireMention: true } }` |
+| Disable all group replies | `groupPolicy: "disabled"` |
+| Only specific groups | `groups: { "<group-id>": { ... } }` (no `"*"` key) |
+| Only you can trigger in groups | `groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]` |
+
+## Session keys
+- Group sessions use `agent:<agentId>:<channel>:group:<id>` session keys (rooms/channels use `agent:<agentId>:<channel>:channel:<id>`).
+- Telegram forum topics add `:topic:<threadId>` to the group id so each topic has its own session.
+- Direct chats use the main session (or per-sender if configured).
+- Heartbeats are skipped for group sessions.
+
+## Pattern: personal DMs + public groups (single agent)
+
+Yes — this works well if your “personal” traffic is **DMs** and your “public” traffic is **groups**.
+
+Why: in single-agent mode, DMs typically land in the **main** session key (`agent:main:main`), while groups always use **non-main** session keys (`agent:main:<channel>:group:<id>`). If you enable sandboxing with `mode: "non-main"`, those group sessions run in Docker while your main DM session stays on-host.
+
+This gives you one agent “brain” (shared workspace + memory), but two execution postures:
+- **DMs**: full tools (host)
+- **Groups**: sandbox + restricted tools (Docker)
+
+> If you need truly separate workspaces/personas (“personal” and “public” must never mix), use a second agent + bindings. See [Multi-Agent Routing](/concepts/multi-agent).
+
+Example (DMs on host, groups sandboxed + messaging-only tools):
+
+```json5
+{
+  agents: {
+    defaults: {
+      sandbox: {
+        mode: "non-main", // groups/channels are non-main -> sandboxed
+        scope: "session", // strongest isolation (one container per group/channel)
+        workspaceAccess: "none"
+      }
+    }
+  },
+  tools: {
+    sandbox: {
+      tools: {
+        // If allow is non-empty, everything else is blocked (deny still wins).
+        allow: ["group:messaging", "group:sessions"],
+        deny: ["group:runtime", "group:fs", "group:ui", "nodes", "cron", "gateway"]
+      }
+    }
+  }
+}
+```
+
+Want “groups can only see folder X” instead of “no host access”? Keep `workspaceAccess: "none"` and mount only allowlisted paths into the sandbox:
+
+```json5
+{
+  agents: {
+    defaults: {
+      sandbox: {
+        mode: "non-main",
+        scope: "session",
+        workspaceAccess: "none",
+        docker: {
+          binds: [
+            // hostPath:containerPath:mode
+            "~/FriendsShared:/data:ro"
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+Related:
+- Configuration keys and defaults: [Gateway configuration](/gateway/configuration#agentsdefaultssandbox)
+- Debugging why a tool is blocked: [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated)
+- Bind mounts details: [Sandboxing](/gateway/sandboxing#custom-bind-mounts)
+
+## Display labels
+- UI labels use `displayName` when available, formatted as `<channel>:<token>`.
+- `#room` is reserved for rooms/channels; group chats use `g-<slug>` (lowercase, spaces -> `-`, keep `#@+._-`).
+
+## Group policy
+Control how group/room messages are handled per channel:
+
+```json5
+{
+  channels: {
+    whatsapp: {
+      groupPolicy: "disabled", // "open" | "disabled" | "allowlist"
+      groupAllowFrom: ["+15551234567"]
+    },
+    telegram: {
+      groupPolicy: "disabled",
+      groupAllowFrom: ["123456789", "@username"]
+    },
+    signal: {
+      groupPolicy: "disabled",
+      groupAllowFrom: ["+15551234567"]
+    },
+    imessage: {
+      groupPolicy: "disabled",
+      groupAllowFrom: ["chat_id:123"]
+    },
+    msteams: {
+      groupPolicy: "disabled",
+      groupAllowFrom: ["user@org.com"]
+    },
+    discord: {
+      groupPolicy: "allowlist",
+      guilds: {
+        "GUILD_ID": { channels: { help: { allow: true } } }
+      }
+    },
+    slack: {
+      groupPolicy: "allowlist",
+      channels: { "#general": { allow: true } }
+    },
+    matrix: {
+      groupPolicy: "allowlist",
+      groupAllowFrom: ["@owner:example.org"],
+      groups: {
+        "!roomId:example.org": { allow: true },
+        "#alias:example.org": { allow: true }
+      }
+    }
+  }
+}
+```
+
+| Policy | Behavior |
+|--------|----------|
+| `"open"` | Groups bypass allowlists; mention-gating still applies. |
+| `"disabled"` | Block all group messages entirely. |
+| `"allowlist"` | Only allow groups/rooms that match the configured allowlist. |
+
+Notes:
+- `groupPolicy` is separate from mention-gating (which requires @mentions).
+- WhatsApp/Telegram/Signal/iMessage/Microsoft Teams: use `groupAllowFrom` (fallback: explicit `allowFrom`).
+- Discord: allowlist uses `channels.discord.guilds.<id>.channels`.
+- Slack: allowlist uses `channels.slack.channels`.
+- Matrix: allowlist uses `channels.matrix.groups` (room IDs, aliases, or names). Use `channels.matrix.groupAllowFrom` to restrict senders; per-room `users` allowlists are also supported.
+- Group DMs are controlled separately (`channels.discord.dm.*`, `channels.slack.dm.*`).
+- Telegram allowlist can match user IDs (`"123456789"`, `"telegram:123456789"`, `"tg:123456789"`) or usernames (`"@alice"` or `"alice"`); prefixes are case-insensitive.
+- Default is `groupPolicy: "allowlist"`; if your group allowlist is empty, group messages are blocked.
+
+Quick mental model (evaluation order for group messages):
+1) `groupPolicy` (open/disabled/allowlist)
+2) group allowlists (`*.groups`, `*.groupAllowFrom`, channel-specific allowlist)
+3) mention gating (`requireMention`, `/activation`)
+
+## Mention gating (default)
+Group messages require a mention unless overridden per group. Defaults live per subsystem under `*.groups."*"`.
+
+Replying to a bot message counts as an implicit mention (when the channel supports reply metadata). This applies to Telegram, WhatsApp, Slack, Discord, and Microsoft Teams.
+
+```json5
+{
+  channels: {
+    whatsapp: {
+      groups: {
+        "*": { requireMention: true },
+        "123@g.us": { requireMention: false }
+      }
+    },
+    telegram: {
+      groups: {
+        "*": { requireMention: true },
+        "123456789": { requireMention: false }
+      }
+    },
+    imessage: {
+      groups: {
+        "*": { requireMention: true },
+        "123": { requireMention: false }
+      }
+    }
+  },
+  agents: {
+    list: [
+      {
+        id: "main",
+        groupChat: {
+          mentionPatterns: ["@clawd", "clawdbot", "\\+15555550123"],
+          historyLimit: 50
+        }
+      }
+    ]
+  }
+}
+```
+
+Notes:
+- `mentionPatterns` are case-insensitive regexes.
+- Surfaces that provide explicit mentions still pass; patterns are a fallback.
+- Per-agent override: `agents.list[].groupChat.mentionPatterns` (useful when multiple agents share a group).
+- Mention gating is only enforced when mention detection is possible (native mentions or `mentionPatterns` are configured).
+- Discord defaults live in `channels.discord.guilds."*"` (overridable per guild/channel).
+- Group history context is wrapped uniformly across channels and is **pending-only** (messages skipped due to mention gating); use `messages.groupChat.historyLimit` for the global default and `channels.<channel>.historyLimit` (or `channels.<channel>.accounts.*.historyLimit`) for overrides. Set `0` to disable.
+
+## Group allowlists
+When `channels.whatsapp.groups`, `channels.telegram.groups`, or `channels.imessage.groups` is configured, the keys act as a group allowlist. Use `"*"` to allow all groups while still setting default mention behavior.
+
+Common intents (copy/paste):
+
+1) Disable all group replies
+```json5
+{
+  channels: { whatsapp: { groupPolicy: "disabled" } }
+}
+```
+
+2) Allow only specific groups (WhatsApp)
+```json5
+{
+  channels: {
+    whatsapp: {
+      groups: {
+        "123@g.us": { requireMention: true },
+        "456@g.us": { requireMention: false }
+      }
+    }
+  }
+}
+```
+
+3) Allow all groups but require mention (explicit)
+```json5
+{
+  channels: {
+    whatsapp: {
+      groups: { "*": { requireMention: true } }
+    }
+  }
+}
+```
+
+4) Only the owner can trigger in groups (WhatsApp)
+```json5
+{
+  channels: {
+    whatsapp: {
+      groupPolicy: "allowlist",
+      groupAllowFrom: ["+15551234567"],
+      groups: { "*": { requireMention: true } }
+    }
+  }
+}
+```
+
+## Activation (owner-only)
+Group owners can toggle per-group activation:
+- `/activation mention`
+- `/activation always`
+
+Owner is determined by `channels.whatsapp.allowFrom` (or the bot’s self E.164 when unset). Send the command as a standalone message. Other surfaces currently ignore `/activation`.
+
+## Context fields
+Group inbound payloads set:
+- `ChatType=group`
+- `GroupSubject` (if known)
+- `GroupMembers` (if known)
+- `WasMentioned` (mention gating result)
+- Telegram forum topics also include `MessageThreadId` and `IsForum`.
+
+The agent system prompt includes a group intro on the first turn of a new group session. It reminds the model to respond like a human, avoid Markdown tables, and avoid typing literal `\n` sequences.
+
+## iMessage specifics
+- Prefer `chat_id:<id>` when routing or allowlisting.
+- List chats: `imsg chats --limit 20`.
+- Group replies always go back to the same `chat_id`.
+
+## WhatsApp specifics
+See [Group messages](/concepts/group-messages) for WhatsApp-only behavior (history injection, mention handling details).

package/docs/concepts/markdown-formatting.md

@@ -0,0 +1,132 @@
+---
+summary: "Markdown formatting pipeline for outbound channels"
+read_when:
+  - You are changing markdown formatting or chunking for outbound channels
+  - You are adding a new channel formatter or style mapping
+  - You are debugging formatting regressions across channels
+---
+# Markdown formatting
+
+Clawdbot formats outbound Markdown by converting it into a shared intermediate
+representation (IR) before rendering channel-specific output. The IR keeps the
+source text intact while carrying style/link spans so chunking and rendering can
+stay consistent across channels.
+
+## Goals
+
+- **Consistency:** one parse step, multiple renderers.
+- **Safe chunking:** split text before rendering so inline formatting never
+  breaks across chunks.
+- **Channel fit:** map the same IR to Slack mrkdwn, Telegram HTML, and Signal
+  style ranges without re-parsing Markdown.
+
+## Pipeline
+
+1. **Parse Markdown -> IR**
+   - IR is plain text plus style spans (bold/italic/strike/code/spoiler) and link spans.
+   - Offsets are UTF-16 code units so Signal style ranges align with its API.
+   - Tables are parsed only when a channel opts into table conversion.
+2. **Chunk IR (format-first)**
+   - Chunking happens on the IR text before rendering.
+   - Inline formatting does not split across chunks; spans are sliced per chunk.
+3. **Render per channel**
+   - **Slack:** mrkdwn tokens (bold/italic/strike/code), links as `<url|label>`.
+   - **Telegram:** HTML tags (`<b>`, `<i>`, `<s>`, `<code>`, `<pre><code>`, `<a href>`).
+   - **Signal:** plain text + `text-style` ranges; links become `label (url)` when label differs.
+
+## IR example
+
+Input Markdown:
+
+```markdown
+Hello **world** — see [docs](https://docs.clawd.bot).
+```
+
+IR (schematic):
+
+```json
+{
+  "text": "Hello world — see docs.",
+  "styles": [
+    { "start": 6, "end": 11, "style": "bold" }
+  ],
+  "links": [
+    { "start": 19, "end": 23, "href": "https://docs.clawd.bot" }
+  ]
+}
+```
+
+## Where it is used
+
+- Slack, Telegram, and Signal outbound adapters render from the IR.
+- Other channels (WhatsApp, iMessage, MS Teams, Discord) still use plain text or
+  their own formatting rules, with Markdown table conversion applied before
+  chunking when enabled.
+
+## Table handling
+
+Markdown tables are not consistently supported across chat clients. Use
+`markdown.tables` to control conversion per channel (and per account).
+
+- `code`: render tables as code blocks (default for most channels).
+- `bullets`: convert each row into bullet points (default for Signal + WhatsApp).
+- `off`: disable table parsing and conversion; raw table text passes through.
+
+Config keys:
+
+```yaml
+channels:
+  discord:
+    markdown:
+      tables: code
+    accounts:
+      work:
+        markdown:
+          tables: off
+```
+
+## Chunking rules
+
+- Chunk limits come from channel adapters/config and are applied to the IR text.
+- Code fences are preserved as a single block with a trailing newline so channels
+  render them correctly.
+- List prefixes and blockquote prefixes are part of the IR text, so chunking
+  does not split mid-prefix.
+- Inline styles (bold/italic/strike/inline-code/spoiler) are never split across
+  chunks; the renderer reopens styles inside each chunk.
+
+If you need more on chunking behavior across channels, see
+[Streaming + chunking](/concepts/streaming).
+
+## Link policy
+
+- **Slack:** `[label](url)` -> `<url|label>`; bare URLs remain bare. Autolink
+  is disabled during parse to avoid double-linking.
+- **Telegram:** `[label](url)` -> `<a href="url">label</a>` (HTML parse mode).
+- **Signal:** `[label](url)` -> `label (url)` unless label matches the URL.
+
+## Spoilers
+
+Spoiler markers (`||spoiler||`) are parsed only for Signal, where they map to
+SPOILER style ranges. Other channels treat them as plain text.
+
+## How to add or update a channel formatter
+
+1. **Parse once:** use the shared `markdownToIR(...)` helper with channel-appropriate
+   options (autolink, heading style, blockquote prefix).
+2. **Render:** implement a renderer with `renderMarkdownWithMarkers(...)` and a
+   style marker map (or Signal style ranges).
+3. **Chunk:** call `chunkMarkdownIR(...)` before rendering; render each chunk.
+4. **Wire adapter:** update the channel outbound adapter to use the new chunker
+   and renderer.
+5. **Test:** add or update format tests and an outbound delivery test if the
+   channel uses chunking.
+
+## Common gotchas
+
+- Slack angle-bracket tokens (`<@U123>`, `<#C123>`, `<https://...>`) must be
+  preserved; escape raw HTML safely.
+- Telegram HTML requires escaping text outside tags to avoid broken markup.
+- Signal style ranges depend on UTF-16 offsets; do not use code point offsets.
+- Preserve trailing newlines for fenced code blocks so closing markers land on
+  their own line.