yt-slack-mcp 0.4.0 → 0.6.0

package/README.md

@@ -9,6 +9,8 @@ A host-agnostic [Model Context Protocol](https://modelcontextprotocol.io) server
 - Return image attachments inline, extract text from PDFs, and return `text/*` attachment contents inline.
 - Retrieve private attachment contents through the authenticated Slack browser session.
 - Reply to a thread, add or remove a reaction, edit an authored message or thread reply, or upload local files only in explicitly allowed channel IDs.
+- Have no plain top-level text post: a reply needs an existing thread, and a file upload with an `initial_comment` is the only way to start a top-level message.
+- Prefix every message the agent posts with `🤖:` — or `🤖 <model>:` when the call names the model — so agent replies stand apart from the account's own messages; an edit can opt out with `agent_authored: false`.
 
 Attachment limits: images and text files are limited to 10 MB; text attachments are truncated at 100,000 characters. PDFs are limited to 20 MB, 50 pages, and 100,000 extracted characters.
 
@@ -18,12 +20,39 @@ Attachment limits: images and text files are limited to 10 MB; text attachments
 |------|-------------|
 | `slack_read_permalink` | Read a message or thread from a channel, DM, or group-DM permalink, including supported attachments. |
 | `slack_get_replies` | Read replies for a thread by channel ID and timestamp. |
-| `slack_get_history` | Read recent channel history. |
-| `slack_reply_to_thread` | Reply to a thread; restricted to allowed channels. |
+| `slack_get_history` | Read recent channel history by channel ID (up to 200 messages). |
+| `slack_reply_to_thread` | Reply to a thread, with optional `model`, in a `🤖:`-prefixed message; restricted to allowed channels. |
 | `slack_add_reaction` | Add a reaction; restricted to allowed channels. |
 | `slack_remove_reaction` | Remove a reaction added by this account; restricted to allowed channels. |
-| `slack_upload_files` | Upload up to 10 local files to a channel or thread, with an optional initial comment; returns file and message permalinks; restricted to allowed channels. |
-| `slack_edit_message` | Edit an authored message or thread reply by channel ID and timestamp; replaces the message text (Slack removes any existing Block Kit blocks) and returns the updated timestamp and permalink; restricted to allowed channels. |
+| `slack_upload_files` | Upload up to 10 local files (10 MB each) to a channel or thread, with an optional `initial_comment` prefixed with `🤖:` and an optional `model` (only used with a comment); returns file and message permalinks; restricted to allowed channels. |
+| `slack_edit_message` | Edit an authored message or thread reply by channel ID and timestamp; replaces the message text with `🤖:`-prefixed text and an optional `model`, or with the text as given when `agent_authored` is `false` (Slack removes any existing Block Kit blocks) and returns the updated timestamp and permalink; restricted to allowed channels. |
+
+## Agent message prefix
+
+The write tools post through the account's own browser session, so Slack shows
+the account name on them. To keep agent-written messages distinguishable, the
+text of every posted message is prefixed with `🤖:` by default:
+
+```text
+🤖: deployed revision 4f2c1a9
+```
+
+The MCP transport does not report which model is calling, so a write tool call
+can pass `model` with the model it is running; the prefix then names it:
+
+```text
+🤖 claude-sonnet-4-5: deployed revision 4f2c1a9
+```
+
+The prefix is added once: text that already starts with `🤖` is sent unchanged,
+so editing a prefixed message does not stack prefixes. A file upload without an
+`initial_comment` — or with only whitespace — gets no comment rather than a bare
+prefix, and `model` has no effect then.
+
+`slack_edit_message` can also replace a message with text that is not
+agent-written, such as a correction to the user's own message: pass
+`agent_authored: false` and the text is stored as given, without the prefix.
+`model` has no effect when `agent_authored` is `false`.
 
 ## Setup
 
@@ -43,12 +72,12 @@ Save each token as a single-line file:
 ~/.config/yt-slack-mcp/secrets/slack-xoxd.txt
 ```
 
-The server reads these paths by default. Override them with the config file or environment variables if your MCP host manages secrets elsewhere.
+The server reads these paths by default. Override them in the config file described below if your MCP host manages secrets elsewhere.
 
 ### 3. (Optional) Configure allowed write channels and paths
 
-All configuration can live in a JSON config file at
-`~/.config/yt-slack-mcp/config.json` (override with `SLACK_MCP_CONFIG`):
+All configuration lives in a JSON config file at
+`~/.config/yt-slack-mcp/config.json`:
 
 ```json
 {
@@ -62,22 +91,27 @@ All configuration can live in a JSON config file at
 
 By default the write tools (`slack_reply_to_thread`, `slack_add_reaction`,
 `slack_remove_reaction`, `slack_edit_message`) and `slack_upload_files` are
-locked down — no channel is writable. Each upload is limited to 10 MB. Every
-field is optional; a missing file just means defaults. Env vars always override
-the config file.
+locked down — no channel is writable. Each uploaded file is limited to 10 MB, and
+a call accepts at most 10 files. Every field is optional; a missing file just
+means defaults.
 
 ## Configuration
 
-Config resolution order: built-in defaults → config file → env vars.
+Configuration comes from the JSON config file, with built-in defaults for
+absent keys.
 
-| Config file key | Env var | Default | Description |
-|-----------------|---------|---------|-------------|
-| `secretsDir` | `SLACK_MCP_SECRETS_DIR` | `~/.config/yt-slack-mcp/secrets` | Directory holding the token files |
-| `xoxcPath` | `SLACK_MCP_XOXC_PATH` | `$SECRETS_DIR/slack-xoxc.txt` | Path to the `xoxc` token |
-| `xoxdPath` | `SLACK_MCP_XOXD_PATH` | `$SECRETS_DIR/slack-xoxd.txt` | Path to the `xoxd` token |
-| `allowedWriteChannels` | `SLACK_MCP_ALLOWED_WRITE_CHANNELS` | *(none)* | Channel IDs allowed for write tools (comma-separated in env) |
-| `userAgent` | `SLACK_MCP_USER_AGENT` | `Mozilla/5.0` | HTTP `User-Agent` header |
-| *(config file path)* | `SLACK_MCP_CONFIG` | `~/.config/yt-slack-mcp/config.json` | Path to the JSON config file |
+| Config key | Default | Description |
+|------------|---------|-------------|
+| `secretsDir` | `~/.config/yt-slack-mcp/secrets` | Directory holding the token files |
+| `xoxcPath` | `$SECRETS_DIR/slack-xoxc.txt` | Path to the `xoxc` token |
+| `xoxdPath` | `$SECRETS_DIR/slack-xoxd.txt` | Path to the `xoxd` token |
+| `allowedWriteChannels` | *(none)* | Channel IDs allowed for write tools |
+| `userAgent` | `Mozilla/5.0` | HTTP `User-Agent` header |
+
+Environment-variable configuration has been removed. Move any environment-supplied
+values into `~/.config/yt-slack-mcp/config.json`; the config path is fixed for the
+CLI. `allowedWriteChannels` accepts an array or a comma-separated string, so an
+old comma-separated value can be copied as-is.
 
 ## MCP host configuration
 
@@ -100,6 +134,14 @@ For example, Claude Desktop uses:
 }
 ```
 
+## Install as a skill
+
+[`skills/slack-mcp/SKILL.md`](skills/slack-mcp/SKILL.md) packages this server as
+an Agent Skill so an agent knows when to read Slack, when a write is allowed,
+and which tool fits the request. Copy or symlink the `skills/slack-mcp`
+directory into your agent's skills directory (for example
+`.agents/skills/slack-mcp`); the server still needs the setup above.
+
 ## License
 
 MIT

package/index.js

@@ -20,6 +20,8 @@ import { fileURLToPath } from "url";
 
 const DEFAULT_SECRETS_DIR = path.join(os.homedir(), ".config", "yt-slack-mcp", "secrets");
 const DEFAULT_CONFIG_PATH = path.join(os.homedir(), ".config", "yt-slack-mcp", "config.json");
+const PACKAGE_INFO = JSON.parse(fs.readFileSync(new URL("./package.json", import.meta.url), "utf8"));
+const SERVER_INFO = { name: "yt-slack-mcp", version: PACKAGE_INFO.version };
 
 const maxImageBytes = 10 * 1024 * 1024;
 const maxPdfBytes = 20 * 1024 * 1024;
@@ -46,14 +48,29 @@ function parseChannelList(value) {
     if (value === undefined || value === null || value === "") {
         return null;
     }
-    return value
-        .split(",")
-        .map((c) => c.trim())
+    const list = Array.isArray(value)
+        ? value
+        : typeof value === "string"
+          ? value.split(",")
+          : null;
+    if (list === null) {
+        throw new Error("channel IDs must be an array or a comma-separated string");
+    }
+    return list
+        .map((channel) => {
+            if (typeof channel !== "string") {
+                throw new Error("channel IDs must be strings");
+            }
+            return channel.trim();
+        })
         .filter(Boolean);
 }
 
-function loadConfig(env = process.env) {
-    const configPath = env.SLACK_MCP_CONFIG || DEFAULT_CONFIG_PATH;
+function loadConfig(input = DEFAULT_CONFIG_PATH) {
+    const configPath =
+        typeof input === "string"
+            ? input
+            : input?.SLACK_MCP_CONFIG || DEFAULT_CONFIG_PATH;
     let fileConfig = {};
     if (fs.existsSync(configPath)) {
         try {
@@ -63,15 +80,16 @@ function loadConfig(env = process.env) {
         }
     }
 
-    const secretsDir =
-        env.SLACK_MCP_SECRETS_DIR || expandHome(fileConfig.secretsDir) || DEFAULT_SECRETS_DIR;
-    const xoxcPath =
-        env.SLACK_MCP_XOXC_PATH || expandHome(fileConfig.xoxcPath) || path.join(secretsDir, "slack-xoxc.txt");
-    const xoxdPath =
-        env.SLACK_MCP_XOXD_PATH || expandHome(fileConfig.xoxdPath) || path.join(secretsDir, "slack-xoxd.txt");
-    const allowedWriteChannels =
-        parseChannelList(env.SLACK_MCP_ALLOWED_WRITE_CHANNELS) ?? fileConfig.allowedWriteChannels ?? [];
-    const userAgent = env.SLACK_MCP_USER_AGENT || fileConfig.userAgent || "Mozilla/5.0";
+    const secretsDir = expandHome(fileConfig.secretsDir) || DEFAULT_SECRETS_DIR;
+    const xoxcPath = expandHome(fileConfig.xoxcPath) || path.join(secretsDir, "slack-xoxc.txt");
+    const xoxdPath = expandHome(fileConfig.xoxdPath) || path.join(secretsDir, "slack-xoxd.txt");
+    let allowedWriteChannels;
+    try {
+        allowedWriteChannels = parseChannelList(fileConfig.allowedWriteChannels) ?? [];
+    } catch (e) {
+        throw new Error(`invalid Slack MCP config ${configPath}: ${e.message}`);
+    }
+    const userAgent = fileConfig.userAgent || "Mozilla/5.0";
 
     return { configPath, secretsDir, xoxcPath, xoxdPath, allowedWriteChannels, userAgent };
 }
@@ -370,8 +388,33 @@ function assertAllowedWriteChannel(channelId, allowed) {
     }
 }
 
+const AGENT_PREFIX_EMOJI = "🤖";
+
+// Slack shows the account's own name on everything this server posts, so mark
+// agent-written text with a robot emoji and name the model that wrote it when
+// the caller says which one it is running. Text is trimmed and blank text has no
+// prefix to carry, so an optional comment stays absent. Text that already
+// carries the prefix is returned unchanged, so editing a prefixed message does
+// not stack prefixes.
+function withAgentPrefix(text, model) {
+    const value = typeof text === "string" ? text.trim() : "";
+    if (!value) {
+        return undefined;
+    }
+    if (value.startsWith(AGENT_PREFIX_EMOJI)) {
+        return value;
+    }
+    const name = typeof model === "string" ? model.trim() : "";
+    return `${AGENT_PREFIX_EMOJI}${name ? ` ${name}` : ""}: ${value}`;
+}
+
 // ── Schemas ─────────────────────────────────────────────────────────────────
 
+const AgentModelField = z
+    .string()
+    .optional()
+    .describe("Model you are running, e.g. gpt-5.1, shown in the 🤖 prefix. Omit when unknown.");
+
 const ReadPermalinkSchema = z.object({
     url: z.string().describe("Slack permalink, e.g. https://<workspace>.slack.com/archives/C.../p..."),
 });
@@ -391,6 +434,7 @@ const ReplyToThreadSchema = z.object({
     channel_id: z.string(),
     thread_ts: z.string(),
     text: z.string(),
+    model: AgentModelField,
 });
 
 const AddReactionSchema = z.object({
@@ -404,12 +448,19 @@ const UploadFilesSchema = z.object({
     file_paths: z.array(z.string().min(1)).min(1).max(10),
     thread_ts: z.string().optional(),
     initial_comment: z.string().optional(),
+    model: AgentModelField,
 });
 
 const EditMessageSchema = z.object({
     channel_id: z.string(),
     timestamp: z.string().describe("Timestamp of the message or thread reply to edit."),
     text: z.string(),
+    agent_authored: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe("Set false when this text is not agent-written, for example correcting the user's own message, so it is stored without the 🤖 prefix; model is ignored when this is false."),
+    model: AgentModelField,
 });
 
 // ── Tool definitions ─────────────────────────────────────────────────────────
@@ -432,7 +483,7 @@ const TOOLS = [
     },
     {
         name: "slack_reply_to_thread",
-        description: "Reply to a Slack thread. Restricted to allowed channels.",
+        description: "Reply to a Slack thread. The posted text is prefixed with `🤖:` — or `🤖 <model>:` when model is given — so readers can tell it came from an agent; pass model to name the model writing it. Restricted to allowed channels.",
         inputSchema: zodToJsonSchema(ReplyToThreadSchema),
     },
     {
@@ -447,12 +498,12 @@ const TOOLS = [
     },
     {
         name: "slack_upload_files",
-        description: "Upload one or more local files to a channel or thread. Restricted to allowed channels.",
+        description: "Upload one or more local files to a channel or thread. A given initial_comment is prefixed with `🤖:` — or `🤖 <model>:` when model is given — so readers can tell it came from an agent; pass model to name the model writing it, and note that model has no effect without initial_comment. Restricted to allowed channels.",
         inputSchema: zodToJsonSchema(UploadFilesSchema),
     },
     {
         name: "slack_edit_message",
-        description: "Edit an authored Slack message or thread reply by channel id and timestamp. Replaces the message text; any existing Block Kit blocks are removed by Slack. Restricted to allowed channels.",
+        description: "Edit an authored Slack message or thread reply by channel id and timestamp. Replaces the message text, prefixed with `🤖:` — or `🤖 <model>:` when model is given — unless it already carries the prefix; pass model to name the model writing it, and set agent_authored to false when the new text is not agent-written. Any existing Block Kit blocks are removed by Slack. Restricted to allowed channels.",
         inputSchema: zodToJsonSchema(EditMessageSchema),
     },
 ];
@@ -500,7 +551,7 @@ function createExecuteToolCall({ slackApi, formatMessages, uploadSlackFiles, all
                 const response = await slackApi("chat.postMessage", {
                     channel: channelId,
                     thread_ts: requireString(a.thread_ts, "thread_ts"),
-                    text: requireString(a.text, "text"),
+                    text: withAgentPrefix(requireString(a.text, "text"), a.model),
                 }, "POST");
                 return { content: [{ type: "text", text: `posted reply at ${response.ts}` }] };
             }
@@ -537,7 +588,7 @@ function createExecuteToolCall({ slackApi, formatMessages, uploadSlackFiles, all
                     filePaths: a.file_paths,
                     channelId,
                     threadTs: a.thread_ts && requireString(a.thread_ts, "thread_ts"),
-                    initialComment: a.initial_comment,
+                    initialComment: withAgentPrefix(a.initial_comment, a.model),
                 });
                 return {
                     content: files.map((file) => ({
@@ -558,7 +609,7 @@ function createExecuteToolCall({ slackApi, formatMessages, uploadSlackFiles, all
                     updated = await slackApi("chat.update", {
                         channel: channelId,
                         ts: timestamp,
-                        text,
+                        text: a.agent_authored ? withAgentPrefix(text, a.model) : text,
                     }, "POST");
                 } catch (error) {
                     const reason = String(error?.message ?? error).replace(/^slack chat\.update failed: /, "");
@@ -612,11 +663,11 @@ async function main() {
     const { slackApi, formatMessages, uploadSlackFiles } = createSlackClient({ xoxcToken, xoxdToken, userAgent: config.userAgent });
 
     const server = new Server(
-        { name: "yt-slack-mcp", version: "0.1.0" },
+        SERVER_INFO,
         {
             capabilities: { tools: {} },
             instructions:
-                "MCP server for Slack. Read with slack_read_permalink, slack_get_replies, slack_get_history; write with slack_reply_to_thread, slack_add_reaction, slack_remove_reaction, slack_upload_files, slack_edit_message (restricted to allowed channels).",
+                "MCP server for Slack. Read with slack_read_permalink, slack_get_replies, slack_get_history; write with slack_reply_to_thread, slack_add_reaction, slack_remove_reaction, slack_upload_files, slack_edit_message (restricted to allowed channels). Messages sent by the write tools are prefixed with `🤖:` by default, and slack_edit_message can opt out with agent_authored false; pass model with the model you are running to include it in the prefix.",
         }
     );
 
@@ -658,14 +709,16 @@ if (isMain) {
 
 export {
     TOOLS,
+    SERVER_INFO,
+    parseChannelList,
     parsePermalink,
     requireString,
     assertAllowedWriteChannel,
+    withAgentPrefix,
     createExecuteToolCall,
     createSlackClient,
     loadConfig,
     expandHome,
-    parseChannelList,
     ReadPermalinkSchema,
     GetRepliesSchema,
     GetHistorySchema,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yt-slack-mcp",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "MCP server for Slack — read permalinks, threads, and channel history; reply to threads; add or remove reactions; edit messages.",
   "type": "module",
   "main": "index.js",
@@ -11,7 +11,8 @@
     "test": "node --test --experimental-test-coverage"
   },
   "files": [
-    "index.js"
+    "index.js",
+    "skills/*/SKILL.md"
   ],
   "keywords": [
     "mcp",

package/skills/slack-mcp/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: slack-mcp
+description: Read and write Slack through yt-slack-mcp — read permalinks, threads, channel history, and attachments; reply in threads, react, upload files, and edit messages in allowed channels. Use when asked to inspect a Slack link, summarize a channel or thread, find recent channel messages, or reply, react, upload, or edit in Slack.
+---
+
+# Slack MCP
+
+Use the `yt-slack-mcp` MCP server through this skill. Read before writing, and
+write only where the channel allow-list permits.
+
+Server: `yt-slack-mcp` 0.6.0, launched as `npx yt-slack-mcp` over stdio.
+
+## Setup and auth
+
+The server talks to Slack through your logged-in browser session, not a bot
+token.
+
+1. Save the `xoxc` token (Slack web localStorage) as a single line in
+   `~/.config/yt-slack-mcp/secrets/slack-xoxc.txt`.
+2. Save the `xoxd` token (the cookie named `d`) as a single line in
+   `~/.config/yt-slack-mcp/secrets/slack-xoxd.txt`.
+3. Allow writes by listing channel IDs in `allowedWriteChannels` in
+   `~/.config/yt-slack-mcp/config.json`. With an empty or missing list, every
+   write is refused.
+
+Configuration is file-based: `config.json` also accepts `secretsDir`, `xoxcPath`,
+`xoxdPath`, and `userAgent`, and the defaults apply when a key is absent. Never
+echo a token or a file's contents back to the user.
+
+### What each failure means
+
+| Message | Cause | Fix |
+|---------|-------|-----|
+| `Error: missing slack-xoxc.txt (looked at <path>)` | The `xoxc` file is absent at startup; the server exits before listing tools. | Write the token file at the reported path, or set `xoxcPath` in `config.json` to point at it. |
+| `Error: missing slack-xoxd.txt (looked at <path>)` | Same, for the `xoxd` file. | Write the token file at the reported path, or set `xoxdPath` in `config.json` to point at it. |
+| `Error: invalid Slack MCP config <path>: <detail>` | `config.json` is not valid JSON, or a value has the wrong type; the detail names the problem. | Fix the JSON, correct the value, or remove the file. |
+| `Error: writes are not allowed for channel <id>` | The channel is not in the allow-list. | Add the channel ID to the allow-list if the user wants writes there; never work around the refusal. |
+| `slack <method> failed: invalid_auth` (or `not_authed`) | The browser session expired or the token was copied incorrectly. | Refresh the `xoxc`/`xoxd` pair, then retry once. |
+| `Error: missing <name>` | A required write-tool argument (`channel_id`, `thread_ts`, `timestamp`, `text`, `reaction`) was blank. | Supply the actual value; do not invent IDs. |
+
+Tool errors arrive as text starting with `Error:`. Report the text instead of
+retrying the same call unchanged.
+
+## Troubleshooting
+
+- **Writes refused or tokens missing after an upgrade.** Configuration is
+  file-based only: values supplied through environment variables are ignored.
+  Move `secretsDir`, `xoxcPath`, `xoxdPath`, `allowedWriteChannels`, and
+  `userAgent` into `~/.config/yt-slack-mcp/config.json`.
+- **Only some expected channels are writable.** `allowedWriteChannels` is the
+  complete list with no additive default; compare it with the channel IDs the
+  user expects.
+- **The server exits at startup.** A reported token path is missing; create the
+  file at that path. An empty or stale token does not stop startup; the first
+  Slack call fails later as `invalid_auth`.
+- **A write still fails inside an allowed channel.** The browser session may have
+  lost write access or the message may be outside the edit window; report the
+  exact `Error:` text instead of retrying.
+
+## Tool map
+
+Choose the read tool from what the user gave you, and the write tool from the
+action they asked for.
+
+| Tool | Use it when |
+|------|-------------|
+| `slack_read_permalink` | A Slack link is the input. Reads the linked message's thread, including inline images, PDF text, and text attachments. |
+| `slack_get_replies` | You have a channel ID and thread timestamp and need that thread again or its latest replies. |
+| `slack_get_history` | There is no link or thread: read recent messages when you have a channel ID. The tool does not resolve channel names. |
+| `slack_reply_to_thread` | Post a reply into an existing thread. Requires `channel_id`, `thread_ts`, `text`, and preferably `model`. |
+| `slack_add_reaction` | Mark or acknowledge a message without posting text. |
+| `slack_remove_reaction` | Remove a reaction this account added. |
+| `slack_upload_files` | Post up to 10 local files (10 MB each) to a channel or thread, with an optional `initial_comment`. |
+| `slack_edit_message` | Correct a message this account already posted, by channel ID and timestamp. |
+
+The server has no plain top-level text post; a reply needs an existing thread.
+A file upload with an `initial_comment` is the only way to start a new top-level
+message. Say so instead of promising a text post.
+
+## Recipes
+
+### Read a permalink and reply in its thread
+
+1. Call `slack_read_permalink` with the `url`.
+2. Take the channel ID from the permalink and the root `[ts]` from the first
+   returned message.
+3. Read the whole thread before answering; do not repost what is already there.
+4. Call `slack_reply_to_thread` with `channel_id`, `thread_ts`, `text`, and
+   `model` set to the model you are running.
+
+### Summarize a channel
+
+1. Resolve the channel ID first. The tool does not accept names like `#ops`; take
+   the ID from a permalink or ask the user.
+2. Call `slack_get_history` with `channel_id` and `limit` up to 200.
+3. Summarize in the conversation, quoting `[ts]` values when the user needs to
+   locate a message.
+4. Post the summary only when asked, and only as a reply in a relevant thread or
+   as a file upload's `initial_comment`; there is no plain top-level text post.
+
+### Upload a file with a comment
+
+1. Resolve absolute local paths; at most 10 files, 10 MB each.
+2. Call `slack_upload_files` with `file_paths`, `channel_id`, an optional
+   `thread_ts`, and `initial_comment` when a message should accompany the files.
+3. Pass `model`, which is used only when `initial_comment` is present; without a
+   comment the upload stays comment-free.
+4. Report the returned file and message permalinks.
+
+### Correct a posted message
+
+1. Call `slack_edit_message` with `channel_id`, the message `timestamp`, and the
+   replacement `text`.
+2. Leave `agent_authored` at its default for agent-written text; pass `model` so
+   the prefix names the model.
+3. Pass `agent_authored: false` only when replacing agent text with the user's own
+   words, such as correcting their message; `model` is then ignored.
+4. Slack removes existing Block Kit blocks on edit and only allows edits to this
+   account's messages within its edit window.
+
+## Guardrails
+
+- Read before writing. Fetch the thread or channel context first, even when the
+  requested text seems obvious.
+- Stay inside the allow-list. Never attempt a write to a channel that is not
+  listed, and never suggest disabling the check to "make it work".
+- Pass `model` on every text-writing call — reply, upload with a comment, edit —
+  so posts read `🤖 <model>:`. Never add the prefix yourself; the server adds it
+  once.
+- `agent_authored: false` is an explicit correction of non-agent text, not a
+  default and not a way to hide that an agent posted.
+- Channel names are not resolved. Never pass `#name` as `channel_id`; use a
+  `C...`, `G...`, or `D...` ID from a permalink or ask the user.
+- Prefer edits over reposting. Do not "fix" a message by posting it again.