PAP-10440: group artifacts by task stacks (#7654)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - The artifacts surface is where board users inspect files, media, and
documents produced by agents.
> - Grouped artifact stacks make that surface easier to scan by task,
but the first pass still made grouping feel secondary to media filters.
> - The follow-up request was to make grouping the default and give the
grouping control the same icon-only outline treatment used on the issues
page.
> - This pull request keeps the existing artifact grouping API/UI, then
polishes the artifacts toolbar state and Storybook review coverage.
> - The benefit is that `/artifacts` now opens in the task-stack view by
default while preserving explicit flat-mode filtering via
`groupBy=none`.

## Linked Issues or Issue Description

No public GitHub issue exists for this internal Paperclip task.

### Subsystem affected

ui/ — React + Vite board UI.

### Problem or motivation

The `/artifacts` grouping affordance was visually placed after the media
filters, rendered as a text button, and defaulted to a flat artifact
list. Internal follow-up `PAP-10465` requested the grouping icon move
left of the filters, become an icon-only outlined button like `/issues`,
and make Task grouping the default.

### Proposed solution

Default `/artifacts` to grouped Task stacks, keep explicit flat mode
available as `groupBy=none`, move the grouping control before the media
chips, and restyle it as the shared icon-only outline button pattern.

### Alternatives considered

Leaving flat mode as the implicit default was rejected because it does
not satisfy the follow-up. Keeping a text label on the grouping trigger
was rejected because `/issues` already established the icon-only outline
pattern for this class of toolbar control.

### Roadmap alignment

This aligns with the `Artifacts & Work Products` roadmap item by making
generated outputs easier to inspect and operate from the board UI.

## What Changed

- Defaulted the `/artifacts` page to `groupBy=task` when no grouping URL
param is present, while keeping explicit flat mode available with
`groupBy=none`.
- Moved the group control before the media filter chips and changed it
to an icon-only outlined button using the shared `Button` pattern.
- Updated artifact page tests to cover default Task grouping, explicit
flat mode, trigger ordering, and icon-only outline metadata.
- Updated the artifact Storybook story so its toolbar mock matches the
production ordering and grouped Task is documented as the default mode.

## Verification

- `pnpm exec vitest run ui/src/pages/Artifacts.test.tsx
ui/src/components/artifacts/ArtifactGroupCard.test.tsx` — passed.
- `pnpm --filter @paperclipai/ui typecheck` — passed.
- `pnpm --filter @paperclipai/server typecheck` — passed.
- `git diff --check` — passed.
- QA visual validation from internal follow-up PAP-10466 passed
desktop/mobile scenarios. Screenshot evidence attached there:
- Desktop default:
http://paperclip-dev:3100/api/attachments/bc81305d-f5de-485c-abeb-9e7c3d9d8539/content
- Desktop toolbar close-up:
http://paperclip-dev:3100/api/attachments/3375a62b-2110-48f3-bafa-ea98c00f99f7/content
- Mobile default:
http://paperclip-dev:3100/api/attachments/bfc5642e-9248-431e-9bac-36284dec1c89/content
- Mobile toolbar close-up:
http://paperclip-dev:3100/api/attachments/ca79401a-5ba8-464d-bc6e-aeffd47fe695/content
- GitHub PR checks on head `431964c8b` — passed, including Greptile 5/5.

## Risks

Low to medium risk. The main behavior shift is intentional: `/artifacts`
now queries grouped Task stacks by default. Existing flat mode remains
available through the grouping menu and explicit `groupBy=none` URLs.

## Model Used

OpenAI Codex, GPT-5.4 class coding model in this Paperclip heartbeat
environment, with shell, git, test, and GitHub CLI tool use. Context
window managed by the Codex runtime.

## 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 run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, I have included before/after
screenshots
- [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>

ui/src/api/artifacts.test.ts

@@ -59,6 +59,41 @@ describe("artifactsApi.list", () => {
     );
   });
 
+  it("omits groupBy when grouping is none", async () => {
+    await artifactsApi.list("company-1", { groupBy: "none" });
+    expect(mockApi.get).toHaveBeenCalledWith("/companies/company-1/artifacts");
+  });
+
+  it("serializes groupBy and the selected stack issue", async () => {
+    await artifactsApi.list("company-1", {
+      groupBy: "parent_task",
+      groupIssueId: "issue-9",
+      kind: "image",
+    });
+    expect(mockApi.get).toHaveBeenCalledWith(
+      "/companies/company-1/artifacts?kind=image&groupBy=parent_task&groupIssueId=issue-9",
+    );
+  });
+
+  it("preserves groups and selectedGroup from the envelope", async () => {
+    const artifact = sampleArtifact();
+    const group = {
+      id: "task:issue-1",
+      groupBy: "task" as const,
+      issue: artifact.issue,
+      title: "Demo reel",
+      count: 3,
+      mediaKinds: ["video" as const],
+      previewArtifacts: [artifact],
+      updatedAt: "2026-06-01T00:00:00.000Z",
+      href: "/PAP/artifacts?groupBy=task&groupIssueId=issue-1",
+    };
+    mockApi.get.mockResolvedValue({ artifacts: [], groups: [group], nextCursor: "next" });
+    const result = await artifactsApi.list("company-1", { groupBy: "task" });
+    expect(result.groups).toEqual([group]);
+    expect(result.nextCursor).toBe("next");
+  });
+
   it("returns the envelope shape from the backend", async () => {
     const artifact = sampleArtifact();
     mockApi.get.mockResolvedValue({ artifacts: [artifact], nextCursor: "next" });

ui/src/api/artifacts.ts

@@ -1,12 +1,15 @@
 import { api } from "./client";
 import type {
   CompanyArtifact,
+  CompanyArtifactGroupBy,
   CompanyArtifactMediaKind,
   CompanyArtifactsResponse,
 } from "@paperclipai/shared";
 
 export type {
   CompanyArtifact,
+  CompanyArtifactGroup,
+  CompanyArtifactGroupBy as ArtifactGroupBy,
   CompanyArtifactMediaKind as ArtifactMediaKind,
   CompanyArtifactsResponse,
   CompanyArtifactSource as ArtifactSource,
@@ -32,6 +35,10 @@ export interface ListArtifactsParams {
   kind?: ArtifactKindFilter;
   projectId?: string;
   q?: string;
+  /** Grouping mode. `none` (default) returns the flat artifact grid. */
+  groupBy?: CompanyArtifactGroupBy;
+  /** When grouping, selects a single stack to expand into its artifacts. */
+  groupIssueId?: string;
   limit?: number;
   cursor?: string;
 }
@@ -41,6 +48,8 @@ function buildArtifactsQuery(params?: ListArtifactsParams): string {
   if (params?.kind && params.kind !== "all") search.set("kind", params.kind);
   if (params?.projectId) search.set("projectId", params.projectId);
   if (params?.q) search.set("q", params.q);
+  if (params?.groupBy && params.groupBy !== "none") search.set("groupBy", params.groupBy);
+  if (params?.groupIssueId) search.set("groupIssueId", params.groupIssueId);
   if (params?.limit != null) search.set("limit", String(params.limit));
   if (params?.cursor) search.set("cursor", params.cursor);
   const qs = search.toString();
@@ -49,8 +58,8 @@ function buildArtifactsQuery(params?: ListArtifactsParams): string {
 
 /**
  * Normalize the endpoint response. The contract is an envelope
- * (`{ artifacts, nextCursor }`), but we also tolerate a bare array so the page
- * keeps working if the backend ships the simpler shape.
+ * (`{ artifacts, groups?, selectedGroup?, nextCursor }`), but we also tolerate a
+ * bare array so the page keeps working if the backend ships the simpler shape.
  */
 function normalizeArtifactsResponse(
   raw: CompanyArtifactsResponse | CompanyArtifact[],
@@ -58,7 +67,12 @@ function normalizeArtifactsResponse(
   if (Array.isArray(raw)) {
     return { artifacts: raw, nextCursor: null };
   }
-  return { artifacts: raw.artifacts ?? [], nextCursor: raw.nextCursor ?? null };
+  return {
+    artifacts: raw.artifacts ?? [],
+    groups: raw.groups,
+    selectedGroup: raw.selectedGroup,
+    nextCursor: raw.nextCursor ?? null,
+  };
 }
 
 export const artifactsApi = {