Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

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.tsx
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.ts
index 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.tsx
index 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
+ <ImageDocumentCardHeader
fileName={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
+ <ImageDocumentCard
documentId={result().documentId}
fileName={result().fileName}
/>
diff --git a/apps/web/src/lib/core/component/ImageDocumentCard.tsx b/apps/web/src/lib/core/component/ImageDocumentCard.tsx
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.rs
index 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 mentio
Use `<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.rs
index 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 the
users 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.md
index 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 long
filenames in the header. The preview loads once the upload
is ready, with a placeholder while it is being prepared. Any commentary the
model 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 key
display 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.md
index 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) f
Only the session's owner can act; other viewers see the question read-only and the header
names 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 load
in bounded batches, including task status/priority/assignees and the viewer's edit
permission. Task badges can appear with the initial preview rather than waiting for
separate properties/document-metadata requests; cached titles may appear first while