diff --git a/docs/Guides/React Components and Custom UIs.md b/docs/Guides/React Components and Custom UIs.md
index d598c08..c1342b3 100644
--- a/docs/Guides/React Components and Custom UIs.md	
+++ b/docs/Guides/React Components and Custom UIs.md	
@@ -2,15 +2,17 @@
 
 smooth-operator's frontend story is **layered and modular** — you can adopt as
 much or as little UI as you want, because every layer sits on the same
-schema-driven WebSocket protocol. And it's all **one package**,
-`@smooai/smooth-operator`, with subpath exports — install once, import the layer
-you need:
+schema-driven WebSocket protocol. The headless client + React layers ship in
+**one package**, `@smooai/smooth-operator` (subpath exports — install once,
+import the layer you need); the no-build embeddable chat widget is the separate,
+**canonical** public package **`@smooai/chat-widget`** (the "Aurora Glass"
+design), which consumes the same client under the hood:
 
 ```mermaid
 flowchart TD
   P["WebSocket protocol<br/>(spec/ — language-neutral)"]
   C["@smooai/smooth-operator<br/>headless TS client"]
-  W["@smooai/smooth-operator/widget<br/>web component (any framework / no build)"]
+  W["@smooai/chat-widget (Aurora Glass)<br/>web component (any framework / no build)"]
   H["@smooai/smooth-operator/react · useConversation<br/>headless hook (your own UI)"]
   S["@smooai/smooth-operator/react · &lt;SmoothChat&gt;<br/>styled component (CSS-variable themed)"]
   P --> C --> W
@@ -19,20 +21,22 @@ flowchart TD
 
 | You want…                                              | Import                                       |
 | ------------------------------------------------------ | -------------------------------------------- |
-| Chat on a page, any framework, maybe no build step     | `@smooai/smooth-operator/widget` (web component) |
+| Chat on a page, any framework, maybe no build step     | `@smooai/chat-widget` (Aurora Glass web component) |
 | A React app, your own components, full design control  | `@smooai/smooth-operator/react` → `useConversation` |
 | A React app, batteries-included chat to theme          | `@smooai/smooth-operator/react` → `<SmoothChat>`    |
 | Another language, or a totally custom surface          | the [[Using the Polyglot Clients\|clients]] directly |
 
-One install gives you all of it:
+One install gives you the client + React layers:
 
 ```bash
 pnpm add @smooai/smooth-operator react react-dom
+# embeddable widget (no React needed): pnpm add @smooai/chat-widget
 ```
 
 `react` / `react-dom` are **optional** peer deps — only needed if you import the
-`./react` subpath. A client-only or widget-only consumer never pulls React into
-their bundle (subpath exports + `sideEffects` keep it tree-shaken out).
+`./react` subpath. A client-only consumer never pulls React into their bundle
+(subpath exports + `sideEffects` keep it tree-shaken out), and the embeddable
+`@smooai/chat-widget` is framework-agnostic (no React on the host page at all).
 
 ## Headless first — `useConversation`
 
@@ -64,25 +68,45 @@ import '@smooai/smooth-operator/react/styles.css'; // once, anywhere
 <SmoothChat url="wss://your-host/ws" agentId={agentId} agentName="Support" greeting="How can I help?" />;
 ```
 
-## No-React option — the web-component widget
+## No-React option — the embeddable widget (`@smooai/chat-widget`)
 
-If you're not on React (or want a no-build `<script>` embed), the same UI ships
-as a framework-agnostic custom element on the `./widget` subpath:
+If you're not on React (or want a no-build `<script>` embed), use the canonical
+public widget **`@smooai/chat-widget`** (the "Aurora Glass" design) — a
+self-contained `<smooth-agent-chat>` custom element that speaks the same protocol
+(it consumes `@smooai/smooth-operator`'s client internally). This is the single
+widget that smooth-operator's own [[Deploy Architecture|local-flavor server]]
+serves, the marketing demos embed, and you should reach for:
 
 ```ts
-import { mountChatWidget } from '@smooai/smooth-operator/widget';
+import { mountChatWidget } from '@smooai/chat-widget';
 mountChatWidget({ endpoint: 'wss://your-host/ws', agentId });
 ```
 
-Or drop the standalone IIFE on any page — no bundler, no framework:
+For a no-bundler `<script>` embed, the **deferred loader** is recommended (best
+Core Web Vitals — it does nothing expensive on the host page until the user shows
+intent, then injects the full widget):
 
 ```html
-<script src="https://unpkg.com/@smooai/smooth-operator/dist/widget/chat-widget.iife.js"></script>
+<script>
+    window.SmoothAgentChatConfig = { endpoint: 'wss://your-host/ws', agentId: '…' };
+</script>
+<script src="https://unpkg.com/@smooai/chat-widget/dist/chat-widget-loader.global.js" async></script>
+```
+
+Or drop the eager standalone IIFE directly:
+
+```html
+<script src="https://unpkg.com/@smooai/chat-widget/dist/chat-widget.global.js"></script>
 <smooth-agent-chat endpoint="wss://your-host/ws" agent-id="…"></smooth-agent-chat>
 ```
 
 The widget is themed with the same palette keys (`ChatWidgetTheme`) as the React
-components, so a brand ports between them unchanged.
+components, so a brand ports between them unchanged. Full embed docs live in the
+[`@smooai/chat-widget` README](https://github.com/SmooAI/chat-widget#readme).
+
+> The `@smooai/smooth-operator` SDK also still ships a `./widget` export (an
+> older in-tree copy of this component); prefer `@smooai/chat-widget` — it's the
+> canonical, separately-versioned public widget.
 
 ## Theming with CSS variables (not a build coupling)