@athenaintel/react 0.11.0 → 0.11.2

package/README.md

@@ -103,9 +103,83 @@ What the statewire transport wires up in `AthenaChat`:
   statewire session to the selected thread. `ThreadList` and
   `useAthenaThreadManager` work in both modes.
 
-Remaining limitations: the `agent` prop is legacy-only (the statewire host
-always runs the Athena deep agent), and `model` defaults to the deep-agent
-default model in this mode.
+Remaining limitations: on statewire the `agent` prop only accepts
+`collab_agent:<asset_id>` refs (see below) — any other value is ignored,
+because the statewire host always runs the Athena deep agent. `model`
+defaults to the deep-agent default model unless a collab agent supplies one.
+
+## Collab Agents
+
+A **collab agent** is an agent configuration authored in Athena (prompt,
+model, toolkits, behavior) and addressed as `collab_agent:<asset_id>`. Point
+the provider at one and the chat runs **as** that agent:
+
+```tsx
+<AthenaProvider
+  transport="statewire"
+  agent="collab_agent:asset_432af46f-293d-480b-a518-30b1f42a9ef7"
+  channel="askbob_web"
+>
+  <AthenaChat />
+</AthenaProvider>
+```
+
+Copy the snippet with real ids from the agent's **Channels** tab in Athena.
+
+`channel` is optional. It selects a **channel override layer** — a built-in
+channel (`email`, `sms`, …) or a custom channel defined on that agent — so one
+agent can present different prompts, models, and tools per surface. Omit it to
+run the agent's base configuration.
+
+### Requirements
+
+- **`transport="statewire"`.** The legacy transport ignores `collab_agent:` refs.
+- **Publish the agent.** Resolution reads the *published* snapshot, not the
+  live draft, so a channel that exists only in the editor is rejected with
+  `collab_agent_channel_unknown`.
+- **The acting user needs VIEW access** to the agent asset (admins bypass).
+  Running as an agent exposes its prompt and tool policy, so the same gate that
+  governs opening the asset governs running it.
+
+### Do not also pass `model`, `systemPrompt`, or `tools`
+
+Request keys override the agent definition, so **anything you pass here
+silently replaces what the agent's author configured** — the run succeeds and
+returns a plausible answer using your config instead of theirs.
+
+```tsx
+// ❌ the agent's prompt, model, and tools are all discarded
+<AthenaProvider
+  transport="statewire"
+  agent="collab_agent:asset_1234"
+  model="claude-opus-4-6"
+  systemPrompt="You are a helpful assistant."
+  tools={['web_search_browse_toolkit']}
+/>
+
+// ✅ the agent's own configuration wins
+<AthenaProvider transport="statewire" agent="collab_agent:asset_1234" />
+```
+
+Pass them only when you deliberately want to override the agent — an explicit
+`model` is honoured as a caller override, with the agent's model as the default
+beneath it.
+
+### Failure codes
+
+A refused selection surfaces as an `AthenaSdkError` with
+`code: 'collab_agent_rejected'`; the specific reason below rides in the error's
+`detail`. Subscribe with `onError` (see
+[Debugging](#debugging-and-diagnostics)) rather than guessing from messages:
+
+| Code | Meaning |
+|---|---|
+| `collab_agent_not_found` | No such asset, or it is not a `collab_agent` |
+| `collab_agent_forbidden` | The acting user lacks VIEW on the asset |
+| `collab_agent_channel_unknown` | No such channel (the message lists the known ones) |
+| `collab_agent_channel_disabled` | The channel exists but is toggled off |
+| `collab_agent_channel_kind_mismatch` | A voice channel was selected for a text run |
+| `collab_agent_runs_disabled` | The deployment has the SDK seam turned off |
 
 ## Authentication
 
@@ -283,6 +357,24 @@ 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.
 
+## Styling
+
+`styles.css` is a self-contained stylesheet compiled at package build time. One import styles every SDK component — the host app does **not** need Tailwind:
+
+```tsx
+import '@athenaintel/react/styles.css';
+```
+
+It contains the design tokens, the Tailwind utilities the SDK components use, and an element reset (preflight) **scoped to the SDK's own chrome** (`.aui-root` trees and `.athena-sdk-chrome` roots, including portaled tooltips/popups). It never restyles the host page — not even host components you nest inside `AthenaProvider` to use hooks like `useSendMessage`: the reset only reaches SDK-rendered roots, design tokens live on the provider's `.athena-sdk` wrapper (inert custom properties) rather than `:root`, and everything ships in CSS cascade layers so any unlayered host rule wins on conflict.
+
+Hosts that already run **Tailwind v4** (like the athena-app template) may instead — or additionally — compile the SDK's classes themselves:
+
+```css
+@source "../node_modules/@athenaintel/react/dist";
+```
+
+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.
+
 ## Theming
 
 ```tsx
@@ -295,6 +387,15 @@ import { themes } from '@athenaintel/react';
 
 Preset themes: `light`, `dark`, `midnight`, `warm`, `purple`, `green`.
 
+For CSS-level theming without the `theme` prop, set the design-token custom properties on `.athena-sdk` (unlayered rules override the SDK's layered defaults):
+
+```css
+.athena-sdk {
+  --primary: oklch(0.4 0.15 260);
+  --radius: 1rem;
+}
+```
+
 ## Key Components
 
 - **`<AthenaProvider>`** — Runtime, auth, theming, and configuration
@@ -323,6 +424,52 @@ function WorkflowButton() {
 }
 ```
 
+## Debugging and Diagnostics
+
+The SDK emits structured diagnostic events — auth handshake, thread list,
+statewire attach, sends, errors — with timings. Nothing is logged by default;
+turn it on with the `debug` prop:
+
+```tsx
+<AthenaProvider
+  debug                        // or 'debug' | 'info' | { console: 'debug', posthog: true }
+  onDiagnostic={(event) => console.log(event.name, event.durationMs)}
+  onError={(error) => reportToSentry(error)}
+>
+```
+
+`onError` receives an `AthenaSdkError` with a stable `code`, a human `hint`,
+and the originating `status`/`detail` — match on `code`, never on message text:
+
+```tsx
+import { ATHENA_SDK_ERROR_CODES } from '@athenaintel/react';
+
+onError={(error) => {
+  if (error.code === ATHENA_SDK_ERROR_CODES.collab_agent_rejected) {
+    // the backend's granular reason rides in `detail`, e.g.
+    // 'collab_agent_channel_unknown' — whose message lists the known channels
+    console.warn(error.detail, error.hint);
+  }
+}}
+```
+
+Each provider registers its own consumer, so multiple mounted providers all
+receive every event; a callback that throws is caught and cannot break the chat.
+
+Without a rebuild, from the browser console:
+
+```js
+localStorage.setItem('athena:debug', 'debug');  // console echo on, survives reload
+__ATHENA_SDK__.diagnostics.snapshot();          // recent events + timings
+__ATHENA_SDK__.diagnostics.export();            // JSON, for attaching to a bug report
+```
+
+Credentials are redacted everywhere (buffer, console, PostHog): any key
+matching `token`, `secret`, `api[-_]?key`, `authorization`, `cookie`, or
+`password` is stripped before an event is recorded. Spans also emit
+`performance.mark`/`measure` entries prefixed `athena-sdk:`, so they show up on
+the browser Performance timeline.
+
 ## License
 
 Proprietary. For licensed enterprise customers only.