diff --git a/AGENTS.md b/AGENTS.md
index ee150ca..0e363ea 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -2,4 +2,8 @@
 
 ## Skills
 
-This repo includes an installable skill at `skills/agent-slack/SKILL.md`. Ensure this stay in sync w/ the code (and Readme.md)
+This repo includes an installable skill at `skills/agent-slack/SKILL.md`. Keep it aligned with the code and README.
+
+- Write the skill for an agent executing Slack tasks, not as user-facing documentation.
+- Keep it token-efficient: do not add tables of contents, exhaustive command/flag catalogs, or duplicate the README and CLI help.
+- Treat the installed `agent-slack --help` and subcommand help as authoritative. Keep only non-obvious workflow, safety, targeting, and output behavior in the skill.
diff --git a/README.md b/README.md
index c223f24..b28c650 100644
--- a/README.md
+++ b/README.md
@@ -108,7 +108,7 @@ agent-slack
 
 Notes:
 
-- Output is **always JSON** and aggressively pruned (`null`/empty fields removed).
+- Slack data commands output aggressively pruned JSON (`null`/empty fields removed); help, update, and some authentication setup commands output text.
 - Attached files are auto-downloaded and returned as absolute local paths.
 
 ## Authentication (no fancy setup)
@@ -220,6 +220,8 @@ agent-slack message draft "https://workspace.slack.com/archives/C123/p1700000000
 
 After sending, the editor shows a "View in Slack" link to the posted message.
 
+`message draft` is send-capable. In CI, it skips the browser editor and immediately sends supplied text; do not use it for a compose-only request in a noninteractive environment.
+
 ### Reply, edit, delete, and react
 
 ```bash
@@ -384,7 +386,7 @@ When to use which:
 
 ### Files (snippets/images/attachments)
 
-`message get/list` auto-download attached files to an agent-friendly temp directory and return file metadata in `message.files[]`, including `name` when Slack provides the original filename and `path` for the local download. Failed downloads keep the attachment entry, preserve `message.files[].path` with a local `.download-error.txt` file, and include `message.files[].error`. `search messages` and `search all` use the same attachment shape for message results, while `search files` skips entries whose download fails.
+`message get/list` auto-download attached files to an agent-friendly temp directory and return file metadata in `message.files[]`, including `name` when Slack provides the original filename and `path` for the local download. Failed downloads keep the attachment entry, preserve `message.files[].path` with a local `.download-error.txt` file, and include `message.files[].error`. `search messages` and `search all` use the same attachment shape for message results, while `search files` skips entries whose download fails. Use `search messages --content-type file` when you also need the source-message permalink for a reply.
 
 - macOS default: `~/.agent-slack/tmp/downloads/`
 
@@ -421,6 +423,9 @@ agent-slack user list --workspace "https://workspace.slack.com" --limit 200 | jq
 # Get one user by id or handle
 agent-slack user get U12345678 --workspace "https://workspace.slack.com" | jq .
 agent-slack user get "@alice" --workspace "https://workspace.slack.com" | jq .
+
+# Open a DM or group DM with one to eight other users (the caller is implicit)
+agent-slack user dm-open "@alice" "@bob" --workspace "https://workspace.slack.com" | jq .
 ```
 
 ### Unreads (inbox view)
@@ -498,6 +503,8 @@ agent-slack later remind "https://workspace.slack.com/archives/C123/p17000000000
 agent-slack later remind "https://workspace.slack.com/archives/C123/p1700000000000000" --in tomorrow
 ```
 
+Named reminder days such as `tomorrow` and `monday` mean 9:00 in the CLI process's local timezone. Use a Unix timestamp when timezone precision matters.
+
 ### Create or fetch a Canvas as Markdown
 
 ```bash
