docs: add status sections, fix the React quick start, drop the broken CSS import

.github/CONTRIBUTING.md

@@ -14,9 +14,9 @@ This is a Bun workspaces monorepo. The widget package depends on sibling repos v
 ```bash
 # Clone all repos as siblings
 cd ~/Projects/deepgram  # or your preferred directory
-git clone git@github.com:deepgram/agent.git
-git clone git@github.com:deepgram/react.git
-git clone git@github.com:deepgram/ui.git
+git clone https://github.com/deepgram/agent.git
+git clone https://github.com/deepgram/react.git
+git clone https://github.com/deepgram/ui.git
 
 # Build sibling dependencies
 cd react && bun install && bun run build && cd ..

.github/workflows/cdn-dryrun.yml

@@ -15,6 +15,7 @@ permissions:
 
 jobs:
   dryrun-widget:
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6

README.md

@@ -6,6 +6,10 @@ Voice agent SDK and embeddable widget for the [Deepgram Agent API](https://devel
 @deepgram/agents  ←  @deepgram/react (external)  ←  @deepgram/ui (external)  ←  @deepgram/agents-widget
 ```
 
+## Status
+
+These packages are pre-1.0. Interfaces may change between minor versions, and releases are cut as the libraries evolve rather than on a fixed schedule. The packages in this family build on the [Deepgram Voice Agent API](https://developers.deepgram.com/docs/voice-agent) to provide browser SDKs, React hooks and UI components, and an embeddable widget.
+
 ## Packages
 
 | Package | Description |
@@ -42,9 +46,25 @@ The package also ships a UMD bundle at `dist/widget.umd.js` for `<script>`-tag u
 ### React
 
 ```tsx
-import { AgentProvider, useAgentState, useAgentConversation } from "@deepgram/ui";
-import "@deepgram/ui/styles.css";
-import { AgentConversation, AgentStartButton, AgentTextInput } from "@deepgram/ui";
+import {
+  AgentProvider,
+  AgentConversation,
+  AgentMessage,
+  AgentStartButton,
+  AgentTextInput,
+  useAgentConversation,
+} from "@deepgram/ui";
+
+function Conversation() {
+  const { conversation } = useAgentConversation();
+  return (
+    <AgentConversation>
+      {conversation.map((entry) => (
+        <AgentMessage key={entry.id} entry={entry} />
+      ))}
+    </AgentConversation>
+  );
+}
 
 function App() {
   return (
@@ -54,14 +74,18 @@ function App() {
         agent: { think: { provider: { type: 'open_ai', model: 'gpt-4o-mini' } } },
       }}
     >
-      <AgentStartButton />
-      <AgentConversation />
-      <AgentTextInput />
+      <div data-dg-agent>
+        <AgentStartButton />
+        <Conversation />
+        <AgentTextInput />
+      </div>
     </AgentProvider>
   );
 }
 ```
 
+Styles are embedded in the JavaScript bundle and injected automatically; no separate CSS import is required. The injected styles, including the theme variables and dark-mode behavior, apply only inside an element that carries the `data-dg-agent` attribute, so keep the components inside that wrapper.
+
 ### SDK only
 
 ```ts
@@ -128,7 +152,7 @@ Live demo: [deepgram-agent-examples.fly.dev](https://deepgram-agent-examples.fly
 **Prerequisites:** [Bun](https://bun.sh/) 1.3+
 
 ```bash
-git clone git@github.com:deepgram/agent.git
+git clone https://github.com/deepgram/agent.git
 cd agent
 bun install
 ```

examples/10-react-sidebar/index.html

@@ -32,15 +32,27 @@ <h3>Code</h3>
   <span class="fn">AgentProvider</span>, <span class="fn">AgentStatus</span>, <span class="fn">AgentConversation</span>,
   <span class="fn">AgentTextInput</span>, <span class="fn">AgentMicrophoneButton</span>,
   <span class="fn">AgentSpeakerButton</span>, <span class="fn">AgentStartButton</span>,
+  <span class="fn">AgentMessage</span>, <span class="fn">useAgentConversation</span>,
 } <span class="kw">from</span> <span class="str">'@deepgram/ui'</span>;
 
+<span class="kw">function</span> <span class="fn">Conversation</span>() {
+  <span class="kw">const</span> { conversation } = <span class="fn">useAgentConversation</span>();
+  <span class="kw">return</span> (
+    <span class="tag">&lt;AgentConversation&gt;</span>
+      {conversation.map((entry) =&gt; (
+        <span class="tag">&lt;AgentMessage</span> <span class="at">key</span>={entry.id} <span class="at">entry</span>={entry} <span class="tag">/&gt;</span>
+      ))}
+    <span class="tag">&lt;/AgentConversation&gt;</span>
+  );
+}
+
 <span class="tag">&lt;AgentProvider</span> <span class="at">config</span>={config}<span class="tag">&gt;</span>
   <span class="tag">&lt;div</span> <span class="at">className</span>=<span class="str">"agent-sidebar"</span> <span class="at">data-dg-agent</span> <span class="at">data-dg-scheme</span>=<span class="str">"dark"</span><span class="tag">&gt;</span>
     <span class="tag">&lt;div</span> <span class="at">style</span>={{ padding: <span class="str">"14px 16px"</span>, display: <span class="str">"flex"</span>, gap: 10 }}<span class="tag">&gt;</span>
       <span class="tag">&lt;span</span> <span class="at">style</span>={{ fontWeight: 600, flex: 1 }}<span class="tag">&gt;</span>Agent<span class="tag">&lt;/span&gt;</span>
       <span class="tag">&lt;AgentStatus /&gt;</span>
     <span class="tag">&lt;/div&gt;</span>
-    <span class="tag">&lt;AgentConversation /&gt;</span>
+    <span class="tag">&lt;Conversation /&gt;</span>
     <span class="tag">&lt;div</span> <span class="at">style</span>={{ padding: <span class="str">"12px 16px"</span>, display: <span class="str">"flex"</span>, flexDirection: <span class="str">"column"</span>, gap: 10 }}<span class="tag">&gt;</span>
       <span class="tag">&lt;div</span> <span class="at">style</span>={{ display: <span class="str">"flex"</span>, gap: 8 }}<span class="tag">&gt;</span>
         <span class="tag">&lt;AgentTextInput /&gt;</span>
@@ -61,7 +73,7 @@ <h3>Code</h3>
     import {
       AgentProvider, AgentStatus, AgentConversation,
       AgentTextInput, AgentMicrophoneButton, AgentSpeakerButton,
-      AgentStartButton,
+      AgentStartButton, AgentMessage, useAgentConversation,
     } from "@deepgram/ui";
     import { baseConfig } from "../src/agent-config.ts";
 
@@ -74,6 +86,13 @@ <h3>Code</h3>
       },
     };
 
+    function Conversation() {
+      const { conversation } = useAgentConversation();
+      return createElement(AgentConversation, null,
+        conversation.map((entry) => createElement(AgentMessage, { key: entry.id, entry })),
+      );
+    }
+
     function App() {
       const [open, setOpen] = useState(false);
 
@@ -91,7 +110,7 @@ <h3>Code</h3>
               createElement(AgentStatus),
               createElement("button", { onClick: () => setOpen(false), style: { background: "none", border: "none", color: "#8b8b9a", cursor: "pointer", fontSize: 18 } }, "✕"),
             ),
-            createElement(AgentConversation),
+            createElement(Conversation),
             createElement("div", { style: { padding: "12px 16px", display: "flex", flexDirection: "column", gap: 10, borderTop: "1px solid rgba(255,255,255,.08)" } },
               createElement("div", { style: { display: "flex", gap: 8, alignItems: "center" } },
                 createElement(AgentTextInput),

examples/11-react-inline/index.html

@@ -32,11 +32,23 @@ <h3>Code</h3>
   <span class="fn">AgentProvider</span>, <span class="fn">AgentStatus</span>, <span class="fn">AgentConversation</span>,
   <span class="fn">AgentTextInput</span>, <span class="fn">AgentMicrophoneButton</span>,
   <span class="fn">AgentSpeakerButton</span>, <span class="fn">AgentStartButton</span>,
+  <span class="fn">AgentMessage</span>, <span class="fn">useAgentConversation</span>,
 } <span class="kw">from</span> <span class="str">'@deepgram/ui'</span>;
 
+<span class="kw">function</span> <span class="fn">Conversation</span>() {
+  <span class="kw">const</span> { conversation } = <span class="fn">useAgentConversation</span>();
+  <span class="kw">return</span> (
+    <span class="tag">&lt;AgentConversation&gt;</span>
+      {conversation.map((entry) =&gt; (
+        <span class="tag">&lt;AgentMessage</span> <span class="at">key</span>={entry.id} <span class="at">entry</span>={entry} <span class="tag">/&gt;</span>
+      ))}
+    <span class="tag">&lt;/AgentConversation&gt;</span>
+  );
+}
+
 <span class="tag">&lt;AgentProvider</span> <span class="at">config</span>={config}<span class="tag">&gt;</span>
   <span class="tag">&lt;div</span> <span class="at">className</span>=<span class="str">"agent-panel"</span> <span class="at">data-dg-agent</span> <span class="at">data-dg-scheme</span>=<span class="str">"dark"</span><span class="tag">&gt;</span>
-    <span class="tag">&lt;AgentConversation /&gt;</span>
+    <span class="tag">&lt;Conversation /&gt;</span>
     <span class="tag">&lt;div</span> <span class="at">style</span>={{ padding: 12, display: <span class="str">"flex"</span>, flexDirection: <span class="str">"column"</span>, gap: 10 }}<span class="tag">&gt;</span>
       <span class="tag">&lt;AgentTextInput /&gt;</span>
       <span class="tag">&lt;AgentStartButton /&gt;</span>
@@ -53,7 +65,7 @@ <h3>Code</h3>
     import {
       AgentProvider, AgentStatus, AgentConversation,
       AgentTextInput, AgentMicrophoneButton, AgentSpeakerButton,
-      AgentStartButton,
+      AgentStartButton, AgentMessage, useAgentConversation,
     } from "@deepgram/ui";
     import { baseConfig } from "../src/agent-config.ts";
 
@@ -66,14 +78,21 @@ <h3>Code</h3>
       },
     };
 
+    function Conversation() {
+      const { conversation } = useAgentConversation();
+      return createElement(AgentConversation, null,
+        conversation.map((entry) => createElement(AgentMessage, { key: entry.id, entry })),
+      );
+    }
+
     function App() {
       return createElement(AgentProvider, { config },
         createElement("div", { className: "agent-panel", "data-dg-agent": "", "data-dg-scheme": "dark" },
           createElement("div", { style: { padding: "14px 16px", display: "flex", alignItems: "center", gap: 10, borderBottom: "1px solid rgba(255,255,255,.08)" } },
             createElement("span", { style: { fontWeight: 600, flex: 1, color: "#fff" } }, "Voice Agent"),
             createElement(AgentStatus),
           ),
-          createElement(AgentConversation),
+          createElement(Conversation),
           createElement("div", { style: { padding: "12px 16px", display: "flex", flexDirection: "column", gap: 10, borderTop: "1px solid rgba(255,255,255,.08)" } },
             createElement("div", { style: { display: "flex", gap: 8, alignItems: "center" } },
               createElement(AgentTextInput),

examples/12-react-floating/index.html

@@ -35,13 +35,25 @@ <h3>Code</h3>
     <pre class="code"><span class="kw">import</span> {
   <span class="fn">AgentProvider</span>, <span class="fn">AgentConversation</span>,
   <span class="fn">AgentTextInput</span>, <span class="fn">AgentStartButton</span>,
+  <span class="fn">AgentMessage</span>, <span class="fn">useAgentConversation</span>,
 } <span class="kw">from</span> <span class="str">'@deepgram/ui'</span>;
 
+<span class="kw">function</span> <span class="fn">Conversation</span>() {
+  <span class="kw">const</span> { conversation } = <span class="fn">useAgentConversation</span>();
+  <span class="kw">return</span> (
+    <span class="tag">&lt;AgentConversation&gt;</span>
+      {conversation.map((entry) =&gt; (
+        <span class="tag">&lt;AgentMessage</span> <span class="at">key</span>={entry.id} <span class="at">entry</span>={entry} <span class="tag">/&gt;</span>
+      ))}
+    <span class="tag">&lt;/AgentConversation&gt;</span>
+  );
+}
+
 <span class="tag">&lt;button</span> <span class="at">className</span>=<span class="str">"agent-fab"</span> <span class="at">onClick</span>={toggle}<span class="tag">&gt;</span>🎙<span class="tag">&lt;/button&gt;</span>
 {open &amp;&amp; (
   <span class="tag">&lt;AgentProvider</span> <span class="at">config</span>={config}<span class="tag">&gt;</span>
     <span class="tag">&lt;div</span> <span class="at">className</span>=<span class="str">"agent-floating"</span> <span class="at">data-dg-agent</span> <span class="at">data-dg-scheme</span>=<span class="str">"dark"</span><span class="tag">&gt;</span>
-      <span class="tag">&lt;AgentConversation /&gt;</span>
+      <span class="tag">&lt;Conversation /&gt;</span>
       <span class="tag">&lt;div</span> <span class="at">style</span>={{ padding: 12, display: <span class="str">"flex"</span>, flexDirection: <span class="str">"column"</span>, gap: 10 }}<span class="tag">&gt;</span>
         <span class="tag">&lt;AgentTextInput /&gt;</span>
         <span class="tag">&lt;AgentStartButton /&gt;</span>
@@ -59,7 +71,7 @@ <h3>Code</h3>
     import {
       AgentProvider, AgentStatus, AgentConversation,
       AgentTextInput, AgentMicrophoneButton, AgentSpeakerButton,
-      AgentStartButton,
+      AgentStartButton, AgentMessage, useAgentConversation,
     } from "@deepgram/ui";
     import { baseConfig } from "../src/agent-config.ts";
 
@@ -72,6 +84,13 @@ <h3>Code</h3>
       },
     };
 
+    function Conversation() {
+      const { conversation } = useAgentConversation();
+      return createElement(AgentConversation, null,
+        conversation.map((entry) => createElement(AgentMessage, { key: entry.id, entry })),
+      );
+    }
+
     function App() {
       const [open, setOpen] = useState(false);
 
@@ -89,7 +108,7 @@ <h3>Code</h3>
               createElement(AgentStatus),
               createElement("button", { onClick: () => setOpen(false), style: { background: "none", border: "none", color: "#8b8b9a", cursor: "pointer", fontSize: 18 } }, "✕"),
             ),
-            createElement(AgentConversation),
+            createElement(Conversation),
             createElement("div", { style: { padding: "12px 16px", display: "flex", flexDirection: "column", gap: 10, borderTop: "1px solid rgba(255,255,255,.08)" } },
               createElement("div", { style: { display: "flex", gap: 8, alignItems: "center" } },
                 createElement(AgentTextInput),

examples/13-react-ui-standalone/index.html

@@ -32,11 +32,23 @@ <h3>Code</h3>
   <span class="fn">AgentProvider</span>, <span class="fn">AgentStatus</span>, <span class="fn">AgentConversation</span>,
   <span class="fn">AgentTextInput</span>, <span class="fn">AgentMicrophoneButton</span>,
   <span class="fn">AgentSpeakerButton</span>, <span class="fn">AgentStartButton</span>,
+  <span class="fn">AgentMessage</span>, <span class="fn">useAgentConversation</span>,
 } <span class="kw">from</span> <span class="str">'@deepgram/ui'</span>;
 
+<span class="kw">function</span> <span class="fn">Conversation</span>() {
+  <span class="kw">const</span> { conversation } = <span class="fn">useAgentConversation</span>();
+  <span class="kw">return</span> (
+    <span class="tag">&lt;AgentConversation&gt;</span>
+      {conversation.map((entry) =&gt; (
+        <span class="tag">&lt;AgentMessage</span> <span class="at">key</span>={entry.id} <span class="at">entry</span>={entry} <span class="tag">/&gt;</span>
+      ))}
+    <span class="tag">&lt;/AgentConversation&gt;</span>
+  );
+}
+
 <span class="tag">&lt;AgentProvider</span> <span class="at">config</span>={config}<span class="tag">&gt;</span>
   <span class="tag">&lt;div</span> <span class="at">className</span>=<span class="str">"agent-card"</span> <span class="at">data-dg-agent</span> <span class="at">data-dg-scheme</span>=<span class="str">"dark"</span><span class="tag">&gt;</span>
-    <span class="tag">&lt;AgentConversation /&gt;</span>
+    <span class="tag">&lt;Conversation /&gt;</span>
     <span class="tag">&lt;div</span> <span class="at">style</span>={{ padding: 12, display: <span class="str">"flex"</span>, flexDirection: <span class="str">"column"</span>, gap: 10 }}<span class="tag">&gt;</span>
       <span class="tag">&lt;div</span> <span class="at">style</span>={{ display: <span class="str">"flex"</span>, gap: 8 }}<span class="tag">&gt;</span>
         <span class="tag">&lt;AgentTextInput /&gt;</span>
@@ -57,7 +69,7 @@ <h3>Code</h3>
     import {
       AgentProvider, AgentStatus, AgentConversation,
       AgentTextInput, AgentMicrophoneButton, AgentSpeakerButton,
-      AgentStartButton,
+      AgentStartButton, AgentMessage, useAgentConversation,
     } from "@deepgram/ui";
     import { baseConfig } from "../src/agent-config.ts";
 
@@ -70,14 +82,21 @@ <h3>Code</h3>
       },
     };
 
+    function Conversation() {
+      const { conversation } = useAgentConversation();
+      return createElement(AgentConversation, null,
+        conversation.map((entry) => createElement(AgentMessage, { key: entry.id, entry })),
+      );
+    }
+
     function App() {
       return createElement(AgentProvider, { config },
         createElement("div", { className: "agent-card", "data-dg-agent": "", "data-dg-scheme": "dark" },
           createElement("div", { style: { padding: "14px 16px", display: "flex", alignItems: "center", gap: 10, borderBottom: "1px solid rgba(255,255,255,.08)" } },
             createElement("span", { style: { fontWeight: 600, flex: 1, color: "#fff" } }, "Voice Agent"),
             createElement(AgentStatus),
           ),
-          createElement(AgentConversation),
+          createElement(Conversation),
           createElement("div", { style: { padding: "12px 16px", display: "flex", flexDirection: "column", gap: 10, borderTop: "1px solid rgba(255,255,255,.08)" } },
             createElement("div", { style: { display: "flex", gap: 8, alignItems: "center" } },
               createElement(AgentTextInput),

packages/sdk/README.md

@@ -2,8 +2,18 @@
 
 Core SDK for the [Deepgram Voice Agent API](https://developers.deepgram.com/docs/voice-agent). Manages the WebSocket session, microphone capture, and audio playback with volume/frequency analysis.
 
+## Status
+
+This package is pre-1.0. Interfaces may change between minor versions.
+
 ## Install
 
+```bash
+npm install @deepgram/agents
+```
+
+or with Bun:
+
 ```bash
 bun add @deepgram/agents
 ```

packages/widget/README.md

@@ -4,6 +4,10 @@ Self-contained voice agent widget for the [Deepgram Agent API](https://developer
 
 Bundles Preact internally (React components from `@deepgram/ui` are aliased to `preact/compat`).
 
+## Status
+
+This package is pre-1.0. Interfaces may change between minor versions.
+
 ## Install
 
 ```bash