@athenaintel/react 0.22.4 → 0.23.0

package/README.md

@@ -14,6 +14,58 @@ If you use the PropelAuth-specific provider from `@athenaintel/react/auth`, also
 npm install @propelauth/react
 ```
 
+## Upgrading
+
+The SDK pins its assistant-ui runtime (`@assistant-ui/tap`, `store`, `core`,
+`react`, `react-statewire`, `statewire`) at exact versions, and those packages
+carry React contexts and module singletons: an app must resolve exactly **one**
+copy of each. A fresh install does. An existing app does not necessarily — bun
+keeps a `bun.lock`'s existing resolutions on `bun add`, so after an SDK bump the
+transitive `@assistant-ui/react-statewire` / `statewire` dependencies can keep
+an older nested `@assistant-ui/tap` next to the SDK's new one. Two tap contexts
+mount and the page renders blank with:
+
+```
+Error: AssistantTapContext is not available
+```
+
+Make the app immune with a `resolve.dedupe` list in `vite.config.ts` (the Athena
+computer templates ship it; other bundlers have an equivalent single-instance
+setting):
+
+```ts
+export default defineConfig({
+  resolve: {
+    dedupe: [
+      '@assistant-ui/tap',
+      '@assistant-ui/store',
+      '@assistant-ui/core',
+      '@assistant-ui/react',
+      '@assistant-ui/react-statewire',
+      'react',
+      'react-dom',
+    ],
+  },
+});
+```
+
+Then bump to the release you want and re-resolve from scratch.
+Lockfile-preserving commands do not do it — `bun update` and
+`bun install --force` keep the nested lockfile entries, and `bun remove` +
+`bun add` (or deleting only `bun.lock`) rewrites the lockfile but bun leaves
+the nested directories in `node_modules`, which Node still resolves first:
+
+```bash
+bun add @athenaintel/react@<version>      # the release you are upgrading to
+rm -rf node_modules bun.lock && bun install
+find node_modules -path '*/@assistant-ui/tap/package.json' | wc -l   # expect 1
+```
+
+Do not add `@assistant-ui/*` packages to your own `dependencies` to pin them:
+`bun update @assistant-ui/tap` on a package that is not a direct dependency
+behaves like `bun add` at the latest version and produces more copies, not
+fewer.
+
 ## Quick Start
 
 ```tsx
@@ -146,9 +198,19 @@ What the statewire transport wires up in `AthenaChat`:
   runtime is refused with a dismissible read-only notice (start a new chat).
   Custom hosts can read all of it via `useAthenaStatewireLifecycle`.
 - **Thread list:** `enableThreadList` provides the persisted Agora session
-  list; switching threads re-attaches the statewire session to the selected
-  thread. `ThreadList`, `useAthenaThreadManager`, and `useRefreshThreadList`
-  read that state (and render nothing / return `null` without it).
+  list; switching threads (or starting a new chat) re-attaches the statewire
+  session to the selected thread while the host's own `children` stay
+  mounted — sidebars keep their scroll position and search text, custom hooks
+  keep their state, and only the per-thread pieces reset: the runtime and its
+  client, `AthenaChat`'s surface (composer draft, viewport scroll, approval
+  cards, banners), and the thread-id contexts. A host composing its own chat
+  from the statewire pieces keys any per-thread UI on
+  `useAthenaStatewireThreadId()` (the attached thread's id, defined for a
+  never-started chat too) the way `AthenaChat` does.
+  `ThreadList`, `SessionList`, `useAthenaThreadManager`,
+  `useAthenaSessionAttention`, and `useRefreshThreadList` read that state
+  (and render nothing / return `null` without it). See
+  [Session list, attention and wake markers](#session-list-attention-and-wake-markers).
 
 The `agent` prop only accepts `collab_agent:<asset_id>` refs (see below),
 because the statewire host always runs the Athena deep agent. **Any other
@@ -157,6 +219,169 @@ silently ignored selector would let a deployment answer as the wrong agent.
 `model` defaults to the deep-agent default model (`DEFAULT_STATEWIRE_MODEL`)
 unless a collab agent supplies one.
 
+## Session list, attention and wake markers
+
+A Devin-style session list on top of `enableThreadList`: every row says what
+the session asks of the viewer, what to do next, and which pull requests it
+opened; the active thread gets a persistent "waiting on you" strip; and a
+GitHub wake renders as a runtime marker instead of a user bubble.
+
+```tsx
+import { AthenaChat, AthenaProvider, SessionList } from '@athenaintel/react';
+
+<AthenaProvider enableThreadList config={{ token }}>
+  <aside><SessionList /></aside>
+  <AthenaChat />
+</AthenaProvider>
+```
+
+### Field contract (v1)
+
+Rows of `POST /api/conversations/threads/list` carry, all optional (an older
+server omits them and the SDK reads `undefined`):
+
+| REST field | SDK field (`ConversationSummary` / `AthenaStatewireThreadSummary`) | Values |
+|---|---|---|
+| `session_status` / `run_status` | `sessionStatus` / `runStatus` | status_v2 planes |
+| `attention` | `attention` | `needs_you` · `working` · `ready` · `watching` · `done` · `error` |
+| `next_action` | `nextAction` | one line, ≤ 80 chars |
+| `attention_source` | `attentionSource` | `interrupt` · `run` · `pull_request` · `termination` · `wake` · `handoff` |
+| `is_favorited` | `isFavorited` | boolean — toggled through `setFavorited` / `POST /api/conversations/threads/favorite` |
+| `last_wake` | `lastWake` | `{ source, reason, at }` |
+| `pull_requests` (opt-in: `include_pull_requests`) | `pullRequests` | `[{ repoFullName, number, url, title, state OPEN/CLOSED/MERGED, isDraft, reviewDecision, checksState SUCCESS/FAILURE/PENDING/NONE, updatedAt }]` — `[]` none, `null` unreadable right now |
+
+The per-user conversation index pushes `attention`, `next_action`,
+`attention_source` and `is_favorited` (never pull-request state), and the
+thread list folds every push into its rows through the same
+`summaryFromConversationIndexEntry` that renames them — a session flips to
+"needs you" live. `deriveConversationAttention` (exported) is the one
+attention rule: the server value when reported, else `needs_you` for a human
+gate, `working` for a live run, `error` for a failed one.
+
+### `SessionList`
+
+Same visual language as `ThreadList` (Tailwind via `cn`, lucide icons), plus:
+
+- a status indicator per row — `needs_you` an orange dot, `working` a spinner,
+  unread (and not needs-you) a blue dot, `watching` a clock, otherwise none;
+- a second line — `nextAction` coloured by attention (needs-you orange, ready
+  green, error red), else the muted relative time of the last update;
+- one pull-request chip (`#123`, or `3 PRs`) with the state icon of the
+  primary pull request (open / draft / merged / closed) linking to it — a
+  sibling of the row button, so a click on it never selects the row;
+- an origin badge from `appId` / `startChannel` / `triggerType` (Chrome,
+  Word, Computer, GitHub, API, …);
+- a trailing action cluster per row, revealed on hover / focus (a pinned pin
+  and any action whose write is in flight stay visible) — every action a
+  labelled `<button>` that is a sibling of the row control, never nested:
+  - **Rename** (prop `showRename`, default `true`): the title becomes an
+    input in place; Enter commits, Escape cancels, blur commits; an unchanged
+    or empty title is never sent; the row shows the new title at once and
+    rolls back on failure (`POST /api/conversations/threads/rename`,
+    `{ thread_id, title }` → the stored, trimmed title; 1–200 characters).
+    A viewer who can pin a shared session cannot retitle it (the route runs
+    the same EDIT gate as `updateAsset(title)`); the row rolls back on the
+    403. On an agora that predates the route (404 / 405) the action is
+    withdrawn (`renameAvailable`) after one console warning.
+  - **Pin / Unpin** (prop `showPinToggle`, default `true`): a `<button
+    aria-pressed>`, filled while the session is pinned.
+  - **Archive** (prop `showArchive`, default `true`): the row leaves the list
+    at once and stays hidden until both list sources stop reporting it; a
+    failure brings it back (`POST /api/conversations/threads/archive`).
+    Archiving the active session moves the chat to a new one once the server
+    has confirmed. Withdrawn on a backend without the route
+    (`archiveAvailable`).
+- groups `Needs you` → `Working` → `Pinned` → `Recent` (prop `grouped`,
+  default `true`; a session appears once, in the first group that applies),
+  labelled in 11 px uppercase muted text; the active row has a `bg-muted`
+  background and a 2 px accent bar; titles are `text-sm font-medium`, the
+  next-action line `text-xs` in its attention tone and never bolder than the
+  title; the pull-request chip sits on the meta line; every row control and
+  action has a `focus-visible` ring;
+- hover prefetch (prop `prefetchOnHover`, default `true`): after the pointer
+  has rested on a row for 120 ms (or when the row control takes focus) the
+  list warms the provider's thread snapshot cache with that thread's REST
+  state — once per thread per identity, at most two fetches in flight,
+  failures ignored — so selecting it paints the transcript on the first
+  frame instead of the loading scrim while the statewire attach lands
+  (`useAthenaStatewireThreadList().prefetchThread(threadId)` for hosts
+  drawing their own rows);
+- skeleton rows (indicator, title line, meta line) while the first page
+  loads — including while no credential has resolved — and for a refresh
+  that has no rows to keep; "No sessions yet." only after a settled empty
+  answer (`hasResolvedFirstPage`); a background refresh keeps the rows it has;
+- a search box wired to the server-side `search` (prop `showSearch`, default
+  `true`), `Load more` over the shared pager, and `New Chat` / refresh as in
+  `ThreadList`.
+
+The pin writes `POST /api/conversations/threads/favorite`
+(`{ thread_id, is_favorited }` → the server's state after the write) with the
+same credential as the other thread endpoints — `setThreadFavorite` is
+exported for hosts calling it themselves. The toggle is optimistic: the row
+flips (and moves between `Pinned` and `Recent`) on the click, the server's
+answer is written back, and a failure restores the previous state. The
+optimistic value is held as an override over both list sources — the fetched
+page and the pushed conversation index — until they report the toggled value,
+so a push that predates the write cannot flip the row back. Writes for one
+session are serialized: the row's pin is disabled while its write is in
+flight (`favoritePendingThreadIds`), and a `setFavorited` call made meanwhile
+records the value and sends at most one follow-up write once the first has
+answered, so the server never ends on an earlier click. Overrides and
+in-flight writes are scoped to the `(backendUrl, principal)` pair — a
+credential swap reads an empty map and drops the previous identity's
+answers. On an agora that
+predates the route the first toggle gets a 404 / 405
+(`isThreadFavoriteUnavailableError`): the row is restored, one console
+warning is logged, `favoriteToggleAvailable` on the thread-list state turns
+`false`, and the row shows a pinned session's pin read-only, as before. The
+conversation-history hooks (`useStatewireConversationHistory`,
+`useRestConversationHistory`) expose the same toggle as
+`setConversationFavorited` / `favoritePending` / `favoriteToggleAvailable`
+beside `setConversationReadState`.
+
+The provider asks for pull-request state by default in thread-list mode
+(`threadListIncludePullRequests`, default `true`; turn it off in a host that
+never shows the chips to spare the server the lookup). The pure rules behind
+the rows — `groupSessions`, `sessionIndicator`, `sessionSecondaryLine`,
+`pullRequestChip`, `sessionOriginLabel` — are exported for hosts drawing their
+own rows; `useAthenaStatewireThreadList().setFavorited({ threadId,
+isFavorited })` is the toggle behind them.
+
+### `useAthenaSessionAttention(threadId?)`
+
+`{ threadId, attention, nextAction, attentionSource, pullRequests, isUnread }`
+for the active (or given) thread, from the thread-list state; `null` outside
+thread-list mode or for a thread the list does not hold. Updates live with the
+index pushes.
+
+### `WaitingOnYouBanner`
+
+Mounted by `AthenaChat` above the thread viewport: a persistent strip while
+the active thread's attention is `needs_you` or the approval hook
+(`useStatewireApprovalRequest`) reports a pending request. Its text is the
+server's `nextAction`, else a summary of the pending request; a click scrolls
+to the approval card (or to the composer when there is none). It never
+duplicates the card's Approve / Reject buttons. `WaitingOnYouBannerView` is
+the pure presenter for hosts that resolve the inputs themselves.
+
+### Wake markers
+
+A user turn injected by a GitHub webhook wake carries a provenance envelope
+under `metadata.custom.github_event_source`. `AthenaChat`'s user message (and
+the `chat-ui` `UserMessage`) render such a turn as a compact runtime marker —
+"Woke: review comment on #36337", linked, with the sender and the comment
+excerpt — in the same style as the runtime-ending card, instead of a bubble
+quoting the whole wake text. `readGithubWakeEvent`, `isGithubWakeMessage`,
+`githubWakeMarkerText`, `WakeMarkerCard` and `WakeMarkerMessage` are exported
+(also on `@athenaintel/react/chat-ui` and `/chat-ui/statewire`).
+
+The envelope is message metadata, so the reader trusts only the shape the
+wake handler stamps: the repository must be `owner/name`, and the link is kept
+only when it is an `https://github.com/<repo>/…` URL for that repository
+(`githubWakeEventUrl`) — anything else renders the reference as plain text.
+The full message text always reaches the model; the marker is provenance for
+rendering only.
+
 ## Voice Sessions (`@athenaintel/react/voice`)
 
 `useAthenaVoiceSession` runs a real-time voice conversation with an Athena
@@ -234,6 +459,93 @@ Both use the same bearer / API key as session creation. The full recipe
 template skill `voice-session-guide.md`. `createAthenaVoiceSession` is also
 exported if you hold the bridge state yourself.
 
+## What's new in 0.23.0
+
+0.23.0 is the Devin-style sessions release: a session list that says what
+each session asks of you, live pull-request state, a "waiting on you" strip,
+wake markers, hover actions (rename / pin / archive) with skeleton loading
+and hover prefetch on that list, a provider whose host UI survives thread
+switches, a paper composer with a staged welcome, a 46rem reading column with
+one tool-card anatomy and grouped turns by default, assistant text that keeps
+its source links and read_asset citations as chips, and the AI Chat computer
+template rebuilt around them. No breaking changes to the API; `<AthenaChat
+groupToolCalls>` now defaults to `true` (pass `false` for the previous inline
+tool cards) and the AI Chat template's `VITE_CONVERSATIONAL_VIEW` defaults on.
+Shipped in this release, by pull request:
+
+- fix(react): AthenaProvider keys only the per-thread runtime so host UI survives thread switches; new export `useAthenaStatewireThreadId` (#36402)
+- feat(react): SessionList with attention, next action and pull-request chips; waiting-on-you banner; wake markers (#36365)
+- feat(react): SessionList pin toggle via `POST /api/conversations/threads/favorite` (#36371)
+- fix(react): pin toggle serializes same-thread writes and scopes overrides per identity (#36373)
+- feat(agora,react): admin-only repository code search route + `useAthenaRepoSearch` (Devin-style Ask) (#36302)
+- feat(agora): live pull-request state on the session list from `agent_pr_threads` (Devin-style sessions) (#36306)
+- feat(deep-agent): the message window per viewer, rebuilt on Statewire documents and per-attach interests (#36322)
+- fix(athena-app): dedupe `@assistant-ui` runtime packages so an SDK upgrade cannot mount two tap contexts (#36395)
+- feat(react): paper composer with clear send states, Enter-to-send hint and a staged welcome screen (#36412)
+- feat(react): thread reading column, scannable turns, one tool-card anatomy, anchored scroll and a quiet thinking line (#36413) — see [the thread's reading column](#styling) under Styling
+- feat(react): one tool-card anatomy for the SDK thread — `ToolFallback` thread appearance, grouped turns by default (#36411) — see [Tool cards in the thread](#tool-cards-in-the-thread)
+- feat(react): SessionList hover actions with inline rename, skeleton loading, hover prefetch and tighter rhythm; props `showRename` / `showArchive` / `prefetchOnHover`, thread-list state `renameThread` / `prefetchThread` / `renameAvailable` / `archiveAvailable` / `hasResolvedFirstPage` (#36415) — see [`SessionList`](#sessionlist)
+- feat(agora): REST rename for session threads (`POST /api/conversations/threads/rename`), the backend of the inline rename (#36409)
+- fix(react): assistant text keeps source links and read_asset citations as clickable chips; `TiptapText` renders through `ChatMessageBody` (#36414)
+- fix(react): message body re-parses only the trailing block and settles streamed words — block memoization, settled streamed words, deferred fence rendering while a reply streams (#36426)
+
+### Sources and citations (#36414)
+
+- **Sources and citations render as chips in every SDK chat surface.** The
+  static message body (`MarkdownText` / `ChatMessageBody`, and `AthenaChat`'s
+  default `TiptapText`, which now renders through it instead of a live Tiptap
+  editor per message) turns the deep agent's citation anchors into chips: a web
+  source (`<a class="mention" data-type="url" data-url="…" data-excerpt="…">`,
+  or any `<a href data-excerpt>`) becomes a favicon chip whose tooltip is the
+  excerpt and which opens the page at the excerpt (`#:~:text=`); a read_asset
+  citation (`<a class="mention" data-type="pdf" data-id="asset_…"
+  data-page-number=… data-excerpt="…">`) becomes an asset chip deep-linked to
+  the cited page (`anchor=page` / `page_range`) with the excerpt as its
+  tooltip; a citation the model left unlabelled reads `Page N` instead of an
+  empty chip. Markdown links, bare URLs and `mailto:` stay plain links; only
+  `http(s):`, `mailto:`, `athena-point:` and app-relative Spaces hrefs pass
+  (`javascript:`, `ftp:`, `data:`, `//host` are stripped to their label). Every
+  anchor click goes through `useAthenaLinkClickHandler` (`linkClicks`, then
+  the asset panel for an Athena citation); modified clicks stay with the
+  browser. Favicons are requested only for public-looking hosts.
+
+### Composer and welcome (#36412)
+
+- **Paper composer.** `<AthenaChat>` renders the shared composer dock's
+  `appearance="paper"` chrome: a card-toned surface (`bg-card`, hairline
+  `border`, 22px radius — still bound to the `composerBorder` /
+  `composerRadius` theme keys), a visible `focus-within` ring with a soft
+  shadow, a `data-drag-active="true"` tint while files hover, and a bottom
+  rail with attach + `@` mention on the left and send / stop on the right.
+  Send is an ink circle with the arrow that reads inert at 30% while the
+  draft is empty; stop is the same circle with a filled square. The draft
+  grows to about eight lines (`12rem`) before it scrolls. The first time the
+  composer is focused in a browser it shows "Enter to send · Shift+Enter for
+  a new line" underneath, until the first send (`localStorage`
+  `athena-sdk:composer-hint-seen`). Enter sends and Shift+Enter breaks the
+  line on every surface, as before.
+- **Staged welcome.** The greeting (`h2`) fades and rises in, the suggestion
+  cards stagger in at 120 ms + 70 ms × index directly above the composer
+  (equal-width in one row from a 40rem-wide thread, a two-column grid below),
+  and the composer arrives last when the thread mounts empty — at 360 ms
+  behind the default four cards, behind the last card when a host passes more.
+  `prefers-reduced-motion` renders all of it in place with no motion.
+- `@athenaintel/react/chat-ui`: `ChatComposerDock` gains `appearance`
+  (`"default" | "paper"`, default unchanged), `dragActive` and
+  `belowSurface`; `TiptapComposer` gains `appearance`, `onSubmitted` and the
+  handle method `openMentionMenu()`; `ComposerDropZone` gains
+  `onDragActiveChange`. The Chrome extension and Office add-in keep the
+  default chrome and are unaffected.
+
+The AI Chat computer template (`docker/athena-app`) pinned to this version
+mounts `SessionList` in its sidebar (hover rename / pin / archive, skeleton
+loading and hover prefetch at their defaults), shows the active session's title and
+attention state in its header, keeps `?session_id` in step with the active
+thread (restored once per page load; one history entry per switch, so Back /
+Forward walk sessions), scopes the thread-loading overlay to the chat column,
+and adds a Cmd/Ctrl+K command palette with `Cmd/Ctrl+Shift+O` (new chat) and
+`Cmd/Ctrl+]` / `Cmd/Ctrl+[` (next / previous session).
+
 ## What's new in 0.22.4
 
 Message actions catch up with Olympus Spaces: assistant replies gain a Regenerate button and a branch picker; user bubbles gain a hover-revealed Copy / Edit bar (Edit hides on read-only threads, while a run is live, or when the runtime lacks the capability) plus a branch picker; code blocks in replies get a copy button; the composer placeholder now hints at `@` mentions. New optional `readOnly` prop on `AthenaChat` hides Edit and Regenerate for transcripts whose server rejects dispatch.
@@ -708,6 +1020,62 @@ text anchors, and positioned citations are also preserved by `parseAthenaCitatio
 `page_rect` may include `unit=percent` (the default) or `unit=point`; retain the unit so the region
 maps to the correct PDF coordinates.
 
+## Repository Code Search (platform staff only, managed cloud)
+
+`useAthenaRepoSearch` searches the workspace's indexed GitHub repositories
+(Clio's repository source) through `POST /api/search/repositories`, without an
+agent turn — the building block for a Devin-style "Ask" surface. It is a
+TanStack Query hook keyed by the request (never by the credential) and uses
+the provider's `backendUrl` and credentials; it works under any
+`<AthenaProvider>`, with or without `enableThreadList`.
+
+The route is limited to **Athena platform staff** (the account-level `is_admin`
+flag — a workspace-role admin is not enough; it is the Clio internal-phase
+audience) and offered on Athena's managed cloud only: a non-staff caller reads
+`403`, a private deployment `404`, both surfaced as an `AthenaSdkError`
+(`auth_rejected` / `repo_search_failed`).
+
+```tsx
+import { useAthenaRepoSearch } from '@athenaintel/react';
+
+function Ask({ query }: { query: string }) {
+  const search = useAthenaRepoSearch({
+    query,
+    limit: 10, // 1–25
+    mode: 'hybrid', // or 'lexical'
+    paths: ['agora/**/*.py'], // gitignore-style globs (optional)
+    languages: ['python'], // Clio language names (optional)
+    repositoryAssetIds: [], // scope to GitHub catalog assets (optional)
+  });
+  if (search.isPending) return <p>Searching…</p>;
+  if (search.isError) return <p>{search.error.message}</p>;
+  return (
+    <ul>
+      {search.data.hits.map((hit) => (
+        <li key={hit.readAssetReference}>
+          <a href={hit.githubUrl ?? undefined}>
+            {hit.path}:{hit.startLine}-{hit.endLine}
+          </a>
+          {hit.symbol ? ` · ${hit.symbol}` : null}
+          <pre>{hit.snippet}</pre>
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+Each hit carries `catalogAssetId`, `repoFullName`, `path`, `startLine` /
+`endLine`, `symbol`, `language`, `unitType` (`code` or `window`), `score`,
+`commitSha`, a GHES-aware `githubUrl` permalink at the indexed commit, the
+`snippet` (header line removed, line breaks kept) and `readAssetReference`
+(`asset_<catalog>?anchor=file_line_range&…`, what `read_asset` and a citation
+take). Without the SDK, call the route directly: `POST
+{backendUrl}/api/search/repositories` with `Content-Type: application/json`,
+`Authorization: Bearer <token>` (or `X-API-KEY: <workspace API key>`) and the
+body `{ query, limit?, mode?, repository_asset_ids?, paths?, languages? }`;
+`fetchRepoSearch` and `repoSearchRequestBody` are exported for that too.
+
 ## Live Collaboration (`@athenaintel/react/collab`)
 
 The `collab` entry hosts the Keryx-backed live surfaces: `useGenericDoc` /
@@ -779,6 +1147,8 @@ Hosts that already run **Tailwind v4** (like the athena-app template) may instea
 
 Importing `styles.css` alongside a host Tailwind build is harmless (utilities are identical and layered). One caveat for themed Tailwind hosts: token values set on the `.athena-sdk` element shadow values inherited from `:root`, so define your app's token overrides on `.athena-sdk` too (`:root, .athena-sdk { --primary: …; }`) — or use the `theme` prop below, which always wins.
 
+The thread's reading column defaults to a 46rem measure (set it with `<AthenaChat maxWidth>`; the chat passes that value to the thread, so the `threadMaxWidth` theme token does not reach it), 15px body text on a relaxed leading, and the `--font-sans` stack (`Inter, ui-sans-serif, system-ui, …` — a stack only, the SDK downloads no webfont). Override the face with `theme.fontFamily`, or `.athena-sdk { --font-sans: …; }`. Assistant turns carry a quiet 2px leading rule (replace it with `components.AssistantAvatar`); every message shows its time on hover beside its action bar, and a day separator marks the first message of a new calendar day.
+
 ## Theming
 
 ```tsx
@@ -800,12 +1170,28 @@ For CSS-level theming without the `theme` prop, set the design-token custom prop
 }
 ```
 
+## Tool cards in the thread
+
+`<AthenaChat>` folds each turn's tool calls into one collapsible activity group with a count, the answer rendered below it (`groupToolCalls`, default `true`; pass `false` to list every tool card inline in call order). Every tool call it renders — the generic `ToolFallback`, the built-in tool UIs, nested sub-calls — shares one row anatomy: a status glyph (spinner / check / x / alert), the verb and its target on one line, a running call's elapsed seconds after three, a failed call tinted red, and a disclosure for the arguments and result.
+
+That row is the `thread` appearance of `ToolFallback`. Hosts that render their own thread keep the boxed host card they render today (the default, `card`); to adopt the row, wrap the thread in the provider or set it per card:
+
+```tsx
+import { ToolFallback, ToolFallbackAppearanceProvider } from '@athenaintel/react/tools';
+
+<ToolFallbackAppearanceProvider appearance="thread">{/* …the thread… */}</ToolFallbackAppearanceProvider>
+<ToolFallback {...props} appearance="thread" />
+```
+
+Dedicated tool UIs built on `ToolCard` follow the provider automatically; `useToolAppearance()` reads the appearance in force for a custom tool UI.
+
 ## Key Components
 
 - **`<AthenaProvider>`** — Runtime, auth, theming, and configuration
 - **`<AthenaChat>`** — Full chat UI with composer, messages, and tool rendering
 - **`<AthenaLayout>`** — Split-pane layout with asset panel
-- **`<ThreadList>`** — Conversation history sidebar
+- **`<SessionList>`** — Session sidebar: attention, next action, pull-request chips, pin, search (see [Session list, attention and wake markers](#session-list-attention-and-wake-markers))
+- **`<ThreadList>`** — Plain conversation history sidebar (title rows only)
 - **`Toolkits`** — Constants for all available backend toolkits
 
 ## Composer Hooks