diff --git a/llms.txt b/llms.txt
index 3c6227b..6dadca7 100644
--- a/llms.txt
+++ b/llms.txt
@@ -6,7 +6,7 @@
 
 - [README](https://github.com/stablyai/agent-slack/blob/main/README.md): Full documentation with installation, authentication, and usage examples
 - [Agent Skill (SKILL.md)](https://github.com/stablyai/agent-slack/blob/main/skills/agent-slack/SKILL.md): Integration guide for Claude Code, Cursor, Codex, and custom AI agents
-- [Command References](https://github.com/stablyai/agent-slack/blob/main/skills/agent-slack/references/): Detailed per-command documentation with examples
+- [Agent References](https://github.com/stablyai/agent-slack/blob/main/skills/agent-slack/references/): Non-obvious targeting, output, and download behavior
 
 ## Key Features
 
diff --git a/skills/agent-slack/SKILL.md b/skills/agent-slack/SKILL.md
index 50e502a..1f2babc 100644
--- a/skills/agent-slack/SKILL.md
+++ b/skills/agent-slack/SKILL.md
@@ -5,7 +5,7 @@ description: "Slack CLI for agents: read URLs/threads/history/unreads/later/canv
 
 # agent-slack
 
-CLI on `$PATH`: `agent-slack ...`. If missing, prefer:
+Use `agent-slack` from `$PATH`. If it is missing, install it with:
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/stablyai/agent-slack/main/install.sh | sh
@@ -13,42 +13,30 @@ curl -fsSL https://raw.githubusercontent.com/stablyai/agent-slack/main/install.s
 
 Fallback: `npm i -g agent-slack` (Node >= 22.5).
 
-Treat the installed CLI's `agent-slack --help` and `agent-slack <command> --help` output as authoritative for supported commands and flags.
+Run `agent-slack --help` or the relevant subcommand help before guessing a command or flag.
+If a capability named here is absent from installed help, report version skew instead of guessing. Do not self-update the CLI without explicit authorization.
 
-Safety: read/search freely. Treat sends, edits, deletes, reactions, invitations, channel or canvas creation, mark-read operations, schedules, uploads, scheduled-message cancellation, and `workflow run` as write actions; perform them only when explicitly requested. Workflow runs can execute downstream actions. Prefer `message draft`.
+## Safety
 
-Auth: `agent-slack auth whoami`; if needed `auth import-desktop`, `auth import-brave`, `auth import-chrome`, or `auth import-firefox`, then `auth test`.
+- Read and search freely.
+- Perform write actions only when explicitly requested: sends, edits, deletes, reactions, invitations, channel or canvas creation, mark-read operations, scheduling or canceling delivery, uploads, Later state/reminder changes, DM/group-DM creation, and `workflow run`. Workflow runs can execute downstream actions.
+- For compose- or review-only requests, return proposed text without invoking Slack. `message draft` is send-capable; use it only when the user explicitly asks to open the interactive editor. In CI or another noninteractive environment, do not invoke it without separate authorization to send immediately: CI skips the editor and sends supplied text.
 
-For labeled links inside bullet or numbered lists, use Slack's `<URL|label>` syntax. Auto-converted lists do not convert CommonMark `[label](URL)` links into labeled link elements.
+## Workflow
 
-Common commands:
+1. Run `agent-slack auth whoami`. If needed, import credentials with `auth import-desktop`, `auth import-brave`, `auth import-chrome`, or `auth import-firefox`, then run `auth test`.
+2. Prefer a Slack message URL when one is available. It carries the workspace, channel, and timestamp needed by most message operations.
+3. Choose the narrowest read operation: `message get` for one message, `message list` for a full thread or channel history, and `search messages` or `search files` for discovery.
+4. Use output limits such as `--limit`, `--max-body-chars`, and `--max-content-chars` to avoid unnecessary context.
+5. For a requested write, execute only the requested mutation and verify the resulting JSON metadata.
 
-```bash
-agent-slack message get "SLACK_URL"
-agent-slack message list "SLACK_URL"
-agent-slack message list "general" --limit 20
-agent-slack search messages "query" --channel "general"
-agent-slack message draft "general" "text"
-agent-slack message send "URL_OR_CHANNEL" "text" --attach ./file.md
-agent-slack message send "general" "text" --schedule-in "3h"
-agent-slack message scheduled list
-agent-slack message scheduled cancel "SCHEDULED_ID" --channel "CHANNEL_ID"
-agent-slack unreads
-agent-slack later list
-agent-slack canvas create --file ./plan.md --title "Plan"
-agent-slack canvas create --markdown $'# Plan\n\n- [ ] Ship it'
-agent-slack canvas get "CANVAS_URL"
-agent-slack workflow list "general"
-agent-slack user list
-agent-slack channel list
-agent-slack user dm-open @alice @bob
-```
+For scheduled writes, prefer `--schedule` with an ISO 8601 timestamp and explicit offset when timezone matters. Named `--schedule-in` phrases use the executing environment's local timezone; confirm that it matches the user's intent.
+
+Named `later remind --in` values such as `tomorrow` or `monday` also use the executing environment's local timezone at 9:00. Confirm that timezone or pass an explicit Unix timestamp.
 
-With multiple workspaces, pass `--workspace "team"` or set `SLACK_WORKSPACE_URL`. Attachments include local `path` in JSON.
-Treat Slack user IDs beginning with `U` or `W` equivalently.
+Ordinary `message send` and `message edit` calls auto-convert lists. `message send --blocks` uses supplied blocks, while `message send --attach` sends its initial comment without automatic list conversion. Inside auto-converted lists, use Slack's `<URL|label>` syntax because CommonMark `[label](URL)` links are not converted into labeled link elements.
 
-For non-trivial usage, read the bundled references:
+## Conditional references
 
-- [references/commands.md](references/commands.md): command map and flags
-- [references/targets.md](references/targets.md): URL, channel, and direct-message targeting rules
-- [references/output.md](references/output.md): JSON shapes and download paths
+- Read [references/targets.md](references/targets.md) only when choosing between a message URL, channel, or user target, or when resolving multiple workspaces.
+- Read [references/output.md](references/output.md) only when handling returned message or canvas metadata, resolved users, or downloaded and failed attachments.
diff --git a/skills/agent-slack/references/commands.md b/skills/agent-slack/references/commands.md
deleted file mode 100644
index efa7419..0000000
--- a/skills/agent-slack/references/commands.md
+++ /dev/null
@@ -1,227 +0,0 @@
-# `agent-slack` command map (reference)
-
-## Contents
-
-- [Auth](#auth)
-- [Messages / threads](#messages--threads)
-- [Channels](#channels)
-- [Later](#later)
-- [Unreads](#unreads)
-- [Search](#search)
-- [Canvas](#canvas)
-- [Workflows](#workflows)
-- [Users](#users)
-
-Treat the installed CLI's `agent-slack --help` and `agent-slack <command> --help` output as authoritative for supported commands and flags.
-
-## Auth
-
-- `agent-slack auth whoami` — show configured workspaces + token sources (secrets redacted)
-- `agent-slack auth test [--workspace <url-or-unique-substring>]` — verify credentials (`auth.test`)
-- `agent-slack auth import-desktop` — import browser-style creds from Slack Desktop (macOS/Windows)
-- `agent-slack auth import-brave` — import creds from Brave (macOS; requires View → Developer → Allow JavaScript from Apple Events)
-- `agent-slack auth import-chrome` — import creds from Chrome (macOS)
-- `agent-slack auth import-firefox` — import creds from Firefox profile storage (macOS/Linux)
-- `agent-slack auth parse-curl` — read a copied Slack cURL command from stdin and save creds
-- `agent-slack auth add --workspace-url <url> [--token <xoxb/xoxp> | --xoxc <xoxc> --xoxd <xoxd>]`
-- `agent-slack auth set-default <workspace-url>`
-- `agent-slack auth remove <workspace-url>`
-
-## Messages / threads
-
-### Automatic rich-text formatting
-
-`message edit` and `message send` without `--attach` convert bullet and numbered lists to Slack native rich text. `message send --blocks` bypasses automatic conversion, while `message send --attach` sends its initial comment as plain text without automatic list conversion. Inside auto-converted lists, use `<URL|label>` for labeled links; CommonMark `[label](URL)` links are not converted into labeled link elements.
-
-- `agent-slack message get <target>`
-  - `<target>`: Slack message URL OR `#channel`/`channel`/channel id (`C...`) (see `targets.md`)
-  - Options:
-    - `--workspace <url-or-unique-substring>` (required when using a channel _name_ across multiple workspaces)
-    - `--ts <seconds>.<micros>` (required when targeting a channel)
-    - `--thread-ts <seconds>.<micros>` (optional hint for thread permalinks)
-    - `--max-body-chars <n>` (default `8000`, `-1` unlimited)
-    - `--include-reactions`
-    - `--resolve-users` (attach resolved user profiles in `referenced_users`)
-    - `--refresh-users` (implies `--resolve-users` and forces a cache refresh)
-
-- `agent-slack message list <target>`
-  - Uses channel-history mode by default. A message URL, `--thread-ts`, or `--ts` selects thread mode, which returns the root plus all replies.
-  - **Channel history** (default when targeting a channel without `--thread-ts`):
-    - `agent-slack message list "general"` — latest 25 messages
-    - `agent-slack message list "general" --limit 50` — latest 50 messages
-  - **Thread mode**:
-    - `agent-slack message list "<url>"` — full thread
-    - `agent-slack message list "general" --thread-ts "1770165109.000001"` — full thread
-  - Options:
-    - `--workspace <url-or-unique-substring>` (same rules as above)
-    - `--thread-ts <seconds>.<micros>` (switches to thread mode)
-    - `--ts <seconds>.<micros>` (resolve a message to its thread)
-    - `--limit <n>` (default `25`, max `200`; channel history mode only)
-    - `--oldest <ts>` (only messages after this ts; channel history mode)
-    - `--latest <ts>` (only messages before this ts; channel history mode)
-    - `--with-reaction <emoji>` (repeatable; include only messages that have this reaction; channel history mode; requires `--oldest`)
-    - `--without-reaction <emoji>` (repeatable; include only messages that do not have this reaction; channel history mode; requires `--oldest`)
-    - `--max-body-chars <n>` (default `8000`, `-1` unlimited)
-    - `--include-reactions`
-    - `--resolve-users` (attach resolved user profiles in `referenced_users`)
-    - `--refresh-users` (implies `--resolve-users` and forces a cache refresh)
-
-- `agent-slack message draft <target> [text]`
-  - Opens a Slack-like WYSIWYG editor in the browser for composing and sending a message.
-  - Formatting toolbar: bold, italic, strikethrough, links, numbered/bulleted lists, quotes, inline code, code blocks.
-  - Toggle between rich-text editing and raw mrkdwn source view.
-  - After sending, shows a "View in Slack" permalink to the posted message.
-  - If `<target>` is a Slack message URL, the draft will reply in that thread.
-  - Options:
-    - `--workspace <url-or-unique-substring>` (needed for channel _names_ across multiple workspaces)
-    - `--thread-ts <seconds>.<micros>` (optional, channel mode only)
-
-- `agent-slack message send <target> [text]`
-  - If `<target>` is a Slack message URL, replies in that message’s thread.
-  - A user ID target (`U...` or `W...`) opens or reuses that user's DM.
-  - Otherwise posts to the channel/DM.
-  - `[text]` is optional when uploading files with `--attach`; when present, it becomes the initial comment on the first uploaded file.
-  - Example: `agent-slack message send "general" "Coverage report" --attach ./report.md`
-  - Example: `agent-slack message send "general" "Monday launch checklist" --schedule-in "monday 9am"`
-  - Options:
-    - `--workspace <url-or-unique-substring>` (needed for channel _names_ across multiple workspaces)
-    - `--thread-ts <seconds>.<micros>` (optional, channel mode only)
-    - `--attach <path>` (repeatable; upload local files as attachments)
-    - `--blocks <path>` raw Block Kit blocks from a JSON file (or `-` for stdin). Bypasses markdown-to-rich-text conversion; enables header/divider/section/table blocks. Cannot be combined with `--attach`.
-    - `--reply-broadcast` when replying in a thread, also post the reply to the parent channel. For channel targets, pair with `--thread-ts`; for URL targets, the thread context is derived from the message. Not supported for DM targets; cannot be combined with `--attach`.
-    - `--schedule <time>` schedule delivery at an ISO 8601 timestamp with explicit timezone (or Unix timestamp). Must be in the future and within Slack's 120-day scheduled-send limit. Compatible with `--blocks`, `--thread-ts`, and `--reply-broadcast`; cannot be combined with `--attach`.
-    - `--schedule-in <duration>` schedule delivery after a duration or simple future phrase (`30m`, `3h`, `2d`, `tomorrow 9am`, `monday 9am`; phrases use your local timezone). Mutually exclusive with `--schedule`; cannot be combined with `--attach`.
-
-- `agent-slack message scheduled list`
-  - Lists pending scheduled messages from Slack's server-side scheduled message queue.
-  - Options:
-    - `--workspace <url-or-unique-substring>` (defaults to configured workspace)
-    - `--channel <channel>` filter to a channel/DM id or channel name
-    - `--oldest <unix-ts>` only messages scheduled after this time
-    - `--latest <unix-ts>` only messages scheduled before this time
-    - `--cursor <cursor>` fetch the next page
-    - `--limit <n>` max messages to return
-
-- `agent-slack message scheduled cancel <scheduled_message_id>`
-  - Cancels a pending scheduled message before it is sent.
-  - Options:
-    - `--channel <channel>` required channel/DM id or channel name for the scheduled message
-    - `--workspace <url-or-unique-substring>` (needed for channel _names_ across multiple workspaces)
-
-- `agent-slack message edit <target> <text>`
-  - URL target edits that exact message.
-  - Channel target requires `--ts`.
-  - Options:
-    - `--workspace <url-or-unique-substring>` (needed for channel _names_ across multiple workspaces)
-    - `--ts <seconds>.<micros>` (required for channel targets)
-
-- `agent-slack message delete <target>`
-  - URL target deletes that exact message.
-  - Channel target requires `--ts`.
-  - Options:
-    - `--workspace <url-or-unique-substring>` (needed for channel _names_ across multiple workspaces)
-    - `--ts <seconds>.<micros>` (required for channel targets)
-
-- `agent-slack message react add <target> <emoji>`
-- `agent-slack message react remove <target> <emoji>`
-  - Options (channel mode):
-    - `--workspace <url-or-unique-substring>` (needed for channel _names_ across multiple workspaces)
-    - `--ts <seconds>.<micros>` (required for channel targets)
-
-## Channels
-
-- `agent-slack channel list [--workspace <url-or-unique-substring>] [--user <U...|W...|@handle|handle> | --all] [--limit <n>] [--cursor <cursor>]`
-  - Default mode calls `users.conversations` for the current user.
-  - `--user` resolves handles/ids and lists conversations for that user.
-  - `--all` switches to `conversations.list` (mutually exclusive with `--user`).
-  - Returns one page and optional `next_cursor`; pass `--cursor` to continue.
-- `agent-slack channel new --name <name> [--private] [--workspace <url-or-unique-substring>]`
-- `agent-slack channel invite --channel <id|name> --users "<user,...>" [--workspace <url-or-unique-substring>]`
-  - Internal invite (default): each `<user>` may be a `U...`/`W...` ID, `@handle`, handle, or email; uses `conversations.invite`
-  - External invite: add `--external` (email targets only) to use `conversations.inviteShared`
-  - Optional: `--allow-external-user-invites` sets `external_limited=false` for external invites
-- `agent-slack channel mark <target> [--ts <seconds>.<micros>] [--workspace <url-or-unique-substring>]`
-  - Marks a channel/DM as read up to the given message timestamp (`conversations.mark`)
-  - URL target extracts channel, ts, and workspace automatically; `--ts` optionally overrides the URL timestamp; `--workspace` is rejected
-  - Channel name/ID target requires `--ts`
-
-## Later
-
-- `agent-slack later list` — list saved-for-later messages (default: in-progress)
-  - Options:
-    - `--workspace <url-or-unique-substring>` (defaults to configured workspace)
-    - `--state <state>` (filter: `in_progress` (default), `archived`, `completed`, `all`)
-    - `--limit <n>` (max items, default `20`)
-    - `--max-body-chars <n>` (max content chars per message, default `4000`, `-1` unlimited)
-    - `--counts-only` (only show counts per state)
-
-- `agent-slack later complete <target>` — mark a saved message as completed
-- `agent-slack later archive <target>` — archive a saved message
-- `agent-slack later reopen <target>` — move back to in-progress (from completed or archived)
-- `agent-slack later save <target>` — save a message for later
-- `agent-slack later remove <target>` — remove from Later entirely
-  - All accept Slack message URL or channel ID with `--ts`
-  - Options: `--workspace <url-or-unique-substring>`, `--ts <seconds>.<micros>`
-
-- `agent-slack later remind <target> --in <duration>` — set a reminder on a saved item
-  - `--in` accepts: `30m`, `1h`, `3h`, `2d`, `tomorrow`, `monday`, or a unix timestamp
-  - Options: `--workspace <url-or-unique-substring>`, `--ts <seconds>.<micros>`
-
-## Unreads
-
-- `agent-slack unreads` — show all unread messages across channels, DMs, and threads
-  - Options:
-    - `--workspace <url-or-unique-substring>` (defaults to configured workspace)
-    - `--counts-only` (only show unread counts, skip message content)
-    - `--max-messages <n>` (max unread messages per channel, default `10`)
-    - `--max-body-chars <n>` (max content chars per message, default `4000`, `-1` unlimited)
-    - `--include-system` (include system messages like joins, leaves, topic changes; excluded by default)
-
-## Search
-
-- `agent-slack search all <query>` — messages + files (default)
-- `agent-slack search messages <query>`
-- `agent-slack search files <query>`
-
-Common options:
-
-- `--workspace <url-or-unique-substring>` (recommended when using channel names across multiple workspaces)
-- `--channel <channel...>` repeatable (`#name`, `name`, or id)
-- `--user <U...|W...|@name|name>`
-- `--after YYYY-MM-DD`
-- `--before YYYY-MM-DD`
-- `--content-type any|text|image|snippet|file`
-- `--limit <n>` (default `20`)
-- `--max-content-chars <n>` (default `4000`, `-1` unlimited; messages only)
-- `--resolve-users` (attach resolved user profiles in `referenced_users`; applies to `search messages` / `search all`)
-- `--refresh-users` (implies `--resolve-users` and forces a cache refresh)
-
-## Canvas
-
-- `agent-slack canvas create (--file <path> | --markdown <text>)`
-  - Creates a standalone canvas owned by the acting user from exactly one Markdown source.
-  - Markdown from either source is passed to Slack unchanged.
-  - Options:
-    - `--file <path>` read Markdown from a local file (mutually exclusive with `--markdown`)
-    - `--markdown <text>` use a Markdown string directly (mutually exclusive with `--file`)
-    - `--title <title>` set the canvas title
-    - `--channel <id-or-name>` add the canvas as a channel tab; required on free Slack plans and requires a standard Slack token
-    - `--workspace <url-or-unique-substring>` select the workspace; required for a channel name across multiple workspaces
-  - Imported browser credentials support standalone canvases. Standard tokens require Slack's `canvases:write` scope and are required with `--channel`.
-- `agent-slack canvas get <canvas-url-or-id>`
-  - Options:
-    - `--workspace <url-or-unique-substring>` (required when passing an id and multiple workspaces)
-    - `--max-chars <n>` (default `20000`, `-1` unlimited)
-
-## Workflows
-
-- `agent-slack workflow list <channel> [--workspace <url-or-unique-substring>]` — list workflows bookmarked or featured in a channel
-- `agent-slack workflow preview <trigger-id> [--workspace <url-or-unique-substring>]` — get workflow metadata from a trigger ID (no side effects)
-- `agent-slack workflow get <id> [--workspace <url-or-unique-substring>]` — get workflow definition including form fields and steps (accepts `Ft...` or `Wf...`)
-- `agent-slack workflow run <trigger-id> --channel <id-or-name> [--workspace <url-or-unique-substring>]` — execute a workflow trigger. This is a write action that can perform downstream actions; run it only when explicitly requested.
-
-## Users
-
-- `agent-slack user list [--workspace <url-or-unique-substring>] [--limit <n>] [--cursor <cursor>] [--include-bots]`
-- `agent-slack user get <U...|W...|@handle|handle> [--workspace <url-or-unique-substring>]`
-- `agent-slack user dm-open <users...> [--workspace <url-or-unique-substring>]` — get a DM or group DM channel ID for one or more `U...`/`W...` IDs or handles (max 8)
diff --git a/skills/agent-slack/references/output.md b/skills/agent-slack/references/output.md
index a4732e5..576b35a 100644
--- a/skills/agent-slack/references/output.md
+++ b/skills/agent-slack/references/output.md
@@ -1,148 +1,28 @@
-# Output + downloads (reference)
+# JSON output and downloads
 
-## Contents
-
-- [Output format](#output-format)
-- [Message shapes](#message-shapes-high-level)
-- [Later shape](#later-shape-high-level)
-- [Unreads shape](#unreads-shape-high-level)
-- [Search shapes](#search-shapes-high-level)
-- [Channel shapes](#channel-shapes-high-level)
-- [File fields in compact messages](#file-fields-in-compact-messages)
-- [Attachment downloads](#attachment-downloads)
-
-## Output format
-
-All commands print JSON to stdout.
+Slack data commands print JSON to stdout. Help, update, and some authentication setup commands print text instead.
 
 - Empty values are pruned (`null`, `[]`, `{}` are removed where possible).
 - `auth whoami` redacts secrets in its output.
 
-## Message shapes (high-level)
-
-- `message get` returns:
-  - `message: { ... }`
-  - `thread?: { ts, length }` (summary only; present when threaded)
-  - `referenced_users?: { [user_id]: { id, name?, real_name?, display_name?, ... } }`
-
-- `message list` returns:
-  - `messages: [ ... ]` (the full thread)
-  - `referenced_users?: { [user_id]: { id, name?, real_name?, display_name?, ... } }`
-  - Messages are compact and omit redundant fields on each item where possible.
-
-- `message send` returns:
-  - `ok: true`
-  - `channel_id: "C..." | "D..."`
-  - `ts?: "<seconds>.<micros>"` — the posted message's ts; absent on file-attachment sends
-  - `thread_ts?: "<seconds>.<micros>"` — present only when the send was into an existing thread
-  - `permalink?: "https://.../archives/..."` — present when `ts` is known and a workspace URL was resolvable
-  - `scheduled_message_id?: "Q..."` — present for `--schedule` / `--schedule-in` sends
-  - `post_at?: <unix-seconds>` — present for scheduled sends
-
-- `message scheduled list` returns:
-  - `scheduled_messages: [{ id, channel_id, post_at, date_created?, text? }]`
-  - `next_cursor?: "<cursor>"`
-
-- `message scheduled cancel` returns:
-  - `ok: true`
-  - `channel_id: "C..." | "D..."`
-  - `scheduled_message_id: "Q..."`
-
-Message payload fields keep canonical user IDs (for example `author.user_id`, reaction `users[]`, and `@U...` or `@W...` mentions in rendered content).
-`referenced_users` provides display metadata for those IDs. The cache is per-workspace with a 24-hour per-entry TTL.
-This behavior is opt-in and requires passing the `--resolve-users` flag (or `--refresh-users` to bypass the cache).
-
-Use `--max-body-chars` to cap message bodies for token budget control.
-
-## Later shape (high-level)
-
-- `later list` returns:
-  - `counts: { in_progress, archived, completed, total }`
-  - `items: [{ channel_id, channel_name, ts, state, date_saved, message? }]`
-  - `message` includes `author`, `content`, `thread_ts`, `reply_count`
-  - Items sorted by most recently saved first
-  - With `--counts-only`, `items` is omitted
-
-- `later complete/archive/reopen/save/remove` returns `{ ok: true }`
-- `later remind` returns `{ ok: true, remind_at }`
-
-## Unreads shape (high-level)
+`message get` returns one message and an optional thread summary. `message list` returns chronological messages; in thread mode this includes the root and all replies.
 
-- `unreads` returns:
-  - `channels: [{ channel_id, channel_name, channel_type, unread_count, mention_count, messages? }]`
-  - `threads?: { has_unreads, mention_count }` (present when there are unread thread replies)
-  - `channel_type` is one of: `"channel"`, `"dm"`, `"mpim"`, `"group"`
-  - Channels sorted by mention count (desc), then unread count (desc)
-  - System messages (joins, leaves, topic changes) are excluded by default; use `--include-system` to include them
-  - With `--counts-only`, `messages` is omitted
+Immediate non-attachment sends return `ts` and usually a `permalink`. Attachment sends return neither; scheduled sends return `scheduled_message_id` and `post_at` instead.
 
-## Search shapes (high-level)
+`canvas create` returns `canvas: { id, title?, channel_id? }`. `canvas get` returns `canvas: { id, title?, markdown }`.
 
-- `search messages|all` returns `messages: [ ... ]`
-- `search messages|all` may include `referenced_users?: { [user_id]: { id, name?, real_name?, display_name?, ... } }`
-- `search files|all` returns `files: [ ... ]`
+Message payloads keep canonical user IDs. Pass `--resolve-users` to add display metadata under `referenced_users`, or `--refresh-users` to refresh the 24-hour per-workspace cache before resolving.
 
-Use `--max-content-chars` (messages) and `--limit` to control size.
+Use `--max-body-chars`, `--max-content-chars`, `--limit`, or a command's counts-only mode to keep results within the task's needs.
 
-## Channel shapes (high-level)
+## Downloaded files
 
-- `channel list` returns:
-  - `channels: [ ... ]`
-  - `next_cursor?: string` (present when more pages are available)
-
-- `channel new` returns:
-  - `channel: { id, name, is_private }`
-
-- `channel invite` returns:
-  - Internal invite mode:
-    - `channel_id`
-    - `invited_user_ids: [ ... ]`
-    - `already_in_channel_user_ids?: [ ... ]`
-    - `unresolved_users?: [ ... ]`
-  - External invite mode (`--external`):
-    - `channel_id`
-    - `external: true`
-    - `external_limited: boolean`
-    - `invited_emails: [ ... ]`
-    - `already_invited_emails?: [ ... ]`
-    - `invalid_external_targets?: [ ... ]`
-
-- `channel mark` returns:
-  - `ok: boolean`
-  - `channel: string` (resolved channel ID)
-  - `ts: string`
-
-## Canvas shapes (high-level)
-
-- `canvas create` returns:
-  - `canvas: { id, title?, channel_id? }`
-- `canvas get` returns:
-  - `canvas: { id, title?, markdown }`
-
-## File fields in compact messages
-
-When messages include file attachments, each file object contains:
-
-- `name` — the original filename (e.g. `"report.pdf"`), omitted if unavailable
-- `mimetype` — MIME type (e.g. `"application/pdf"`)
-- `mode` — Slack file mode (e.g. `"hosted"`, `"snippet"`)
-- `path` — absolute local path to the downloaded file
-
-Only files with a successful download are included.
-
-## Attachment downloads
-
-Attachments are downloaded to an agent-friendly temp directory.
+Message reads and searches download Slack files locally. Each successful file includes an absolute `path` plus available metadata such as `name`, `mimetype`, and `mode`.
 
 - Successful downloads are returned as absolute paths in output.
-- `message get/list` preserves failed attachment downloads with `message.files[].error` and keeps `message.files[].path` pointing to a local `.download-error.txt` file.
+- `message get` preserves failed downloads in `message.files[]`; `message list` uses `messages[].files[]`. Each failed entry has `error` and a `path` to a local `.download-error.txt` file.
 - Message results from `search messages|all` preserve failed attachment downloads with `messages[].files[].error` and keep `messages[].files[].path` pointing to a local `.download-error.txt` file.
-- `search files` skips files whose download fails and continues returning the remaining matches.
-
-Default download root:
-
-- `~/.agent-slack/tmp/downloads/`
-
-If `XDG_RUNTIME_DIR` is set, downloads live under:
+- `search files` warns and skips files whose download fails. Do not treat a skip warning as proof that no matching file exists; retry through the source message with `message get/list` when possible.
+- For download-then-reply workflows, use `search messages --content-type file`: `search files` results include local paths but no source-message permalink or thread target.
 
-- `$XDG_RUNTIME_DIR/agent-slack/tmp/downloads/`
+Downloads use `$XDG_RUNTIME_DIR/agent-slack/tmp/downloads/` when `XDG_RUNTIME_DIR` is set; otherwise they use `~/.agent-slack/tmp/downloads/`.
diff --git a/skills/agent-slack/references/targets.md b/skills/agent-slack/references/targets.md
index 8c38512..a4636af 100644
--- a/skills/agent-slack/references/targets.md
+++ b/skills/agent-slack/references/targets.md
@@ -1,91 +1,26 @@
-# Targets: URLs, channels, and users (reference)
+# Target selection
 
-Message commands accept a **Slack message URL** (preferred) or a **channel reference**.
-`message send` also accepts a Slack user ID to open or reuse a direct message.
-
-## Preferred: Slack message URL
-
-Use the message permalink whenever you have it:
+Prefer a Slack message URL whenever one is available:
 
 ```text
 https://<workspace>.slack.com/archives/<channel_id>/p<digits>[?thread_ts=...]
 ```
 
-Examples:
-
-- `agent-slack message get "<url>"`
-- `agent-slack message list "<url>"`
-- `agent-slack message send "<url>" "reply text"`
-- `agent-slack message edit "<url>" "updated text"`
-- `agent-slack message delete "<url>"`
-- `agent-slack message react add "<url>" "eyes"`
-- `agent-slack channel mark "<url>"`
-
-## Direct-message target (`message send` only)
-
-Pass a `U...` or `W...` user ID to open or reuse that user's direct-message channel:
-
-```bash
-agent-slack message send "W12345678" "Hello"
-```
-
-Other message operations require a message URL or channel reference.
-
-## Channel targets (when you don’t have a URL)
-
-Channel references can be:
-
-- channel name: `general` (bare name, without `#` prefix)
-- channel id: `C...` (or `G...`/`D...`)
-
-### `message get` by channel + `--ts`
-
-```bash
-agent-slack message get "general" --ts "1770165109.628379"
-```
+A URL supplies the workspace, channel, and message timestamp. With a URL target:
 
-### `message list` by channel + `--thread-ts` (or `--ts` to resolve)
+- `message get`, `edit`, `delete`, and `react` operate on that message.
+- `message list` returns the thread root and all replies.
+- `message send` replies in that message's thread. `message draft` does the same unless `--thread-ts` explicitly overrides the URL-derived thread.
+- `channel mark` marks through that message timestamp; `--ts` explicitly overrides the timestamp. It rejects `--workspace` because the URL supplies it.
 
-```bash
-agent-slack message list "general" --thread-ts "1770165109.000001"
-agent-slack message list "general" --ts "1770165109.628379"
-agent-slack message list "general" --without-reaction dart --oldest "1770165109.000000" --limit 20
-```
-
-### Reactions by channel + `--ts`
-
-```bash
-agent-slack message react add "general" "eyes" --ts "1770165109.628379"
-```
-
-### Edit/delete by channel + `--ts`
-
-```bash
-agent-slack message edit "general" "updated text" --ts "1770165109.628379"
-agent-slack message delete "general" --ts "1770165109.628379"
-```
-
-### Mark as read by channel + `--ts`
-
-```bash
-agent-slack channel mark "general" --ts "1770165109.628379"
-agent-slack channel mark "D0A04PB2QBW" --ts "1770165109.628379"
-```
-
-### Channel admin by id/name
-
-```bash
-agent-slack channel invite --channel "general" --users "@alice,bob@example.com"
-agent-slack channel invite --channel "C0123ABCDEF" --users "U01234567"
-agent-slack channel invite --channel "shared-room" --users "partner@vendor.com" --external
-agent-slack channel invite --channel "shared-room" --users "partner@vendor.com" --external --allow-external-user-invites
-```
+Use a channel name or a `C...`, `G...`, or `D...` channel ID only when no URL is available:
 
-## Multi-workspace ambiguity (channel names only)
+- `message get`, `edit`, `delete`, and `react` require `--ts`.
+- `message list` reads channel history unless `--thread-ts` or `--ts` selects a thread.
+- `channel mark` requires `--ts`.
 
-If you have multiple workspaces configured and your target is a channel **name** (e.g. `general`), you must disambiguate:
+Among `message` subcommands, only `message send` accepts a `U...` or `W...` user ID as a target; it opens or reuses that user's direct-message channel. Treat `U`- and `W`-prefixed user IDs equivalently.
 
-- pass `--workspace "https://myteam.slack.com"` (or a unique substring like `--workspace "myteam"`), or
-- set `SLACK_WORKSPACE_URL` to the same selector format
+Use `user dm-open <users...>` with one to eight other user IDs or handles to get a DM or group-DM channel ID, then use that channel ID for message operations. The authenticated caller is implicit.
 
-Channel IDs (`C...`/`G...`/`D...`) do not require `--workspace`.
+Non-URL targets do not carry workspace identity. When multiple workspaces are configured, use the intended configured default or pass `--workspace <url-or-unique-substring>`/`SLACK_WORKSPACE_URL`, including for channel, user, canvas, and workflow IDs.
diff --git a/src/cli/canvas-command.ts b/src/cli/canvas-command.ts
index 4d89f4a..b68445c 100644
--- a/src/cli/canvas-command.ts
+++ b/src/cli/canvas-command.ts
@@ -51,13 +51,13 @@ export function registerCanvasCommand(input: { program: Command; ctx: CliContext
 
   canvasCmd
     .command("create")
-    .description("Create a Slack canvas from Markdown")
-    .option("--file <path>", "Read Markdown from a local file")
-    .option("--markdown <text>", "Use a Markdown string directly")
+    .description("Create a Slack canvas from exactly one Markdown source")
+    .option("--file <path>", "Read Markdown from a local file; mutually exclusive with --markdown")
+    .option("--markdown <text>", "Use a Markdown string; mutually exclusive with --file")
     .option("--title <title>", "Canvas title")
     .option(
       "--channel <id-or-name>",
-      "Add the canvas as a channel tab (required on free Slack plans)",
+      "Add as a channel tab (required on free Slack plans; requires a standard token with canvases:write; browser auth supports standalone canvases only)",
     )
     .option(
       "--workspace <url>",
diff --git a/src/cli/channel-command.ts b/src/cli/channel-command.ts
index 8a46cc9..64a6aa1 100644
--- a/src/cli/channel-command.ts
+++ b/src/cli/channel-command.ts
@@ -227,10 +227,13 @@ export function registerChannelCommand(input: { program: Command; ctx: CliContex
     .command("mark")
     .description("Mark a channel/DM as read up to a given message")
     .argument("<target>", "Slack message URL, #channel, or channel ID")
-    .option("--ts <ts>", "Message ts to mark as read (required when target is a channel name/ID)")
+    .option(
+      "--ts <ts>",
+      "Message ts to mark as read (required for channel name/ID targets; overrides a URL timestamp)",
+    )
     .option(
       "--workspace <url>",
-      "Workspace selector (full URL or unique substring; required if you have multiple workspaces)",
+      "Workspace selector for channel name/ID targets; cannot be used with URL targets",
     )
     .action(async (...args) => {
       const [targetArg, options] = args as [string, { ts?: string; workspace?: string }];
diff --git a/src/cli/later-command.ts b/src/cli/later-command.ts
index 9d5097f..783522b 100644
--- a/src/cli/later-command.ts
+++ b/src/cli/later-command.ts
@@ -240,7 +240,10 @@ export function registerLaterCommand(input: { program: Command; ctx: CliContext
     .command("remind")
     .description("Set a reminder for a saved message")
     .argument("<target>", "Slack message URL or channel ID")
-    .requiredOption("--in <duration>", "When to remind: 30m, 1h, 3h, 2d, tomorrow, monday, etc.")
+    .requiredOption(
+      "--in <duration>",
+      "When to remind: 30m, 1h, 3h, 2d, tomorrow, monday, or Unix timestamp; named days use this process's local timezone at 9:00",
+    )
     .option("--workspace <url>", "Workspace URL")
     .option("--ts <ts>", "Message ts (required when using channel ID)")
     .action(async (...args) => {
diff --git a/src/cli/message-command.ts b/src/cli/message-command.ts
index dc58759..71e25f7 100644
--- a/src/cli/message-command.ts
+++ b/src/cli/message-command.ts
@@ -166,23 +166,31 @@ export function registerMessageCommand(input: { program: Command; ctx: CliContex
       "--workspace <url>",
       "Workspace selector (full URL or unique substring; needed when using #channel/channel id across multiple workspaces)",
     )
-    .option("--thread-ts <ts>", "Thread root ts to post into (optional)")
+    .option(
+      "--thread-ts <ts>",
+      "Thread root ts for channel targets; URL targets derive their thread context",
+    )
     .option(
       "--reply-broadcast",
-      "Also broadcast this thread reply to the parent channel (requires thread context; use --thread-ts for channel targets; cannot be combined with --attach).",
+      "Also broadcast this thread reply to the parent channel (requires thread context; use --thread-ts for channel targets; not supported for user-ID/DM targets; cannot be combined with --attach).",
+    )
+    .option(
+      "--attach <path>",
+      "Attach a local file path (repeatable); text becomes an initial comment without automatic list conversion",
+      collectOptionValue,
+      [],
     )
-    .option("--attach <path>", "Attach a local file path (repeatable)", collectOptionValue, [])
     .option(
       "--blocks <path>",
       "Path to a JSON file containing a Block Kit blocks array. Bypasses automatic markdown-to-rich-text conversion. Use '-' to read from stdin. Cannot be combined with --attach.",
     )
     .option(
       "--schedule <time>",
-      "Schedule delivery at an ISO 8601 timestamp with explicit timezone (or Unix timestamp). Cannot be combined with --attach.",
+      "Schedule delivery at an ISO 8601 timestamp with explicit timezone (or Unix timestamp), within 120 days. Cannot be combined with --attach.",
     )
     .option(
       "--schedule-in <duration>",
-      "Schedule delivery after a duration or future phrase, e.g. 3h, tomorrow 9am, monday 9am. Cannot be combined with --attach.",
+      "Schedule delivery within 120 days after a duration or future phrase, e.g. 3h or monday 9am. Named phrases use this process's local timezone. Cannot be combined with --attach.",
     )
     .action(async (...args) => {
       const [targetInput, text, options] = args as [
@@ -248,14 +256,19 @@ export function registerMessageCommand(input: { program: Command; ctx: CliContex
 
   messageCmd
     .command("draft")
-    .description("Open a rich Slack-like editor to compose and send a message")
+    .description(
+      "Open a send-capable rich editor; CI skips the editor and immediately sends supplied text",
+    )
     .argument("<target>", "Slack message URL, #name/name, or channel id")
-    .argument("[text]", "Initial draft text (mrkdwn format)")
+    .argument("[text]", "Initial draft text (sent immediately when CI skips the editor)")
     .option(
       "--workspace <url>",
       "Workspace selector (full URL or unique substring; needed when using #channel/channel id across multiple workspaces)",
     )
-    .option("--thread-ts <ts>", "Thread root ts to post into (optional)")
+    .option(
+      "--thread-ts <ts>",
+      "Thread root ts to post into; overrides the URL-derived thread when supplied",
+    )
     .action(async (...args) => {
       const [targetInput, text, options] = args as [
         string,
diff --git a/src/cli/message-scheduled-command.ts b/src/cli/message-scheduled-command.ts
index e41228b..9a526bc 100644
--- a/src/cli/message-scheduled-command.ts
+++ b/src/cli/message-scheduled-command.ts
@@ -44,7 +44,7 @@ export function registerScheduledMessageCommand(input: {
     .argument("<id>", "scheduled_message_id returned by message send --schedule")
     .requiredOption(
       "--channel <channel>",
-      "Channel/DM id or channel name for the scheduled message",
+      "Required channel/DM id or channel name for the scheduled message",
     )
     .option("--workspace <url>", "Workspace selector (full URL or unique substring)")
     .action(async (...args) => {
diff --git a/src/cli/user-command.ts b/src/cli/user-command.ts
index 7909821..a47f71b 100644
--- a/src/cli/user-command.ts
+++ b/src/cli/user-command.ts
@@ -70,7 +70,7 @@ export function registerUserCommand(input: { program: Command; ctx: CliContext }
   userCmd
     .command("dm-open")
     .description("Open or get a DM / group DM channel")
-    .argument("<users...>", "One or more user IDs (U.../W...) or @handles")
+    .argument("<users...>", "One to 8 other user IDs (U.../W...) or @handles; caller is implicit")
     .option("--workspace <url>", "Workspace URL (required if you have multiple workspaces)")
     .action(async (...args) => {
       const [users, options] = args as [string[], { workspace?: string }];
diff --git a/test/help-contracts.test.ts b/test/help-contracts.test.ts
new file mode 100644
index 0000000..c5d41a7
--- /dev/null
+++ b/test/help-contracts.test.ts
@@ -0,0 +1,95 @@
+import { describe, expect, test } from "bun:test";
+import { Command } from "commander";
+import { registerCanvasCommand } from "../src/cli/canvas-command.ts";
+import { registerChannelCommand } from "../src/cli/channel-command.ts";
+import type { CliContext } from "../src/cli/context.ts";
+import { registerLaterCommand } from "../src/cli/later-command.ts";
+import { registerMessageCommand } from "../src/cli/message-command.ts";
+import { registerUserCommand } from "../src/cli/user-command.ts";
+
+function findCommand(root: Command, ...path: string[]): Command {
+  let current = root;
+  for (const name of path) {
+    const next = current.commands.find((command) => command.name() === name);
+    if (!next) {
+      throw new Error(`Missing command: ${path.join(" ")}`);
+    }
+    current = next;
+  }
+  return current;
+}
+
+function optionDescription(command: Command, long: string): string {
+  const option = command.options.find((candidate) => candidate.long === long);
+  if (!option) {
+    throw new Error(`Missing option ${long} on ${command.name()}`);
+  }
+  return option.description;
+}
+
+function buildProgram(): Command {
+  const program = new Command();
+  const ctx = {} as CliContext;
+  registerMessageCommand({ program, ctx });
+  registerCanvasCommand({ program, ctx });
+  registerChannelCommand({ program, ctx });
+  registerLaterCommand({ program, ctx });
+  registerUserCommand({ program, ctx });
+  return program;
+}
+
+describe("agent-facing help contracts", () => {
+  test("message send documents non-obvious formatting and scheduling behavior", () => {
+    const send = findCommand(buildProgram(), "message", "send");
+
+    expect(optionDescription(send, "--attach")).toContain("without automatic list conversion");
+    expect(optionDescription(send, "--schedule")).toContain("within 120 days");
+    expect(optionDescription(send, "--schedule-in")).toContain("local timezone");
+    expect(optionDescription(send, "--thread-ts")).toContain("channel targets");
+    expect(optionDescription(send, "--reply-broadcast")).toContain("DM targets");
+  });
+
+  test("message draft identifies its CI send behavior", () => {
+    const draft = findCommand(buildProgram(), "message", "draft");
+
+    expect(draft.description()).toContain("CI skips the editor");
+    expect(draft.registeredArguments[1]?.description).toContain("sent immediately");
+    expect(optionDescription(draft, "--thread-ts")).toContain("overrides the URL-derived thread");
+  });
+
+  test("scheduled cancellation identifies its required channel", () => {
+    const cancel = findCommand(buildProgram(), "message", "scheduled", "cancel");
+
+    expect(optionDescription(cancel, "--channel")).toContain("Required");
+  });
+
+  test("Later reminders identify named-day timezone behavior", () => {
+    const remind = findCommand(buildProgram(), "later", "remind");
+
+    expect(optionDescription(remind, "--in")).toContain("local timezone at 9:00");
+    expect(optionDescription(remind, "--in")).toContain("Unix timestamp");
+  });
+
+  test("canvas creation identifies source and credential constraints", () => {
+    const create = findCommand(buildProgram(), "canvas", "create");
+
+    expect(create.description()).toContain("exactly one Markdown source");
+    expect(optionDescription(create, "--file")).toContain("mutually exclusive");
+    expect(optionDescription(create, "--channel")).toContain("canvases:write");
+    expect(optionDescription(create, "--channel")).toContain("browser auth");
+  });
+
+  test("channel mark distinguishes URL and non-URL workspace handling", () => {
+    const mark = findCommand(buildProgram(), "channel", "mark");
+
+    expect(optionDescription(mark, "--workspace")).toContain("cannot be used with URL targets");
+    expect(optionDescription(mark, "--ts")).toContain("overrides a URL timestamp");
+  });
+
+  test("DM help states Slack's group size limit", () => {
+    const dmOpen = findCommand(buildProgram(), "user", "dm-open");
+
+    expect(dmOpen.registeredArguments[0]?.description).toContain("One to 8 other user");
+    expect(dmOpen.registeredArguments[0]?.description).toContain("caller is implicit");
+  });
+});