Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
chore(agents): show generated and mentioned images inline in channel messages (#7289)
Wolf Mermelstein10d7922c7bb9
diff --git a/apps/web/src/features/channel/Message/Content.tsx b/apps/web/src/features/channel/Message/Content.tsxindex b6ed834095..aae4144f3c 100644--- a/apps/web/src/features/channel/Message/Content.tsx+++ b/apps/web/src/features/channel/Message/Content.tsx@@ -7,6 +7,7 @@ import { createMemo, createSignal, Show } from 'solid-js';import { splitMessageContent } from './agent-session-link';import { useMessage, useSearchHighlightTermsLookup } from './context';import { createSearchHighlightOverlay } from './highlightOverlay';+import { MentionedImages } from './MentionedImages';type ContentProps = {class?: string;@@ -42,6 +43,7 @@ export function Content(props: ContentProps) {target="internal"rootRef={setMarkdownRoot}/>+ <MentionedImages content={content()} /></div></Show>);diff --git a/apps/web/src/features/channel/Message/MentionedImages.test.tsx b/apps/web/src/features/channel/Message/MentionedImages.test.tsxnew file mode 100644index 0000000000..9c2a557167--- /dev/null+++ b/apps/web/src/features/channel/Message/MentionedImages.test.tsx@@ -0,0 +1,163 @@+import { cleanup, render } from '@solidjs/testing-library';+import { createSignal } from 'solid-js';+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';++type Preview =+ | { loading: true; id: string; type: 'document' }+ | {+ loading: false;+ access: 'access';+ id: string;+ type: 'document' | 'channel';+ name: string;+ fileType?: string;+ }+ | { loading: false; access: 'no_access'; id: string; type: 'document' };++const fixture = vi.hoisted(() => ({+ previews: new Map<string, () => Preview>(),+ requested: [] as { id: string; type?: string }[],+}));++vi.mock('@queries/preview', () => ({+ useItemPreview: (entity: () => { id: string; type?: string }) => {+ fixture.requested.push(entity());+ return [+ () =>+ fixture.previews.get(entity().id)?.() ?? {+ loading: true,+ id: entity().id,+ type: 'document',+ },+ ];+ },+ isAccessiblePreviewItem: (item: { loading: boolean; access?: string }) =>+ !item.loading && item.access === 'access',+}));++vi.mock('@core/constant/allBlocks', () => ({+ verifyBlockName: (name?: string) => name ?? 'unknown',+ fileTypeToResolvedBlockName: (fileType?: string) =>+ fileType === 'png' || fileType === 'jpg' ? 'image' : 'unknown',+}));++vi.mock('@service-storage/itemType', () => ({+ blockNameToItemType: (blockName: string) =>+ blockName === 'channel' || blockName === 'chat' ? blockName : 'document',+}));++vi.mock('@core/component/ImageDocumentCard', () => ({+ ImageDocumentCard: (props: { documentId: string; fileName: string }) => (+ <figure data-document-id={props.documentId}>{props.fileName}</figure>+ ),+}));++import { MentionedImages } from './MentionedImages';++const mention = (documentId: string, blockName = 'md') =>+ `<m-document-mention>${JSON.stringify({+ documentId,+ documentName: '',+ blockName,+ blockParams: {},+ })}</m-document-mention>`;++function accessible(+ id: string,+ name: string,+ fileType?: string,+ type: 'document' | 'channel' = 'document'+): Preview {+ return { loading: false, access: 'access', id, type, name, fileType };+}++afterEach(cleanup);+beforeEach(() => {+ fixture.previews.clear();+ fixture.requested = [];+});++describe('MentionedImages', () => {+ it('shows an image card for each mentioned image document', () => {+ fixture.previews.set('frog', () => accessible('frog', 'frog.png', 'png'));+ fixture.previews.set('notes', () => accessible('notes', 'Notes', 'md'));+ const view = render(() => (+ <MentionedImages+ content={`here ${mention('frog', 'md')} and ${mention('notes')}`}+ />+ ));+ const cards = view.getAllByRole('figure');+ expect(cards.map((card) => card.getAttribute('data-document-id'))).toEqual([+ 'frog',+ ]);+ expect(cards[0].textContent).toBe('frog.png');+ });++ it('relies on the resolved file type, not the block name the author wrote', () => {+ fixture.previews.set('frog', () => accessible('frog', 'frog.jpg', 'jpg'));+ const view = render(() => (+ <MentionedImages content={mention('frog', 'image')} />+ ));+ expect(view.getByRole('figure').textContent).toBe('frog.jpg');+ });++ it('never looks up channels or chats as documents', () => {+ fixture.previews.set('general', () =>+ accessible('general', 'general', undefined, 'channel')+ );+ const view = render(() => (+ <MentionedImages+ content={`${mention('general', 'channel')} ${mention('c1', 'chat')}`}+ />+ ));+ expect(view.queryByRole('figure')).toBeNull();+ expect(fixture.requested).toEqual([]);+ expect(+ view.container.querySelector('[data-message-mentioned-images]')+ ).toBeNull();+ });++ it('renders nothing for inaccessible or pending documents', () => {+ fixture.previews.set('secret', () => ({+ loading: false,+ access: 'no_access',+ id: 'secret',+ type: 'document',+ }));+ const view = render(() => (+ <MentionedImages+ content={`${mention('secret', 'image')} ${mention('pending', 'image')}`}+ />+ ));+ expect(view.queryByRole('figure')).toBeNull();+ expect(fixture.requested.map((entity) => entity.type)).toEqual([+ 'document',+ 'document',+ ]);+ });++ it('shows one card when the same image is mentioned twice', () => {+ fixture.previews.set('frog', () => accessible('frog', 'frog.png', 'png'));+ const view = render(() => (+ <MentionedImages+ content={`${mention('frog', 'md')} again ${mention('frog', 'image')}`}+ />+ ));+ expect(view.getAllByRole('figure')).toHaveLength(1);+ });++ it('appears once the preview resolves to an image', () => {+ const [preview, setPreview] = createSignal<Preview>({+ loading: true,+ id: 'frog',+ type: 'document',+ });+ fixture.previews.set('frog', preview);+ const view = render(() => (+ <MentionedImages content={mention('frog', 'image')} />+ ));+ expect(view.queryByRole('figure')).toBeNull();+ setPreview(accessible('frog', 'frog.png', 'png'));+ expect(view.getByRole('figure').textContent).toBe('frog.png');+ });+});diff --git a/apps/web/src/features/channel/Message/MentionedImages.tsx b/apps/web/src/features/channel/Message/MentionedImages.tsxnew file mode 100644index 0000000000..413a07eae5--- /dev/null+++ b/apps/web/src/features/channel/Message/MentionedImages.tsx@@ -0,0 +1,69 @@+import { ImageDocumentCard } from '@core/component/ImageDocumentCard';+import {+ fileTypeToResolvedBlockName,+ verifyBlockName,+} from '@core/constant/allBlocks';+import {+ type DocumentMentionRef,+ getDocumentMentions,+} from '@core/util/documentMentions';+import { isAccessiblePreviewItem, useItemPreview } from '@queries/preview';+import { blockNameToItemType } from '@service-storage/itemType';+import { createMemo, For, Show } from 'solid-js';++/** Mentions that can resolve to a stored document; channels, chats, and the like never unfurl. */+function isDocumentMention(mention: DocumentMentionRef): boolean {+ return blockNameToItemType(verifyBlockName(mention.blockName)) === 'document';+}++function MentionedImage(props: { documentId: string }) {+ // Same preview the mention chip in the text fetches, so this adds no request.+ const [item] = useItemPreview(() => ({+ id: props.documentId,+ type: 'document',+ }));+ const image = () => {+ const preview = item();+ if (!isAccessiblePreviewItem(preview) || preview.type !== 'document') {+ return;+ }+ if (fileTypeToResolvedBlockName(preview.fileType) !== 'image') return;+ return preview;+ };++ return (+ <Show when={image()}>+ {(document) => (+ <div class="mt-2 max-w-md">+ <ImageDocumentCard+ documentId={document().id}+ fileName={document().name}+ />+ </div>+ )}+ </Show>+ );+}++/**+ * Image documents mentioned in a message, shown as inline previews beneath+ * its text. The mention chip in the text stays; this is what the chip+ * points at, so a generated or shared picture is seen without opening it.+ */+export function MentionedImages(props: { content: string }) {+ const documentIds = createMemo(() =>+ getDocumentMentions(props.content)+ .filter(isDocumentMention)+ .map((mention) => mention.documentId)+ );++ return (+ <Show when={documentIds().length > 0}>+ <div class="flex flex-wrap gap-x-2" data-message-mentioned-images>+ <For each={documentIds()}>+ {(documentId) => <MentionedImage documentId={documentId} />}+ </For>+ </div>+ </Show>+ );+}diff --git a/apps/web/src/lib/core/component/AI/component/message/userMessageAttachments.ts b/apps/web/src/lib/core/component/AI/component/message/userMessageAttachments.tsindex 4679a9c77d..61566c5e20 100644--- a/apps/web/src/lib/core/component/AI/component/message/userMessageAttachments.ts+++ b/apps/web/src/lib/core/component/AI/component/message/userMessageAttachments.ts@@ -1,4 +1,5 @@import type { Attachment } from '@core/component/AI/types';+import { getMentionedItemIds } from '@core/util/documentMentions';const ITEM_ATTACHMENT_TYPES = new Set<Attachment['entity_type']>(['channel',@@ -7,31 +8,6 @@ const ITEM_ATTACHMENT_TYPES = new Set<Attachment['entity_type']>(['project',]);-const DOCUMENT_MENTION_PATTERN =- /<m-document-mention>([\s\S]*?)<\/m-document-mention>/g;--function getMentionedItemIds(content: string): Set<string> {- const ids = new Set<string>();-- for (const match of content.matchAll(DOCUMENT_MENTION_PATTERN)) {- try {- const mention = JSON.parse(match[1]);- if (- mention &&- typeof mention === 'object' &&- typeof mention.documentId === 'string' &&- 'documentName' in mention- ) {- ids.add(mention.documentId);- }- } catch {- // Malformed mention markup renders as an unknown item, not a reference.- }- }-- return ids;-}-export function getVisibleUserMessageAttachments(content: string,attachments: Attachment[]diff --git a/apps/web/src/lib/core/component/AI/component/tool/GenerateImage.tsx b/apps/web/src/lib/core/component/AI/component/tool/GenerateImage.tsxindex bff71dcd59..6419dd0911 100644--- a/apps/web/src/lib/core/component/AI/component/tool/GenerateImage.tsx+++ b/apps/web/src/lib/core/component/AI/component/tool/GenerateImage.tsx@@ -1,85 +1,11 @@-import { useSplitLayout } from '@components/app/split-layout/layout';-import { openInNewSplitForMention } from '@core/util/openInNewSplit';-import { useSplitNavigationHandler } from '@core/util/useSplitNavigationHandler';-import LoadingSpinner from '@phosphor/spinner.svg';-import Image from '@phosphor-icons/core/regular/image.svg';-import { useBinaryDocumentQuery } from '@queries/storage/binary-document';-import { createSignal, Show, Suspense } from 'solid-js';+import {+ ImageDocumentCard,+ ImageDocumentCardHeader,+ ImageDocumentPreviewStatus,+} from '@core/component/ImageDocumentCard';+import { Show } from 'solid-js';import { createToolRenderer, useToolError } from './ToolRenderer';-function ImageHeader(props: { fileName: string }) {- return (- <div class="flex w-0 min-w-full items-center gap-2 rounded-t-xl border-b border-edge-muted bg-surface px-3 py-2 text-sm text-ink">- <Image class="size-4 shrink-0 text-ink-muted" />- <span class="min-w-0 truncate" title={props.fileName}>- {props.fileName}- </span>- </div>- );-}--function PreviewStatus(props: { failed?: boolean; generating?: boolean }) {- return (- <div- class="flex h-64 items-center justify-center gap-2 bg-surface text-sm text-ink-muted"- role="status"- >- <Show when={!props.failed}>- <LoadingSpinner class="size-4 animate-spin" />- </Show>- <span>- {props.failed- ? 'Preview unavailable'- : props.generating- ? 'Generating image'- : 'Preparing preview'}- </span>- </div>- );-}--/** Storage finishes the upload asynchronously; its query waits for a readable URL. */-function GeneratedImage(props: { documentId: string; fileName: string }) {- const query = useBinaryDocumentQuery(() => props.documentId);- // A pending query must not suspend the surrounding transcript.- const url = () => (query.isSuccess ? query.data : undefined);- const [failedUrl, setFailedUrl] = createSignal<string>();- const failed = () =>- query.isError || (url() !== undefined && failedUrl() === url());- const { insertSplit, replaceOrInsertSplit } = useSplitLayout();- const open = useSplitNavigationHandler<HTMLButtonElement>((event) => {- const split = { type: 'image' as const, id: props.documentId };- const handle = openInNewSplitForMention(event.shiftKey, true)- ? insertSplit(split)- : replaceOrInsertSplit(split);- handle?.activate();- });-- return (- <button- type="button"- aria-label={`Open ${props.fileName} in a new split`}- class="block w-fit max-w-full overflow-hidden rounded-xl border border-edge-muted text-left hover:border-accent hover-transition-border focus-visible:outline-2 focus-visible:outline-accent"- {...open}- >- <ImageHeader fileName={props.fileName} />- <Suspense fallback={<PreviewStatus />}>- <Show- when={url() && !failed()}- fallback={<PreviewStatus failed={failed()} />}- >- <img- src={url()}- alt={props.fileName}- class="block h-auto max-h-96 w-auto max-w-full"- onError={() => setFailedUrl(url())}- />- </Show>- </Suspense>- </button>- );-}-export const generateImageHandler = createToolRenderer({name: 'GenerateImage',render: (ctx) => {@@ -89,7 +15,7 @@ export const generateImageHandler = createToolRenderer({when={ctx.response?.data}fallback={<div class="w-full max-w-md overflow-hidden rounded-xl border border-edge-muted">- <ImageHeader+ <ImageDocumentCardHeaderfileName={ctx.tool.data.fileName ?? 'Generated image'}/><Show@@ -100,14 +26,14 @@ export const generateImageHandler = createToolRenderer({</div>}>- <PreviewStatus generating />+ <ImageDocumentPreviewStatus label="Generating image" /></Show></div>}>{(result) => (<div class="my-2 max-w-md space-y-2">- <GeneratedImage+ <ImageDocumentCarddocumentId={result().documentId}fileName={result().fileName}/>diff --git a/apps/web/src/lib/core/component/ImageDocumentCard.tsx b/apps/web/src/lib/core/component/ImageDocumentCard.tsxnew file mode 100644index 0000000000..9b41fc583f--- /dev/null+++ b/apps/web/src/lib/core/component/ImageDocumentCard.tsx@@ -0,0 +1,91 @@+import { useSplitLayout } from '@components/app/split-layout/layout';+import { openInNewSplitForMention } from '@core/util/openInNewSplit';+import { useSplitNavigationHandler } from '@core/util/useSplitNavigationHandler';+import LoadingSpinner from '@phosphor/spinner.svg';+import Image from '@phosphor-icons/core/regular/image.svg';+import { useBinaryDocumentQuery } from '@queries/storage/binary-document';+import { createSignal, Show, Suspense } from 'solid-js';++export function ImageDocumentCardHeader(props: { fileName: string }) {+ return (+ <div class="flex w-0 min-w-full items-center gap-2 rounded-t-xl border-b border-edge-muted bg-surface px-3 py-2 text-sm text-ink">+ <Image class="size-4 shrink-0 text-ink-muted" />+ <span class="min-w-0 truncate" title={props.fileName}>+ {props.fileName}+ </span>+ </div>+ );+}++export function ImageDocumentPreviewStatus(props: {+ failed?: boolean;+ /** Replaces the default pending label. */+ label?: string;+}) {+ return (+ <div+ class="flex h-64 items-center justify-center gap-2 bg-surface text-sm text-ink-muted"+ role="status"+ >+ <Show when={!props.failed}>+ <LoadingSpinner class="size-4 animate-spin" />+ </Show>+ <span>+ {props.failed+ ? 'Preview unavailable'+ : (props.label ?? 'Preparing preview')}+ </span>+ </div>+ );+}++/**+ * A stored image document as a file card with its preview: the filename+ * header above the image, opening the image block on click.+ *+ * Storage finishes uploads asynchronously; the binary query waits for a+ * readable URL, so the card shows a pending status until then.+ */+export function ImageDocumentCard(props: {+ documentId: string;+ fileName: string;+}) {+ const query = useBinaryDocumentQuery(() => props.documentId);+ // A pending query must not suspend the surrounding transcript.+ const url = () => (query.isSuccess ? query.data : undefined);+ const [failedUrl, setFailedUrl] = createSignal<string>();+ const failed = () =>+ query.isError || (url() !== undefined && failedUrl() === url());+ const { insertSplit, replaceOrInsertSplit } = useSplitLayout();+ const open = useSplitNavigationHandler<HTMLButtonElement>((event) => {+ const split = { type: 'image' as const, id: props.documentId };+ const handle = openInNewSplitForMention(event.shiftKey, true)+ ? insertSplit(split)+ : replaceOrInsertSplit(split);+ handle?.activate();+ });++ return (+ <button+ type="button"+ aria-label={`Open ${props.fileName} in a new split`}+ class="block w-fit max-w-full overflow-hidden rounded-xl border border-edge-muted text-left hover:border-accent hover-transition-border focus-visible:outline-2 focus-visible:outline-accent"+ {...open}+ >+ <ImageDocumentCardHeader fileName={props.fileName} />+ <Suspense fallback={<ImageDocumentPreviewStatus />}>+ <Show+ when={url() && !failed()}+ fallback={<ImageDocumentPreviewStatus failed={failed()} />}+ >+ <img+ src={url()}+ alt={props.fileName}+ class="block h-auto max-h-96 w-auto max-w-full"+ onError={() => setFailedUrl(url())}+ />+ </Show>+ </Suspense>+ </button>+ );+}diff --git a/apps/web/src/lib/core/util/documentMentions.test.ts b/apps/web/src/lib/core/util/documentMentions.test.tsnew file mode 100644index 0000000000..dfbd6cecd1--- /dev/null+++ b/apps/web/src/lib/core/util/documentMentions.test.ts@@ -0,0 +1,56 @@+import { describe, expect, it } from 'vitest';+import { getDocumentMentions, getMentionedItemIds } from './documentMentions';++const mention = (documentId: string, blockName = 'md') =>+ `<m-document-mention>${JSON.stringify({+ documentId,+ documentName: '',+ blockName,+ blockParams: {},+ })}</m-document-mention>`;++describe('getDocumentMentions', () => {+ it('lists mentions in order with their block names', () => {+ const content = `see ${mention('a', 'image')} and ${mention('b', 'channel')}`;+ expect(getDocumentMentions(content)).toEqual([+ { documentId: 'a', blockName: 'image' },+ { documentId: 'b', blockName: 'channel' },+ ]);+ });++ it('keeps the first occurrence of a repeated id', () => {+ const content = `${mention('a', 'md')} twice ${mention('a', 'image')}`;+ expect(getDocumentMentions(content)).toEqual([+ { documentId: 'a', blockName: 'md' },+ ]);+ });++ it('skips malformed and non-document payloads', () => {+ const content = [+ '<m-document-mention>not json</m-document-mention>',+ '<m-document-mention>{"documentId":"x"}</m-document-mention>',+ '<m-document-mention>{"documentId":1,"documentName":""}</m-document-mention>',+ '<m-user-mention>{"userId":"u"}</m-user-mention>',+ mention('ok'),+ ].join(' ');+ expect(getDocumentMentions(content)).toEqual([+ { documentId: 'ok', blockName: 'md' },+ ]);+ });++ it('tolerates a mention without a block name', () => {+ const content =+ '<m-document-mention>{"documentId":"a","documentName":"Doc"}</m-document-mention>';+ expect(getDocumentMentions(content)).toEqual([+ { documentId: 'a', blockName: undefined },+ ]);+ });+});++describe('getMentionedItemIds', () => {+ it('collects the unique ids', () => {+ expect(+ getMentionedItemIds(`${mention('a')} ${mention('b')} ${mention('a')}`)+ ).toEqual(new Set(['a', 'b']));+ });+});diff --git a/apps/web/src/lib/core/util/documentMentions.ts b/apps/web/src/lib/core/util/documentMentions.tsnew file mode 100644index 0000000000..8177a4da56--- /dev/null+++ b/apps/web/src/lib/core/util/documentMentions.ts@@ -0,0 +1,48 @@+const DOCUMENT_MENTION_PATTERN =+ /<m-document-mention>([\s\S]*?)<\/m-document-mention>/g;++export type DocumentMentionRef = {+ documentId: string;+ blockName?: string;+};++/**+ * The items referenced by `<m-document-mention>` tags in Macro markdown, in+ * order of first appearance and without repeats. Malformed tags render as+ * unknown items rather than references, so they are skipped.+ */+export function getDocumentMentions(content: string): DocumentMentionRef[] {+ const mentions = new Map<string, DocumentMentionRef>();++ for (const match of content.matchAll(DOCUMENT_MENTION_PATTERN)) {+ try {+ const mention = JSON.parse(match[1]);+ if (+ mention &&+ typeof mention === 'object' &&+ typeof mention.documentId === 'string' &&+ 'documentName' in mention &&+ !mentions.has(mention.documentId)+ ) {+ mentions.set(mention.documentId, {+ documentId: mention.documentId,+ blockName:+ typeof mention.blockName === 'string'+ ? mention.blockName+ : undefined,+ });+ }+ } catch {+ // Malformed mention markup renders as an unknown item, not a reference.+ }+ }++ return [...mentions.values()];+}++/** IDs of the items referenced by `<m-document-mention>` tags in `content`. */+export function getMentionedItemIds(content: string): Set<string> {+ return new Set(+ getDocumentMentions(content).map((mention) => mention.documentId)+ );+}diff --git a/crates/prompt/src/mentions.rs b/crates/prompt/src/mentions.rsindex 7a46e49b60..808feae6f5 100644--- a/crates/prompt/src/mentions.rs+++ b/crates/prompt/src/mentions.rs@@ -27,6 +27,7 @@ When referencing a Macro item, person, date/time, agent session, or other mentioUse `<m-document-mention>` with the right `blockName` (and `blockParams` when needed):- Document mention: `<m-document-mention>{"documentId":"{id}","documentName":"","blockName":"md","blockParams":{}}</m-document-mention>`+- Image document mention (a generated or uploaded picture): `<m-document-mention>{"documentId":"{id}","documentName":"","blockName":"image","blockParams":{}}</m-document-mention>`- Channel mention: `<m-document-mention>{"documentId":"{id}","documentName":"","blockName":"channel","blockParams":{}}</m-document-mention>`- Channel message mention: `<m-document-mention>{"documentId":"{channel_id}","documentName":"","blockName":"channel","blockParams":{"channel_message_id":"{message_id}"}}</m-document-mention>`- Chat mention: `<m-document-mention>{"documentId":"{id}","documentName":"","blockName":"chat","blockParams":{}}</m-document-mention>`diff --git a/crates/prompt/src/tool_usage.rs b/crates/prompt/src/tool_usage.rsindex 649d6bf5d0..30a8145763 100644--- a/crates/prompt/src/tool_usage.rs+++ b/crates/prompt/src/tool_usage.rs@@ -32,7 +32,7 @@ when the user explicitely asks you to _execute_ code.(which creates a file for the code execution environment) for the `CreateDocument` tool which creates a document in theusers workspace. If the user asks you to create a document, write a code file, or create any file you should use the `CreateDocument` tool.-- To make a picture (illustration, photo-style image, logo concept, mockup, diagram concept), use `GenerateImage`. It renders the prompt with an image model and saves the result as an image document; cite the returned document with a mention tag so the user sees it inline. `CreateDocument` cannot produce image bytes.+- To make a picture (illustration, photo-style image, logo concept, mockup, diagram concept), use `GenerateImage`. It renders the prompt with an image model and saves the result as an image document; cite the returned document with a mention tag using `blockName` `image` so the picture itself shows inline in chat and channel messages. `CreateDocument` cannot produce image bytes.- `CreateDocument` content (for Markdown documents) is rendered with the same Markdown parser as your chat responses, channel messages, and email bodies, and citation syntax (`[[uuid]]`, `[[md;...]]`) works identically inside created documents. For linking to other Macro items from within that content, see the "Linking Macro items inside document content" rules. Non-Markdown documents (PDF, CSV, images, etc.) take raw content instead — no Markdown syntax or mention tags.diff --git a/docs/AGENT_GUIDE/ai-chat.md b/docs/AGENT_GUIDE/ai-chat.mdindex 5029643c77..36e751dd44 100644--- a/docs/AGENT_GUIDE/ai-chat.md+++ b/docs/AGENT_GUIDE/ai-chat.md@@ -57,6 +57,9 @@ width without side padding, preserves its aspect ratio, and truncates longfilenames in the header. The preview loads once the uploadis ready, with a placeholder while it is being prepared. Any commentary themodel added appears below the image.+In a channel thread, where the bot's reply is plain message text with a+mention chip rather than a tool card, the same image card renders beneath the+message for every image document the reply mentions (see channels.md).Refused prompts, provider failures, and hosts without a Google Generative AI keydisplay a failed tool call; the error tells the agent whether to rephrase, retry,or stop.diff --git a/docs/AGENT_GUIDE/channels.md b/docs/AGENT_GUIDE/channels.mdindex 7eb84992e6..2058c3fea0 100644--- a/docs/AGENT_GUIDE/channels.md+++ b/docs/AGENT_GUIDE/channels.md@@ -267,7 +267,16 @@ for a tool draft, `Decline · Submit · Open in session` (or `Open` for a URL) fOnly the session's owner can act; other viewers see the question read-only and the headernames who is being waited on. Once answered, the area shows the agent's passage again.Agent replies may contain mention chips (`<m-document-mention>`) that render like any-other channel mention. With GraphQL enabled, document mentions and preview cards load+other channel mention. A mention of an image document (PNG, JPG, GIF, SVG, WebP —+including a picture the bot made with `GenerateImage`) also unfurls beneath the+message text as an image card: a header with the filename above the picture,+inside the message's `[data-message-mentioned-images]` element. The chip stays;+clicking the card opens the image document in a split. The same image mentioned+twice unfurls once, mentions of other document types, channels, and chats never+unfurl, and inaccessible images show nothing. This applies to every channel+message, not only bot replies, so a person sharing an image document by `@`+mention sees the same card. The preview shows `Preparing preview` until storage+has the bytes. With GraphQL enabled, document mentions and preview cards loadin bounded batches, including task status/priority/assignees and the viewer's editpermission. Task badges can appear with the initial preview rather than waiting forseparate properties/document-metadata requests; cached titles may appear first while