feat: add agent avatar download to Slack setup and settings (#13740)

## Thinking Path

> - Paperclip helps people manage AI agents for work.
> - Slack connections let a team talk to those agents in Slack.
> - Agents now have a saved avatar, but Slack setup did not offer that
image.
> - A matching avatar helps a team recognize its agent.
> - This pull request adds an optional avatar step and a download in
connector Settings.
> - Users download a PNG and upload it directly in Slack with clear
instructions.

## Linked Issues or Issue Description

**What existing behavior does this improve?**
Slack connector onboarding and its Settings page.

**Current behavior**
Setup does not offer the assigned agent's avatar or explain how to
upload it in Slack.

**Proposed behavior**
After Slack connection verification, users can download a 512 × 512 PNG
of their agent's saved avatar. They can upload it in Slack, confirm, or
skip. Settings keeps the download and upload instructions available
after onboarding.

**Reason and benefit**
The same avatar helps people recognize the agent across Paperclip and
Slack. Users who skip the optional step can return to it in Settings.

**Breaking changes**
None. No schema, authentication, Slack scope, or provider API change.
Completed connections keep their existing completion state. Searched
existing Slack avatar and Cliptoon PRs; no matching implementation was
found.

## What Changed

- Add an optional avatar step before personal Slack account linking.
Keep the numbered sidebar and shared footer.
- Resolve the selected agent's saved appearance for the preview and PNG
download.
- Add the same download and expandable upload instructions to connector
Settings.
- Remember uploaded or skipped per company and endpoint in browser
storage. Treat uploaded as user confirmation, not provider verification.
- Reject failed or non-PNG download responses and allow retry.
- Reuse the production avatar components in onboarding and Settings
stories.
- Test wizard progression, resume, Settings, download recovery, storage
isolation, and terminated assigned agents.
- Exercise real PNG downloads in the Slack browser flow and keep default
app names consistent with app creation.
- Fetch the assigned agent directly so its saved avatar remains
available after termination.

## Verification

- Focused chat suites: 48 passed; the two affected suites passed again
after the final naming fix (32 tests).
- Slack browser E2E passed through setup, avatar download, account
linking, and Settings download. PNG signature and 512 × 512 dimensions
verified.
- UI token gates passed.
- Browser: downloaded the real 512 × 512 PNG; checked confirmation,
return, mobile layout, and Settings instructions.
- Full workspace typecheck, application build, and production Storybook
build passed.
- All latest-head CI checks passed (54 passed, 2 skipped), including all
browser, chat, general, and serialized test groups. The unrelated Sentry
test failed once and passed on the single CI rerun; its suite also
passed locally.
- Local full-suite attempt encountered a rapid Slack callback ordering
failure under concurrent build load; that test passed in isolation, and
all three chat shards passed in CI. The remaining local run was not used
as the merge gate.
- Review the Connections / Slack / Add avatar and Avatar in Settings
stories.

## Risks

- Slack upload is manual. Confirmation does not claim to verify the
Slack icon.
- Optional step progress is browser-local. Clearing storage or changing
browsers can show it again. Setup still works when storage is
unavailable.
- The existing avatar API remains the image source. Download failures
show a retry message.

## Model Used

OpenAI GPT-6 through Codex, with reasoning, repository tools, code
execution, and browser testing. The exact deployment model ID and
context window are not exposed in this session.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

Author: cryppadotta

doc/connections/CHAT-CONNECTOR-UX.md

@@ -300,3 +300,18 @@ email integration's actual mechanisms.
 
 The intended result is consistent interaction and permission semantics across
 providers, with instructions and step count tailored to each real workflow.
+
+## Agent avatars in provider setup
+
+Offer the selected agent's existing avatar as a downloadable image when the
+provider supports a custom bot image. Keep manual upload instructions next to
+the download, use the saved provider app name, and distinguish user confirmation
+from provider verification. Keep a download in connector Settings so skipping
+the optional setup step does not hide it permanently.
+
+Slack uses a 512 × 512 PNG from the existing avatar renderer. Its optional step
+comes after connection verification and before personal account linking. Upload
+the file through Basic Information → Display Information → App icon & Preview,
+confirm the crop, then save in Slack. Confirmation/skipping is browser-local,
+scoped to the company and endpoint; it is not proof of a Slack configuration
+change. No new Slack scope or API mutation is needed.

tests/e2e/chat-adapters-ui-providers.spec.ts

@@ -1,3 +1,4 @@
+import { readFile } from "node:fs/promises";
 import { expect, test, type Page } from "@playwright/test";
 
 import {
@@ -237,6 +238,16 @@ test.describe.serial("native chat adapter UI", () => {
         await expect(page.getByRole("heading", { name: "Verify Slack connection" })).toBeVisible();
         await expect(page.getByText("Slack needs to confirm that it can reach your Paperclip instance.")).toBeVisible();
         mock.setWebhookVerified();
+        await expect(page.getByRole("heading", { name: "Give Maya a face in Slack" })).toBeVisible();
+        const downloadEvent = page.waitForEvent("download");
+        await page.getByRole("link", { name: "Download avatar" }).click();
+        const download = await downloadEvent;
+        expect(download.suggestedFilename()).toBe("maya-paperclip-avatar.png");
+        const png = await readFile((await download.path())!);
+        expect(png.subarray(1, 4).toString()).toBe("PNG");
+        expect(png.readUInt32BE(16)).toBe(512);
+        expect(png.readUInt32BE(20)).toBe(512);
+        await page.getByRole("button", { name: "I’ve uploaded the avatar" }).click();
         await expect(page.getByRole("heading", { name: "Connect your Slack account" })).toBeVisible();
         await expect(page.getByText("/maya-public connect", { exact: true })).toBeVisible();
         await page.getByRole("button", { name: "Link Test operator to my Paperclip account" }).click();
@@ -318,6 +329,13 @@ test.describe.serial("native chat adapter UI", () => {
         await expect(page.getByText("@maya-paperclip you there?", { exact: true })).toBeVisible();
         await expect(page.getByRole("button", { name: "Copy message" })).toBeVisible();
         await expect(page.getByRole("heading", { name: "Allowed Channels" })).toBeVisible();
+        const avatarSection = page.getByRole("region", { name: "Slack avatar" });
+        await expect(avatarSection.getByRole("link", { name: "Download avatar" })).toBeVisible();
+        await avatarSection.getByText("How to upload in Slack", { exact: true }).click();
+        await expect(avatarSection.getByRole("link", { name: "Open Slack app Settings" })).toBeVisible();
+        const settingsDownloadEvent = page.waitForEvent("download");
+        await avatarSection.getByRole("link", { name: "Download avatar" }).click();
+        expect((await settingsDownloadEvent).suggestedFilename()).toBe("maya-paperclip-avatar.png");
       }
 
       await expect(

tests/e2e/chat-adapters-ui.shared.ts

@@ -911,7 +911,7 @@ export async function expectSetupRail(page: Page) {
   const rail = page.getByRole("navigation", { name: "Connection setup progress" });
   await expect(rail).toBeVisible();
   const labels = new URL(page.url()).searchParams.get("provider") === "slack"
-    ? ["Choose agent", "Create Slack app", "Add credentials", "Verify Slack connection", "Connect your Slack account", "Try it"]
+    ? ["Choose agent", "Create Slack app", "Add credentials", "Verify Slack connection", "Add avatar", "Connect your Slack account", "Try it"]
     : ["Choose agent", "Connect provider", "Try it"];
   await expect(rail.getByRole("listitem")).toHaveCount(labels.length);
   for (const label of labels) {

ui/src/pages/apps/chat/ChatEndpoint.clipboard.test.tsx

@@ -14,6 +14,9 @@ import { ChatEndpointDetail } from "./ChatEndpointDetail";
 
 const mocks = vi.hoisted(() => ({
   get: vi.fn(),
+  getAgent: vi.fn(),
+  listAgents: vi.fn(),
+  listResources: vi.fn(),
   tab: "access",
   listActivityPage: vi.fn(),
   create: vi.fn(),
@@ -33,7 +36,7 @@ const mocks = vi.hoisted(() => ({
 vi.mock("@/api/chatEndpoints", () => ({ chatEndpointsApi: mocks }));
 vi.mock("@/api/auth", () => ({ authApi: { getSession: async () => ({ user: { id: "owner-user", name: "Owner" } }) } }));
 vi.mock("@/api/health", () => ({ healthApi: { get: async () => ({ deploymentMode: "authenticated" }) } }));
-vi.mock("@/api/agents", () => ({ agentsApi: { list: async () => [] } }));
+vi.mock("@/api/agents", () => ({ agentsApi: { list: mocks.listAgents, get: mocks.getAgent } }));
 vi.mock("@/api/instanceSettings", () => ({ instanceSettingsApi: { getExperimental: async () => ({ enableIsolatedWorkspaces: true }) } }));
 vi.mock("@/context/CompanyContext", () => ({
   useCompany: () => ({ selectedCompanyId: "company-a" }),
@@ -67,6 +70,10 @@ describe("chat setup and identity-link clipboard actions", () => {
   const secret = "synthetic-one-time-webhook-secret";
 
   beforeEach(() => {
+    localStorage.clear();
+    mocks.listAgents.mockResolvedValue([{ id: "agent-a", name: "Maya", status: "idle" }]);
+    mocks.getAgent.mockResolvedValue({ id: "agent-a", name: "Maya", appearance: { schemaVersion: 1, characterVersion: "cap-v1", paletteId: "cherry-pop" } });
+    mocks.listResources.mockResolvedValue([]);
     mocks.tab = "access";
     mocks.listActivityPage.mockReset();
     container = document.createElement("div");
@@ -363,13 +370,13 @@ describe("chat setup and identity-link clipboard actions", () => {
     await client.invalidateQueries({ queryKey: ["chat-endpoint-slack-webhook-verification", endpoint.id] });
     await settle();
     expect(mocks.setup).toHaveBeenLastCalledWith(endpoint.id, { action: "verify", credentials: undefined });
-    expect(container.querySelector('aside button[aria-current="step"]')?.textContent).toBe("5Connect your Slack account");
-    expect(container.textContent).toContain("/maya-test connect");
+    expect(container.querySelector('aside button[aria-current="step"]')?.textContent).toBe("5Add avatar");
+    expect(container.textContent).toContain("Give Maya a face in Slack");
     await click("4Verify Slack connection");
     expect(container.querySelector("h1")?.textContent).toBe("Verify Slack connection");
     expect(container.textContent).toContain("Slack verified your connection.");
     await click("Continue");
-    expect(container.querySelector('aside button[aria-current="step"]')?.textContent).toBe("5Connect your Slack account");
+    expect(container.querySelector('aside button[aria-current="step"]')?.textContent).toBe("5Add avatar");
     expect(mocks.setup).toHaveBeenCalledTimes(2);
     await click("3Add credentials");
     expect(container.querySelector("h1")?.textContent).toBe("Add Slack credentials");
@@ -386,7 +393,7 @@ describe("chat setup and identity-link clipboard actions", () => {
     await settle();
     expect(mocks.setup).toHaveBeenCalledTimes(1);
     expect(mocks.setup).toHaveBeenCalledWith(endpoint.id, { action: "verify", credentials: undefined });
-    expect(container.querySelector('aside button[aria-current="step"]')?.textContent).toBe("5Connect your Slack account");
+    expect(container.querySelector('aside button[aria-current="step"]')?.textContent).toBe("5Add avatar");
   });
 
   it("picks up verification completed in another tab", async () => {
@@ -400,7 +407,7 @@ describe("chat setup and identity-link clipboard actions", () => {
     flushSync(() => client.setQueryData(["chat-endpoint-setup-resume", endpoint.id], verified));
     await settle();
     expect(mocks.setup).toHaveBeenCalledTimes(1);
-    expect(container.querySelector('aside button[aria-current="step"]')?.textContent).toBe("5Connect your Slack account");
+    expect(container.querySelector('aside button[aria-current="step"]')?.textContent).toBe("5Add avatar");
     expect(container.textContent).not.toContain("Connection failed");
   });
 
@@ -418,7 +425,7 @@ describe("chat setup and identity-link clipboard actions", () => {
     mocks.setup.mockResolvedValueOnce({ ...verified, setup: { ...verified.setup, step: "test" } });
     await click("Continue");
     expect(mocks.setup).toHaveBeenCalledTimes(2);
-    expect(container.querySelector('aside button[aria-current="step"]')?.textContent).toBe("5Connect your Slack account");
+    expect(container.querySelector('aside button[aria-current="step"]')?.textContent).toBe("5Add avatar");
   });
 
   async function renderSlackIdentityStep() {
@@ -428,9 +435,56 @@ describe("chat setup and identity-link clipboard actions", () => {
       setup: { ...endpoint.setup, step: "test", command: "/maya-test", testStartedAt: "2026-09-18T20:00:00Z" },
     }));
     await settle();
+    await click("Skip for now");
     return endpoint;
   }
 
+  it("uses the persisted agent appearance and remembers avatar confirmation on resume", async () => {
+    await renderSlackIdentityStep();
+    await click("5Add avatar");
+    const download = container.querySelector<HTMLAnchorElement>('a[download]')!;
+    expect(download.getAttribute("href")).toBe("/api/agent-avatars/cap-v1/cherry-pop/rest.png?size=512&scale=1");
+    expect(download.download).toBe("maya-paperclip-avatar.png");
+    const endpoint = client.getQueryData<ChatEndpoint>(["chat-endpoint-setup-resume", "endpoint-a"])!;
+    flushSync(() => client.setQueryData(["chat-endpoint-setup-resume", "endpoint-a"], {
+      ...endpoint, setup: { ...endpoint.setup, slackApp: { appName: "Custom Slack App", botName: "custom", command: "/custom" } },
+    }));
+    await settle();
+    expect(container.querySelector<HTMLAnchorElement>('a[download]')!.download).toBe("Custom-Slack-App-avatar.png");
+    expect(container.textContent).toContain("Custom Slack App");
+    await click("I’ve uploaded the avatar");
+    expect(container.querySelector('aside button[aria-current="step"]')?.textContent).toBe("6Connect your Slack account");
+    await click("5Add avatar");
+    expect(container.textContent).toContain("You marked the avatar as uploaded in Slack.");
+    expect(localStorage.getItem("paperclip:slack-avatar:v1:company-a:endpoint-a")).toBe("uploaded");
+    flushSync(() => root.unmount());
+    root = createRoot(container);
+    const saved = client.getQueryData<ChatEndpoint>(["chat-endpoint-setup-resume", "endpoint-a"])!;
+    mocks.get.mockResolvedValue(saved);
+    flushSync(() => root.render(<QueryClientProvider client={client}><TooltipProvider><ChatSetupSidebarProvider><ChatSetupSidebar /><ChatEndpointSetup /></ChatSetupSidebarProvider></TooltipProvider></QueryClientProvider>));
+    await settle();
+    expect(container.querySelector('aside button[aria-current="step"]')?.textContent).toBe("6Connect your Slack account");
+  });
+
+  it("keeps a terminated agent’s saved avatar when the company list omits it", async () => {
+    mocks.listAgents.mockResolvedValue([]);
+    mocks.getAgent.mockResolvedValue({ id: "agent-a", name: "Maya", status: "terminated", appearance: { schemaVersion: 1, characterVersion: "cap-v1", paletteId: "orchid-peach" } });
+    await renderSlackIdentityStep();
+    await click("5Add avatar");
+    expect(container.querySelector('a[download]')?.getAttribute("href")).toBe("/api/agent-avatars/cap-v1/orchid-peach/rest.png?size=512&scale=1");
+    expect(mocks.getAgent).toHaveBeenCalledWith("agent-a", "company-a");
+  });
+
+  it("keeps avatar download available in connector settings", async () => {
+    mocks.tab = "settings";
+    await render("slack", true);
+    const section = container.querySelector('section[aria-label="Slack avatar"]')!;
+    expect(section.textContent).toContain("Download avatar");
+    expect(section.querySelector('a[download]')?.getAttribute("href")).toContain("/cherry-pop/rest.png?size=512&scale=1");
+    expect(section.querySelector("details")?.open).toBe(false);
+    expect(mocks.getAgent).toHaveBeenCalledWith("agent-a", "company-a");
+  });
+
   it("waits for a fresh connect command and links the selected identity inside the wizard", async () => {
     mocks.listPrincipals.mockResolvedValue([
       { id: "old", principalId: "old", externalLabel: "Old workspace member", status: "pending", lastConnectAt: "2026-09-17T20:00:00Z" },
@@ -459,9 +513,9 @@ describe("chat setup and identity-link clipboard actions", () => {
     expect(mocks.createLinkIntent).toHaveBeenCalledWith("endpoint-a", "principal-a");
     expect(mocks.confirmIdentityLink).toHaveBeenCalledWith("synthetic-private-confirmation-token");
     expect(container.textContent).toContain("Linked to you");
-    expect(container.querySelector('aside button[aria-current="step"]')?.textContent).toBe("5Connect your Slack account");
+    expect(container.querySelector('aside button[aria-current="step"]')?.textContent).toBe("6Connect your Slack account");
     await click("Continue to message test");
-    expect(container.querySelector('aside button[aria-current="step"]')?.textContent).toBe("6Try it");
+    expect(container.querySelector('aside button[aria-current="step"]')?.textContent).toBe("7Try it");
     expect(container.textContent).toContain("@Maya you there?");
     await click("Copy message");
     expect(copied).toContain("@Maya you there?");
@@ -478,10 +532,10 @@ describe("chat setup and identity-link clipboard actions", () => {
     client.setQueryData(["chat-endpoint-setup-test-status", "endpoint-a"], { messageReceivedAt: "2026-09-18T20:02:00Z" });
     await settle();
     expect(container.textContent).toContain("Received your Slack message.");
-    await click("5Connect your Slack account");
+    await click("6Connect your Slack account");
     expect([...container.querySelectorAll("h1")].find((heading) => !heading.closest("[hidden]"))?.textContent).toBe("Connect your Slack account");
     expect(container.textContent).toContain("Linked to you");
-    await click("6Try it");
+    await click("7Try it");
     expect([...container.querySelectorAll("h1")].find((heading) => !heading.closest("[hidden]"))?.textContent).toBe("Try Maya in Slack");
   });
 

ui/src/pages/apps/chat/ChatEndpointDetail.tsx

@@ -1,3 +1,8 @@
+import { defaultSlackAppName } from "./slack-app-name";
+import { SlackAvatarSettings } from "./SlackAvatarStep";
+import { agentsApi } from "@/api/agents";
+import { agentAvatarUrl } from "@/lib/agent-avatar-url";
+import { resolveAgentAppearance } from "@paperclipai/shared";
 import { EmailEndpointSettings } from "./EmailEndpointSetup";
 import { useEffect, useMemo, useState } from "react";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
@@ -343,6 +348,11 @@ function Settings({
   const queryClient = useQueryClient();
   const { pushToast } = useToast();
   const [messageCopied, setMessageCopied] = useState(false);
+  const avatarAgent = useQuery({
+    queryKey: queryKeys.agents.detail(endpoint.assignedAgentId),
+    queryFn: () => agentsApi.get(endpoint.assignedAgentId, endpoint.companyId),
+    enabled: endpoint.provider === "slack",
+  });
   const mentionMessage = `@${(endpoint.botUsername ?? endpoint.botLabel ?? endpoint.assignedAgentName).replace(/^@/, "")} you there?`;
   const resourcesQuery = useQuery({
     queryKey: queryKeys.chatEndpoints.resources(endpointId),
@@ -399,6 +409,15 @@ function Settings({
           </div>
         </div>
       )}
+      {endpoint.provider === "slack" && (
+        avatarAgent.isPending ? <p role="status" className="text-sm text-muted-foreground">Loading agent avatar…</p>
+          : avatarAgent.isError ? <p role="alert" className="text-sm text-destructive">Couldn’t load the agent’s avatar. <button className="underline" onClick={() => void avatarAgent.refetch()}>Try again</button></p>
+          : <SlackAvatarSettings
+              agentName={avatarAgent.data?.name ?? endpoint.assignedAgentName}
+              appName={endpoint.setup?.slackApp?.appName ?? defaultSlackAppName(avatarAgent.data?.name ?? endpoint.assignedAgentName)}
+              avatarUrl={agentAvatarUrl(resolveAgentAppearance(avatarAgent.data?.appearance, endpoint.assignedAgentId), 512, 1, "rest")}
+            />
+      )}
       {endpoint.provider === "telegram" && (
         <div className="space-y-2">
           <h2 className="text-lg font-semibold">Telegram group command</h2>